Software Documentation

Software Documentation

Effects OverviewDocumentation

Hobbyist Last updated: August 28, 2022

14 Programmer documentation: Effect Data and Motion Data

Drones, saxons, wheels, and castiles all involve animated positions and orientations.   Drone lights also involve animated colors during the course of the light effect.  Finale 3D uses the Effect Data field in the script window, and the Motion Data in the position window, to hold the animation information.

Both fields have a similar format for storing the information.  The information usually gets filled in as a result of an operation like “Import drone show”, but the information is also readable and editable by users as a text field, which makes it possible for users to animate positions and colors for their own purposes.

 

Syntax of Motion Data and Effect Data fields

The syntax of both the Motion Data and Effect Data fields is a pair of curly braces defining an object with attribute-value pairs in square brackets within the curly braces.  The values for most attributes are lists of numbers that are also in square brackets, leading to a large number of brackets in the text string that must be carefully matched up without typos if you are entering data by hand.  An example that defines the motion path for effect on a 0.5m radius wheel rotating clockwise 10 full 360 degree cycles over 10000ms (10 seconds) is,

{[pos2 [0 .5 0 0]] [hpr [10000 0 0 -3600]]}

An example defining the animated motion path of a drone over 5 minutes is,

{[hash 1908853237] [pos [13000 0.0 7.9 0.0 19500 2.77 11.06 3.33 20500 3.42 12.1 4.59 21500 3.75 13.22 6.22 22000 3.61 13.76 7.17 22500 3.12 14.16 8.1 23000 2.39 14.3 8.74 24500 0.13 14.32 9.82 26000 -2.49 14.32 10.72 27000 -4.54 13.39 11.22 28000 -6.84 12.47 11.58 29500 -10.73 11.07 11.7 31000 -15.06 9.68 11.14 32000 -18.12 8.76 10.27 33000 -21.24 7.83 8.94 34000 -24.34 6.9 7.09 35000 -27.3 5.98 4.68 36000 -30.0 5.14 1.69 37000 -32.31 5.14 -1.88 37500 -33.27 5.14 -3.86 38000 -34.07 5.14 -5.97 38500 -34.69 5.14 -8.2 39000 -35.12 5.14 -10.52 39500 -35.34 5.14 -12.93 40000 -35.33 5.14 -15.4 40500 -35.07 5.14 -17.91 41000 -34.56 5.14 -20.44 41500 -33.77 5.14 -22.95 42000 -32.71 5.14 -25.42 42500 -31.38 5.14 -27.81 43000 -29.76 5.14 -30.08 43500 -27.87 5.14 -32.21 44000 -25.71 5.14 -34.14 44500 -23.31 5.14 -35.86 45000 -20.68 5.14 -37.3 45500 -17.84 5.14 -38.45 46000 -14.84 5.14 -39.27 46500 -11.71 5.14 -39.72 47000 -8.49 5.14 -39.78 47500 -5.24 5.14 -39.43 48000 -2.01 5.14 -38.66 48500 1.15 5.14 -37.46 49000 4.16 5.14 -35.82 49500 5.73 5.37 -34.2 50000 5.33 6.16 -32.54 50500 5.1 6.96 -30.66 51000 5.03 7.75 -28.51 52000 5.33 9.33 -23.28 52500 5.66 9.86 -20.87 53000 6.01 10.17 -18.88 54000 6.53 10.17 -16.47 55000 6.68 10.17 -13.81 55500 6.58 10.17 -12.41 56500 5.99 10.17 -9.54 57000 5.47 10.17 -8.1 58000 3.99 10.17 -5.28 58500 3.01 10.17 -3.96 59500 0.6 10.18 -1.56 60000 -0.83 10.18 -0.53 61000 -4.05 10.18 1.06 61500 -5.82 10.18 1.59 62000 -7.67 10.18 1.92 62500 -9.57 10.35 2.04 63000 -11.41 10.83 1.87 63500 -12.85 11.01 1.21 64500 -15.71 11.18 -0.75 65000 -17.07 11.2 -2.03 65500 -18.33 11.21 -3.5 66000 -19.47 11.24 -5.14 66500 -20.47 11.29 -6.94 67000 -21.29 11.41 -8.87 67500 -21.93 11.61 -10.89 68000 -22.36 11.91 -12.98 68500 -22.59 12.34 -15.1 69000 -22.61 12.9 -17.2 69500 -22.42 13.61 -19.26 70000 -22.04 14.48 -21.22 70500 -21.47 15.51 -23.06 71000 -20.74 16.69 -24.72 71500 -19.86 18.03 -26.2 72000 -18.87 19.5 -27.44 72500 -17.78 21.1 -28.43 73000 -16.63 22.81 -29.15 73500 -15.43 24.59 -29.59 74000 -14.24 26.44 -29.74 74500 -13.05 28.32 -29.6 75000 -11.92 30.2 -29.17 75500 -10.84 32.05 -28.47 76000 -9.85 33.86 -27.51 76500 -8.96 35.59 -26.31 77000 -8.19 37.23 -24.89 77500 -7.54 38.75 -23.29 78000 -7.02 40.13 -21.53 78500 -6.64 41.37 -19.64 79000 -6.39 42.46 -17.66 79500 -6.26 43.38 -15.62 80500 -6.38 44.74 -11.46 81500 -6.93 45.48 -7.39 82500 -7.83 45.68 -3.6 83500 -8.97 45.45 -0.21 84500 -10.26 44.91 2.69 85500 -11.62 44.2 5.05 86500 -12.97 43.42 6.9 87500 -14.25 42.7 8.26 89000 -15.94 41.89 9.51 90000 -17.35 41.62 10.25 90500 -18.44 40.89 10.82 92000 -20.65 39.07 11.72 93000 -22.08 38.17 12.28 94500 -24.17 37.26 13.21 95500 -25.5 36.93 13.91 96500 -25.4 36.82 13.78 99500 -22.78 36.81 12.01 105000 -20.81 29.72 15.0 105500 -19.62 27.8 14.1 106000 -18.18 25.78 13.35 106500 -17.56 25.1 13.48 109000 -17.68 26.2 16.13 110000 -17.62 25.84 17.46 112000 -18.0 25.43 20.1 114500 -18.35 27.07 22.52 115500 -18.67 27.9 23.33 118000 -19.54 28.2 26.17 119500 -20.38 28.71 27.6 120500 -20.83 29.53 28.18 122000 -21.54 30.99 28.63 123500 -22.47 32.21 29.01 124500 -23.47 32.76 29.56 125500 -24.69 33.33 29.93 127000 -26.7 34.29 30.03 128000 -27.35 35.29 29.95 129000 -27.77 36.42 29.78 129500 -28.24 36.88 29.68 130500 -28.87 37.97 29.4 131000 -29.58 38.34 29.28 132500 -31.67 39.48 28.62 134000 -33.62 40.65 27.6 135000 -34.42 41.79 27.19 135500 -35.0 42.68 26.49 137000 -41.73 51.43 14.21 156500 -32.35 49.75 19.48 157000 -30.51 49.22 19.72 158000 -28.05 47.93 17.72 159000 -25.99 46.69 15.27 160000 -24.42 45.55 12.45 161000 -23.38 44.53 9.34 162000 -22.91 43.68 6.05 162500 -22.89 43.32 4.38 163500 -23.29 42.76 1.02 164500 -24.26 42.41 -2.25 165500 -25.77 42.3 -5.33 166500 -27.77 42.43 -8.11 167500 -30.19 42.78 -10.52 168000 -31.54 43.04 -11.55 169000 -34.44 43.71 -13.23 170000 -37.56 44.58 -14.37 171000 -40.79 45.6 -14.92 172000 -44.02 46.75 -14.87 173000 -47.14 47.99 -14.22 174000 -49.79 49.16 -13.13 174500 -51.36 48.62 -14.01 175000 -53.17 48.29 -14.74 176500 -59.26 47.82 -16.54 177000 -61.16 47.56 -17.22 177500 -62.81 47.09 -18.05 178000 -64.12 46.35 -19.07 178500 -65.03 45.28 -20.34 179000 -65.49 43.86 -21.88 179500 -65.21 42.21 -23.46 180000 -64.6 40.3 -25.25 183500 -56.64 33.85 -30.0 190000 -71.73 46.09 -20.99 192000 -69.21 44.05 -22.49 192500 -67.08 43.24 -23.24 193000 -62.26 42.42 -22.64 193500 -57.62 41.03 -21.4 194000 -53.33 39.38 -19.46 194500 -49.73 37.61 -16.51 195000 -46.95 36.12 -12.64 195500 -44.57 35.26 -8.34 196000 -42.09 35.07 -4.01 196500 -39.5 35.49 0.25 197000 -36.85 36.51 4.36 197500 -34.16 38.12 8.25 198000 -31.48 40.37 11.81 198500 -28.89 43.31 14.91 199000 -26.53 46.97 17.36 199500 -24.56 51.26 18.96 200000 -23.31 56.04 19.63 200500 -22.8 60.99 19.24 201000 -22.88 65.72 17.68 201500 -23.35 69.71 14.75 202000 -23.89 72.18 10.48 202500 -24.18 72.69 5.55 203000 -23.96 71.57 0.71 203500 -23.0 69.24 -3.6 204000 -21.17 66.34 -7.22 204500 -18.68 62.77 -9.62 205000 -15.96 58.68 -10.44 205500 -13.33 54.5 -9.76 206000 -10.96 50.63 -7.71 206500 -9.03 47.4 -4.44 207000 -7.08 44.56 -0.83 207500 -4.21 41.52 1.88 208000 -0.61 38.28 3.04 208500 3.15 35.03 2.66 209000 6.72 31.86 1.21 209500 9.9 28.7 -0.99 210000 12.04 25.86 -4.48 210500 13.51 23.21 -8.46 211000 14.44 20.66 -12.65 211500 14.77 18.2 -16.99 212000 14.31 16.11 -21.5 212500 12.69 14.69 -25.99 213000 9.96 13.6 -30.02 213500 6.41 12.65 -33.39 214000 2.2 11.84 -35.95 214500 -2.49 11.21 -37.54 215000 -7.44 10.83 -38.03 215500 -12.38 10.73 -37.35 216000 -17.07 10.85 -35.64 216500 -21.43 11.0 -33.2 217000 -25.32 11.15 -30.07 217500 -28.52 11.32 -26.25 218000 -30.7 11.5 -21.77 218500 -31.44 11.68 -16.85 219000 -30.63 11.88 -11.94 219500 -28.53 12.07 -7.42 220000 -25.5 12.28 -3.46 220500 -21.66 12.5 -0.28 221000 -17.16 12.73 1.86 221500 -12.28 12.94 2.84 222000 -7.3 13.13 2.55 222500 -2.57 13.29 0.98 223000 1.51 13.38 -1.88 223500 4.54 13.42 -5.83 224000 6.42 13.55 -10.45 224500 6.99 13.96 -15.38 225000 5.97 14.73 -20.18 225500 3.35 15.89 -24.25 226000 -0.53 17.42 -26.93 226500 -5.1 19.24 -27.44 227000 -9.58 20.49 -25.68 227500 -13.46 21.09 -22.61 228000 -16.33 21.13 -18.55 228500 -17.52 20.57 -13.76 229000 -16.41 19.49 -9.06 229500 -14.6 17.86 -4.73 230000 -11.69 16.0 -1.2 230500 -7.14 14.82 0.32 231000 -2.28 14.2 -0.49 231500 1.88 13.88 -3.19 232000 4.79 13.7 -7.23 232500 6.5 13.79 -11.91 233000 6.73 14.22 -16.86 233500 5.26 15.07 -21.53 234000 2.23 16.34 -25.27 234500 -1.94 17.99 -27.37 235000 -6.57 19.73 -27.08 235500 -10.89 20.74 -24.83 236000 -14.5 21.16 -21.42 236500 -16.93 21.02 -17.09 237000 -17.41 20.27 -12.21 237500 -15.72 19.09 -7.69 238000 -13.84 17.32 -3.45 238500 -10.31 15.61 -0.45 239000 -5.52 14.61 0.28 239500 -0.81 14.1 -1.19 240000 2.97 13.82 -4.41 240500 5.5 13.7 -8.71 241000 6.76 13.89 -13.52 241500 6.43 14.46 -18.45 242000 4.41 15.45 -22.89 242500 0.95 16.84 -26.16 243000 -1.42 17.81 -26.51 256000 9.53 15.0 14.07 264500 0.0 15.0 0.0 297000 0.0 -3.99 0.0]]}

