Mesh Prims#

Utility functions to create polygonal UsdGeomMesh Prims.

See UsdGeomMesh for details.

Functions Summary#

Vec3fPrimvarData usdex::core::computeMeshNormals(pxr::UsdGeomMesh mesh, const pxr::TfToken &interpolation=pxr::UsdGeomTokens->uniform, const pxr::GfVec3f &fallback=pxr::GfVec3f(0.0f, 0.0f, 1.0f))

Computes mesh normals and updates the mesh with the computed normals.

Vec3fPrimvarData usdex::core::computeMeshNormals(const pxr::VtIntArray &faceVertexCounts, const pxr::VtIntArray &faceVertexIndices, const pxr::VtVec3fArray &points, const pxr::TfToken &interpolation=pxr::UsdGeomTokens->uniform, const pxr::GfVec3f &fallback=pxr::GfVec3f(0.0f, 0.0f, 1.0f))

Computes mesh normals for a given mesh topology.

std::vector< pxr::UsdGeomSubset > usdex::core::defineNonOverlappingSubsets(pxr::UsdGeomMesh mesh, const std::vector< pxr::TfToken > &names, const std::vector< pxr::VtIntArray > &indices, const pxr::TfToken &elementType=pxr::UsdGeomTokens->face, const pxr::TfToken &familyName=pxr::UsdShadeTokens->materialBind)

Partially partitions a geometry prim into multiple disjoint subsets.

std::vector< pxr::UsdGeomSubset > usdex::core::definePartitionedSubsets(pxr::UsdGeomMesh mesh, const std::vector< pxr::TfToken > &names, const std::vector< pxr::VtIntArray > &indices, const pxr::TfToken &elementType=pxr::UsdGeomTokens->face, const pxr::TfToken &familyName=pxr::UsdShadeTokens->materialBind)

Fully partitions a geometry prim into multiple disjoint subsets.

pxr::UsdGeomMesh usdex::core::definePolyMesh(pxr::UsdPrim parent, const std::string &name, const pxr::VtIntArray &faceVertexCounts, const pxr::VtIntArray &faceVertexIndices, const pxr::VtVec3fArray &points, std::optional< const Vec3fPrimvarData > normals=std::nullopt, std::optional< const Vec2fPrimvarData > uvs=std::nullopt, std::optional< const Vec3fPrimvarData > displayColor=std::nullopt, std::optional< const FloatPrimvarData > displayOpacity=std::nullopt)

Defines a basic polygon mesh on the stage.

pxr::UsdGeomMesh usdex::core::definePolyMesh(pxr::UsdPrim prim, const pxr::VtIntArray &faceVertexCounts, const pxr::VtIntArray &faceVertexIndices, const pxr::VtVec3fArray &points, std::optional< const Vec3fPrimvarData > normals=std::nullopt, std::optional< const Vec2fPrimvarData > uvs=std::nullopt, std::optional< const Vec3fPrimvarData > displayColor=std::nullopt, std::optional< const FloatPrimvarData > displayOpacity=std::nullopt)

Defines a basic polygon mesh from an existing prim.

pxr::UsdGeomMesh usdex::core::definePolyMesh(pxr::UsdStagePtr stage, const pxr::SdfPath &path, const pxr::VtIntArray &faceVertexCounts, const pxr::VtIntArray &faceVertexIndices, const pxr::VtVec3fArray &points, std::optional< const Vec3fPrimvarData > normals=std::nullopt, std::optional< const Vec2fPrimvarData > uvs=std::nullopt, std::optional< const Vec3fPrimvarData > displayColor=std::nullopt, std::optional< const FloatPrimvarData > displayOpacity=std::nullopt)

Defines a basic polygon mesh on the stage.

std::vector< pxr::UsdGeomSubset > usdex::core::defineUnrestrictedSubsets(pxr::UsdGeomMesh mesh, const std::vector< pxr::TfToken > &names, const std::vector< pxr::VtIntArray > &indices, const pxr::TfToken &elementType=pxr::UsdGeomTokens->face, const pxr::TfToken &familyName=pxr::UsdShadeTokens->materialBind)

