Mesh#

Fully qualified name: isaacsim::foundation::objects::Mesh

class Mesh : public isaacsim::foundation::objects::Xform#

Wrapper over one or more USD Mesh (points connected into edges and faces) prims.

Wraps existing USD Mesh prims or creates new ones, depending on whether the given paths already resolve on the active stage:

  • If the paths exist, a wrapper is placed over the USD Mesh prims found there.

  • If the paths do not exist, USD Mesh prims are created at each path and then wrapped.

Mesh attributes are ragged: each prim holds its own number of points, faces, creases and corners. Accessors therefore take and return one array per selected prim rather than a single batched array. All methods that accept an indices parameter operate only on the prims at those positions; when indices is omitted, all wrapped prims are processed. Where a method takes a list of arrays, a single-element list is broadcast to every selected prim.

Public Functions

Mesh(
const std::variant<std::string, std::vector<std::string>> &paths,
const std::optional<std::variant<std::string, std::vector<std::string>>> &primitives = std::nullopt,
const std::optional<ColorType> &colors = std::nullopt,
bool resetXformOpProperties = true,
)#

Construct a Mesh wrapper and optionally configure the initial geometry.

When the prims are created rather than wrapped, primitives selects the geometry generated at each path. Supported names are "Cone", "Cube", "Cylinder", "Disk", "Plane", "Sphere" and "Torus"; a single name is broadcast to every path. The generated primitives are Z-up and are sized to a half extent of 50 cm expressed in stage units. If primitives is omitted, empty meshes are created instead.

Parameters:
  • paths – [in] Single path or list of paths to existing or non-existing (one of both) USD prims. May include regular expressions.

  • primitives – [in] Names of the primitives to generate (shape (N,)). Used only when creating prims; ignored when wrapping existing ones. Optional.

  • colors – [in] Initial display colors. Optional.

  • resetXformOpProperties – [in] Whether to normalize the xformOp stack to translate/orient/scale.

Throws:
  • std::runtime_error – if a wrapped prim is not a USD Mesh.

  • std::invalid_argument – if a primitive name is not supported, or if the number of primitives is neither one nor the number of paths.

~Mesh() = default#
std::vector<size_t> numFaces()#

Get the number of faces of all wrapped meshes.

Returns:

Face counts, as given by the size of each prim’s faceVertexCounts array, one per wrapped prim.

void setPoints(
const std::vector<array::Array> &points,
const std::optional<array::Array> &indices = std::nullopt,
)#

Set the mesh points (in local space) of the selected prims.

Parameters:
  • points – [in] List (shape (N,)) of point arrays (shape (number of points, 3)). Broadcast rules apply.

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

Throws:

std::invalid_argument – if points holds neither one array nor one per selected prim.

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

Get the mesh points (in local space) of the selected prims.

Parameters:

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

Returns:

List (shape (N,)) of point arrays (shape (number of points, 3)).

void setNormals(
const std::vector<array::Array> &normals,
const std::optional<array::Array> &indices = std::nullopt,
)#

Set the mesh normals (object-space orientation for individual points) of the selected prims.

Note

Normals should not be authored on a subdivided USD Mesh, since the subdivision algorithm defines its own normals.

Parameters:
  • normals – [in] List (shape (N,)) of normal arrays (shape (number of normals, 3)). Broadcast rules apply.

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

Throws:

std::invalid_argument – if normals holds neither one array nor one per selected prim.

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

Get the mesh normals (object-space orientation for individual points) of the selected prims.

Parameters:

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

Returns:

List (shape (N,)) of normal arrays (shape (number of normals, 3)).

void setFaceSpecifications(
const std::optional<std::vector<array::Array>> &vertexIndices = std::nullopt,
const std::optional<std::vector<array::Array>> &vertexCounts = std::nullopt,
const std::optional<std::variant<std::string, std::vector<std::string>>> &varyingLinearInterpolations = std::nullopt,
const std::optional<std::vector<array::Array>> &holeIndices = std::nullopt,
const std::optional<array::Array> &indices = std::nullopt,
)#

Set the face (3D model flat surface) specifications of the selected prims.

Parameters:
  • vertexIndices – [in] List (shape (N,)) of point indices for each vertex of each face (shape (sum of all elements of the vertexCounts,)). Optional.

  • vertexCounts – [in] List (shape (N,)) of the number of vertices in each face, which is also the number of consecutive entries in faceVertexIndices that define the face (shape (number of faces,)). Optional.

  • varyingLinearInterpolations – [in] Face-varying interpolation rules in the interior of face-varying regions and at the boundaries for subdivision surfaces (shape (N,)). Optional.

  • holeIndices – [in] List (shape (N,)) of indices of all faces to treat as holes, that is, made invisible (shape (up to the number of faces,)). Optional.

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

Throws:

