Prim#

Fully qualified name: isaacsim::foundation::objects::Prim

class Prim#

High-level wrapper over one or more USD prims for batch attribute and schema operations.

Wraps a list of USD prim paths and exposes a unified interface for querying and modifying prim metadata, schema APIs, variant selections, and arbitrary attributes. All methods that accept an indices parameter operate only on the prims at those positions; when indices is omitted, all wrapped prims are processed.

Paths may contain regular expressions; the constructor resolves them against the active stage unless resolvePaths is false.

Subclassed by isaacsim::foundation::objects::Xform, isaacsim::foundation::objects::physics_scenes::PhysicsScene

Public Functions

Prim(
const std::variant<std::string, std::vector<std::string>> &paths,
bool resolvePaths = true,
)#

Construct a Prim wrapper for one or more USD prim paths.

Parameters:
  • paths – [in] Single path string or list of path strings. May include regular expressions that are expanded against the active stage.

  • resolvePaths – [in] Whether to resolve and expand the given paths (true) or use them as-is (false).

Throws:

std::runtime_error – if no active or default stage has been set.

~Prim() = default#
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 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

Prim()#
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.