Partially partitions a geometry prim into multiple, possibly overlapping, subsets.

Functions#

Vec3fPrimvarData usdex::core::computeMeshNormals(
pxr::UsdGeomMesh mesh,
const pxr::TfToken &interpolation = pxr::UsdGeomTokens->uniform,
const pxr::GfVec3f &fallback = pxr::GfVec3f(0.0f, 0.0f, 1.0f),
)#

Computes mesh normals and updates the mesh with the computed normals.

This is an overloaded member function, provided for convenience.

Parameters:

  • mesh – Mesh prim

  • interpolation – The desired interpolation type for the computed normals

  • fallback – The fallback normal to use for degenerate faces and vertices with no contributing faces

Returns:

Vec3fPrimvarData containing the computed normals, or an invalid one if computation fails.

Vec3fPrimvarData usdex::core::computeMeshNormals(
const pxr::VtIntArray &faceVertexCounts,
const pxr::VtIntArray &faceVertexIndices,
const pxr::VtVec3fArray &points,
const pxr::TfToken &interpolation = pxr::UsdGeomTokens->uniform,
const pxr::GfVec3f &fallback = pxr::GfVec3f(0.0f, 0.0f, 1.0f),
)#

Computes mesh normals for a given mesh topology.

This function computes normals for mesh geometry using vector-area approach for face normals and area-weighted averaging for vertex normals. The computation supports uniform, vertex, and faceVarying interpolations to match USD’s primvar interpolation types. FaceVarying normals are a simplified approach that assigns the same face normal to all corners of each face.

Normal computation assumes right-handed mesh orientation. The winding order of the data should be reversed in advance if that is not the case.

Degenerate faces (with zero area) and vertices with no contributing faces are assigned the fallback normal.

Note

This function is designed primarily to resolve USD validation issues for meshes that lack normals data. For production-quality rendering with sharp edges or complex shading requirements, consider using specialized mesh processing libraries that provide full edge connectivity analysis and advanced normal computation algorithms.

Parameters:

  • faceVertexCounts – The number of vertices in each face of the mesh

  • faceVertexIndices – Indices of the positions from the points to use for each face vertex

  • points – Vertex positions for the mesh described in local space

  • interpolation – The desired interpolation type for the computed normals

  • fallback – The fallback normal to use for degenerate faces and vertices with no contributing faces

Returns:

Vec3fPrimvarData containing the computed normals, or an invalid one if computation fails.

std::vector<pxr::UsdGeomSubset> usdex::core::defineNonOverlappingSubsets(
pxr::UsdGeomMesh mesh,
const std::vector<pxr::TfToken> &names,
const std::vector<pxr::VtIntArray> &indices,
const pxr::TfToken &elementType = pxr::UsdGeomTokens->face,
const pxr::TfToken &familyName = pxr::UsdShadeTokens->materialBind,
)#

Partially partitions a geometry prim into multiple disjoint subsets.

An element may appear in at most one subset in this family, and at most once within that subset. The union of all subsets need not cover the whole geometry (some elements may be unassigned). Use when subsets must not overlap but need not cover the entire geometry.

The prim must be a geometry that supports subsets (e.g. UsdGeomMesh from usdex::core::definePolyMesh). Use usdex::core::bindMaterial to bind materials to each subset.

elementType defaults to UsdGeomTokens->face. See UsdGeomSubset for details.

familyName defaults to UsdShadeTokens->materialBind. See UsdGeomSubset for details.

Parameters:

  • mesh – Mesh prim to add the subsets to

  • names – The names of the subsets (size must equal indices.size())

  • indices – Per-subset element indices; indices.size() is the number of subsets, indices[i] is the index list for subset i

  • elementType – The element type of the subsets. Valid values are UsdGeomTokens->face, UsdGeomTokens->edge, and UsdGeomTokens->point.

  • familyName – The family name of the subsets

