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
indicesparameter operate only on the prims at those positions; whenindicesis omitted, all wrapped prims are processed.Paths may contain regular expressions; the constructor resolves them against the active stage unless
resolvePathsisfalse.Subclassed by isaacsim::foundation::objects::Xform, isaacsim::foundation::objects::physics_scenes::PhysicsScene
Public Functions
- Prim( )#
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#
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 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
-
Prim()#
- 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.