MVR File Description

From GDTF Development
Jump to: navigation, search

MVR Version: 1.3

In the entertainment industry, the MVR file format allows programs to share data and geometry for a scene. A scene is a set of parametric objects such as fixtures, trusses, video screens, and other objects that are used in the entertainment industry.

All objects used have a persistent unique ID to track changes between the exchanging programs.

Typical workflow:

  1. Program A saves an MVR file containing a scene;
  2. Program B imports this file;
  3. Program B changes some parametric data in the scene;
  4. Program B saves an MVR containing the scene;
  5. Program A imports this file and applies the changes to the existing objects.

Vectorworks provide a portable library for convenience. This library helps to read and write MVR files. This allows easy implementation of the MVR file format.

Definition

The file is an uncompressed ZIP archive file containing a set of files. The files are stored in the root level within the archive without using nesting folders. There must be at least one root file and a set of other files. Their meaning is defined by the root file or other files that the root file defines. The file name of the ZIP archive can be chosen freely. The extension is:

*.mvr

Example of a typical MVR archive:

GeneralSceneDescription.xml
GeneralSceneDescription.checksum.txt
Custom@Fixture.gdtf
Custom@Fixture.checksum.txt
Custom@Fixture.gdtf
geo1.3ds
geo2.checksum.txt
Textr12.png
Textr12.checksum.txt

It is not allowed to create folders in this structure.

Root File Definition

The name of the file is:

GeneralSceneDescription.xml

The root file is an XML file with root node named: GeneralSceneDescription

Attribute Name Attribute Value Type Default Value when Optional Description
verMajor Integer <Not Optional> Denotes the major version of the format used when saving this file.
verMinor Integer <Not Optional> Denotes the minor version of the format used when saving this file.
Child Node Allowed Count Description
UserData 0 or 1 Specifies user data associated with this file.
Scene 1 Defines the scene described in this file.

Find a complete example of a file here .

Node Definition: UserData

This node contains a collection of user data nodes defined and used by provider applications if required.

Node name: UserData

Child Node Allowed Count Description
Data 0 or many Defines a block of user data.

Node Definition: Data

This node contains a collection of data specified by the provider application.

Node name: Data

Attribute Name Attribute Value Type Default Value when Optional Description
provider String <Not Optional> Specifies the name of the provider application that created this data.
ver String 1 Version information of the data as specified by the provider application.

Node Definition: Scene

This node contains information about the scene.

Node name: Scene

Child Node Allowed Count Description
AUXData 0 or 1 Defines auxiliary data for the scene.
Layers 1 A list of layers in the scene.

Node Definition: AUXData

This node contains auxiliary data for the scene node.

Node name: AUXData

Child Node Allowed Count Description
Symdef 0 or any Graphical representation that will be instanced in the scene.
Position 0 or any Defines a logical group of lighting devices.

Node Definition: Symdef

This node contains the graphics so the scene can refer to this, thus optimizing repetition of the geometry. The child objects are located within a local coordinate system.

Node name: Symdef

Attribute Name Attribute Value Type Default Value when Optional Description
uuid UUID <Not Optional> The unique identifier of the object.
name String Empty The name of the object

The child list contains a list of the following nodes:

Child Node Description
Geometry3D The geometry of this definition that will be instanced in the scene.
Symbol The symbol instance that will provide a geometry of this definition.

Node Definition: Position

This node defines a logical grouping of lighting devices and trusses.

Node name: Position

Attribute Name Attribute Value Type Default Value when Optional Description
uuid UUID <Not Optional> The unique identifier of the object.
name String Empty The name of the object

Node Definition: Layers

This node defines a list of layers inside the scene. The layer is a container of graphical objects defining a local coordinate system.

Node name: Layers

The child list contains a list of layer nodes:

Child Node Description
Layer A layer representation.

Node Definition: Layer

This node defines a layer. The layer is a spatial representation of a geometric container. The child objects are located inside a local coordinate system.

Node name: Layer

Attribute Name Attribute Value Type Default Value when Optional Description
uuid UUID <Not Optional> The unique identifier of the object.
name String Empty The name of the object
Child Node Allowed Count Description
Matrix 0 or 1 The transformation matrix that defines the location and orientation of this the layer inside its global coordinate space. This effectively defines local coordinate space for the objects inside. The Matrix of the Layer is only allowed to have an elevation, but no rotation.
ChildList 1 A list of graphic objects that are part of the layer.

Node Definition for Parametric Objects

Node Definition: SceneObject

This node defines a generic graphical object.

Node name: SceneObject

