Prim identity and transform#
Structural columns on every physics-domain prim: the type token, the applied-schema list, and the local transform. Prims are created implicitly by an upsert write through a path-list query. The path, parent and children built-ins are derived by ovstage from the written paths and must never be written.
Scope: prim
What USD population writes#
A prim gets a row when its type or an applied schema is in the producer’s physics set (PhysicsScene, joints, PhysicsRigidBodyAPI, PhysicsCollisionAPI, PhysicsMaterialAPI, articulation, deformable, particle, vehicle and Newton schemas), when it is a collider GeomSubset, when it authors a physics material binding, when it is a PointInstancer reaching a physics prototype, or when it is a one-hop Boundable target of a published relationship. EVERY ANCESTOR of such a prim also gets a row, carrying only the type token, the schema list if any, and the transform columns if Xformable.
Columns#
Column |
Type |
Required |
Producer writes |
If absent |
|---|---|---|---|---|
|
uint64 |
yes |
token id of the type name, or of ovstage_population_untyped for a typeless prim |
The prim is not classified. Type-enumerated components (PhysicsScene, shapes) never see it; schema-enumerated components (rigid body) still do, so a body without a type has no shape. |
|
uint64 array |
no |
token ids of every applied schema, sorted by id; the column is omitted when the prim applies none |
No API schema is read. Every api_schema component is enumerated or gated by a CONTAINS predicate on this list; a column of an API that is not listed is inert even if written. The producer omits the column entirely on a prim with no applied schemas. |
|
float64[16], MATRIX |
no |
the prim’s composed LOCAL transform (all xformOps folded into one matrix) |
The consumer falls back to xformOp:transform, then the xformOp:* stack, then identity. The producer never writes xformOp:* columns, so on a producer-populated stage this column is the local transform. |
|
bool8 |
no |
the USD resetXformStack flag, false included |
Parent transforms compose normally. |
|
float64[16], MATRIX |
no |
on a PHYSICS-only populate: the LOCAL matrix as a seed, later replaced by ovstage_compute_hierarchy; on a populate that includes RENDERING: not written by population at all |
The consumer composes the world transform from the local matrices of the prim and its ancestors, stopping at omni:resetXformStack or the root. |
Notes#
Do not write usd-path, usd-parent, usd-children or usd-active: ovstage derives them from the written paths and the hierarchy index. usd-active is not supported for reads or filters.
Ancestors need rows. The consumer walks the parent chain for transforms, so every ancestor of a physics prim must exist with at least usd-prim-type and, if Xformable, omni:xform. The producer guarantees this by populating the whole ancestor chain.
Two id namespaces live in one path dictionary: token ids (type names, schema names, token-valued attributes) come from intern_token; path ids (relationship targets, _protoPath) come from intern_path. The producer never stringifies on write.
Native instancing: prototype content is published once under /__Prototype_N with an extra PrototypeRootAPI entry in usd-schemas, and each instance root carries a _protoPath column (one path id). No rows exist at instance-proxy paths.
Reads observe sealed ordinals only. Advance the write floor to the population ordinal before attaching or draining. Writes are UPSERT; a column that disappears from a prim must be deleted explicitly, and a prim that leaves the domain is deleted whole with an empty attribute list.
Any 8-bit integer or bool column decodes as bool on the consumer; float64 columns with 2 to 4 lanes are narrowed to float32; lane counts above 4 are rejected except for the 16-lane matrices.