Xform#
Fully qualified name: isaacsim::foundation::objects::Xform
-
class Xform : public isaacsim::foundation::objects::Prim#
High-level wrapper over one or more USD Xform prims for transform and visibility operations.
Extends Prim with pose (position/orientation) and scale management in both world and local frames, visibility control, and a default-state mechanism for resetting prims to a previously recorded pose.
Note
Transformation operations on non-root articulation links are not supported.
Subclassed by isaacsim::foundation::objects::Camera, isaacsim::foundation::objects::Mesh, isaacsim::foundation::objects::lights::Light, isaacsim::foundation::objects::shapes::Shape, isaacsim::foundation::prims::physics::Articulation, isaacsim::foundation::prims::physics::ColliderBody, isaacsim::foundation::prims::physics::GroundPlane, isaacsim::foundation::prims::physics::RigidBody
Public Functions
- Xform(
- const std::variant<std::string, std::vector<std::string>> &paths,
- bool resetXformOpProperties = true,
- bool resolvePaths = true,
Construct an Xform wrapper.
- Parameters:
paths – [in] Single path or list of paths to USD Xform prims. May include regular expressions.
resetXformOpProperties – [in] Whether to normalize the xformOp stack to translate/orient/scale.
resolvePaths – [in] Whether to resolve and expand path expressions.
-
~Xform() = default#
- void setVisibilities( )#
Set the visibility of the selected prims.
- Parameters:
visibilities – [in] Boolean flags (shape
(N,1)).truemakes a prim visible,falsemakes it invisible. Broadcast rules apply for smaller inputs.indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- array::Array getVisibilities( )#
Get the visibility state of the selected prims.
- Parameters:
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Boolean flags indicating visibility (shape
(N,1)).
- std::tuple<array::Array, array::Array> getWorldPoses(
- const std::optional<array::Array> &indices = std::nullopt,
- const std::string &rotationFormat = "xyzw",
Get the world-frame poses (positions and orientations) of the selected prims.
- Parameters:
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
rotationFormat – [in] Component order of the returned quaternions:
"xyzw"or"wxyz".
- Throws:
std::invalid_argument – if
rotationFormatis neither"xyzw"nor"wxyz".- Returns:
A pair of (positions, orientations). Positions have shape
(N,3); orientations are quaternions inrotationFormatorder with shape(N,4).
- std::tuple<array::Array, array::Array> getLocalPoses(
- const std::optional<array::Array> &indices = std::nullopt,
- const std::string &rotationFormat = "xyzw",
Get the local-frame poses (translations and orientations) of the selected prims.
- Parameters:
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
rotationFormat – [in] Component order of the returned quaternions:
"xyzw"or"wxyz".
- Throws:
std::invalid_argument – if
rotationFormatis neither"xyzw"nor"wxyz".- Returns:
A pair of (translations, orientations). Translations have shape
(N,3); orientations are quaternions inrotationFormatorder with shape(N,4).
- array::Array getLocalScales( )#
Get the local scales of the selected prims.
- Parameters:
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Scale values (shape
(N,3)).
- void setLocalScales( )#
Set the local scales of the selected prims.
- Parameters:
scales – [in] Scale values to apply (shape
(N,3)). Broadcast rules apply for smaller inputs.indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- void setLocalPoses(
- const std::optional<array::Array> &translations = std::nullopt,
- const std::optional<array::Array> &orientations = std::nullopt,
- const std::optional<array::Array> &indices = std::nullopt,
- const std::string &rotationFormat = "xyzw",
Set the local-frame poses (translations and/or orientations) of the selected prims.
At least one of
translationsororientationsmust be provided. This method teleports prims to the specified poses.- Parameters:
translations – [in] Local-frame translations (shape
(N,3)). Optional.orientations – [in] Orientations as quaternions in
rotationFormatorder (shape(N,4)). Optional.indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
rotationFormat – [in] Component order of
orientations:"xyzw"or"wxyz".
- Throws:
std::invalid_argument – if
rotationFormatis neither"xyzw"nor"wxyz".
- void setWorldPoses(
- const std::optional<array::Array> &positions = std::nullopt,
- const std::optional<array::Array> &orientations = std::nullopt,
- const std::optional<array::Array> &indices = std::nullopt,
- const std::string &rotationFormat = "xyzw",
Set the world-frame poses (positions and/or orientations) of the selected prims.
At least one of
positionsororientationsmust be provided. This method teleports prims to the specified poses.- Parameters:
positions – [in] World-frame positions (shape
(N,3)). Optional.orientations – [in] Orientations as quaternions in
rotationFormatorder (shape(N,4)). Optional.indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
rotationFormat – [in] Component order of
orientations:"xyzw"or"wxyz".
- Throws:
std::invalid_argument – if
rotationFormatis neither"xyzw"nor"wxyz".
-
void resetXformOpProperties()#
Normalize the xformOp stack of all wrapped prims to the standard translate/orient/scale order.
Removes unsupported or redundant xformOp attributes and ensures only
xformOp:translate,xformOp:orient, andxformOp:scaleremain, in that order. World-frame poses are preserved through the normalization.
-
size_t size() const#
Return the number of wrapped prims.
- Returns:
Count of prims managed by this wrapper.
-
const std::vector<std::string> &paths() const#
Return the resolved stage paths of all wrapped prims.
- Returns:
Ordered list of absolute USD stage paths.
-
const Stage &getStage() const#
Return the Stage associated with the wrapped prims.
- Returns:
Reference to the Stage wrapper.
- std::vector<std::string> getName( ) const#
Get the prim names (leaf tokens of each path) for the selected prims.
- Parameters:
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Ordered list of name tokens, one per selected prim.
- std::vector<std::string> getTypeName( ) const#
Get the USD schema type names of the selected prims.
- Parameters:
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Ordered list of type name strings, one per selected prim.
- std::vector<std::string> getParent( ) const#
Get the parent prim paths of the selected prims.
- Parameters:
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Ordered list of parent path strings, one per selected prim.
- std::vector<std::vector<std::string>> getChildren( ) const#
Get the direct child prim paths of the selected prims.
- Parameters:
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Ordered list of child path lists, one list per selected prim.
- std::vector<std::unordered_map<std::string, std::vector<std::string>>> getVariantSets( ) const#
Get the variant sets and their available variants for the selected prims.
- Parameters:
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Ordered list of maps from variant-set name to list of available variant names, one map per selected prim.
- std::vector<std::unordered_map<std::string, std::string>> getVariantSelection( ) const#
Get the active variant selection for each selected prim.
- Parameters:
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Ordered list of maps from variant-set name to selected variant name, one map per selected prim.
- void setVariantSelection(
- const std::unordered_map<std::string, std::string> &variants,
- const std::optional<array::Array> &indices = std::nullopt,
Set the active variant selection on the selected prims.
- Parameters:
variants – [in] Map of variant-set name to variant name to activate.
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- array::Array isA( ) const#
Check whether each selected prim is typed as the given USD schema type.
- Parameters:
schemaType – [in] USD schema type name to test (e.g.
"UsdGeomMesh").indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Boolean flags (dtype bool, shape
(N,1)), one per selected prim.
- array::Array hasApi(
- const std::string &schemaType,
- const std::optional<std::string> &instanceName = std::nullopt,
- const std::optional<array::Array> &indices = std::nullopt,
Check whether each selected prim has the given USD API schema applied.
- Parameters:
schemaType – [in] USD API schema type name.
instanceName – [in] For multi-apply schemas, the instance name to check. Single-apply schemas leave this empty.
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Boolean flags (dtype bool, shape
(N,1)), one per selected prim.
- array::Array applyApi(
- const std::string &schemaType,
- const std::optional<std::string> &instanceName = std::nullopt,
- const std::optional<array::Array> &indices = std::nullopt,
Apply a USD API schema to each selected prim.
- Parameters:
schemaType – [in] USD API schema type name.
instanceName – [in] For multi-apply schemas, the instance name to use.
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Boolean flags indicating success (dtype bool, shape
(N,1)), one per selected prim.
- array::Array removeApi(
- const std::string &schemaType,
- const std::optional<std::string> &instanceName = std::nullopt,
- const std::optional<array::Array> &indices = std::nullopt,
Remove a USD API schema from each selected prim.
- Parameters:
schemaType – [in] USD API schema type name.
instanceName – [in] For multi-apply schemas, the instance name to remove.
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Boolean flags indicating success (dtype bool, shape
(N,1)), one per selected prim.
- std::vector<std::vector<std::string>> getAppliedSchemas( ) const#
Get the names of all applied API schemas for each selected prim.
- Parameters:
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Ordered list of schema name lists, one list per selected prim.
- array::Array createAttribute(
- const std::string &attributeName,
- const std::string &typeName,
- const std::optional<array::Array> &indices = std::nullopt,
Create a custom attribute on each selected prim.
- Parameters:
attributeName – [in] Name of the attribute to create.
typeName – [in] USD value type name (e.g.
"float","double3").indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Boolean flags indicating whether the attribute was created (dtype bool, shape
(N,1)), one per selected prim.
- array::Array removeAttribute( ) const#
Remove a custom attribute from each selected prim.
- Parameters:
attributeName – [in] Name of the attribute to remove.
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Boolean flags indicating whether the attribute was removed (dtype bool, shape
(N,1)), one per selected prim.
- OutputValueType getAttributeValues( ) const#
Get the values of a named attribute for each selected prim.
- Parameters:
attributeName – [in] Name of the attribute to query.
indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
- Returns:
Attribute values as an
OutputValueTypevariant (string list, nested string list, or numeric array).
- void setAttributeValues(
- const std::string &attributeName,
- const InputValueType &values,
- const std::optional<array::Array> &indices = std::nullopt,
Set the values of a named attribute on each selected prim.
- Parameters:
attributeName – [in] Name of the attribute to set.
values – [in] New attribute values as an
InputValueTypevariant.indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.
Public Static Functions
- static array::Array areOfType( )#
Check whether the prims at the given paths are of the type handled by this class.
As the base class of all transformable prims, this method tests for the
UsdGeomXformableschema, which every shape, light, camera and mesh derives from. Atrueflag therefore does not imply the prim is a plainXform; use the subclass-specificareOfTypeto narrow it down.The paths are resolved against the active stage before being checked. Since this method is static, the returned array is always allocated on the CPU.
- Parameters:
paths – [in] Single path string or list of path strings. May include regular expressions that are expanded against the active stage.
- Throws:
std::runtime_error – if the given paths do not correspond to existing prims.
- Returns:
Boolean flags (dtype bool, shape
(N,1)), one per resolved prim.
- static std::tuple<std::vector<std::string>, std::vector<std::string>> resolvePaths( )#
Resolve a path expression against the active stage.
- Parameters:
paths – [in] Single path or list of paths, may include regular expressions.
raiseOnMixedPaths – [in] If
true, throws when existing and non-existing paths are mixed.
- Returns:
A pair of (existing paths, non-existing paths).
Protected Functions
-
Xform()#
-
void _initialize(bool resetXformOpProperties = false)#
Normalizes the xformOp stack of the wrapped prims when requested.
- std::vector<int64_t> _resolveIndexValues(
- const std::optional<array::Array> &indices,
Converts optional selection indices into signed index values.
- int64_t _resolveIndexedSize(
- const std::optional<array::Array> &indices,
Returns the number of selected prims.