Type any phrase to search documentation

Software Documentation

Scenery and positionsDocumentation

Last updated: March 30, 2021

2 Positions coordinate system

The coordinates of positions are relative to the model they are attached to, if they are attached to a model, and are global coordinates otherwise. To symbolize the global coordinate system and to convey the correct sense of scale, a six foot tall human facing the forward camera is drawn at the coordinates <0, 0, 0>. His name is “Origin Man.”

Figure 1 – “Origin Man” stands at coordinates <0, 0, 0>.


In the global frame of reference, the X-axis aims to the right of the screen, the Y-axis aims up into the sky, and the Z-axis aims out of the screen toward the viewer (you). Position orientations are represented in Euler angles as heading (a rotation about the global Y-axis), pitch (a rotation about the global X-axis), and roll (a rotation about the global Z-axis). All angles are “right-handed” rotations, meaning that that if you aimed the thumb of your right hand in the direction of the axis of rotation, then your fingers would curl in the positive direction of the angle. Following this convention, heading is a counter-clockwise rotation, viewed from above; pitch aims the position’s up vector forwards toward the viewer (i.e., aiming out of the screen) when viewed from the front; roll aims the position’s up vector to the left on the screen when viewed from the front.

The orientation of a position may be calculated by a sequence of three rotations, rotating the position first by pitch about the global X-axis, then by roll about the global Z-axis, and finally by heading about the global Y-axis. The ranges of the angles are,

Heading: [-180, +180]
Pitch: [-180, +180]
Roll: [-90, +90]

In this Euler angle axes and angles convention, rotation sequences with a roll of +/- 90 degrees are equivalent to other rotation sequences in which heading and pitch sum to a constant value. In circumstances in which an orientation is converted to a rotation sequence that is not uniquely defined, the rotation sequence with pitch = 0 will be chosen arbitrarily.


Rotating positions

To rotate the heading of a position, right click the position and select “Rotate (heading)”. A rotation wheel will appear. If you drag the reddish arrow around the wheel, you will adjust the heading of the position. The heading of the position is the global heading, analogous to a compass heading, which is unaffected by the pitch or roll of the position. The arrow on the top of the position disk always aims in the same direction as its heading.


Figure 2 – Adjust the heading by right-clicking the position and selecting “Rotate (heading)”.


The pitch of the position aims the arrow on the position disk down into the ground (positive pitch) or up into the sky (negative pitch), as shown in Figure 3.


Figure 3 – Adjust the pitch by right-clicking the position and selecting “Rotate (pitch)”.


The roll angle rotates the position on its side. Following the right-hand rule, a positive roll rotates the position to the left when viewed from the front, since the Z-axis aims toward the front.

Figure 4 – Adjust the pitch by right-clicking the position and selecting “Rotate (roll)”.



Rotating positions on a wall

The heading, pitch and roll angles are convenient for representing orientations that are resting on the ground or are pitched or rolled by less than 90 degrees. They aren’t at all convenient for representing sideways positions, such as positions mounted on a wall or side of a tower facing outward. The position shown in Figure 5 can be rotated with the right-click context menu command, “Rotate (around position’s up vector)”. The other rotation commands shown in Figure 2, Figure 3, and Figure 4, are useless for rotating positions on walls.


Figure 5 – Use “Rotate (around position’s up vector)” to rotate positions on walls. The other rotation commands are useless.


Moving positions on a wall

Positions will automatically orient themselves flatly against the surface when you are dragging them onto a wall, but you may need to adjust the coordinates. The right-click menu item “Move on axis…” brings up three colored axes in the frame of reference of the position. You can drag the red, green, and blue arrows to move the position along any of its local axes, as shown in Figure 6.

Figure 6 – The right-click menu command “Move on axis” bring up three arrows that you can drag to adjust the position.


Arranging positions on towers and trusses

The right-click menu commands to rotate and move positions apply to all selected positions, as a group, centered around the position you are right-clicking. For towers and walls, you may find it easier to arrange positions in a pattern on the ground, and then rotate the entire pattern up sideways and project it onto the tower or wall. Consider two examples.

Example 1: Arranging positions vertically with even spacing on the side of a tower that tapers toward the top. The rulers and tools for arranging positions work best on the ground, so arrange the positions on the ground in a line in regular intervals. Then select all the positions in the line, right-click on the first position in the line, and do “Rotate (pitch)” or “Rotate (roll)” to rotate the entire line up into air. Then do the menu item “Positions > Coordinates > Project positions on their down axis to nearest surface” to project the positions against the tower surface behind them.

Example 2: Arranging positions on the seats of a ferris wheel. Measure the diameter of the ferris wheel by right clicking on one of the seats and doing “Measure to this point” from the context menu. Knowing now the diameter of the circle, insert N positions into the scene with the menu item, “Positions > Insert > Insert multiple…” and then do the menu item “Positions > Arrange into pattern > Into a circle…” to arrange the positions into a circle of the right diameter — on the ground. Slide the circle of positions on the ground so it is in front of the ferris wheel, as if the ferris wheel were casting a shadow on the ground in front of it and the positions were on the shadows of the seats. Right click on the position farthest from the ferris wheel base, and do “Rotate (pitch)” to pitch the entire circle of positions upward. Then right click one of the positions and do “Move on axis…” to move the circle of positions up and back to register against the ferris wheel model.



Exporting coordinates and angles

The Finale Generic CSV export format (see Finale Generic CSV (full show export format)) contains the world coordinates and angles of the positions and effects of an exported show. The exported CSV converts the coordinates and angles to world coordinates, as a convenience. By contrast, the table windows in Finale 3D contain relative coordinates and angles, i.e., effects are relative to their positions; and positions are relative to the models they are attached to if they are attached to models. Figure 7 shows an example of the table windows involved in calculating the world coordinates and angles of effects.


Figure 7 – In the table windows, effects are relative to positions, which are in turn relative to the models they are attached to.


The example CSV export that you can download from Table 3 below corresponds to Figure 7. It covers all the major scenarios — left/right angles, forward/back angles, effects in rotated positions, and effects in rotated positions attached to rotated models. The test file has eight positions, each with two effects. The first position has effects at 30 degrees left and 30 degrees right relative to the position. The second position has effects at 30 degrees forward and 30 degrees back. The next two positions are the same as the previous two except the positions are themselves rotated 90 degrees clockwise. The next four positions are the same as the previous four except that the positions are attached to a model that is itself translated and rotated 90 degrees clockwise.


Table 3 – Example files and downloads

Download linkExplanation
angle-test.csvTest file for exporting angles and coordinates