Alembic archives

The main format used in Sky Engine for carrying information about scene definition: models and their relative
positions (or position ranges for randomization) is Alembic (.abc).
Alembic exchange format developed by Sony Pictures Imageworks and Lucasfilm is widely used in the industry
and is supported by most of the modern CG tools.
Alembic file format can contain locators, geometries and cameras organized in a tree.

Agenda:

• Sky Engine Alembic naming convention
• Additional parameters
• Instancing
• Scene setups example

Sky Engine Alembic naming convention

If you'd like to prepare an arbitrarily complicated scene that can be automatically with no further configuration
loaded and organized in the Sky Engine Renderer, you need to follow the guidelines below.

The function and meaning of files and nodes building a scene is controlled by name suffixes. We have defined 7
file name suffixes and 5 node name suffixes.

Possible file name suffixes:

• SCN - scene file,
• COL - collection file,
• GEO - geometry file,
• CAM - camera file,
• STS - surface sampler file,
• VTS - volume sampler file,
• ITS - instancer sampler file.

Possible node name suffixes:

• ROOT - a collection locator and collection file attachment point,
• GEO_NUL - geometry locator and geometry file attachment point,
• CAM_NUL - camera locator and camera file attachment point,
• LIGHT_NUL - light locator,
• NUL - general purpose empty locator.

Of course, you don't need to use all of them in a scene. As you've seen above, three files: SCN, GEO and CAM
are sufficient to create a scene with an animation, light and camera already encoded.

Special node names can indicate the name of the file that should be attached there. For example, when you see
the example_ROOT node in the SCN file, you can expect to find an example_COL.abc file in the same folder.
Similarly, player_GEO_NUL node is a place, where a player_GEO file is attached. CAM_NUL node and CAM file
are analogous.

LIGHT_NUL and NUL nodes don't indicate additional files. LIGHT_NUL is just a locator for a light, white sphere
light is put there automatically if you load a full Alembic scene. NUL node is used when some location needs to
be specified, but it's not a light, geometry, camera or collection locator - for example the point the camera
looks at, camera target.

SCN file

This is a starting point for the Alembic scene parsing. If you use just a folder name to load the Alembic scene,
the SCN file is automatically found inside.

There can be only one SCN file for a scene and the SCN file must be flat. If you want to create a multi-level
scene you have to use ROOT nodes and COL files (see below).

This file provides attachment points for all the other files, so you can find all the special nodes there
(ROOT, GEO_NUL, CAM_NUL, LIGHT_NUL, NUL).

COL file

Collection file extends the SCN functionality - it's basically another SCN file that starts at a ROOT node.
You can use the ROOT nodes inside the COL files too, so the scene can have arbitrarily complicated,
arbitrarily deep structure.

GEO file

Geometry file - it must contain one geometry (mesh) node. If there are any corrective transformation inside,
like scale change, axis rotation they will be applied during loading. Such corrections are sometimes automatically
applied by the graphic software. However, this feature should never be abused to move the geometry - the position
of the geometry must be controlled by its GEO_NUL node.

GEO file can also contain the keypoints of its mesh. All the locators that are siblings of the mesh node in the
GEO file are interpreted as keypoints. The keypoint node names are also special, but they depend on
the keypoint configuration, so there is no one general rule. For example, the names we assigned for the COCO
person keypoints convention are KP_Ankle_L, KP_Ankle_R, KP_Knee_L, KP_Knee_R etc.

CAM file

Camera file must contain one camera object as defined by Alembic standard with the camera properties.

STS, VTS, ITS files

The sampler files - STS, VTS, ITS - are a bit different. They describe how the node they are attached to behaves.
Each of them has a mesh geometry that describe this behavior.

For example, STS file, surface transformation sampler, randomizes the transformation of the node it is attached
to on a surface of a mesh it has inside. It uses three coordinates: frame number (mesh can be animated)
and the UV coordinates of the mesh. You can think of it as of reversed texturing: instead of using UV coordinates
of the given point on a mesh to put a texture on it, we use UV coordinates to find a position on a mesh.

The mechanism is very similar for VTS and ITS files. VTS, volume transformation sampler, has one more coordinate.
It uses frame number, UV coordinates and the distance from the meshes' local (0, 0, 0) point. This way it can
sample the 3D transformation inside the mesh - in its volume.

