How the MVR generator treats GDTF files
Principles
- The reference is the specification — GDTF 1.2 (DIN SPEC 15800:2022) with its XSD and the MVR specification — not the behaviour of any one program.
- Repair only what is needed. A file without problems goes into the MVR byte-identical and gets no
Revision. - Additive. DMX data (offsets, breaks, number and order of channels,
Attributevalues, mode names), theFixtureTypeIDand thePositionof existing nodes are never changed. Exceptions: DEF-01 fillsPrimitiveType="Undefined"and zero dimensions of an existing model, DEF-02 retags containers asAxis(channel names{Geometry}_{Attribute}follow), DEF-21 redirectsDMXMode/@Geometry, DEF-22 turns a reference without a target into aGeometry. - Recorded in the file. A changed GDTF gets
<Revision Text="SanitizedBy MVR-Generator 2.5 (DEF-02, DEF-06)" ModifiedBy="MVR-Generator 2.5"/>, inserted where the XSD expects it (beforeFTPresets/Protocols). The report lists every repair. - Extensions are respected. A GDTF with a valid
.soh.jsonis never changed, so the extension stays valid and is packed next to it.
Rules R1–R6
| Rule | When | What the generator does | Programs |
|---|---|---|---|
| R1 | The GDTF is invalid by the specification or XSD, or cannot be read as intended | Repairs it: DEF-09, DEF-20, DEF-21, DEF-22; writes Revision in XSD order; fills Default where the XSD requires it | all |
| R2 | The GDTF is valid but lacks data every visualizer needs (model, light source, axes, ranges) | Adds an estimate derived from the structure of the file: DEF-01, 02, 03, 04, 06 | all |
| R3 | A valid GDTF that only BlenderDMX reads wrongly | Extra heuristics for BlenderDMX's GDTF reader; the Revision text adds ; profile blenderdmx | BlenderDMX only |
| R4 | A change that adds no information | Not done: no synthetic min/max/center ChannelSets, no generated thumbnails unless asked, DEF-11 only reported | all |
| R5 | The GDTF has a valid .soh.json | Audit only; the GDTF goes in byte-identical and the extension is packed | all |
| R6 | Roles, placement and size warnings of fixtures | Computed by the same rules for every program; only the GDTF bytes of the BlenderDMX variant differ | all |
Defect codes
| Code | Problem | Treatment |
|---|---|---|
| DEF-01 | no 3D model | primitive model from the GDTF PrimitiveType list, with dimensions, for the root and Yoke/Head only (R2) |
| DEF-02 | moving head without Axis | Pan/Tilt axes added (R2); galvo lasers are left alone (DEF-18) |
| DEF-03 | Beam missing | Beam added (R2): under the root of each light mode; power only from Properties/PowerConsumption, otherwise 100 W → 8,000 lm, never above 10,000 lm. Dimmer packs and LED decoders get a weak Glow beam without flux in every zone their Dimmer channels drive. Pixel bars and heads get a beam per pixel geometry that has none. |
| DEF-04 | Pan/Tilt without physical range | physical range added (R2); for galvo lasers the scan field (ScanAngle, otherwise ±30°/±20°). A single-value function that takes one DMX step next to a function of the same attribute with real travel (laser rest at DMX 0, e.g. Pan_1 0…0 beside Pan_2) is a rest position and is kept (since 9 Nov 2026) |
| DEF-05 | ChannelFunction without ChannelSets | only sets for the slots of an indexed wheel (WheelSlotIndex); nothing synthetic (R4) |
| DEF-06 | ChannelFunction without Default | value inside the function's own range: Dimmer and colour minimum, shutter open, Pan/Tilt/Zoom/Focus centre (R1/R2) |
| DEF-07 | missing thumbnail | only with option thumbnails (off by default, R4) |
| DEF-08 | empty DMX mode | reported; the mode cannot be chosen |
| DEF-09 | broken XML (NUL bytes, junk after the root element) | sanitized (R1) |
| DEF-10 | gobo slot without a media file | reported |
| DEF-11 | no ColorSpace / Emitters | reported only (R4) |
| DEF-12 | missing DataVersion | reported; the file is not used |
| DEF-13 | dummy stub GDTF | reported |
| DEF-14–16 | identifiers with spaces, virtual channels / Relations, footprint via GeometryReference | informative |
| DEF-17 | virtual Dimmer with Default 0 or without it, and no physical Dimmer (the fixture may look dark) | reported; option fix_virtual_dimmer sets it to full |
| DEF-18 | galvo laser: Pan/Tilt without axes | informative, intentionally not repaired |
| DEF-19 | no light channel (hazer, motor, media) | informative; no beam is invented |
| DEF-20 | mode without root geometry | DMXMode/@Geometry set when the root is unambiguous (R1) |
| DEF-21 | mode channels outside the root geometry | DMXMode/@Geometry redirected to a root that covers them (R1) |
| DEF-22 | geometry reference without target | turned into a plain Geometry (R1) |
Target programs
The job field visualizer (step “Program” on the export page) selects the profile. Only BlenderDMX has its
own repair variant; GET /mvr-generate.php?action=visualizers reports it in the field
gdtf_repairs.
| Profile | Program | gdtf_repairs |
|---|---|---|
generic | Generic (maximum compatibility) | generic |
stageviz | 3D Stage Visualizer | generic |
grandma3, capture, depence, wysiwyg, vision, l8 | grandMA3, Capture, Depence, WYSIWYG, Vision, L8 | generic |
blenderdmx | BlenderDMX | blenderdmx |
Job options: options.repair_gdtf (default true; false = audit only),
options.thumbnails (default false), options.fix_virtual_dimmer (default
false). Each GDTF in the report has audit[].soh_extension and, for the BlenderDMX variant,
audit[].gdtf_variant.
In numbers
Library scan of 26 October 2026, profile generic:
| Files | Count | Changed by 2.4 | Changed by 2.5 |
|---|---|---|---|
| GDTF from manufacturers and the community | 10,890 | 6,257 | 2,382 |
| SOH library | 170 | 41 | 41 |
SOH with .soh.json | 4 | 0 | 0 |
The drop comes from rule R4 alone (no synthetic ChannelSets, no generated thumbnails). Validated against the GDTF XSD, the 2.5 output has no error that the 2.4 output did not have.
Known limits
- A file that mixes dimmer-only modes and RGBW modes on the same zones keeps those zones without a light source.
- Any repair changes
description.xml. A.soh.jsonwritten for the original file then no longer applies, which is why rule R5 exists.