How Texelator Core Works¶

Edition: Core

Texelator Core is a Maya Python tool built around a small UI/orchestration layer and four workflow-focused logic modules.

flowchart LR
  UI[Main.py UI and state] --> S1[step1_logic]
  UI --> S2[step2_logic]
  UI --> S3[step3_logic]
  UI --> UV[step3_uv_logic]
  S1 --> C[compat.py]
  S2 --> C
  S3 --> C
  S3 --> Maya[Maya DAG and DG nodes]
  UV --> Maya

Project map¶

Area	Responsibility
`Texelator.py`	Public entry point; reloads and opens the tool.
`Main.py`	Builds the UI, owns workflow state, manages Revert and existing setup loading.
`logic/step1_logic.py`	Guide placement and mirror-guide behavior.
`logic/step2_logic.py`	Follicles, control curves, control colors, and Precision-driven movement.
`logic/step3_logic.py`	Projection texture workflow, material connection, layer management, and sequences.
`logic/step3_uv_logic.py`	UV texture workflow and UV reference connections.
`logic/compat.py`	Selects compatible Maya math-node names for the running Maya version.
`install.py` / `install.mel`	Creates or updates the Maya shelf button.

Runtime state in `Main.py`¶

Main.py is the coordinator. It owns the Maya UI and keeps the current setup in memory while the window is open.

State value	What it tracks	Why a contributor should care
`selected_mesh_transform` / `selected_mesh_shape`	The selected mesh transform and shape.	Every stage depends on these references.
`setup_group`	The `Texelator_<MeshName>` setup group.	Metadata, RIG, UTIL, and setup recovery attach here.
`locators_data`	Prefix-to-guide locator mapping.	Step 1 output and Step 2 input.
`parts_data`	Logical parts, including mirror settings and guide/original keys.	Keeps the Parts list distinct from individual L/R guide nodes.
`follicles_data`	Prefix-to-follicle/control information.	Step 2 output and Step 3 placement input.
`textures_data`	Per-main texture settings and runtime node references.	Used for Build Final, cleanup, and recovery.
`texture_order`	Main texture order.	Controls managed `layeredTexture` order.
`material_snapshots`	Material input state before Step 3.	Allows failed or reverted builds to restore prior material wiring.

When you add a user-facing setting, decide whether it belongs only in temporary UI state or must be saved with texelatorData so Edit Existing Setup can restore it.

Maya commands and node networks¶

The tool uses maya.cmds to create and connect Maya nodes. A Step 2 build uses follicles and control curves to keep a control associated with the mesh surface. Step 3 creates file/placement networks and connects managed layers to the mesh material.

What each stage creates¶

Step 1: guides and mirror graph¶

Step 1 creates locators. Mirrored parts use an original guide and generated guide, with L_ / R_ naming based on Original Side:. The mirror connection uses the selected mesh and utility nodes such as multiplyDivide plus the version-compatible additive math node. A reference follicle named PosRefFol is used by the guide-placement logic.

Do not replace mirror graph nodes with direct, one-time transforms: the generated guide must continue to react when the original guide moves.

Step 2: follicle and control graph¶

For every guide, step2_logic.py finds surface UV coordinates and creates a follicle transform/shape. The control hierarchy includes a position group, an invert group, a *_Slide_ctrl curve, and a hidden *_bind joint. The motion chain uses composeMatrix, multMatrix, decomposeMatrix, multiplyDivide, compatible scalar math nodes, and a clamp that restricts follicle U/V to the 0–1 range.

The slide control's Precision attribute is connected into the U/V movement drivers. Step 2 stores utility-node message connections on the follicle through the multi-message texelatorUtilityNodes attribute; cleanup uses this to remove the technical graph reliably.

Step 3: texture and material graph¶

Every main texture starts with a file node and place2dTexture node. Step 3 finds an assigned material or creates a Lambert material when needed, then puts managed color/alpha outputs into a layeredTexture arrangement.

Projection mode adds a place3dTexture and planar projection network. Its alpha path is also projected so image alpha stays aligned with projected color. UV mode instead builds a UV reference hierarchy and drives place2dTexture attributes from it. The UV reference includes TranslateU, TranslateV, ScaleU, ScaleV, and RotateFrame values; slide-control rotation and scale feed that reference graph.

Before Build Final, Core captures the material color input. On an unsuccessful build, it deletes tracked Step 3 nodes and restores that saved connection.

Placement modes¶

Projection? selects a planar projection driven by place3dTexture. When it is off, the UV workflow uses mesh UVs, place2dTexture, and UV reference objects. Keep these paths separate when changing placement behavior.

Scene metadata and recovery¶

Each mesh setup is collected below Texelator_<MeshName>. The setup stores an identifier, mesh reference, workflow stage, and serialized data. This is why Edit Existing Setup can scan the scene and resume an unfinished setup.

The setup attributes are isTexelatorSetup, texelatorSetupId, texelatorMesh, texelatorStage, and texelatorData. Treat these names as persistence contracts: changing or deleting them needs a migration plan for existing scenes.

Maya-version compatibility¶

compat.py uses legacy addDoubleLinear / multDoubleLinear nodes in Maya 2022–2025 and the renamed addDL / multDL nodes in Maya 2026. New utility node code should use the same compatibility approach when an affected node type is required.

Core design principle¶

Keep user-facing actions in Main.py and focused Maya-node operations in the appropriate logic module. This makes the three workflow stages easier to reason about, revert, and resume.