std::invalid_argument – if none of vertexIndices, vertexCounts, varyingLinearInterpolations and holeIndices is defined.

std::tuple<std::vector<array::Array>, std::vector<array::Array>, std::vector<std::string>, std::vector<array::Array>> getFaceSpecifications(
const std::optional<array::Array> &indices = std::nullopt,
)#

Get the face (3D model flat surface) specifications of the selected prims.

Parameters:

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

Returns:

Four-element tuple. 1) List of point indices for each vertex of each face. 2) List of the number of vertices in each face. 3) List of face-varying interpolation rules. 4) List of indices of all face holes.

void setCreaseSpecifications(
const std::vector<array::Array> &creaseIndices,
const std::vector<array::Array> &creaseLengths,
const std::vector<array::Array> &creaseSharpnesses,
const std::optional<array::Array> &indices = std::nullopt,
)#

Set the crease (set of adjacent sharpened edges) specifications of the selected prims.

Parameters:
  • creaseIndices – [in] List (shape (N,)) of point indices grouped into sets of successive pairs that identify the edges to crease (shape (sum of all elements of the creaseLengths,)). Broadcast rules apply.

  • creaseLengths – [in] List (shape (N,)) of the number of points of each crease, whose indices are successively laid out in creaseIndices (shape (number of creases,)). Since each crease is at least one edge long, every element is at least two. Broadcast rules apply.

  • creaseSharpnesses – [in] List (shape (N,)) of per-crease or per-edge sharpness values (shape (number of creases,) or (sum over all X of (creaseLengths[X] - 1),)). Broadcast rules apply.

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

Throws:

std::invalid_argument – if the sum of the elements of creaseLengths is not equal to the number of elements of creaseIndices, or if the number of elements of creaseSharpnesses matches neither the number of elements of creaseLengths nor the sum over all X of (creaseLengths[X] - 1).

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

Get the crease (set of adjacent sharpened edges) specifications of the selected prims.

Parameters:

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

Returns:

Three-element tuple. 1) List of point indices. 2) List of the number of points of each crease. 3) List of sharpness values.

void setCornerSpecifications(
const std::vector<array::Array> &cornerIndices,
const std::vector<array::Array> &cornerSharpnesses,
const std::optional<array::Array> &indices = std::nullopt,
)#

Set the corner specifications of the selected prims.

Parameters:
  • cornerIndices – [in] List (shape (N,)) of point indices (shape (number of target points,)) for which a corresponding sharpness value is given in cornerSharpnesses. Broadcast rules apply.

  • cornerSharpnesses – [in] List (shape (N,)) of sharpness values (shape (number of target points,)) associated with the points given in cornerIndices. Broadcast rules apply.

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

Throws:

std::invalid_argument – if a pair of items from cornerIndices and cornerSharpnesses has different sizes.

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

Get the corner specifications of the selected prims.

Parameters:

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

Returns:

Two-element tuple. 1) List of point indices. 2) List of sharpness values.

void setSubdivisionSpecifications(
const std::optional<std::variant<std::string, std::vector<std::string>>> &subdivisionSchemes = std::nullopt,
const std::optional<std::variant<std::string, std::vector<std::string>>> &interpolateBoundaries = std::nullopt,
const std::optional<std::variant<std::string, std::vector<std::string>>> &triangleSubdivisionRules = std::nullopt,
const std::optional<array::Array> &indices = std::nullopt,
)#

Set the subdivision specifications of the selected prims.

Parameters:
  • subdivisionSchemes – [in] Subdivision schemes (shape (N,)). Optional.

  • interpolateBoundaries – [in] Boundary interpolation rules for faces adjacent to boundary edges and points (shape (N,)). Optional.

  • triangleSubdivisionRules – [in] Subdivision rules for the Catmull-Clark scheme, used to reduce artifacts when subdividing triangles (shape (N,)). Optional.

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

Throws:

std::invalid_argument – if none of subdivisionSchemes, interpolateBoundaries and triangleSubdivisionRules is defined.

std::tuple<std::vector<std::string>, std::vector<std::string>, std::vector<std::string>> getSubdivisionSpecifications(
const std::optional<array::Array> &indices = std::nullopt,
)#

Get the subdivision specifications of the selected prims.

Parameters:

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

Returns:

Three-element tuple. 1) Subdivision schemes. 2) Boundary interpolation rules. 3) Triangle subdivision rules.

void setDisplayColors(
const ColorType &colors,
const std::optional<array::Array> &indices = std::nullopt,
)#

Set the display colors of the selected prims.

Parameters:
  • colors – [in] Normalized RGB display colors (shape (N,3)) or case-insensitive string representations. Broadcast rules apply.

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

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

Get the display colors of the selected prims.

Parameters:

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

Returns:

Normalized RGB display colors (shape (N,3)).

void updateExtents()#

Update the USD extent attribute of all wrapped mesh prims to match their current points.

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.

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

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.