Software Documentation

Exporting a firing system scriptDocumentation

IntegrationIntermediate Last updated: August 1, 2019

12 Explo

To create and export a script for the Explo firing system, please follow these steps:

  1. Address the show (“Addressing > Address show”).
  2. Export the script (“File > Export > Export firing scripts“).

Step 2 creates the SHW script file.  The file format details are described in this section.

 

Figure 1 – Explo firing system

 

The Explo SHW script can be imported and exported from Finale 3D.  It is a CSV file with SHW filename extension.  The SHW file is both a direct representation of what the user sees when editing a script in the Explo software, and also a firing system format, so the format is more flexible than most firing-system-only formats, to enable the user to represent script rows in the most convenient and readable representation (see “What rows represent” in Table 2, below).

 

Table 1 – File format and encoding

File format Extension Text encoding Field delimiter End-of-line
Text .SHW Code Page 1252 Tab LF

The script contains rows of information including module, pin, and ignition-time and other information.  Multiple effects on the same module and pin at the same ignition time can be combined as a single row, or can be listed as separate rows.  The special characteristics of the script are shown in the following table:

 

Table 2 – Special characteristics

Special characteristics Description
Sort order of rows Rows sorted ascending by effect time.
What rows represent Each row contains firing information associated with a shot.  Although the rows are sorted by effect time, any single row may contain multiple effects ignited by the same module and pin, at the event time.  Coalescing by unique module-pin or module-pin-event-time is not required.  For example, a chain of five shells can be one row, or can be five rows.  A pair of shells shot together from the same position can be one row, or two.

Rows with module addresses corresponding to Explo Flamer units have a special meaning.  Since flame projector units do not require a pin number to identify an electrical terminal, the pin number in the row is available for another use.   For Explo Flamer units, the pin number represents a pre-defined flame program, or macro, that causes the flame to project at a specific angle or to animate across a sequence of angles.

Header and end-of-show line The file contains a single header row with the column names, in the same format as the CSV data rows themselves. After the data rows, the file contains a final row with all fields blank except the second, which is the last effect time in the show, and the fourth, which is the word “Ende”.
Multi-hit pins Non-pyro effects like flames and relays can be triggered multiple times on the same module-pin address. The standard pyro addressing functions in Finale 3D assign pins sequentially, so it may be easiest to address multi-hit pins in Finale 3D by editing the script table by hand and then locking the edited rows so the show can be re-addressed for pyro without affecting them.
Special characters The characters ‘ and “ and , and ; and \ and tab and newline will be filtered out of any text fields.
Minimum separation between cues None required; 1/100th second resolution supported.
Module specifications Supports 99 modules (numbered 1-99), each module with 30 or 70 pins (numbers beginning with 1). Also supports “Splitt” boxes that partition the range of pins in separate boxes that can be located at different positions (see below).  The full list of Explo module types in Finale 3D is: Explo 30K, Explo 20K, Explo 2 x 20K, Explo 3 x 20K, Explo 2 x 20K Offset 10, Explo 3 x 20K Offset 10, Explo Flame Unit.
“Splitt boxes” Explo firing systems support partitioning a device’s range of pins into 20-pin “splitt boxes.” Finale 3D supports splitt boxes using virtual slats, so you can take advantage of Finale 3D’s powerful addressing and racking features for reasoning with constraints relating to slats being at different physical locations (see Slats, virtual slats, and splitter boxes).Suppose you have one module with 70 pins that are distributed to three different launch positions using three splitt boxes with twenty pins each (10 pins being left over, unused). It would be important when addressing the show to apply the constraint that each splitt box is restricted to serving a single launch position, for otherwise you might have e-match wires running from position to position. But it would be too restrictive to constrain each module to serving a single launch position, because that would defeat the whole idea of using splitt boxes to distribute the module’s pins among multiple positions. Using virtual slats to represent splitt boxes allows you to arrange slats (splitt boxes) at various positions while having their module number and pin numbers still refer to the correct pin range of the parent module.

In the Finale 3D script, splitt boxes’ Rail Addresses are two-part addresses, such as 1-A meaning module 1, first splitt box; or 1-B meaning module 1, second splitt box. The pins of each splitt box are numbered 1-20 in the Finale 3D script, but are converted to the corresponding 20 pin sub-range of the parent module’s range of pins 1-70 when exported to the SHW file. If Finale 3D, if you use the “Explo 2 x 20K” module type, its rail and pin addresses will be represented in the script window as rail address “1-A” and pin addresses 1 through 20 for the first splitt box, then “1-B” and pin addresses 1 through 20 for the second splitt box, etc., but will be translated to module address “1”, pin addresses 1 through 40 in the SHW file.

