Software Documentation

Software Documentation

Importing ShowsDocumentation

Pro Last updated: June 28, 2024

3 Importing drone shows

The Pro version of Finale 3D has the capability of importing drone show scripts (file type “.vviz”) created externally in drone design software.  In Finale 3D you can combine the imported  drone shows along with fireworks in the 3D view for the purpose of designing hybrid shows or making videos.  The menu item to import a drone show is “File > Import > Import drone show”.   The function will import or re-import the drone show, merging it into the active show which may already contain pyro or drones.  Importing a drone show replaces any existing drones in the active show while leaving pyro unaffected.

 

 

Figure 1 – Example drone show imported into Finale 3D to combine with fireworks

 

In Finale 3D, drones are represented as positions.    In Figure 1, the pink positions in the shape of a heart in the sky are the drones.  If you import a drone show with 300 drones, the import function will add 300 positions to the show you are working on, with position names identifying the drones, like D001 and D002.  Drones may contain pyro payloads or colored LED light effects or both.  Thus, in addition to importing positions to represent the drones themselves, the import function also imports effects in the script window and the Per-show effects collection to represent the visual effects attached to the drones.

To avoid overwhelming the timeline and script window with so many events as to make scripting pyro difficult, the import function automatically groups the imported drone effects into a single row in the script window, and hides the trajectories and timeline bars of the drone effects in the 3D view and timeline.  You can see all the drone effects as individual rows or collapse them into a single row by clicking the blue gear icon in the upper right of the script window and toggling “Show groups as one row”.  If you want to unhide the drone effects’ timeline bars and trajectories, you can do the menu item “Script > Unhide all”.  To re-hide them, do “Edit > Select special > Select drone effects” and “Script > Hide special > Hide timeline bars and trajectories as group”.

 

Designing and exporting the drone show

When designing and exporting the drone show in drone show software or in Blender, you need to specify any pyro effects carried by the drones (if any), and you need to specify the compression of the file when you export it.  The Verge Aero software and DSS Drone Show Creator software shown in Figure 2a-c have dialogs for these purposes shown in Figure 3 and Figure 4a-b.

 

Figure 2a – Verge Aero drone design software

 

Figure 2bDSS Drone Show Creator design software

 

Figure 2cDSS Path Viewer drone show visualization software

 

Importing or adding pyro payloads for the drones

In addition to the LED light values specified as RGB colors, VVIZ files may contain pyro payloads for the drones.  A pyro payload is typically a gerb, but it could also be a comet shooting down or at an angle, or a comet “cake” that shoots comets out radially.  A drone can have multiple pyro payloads.  In Finale 3D, pyro payload effects are imported aiming down by default since that is the usual case, though the VVIZ file can specify pan andtilt angles.

A designer can specify the specific pyro effects and optionally firing system and shooting angle information in the drone show design software (Verge) or in drone show exporting tools or plugins (DSS/Blender).

Finale 3D supports two workflows for pyro payloads:

  1. The user specifies all pyro payload information in the drone related software outside of Finale 3D.
  2. The user specifies template pyro payload information such as firing system and shooting angle information without the ignition times or specific effects in the drone related software, and then fills in the ignition times and specific effects in the script rows in Finale 3D.

When the designer imports and drone show into Finale 3D, if the existing show contains pyro payloads, Finale 3D will present a dialog asking, “Preserve existing pyro on drones?”

If the designer is following the first workflow, then every time the designer imports an updated drone show into Finale 3D, the designer will replace any pyro payloads in the existing show in Finale 3D with the updated information.

If the designer is following the second workflow, then when the designer imports an updated drone show, the designer will choose to preserve the existing pyro since it has been modified in Finale 3D.  Selecting this option causes the import process not to delete the existing pyro script rows and effect definitions, and to ignore any pyro payloads in the file being imported.  If the drone IDs have changed in the updated file, then obviously the designer would need to update the script rows’ position names manually to match the new drone IDs.

 

 Figure 3 – Specifying pyro payloads on drones

 