The attribute-value pairs are defined in Table 1, below.   The attributes are the same for the Effect Data field (of effects in the script) and the Motion Data field (of positions), except that the time values for the Motion Data are relative to the beginning of the show, whereas the time values for the Effect Data are relative to the beginning of the effect itself.  Also, the “rgb” color animation attribute only applies in the Effect Data field in the script table, because it doesn’t make sense to apply colors to positions.

The “hash” attribute is an optimization for large imported data, such as data from importing a drone show.  If you are entering data by hand, your data should not include a hash attribute.

 

Property in Motion Data or Effect Data Example Meaning
pos [pos [0 0 0 0 1000 0 10 0 2000 10 10 0 3000 10 0 0 4000 0 0 0]]

 

The syntax is: [pos [t0 x0 y0 z0 t1 x1 y1 z1…]]. The list of numbers in brackets is a list of samples defining a motion path of coordinates in connected line segments from sample point to sample point.  Each sample point is represented as four numbers, so the length of the list is 4N for N sample points.  Each sample point consists of an integer number of milliseconds followed by X, Y, Z coordinates in meters (integers or floating point numbers).  The milliseconds represent an absolute time, not a time delta.

If the first sample in the list does not begin at time 0, then the implicit starting point at time 0 is 0, 0, 0 coordinates, and the path will interpolate from there to the first sample point explicitly in the list.