The Finale 3D module types “Explo 2 x 20K Offset 10” and “Explo 3 x 20K Offset 10” are the same as “Explo 2 x 20K” and “Explo 3 x 20K” except the pin numbers in the exported SHW file begin at 11 instead of 1.

Flame units To design a show with Explo flame units using Finale 3D, please address the show with “Explo Flame Unit” module types if the show is entirely flame effects, or assign “Explo Flame Unit” as the module type of specific positions (by editing their position properties) if the show is partially flame effects and partially pyrotechnics. Any single position will be entirely flame or entirely pyrotechnic, depending on its module type.

From the effects window, add pyrotechnic effects to the pyrotechnic positions, and add flame effects to the flame positions. Explo X2 Flamer units support 66 pre-defined flame programs, or macros, that cause the flame to project at a specific angle or to animate across a sequence of angles. The Generic Effects collection in Finale 3D includes 66 pre-made effects corresponding to the Explo flame programs, GFX9001 to GFX9066.

These Explo effects all have realistic simulations and correct parameters representing the flame program numbers that get carried through into the script when you address the show and into the exported SHW file when you export. Thus, to design a show with Explo flame units, all you need to do is specify the module type is “Explo Flame Unit” and script using the pre-made Explo effects from Generic Effects; then address the show and export the SHW file. The show simulation will be realistic, and the exported SHW file will contain the flame program numbers.

In the SHW file, the pin number in the “Box/Nr” field represents the flame program number for flame units. The pin number field is available because the flame units do not have physical pins. When you address the show, Finale 3D assigns module and pin numbers for the pyrotechnic module types, and assigns module and program numbers for the flame unit module types. The program numbers, stored in the “Pin” column in Finale 3D and the Box/Nr field of the SHW file, come from the “Custom Part Field” of the effects. As a convenience to the user, the Generic Effects with part numbers GFX9001, GFX9002, GFX9003, etc., happen to correspond to flame programs 1, 2, 3, and so on; but the actual data field in those effect definitions that specifies the flame program number is the Custom Part Field, not the part number.  Please unhide the Custom Part Field column in the effects window to see.

After the header, each row in the script has a number of fields separated by tab.  The names of these fields and their descriptions are the following:

 

Table 3 – Specifications of script fields

Field name Description
Box/Nr (Exported and imported) The module (box) and pin (post) or Explo Flamer program number ( 1-66) of the shot, separated by slash.
Explozeit (Exported and imported) The break time of the shot, in the format MM:SS.DD, where MM is the number of minutes formatted as two or more digits; thus capable of representing shows longer than 99 minutes.
Abstand Zündzeit (Exported only) The delay to the next firing row, in the format MM:SS.DD, where MM is the number of minutes formatted as two or more digits; thus capable of representing shows longer than 99 minutes.
Effektbezeichnung (Exported and imported) The effect description. (string, 80 characters max)
Stz. (Exported and imported) The prefire time, in the format 0,0 (comma radix point).
Efz. (Exported and imported) The duration of the effect, in the format 0,00 (comma radix point).
Efg. (Exported and imported) The hazard field. (string, 80 characters max)
Stop (Exported only) Finale 3d leaves this field blank.
Stk. (Exported and imported) Quantity. Finale 3d writes the total number of devices represented by the firing row.
Beschreibung (Exported and imported) Comment field. Finale 3d writes a graphic indicating the angles of the shots, such as ///. (string, 80 characters max)
Position (Exported and imported) Position name. When importing a SHW file, if the Position field is blank then Finale 3D will construct a position name from the module number in the Box/Nr field, e.g., “Box-11”. (string, 80 characters max)
Steighöhe (Exported only) Finale 3d leaves this field blank.
Größe (Exported and imported) Size. Finale 3d writes the part’s Size into this field, including its units, e.g., 2.5″ or 30mm.
Etk. (Exported only) Number of labels to print. Finale 3d writes the total number of devices, same as “Stk.” field.
Effekttop (Exported only) Finale 3d leaves this field blank.
Gruppe (Exported only) Finale 3d writes the value in the Track field if it is a valid value. (integer, 0-999)
Bereich (Exported only) Finale 3d leaves this field blank.
Winkel (Exported and imported) Angle. Finale 3d writes the shot angle, formatted as an integer, followed by the degrees character, i.e., 0° (character 0xB0 in Code Page 1252 encoding). If the script row represents multiple shots, the angle is that of the first.
Pos. (Exported only) Finale 3d leaves this field blank. Use of this field is deprecated by Explo, though in practice it is sometimes used for the launch position notwithstanding the guidance from Explo (understandably, given the name).
(blank) (Exported and imported) Artikel Ref. Finale 3d writes the Part Number. (string, 80 characters max)

 

