Transformation#

This page discusses how to move things around.

To describe the position, orientation and size of an object in the scene must be defined by a sequence of transform operators (also known as a scene graph). This sequence is ordered such that global transforms are towards the top, while local transforms are towards the bottom. If you are not familiar with what “global” and “local” means, here is an example.

Scene Graph Example#

Imagine that there is a observatory that has a movable base, a dome that can rotate around and a retractable scope that can rotate up and down. Inside the observatory sits a bird, Oro. You are sitting at the scope head, looking at Oro. And assume that Oro is frozen in space, so that if the observatory moves, it moves relative to Oro and you want to see Oro from different perspectives. The whole setting is:

Note that the scope head points towards the positive direction of the Z-axis, so we are looking towards the negative direction of Z-axis. Because the scope is retractable, let’s start at 0 length, so that we are inside Oro’s body. This is the starting pose, if no transform operators are defined at all.

Let’s define these entities in our descriptions. A camera, with camera parameters defined as described in Camera; A Dome light so that we can see things; and Oro, which is a Geometry. The observatory is only conceptual, we don’t need to see it.

dome_light:
  type: light
  subtype: dome
  intensity: 1000

default_camera:
  type: camera
  camera_parameters: $[/camera_parameters]

penguin:
  type: geometry
  subtype: mesh
  usd_path: [PATH_TO_PENGUIN]

Note

If no camera is defined, no images are output, because nothing is there to see.

Now we extend the scope along the Z-axis using the translate operator, so that we are 1000 units way from Oro, and take a picture.

default_camera:
  # ...
  transform_operators:
  - translate:
    - 0
    - 0
    - 1000

We can then rotate the scope around the X-axis by 30 degrees. This applies a rotateX operator, upon the original translate.

transform_operators:
- rotateX: -30
- translate:
  - 0
  - 0
  - 1000

If we go the other way around, we will be rotating the muzzle itself, and translating along the Z-axis, in this case the camera looks away from Oro, which is not our intention.

Next, rotate the turret, giving another operator rotateY.

transform_operators:
- rotateY: 60
- rotateX: -30
- translate:
  - 0
  - 0
  - 1000

And eventually, drive the observatory forward, which is yet another translate, so that we don’t always have Oro at the center of the screen. Because we are defining 2 translates, we add a suffix translate_global:

transform_operators:
- translate_global:
  - 0
  - 0
  - 1000
- rotateY: 60
- rotateX: -30
- translate:
  - 0
  - 0
  - 1000

Note

Duplicated names of transform operators are not allowed. Add _suffix to differentiate.

Let’s randomize all transform operators with mutable attributes and generate five images.

transform_operators:
- translate_global:
    distribution_type: range
    start:
    - -500
    - 0
    - -500
    end:
    - 500
    - 0
    - 500
- rotateY:
    distribution_type: range
    start: -180
    end: 180
- rotateX:
    distribution_type: range
    start: -60
    end: 60
- translate:
    distribution_type: range
    start:
    - 0
    - 0
    - 800
    end:
    - 0
    - 0
    - 1200

Now we have different views of Oro! The AI model you are about to train will get a better understanding of Oro.

Transform Operators#

All available transform operators are:

Translate operator

Operator Name	Required Format
translate, rotateXYZ, rotateXZY, rotateYXZ, rotateYZX, rotateZXY, rotateZYX, scale	numeric, dimension 3 list
orient	numeric, dimension 4 list
rotateX, rotateY, rotateZ	numeric
transform	numeric, dimension 4x4 list of lists

Required format indicates the dimension and type of expected input. numeric means float or int, or a value evaluated to float or int by macro or mutable attribute. For example:

rotateXYZ:
- $[../index]
- 5
- 10

is valid, while:

rotateXYZ:
- True
- abc

is not valid.

Note

orient is represented by a quaternion in wxyz order, in which w is the scalar part; all other rotate operators describe rotation in degrees.
The Euler angle sequence is represented from local to global from left to right. For example, rotateXYZ means Y is global rotation relative to X, and Z is global rotation relative to Y.
Scale operators appear at the bottom. It’s not recommended to define a scale above a translate or rotate, unless this is intended.