Implicitly, the motion path after the last sample point continues with the coordinates of the last sample point.

hpr [hpr [10000 0 0 3600]] The syntax is: [hpr [t0 h0 p0 r0 t1 h1 p1 r1…]]. The list of numbers in brackets is a list of samples defining a motion path of orientations.  Each sample point is represented as four numbers, so the length of the list is 4N for N sample points.  Each sample point consists of an integer number of milliseconds followed by heading, pitch, and roll angles in degrees (integers or floating point numbers).  The milliseconds represent an absolute time, not a time delta.

Heading, pitch, and roll values are not restricted to 360 degrees.  From sample point to sample point, the intermediate heading, pitch and roll values interpolate between the two samples individually as numbers, and the intermediate orientation is constructed from the interpolated heading, pitch and roll values; as opposed to the intermediate orientations being constructed by interpolating between the orientations defined by the heading, pitch and roll values at the sample points.

These interpolation mechanics support “spinning” multiple rotation cycles between sample points.  The example  [hpr [10000 0 0 3600]] means at time 10 seconds (10,000 milliseconds) , the roll is 3600 = 360 degrees * 10.  Interpolating from the implicit identity orientation at time 0 to this sample point at 10 seconds thus rotates the orientation completely around 10 times in the span of 10 seconds.