Attribute Name Attribute Value Type Default Value when Optional Description
uuid UUID <Not Optional> The unique identifier of the object.
name String Empty The name of the object
Child Node Allowed Count Description
Matrix 0 or 1 The location of the object inside the parent coordinate system.
Geometries 1 A list of geometrical representation objects that are part of the object.

Node Definition: GroupObject

This node defines logical group of objects. The child objects are located inside a local coordinate system.

Node name: GroupObject

Attribute Name Attribute Value Type Default Value when Optional Description
uuid UUID <Not Optional> The unique identifier of the object.
name String Empty The name of the object
Child Node Allowed Count Description
Matrix 0 or 1 The location of the object inside the parent coordinate system.
ChildList 1 A list of graphic objects that are part of the group.

Node Definition: FocusPoint

This node defines a focus point object.

Node name: FocusPoint

Attribute Name Attribute Value Type Default Value when Optional Description
uuid UUID <Not Optional> The unique identifier of the object.
name String Empty The name of the object
Child Node Allowed Count Description
Matrix 0 or 1 The location of the object inside the parent coordinate system.
Geometries 1 A list of geometrical representation objects that are part of the object.

Node Definition: Fixture

This node defines a light fixture object.

Node name: Fixture

Attribute Name Attribute Value Type Default Value when Optional Description
uuid UUID <Not Optional> The unique identifier of the object.
name String Empty The name of the object
Child Node Allowed Count Value Type Description
Matrix 0 or 1 The location of the object inside the parent coordinate system.
GDTFSpec 1 FileName The name of the file containing the GDTF information for this light fixture.
GDTFMode 1 String The name of the used DMX mode. This has to match the name of a DMXMode in the GDTF file.
Focus 0 or 1 UUID A focus point reference that this lighting fixture aims at if this reference exists.
Position 0 or 1 UUID A position reference that this lighting fixture belongs to if this reference exists.
FixtureId 1 String The Fixture ID of the lighting fixture. This is the short name of the fixture.
UnitNumber 1 Integer The unit number of the lighting fixture in a position.
Addresses 1 The container for DMX Addresses for this fixture.
CIEColor 0 or 1 CIE Color A color assigned to a fixture. If it is not defined, there is no color for the fixture.
FixtureTypeId 0 or 1 Integer The Fixture Type ID is a value that can be used as a short name of the Fixture Type. This does not have to be unique. The default value is 0.
CustomId 0 or 1 Integer The Custom ID is a value that can be used as a short name of the Fixture Instance. This does not have to be unique. The default value is 0.

Note: The fixture has no Geometries node as geometry is defined in a GDTF file.

An example of a node definition is shown below:

<Fixture name="Robe Robin MMX WashBeam" uuid="93 9F 36 0A 62 39 46 4E 9F B6 47 59 49 DB 04 BB">
    <Matrix>{0.158127,-0.987419,0.000000},{0.987419,0.158127,0.000000},{0.000000,0.000000,1.000000},{6020.939200,2838.588955,4978.134459},</Matrix>
    <GDTFSpec>Custom@Robe Robin MMX WashBeam</GDTFSpec>
    <GDTFMode>DMX Mode</GDTFMode>
    <Focus>4A B1 94 62 A6 E3 4C 3B B2 5A D8 09 9F 78 17 0C</Focus>
    <Position>77 BC DE 16 95 A6 47 25 9D 04 16 A0 BD 67 CD 1A</Position>
    <Addresses>
    	<Address break="0">45</Address>
    </Addresses>
    <FixtureID></FixtureID>
    <UnitNumber>0</UnitNumber>
    <FixtureTypeId>0</FixtureTypeId>
    <CustomId>0</CustomId>
    <Color>{2.533316,-5.175210,3.699302}</Color>
</Fixture>

Node Definition: Addresses

This node defines a group of DMX Addresses.

Node name: Addresses

The child list contains a list of the following nodes:

Child Node Description
Address One address of fixture.

Node Definition: Address

This node defines a DMX address.

Node name: Address

Attribute Name Attribute Value Type Default Value when Optional Description
break Integer 0 This is the break ident for this address. This value has to be unique for one fixture.
Value Type Default Value When Missing Description
Integer or String <Not Optional> This is the DMX address.
Integer Format:
Absolute DMX address;
String format: 
Universe - integer universe number, starting with 1; Address - address within universe from 1 to  512. Universe.Address

Node Definition: Truss

This node defines a truss object.

Node name: Truss

Attribute Name Attribute Value Type Default Value when Optional Description
uuid UUID <Not Optional> The unique identifier of the object.
name String Empty The name of the object
Child Node Allowed Count Value Type Description
Matrix 0 or 1 The location of the object inside the parent coordinate system.
Position 0 or 1 UUID A position reference that this truss belongs to if this reference exists.
Geometries 1 A list of geometrical representation objects that are a part of the object.

