# louisvottero/vtool architecture

> Architecture diagram of the GitHub repository louisvottero/vtool, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/louisvottero/vtool
- Repository: https://github.com/louisvottero/vtool

## Overview

1. **What this repo is**
   Vetala is a cross-DCC rigging and asset-creation toolkit. The same Python package is meant to run inside Maya, Unreal, or Houdini, and can also be launched from a standalone PySide/Qt environment. The repo is organized around host-specific adapters plus shared pipeline/UI code.

2. **Top-level package layout**
   The main runtime code lives under `python/vtool`. That package contains shared utilities, UI helpers, logging, USD helpers, and several large feature areas: `maya_lib`, `unreal_lib`, `houdini_lib`, `process_manager`, `script_manager`, `render_farm`, and `ramen`. This makes the package feel like a platform with several app-like modules rather than a single monolith.

3. **Primary user-facing entry points**
   The README points to two main launch paths: Maya users call `vtool.maya_lib.ui.tool_manager()`, while Unreal users call `vtool.ui.process_manager()`. That suggests the UI layer is a front door into different workflows, with Maya being the most mature host integration. There are also standalone `.pyw` launchers under `install/` for process and script manager tools.

4. **Host integration boundaries**
   The repo is explicitly split by runtime host:
   - `maya_lib` contains the richest implementation and likely the main production path.
   - `unreal_lib` and `houdini_lib` provide host-specific APIs, graph helpers, and UI hooks.
   - `python/vtool/usd.py` and host-specific `usd.py` modules indicate shared USD-related workflows adapted per host.
   This host split is the main architectural boundary: shared UI/workflow code above, app-specific scene manipulation below.

5. **Shared infrastructure layer**
   Common support code is centralized in `util.py`, `util_file.py`, `util_math.py`, `data.py`, `qt.py`, `qt_ui.py`, `logger.py`, and `logging.json`. These modules likely provide cross-platform helpers for filesystem work, math, logging, and Qt abstraction so the higher-level tools can stay host-agnostic where possible.

6. **Maya subsystem**
   `maya_lib` is the largest subsystem and appears to cover the full Maya-facing stack: animation, attributes, curves, deformations, shading, rigs, spaces, corrective workflows, picking, geometry, and expressions. It also has its own UI stack in `ui.py`, `ui_core.py`, and `ui_lib/` with feature-specific panels like animation, character, rig, corrective, model, and picker tools. This is the clearest sign that Maya is the core production environment.

7. **Ramen: rig logic / graph system**
   `python/vtool/ramen` looks like a platform-neutral rigging/evaluation layer. It includes `eval.py`, rig modules for Maya/Houdini/Unreal, and a UI library with node-based interfaces. The presence of `rigs_crossplatform.py` implies Ramen is meant to describe rig behavior once and adapt execution to different DCCs.

8. **Process management subsystem**
   `process_manager` is a separate workflow application, with modules for processes, batch execution, UI state/options/templates, settings, maintenance, and view/data/code components. This likely acts as the project/task orchestration layer: configuring jobs, managing templates, and packaging execution for different environments.

9. **Render-farm / batch execution**
   `render_farm` contains Deadline integration and cache-related jobs such as Alembic and Yeti. This suggests a pipeline boundary where local rigging/scene tools hand off longer-running cache or render work to a farm scheduler. Deadline is the main external service implied by the code layout.

10. **Script management**
   `script_manager` is a smaller but distinct toolset with a `script_view.py` and installer launcher. It appears to be a generic utility for browsing/running scripts, separate from the process manager and rigging workflows.

11. **Configuration, templates, and assets**
   The repo carries operational assets inside the package: icon resources, curve data (`maya_lib/curve_data/default_curves.data`), version metadata, stylesheet files, and install-time customization hooks such as `__custom__.py.example`. These files indicate the tools are configurable and likely rely on local studio setup for branding, paths, or environment overrides.

12. **Platform installation and bootstrapping**
   The `install/` directory holds integration glue rather than application logic: Maya `userSetup.py`, a Houdini `.pypanel`, and launcher scripts. That means deployment is host-driven: users wire the package into each DCC’s Python path and startup mechanism, then the package opens its own Qt-based interfaces.

13. **Documentation and generated docs**
   `docs/` is a full Sphinx documentation tree with custom manuals for UI tabs, pose/joint-orient tutorials, API docs, and build scripts. This indicates the repo is intended as a maintained tool platform with separate developer/user documentation, not just a code drop.

