Metadata-Version: 2.4
Name: armature-studio
Version: 0.3.0
Summary: Block the shot; the model shoots it — GLB-authored previz, control sequences and gates for video-diffusion generation.
Author-email: mcp-tool-shop <64996768+mcp-tool-shop@users.noreply.github.com>
License: MIT License
        
        Copyright (c) 2026 mcp-tool-shop
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://mcp-tool-shop-org.github.io/armature/
Project-URL: Repository, https://github.com/mcp-tool-shop-org/armature
Project-URL: Changelog, https://github.com/mcp-tool-shop-org/armature/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/mcp-tool-shop-org/armature/issues
Keywords: previz,blender,video-diffusion,controlnet,turnaround,glb,character,animation,comfyui,sprite
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics :: 3D Rendering
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# armature

**You block the shot. The model shoots it.**

A video model can produce motion, light and life that no renderer can. It cannot be told
*who is on screen and where they are standing*. armature supplies exactly that: a canonical
character mesh is staged and animated in headless Blender, and the render becomes a per-frame
**control sequence** the video model must obey — so AI-generated video can carry one
persistent main character whose position and pose are known every frame.

**armature is image-to-video with a GLB instead of an image.** Everything spatial is
authored, and the model paints life over it. The deliverable is footage — film, cutscenes,
character poses and movement, any shot at all. A game is one consumer of that footage, never
the boundary of the tool.

## Install

```bash
pip install armature-studio
```

```bash
armature check
```

## What this package is

The installable package is `armature_core` — the measured pieces of the pipeline, every one
of which imports under a plain CPython:

- **Gates that raise.** `gates`, `route_gates`, `rig_gates`, `donor_gate` — predicates that
  refuse a bad step *inside* the tool performing it, rather than warning beside it.
- **Framing and turnaround.** `framing`, `turnaround`, `startframe` — perspective and
  orthographic camera solves, shared-scale shot-sets, silhouette extent, and the
  frame-clearance checks that refuse a cropped subject.
- **Control channels.** `channels`, `openpose`, `aapose`, `landmarks`, `lift_solve` —
  channel maths and pose conventions for driving a video model.
- **Rig and mesh.** `joints`, `binding`, `parts`, `posearc`, `walk`, `glb`.
- **Contracts and records.** `shotspec`, `subject`, `sitelist`, `assembly`, `clipstats`,
  `clipcompare`, `pngio`, `errors`.

```python
from armature_core import turnaround, framing

plan = turnaround.projection_plan(ortho=True, ortho_scale=1.1235359256161628)
```

## What this package is not

**The rendering scripts are not console entry points, deliberately.**
`render_turnaround.py`, `stage_render.py` and their siblings run inside **Blender's own
interpreter**:

```bash
blender -b -P tools/render_turnaround.py -- --glb subject.glb --out renders --ortho
```

A console script installed on your Python could not import `bpy` and would fail on its first
line, so shipping one would be a promise the package cannot keep. Those scripts live in the
repository, where the invocation that works is the one written down.

`armature_core.blender_scene` is the single module that imports `bpy`. It is packaged, and it
resolves only under Blender — `armature check` reports it as `needs-blender` rather than as a
defect.

## The discipline this comes from

armature is an experiment repository whose product is its record: a spec before the work, a
report after, a ruling last, and the Director's eye as the verdict of record. Metrics are
diagnostics and gate nothing on their own. Every generation records its model, payload, seed
and control hashes, because a recipe that does not reproduce its output is not a recipe. No
non-commercially-licensed model, weight or dependency enters the pipeline — anywhere,
including experiments.

- **Docs and handbook:** https://mcp-tool-shop-org.github.io/armature/
- **Repository and the full record:** https://github.com/mcp-tool-shop-org/armature

## Requirements

Python 3.10+ and numpy. Blender 5.x is required only for the rendering scripts in the
repository, not for this package.

## License

MIT.
