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,
        "homeH": 0.0, // optional heading in degrees
        "agentTraversal": [
          {
            "dx": 0.0,
            "dy": 0.0,
            "dz": 0.0,
            "dh": 0.0 // optional heading delta in degrees
          },
          {
            "dt": 1.5, // optional time delta from previous sample to this sample in seconds
            "dx": 0.0,
            "dy": 0.0,
            "dz": 0.0,
            "dh": 0.0 // optional heading delta in degrees
          } // 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 position data samples may include a dh heading delta in degrees.  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 homeX, homeY, homeZ, and homeH are the initial coordinates of the drone in the coordinate system defined below.

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 a various optional attributes.

Pyro payloads

A pyro payload must contain an eventTime and vdl attribute and a type attribute (“Pyro” or “Light”). Additionally, it may contain partNumber, notes, rail, pin, tilt, and pan attributes, as in this example:

        {
          "id": 1,
          "type": "Pyro",
          "eventTime": 90.0,
          "notes": "my notes",
          "rail": "0",
          "pin": "1",
          "tilt": 180,
          "pan": 0,
          "vdl": "30s Gold Glittering Gerb",
          "partNumber": ""
        }

The angles are relative to the drone.  A drone may contain multiple pyro payloads at various angles and trigger times.

Coordinate system

All VVIZ 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.

A VVIZ heading of zero degrees aims toward the audience in Finale 3D‘s coordinate system (+Z in Finale 3D, -Z in VVIZ).  A positive heading delta rotates around the Y-axis in a counter-clockwise direction, as viewed from above.

If you import a google map into Finale 3D, the origin is the latitude and longitude, and North is into the screen.  You can change the default orientation for the Front, Side, and Top camera buttons and for the “up” direction in site layout diagrams by right clicking the ground and choosing “Set default orientation”.

Compression and troubleshooting

Finale 3D‘s table cells, which hold all the imported drone data, are limited to 16k characters per cell.  As of June 2024, Finale 3D automatically compresses the Motion Data and Effect Data in table cells to make the drone information fit within the 16k character limit, eliminating any problems with the size of the data being imported.  If you are concerned that the compression is resulting in a visualization that is different from your original data, please see Importing drone shows for instructions to disable compression or modify compression limits.

Auxiliary attributes

The curly-brace JSON objects in the VVIZ file may contain auxiliary fields that are not defined in the VVIZ format, for debugging or for platform specific concerns.  The example files exported by the Verge software contain fields airframe, colorType, sourceType, and others which have no meaning in VVIZ.  Readers of VVIZ can ignore auxiliary terms.  Writers of VVIZ can add auxiliary terms at their discretion.

Table 1 – Example files and downloads