Software Documentation

Software Documentation

Importing ShowsDocumentation

Intermediate Last updated: September 30, 2019

2 Importing chains

Importing chains is complex because people follow different conventions for the meaning of chain quantity.  To some, quantity 10 of “Chain of 10” means a total of 10 devices; to others it means a total of 10 chains of 10 devices, for 100 devices total.

Figure 1 – Does “Quantity = 5” mean 5 chains or 5 shells?

 

When importing a show, the dialog asks you if the chain quantity means number of chains or number of shells.  It’s really important that you answer that question correctly, or you could end up with 10 times as many chains as you want, or with boring chains of 1 shell each.  If your imported script format does not have a quantity column, then please select “Means number of chains”.  If it does have a quantity column, then select “Means number of chains” or “Means number of devices” depending on whether the quantities are the numbers of chains or the numbers of shells.

The import dialog isn’t the only factor.  An effect description or VDL may specify the number of devices, as in “Red Peony Chain of 10” or may just indicate the effect is a chain and leave the number of devices off, as in “Red Peony Chain”, relying on the “Devices” or “Quantity” column to fill in the number.

An imported show or effects list may or may not contain an optional “Devices” column or a “Quantity” column.  Depending on the presence of these columns, and the values in them, each row of the effects list or show will correspond to a certain number of devices inserted into the show (immediately for an imported show, or when clicking on an item from an imported effects list).

Based on these variations and based on your choice in the import dialog, the following rules determine the number of inserted devices for a row of the imported effects list or show:

 

Table 1 – Factors affecting imported chains, and the number shells represented.

Operation Quantity in VDL or Description column (X) Quantity in Devices or Quantity column (Y) Number of devices that will be inserted
Importing effects Missing Missing 10
Importing effects 1 or more Missing X
Importing effects Missing 1 or more Y
Importing effects 1 or more 1 or more Y
Importing show, number of devices option Missing Missing 1
Importing show, number of devices option 1 or more Missing 1
Importing show, number of devices option Missing 1 or more Y
Importing show, number of devices option 1 or more 1 or more Y
Importing show, number of chains option Missing Missing 10
Importing show, number of chains option 1 or more Missing X
Importing show, number of chains option Missing 1 or more 10 * Y
Importing show, number of chains option 1 or more 1 or more X * Y

When importing a chain into a show from a single row or inserting chains into a show, the prefire of the chain applies both to the chain itself and to all the devices in the chain. In other words, the chain’s prefire and the prefire of its devices are one and the same. When importing a chain from multiple rows that are grouped together with the reference number in the “Chain” column, or when combining effects that already exist into the show into a chain, the first device’s prefire will be the prefire of the chain, and the other devices in the chain may have different prefires if they are different part numbers.

When importing chains into a show, the effect definitions in the imported Per-show effects will have “Duration” equal to zero, and “Devices” equal to one, always. Neither of these fields is referenced by the chain rows of the script (see “Representation of chains in the script”). The same chain part number could be imported with different numbers of devices, which implies the duration and number of devices of the chain may not have a single unique definition. The values of these fields are cleared in order to guarantee consistent results.

When importing chains into the Effects window, the duration of the chains is determined by: the “Duration” column in the imported row if present, else the duration specification in the “VDL” column if present, else the duration specification in the “Description” column if present, else a default duration calculated from the number of devices in the chain, that number of devices being the value in the “Devices” column if present, else the specification in the “VDL” column if present, else the specification in the “Description” column if present, else 10. The calculation of the default duration is,

ChainDuration = ( NumberOfDevices - 1 ) * 0.05

The specification of the duration in the “VDL” or “Description” column is a quantity followed by the letter “s”, as in “8s Salute Chain Of 5”. The specification of the number of devices is either explicit, as in this “Chain Of 5” example, or implicit, based on the number of device descriptions are in the chain description, separated by plus signs (+), such as the chain of 3 devices described as, “Red Peony + Blue Peony + Green Peony Chain”.

Figure 2 – The “Used” column depends on “Devices” and the user setting: “Display chain…”

 

In the effects window, the “Used” column that shows the number of chains used depends on the “File > User settings > Display chain ‘Used’ quantity as per-shell” setting.  If you have this setting checked, then the number displayed in the “Used” column for chains is just the number of devices in the script of that part number.  However, if you have the setting un-checked, then the number displayed in the “Used” column for chains is the number of devices, divided by the “Devices” count in the effect window, unless the Devices count is blank or zero, which is treated the same as the value “1”.   The chain quantity in the “Description” field and the “VDL” field does not affect the Used quantity; only the Devices field does.  Please note that the Devices field gets filled in from the Description or VDL field in the imported script, but thereafter the Devices column is independent.  If you manually change the Description or VDL fields after importing the show, that will not affect the Devices column and will thus not affect the displayed Used column.

As you can conclude from the foregoing description, importing chains is complicated.  It is nearly impossible to edit chain simulations or specifications after importing them as part of a show, because when chains are inserted or imported, they are expanded to their constituent devices that are independent of the original chain definition with respect to multiple factors.  If you need to change chains after importing, the easiest solution is to delete them from the show and re-insert them manually.