MVR-WorkZ · Help

1. Quick start

1. Open the viewer. Drag a .mvr file onto the dark canvas (or use the Load MVR button in the top-left).
2. The file persists across refreshes in your browser — you only have to load it once per machine.
3. Use WASD to fly, drag the mouse to look around, and click any fixture to see its info.
4. To see a fixture's beams, colour, and gobos: select it and click Test this fixture in the Properties panel, then drag the channel sliders (section 7). For real channels on a Vectorworks-stripped profile, replace it with a manufacturer GDTF first (sections 5 & 6) — pick Hybrid.

2. Navigation

3. Loading MVR files

MVR is just a ZIP with a GeneralSceneDescription.xml plus embedded 3DS / GLB model files and GDTF fixture profiles. The viewer parses it entirely in your browser — no upload happens.

Two ways to load

• Drag-and-drop a .mvr onto the 3D viewport.
• Click Load MVR in the header and pick a file.

Persistence

The loaded MVR is cached in IndexedDB on your device. Refresh the page and it auto-restores. Edits you make (position, rotation, patch fields, profile replacements) are persisted to that cache too — they survive a refresh but you'd need to use Save MVR to take the modified file elsewhere.

To start fresh, drop in a different file (it overwrites the cache).

4. Editing fixtures & objects

Click a fixture or truss/object in the viewer to select it. The right-side Properties panel populates.

Position & rotation

