TDMvr

A TouchDesigner tool that imports MVR (My Virtual Rig) files and rebuilds the described rig as a TouchDesigner network: one Point POP and one fixture Base COMP per fixture type and DMX mode, with per-fixture positions, DMX addressing attributes, and a DMX Out POP already wired up.

MVR files are ZIP archives produced by lighting design and previz software (Vectorworks, grandMA, Depence, …). They contain a GeneralSceneDescription.xml scene graph (layers, fixtures, groups, trusses), the GDTF fixture definitions embedded per fixture type, and optional geometry files. TDMvr reads the scene graph with pymvr, extracts the embedded GDTF files, and delegates fixture building to TDGdtf.

On import, TDMvr:

• extracts all embedded .gdtf files to gdtf/ in the project folder
• flattens all layers, groups, and trusses into a single rig table (table_rig) with one row per fixture — UUID, name, GDTF spec and mode, patch (universe/address/break), position, color, layer, and scene-graph references
• creates one Point POP per unique (GDTF spec, DMX mode) pair with one point per fixture instance, carrying the position and the DMX addressing point attributes used by TDGdtf:
  • DMXFixtureNet, DMXFixtureSubnet, DMXFixtureUniverse, DMXFixtureChannel
  • DMXFixtureNetAddress (when the MVR patch includes per-fixture network addresses)
• creates one Base COMP per fixture type+mode that externally loads the TDGdtf fixture component, points it at the extracted GDTF file, and parses it
• wires each fixture component into the contained DMX Out POP, so the imported rig can output DMX/sACN/Art-Net directly

Each imported fixture type appears as a block in the component's sequential Fixtures parameters, where it can be activated for output and its DMX mode switched. Flat Art-Net universes from the MVR patch are split into net/subnet/universe automatically.

Setup

Installation

Install the package into a Python virtual environment used by TouchDesigner (e.g. one managed by TD's Python Environment Manager). The package is not on a public index, so install straight from GitHub (or from a local clone with pip install <path>):

pip install git+https://github.com/TouchDesigner/TDMvr.git

This also installs the TDGdtf and pymvr dependencies.

The packaged component (tdmvr.tox) ships inside the package. To load it, create a Base COMP and set its External .tox parameter to the packaged file using an expression:

mod.TDMvr.toxPath('TDMvr')

Importing an MVR file

1. Set the Mvrfile parameter on the component to point at a .mvr file.
2. Press Load to import (or call LoadMVR(path) from Python).
3. Usually the included gdtf files are just stubs, so it's required to find full gdtf files for the fixtures, reference them and parse them via the "Parse All" parameter.
4. Activate fixture types for DMX output via the blocks of the sequential Fixtures parameters, and pick the DMX mode per type.

Fixtures whose GDTF could not be resolved (e.g. generic placeholders exported without an embedded GDTF) are left with an empty gdtf_path in the rig table and can be resolved manually.

---

Promoted API Reference

All promoted functions are accessed via op('yourComp').FunctionName(...).

Method	Description
LoadMVR(path)	Import an MVR file: clear any previous import, extract the embedded GDTF files, populate table_rig, table_mvr_info, and table_userdata, and build the Point POP + fixture Base COMP network.
Reset()	Remove all operators created by the import, reset the sequential Fixtures and DMX Out blocks, and clear all data tables.

Data tables

Table	Contents
table_rig	One row per fixture: uuid, name, gdtf_spec, gdtf_mode, gdtf_path, fixture_id, unit_number, layer, universe, address, dmx_break, position (tx/ty/tz), CIE xyY source color, and scene-graph UUIDs (focus, position, classing, multipatch).
table_mvr_info	Provider, provider version, MVR format version, and source path of the imported file.
table_userdata	Provider-specific UserData entries found in the MVR.

Each per-type fixture Base COMP additionally contains a table_fixtures DAT with the patch and metadata rows for its own instances.

---

Development

The Python package lives in src/TDMvr with a standard src layout:

src/TDMvr/
├── td/             # TouchDesigner-only (references project, tdu, op)
│   └── TDMvrExt.py #   COMP extension: MVR parsing and network builder
└── tdmvr.tox       # packaged component

Requires Python 3.11+, pymvr, and TDGdtf:

pip install -e .[dev]

Sample MVR files for testing are in MVRSampleFiles/ (not part of the repository).

Releasing

Releases are built by the tag-triggered GitHub workflow. To publish a new release:

1. Bump __version__ in src/TDMvr/__init__.py (pyproject.toml reads it dynamically) and commit.
2. Tag the commit v<version> — the tag must match __version__ exactly, or the workflow fails.
3. Push the commit and the tag: git push origin master v<version>.

The workflow builds the sdist and wheel and creates a GitHub release with notes auto-generated from the commit messages since the previous tag.

---

AI Transparency

Claude (Anthropic) was used in the development of this project, primarily for documentation as well as Python optimizations and robustness.

License

Shared Use License, Derivative Inc. — see LICENSE.