Metadata-Version: 2.4
Name: blendertk
Version: 0.26.1
Summary: Python toolkit for Blender mirroring mayatk's API: modeling, UV, materials, animation, rigging and export utilities.
Author-email: Ryan Simpson <m3trik@outlook.com>
License: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/m3trik/blendertk
Project-URL: Repository, https://github.com/m3trik/blendertk
Project-URL: Changelog, https://github.com/m3trik/blendertk/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/m3trik/blendertk/issues
Keywords: m3trik,blender,blender-python,bpy,rigging,technical-art,dcc
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Intended Audience :: Developers
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: COPYING
License-File: COPYING.EXCEPTION
Requires-Dist: pythontk>=0.25.1
Requires-Dist: uitk>=1.11.4
Dynamic: license-file

[![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0.en.html)
[![PyPI](https://img.shields.io/pypi/v/blendertk.svg)](https://pypi.org/project/blendertk/)
[![Blender](https://img.shields.io/badge/Blender-4.x+-orange.svg)](https://www.blender.org/)
[![Tests](https://img.shields.io/badge/Tests-8001%20passed-brightgreen.svg)](../tests/)
![Platform](https://img.shields.io/badge/Platform-Windows%2C%20Linux-lightgrey.svg)

# blendertk

<!-- short_description_start -->
*Blender 4.x+ tech-art toolkit mirroring [mayatk](https://github.com/m3trik/mayatk)'s public API (`btk.X` ↔ `mtk.X`) — modeling, animation, materials, rigging, and scene-pipeline automation over native `bpy`/`bmesh`, plus one-click bridges into Marmoset, Substance Painter, RizomUV, Maya, Unity, and the browser. The tool panels over it are [tentacle](https://github.com/m3trik/tentacle)'s.*
<!-- short_description_end -->

blendertk is the Blender layer of the `pythontk → uitk → {mayatk, blendertk} → tentacle` ecosystem. It mirrors mayatk at the **name + behavior** level — and by signature where a shared panel calls the operation, never by line count — so the shared [tentacle](https://github.com/m3trik/tentacle) panels stay branch-free across DCCs. Where Blender ships the capability natively, blendertk stays a thin adapter over `bpy`/`bmesh` operators; where it doesn't, the DCC-agnostic core lives upstream in [pythontk](https://github.com/m3trik/pythontk) and both DCC layers adapt it.

<!-- diagram:ecosystem/blendertk -->
<!-- Generated by m3trik/scripts/generate_readme_diagrams.py from the workspace's declarations: change those and re-run it, never this block. -->
<p align="center">
<a href="https://github.com/m3trik/m3trik#readme"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/m3trik/m3trik/main/docs/diagrams/ecosystem-blendertk-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/m3trik/m3trik/main/docs/diagrams/ecosystem-blendertk-light.svg"><img alt="blendertk (highlighted) in the ecosystem: uitk requires pythontk; unitytk requires pythontk; mayatk requires uitk; blendertk requires uitk; tentacle requires uitk; extapps requires uitk; tentacle installs mayatk as its [maya] extra; tentacle installs blendertk as its [blender] extra; tentacle opens extapps by name (its [apps] extra) and never imports it; mayatk and blendertk share a mirrored API. tentacle and extapps are products, which nothing imports." src="https://raw.githubusercontent.com/m3trik/m3trik/main/docs/diagrams/ecosystem-blendertk-light.svg" width="781"></picture></a>
</p>
<!-- /diagram:ecosystem/blendertk -->

## Installation

```bash
pip install blendertk
```

**Requirements:** Blender 4.x+ (developed against 5.1 / Python 3.13) · [`pythontk`](https://pypi.org/project/pythontk/). `bpy` is provided by the Blender runtime — importing blendertk and resolving its surface never needs a running Blender (all `bpy` imports are deferred into call bodies).

## Packages

Same subpackage names, main-module filenames, and namespace classes as mayatk — the full correspondence map (including what is deliberately absent on each side, and why) is [`STRUCTURE.md`](STRUCTURE.md).

| Package | What it covers |
|---|---|
| `anim_utils` | Shots suite (the Blender host of the shared pythontk shots engine, and the manifest and sequencer hosts tentacle's panels call), smart bake, blendshape animation, playblast, key scaling/staggering |
| `audio_utils` | Sound-strip CRUD over the Video Sequence Editor (deliberately not a mirror of Maya's DG-node audio machinery) |
| `cam_utils` | Camera utilities |
| `core_utils` | `CoreUtils`, `AutoInstancer`, `Preview` (uitk's `PreviewController` bound to a Blender session), script-job manager over `bpy.app.handlers`, diagnostics |
| `display_utils` | Color ID, exploded view, Blender-only `OutlinerTint` |
| `edit_utils` | `EditUtils`, mirror, cut-on-axis, duplicate (linear/radial/grid), bevel, bridge, snap, naming, curtain rig, target weld |
| `env_utils` | `BlenderConnection`, `BlenderSceneFiles` (the `blender` operation host: a fresh background Blender per `python -m pythontk ops` call, one kept per MCP session), workspaces (`workspace.mel` shared with Maya), reference manager, hierarchy sync, FBX/USD, scene exporter, Maya + Unity bridges, WebXR preview, docked script console |
| `light_utils` | Lightmap baker + web export, HDR manager, lights-from-geometry |
| `mat_utils` | Game shader, material updater, texture path editor, shader templates, render opacity, image-to-plane, emissive groups, Marmoset + Substance live-RPC bridges |
| `node_utils` | `NodeUtils`, `DataNodes` ([shared scene data carriers](data_nodes.md)), the Channels engine |
| `nurbs_utils` | Curve helpers (relaxed mirror), `ImageTracer`, curve-to-tube |
| `render_utils` | Render engines, render settings + presets, render cameras, a rendered frame (mayatk's names; no IPR) |
| `rig_utils` | Constraints/drivers/armature primitives; tube / wheel / telescope / shadow / [articulated](https://github.com/m3trik/mayatk/blob/main/docs/articulated_rig.md) rigs |
| `ui_utils` | `BlenderUiHandler`, `BlenderMarkingMenuHost` (the `uitk.MarkingMenuHost` adapter, over `QtRuntime` and the 3D View `KeymapBridge`), native-menu wrapper, Qt dock container, calculator, style setter |
| `uv_utils` | UV utilities, [Texture Combine](https://github.com/m3trik/mayatk/blob/main/docs/texture_combine.md) (material atlas combine + UV / texture transfer), Rizom bridge |
| `xform_utils` | Transforms and matrix IO |

Classes — and, for the wildcard-scanned `*_utils` roots, their public methods — are exposed at the package root via the lazy-loading resolver:

```python
import blendertk as btk

btk.selected_objects()                      # bare form — CoreUtils.selected_objects, wildcard-exposed
btk.EditUtils.mirror(...)                   # class-qualified — mirrors mtk.EditUtils.mirror
btk.AutoInstancer(tolerance=0.001).run()    # same call in mayatk: mtk.AutoInstancer(...).run()
```

Full public surface, searched live from the installed source: `python -m pythontk ops run api.search "query=<words>"`.

## Highlights

- **Maya bridge, both directions** — `MayaBridge.send()` exports the selection and launches an interactive Maya on it; `save_as()` runs mayapy headlessly and returns a written `.ma`/`.mb`; `MayaSceneImport` pulls a Maya scene *in* via a blocking headless FBX round-trip, translating FBX-hostile shaders and rebuilding packed PBR maps from a manifest sidecar. Mirrored by mayatk's `BlenderBridge`, so each DCC reads and writes the other's native format off one shared export pipeline.
- **Lightmap pipeline** — `LightmapBaker` commits bake state (markers + manifest) that every exporter reads on its own: Unity via the FBX carrier, GLB via pythontk's lightmap applier, and `LightmapWebExport` wraps Blender's own glTF exporter for the [live WebXR preview](https://github.com/m3trik/pythontk/blob/main/docs/webxr_preview.md) — a clean no-op on unbaked scenes. mayatk's Blender bridge drives this baker headlessly for the Maya round trip.
- **Drive Blender from outside** — `BlenderConnection` mirrors mayatk's `MayaConnection`: fresh `--background` instances only, the backbone of the test suite. An artist's open session is never touched.
- **Hierarchy sync** — diff a scene against a reference `.blend` (or `.fbx`, staged to a temp `.blend`) linked as a library, then repair drift: stub missing objects, quarantine extras, fix fuzzy renames and reparents; `ObjectSwapper` pulls matched reference objects in fresh.
- **Shared workspaces** — one project folder serves Maya natively and Blender via blendertk: the `workspace.mel` codec and template store live in pythontk, and the editor part of tentacle's Workspaces panel mirrors Maya's Project Window.
- **Tool panels** — blendertk holds no UI: each tool's panel is one [tentacle](https://github.com/m3trik/tentacle) panel shared with Maya, calling this package's API, so a script gets everything the panel does.

## Parity — how the mirror stays honest

Parity is measured, not eyeballed: `compare_panel_surface.py` resolves every call tentacle's shared panels make through `self.tk` on both mayatk and blendertk ([tentacle/docs/PARITY_SURFACE.md](https://github.com/m3trik/tentacle/blob/main/docs/PARITY_SURFACE.md)); a call one host lacks must be hidden (`requires`) or guarded there, else it fails the gate. The coarse gap and port-this-next recipes live in [PARITY_AUDIT.md](https://github.com/m3trik/tentacle/blob/main/docs/PARITY_AUDIT.md) and [PARITY_PORTING_PLAN.md](https://github.com/m3trik/tentacle/blob/main/docs/PARITY_PORTING_PLAN.md).

## Session safety

Nothing in blendertk attaches to a running Blender. Tests and headless tooling always launch a **fresh** `blender --background --factory-startup` process; `BlenderConnection` does the same. See [AGENTS.md](../AGENTS.md) for the full rule.

## Guides

- **[Scene data nodes](data_nodes.md)** — the `data_internal` / `data_export` carriers and how their metadata rides into the FBX (Blender delta of [mayatk's owner doc](https://github.com/m3trik/mayatk/blob/main/docs/data_nodes.md))
- **[Shot Sequencer](https://github.com/m3trik/mayatk/blob/main/docs/shot_sequencer.md)** (mayatk, one guide for both hosts) — the per-shot animation timeline and its graph view; the panel's `?` help links here
- **[Emissive groups](https://github.com/m3trik/mayatk/blob/main/docs/emissive_groups.md)** (mayatk, cross-package reference) — regions whose glow plays on its own, as materials; blendertk's `EmissiveGroups` tags each copy on its node tree
- **[Live WebXR preview](https://github.com/m3trik/pythontk/blob/main/docs/webxr_preview.md)** (pythontk) — the shared DCC → glTF → headset pipeline behind `btk.WebXrPreview`

## Links

- **Full API:** `python -m pythontk ops run api.search "query=<words>"` (the installed source, searched)
- **Structure / parity map:** [`STRUCTURE.md`](STRUCTURE.md)
- **Test suite:** [`tests/README.md`](../tests/README.md) — suite layout, sentinel conventions, fresh-instance runner
- **Changelog:** [`CHANGELOG.md`](../CHANGELOG.md)
- **Contributor / AI-agent guide:** [`AGENTS.md`](../AGENTS.md)
- **PyPI:** https://pypi.org/project/blendertk/
- **Issues:** https://github.com/m3trik/blendertk/issues

## License

GPL-3.0-or-later — see [COPYING](https://github.com/m3trik/blendertk/blob/main/COPYING), plus an additional permission to combine it with mayatk, tentacle and Autodesk Maya ([COPYING.EXCEPTION](https://github.com/m3trik/blendertk/blob/main/COPYING.EXCEPTION)).