Importing SHW files

You can import a SHW file into Finale 3D from the “File > Open…” menu item, simply by selecting the SHW file to import.  Finale 3D will construct a show from the fields in the SHW file indicated in Table 3.   SHW files do not contain 3D coordinates of the positions, so Finale 3D lays out the positions in the 3D world in a reasonable default pattern that takes into account the size of effects at each position.  Finale 3D constructs visual simulations for the effects directly from the effect descriptions themselves, also taking into consideration the size and duration fields if provided.

For importing shows that include Explo Flamer effects on their own or in combination with pyrotechnic effects, Finale 3D processes the imported data from the SHW file to expand the rows with flame effects into script rows in Finale 3D that have the correct visual simulations for the flames.   Based on the Box/Nr field, Finale 3D can infer the Flamer program number (1-66) and can construct a matching simulation for the flame animation.  But first, Finale 3D first must determine what rows in the show are flames, and what rows are pyrotechnic effects.  Finale 3D follows this logic to make a good guess:

Since the SHW file does not contain any reliable explicit indication of what rows are flames versus what rows are pyrotechnics (the descriptions sometimes include the word “flame” for flames but often they do not), Finale 3D examines the full show and attempts to determine what modules (boxes) are flames based on their pin outputs.  If the module has at least two rows with the same pin number at different times, then the pin is not a pyrotechnic effect because it couldn’t ignite an e-match twice.   If the pin is not a pyrotechnic effect, it is probably a Flamer program number (1-66).  If the pin is a Flamer program number, then the module must actually be a flame unit.  Therefore all the pins on that firing module should be interpreted as Flamer program numbers.

Having determined what rows are flames, Finale 3D takes takes the following steps to process the flame rows:

  1. Change the Module Type of the imported row to explo_flame.
  2. Change the Custom Part Field of the the imported row to the program number (1-66).
  3. Change the Description to the corresponding description of the program’s animation, looking the description up from a table of 66 values.
  4. Change the Part Number of the imported row to the corresponding effect in Finale 3D‘s Generic Effects collection.
  5. Erase the angle field, because the program subsumes the angle.
  6. Change the Devices field to zero, since flame effects themselves are not devices.
  7. Change the VDL field to the corresponding VDL animation description that matches the program number.

 

Examples

An example script is shown below.  Notice the last two rows are at the same event time but have different modules and therefore cannot be combined into a single row.

Exported from Finale3D	
test_explo.mp3
Box/Nr	Explozeit	Abstand Zündzeit	Effektbezeichnung	Stz.	Efz.	Efg.	Stop	Stk.	Beschreibung	Position	Steighöhe	Größe	Etk.	Effekttop	Gruppe	Bereich	Winkel	Pos.	
1/1	00:05.00	00:00.10	Green Chrysanthemum	2,2	1,00	shell		1	|	Pos-01		2"	1						G2SH1003
2/1	00:05.10	00:00.10	Green Chrysanthemum	2,2	1,00	shell		1	|	Pos-02		2"	1						G2SH1003
3/1	00:05.20	00:00.10	Green Chrysanthemum	2,2	1,00	shell		1	|	Pos-03		2"	1						G2SH1003
4/1	00:05.30	00:00.10	Green Chrysanthemum	2,2	1,00	shell		1	|	Pos-04		2"	1						G2SH1003
5/1	00:05.40	00:00.10	Green Chrysanthemum	2,2	1,00	shell		1	|	Pos-05		2"	1						G2SH1003
6/1	00:05.50	00:00.10	Green Chrysanthemum	2,2	1,00	shell		1	|	Pos-06		2"	1						G2SH1003
7/1	00:05.60	00:00.10	Green Chrysanthemum	2,2	1,00	shell		1	|	Pos-07		2"	1						G2SH1003
8/1	00:05.70	00:00.10	Green Chrysanthemum	2,2	1,00	shell		1	|	Pos-08		2"	1						G2SH1003
8/2	00:05.80	00:00.00	Green Chrysanthemum	2,2	1,00	shell		1	|	Pos-08		2"	1						G2SH1003
9/1	00:05.80	00:00.00	Green Chrysanthemum	2,2	1,00	shell		1	|	Pos-09		2"	1						G2SH1003
	00:05.80		Ende																

Figure 1 – Example Explo SHW script

 

Table 4 – Example files

Download link Explanation
test_explo.shw Example exported file  (CSV)
test_explo.fin Example show file
demo_explo_flame.shw Example flames exported file
demo_explo_flame.fin Example flames show file
demo_explo_flame.mp4 Render example of flames