Node Definition: VideoScreen

This node defines a video screen object.

Node name: VideoScreen

Attribute Name Attribute Value Type Default Value when Optional Description
uuid UUID <Not Optional> The unique identifier of the object.
name String Empty The name of the object.
Child Node Allowed Count Description
Matrix 0 or 1 The location of the object inside the parent coordinate system.
Geometries 1 A list of geometrical representation objects that are a part of the object.

Other Node Definition

Node Definition: Geometries

This node defines a group of graphical objects.

Node name: Geometries

The child list contains a list of the following nodes:

Child Node Description
Geometry3D The geometry of this definition that will be instanced in the scene.
Symbol The symbol instance that will provide a geometry of this definition.


Node Definition: Symbol

This node specified a symbol instance (geometry insert) of the definition geometry defined by a Symdef node.

Node name: Symbol

Attribute Name Attribute Value Type Default Value when Optional Description
uuid UUID <Not Optional> The unique identifier of the object.
symdef UUID <Not Optional> The unique identifier of the Symdef node that will be the source of geometry.
Child Node Allowed Count Description
Matrix 0 or 1 The transformation matrix that defines the location and orientation of the geometry inside the local coordinate space of the container. Considered identity when missing.

Node Definition: Geometry3D

This node provides a geometry from an external file. The type of the file is determined by the extension.

Node name: Geometry3D

Attribute Name Attribute Value Type Default Value when Optional Description
file FileName <Not Optional> The file name, including extension, of the external file in the archive. If there is no extension, it will assume that the extension is 3ds.
Child Node Allowed Count Description
Matrix 0 or 1 The transformation matrix that defines the location and orientation of the geometry inside the local coordinate space of the container. Considered identity when missing.

Node Definition: Matrix

This node contains a definition of a transformation matrix.

Node name: Matrix

Value Type Default Value When Missing Description
{float,float,float,float}, {float,float,float,float}, {float,float,float,float} {1,0,0}, {0,1,0}, {0,0,1}, {0,0,0}, This node contains the array for a 4x3 transform matrix.
The order is
u1,u2,u3
v1,v2,v3
w1,w2,w3
o1,o2,o3

Node Definition: ChildList

This node defines a list of graphical objects.

Node name: ChildList

The child list contains a list of one of the following nodes:

Child Node Description
SceneObject A generic graphical object from the scene.
GroupObject A grouping object of other graphical objects inside local coordinate system.
FocusPoint A definition of a focus point.
Fixture A definition of a fixture.
Truss A definition of a truss.
VideoScreen A definition of a video screen.

Generic Value Types

Here is a list of the available types for node or attribute values:

Value Type Name Description
Integer A signed or unsigned integer value. Uses a dash ('-') as a prefix to denote negative numbers.
Float A floating point numeric value. Uses a decimal point ('.') as an integer-read delimiter.
String Any sequence of symbols. The following symbols will be used (with their meaning in brackets) according to the XML standard: &lt; (<), &amp; (&), &gt; (>), &quot; ("), and &apos; (')
UUID A unique identifier defined with hex values with dash delimiters. XX – 2 digits in hexadecimal notation. Example: "70 8B CD 59 9E 14 00 00 C1 52 36 54 9A 84 55 B0".
Vector A three Float values separated by ',' defining a 3D vector's X, Y, and Z components.
FileName A file name defined by letters A-Z , a-z plus numbers 0-9 and the symbol '_'. The extension is defined by a list of A-Z and a-z letters delimited from the name by '.'
CIE Color CIE color representation xyY 1931. The Node value is: {floatx, floaty, floatY}

Revision History

This section lists all the changes that are made to MVR.

Version 1.0

  • Created the file format specification.

Version 1.1

  • Added information about the name of the archive
  • Updated version attributes from the root node. We now have to integer values for this.
  • The version attribute from the UserData node is now a String so it can contain any data.
  • Make it clear that the SymDef can contain Symbol and Geometry3D nodes.
  • Geometry3D file attribute defines the behavior if there is no extension for a file.
  • Changed the matrix definition to match GDTF.
  • Make it clear that a layers parent coordinate system is the global coordinate space.
  • Give the option to have multiple addresses.
  • Add DMX node to fixture. This can be used to define the DMX Mode for the GDTF file.

Version 1.2

  • Fixed a copy error in the Addresses Node. An Addresses Node can only contain Address Nodes.
  • GDTFMode Node name now without white space.
  • Added CIE Color for Fixture Node.
  • Added Fixture Type ID
  • Added Custom ID

Version 1.3

  • Fixed spelling mistakes.