The two pieces of information required for a pyro payload are the VDL, specifying the visual appearance, and the optional part number, identifying the stock keeping unit for purpose of inventory tracking or matching up the effect in the drone show design to pyro effect definitions in your inventory in Finale 3D (for details see Table 2, below).  The VDL is a text description of the visual appearance of the effect, like “10s Gold Gerb” for a 10 second gold gerb effect, or “25mm Red Comet” for a one inch red comet.  Finale 3D will create a visual simulation of the effect based on the VDL description, using whatever parameters you specify in the description.  To specify various durations of gerbs, just type “10s Gold Gerb” or “20s Gold Gerb”, for example.

 

Figure 4a – Choosing compression level in the Verge export dialog

 

 Figure 4b  – Choosing compression level in the DSS Path Viewer export dialog

 

 

File size and resolution

The file size for an exported drone show may be large, as it contains the motion paths and color changes for hundreds of drones.  The export dialog in the drone design software may give you the ability to specify the quality level of the exported data, which affects compression: the higher the quality, the larger the file.

 

Table 1 – Recommended sample rates

Data type Lower bound Upper bound
Position data 4 FPS 10 FPS
Color data 4 FPS 20 FPS

 

Since drones move smoothly, the compression algorithms can reduce the size of the file substantially with very little visual difference.   Thus you can likely reduce the file size to 20Mb or so while still appearing high quality.  At higher quality levels, your exported file may be more than 100Mb.

Table 1 shows the recommended sample rates for exported VVIZ files.  Although Finale 3D can import sample rates up to 100 FPS, higher frame rates require more memory and may exceed your machine’s resources.  In general, 10 FPS and 20 FPS are fine sample rates for position and color data for shows of less than 20 minute durations.  For longer shows, depending on your machines resources, you may need to export in lower frame rates.

 

Table 2 – Special fields of imported drone data

Field Name Value Explanation
Custom Part Field of effects imported into the Per-show effects collection drone The Custom Part Field helps the import function decide whether to overwrite or delete effect definitions in Per-show effects if you are re-importing a drone show.  Since importing a drone show is intended to replace any previously imported drone data in the active show, the import function deletes existing effects in the Per-show effects collection that have “drone” in the Custom Part Field.  Any new effect added by the import function will have “drone” in the Custom Part Field to ensure that re-importing will delete or overwrite it with newer content from the file being imported.

All LED effects and any pyro payload effects that do not have part numbers in the imported script file will be imported, and will thus have Custom Part Field of “drone”.  Pyro payload effects that do have part numbers will also be imported — unless their part numbers match part numbers of existing effects that do not have Custom Part Field of “drone”, in which case the effect definitions being imported are ignored in lieu of the existing effect definitions for the same part numbers.

If you are importing drone shows with LED effects exclusively, you don’t need to pay attention to the Custom Part Field.  However, if you are importing drone shows with pyro payload effects that correspond to effects in your inventory collections then you probably want to use the effect definitions from your inventory collections rather than the placeholder effect definitions constructed from the VDL in the imported script file.  In this case, the best workflow is: 1) In your drone show design, use part numbers for the pyro payload effects that match your inventory part numbers, 2) Import the drone show into Finale 3D, 3) Do “Effects > Update per-show effects…” to update the imported effect definitions to match your inventory, 4) If and when you re-import the drone show into Finale 3D, you will not need to repeat step (3) since the re-imported effects will not overwrite the updated effect definitions that do not have “drone” in the Custom Part Field.

Custom Script Field of events imported into the script window drone The Custom Script Field helps the import function decide whether to overwrite or delete events in the script window.  Since importing a drone show is intended to replace any previously imported drone data in the active show, the import function deletes existing events in the script that have “drone” in the Custom Script Field.  Any new event added by the import function will have “drone” in the Custom Script Field to ensure that re-importing will delete or overwrite it with newer content from the file being imported.
Type of positions imported into the positions window drone The Type of the imported positions representing drones is “drone” as opposed to “pyro” or “fixture” or “slave”.   Positions with Type of “drone” are drawn in the magenta color, to make them recognizable from pyro or fixture positions.  The Type value also supports the “Edit > Select special > Select drone effects” function and similar functions that recognize events as applying to drones based on the Type of position that houses them.  Lastly, the position Type also affects addressing.  Since pyro payloads of drones generally need firing system addresses (something has to ignite them!) but LED light effects on drones do not need firing system addresses, the addressing functions in Finale 3D do not assign firing system addresses to effects of Type “light” if they are on positions of Type “drone” (see Why is ‘Type’ so important? What depends on it?).
Duration of events in the script window Duration of LED light effects Imported pyro effects contain their duration in the VDL itself, as in “10s Gold Gerb”.  Imported drone LED lights turn on and off and change colors during the show continuously, so Finale 3D represents the LED light effects that change over time as long duration, animated effects.  Finale 3D divides the total LED effect duration into segments of maximum 60 seconds, and creates individual animated effects for each segment.