Returns:

The subsets created

std::vector<pxr::UsdGeomSubset> usdex::core::definePartitionedSubsets(
pxr::UsdGeomMesh mesh,
const std::vector<pxr::TfToken> &names,
const std::vector<pxr::VtIntArray> &indices,
const pxr::TfToken &elementType = pxr::UsdGeomTokens->face,
const pxr::TfToken &familyName = pxr::UsdShadeTokens->materialBind,
)#

Fully partitions a geometry prim into multiple disjoint subsets.

Every element of the geometry must appear in exactly one subset in this family, with no element appearing in more than one subset, and no element left unassigned.

The prim must be a geometry that supports subsets (e.g. UsdGeomMesh from usdex::core::definePolyMesh). Use usdex::core::bindMaterial to bind materials to each subset.

elementType defaults to UsdGeomTokens->face. See UsdGeomSubset for details.

familyName defaults to UsdShadeTokens->materialBind. See UsdGeomSubset for details.

Parameters:

  • mesh – Mesh prim to add the subsets to

  • names – The names of the subsets (size must equal indices.size())

  • indices – Per-subset element indices; indices.size() is the number of subsets, indices[i] is the index list for subset i

  • elementType – The element type of the subsets. Valid values are UsdGeomTokens->face, UsdGeomTokens->edge, and UsdGeomTokens->point.

  • familyName – The family name of the subsets

Returns:

The subsets created

pxr::UsdGeomMesh usdex::core::definePolyMesh(
pxr::UsdPrim parent,
const std::string &name,
const pxr::VtIntArray &faceVertexCounts,
const pxr::VtIntArray &faceVertexIndices,
const pxr::VtVec3fArray &points,
std::optional<const Vec3fPrimvarData> normals = std::nullopt,
std::optional<const Vec2fPrimvarData> uvs = std::nullopt,
std::optional<const Vec3fPrimvarData> displayColor = std::nullopt,
std::optional<const FloatPrimvarData> displayOpacity = std::nullopt,
)#

Defines a basic polygon mesh on the stage.

This is an overloaded member function, provided for convenience. It differs from the above function only in what arguments it accepts.

Parameters:

  • parent – Prim below which to define the mesh

  • name – Name of the mesh

  • faceVertexCounts – The number of vertices in each face of the mesh

  • faceVertexIndices – Indices of the positions from the points to use for each face vertex

  • points – Vertex positions for the mesh described in local space

  • normals – Values to be authored for the normals primvar

  • uvs – Values to be authored for the uv primvar

  • displayColor – Values to be authored for the display color primvar

  • displayOpacity – Values to be authored for the display opacity primvar

Returns:

UsdGeomMesh schema wrapping the defined UsdPrim

pxr::UsdGeomMesh usdex::core::definePolyMesh(
pxr::UsdPrim prim,
const pxr::VtIntArray &faceVertexCounts,
const pxr::VtIntArray &faceVertexIndices,
const pxr::VtVec3fArray &points,
std::optional<const Vec3fPrimvarData> normals = std::nullopt,
std::optional<const Vec2fPrimvarData> uvs = std::nullopt,
std::optional<const Vec3fPrimvarData> displayColor = std::nullopt,
std::optional<const FloatPrimvarData> displayOpacity = std::nullopt,
)#

Defines a basic polygon mesh from an existing prim.

This converts an existing prim to a Mesh type, preserving any existing transform data.

Parameters:

  • prim – The existing prim to convert to a mesh

  • faceVertexCounts – The number of vertices in each face of the mesh

  • faceVertexIndices – Indices of the positions from the points to use for each face vertex

  • points – Vertex positions for the mesh described in local space

  • normals – Values to be authored for the normals primvar

  • uvs – Values to be authored for the uv primvar

  • displayColor – Values to be authored for the display color primvar

  • displayOpacity – Values to be authored for the display opacity primvar

Returns:

UsdGeomMesh schema wrapping the converted UsdPrim

pxr::UsdGeomMesh usdex::core::definePolyMesh(
pxr::UsdStagePtr stage,
const pxr::SdfPath &path,
const pxr::VtIntArray &faceVertexCounts,
const pxr::VtIntArray &faceVertexIndices,
const pxr::VtVec3fArray &points,
std::optional<const Vec3fPrimvarData> normals = std::nullopt,
std::optional<const Vec2fPrimvarData> uvs = std::nullopt,
std::optional<const Vec3fPrimvarData> displayColor = std::nullopt,
std::optional<const FloatPrimvarData> displayOpacity = std::nullopt,
)#

Defines a basic polygon mesh on the stage.

Attribute values will be validated and in the case of invalid data the Mesh will not be defined. An invalid UsdGeomMesh object will be returned in this case.

A “Subdivision Scheme” of “None” is authored to ensure that the Mesh is not treated as a subdivision surface. For this reason there is no support for authoring subdivision surface attributes during definition.

Values will be authored for all attributes required to completely describe the Mesh, even if weaker matching opinions already exist.

  • Face Vertex Counts

  • Face Vertex Indices

  • Points

  • Extent

The orientation of the Mesh is assumed to be “Right Handed”. The winding order of the data should be reversed in advance if that is not the case.

The “extent” of the Mesh will be computed and authored based on the points provided.

The following common primvars can optionally be authored at the same time using a PrimvarData to specify interpolation, data, and optionally indices or elementSize.

  • Normals

  • Primary UV Set

  • Display Color

  • Display Opacity

Normals are authored as primvars:normals so that indexing is possible and to ensure that the value takes precedence in cases where both normals and primvars:normals are authored. See UsdGeomPointBased for details.

The primary uv set will be named based on the result of UsdUtilsGetPrimaryUVSetName(). By default the name is “st” but can be configured by extension. See UsdUtils Pipeline for details.

Parameters:

  • stage – The stage on which to define the mesh

  • path – The absolute prim path at which to define the mesh

  • faceVertexCounts – The number of vertices in each face of the mesh

  • faceVertexIndices – Indices of the positions from the points to use for each face vertex

  • points – Vertex positions for the mesh described in local space

  • normals – Values to be authored for the normals primvar

  • uvs – Values to be authored for the uv primvar

  • displayColor – Values to be authored for the display color primvar

  • displayOpacity – Values to be authored for the display opacity primvar

Returns:

UsdGeomMesh schema wrapping the defined UsdPrim

std::vector<pxr::UsdGeomSubset> usdex::core::defineUnrestrictedSubsets(
pxr::UsdGeomMesh mesh,
const std::vector<pxr::TfToken> &names,
const std::vector<pxr::VtIntArray> &indices,
const pxr::TfToken &elementType = pxr::UsdGeomTokens->face,
const pxr::TfToken &familyName = pxr::UsdShadeTokens->materialBind,
)#

Partially partitions a geometry prim into multiple, possibly overlapping, subsets.

No restrictions: elements may appear in multiple subsets, and the union of all subsets need not represent the whole geometry. Use when overlapping or partial subsets are needed.

The prim must be a geometry that supports subsets (e.g. UsdGeomMesh from usdex::core::definePolyMesh). Use usdex::core::bindMaterial to bind materials to each subset.

elementType defaults to UsdGeomTokens->face. See UsdGeomSubset for details.

familyName defaults to UsdShadeTokens->materialBind. See UsdGeomSubset for details.

Parameters:

  • mesh – Mesh prim to add the subsets to

  • names – The names of the subsets (size must equal indices.size())

  • indices – Per-subset element indices; indices.size() is the number of subsets, indices[i] is the index list for subset i

  • elementType – The element type of the subsets. Valid values are UsdGeomTokens->face, UsdGeomTokens->edge, and UsdGeomTokens->point.

  • familyName – The family name of the subsets

Returns:

The subsets created