pos2 [pos2 [0 .5 0 0]] The syntax is: [pos2 [t0 x0 y0 z0 t1 x1 y1 z1…]].  The list of numbers has the same syntax and meaning as for pos, except that pos2 defines a position offset that is rotated by the hpr rotation, if present, and then added to the pos position offset.

To make a spinning wheel with the pyro effect at the end of a 0.5m spoke, the positions and orientation offsets could be: [pos2 [0 .5 0 0]] and [hpr [10000 0 0 3600]].  This position offset is constant, radially out 0.5m from the origin, but the hpr spins that position offset around the origin 10 cycles over 10 seconds.

hpr2 [hpr2 [10000 3600 0 0]] The syntax is: [hpr2 [t0 h0 p0 r0 t1 h1 p1 r1…]]. The list of numbers has the same syntax and meaning as for hpr, except that hpr2 does not affect pos or pos2 offsets.  Hpr2 defines an orientation that is composed with hpr to construct the final orientation of the effect.  Hpr2 applies within the frame of reference of hpr.  In a human arm analogy, the hpr2 is the wrist orientation, and the hpr is the elbow orientation.
rgb (in Effect Data only) [rgb [0 255 10000 65280]] The syntax is: [rgb [t0 rgb0 t1 rgb1…]]. The list of numbers in brackets is a list of color samples defining a color animation from sample point to sample point.  Each sample point is represented as two numbers, so the length of the list is 2N for N sample points.  Each sample point consists of an integer number of milliseconds followed by integer RGB value with B represented by the low 8-bits of the number, G represented by bits 8-15, and R represented by bits 16-23.  The milliseconds represent an absolute time, not a time delta.

If the first sample in the list does not begin at time 0, then the implicit starting point at time 0 is black, and the color animation will interpolate from black to the first sample point explicitly in the list.

Implicitly, the color after the last sample point continues with the color of the last sample point.

The RGB colors defined by this syntax apply to effects whose VDL contains the color term, “ScriptRGB” instead of an explicit color like “Red” or “Blue”.  The ScriptRGB term indicates the effect should get its color from the Effect Data field.

hash [hash 1908853237] The hash attribute value is an integer identifying full payload of the Motion Data or Effect Data field (excluding the hash value itself).  The hash attribute is an optional optimization for large imported data, such as data from imported drone shows, enabling the Finale 3D renderer to determine quickly whether the data has changed.

If you are entering Motion Data or Effect Data manually, your data is probably small enough that the hash attribute optimization is insignificant, so your data does not need to include the hash attribute.  If you are generating large data manually or by some programmatic method, you should calculate and include a hash based on the data content using any hash algorithm that is likely to produce a different hash value for different data.