Coordinate spaces

Every slot (object) in a world within Resonite has an associated set of position, rotation and scale values. This is true even if the slot does not have a visual component associated with it. Since space is three dimensional inside Resonite worlds, position is encoded as a float3 datatype - a 3D vector of coordinates along X, Y, and Z axes. Rotations can also be expressed as angular displacements about these three axes and this is how it is displayed in the slot inspector panel. However rotations are managed internally, and exposed to ProtoFlux, as a four dimensional floatQ - a quaternion. Scale works similarly to position and is encoded as a float3.

the Inspector Panel shows a reference of directions in Resonite

In Resonite the positive X axis direction is defined as 'right', negative X direction is 'left'. The positive Y axis direction is defined as 'up', negative Y is 'down'. The the positive Z axis direction is defined as 'forward', negative Z direction is 'back. The positive X, Y and Z axes correspond to the red, green and blue arrows on the gizmo tool. Distances are scaled such that a unit of 1 in any axis direction corresponds to 1 meter. Angles are displayed in the slot inspector panel in units of degrees.

Global vs. Local

For any slot, there are two coordinate spaces which may be relevant:

• The Global coordinate space, which is measured relative to the world root slot.
• The Local coordinate space, which is measured relative to the slot's immediate parent in the slot hierarchy.

Local coordinates are the ones displayed in the slot inspector panel.

The world's root slot is unique and always at the top of the world slot hierarchy. It has a fixed position at [0,0,0], fixed identity rotation (basically [0,0,0] degrees) and [1,1,1] scaling. This means that, for a slot parented directly under the world root, global and local coordinate measures will be equivalent. This is also true if, and only if, all of a slot's parents have [0,0,0] position, [0,0,0] rotation, and [1,1,1] scale.

For example, if a slot, Slot_A, is parented under the world root and has global position [1,0,0] (i.e. 1 meter to the right of the world root) its local position, as shown in the inspector, will be [1,0,0]. If another slot, Slot_B, is parented under Slot_A and also has local position [1,0,0], its global position is [2,0,0]. If Slot_A is now moved to [1,1,0] (i.e. translated 1 meter upwards), Slot_B will move with Slot_A and its local position remains [1,0,0]; its global position will now be [2,1,0].

Transformations

In principle one could calculate a slot's global position by summing its local position vector with those of all of its parents. However it is much easier to use the Global Transform ProtoFlux node for this purpose. The same goes for global rotation and scale, although those would require the element-wise product of parent local rotations or scales due to how those quantities are combined.

There are many ProtoFlux nodes which are particularly useful for moving, rotating and scaling slots in the Transform category of the ProtoFlux node browser. When applying a transformation (movement, rotation or scale) to a slot, such as via a Drive or a Tween, one usually wants the input value to be in the target slot's local coordinate space. Initially calculating transformations using global coordinates may be useful if the intended effect should not depend on the slot's current context. Conversely, typically one wants transformations to happen relative to the slot's current state which requires the use of local coordinates. There are a several nodes for converting positions, directions, rotations and scales between global and local coordinates. There are also ones for converting between the local coordinate spaces of two slots with different parents.

It is possible to scale objects non-uniformly (i.e. having different X, Y and Z scale values), though this should be done with care as child slots inherit scaling from their parents. This can cause hard-to-debug issues where a visual component of a child slot displays strangely due to a non-uniformly scaled parent somewhere above in the hierarchy. The requirement for non-uniform scaling to achieve the desired look with primitive meshes (boxes, spheres, cones, quads etc.) can, and should, usually be avoided by instead changing the parameters of the respective mesh component.

In addition to ProtoFlux, slots can be made to move or transform in various ways using components under the Transform component category (e.g. Spinner, Wiggler, Wobbler etc.).

Tools

• The Dev Tool is extremely useful since it gives access to the transform gizmos and slot inspector panels which enable setting coordinates precisely.
• The ProtoFlux Tool is required for interacting with coordinate values via ProtoFlux nodes.
• The Meter Tool can be useful for measuring distances in various ways.

See Also

• 3D Space defined in Wikipedia
• 3D Vectors defined in Wikipedia
• Quaternions defined in Wikipedia