mayatk
Maya 2025+ tech-art toolkit built on maya.cmds + maya.api.OpenMaya (no PyMEL) — modeling, animation, materials, rigging, and scene-pipeline automation, plus tool panels and one-click bridges into Marmoset, Substance Painter, RizomUV, Blender, and Unity.
mayatk is the Maya layer of the pythontk → uitk → mayatk → tentacle ecosystem: a library of composable helpers first, with a fleet of uitk-based tool panels (Shot Sequencer, Channels, Scene Exporter, …) built on top of it.
Installation
pip install mayatk
Requirements: Maya 2025+ (Python 3.11+).
mayatk also ships mayapy-package-manager.bat — an interactive Windows menu for installing/updating/backing up packages in Maya's bundled Python interpreter.
Packages
| Package | What it covers |
|---|---|
anim_utils |
Animation curves, shots, blendshape animation, playblast, smart bake |
audio_utils |
Audio clips, ffmpeg-backed conversion, timeline-keyed events |
cam_utils |
Camera utilities and default-camera handling |
core_utils |
CoreUtils, Components, AutoInstancer, MASH bridge, diagnostics, preview |
display_utils |
Visibility & isolation, color ID, exploded view |
edit_utils |
Selection, naming, primitives, snap, bevel, bridge, mirror, duplicate (linear/radial/grid), mesh graph |
env_utils |
MayaConnection, workspace, namespace sandbox, references, hierarchy sync, FBX/USD, scene exporter, Blender + Unity bridges, WebXR preview |
light_utils |
Lightmap baker, HDR manager, lights-from-geometry |
mat_utils |
GameShader, RenderEffects (per-object opacity / highlight channels; RenderOpacity is its one-release alias), ImageToPlane, MatUpdater, shader templates, emissive groups, Marmoset + Substance bridges |
node_utils |
NodeUtils, Attributes, Channels tool, shared scene data nodes |
nurbs_utils |
NURBS surfaces, ImageTracer, curve-to-tube |
render_utils |
Renderer switching and render-settings helpers (composed by hdr_manager) |
rig_utils |
Controls, skinning, tube / wheel / telescope / shadow rigs |
ui_utils |
MayaUiHandler, channel box, native menus, hotkey collision check, node icons |
uv_utils |
UV utilities, Rizom bridge |
xform_utils |
Transforms, matrices, pivot watcher |
Classes — and, for the wildcard-scanned *_utils roots, their public methods — are exposed at the package root via the lazy-loading resolver. Both bare and class-qualified forms work:
import mayatk as mtk
@mtk.undoable # bare form — wildcard-exposed
def operation():
mtk.freeze_transforms("pCube1")
# Class-qualified form — explicit, no risk of collision
mtk.NodeUtils.is_group("group1")
mtk.XformUtils.freeze_transforms("pCube1")
mtk.EnvUtils.SCENE_UNIT_VALUES
sel = mtk.Selection()
For the full public surface (auto-generated, refreshed each release) see API_REGISTRY.md.
Design notes: Shadow Rig — a source-responsive rig type (the Rig: combo's planned Morphing entry: options weighed, a recommendation, the maintainer's decisions).
Tour
A curated subset — the packages table is the map; these are the standouts.
Auto-instancing
Convert geometrically identical meshes to instances. Duplicates are matched by geometry signature, so rotated and scaled copies are found regardless of transform or name:
import mayatk as mtk
mtk.AutoInstancer(tolerance=0.001, require_same_material=True).run()
Drive Maya from outside
MayaConnection launches and remote-controls Maya from any Python process — the backbone of mayatk's own test suite:
from mayatk import MayaConnection
conn = MayaConnection.get_instance()
conn.connect() # launches a fresh Maya on a free port
conn.execute("import maya.cmds as cmds; cmds.polySphere()") # runs in that Maya, not yours
By default every connect() gets a new instance — an artist's open session is never touched (see Session safety below).
Smart bake
Analyzes what is actually driven — constraints, set-driven keys, expressions, IK — and bakes only those channels, onto an override layer, with a persisted manifest that makes the bake reversible even after save/reopen:
result = mtk.SmartBake(optimize_keys=True).execute()
mtk.SmartBake.restore() # undo the bake — drivers resume
Scene audit
mtk.SceneAnalyzer.run_audit(adaptive=True)
# → triangle/material budgets, top-offender Pareto, missing-texture impact,
# instancing stats (format_audit_html for an HTML report)
DCC bridges
One-click hand-offs that export the selection and drive the target app with a templated script: Marmoset Toolbag (including a bundled JSON-RPC plugin for live Toolbag scene ops), Substance 3D Painter, RizomUV, Blender, and Unity. Built on pythontk's HandoffBridge engine (RizomUV uses its own script-driven flow); each ships as a tool panel.
WebXrPreview is the same engine aimed at a browser instead of an application: mtk.WebXrPreview().push() converts the selection to glTF and publishes it to a loopback server, so a tab left open — including one open in a PC-tethered headset — swaps to the new version on its next poll. Baked lightmaps and the scene sidecar ride along automatically. See Live WebXR preview (pythontk owns the shared pipeline).
More highlights
Preview— hermetic operation preview: tools show live results, roll back on cancel, replay on commit.Components— component islands, border edges, edge paths, normal-angle edge selection.ExplodedView— force-based exploded view (vectorized repulsion), toggleable and reversible.NamespaceSandbox— import files into disposable namespaces for analysis or object swapping, with guaranteed cleanup.HierarchySync— diff a working scene against a reference and repair it: create stubs, quarantine extras, fix fuzzy renames and reparents.TubeRig/WheelRig/ShadowRig— rig builders: FK / spline-IK / anchor chains from a mesh centerline, expression-driven wheel rotation, fake contact shadows.ImageTracer— trace images or Blue Pencil strokes into curves and meshes.DevTools/WidgetInspector— grep Maya's MEL source and globals; walk, snapshot, and diff Maya's live Qt widget tree.StyleSetter— restyle Maya's scriptable viewport colors to match another DCC.
Bundled UITK Editors
MayaUiHandler ships with a one-line entry point for launching the
uitk editor windows from a Maya shelf
button or script:
from mayatk.ui_utils.maya_ui_handler import MayaUiHandler
MayaUiHandler.instance().editors.show("browser")
| Editor key | Description |
|---|---|
browser |
Searchable launcher for every UI registered with the switchboard — tags, filtering, hide lists, launch options, JSON-portable presets. |
style |
Theme + QSS variable editor for live restyling of the dark/light themes. |
shortcut |
Keyboard-shortcut editor for slots and commands; a focused global_shortcuts view also exists. Hosts can wire in Maya-aware collision checking via mtk.HotkeyCollisions.maya_collision_checker. |
MayaUiHandler.instance() is reentrant: if tentacle (or any other tool)
already created the handler, the call returns the existing singleton; otherwise
it bootstraps one with a fresh Switchboard. The editor window is cached per-handler — clicking the shelf button twice focuses the existing window rather than spawning a duplicate.
Session safety
MayaConnection.connect() defaults to launch=True, force_new_instance=True — every call launches a fresh Maya on an unused port. The user's open session is never touched. The test runner (test/run_tests.py) defaults the same way; only --reuse overrides, and you should not pass it. See CLAUDE.md for the full rule.
Guides
- Scene data nodes — the shared
data_internal/data_exporttwo-node model that every tool uses to stash scene-wide metadata and (optionally) embed it in an FBX. - Shot data in the FBX → Unity — exporting Shots as named Unity AnimationClips plus embedded shot metadata, and side-by-side coexistence with Audio events.
- Emissive groups → Unity — runtime-toggleable emissive regions: one all-on emissive map, per-group gating via vertex-color or mask-texture encoding; cross-package SSoT (pythontk region-mask engine, blendertk mirror, unitytk templates).
- Live WebXR preview (pythontk) — what
WebXrPreviewbuilds and what survives the trip: lightmap carriage through a slot-less format, theSceneStatesidecar sections that repair FBX translation loss, normal-map wiring, and the size/GPU-memory budget.
Format specs (co-located with the code that consumes them):
- Shot-manifest behaviors — behavior file format for the shot manifest.
- Shot-manifest mapping — mapping file format for the shot manifest.
- Scene-exporter template rules — export-template rule syntax.
Links
- Full API:
API_REGISTRY.md·API_CHANGES.md - Blender parity: blendertk mirrors this package's public API (
btk.X↔mtk.X); the subpackage/class correspondence map — including what is deliberately absent on each side — is blendertk/docs/STRUCTURE.md. Consult it before adding, moving, or renaming a public symbol here. - Test suite:
test/README.md— suite layout, base classes, runner invocations - Changelog:
CHANGELOG.md - Contributor / AI-agent guide:
CLAUDE.md - PyPI: https://pypi.org/project/mayatk/
- Issues: https://github.com/m3trik/mayatk/issues
License
MIT — see LICENSE.
1 maintainer
Release files for mayatk 0.18.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| mayatk-0.18.0-py3-none-any.whl | Python 3 | none | any | Details |
Release files / mayatk-0.18.0-py3-none-any.whl
| Download URL | mayatk-0.18.0-py3-none-any.whl |
|---|---|
| Size | 2.7 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bbf80f81a994d400ceb58bb6a73d57ed7b85c1db4fb6c35c9f34d091e0733fc2
|
|
BLAKE2b-256 checksum How to use checksums |
833629e4d25244e131b642c5f68d61119011adf126bb28a95c0ba8d915f61a20
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.16
|
