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:

../../_images/transformation-0.png

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.

../../_images/transformation-1-1.gif
default_camera:
  # ...
  transform_operators:
  - translate:
    - 0
    - 0
    - 1000
../../_images/transformation-1-2.png

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

../../_images/transformation-2-1.gif
transform_operators:
- rotateX: -30
- translate:
  - 0
  - 0
  - 1000
../../_images/transformation-2-2.png

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.

../../_images/transformation-3-1.gif
transform_operators:
- rotateY: 60
- rotateX: -30
- translate:
  - 0
  - 0
  - 1000
../../_images/transformation-3-2.png

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
../../_images/transformation-4.png

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
../../_images/transformation-5-1.png ../../_images/transformation-5-2.png ../../_images/transformation-5-3.png ../../_images/transformation-5-4.png ../../_images/transformation-5-5.png

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.