14. **Overall data flow**
   The main flow is: user launches a Qt UI inside a host DCC or standalone, the UI calls into shared tool logic, that logic routes into the appropriate host adapter (`maya_lib`, `unreal_lib`, `houdini_lib`), and then results are written back to the scene, exported data, or farm jobs. Cross-cutting concerns like logging, file utilities, templates, and Deadline integration support that flow across subsystems.

Main entry points: [`python/vtool/maya_lib/core.py`](https://github.com/louisvottero/vtool/blob/main/python/vtool/maya_lib/core.py) (Maya core), [`python/vtool/maya_lib/ui.py`](https://github.com/louisvottero/vtool/blob/main/python/vtool/maya_lib/ui.py) (Maya UI), [`python/vtool/unreal_lib/core.py`](https://github.com/louisvottero/vtool/blob/main/python/vtool/unreal_lib/core.py) (Unreal core), [`python/vtool/houdini_lib/core.py`](https://github.com/louisvottero/vtool/blob/main/python/vtool/houdini_lib/core.py) (Houdini core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_readme["README<br/>entry doc<br/>[README.md]"]
  node_process_launcher["Process launch<br/>Qt launcher"]
  node_script_launcher["Script launch<br/>Qt launcher"]
end

subgraph group_core["Shared core"]
  node_core_utils["Core utils<br/>shared helpers<br/>[util.py]"]
  node_core_ui["UI base<br/>Qt shell<br/>[ui.py]"]
  node_core_usd["USD core<br/>shared usd<br/>[usd.py]"]
end

subgraph group_maya["Maya stack"]
  node_maya_core["Maya core<br/>Maya api<br/>[core.py]"]
  node_maya_rigs["Maya rigs<br/>Maya rigging<br/>[rigs.py]"]
  node_maya_ui["Maya UI<br/>Maya interface<br/>[ui.py]"]
  node_maya_tools["Maya tools<br/>Maya feature set<br/>[anim.py]"]
end

subgraph group_unreal["Unreal stack"]
  node_unreal_core["Unreal core<br/>Unreal api<br/>[core.py]"]
  node_unreal_graph["Unreal graph<br/>[graph.py]"]
  node_unreal_ui["Unreal UI<br/>Unreal interface<br/>[ui.py]"]
end

subgraph group_houdini["Houdini stack"]
  node_houdini_core["Houdini core<br/>Houdini api<br/>[core.py]"]
  node_houdini_graph["Houdini graph<br/>[graph.py]"]
  node_houdini_ui["Houdini UI<br/>Houdini interface<br/>[ui.py]"]
end

subgraph group_ramen["Ramen"]
  node_ramen_eval["Ramen eval<br/>rig evaluation<br/>[eval.py]"]
  node_ramen_rigs["Ramen rigs<br/>cross-platform rigging"]
  node_ramen_ui["Ramen UI<br/>node UI<br/>[ui_ramen.py]"]
end

subgraph group_process["Process manager"]
  node_process_ui["Process UI<br/>workflow app"]
  node_process_core["Process core<br/>job orchestration<br/>[process.py]"]
end

subgraph group_pipeline["Pipeline tools"]
  node_deadline_cache["Deadline cache<br/>farm jobs<br/>[deadline.py]"]
  node_script_view["Script view<br/>script browser<br/>[script_view.py]"]
end

subgraph group_docs["Docs and install"]
  node_maya_launcher["Maya launch<br/>startup hook<br/>[userSetup.py]"]
  node_houdini_launcher["Houdini panel<br/>startup hook<br/>[vetala.pypanel]"]
  node_docs_index["Docs index<br/>[index.rst]"]
end

node_readme -->|"launches"| node_maya_ui
node_readme -->|"launches"| node_process_ui
node_maya_launcher -->|"boots"| node_maya_ui
node_houdini_launcher -->|"boots"| node_houdini_ui
node_process_launcher -->|"opens"| node_process_ui
node_script_launcher -->|"opens"| node_script_view
node_core_ui -->|"supports"| node_maya_ui
node_core_ui -->|"supports"| node_process_ui
node_core_utils -->|"supports"| node_maya_core
node_core_utils -->|"supports"| node_unreal_core
node_core_utils -->|"supports"| node_houdini_core
node_core_usd -->|"adapts"| node_maya_core
node_core_usd -->|"adapts"| node_unreal_core
node_core_usd -->|"adapts"| node_houdini_core
node_maya_ui -->|"drives"| node_maya_core
node_maya_core -->|"uses"| node_maya_rigs
node_maya_core -->|"uses"| node_maya_tools
node_unreal_ui -->|"drives"| node_unreal_core
node_unreal_core -->|"uses"| node_unreal_graph
node_houdini_ui -->|"drives"| node_houdini_core
node_houdini_core -->|"uses"| node_houdini_graph
node_ramen_ui -->|"runs"| node_ramen_eval
node_ramen_eval -->|"evaluates"| node_ramen_rigs
node_ramen_rigs -->|"targets"| node_maya_core
node_ramen_rigs -->|"targets"| node_unreal_core
node_ramen_rigs -->|"targets"| node_houdini_core
node_process_ui -->|"orchestrates"| node_process_core
node_process_core -->|"submits"| node_deadline_cache
node_process_core -.->|"integrates"| node_script_view
node_deadline_cache -.->|"feeds"| node_process_core
node_docs_index -.->|"documents"| node_core_ui
node_docs_index -.->|"documents"| node_maya_ui

click node_readme "https://github.com/louisvottero/vtool/blob/main/README.md"
click node_maya_launcher "https://github.com/louisvottero/vtool/blob/main/install/maya/userSetup.py"
click node_houdini_launcher "https://github.com/louisvottero/vtool/blob/main/install/houdini/vetala.pypanel"
click node_process_launcher "https://github.com/louisvottero/vtool/blob/main/install/run_process_manager.pyw"
click node_script_launcher "https://github.com/louisvottero/vtool/blob/main/install/run_script_manager.pyw"
click node_core_utils "https://github.com/louisvottero/vtool/blob/main/python/vtool/util.py"
click node_core_ui "https://github.com/louisvottero/vtool/blob/main/python/vtool/ui.py"
click node_core_usd "https://github.com/louisvottero/vtool/blob/main/python/vtool/usd.py"
click node_maya_core "https://github.com/louisvottero/vtool/blob/main/python/vtool/maya_lib/core.py"
click node_maya_rigs "https://github.com/louisvottero/vtool/blob/main/python/vtool/maya_lib/rigs.py"
click node_maya_ui "https://github.com/louisvottero/vtool/blob/main/python/vtool/maya_lib/ui.py"
click node_maya_tools "https://github.com/louisvottero/vtool/blob/main/python/vtool/maya_lib/anim.py"
click node_unreal_core "https://github.com/louisvottero/vtool/blob/main/python/vtool/unreal_lib/core.py"
click node_unreal_graph "https://github.com/louisvottero/vtool/blob/main/python/vtool/unreal_lib/graph.py"
click node_unreal_ui "https://github.com/louisvottero/vtool/blob/main/python/vtool/unreal_lib/ui.py"
click node_houdini_core "https://github.com/louisvottero/vtool/blob/main/python/vtool/houdini_lib/core.py"
click node_houdini_graph "https://github.com/louisvottero/vtool/blob/main/python/vtool/houdini_lib/graph.py"
click node_houdini_ui "https://github.com/louisvottero/vtool/blob/main/python/vtool/houdini_lib/ui.py"
click node_ramen_eval "https://github.com/louisvottero/vtool/blob/main/python/vtool/ramen/eval.py"
click node_ramen_rigs "https://github.com/louisvottero/vtool/blob/main/python/vtool/ramen/rigs_crossplatform.py"
click node_ramen_ui "https://github.com/louisvottero/vtool/blob/main/python/vtool/ramen/ui_lib/ui_ramen.py"
click node_process_ui "https://github.com/louisvottero/vtool/blob/main/python/vtool/process_manager/ui_process_manager.py"
click node_process_core "https://github.com/louisvottero/vtool/blob/main/python/vtool/process_manager/process.py"
click node_deadline_cache "https://github.com/louisvottero/vtool/blob/main/python/vtool/render_farm/deadline.py"
click node_script_view "https://github.com/louisvottero/vtool/blob/main/python/vtool/script_manager/script_view.py"
click node_docs_index "https://github.com/louisvottero/vtool/blob/main/docs/index.rst"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_readme,node_process_launcher,node_script_launcher,node_process_ui,node_process_core toneBlue
class node_core_utils,node_core_ui,node_core_usd,node_deadline_cache,node_script_view toneAmber
class node_maya_core,node_maya_rigs,node_maya_ui,node_maya_tools,node_maya_launcher,node_houdini_launcher,node_docs_index toneMint
class node_unreal_core,node_unreal_graph,node_unreal_ui toneRose
class node_houdini_core,node_houdini_graph,node_houdini_ui toneIndigo
class node_ramen_eval,node_ramen_rigs,node_ramen_ui toneTeal
```

## Components

### Entry points

Launchers and primary user-facing entry hooks.

- [README](https://github.com/louisvottero/vtool/blob/main/README.md): entry doc · Top-level overview and launch guidance. · `README.md`
- [Process launch](https://github.com/louisvottero/vtool/blob/main/install/run_process_manager.pyw): Qt launcher · Standalone launcher for the process manager. · `install/run_process_manager.pyw`
- [Script launch](https://github.com/louisvottero/vtool/blob/main/install/run_script_manager.pyw): Qt launcher · Standalone launcher for the script manager. · `install/run_script_manager.pyw`

### Shared core

Host-agnostic utilities and UI infrastructure.

- [Core utils](https://github.com/louisvottero/vtool/blob/main/python/vtool/util.py): shared helpers · Filesystem, math, data, logging, and Qt abstractions. · `python/vtool/util.py`
- [UI base](https://github.com/louisvottero/vtool/blob/main/python/vtool/ui.py): Qt shell · Shared UI entry layer and Qt helpers. · `python/vtool/ui.py`
- [USD core](https://github.com/louisvottero/vtool/blob/main/python/vtool/usd.py): shared usd · Shared USD-facing helpers used across hosts. · `python/vtool/usd.py`

### Maya stack

Main production subsystem for Maya.

- [Maya core](https://github.com/louisvottero/vtool/blob/main/python/vtool/maya_lib/core.py): Maya api · Central Maya host adapter and scene-facing operations. · `python/vtool/maya_lib/core.py`
- [Maya rigs](https://github.com/louisvottero/vtool/blob/main/python/vtool/maya_lib/rigs.py): Maya rigging · Rig construction and rigging utilities for Maya. · `python/vtool/maya_lib/rigs.py`
- [Maya UI](https://github.com/louisvottero/vtool/blob/main/python/vtool/maya_lib/ui.py): Maya interface · Main Maya tool manager and UI shell. · `python/vtool/maya_lib/ui.py`
- [Maya tools](https://github.com/louisvottero/vtool/blob/main/python/vtool/maya_lib/anim.py): Maya feature set · Animation, deform, shading, picker, corrective, and related modules. · `python/vtool/maya_lib/anim.py`

### Unreal stack

Unreal-specific adapters and UI.

- [Unreal core](https://github.com/louisvottero/vtool/blob/main/python/vtool/unreal_lib/core.py): Unreal api · Unreal host integration and scene helpers. · `python/vtool/unreal_lib/core.py`
- [Unreal graph](https://github.com/louisvottero/vtool/blob/main/python/vtool/unreal_lib/graph.py): Unreal graph · Unreal graph and node-building helpers. · `python/vtool/unreal_lib/graph.py`
- [Unreal UI](https://github.com/louisvottero/vtool/blob/main/python/vtool/unreal_lib/ui.py): Unreal interface · UI hooks for Unreal workflows. · `python/vtool/unreal_lib/ui.py`

### Houdini stack

Houdini-specific adapters and UI.

- [Houdini core](https://github.com/louisvottero/vtool/blob/main/python/vtool/houdini_lib/core.py): Houdini api · Houdini host integration and scene helpers. · `python/vtool/houdini_lib/core.py`
- [Houdini graph](https://github.com/louisvottero/vtool/blob/main/python/vtool/houdini_lib/graph.py): Houdini graph · Houdini graph and node-building helpers. · `python/vtool/houdini_lib/graph.py`
- [Houdini UI](https://github.com/louisvottero/vtool/blob/main/python/vtool/houdini_lib/ui.py): Houdini interface · UI hooks for Houdini workflows. · `python/vtool/houdini_lib/ui.py`

### Ramen

Cross-platform rig logic and node UI.

- [Ramen eval](https://github.com/louisvottero/vtool/blob/main/python/vtool/ramen/eval.py): rig evaluation · Evaluation and execution layer for cross-platform rigs. · `python/vtool/ramen/eval.py`
- [Ramen rigs](https://github.com/louisvottero/vtool/blob/main/python/vtool/ramen/rigs_crossplatform.py): cross-platform rigging · Platform-neutral rig definitions and adapters. · `python/vtool/ramen/rigs_crossplatform.py`
- [Ramen UI](https://github.com/louisvottero/vtool/blob/main/python/vtool/ramen/ui_lib/ui_ramen.py): node UI · Node-based Ramen interface. · `python/vtool/ramen/ui_lib/ui_ramen.py`

### Process manager

Job, template, and workflow orchestration.

- [Process UI](https://github.com/louisvottero/vtool/blob/main/python/vtool/process_manager/ui_process_manager.py): workflow app · Main process manager interface and views. · `python/vtool/process_manager/ui_process_manager.py`
- [Process core](https://github.com/louisvottero/vtool/blob/main/python/vtool/process_manager/process.py): job orchestration · Process definitions, batch execution, settings, and templates. · `python/vtool/process_manager/process.py`

### Pipeline tools

Farm and script-oriented support tools.

- [Deadline cache](https://github.com/louisvottero/vtool/blob/main/python/vtool/render_farm/deadline.py): farm jobs · Farm submission helpers for cache and render tasks. · `python/vtool/render_farm/deadline.py`
- [Script view](https://github.com/louisvottero/vtool/blob/main/python/vtool/script_manager/script_view.py): script browser · Standalone script manager UI. · `python/vtool/script_manager/script_view.py`

### Docs and install

Documentation and host bootstrapping.

- [Maya launch](https://github.com/louisvottero/vtool/blob/main/install/maya/userSetup.py): startup hook · Maya startup integration for Vetala. · `install/maya/userSetup.py`
- [Houdini panel](https://github.com/louisvottero/vtool/blob/main/install/houdini/vetala.pypanel): startup hook · Houdini panel registration for Vetala. · `install/houdini/vetala.pypanel`
- [Docs index](https://github.com/louisvottero/vtool/blob/main/docs/index.rst): docs · Documentation entry and published manuals. · `docs/index.rst`

## Connections

- README → Maya UI: launches · Primary Maya entry point described in the repository overview.
- README → Process UI: launches · Primary standalone process manager entry point.
- Maya launch → Maya UI: boots · Registers the Maya package on startup and exposes the UI.
- Houdini panel → Houdini UI: boots · Registers the Houdini panel and connects it to the UI.
- Process launch → Process UI: opens · Standalone launcher for the process manager application.
- Script launch → Script view: opens · Standalone launcher for the script browser application.
- UI base → Maya UI: supports · Shared Qt/UI infrastructure used by host-specific tools.
- UI base → Process UI: supports · Shared Qt/UI infrastructure used by workflow apps.
- Core utils → Maya core: supports · Common utilities underpin host operations.
- Core utils → Unreal core: supports · Common utilities underpin host operations.
- Core utils → Houdini core: supports · Common utilities underpin host operations.
- USD core → Maya core: adapts · Shared USD workflows are specialized per host.
- USD core → Unreal core: adapts · Shared USD workflows are specialized per host.
- USD core → Houdini core: adapts · Shared USD workflows are specialized per host.
- Maya UI → Maya core: drives · Maya UI routes actions into scene operations.
- Maya core → Maya rigs: uses · Rig-building is a central Maya capability.
- Maya core → Maya tools: uses · Animation, deform, shade, picker, and corrective tools hang off the Maya core.
- Unreal UI → Unreal core: drives · Unreal UI routes actions into host operations.
- Unreal core → Unreal graph: uses · Graph helpers are part of the Unreal adapter layer.
- Houdini UI → Houdini core: drives · Houdini UI routes actions into host operations.
- Houdini core → Houdini graph: uses · Graph helpers are part of the Houdini adapter layer.
- Ramen UI → Ramen eval: runs · Node UI feeds into the Ramen execution layer.
- Ramen eval → Ramen rigs: evaluates · Evaluation executes platform-neutral rig descriptions.
- Ramen rigs → Maya core: targets · Ramen can materialize behavior in Maya.
- Ramen rigs → Unreal core: targets · Ramen can materialize behavior in Unreal.
- Ramen rigs → Houdini core: targets · Ramen can materialize behavior in Houdini.
- Process UI → Process core: orchestrates · UI configures and runs processes, batches, and templates.
- Process core → Deadline cache: submits · Process workflows can hand off long-running work to farm jobs.
- Process core → Script view: integrates · Script tooling sits adjacent to workflow management.
- Deadline cache → Process core: feeds · Farm execution is part of the broader process pipeline.
- Docs index → UI base: documents · Documentation covers the shared UI layer and tabs.
- Docs index → Maya UI: documents · Documentation includes Maya-facing UI and tutorials.