Instancer transformation sampler, ITS, takes a bit of different approach. Its purpose is to enable using
mesh's triangles as spots of node instancing. As coordinates, it uses frame number, triangle number
and its barycentrics. This way, if you want to instance the node (and everything that's below in a tree)
at once at the precisely defined N places, you can use a mesh with N triangles, use it as ITS
and choose a different triangle number for each instance.

STS, VTS and ITS can be attached to the same node as other file. Let's say you have a player and a mesh of a pitch
it can stand on randomly. You use files player_GEO.abc, containing player mesh, and player_STS.abc,
containing the pitch mesh. They will both automatically attach to the node player_GEO_NUL.

Another example: you have a flying insect you want to put inside a swarm mesh and multiply it there millions
of times. You can put an insect_GEO_NUL node to the SCN or COL file and then prepare an insect_GEO.abc file
with the insect mesh and an insect_VTS.abc file with a swarm mesh. The insect transformation will be sampled
inside automatically. Now you just have to specify the instance_count to get millions of insects.

You can use this table as a quick reference:

Additional parameters

Above we gave an example for STS file to use the pitch mesh as a surface the player is sampled on. Isn't it
an overkill for this purpose? STS file is perfect to sample objects on complicated surfaces, for a flat surface
it would be easier to define just the translation range for X and Y axes.

For this reason we are also supporting the addition parameters saved in json files.

We support following parameters:

• #t_range_x, #t_range_y, #t_range_z - translation range for each axis,
• #r_range_x, #r_range_y, #r_range_z - rotation range for each axis,
• #s_range_x, #s_range_y, #s_range_z - scale range for each axis.

Each range must be just one number - the range always start from zero and the parameter number is the upper
limit of the range. Just remember to prepare the asset controlled by these parameters in the lower
end of translation, rotation, scale limits.

Parameters json example:

stadium_SCN.json

{ "player_GEO_NUL": { "#t_range_x": 65, "#t_range_y": 100, "#r_range_z": 360 }, "camera_target_NUL": { "#t_range_y": 80 } }

This file goes together with stadium_SCN.abc file. The settings for player_GEO_NUL replace the need for STS file
(translation ranges) and additionally enable free rotation of the player along Z axis (360 degrees). Camera target
locator, camera_target_NUL, also has randomized position, that will cause some camera movement without the need
of further configuration.

Instancing

There are three possibilities to easily instance one node multiple times. Two were already mentioned,
let's see all of them:

• use ITS file,
• use STS file, VTS file or parameters to allow node transformation randomization and multiply the node
  using n_instances setting during scene configuration,
• use multiple nodes with suffixes for the same file.

The third one is new and the simplest. Let's say you have a goal geometry goal_GEO.abc and you want to put it
on two ends of the pitch. Just add the number to the node name in SCN or COL file! The first location would be
called goal_GEO_NUL_000 and the second - goal_GEO_NUL_001. There are three digits because that's the default
behavior, but of course goal_GEO_NUL_0 and goal_GEO_NUL_1 would also work just fine.

Scene setups example

You will see just one SCN file, lots of GEO files and one CAM file. There are no COL files, so all the GEO_NUL
nodes must be in this one SCN file. The SCN file has also accompanying json file. Let's look inside.

You can note that:

• the node structure inside is flat - as required in SCN and COL files,
• there are GEO_NUL nodes for each GEO file in the folder and CAM_NUL for the CAM file,
• there is a NUL node used as a camera target,
• the bumper_GEO.abc will be instanced in four places, rugby_pitch_GEO.abc in two,
• there are four lights - four LIGHT_NUL nodes,
• translation and rotation range of player_GEO_NUL and translation range of camera_target_NUL
  are defined in json file.

You can see the mesh node and keypoints inside (see: SYSTEM_Keypoints tutorial). Here it looks like the
keypoints are one level lower than the mesh node (player_GEOShape). In Blender, player_GEO and player_GEOShape
nodes are merged (player_GEO is used to hold the transformation of the shape moved by the artist). Therefore, if
the artist prepares keypoints as mesh siblings, in the more detailed structure here they are mesh's parent's
siblings.
Camera consist of one simple camera node and a locator.

Summary

In this section you have learnt:

• Alembic format is the main format for storing information of scene definitions in SkyRenderer.
• There are a few suffixes for file names and node names allowing automatic load of robust scenes.
• Additional files like .json and instancing files may be used to manage additionally transformations of nodes.