The VVIZ drone show file format is an interchange format for visualizing drone shows. VVIZ files are human-readable JSON text files that define the motion paths, colors and pyro payloads of drones in a show. The file format supports compression since drone data can be large and since drone motion and color animation compress well with negligible visual degradation.
Finale 3D imports drone show files as described in Importing drone shows for scripting pyro in Finale 3D to coordinate with the drones or for making simulation videos of hybrid shows combining drones and fireworks. Finale 3D‘s import functions facilitate a work flow in which the user may iteratively edit the drone show in external drone show editing software, export the updated VVIZ drone show file, and import it into Finale 3D to update a hybrid show being designed in Finale 3D. The import function will replace the previously imported drone data without affecting the pyro being scripted.
Finale 3D does not support editing drone motion paths or exporting VVIZ drone show files from Finale 3D. The import path is a one-way road, from external drone show software into Finale 3D.
File structure
The file structure is a JSON object with attribute-value pairs, as shown in the following example. The comments beginning with // are not part if the script format. Please do not attempt to include // comments in your imported script files.
"version": "1.0",
"defaultPositionRate": 2.0,
"defaultColorRate": 10.0,
"timeOffsetSecs": 120.0,
"performances": [
{
"id": 0,
"agentDescription": {
"homeX": -7.5,
"homeY": 0.0499995537,
"homeZ": -7.49999952,
"agentTraversal": [
{
"dx": 0.0,
"dy": 0.0,
"dz": 0.0
},
{
"dt": 1.5, // optional time delta from previous sample to this sample in seconds
"dx": 0.0,
"dy": 0.0,
"dz": 0.0
} // and more samples...
]
},
"payloadDescription": [
{ // optional but very common LED light animation payload
"id": 0,
"type": "Light",
"payloadActions": [
{
"r": 0,
"g": 0,
"b": 0
},
{
"r": 255,
"g": 255,
"b": 255,
"frames": 505 // optional time delta from previous sample to this sample in units of 1/defaultColorRate
} // and more samples...
]
},
{ // optional and less common pyro payload
"id": 1,
"type": "Pyro",
"eventTime": 37.7,
"vdl": "10s Gold Glittering Gerb",
"partNumber": ""
}
]
}
]
}The defaultPositionRate and defaultColorRate define the default sampling rate for position coordinates and RGB values for LED lights on the drones, in samples/second. The position data samples include dx, dy, and dz attributes that are position deltas in meters from the previous position to the sample’s position. The samples may or may not include a dt attribute, indicating the time delta from the previous sample to this sample in seconds. If dt is present, the time delta is dt seconds (unaffected by defaultPositionRate). If dt is missing, the default time delta is 1/defaultPositionRate seconds.
The color data samples with integer 8-bit RGB components may or may not include a frames attribute, indicating the time delta from the previous sample to this sample. If frames is present, the time delta is frames/defaultColorRate seconds (i.e., it is affected by defaultColorRate). If frames is missing, the implied time delta is 1/defaultColorRate seconds. The magnitude of the color sample values represents linear intensity. Values <10,10,10> are less intense than values <255, 255, 255>. Additional intensity scale attributes may be added to the VVIZ specification in the future.
Finale 3D will interpolate the data values from the previous sample to this sample over the time delta specified in this sample, or the default if not present. Thus the time delta looks backward, not forward. The time delta is not a “hold for” time.
The timeOffsetSecs field is an optional offset in seconds that applies to the entire imported file. When the user imports a VVIZ file into Finale 3D, the user is given the option to enter a time offset at which to import the file. The default time offset presented to the user is the value in the VVIZ file itself, in the timeOffsetSecs field.
The performances field is an array of drone “performances”, each performance including a drone motion path (the agentDescription) and a list of drone payloads (payloadDescription). The payloads are LED light animation or triggered pyro payloads. Each drone performance contains a unique integer id, which is nominally the name of the drone. Each payloadDescriptionalso contains a unique integer id, which is a programming convenience that has no meaning to the user.
The LED light animation is a sequence of RGB color samples. The pyro payloads are triggered pyro effects defined by a trigger time (the eventTime in seconds), and the VDL visual effect description (vdl), and an optional part number of the pyro effect (partNumber).
Coordinate system
All position coordinates are relative the global origin (defined by “Origin Man” in Finale 3D) , with the X-axis aiming to the right of the screen from viewer perspective, the Y-axis aiming up into the sky, and the Z-axis aiming into the screen. The coordinate system in the VVIZ file is similar to Finale 3D‘s coordinate system except that the Z-axis is inverted.
If you import a google map into Finale 3D, the origin is the latitude and longitude, and North is into the screen (+Z).
Table 1 – Example files and downloads
| Download link | Explanation |
| test-AGT.vviz | Example Verge Aero drone show with animated RGB lights |
| test-pyro.vviz | Example Verge Aero drone show with pyro payloads |