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(
const array::Array &visibilities,
const std::optional<array::Array> &indices = std::nullopt,
)#

Set the visibility of the selected prims.

Parameters:
  • visibilities – [in] Boolean flags (shape (N,1)). true makes a prim visible, false makes 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(
const std::optional<array::Array> &indices = std::nullopt,
)#

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 rotationFormat is neither "xyzw" nor "wxyz".

Returns:

A pair of (positions, orientations). Positions have shape (N,3); orientations are quaternions in rotationFormat order 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 rotationFormat is neither "xyzw" nor "wxyz".

Returns:

A pair of (translations, orientations). Translations have shape (N,3); orientations are quaternions in rotationFormat order with shape (N,4).

array::Array getLocalScales(
const std::optional<array::Array> &indices = std::nullopt,
)#

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(
const array::Array &scales,
const std::optional<array::Array> &indices = std::nullopt,
)#

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 translations or orientations must 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 rotationFormat order (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 rotationFormat is 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 positions or orientations must 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 rotationFormat order (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 rotationFormat is 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, and xformOp:scale remain, 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 std::optional<array::Array> &indices = std::nullopt,
) 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 std::optional<array::Array> &indices = std::nullopt,
) 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 std::optional<array::Array> &indices = std::nullopt,
) 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 std::optional<array::Array> &indices = std::nullopt,
) 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 std::optional<array::Array> &indices = std::nullopt,
) 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 std::optional<array::Array> &indices = std::nullopt,
) 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,
) const#

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 std::string &schemaType,
const std::optional<array::Array> &indices = std::nullopt,
) 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,
) const#

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,
) const#

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,
) const#

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 std::optional<array::Array> &indices = std::nullopt,
) 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,
) const#

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 std::string &attributeName,
const std::optional<array::Array> &indices = std::nullopt,
) 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 std::string &attributeName,
const std::optional<array::Array> &indices = std::nullopt,
) 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 OutputValueType variant (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,
) const#

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 InputValueType variant.

  • indices – [in] Indices of prims to process. If omitted, all wrapped prims are processed.

Public Static Functions

static array::Array areOfType(
const std::variant<std::string, std::vector<std::string>> &paths,
)#

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 UsdGeomXformable schema, which every shape, light, camera and mesh derives from. A true flag therefore does not imply the prim is a plain Xform; use the subclass-specific areOfType to 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(
const std::variant<std::string, std::vector<std::string>> &paths,
bool raiseOnMixedPaths = true,
)#

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,
) const#

Converts optional selection indices into signed index values.

int64_t _resolveIndexedSize(
const std::optional<array::Array> &indices,
) const#

Returns the number of selected prims.

std::vector<std::string> _resolveIndexedPaths(
const std::optional<array::Array> &indices,
) const#

Returns paths for the selected prims.

std::vector<std::string> _resolveStringList(
const std::variant<std::string, std::vector<std::string>> &values,
const std::optional<array::Array> &indices,
) const#

Expands a scalar or list value to match the selected prim count.

Protected Attributes

std::vector<std::string> m_paths#

Resolved USD paths wrapped by this object.