The LED effects’ color animation information is stored in the Effect Data field of the script window.  Since imported LED light effects are limited to 60s duration, a flight path of a drone lasting longer than 60s will require multiple events, back to back in the script.

Effect Data of events in the script window RGB color animation information Imported LED light effects for drones have a VDL description that includes the term ScriptRGB, as in the VDL, “ScriptRGB Point Light”.  That term indicates the color of the light effect, which may animate over time, is specified by information in the Effect Data field of the script event.
VDL of effects in the Per-show effects collection Pyro payload description like “10s Gold Gerb” or LED light description, “ScriptRGB Point Light” The VDL of imported LED light and pyro effects specifies the visual description of the effect.  All LED light effects use the same effect in the Per-show effects collection.  The effect’s color animation and duration are specified by fields in the script window (Effect Data and Duration).
Motion Data of imported positions in the positions window Position and optionally orientation animation information Imported drones are represented as positions whose motion paths are specified in the Motion Data field of the positions.

 

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 during the import process to make the data fit within the 16k character limit as a guarantee no matter what the sample rate is in the VVIZ file.  Notwithstanding this guarantee, it is a good idea to export VVIZ data with the sample rates described in Table 1 to avoid exceeding your machine’s resources.

Finale 3D uses a high quality variable sample rate compression algorithm tuned for drone shows to compress the data with a minimum of visual difference from the original high resolution data.  However, since the algorithm guarantees the data fits within a fixed data size, it cannot also  guarantee that the imported path and color animation match the original exactly.

Finale 3D also uses GZIP compression to encode the Motion Data as a blob in about 1/2 the number of characters.  When encoded, the Motion Data in the Positions window will appear as “{[hash 112912603] [blob #[“{PH4sAACmVZSa5lNQ…” instead of with human readable “pos” and “hpr2” attributes, as in “{[hash 112912603] [pos [250 0.0 0.0 0.0 10000…”.  If you want to read the “pos” and “hpr2” attributes, you can disable blob compression with the variable described in Table 3.  Blob compression does not change the limit of the number characters; it enables more samples to fit within the limit.

The combination of variable sample rate compression and GZIP blob compression enables about 48 minutes of drone flight to be encoded in the 16k character limit of the table cells before visual artifacts from the compression become significant.

If you are concerned that the compression is resulting in a visualization that is different from your original data, there are some variables in Per-Show Settings that you can use to investigate the effect of compression.  To use one of these compression variables, add the variable and its value to the Per-Show Settings table in Finale 3D prior to importing the drone show.

 

Table 3 – Variables in Per-Show Settings for troubleshooting compression

Variable Value Range Explanation
vviz_do_not_compress true or false If true, prevents variable sample rate compression. Finale 3D will import the file, but if the data cells exceed 16k characters, then the drone show will not be saved along with the show file when the show file is saved.
vviz_disable_blobs true or false If true, prevents the GZIP blob compression of Motion Data; making Motion Data in the Positions window human readable (like “{[pos [250 0.0 0.0 0.0 10000…” instead of “{[blob #[“{PH4sAACmVZSa5lNQ…”) but at the cost of fitting only about half as many samples within the character limit.
vviz_max_data_size 1000 – 100000 If you want to test the compression of the motion data to a threshold other than 16k characters, set this field to your desired limit. If your limit is greater than 16k, then the drone show will import but will not be saved along with the show file when the show file is saved.
vviz_max_rgb_samples 3 – 100000 Each RGB sample can take 15 characters to represent, depending on the size of the numbers. Thus the 16k character limit allows approximately 1092 samples. Finale 3D‘s default max RGB samples limit is 1088. You can change it with this variable. The drone lights are represented in Finale 3D as one-minute long effects with color animation provided by the Event Data. Thus unlike the motion samples the sample limit for RGB samples applies to at most one minute of data. The 1088 sample limit is 1088/60 = 18.13 FPS, which is obviously a fairly high resolution already.