• Drag the on-object gizmo handles directly in 3D. The T key switches it to Move, R to Rotate. The Properties panel updates live.
• Or type values into Position (mm) and Rotation (°) — three X/Y/Z fields each. Position is in millimeters (MVR's native unit); rotation is Euler XYZ in degrees.

Patch fields (fixtures only)

Edit Fixture ID, Unit #, and DMX addresses directly in the Properties panel. The sidebar list updates immediately. These edits go into the MVR's XML on save.

Save

Click Save MVR in the header to download the modified file as edited.mvr. Open it in Vectorworks, Capture, MagicQ, etc. and your edits are there.

5. Fixture profiles (GDTF)

Each fixture in an MVR references a GDTF profile file embedded inside the archive. Vectorworks-emitted profiles (filenames like Custom@Light_Instr_*.gdtf) are often stripped — they have good geometry models but generic DMX mode definitions.

The Profiles tab in the sidebar lists every unique GDTF, with a count of fixtures and the mode(s) the MVR has them patched in.

Replacing a profile

For each row you can:

• Search GDTF Share — opens an inline search panel for the manufacturer's published profile. Click Use this on a result to apply it.
• Replace… button — file picker for a downloaded .gdtf.
• Drag-and-drop — drop a .gdtf file from your Finder/Explorer onto a row.

Merged / Hybrid / Full

After a replacement, the row shows a three-way toggle. It controls how much of the dropped GDTF is used versus the original Vectorworks-exported body from the MVR:

• Hybrid (default) — uses the new GDTF's full description (its geometry tree + DMX modes + colour/gobo wheels) and fills any missing 3D meshes from the VWX body. This is what you want for almost any real fixture: it's the only mode that brings across per-pixel cells (matrix washes, multi-cell strobes/blinders) and colour/gobo wheels.
• Merged — keeps the VWX body and splices in only the new GDTF's DMX modes. Lightweight, but it silently drops wheels and any multi-element geometry, so per-pixel and gobo/colour-wheel fixtures won't work. Use only for a simple single-beam fixture whose colour is plain RGB/RGBW/CMY.
• Full — uses everything from the dropped GDTF, including its own 3D models. Best when the manufacturer GDTF ships good geometry. If it has no models (common for console-tuned GDTFs), it falls back to the VWX body automatically.

The choice for each profile persists in the saved MVR and survives a page refresh, so the toggle is still there after a reload.

Mode dropdown

Each row also has a Mode dropdown showing every DMX mode the GDTF defines, with channel counts (e.g. Standard 21Ch · 21ch). If the MVR's mode name doesn't match any mode in the GDTF, a red "MVR: … (not in GDTF — pick one)" placeholder appears at the top of the list. Pick a mode whose channel count matches your console's patch (e.g. 32ch if MagicQ has them patched on 32-channel offsets).

6. GDTF Share

The viewer integrates with gdtf-share.com so you can search the entire public profile library and download manufacturer-published GDTFs in-place.

Signing in

1. Click the GDTF Share · sign in pill in the header.
2. Enter your gdtf-share.com email + password. You need your own account — sign up free at gdtf-share.com if you don't have one.
3. Click Sign in. On success the pill turns green and shows your email.

Searching & replacing

Once signed in, in the Profiles tab click Search GDTF Share on any row. An inline panel shows up to 8 matching fixtures from GDTF Share (Manufacturer · Fixture · Revision). Click Use this on the right one — it downloads + applies in one click.

Sign out

Click the pill (now green with your email) → Sign out. Clears the cookie.

7. Test mode (drive a fixture)

Test mode isolates a single fixture and turns the Properties panel into a small lighting console, so you can verify a profile actually works — its beam, colour mixing, colour/gobo wheels, gobo rotation, pan/tilt, zoom/iris — before trusting it in a show. There's no console or network involved; you drive the channels by hand.

Entering test mode

• From a loaded MVR: select a fixture (in the viewport or the Fixtures list), then click Test this fixture in the Properties panel. Everything else hides, the camera frames the fixture, and the channel console appears.
• A standalone GDTF: click Test GDTF in the header and pick a .gdtf file. It loads that one fixture into an empty scene at ~30 ft — handy for checking a profile you just downloaded.
• Click Exit test mode at the top of the panel to restore the full rig.

The console panel

• Beam / Room sliders (top) — Beam scales the visualised beam + projection brightness; Room scales the ambient/sun lights so you can darken the space to read the beams. Both persist.
• Mode dropdown + Address — the active DMX mode and start address for this fixture.
• Presets — one-click states (All open, Blackout, White full, Red/Green/Blue, Pan/Tilt center, Zoom wide/narrow, Iris open/closed…). They set every matching channel, so they degrade gracefully across fixture types.
• Channels — one slider per DMX channel (0–255, or 0–65535 for 16-bit). This is the real control; drag any channel to see its effect immediately.

What it renders

• Intensity / colour — Dimmer, additive RGB/RGBW emitters, subtractive CMY, and CTO/CTC all drive the beam colour. Multiple dimmers in a chain multiply (group × pixel).
• Colour wheels — the active slot tints both the in-air beam and the projected floor pool (needs a Hybrid replacement so the wheels load — see section 5).
• Gobos — a sharp gobo is projected onto the floor via a spotlight; gobo-rotation channels spin the pattern. Gobo channels usually have sub-ranges: a select range for static gobos, plus shake / wheel-spin ranges higher up — keep the channel in its select range to land on a gobo.
• Movement / beam shape — Pan/Tilt articulate the yoke/head, Zoom and Iris widen/narrow the cone. Multi-element fixtures (matrix washes, multi-cell strobes) render one cell per pixel, each with its own channels.

8. Lighting & beams

The Lighting panel near the bottom of the sidebar has a Room slider (0–200%) that scales the ambient + directional scene lights for the whole rig. Set it lower to see beams more vividly against a darker stage.

Beams themselves only render in Test mode (section 7) — the editor shows the rig with its bodies but no beams until you isolate a fixture and drive it. The matching Beam brightness slider lives in the test panel alongside Room.

Beam brightness

Each beam fades from full at the lens to ~0 at the tip (~20 m) along an inverse-square curve, then is scaled by the Beam slider and by the GDTF's LuminousFlux (lumens) — a 22,000-lumen wash visually outshines a 3,000-lumen profile at the same dimmer value. Zoom widens the cone; Iris narrows it and dims it.

Beam direction

Beams emit along each fixture's local -Z axis — i.e. the GDTF spec's +Z flipped, because most Vectorworks-exported MVRs don't bake the "hung from truss" 180° rotation into the fixture matrix. A fixture at its rigged rest pose points wherever it was hung; in test mode use the Tilt slider (or Tilt center preset) to aim it.

9. Visibility controls

Two layers of show/hide:

Per item

• Each row in the Fixtures and Objects tabs has an eye icon on the right edge. Click to hide the whole object in 3D (the row dims, the icon switches to ◯).
• The Properties panel has a Display group with a Visible checkbox that toggles the whole object (mirrors the eye icon).

Bulk

Above each list, Show all / Hide all applies to every item in that tab.

Visibility state is keyed by object UUID and persists in localStorage so it survives a refresh.

10. Saving & sharing

Click Save MVR in the header to download the modified file as edited.mvr. It includes:

• Updated positions and rotations of any objects you moved.
• Edited Fixture IDs, Unit #s, and DMX addresses.
• Replaced GDTF profiles (with their Merged / Hybrid / Full mode applied).

The saved file is a standard MVR — open it in Vectorworks, MagicQ, Capture, Depence, MA3D, etc.

Sharing the live URL

Anyone can open the viewer URL and load their own MVR. Their session is theirs alone — your IndexedDB cache and visibility state don't leak to them.

11. Troubleshooting

A fixture's channels do nothing in test mode

Vectorworks placeholder profiles (Custom@Light_Instr_*.gdtf) usually ship a generic Dimmer/Pan/Tilt/Zoom set with no real colour, gobo, or per-pixel channels — so there's little to drive. Replace the profile with the manufacturer's GDTF (sections 5 & 6) in Hybrid mode and the real channels appear. Also check the Mode dropdown matches the channel count you expect.

If even a real profile is mute, the MVR's mode name may not exist in the GDTF, leaving the channel map empty. Open DevTools (Cmd+Option+I) → Console and look for [fixture] …; dimmer=MISSING; attrs=[…] — the attrs list shows what the GDTF declares; pick a matching Mode.

Colour wheels, gobos, or per-pixel cells don't work

These come from the GDTF's geometry tree and <Wheels> section, which only the Hybrid (or Full) replacement mode brings across — plain Merged drops them. Open the Profiles tab and switch that profile's toggle to Hybrid. (New replacements already default to Hybrid.)

GDTF Share says it can't reach the proxy

GDTF Share search runs through a server-side proxy. On the hosted site it's always available; if you're running the viewer from localhost without that backend you'll see this message — use the hosted URL, or sign in again after a moment if the hosted proxy hiccupped.

"Init failed" overlay

A bug in the viewer code threw during startup. Open DevTools Console for the stack trace. As a recovery option, paste this into the console and hit Enter to nuke the IndexedDB cache + localStorage and reload:

indexedDB.deleteDatabase('mvr-viewer');
Object.keys(localStorage).filter(k=>k.startsWith('mvr-viewer-')).forEach(k=>localStorage.removeItem(k));
location.reload();

I want to start over

Same nuke-everything snippet above. Or just load a different MVR — that replaces the cache.