3D Transforms & Coordinates (TransformProperties)

Comprehensive reference of 3D transform conventions in the Aircada SDK, including coordinate systems, scale factors, and rotational math.
Published: 7/10/2026

In Aircada, all 3D scene objects have a transform property conforming to TransformFacade. This includes position, rotation, and scale facades.

Rather than using direct property reassignments (which would fail because the subproperties are read-only facade instances), developers interact with transforms using a set of dedicated read and write methods.

The Coordinate System & Units#

How Aircada maps 3D spatial dimensions to standard axes, scales, and physical metrics.

Aircada uses the industry-standard right-handed coordinate layout (identical to WebGL and Three.js):

- X Axis (Horizontal): Horizontal position. Positive values (+X) translate to the viewer's right, negative values (-X) translate to the left.

- Y Axis (Vertical/Elevation): Height. Positive values (+Y) move upwards (elevation), negative values (-Y) move downwards below the baseline.

- Z Axis (Depth): Depth relative to camera. Positive values (+Z) move closer to the camera/viewer (projecting out of the viewport), while negative values (-Z) move further away into the distance.

Unit Scale

The standard system unit is the Meter (1 unit = 1.0 meter). Scaling and translation must be performed with this baseline in mind. For instance, translating by { y: 0.1 } moves the object by exactly 10 centimeters.

  • +X Axis: Right direction in standard right-handed space.
  • +Y Axis: Upward direction, representing real-world height / altitude.
  • +Z Axis: Projects outwards towards the user; -Z goes deep into the scene.
  • Unit scale is strictly metric (1 unit = 1 meter).

Example: Reading and Writing Transform Coordinates#

Example illustrating spatial coordinate access and modification using direct getters and batched set and copy methods.

Example showing how to read and write spatial coordinates.

typescript
// Reading spatial properties
const currentHeight = this.targetCube.transform.position.y;

// Updating positions and scales using the .set(x, y, z) method
this.targetCube.transform.position.set(0, 1.5, -3.0); // 1.5m high, 3m back
this.targetCube.transform.scale.set(0.5, 0.5, 0.5);    // Half size uniformly

// Copying coordinates from another vector or reference source
const targetLocation = { x: 2.0, y: 0.0, z: -1.0 };
this.targetCube.transform.position.copy(targetLocation);
Reading position y coordinate, setting position and scale Vector3s, and copying positions.

Example: Querying and Modifying Quaternion Rotations#

Example showcasing Quaternion getter syntax and updating rotation states via the set and copy methods.

Example showing how to query and modify Quaternion orientations.

typescript
// Reading individual Quaternion components
const wVal = this.targetCube.transform.rotation.w;

// Setting a complete Quaternion orientation
this.targetCube.transform.rotation.set(0, 0.7071, 0, 0.7071);

// Copying orientation from another source
this.targetCube.transform.rotation.copy(otherObject.transform.rotation);
Querying quaternion component w, setting a quaternion rotation, and copying orientation from another object.

Rotational Math: Euler Angles vs. Quaternions#

Understanding how Aircada represents 3D rotations via Quaternions to prevent gimbal lock, and how to configure them via the rotation facade.

Rotations are represented natively in Aircada as a Quaternion via the QuaternionFacade ({ x: number, y: number, z: number, w: number }).

Why Quaternions?

Unlike Euler angles (Pitch, Yaw, Roll) which calculate rotations sequentially, Quaternions rotate around all three axes in a single four-dimensional calculation. This completely avoids gimbal lock (the loss of a degree of rotational freedom when two axes align) and permits mathematically smooth, direct interpolations.

Using the Rotation Facade

To query or modify rotations, use the getters or the batched .set() and .copy() methods.

  • Four-Dimensional Complex Vector: Quaternions (x, y, z, w) represent orientation directly.
  • Zero Gimbal Lock: Eliminates sequential rotational calculation issues.
  • Smooth Interpolation: Standard spherical linear interpolation (Slerp) works natively on Quaternions.

Multiplicative Scale & Bounds#

How Aircada scales 3D meshes along Cartesian axes relative to their original imported dimensions.

The scale property coordinates multiplicative multipliers along each primary coordinate axis (X, Y, Z) using the Vector3Facade class.

Proportional vs. Non-Uniform Scaling

- Uniform Scaling: Keeping the x, y, and z values equal maintains the original mesh proportions (e.g. scale.set(2, 2, 2) doubles the object in size uniformly).

- Non-Uniform Scaling: Stretching or flattening the geometry along selective axes (e.g. scale.set(2, 1, 1) stretches it horizontally only).

Defaults & Physics

The default base scale multiplier depends on visual docs.studio hydration, but is typically normalized relative to the primary bounds. Modifying scale is non-destructive; it adjusts the instance transform matrix without modifying the underlying imported mesh file.

  • Multiplicative multiplier: 1.0 is original imported size.
  • Proportions are maintained by applying uniform values across all three dimensions.
  • Instance-based: Does not mutate the source asset in the project's media library.