10.10.4.7. Transformation

In this page we discuss how to move things around.

We need to describe the position, orientation and size of an object in the scene. We do so by defining 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.

10.10.4.7.1. Scene graph example

We imagine 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. We are sitting at the scope head, looking at Oro. And we also make an assumption, that Oro is frozen in space, so that if the observatory moves, it moves relative to Oro. We want to see Oro from different perspectives. The whole setting is shown in the picture below.

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. Since 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 will be 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. Note that 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 translate along Z-axis, in this case the camera looks away from Oro, which is not what we intend in the first place.

Next, we rotate the turret, giving another operator rotateY.

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

And eventually, we can drive the observatory forward, which is yet another translate, so that we don’t always have Oro at the center of the screen. Since now we are defining 2 translates, we add a suffix, now we have 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 5 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.

10.10.4.7.2. Transform Operators

All available transform operators are defined below.

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.

Note

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.

Note

scale operators should appear at the bottom. It’s not recommended to define a scale above a translate or rotate, unless this is intended.