Loading...
Searching...
No Matches
UsdGeomSubset Class Reference

Encodes a subset of a piece of geometry (i.e. More...

#include <subset.h>

+ Inheritance diagram for UsdGeomSubset:

Public Member Functions

 UsdGeomSubset (const UsdPrim &prim=UsdPrim())
 Construct a UsdGeomSubset on UsdPrim prim .
 
 UsdGeomSubset (const UsdSchemaBase &schemaObj)
 Construct a UsdGeomSubset on the prim held by schemaObj .
 
virtual USDGEOM_API ~UsdGeomSubset ()
 Destructor.
 
USDGEOM_API UsdAttribute GetElementTypeAttr () const
 The type of element that the indices target.
 
USDGEOM_API UsdAttribute CreateElementTypeAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 See GetElementTypeAttr(), and also Create vs Get Property Methods for when to use Get vs Create.
 
USDGEOM_API UsdAttribute GetIndicesAttr () const
 The set of indices included in this subset.
 
USDGEOM_API UsdAttribute CreateIndicesAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 See GetIndicesAttr(), and also Create vs Get Property Methods for when to use Get vs Create.
 
USDGEOM_API UsdAttribute GetFamilyNameAttr () const
 The name of the family of subsets that this subset belongs to.
 
USDGEOM_API UsdAttribute CreateFamilyNameAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 See GetFamilyNameAttr(), and also Create vs Get Property Methods for when to use Get vs Create.
 
- Public Member Functions inherited from UsdTyped
 UsdTyped (const UsdPrim &prim=UsdPrim())
 Construct a UsdTyped on UsdPrim prim .
 
 UsdTyped (const UsdSchemaBase &schemaObj)
 Construct a UsdTyped on the prim held by schemaObj .
 
virtual USD_API ~UsdTyped ()
 Destructor.
 
- Public Member Functions inherited from UsdSchemaBase
bool IsConcrete () const
 Returns whether or not this class corresponds to a concrete instantiable prim type in scene description.
 
bool IsTyped () const
 Returns whether or not this class inherits from UsdTyped.
 
bool IsAPISchema () const
 Returns whether this is an API schema or not.
 
bool IsAppliedAPISchema () const
 Returns whether this is an applied API schema or not.
 
bool IsMultipleApplyAPISchema () const
 Returns whether this is an applied API schema or not.
 
UsdSchemaKind GetSchemaKind () const
 Returns the kind of schema this class is.
 
USD_API UsdSchemaBase (const UsdPrim &prim=UsdPrim())
 Construct and store prim as the held prim.
 
USD_API UsdSchemaBase (const UsdSchemaBase &otherSchema)
 Construct and store for the same prim held by otherSchema.
 
virtual USD_API ~UsdSchemaBase ()
 Destructor.
 
UsdPrim GetPrim () const
 Return this schema object's held prim.
 
SdfPath GetPath () const
 Shorthand for GetPrim()->GetPath().
 
USD_API const UsdPrimDefinitionGetSchemaClassPrimDefinition () const
 Return the prim definition associated with this schema instance if one exists, otherwise return null.
 
USD_API operator bool () const
 Return true if this schema object is compatible with its held prim, false otherwise.
 

Static Public Member Functions

static USDGEOM_API const TfTokenVectorGetSchemaAttributeNames (bool includeInherited=true)
 Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
 
static USDGEOM_API UsdGeomSubset Get (const UsdStagePtr &stage, const SdfPath &path)
 Return a UsdGeomSubset holding the prim adhering to this schema at path on stage.
 
static USDGEOM_API UsdGeomSubset Define (const UsdStagePtr &stage, const SdfPath &path)
 Attempt to ensure a UsdPrim adhering to this schema at path is defined (according to UsdPrim::IsDefined()) on this stage.
 
static USDGEOM_API UsdGeomSubset CreateGeomSubset (const UsdGeomImageable &geom, const TfToken &subsetName, const TfToken &elementType, const VtIntArray &indices, const TfToken &familyName=TfToken(), const TfToken &familyType=TfToken())
 Creates a new GeomSubset below the given geom with the given name, subsetName, element type, elementType and indices.
 
static USDGEOM_API UsdGeomSubset CreateUniqueGeomSubset (const UsdGeomImageable &geom, const TfToken &subsetName, const TfToken &elementType, const VtIntArray &indices, const TfToken &familyName=TfToken(), const TfToken &familyType=TfToken())
 Creates a new GeomSubset below the given imageable, geom with the given name, subsetName, element type, elementType and indices.
 
static USDGEOM_API std::vector< UsdGeomSubsetGetAllGeomSubsets (const UsdGeomImageable &geom)
 Returns all the GeomSubsets defined on the given imageable, geom.
 
static USDGEOM_API std::vector< UsdGeomSubsetGetGeomSubsets (const UsdGeomImageable &geom, const TfToken &elementType=TfToken(), const TfToken &familyName=TfToken())
 Returns all the GeomSubsets of the given elementType belonging to the specified family, familyName on the given imageable, geom.
 
static USDGEOM_API TfToken::Set GetAllGeomSubsetFamilyNames (const UsdGeomImageable &geom)
 Returns the names of all the families of GeomSubsets defined on the given imageable, geom.
 
static USDGEOM_API bool SetFamilyType (const UsdGeomImageable &geom, const TfToken &familyName, const TfToken &familyType)
 This method is used to encode the type of family that the GeomSubsets on the given geometric prim geom, with the given family name, familyName belong to.
 
static USDGEOM_API TfToken GetFamilyType (const UsdGeomImageable &geom, const TfToken &familyName)
 Returns the type of family that the GeomSubsets on the given geometric prim geom, with the given family name, familyName belong to.
 
static USDGEOM_API VtIntArray GetUnassignedIndices (const UsdGeomImageable &geom, const TfToken &elementType, const TfToken &familyName, const UsdTimeCode &time=UsdTimeCode::EarliestTime())
 Utility for getting the list of indices that are not assigned to any of the GeomSubsets in the familyName family on the given geom at the timeCode, time, given the element count (total number of indices in the array being subdivided).
 
static USDGEOM_API VtIntArray GetUnassignedIndices (const std::vector< UsdGeomSubset > &subsets, const size_t elementCount, const UsdTimeCode &time=UsdTimeCode::EarliestTime())
 
static USDGEOM_API bool ValidateSubsets (const std::vector< UsdGeomSubset > &subsets, const size_t elementCount, const TfToken &familyType, std::string *const reason)
 
static USDGEOM_API bool ValidateFamily (const UsdGeomImageable &geom, const TfToken &elementType, const TfToken &familyName, std::string *const reason)
 Validates whether the family of subsets identified by the given familyName and elementType on the given imageable, geom contain valid data.
 
- Static Public Member Functions inherited from UsdTyped
static USD_API const TfTokenVectorGetSchemaAttributeNames (bool includeInherited=true)
 Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
 
static USD_API UsdTyped Get (const UsdStagePtr &stage, const SdfPath &path)
 Return a UsdTyped holding the prim adhering to this schema at path on stage.
 
- Static Public Member Functions inherited from UsdSchemaBase
static const TfTokenVectorGetSchemaAttributeNames (bool includeInherited=true)
 

Static Public Attributes

static const UsdSchemaKind schemaKind = UsdSchemaKind::ConcreteTyped
 Compile time constant representing what kind of schema this class is.
 
- Static Public Attributes inherited from UsdTyped
static const UsdSchemaKind schemaKind = UsdSchemaKind::AbstractBase
 Compile time constant representing what kind of schema this class is.
 
- Static Public Attributes inherited from UsdSchemaBase
static const UsdSchemaKind schemaKind = UsdSchemaKind::AbstractBase
 Compile time constant representing what kind of schema this class is.
 

Protected Member Functions

USDGEOM_API UsdSchemaKind _GetSchemaKind () const override
 Returns the kind of schema this class belongs to.
 
- Protected Member Functions inherited from UsdTyped
USD_API UsdSchemaKind _GetSchemaKind () const override
 Returns the kind of schema this class belongs to.
 
USD_API bool _IsCompatible () const override
 Subclasses may override _IsCompatible to do specific compatibility checking with the given prim, such as type compatibility or value compatibility.
 
- Protected Member Functions inherited from UsdSchemaBase
virtual UsdSchemaKind _GetSchemaType () const
 
const TfType_GetType () const
 
USD_API UsdAttribute _CreateAttr (TfToken const &attrName, SdfValueTypeName const &typeName, bool custom, SdfVariability variability, VtValue const &defaultValue, bool writeSparsely) const
 

Friends

class UsdSchemaRegistry
 

Detailed Description

Encodes a subset of a piece of geometry (i.e.

a UsdGeomImageable) as a set of indices. Currently supports encoding subsets of faces, points, edges, and tetrahedrons.

To apply to a geometric prim, a GeomSubset prim must be the prim's direct child in namespace, and possess a concrete defining specifier (i.e. def). This restriction makes it easy and efficient to discover subsets of a prim. We might want to relax this restriction if it's common to have multiple families of subsets on a gprim and if it's useful to be able to organize subsets belonging to a family under a common scope. See 'familyName' attribute for more info on defining a family of subsets.

Note that a GeomSubset isn't an imageable (i.e. doesn't derive from UsdGeomImageable). So, you can't author visibility for it or override its purpose.

Materials are bound to GeomSubsets just as they are for regular geometry using API available in UsdShade (UsdShadeMaterial::Bind).

For any described attribute Fallback Value or Allowed Values below that are text/tokens, the actual token is published and defined in UsdGeomTokens. So to set an attribute to the value "rightHanded", use UsdGeomTokens->rightHanded as the value.

Definition at line 86 of file subset.h.

Constructor & Destructor Documentation

◆ UsdGeomSubset() [1/2]

UsdGeomSubset ( const UsdPrim prim = UsdPrim())
inlineexplicit

Construct a UsdGeomSubset on UsdPrim prim .

Equivalent to UsdGeomSubset::Get(prim.GetStage(), prim.GetPath()) for a valid prim, but will not immediately throw an error for an invalid prim

Definition at line 98 of file subset.h.

◆ UsdGeomSubset() [2/2]

UsdGeomSubset ( const UsdSchemaBase schemaObj)
inlineexplicit

Construct a UsdGeomSubset on the prim held by schemaObj .

Should be preferred over UsdGeomSubset(schemaObj.GetPrim()), as it preserves SchemaBase state.

Definition at line 106 of file subset.h.

◆ ~UsdGeomSubset()

virtual USDGEOM_API ~UsdGeomSubset ( )
virtual

Destructor.

Member Function Documentation

◆ _GetSchemaKind()

USDGEOM_API UsdSchemaKind _GetSchemaKind ( ) const
overrideprotectedvirtual

Returns the kind of schema this class belongs to.

See also
UsdSchemaKind

Reimplemented from UsdTyped.

◆ CreateElementTypeAttr()

USDGEOM_API UsdAttribute CreateElementTypeAttr ( VtValue const &  defaultValue = VtValue(),
bool  writeSparsely = false 
) const

See GetElementTypeAttr(), and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute's default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

◆ CreateFamilyNameAttr()

USDGEOM_API UsdAttribute CreateFamilyNameAttr ( VtValue const &  defaultValue = VtValue(),
bool  writeSparsely = false 
) const

See GetFamilyNameAttr(), and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute's default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

◆ CreateGeomSubset()

static USDGEOM_API UsdGeomSubset CreateGeomSubset ( const UsdGeomImageable geom,
const TfToken subsetName,
const TfToken elementType,
const VtIntArray &  indices,
const TfToken familyName = TfToken(),
const TfToken familyType = TfToken() 
)
static

Creates a new GeomSubset below the given geom with the given name, subsetName, element type, elementType and indices.

If a subset named subsetName already exists below geom, then this updates its attributes with the values of the provided arguments (indices value at time 'default' will be updated) and returns it.

The family type is set / updated on geom only if a non-empty value is passed in for familyType and familyName.

◆ CreateIndicesAttr()

USDGEOM_API UsdAttribute CreateIndicesAttr ( VtValue const &  defaultValue = VtValue(),
bool  writeSparsely = false 
) const

See GetIndicesAttr(), and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute's default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

◆ CreateUniqueGeomSubset()

static USDGEOM_API UsdGeomSubset CreateUniqueGeomSubset ( const UsdGeomImageable geom,
const TfToken subsetName,
const TfToken elementType,
const VtIntArray &  indices,
const TfToken familyName = TfToken(),
const TfToken familyType = TfToken() 
)
static

Creates a new GeomSubset below the given imageable, geom with the given name, subsetName, element type, elementType and indices.

If a subset named subsetName already exists below geom, then this creates a new subset by appending a suitable index as suffix to subsetName (eg, subsetName_1) to avoid name collisions.

The family type is set / updated on geom only if a non-empty value is passed in for familyType and familyName.

◆ Define()

static USDGEOM_API UsdGeomSubset Define ( const UsdStagePtr &  stage,
const SdfPath path 
)
static

Attempt to ensure a UsdPrim adhering to this schema at path is defined (according to UsdPrim::IsDefined()) on this stage.

If a prim adhering to this schema at path is already defined on this stage, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and this schema's prim type name for the prim at path at the current EditTarget. Author SdfPrimSpec s with specifier == SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.

The given path must be an absolute prim path that does not contain any variant selections.

If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget's namespace) issue an error and return an invalid UsdPrim.

Note that this method may return a defined prim whose typeName does not specify this schema class, in case a stronger typeName opinion overrides the opinion at the current EditTarget.

◆ Get()

static USDGEOM_API UsdGeomSubset Get ( const UsdStagePtr &  stage,
const SdfPath path 
)
static

Return a UsdGeomSubset holding the prim adhering to this schema at path on stage.

If no prim exists at path on stage, or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:

UsdGeomSubset(stage->GetPrimAtPath(path));
Encodes a subset of a piece of geometry (i.e.
Definition: subset.h:87

◆ GetAllGeomSubsetFamilyNames()

static USDGEOM_API TfToken::Set GetAllGeomSubsetFamilyNames ( const UsdGeomImageable geom)
static

Returns the names of all the families of GeomSubsets defined on the given imageable, geom.

◆ GetAllGeomSubsets()

static USDGEOM_API std::vector< UsdGeomSubset > GetAllGeomSubsets ( const UsdGeomImageable geom)
static

Returns all the GeomSubsets defined on the given imageable, geom.

◆ GetElementTypeAttr()

USDGEOM_API UsdAttribute GetElementTypeAttr ( ) const

The type of element that the indices target.

"elementType" can have one of the following values:

  • face: Identifies faces on a Gprim's surface. For a UsdGeomMesh, each element of the indices attribute would refer to an element of the Mesh's faceCounts attribute. For a UsdGeomTetMesh, each element of the indices attribute would refer to an element of the Mesh's surfaceFaceVertexIndices attribute.
  • point: for any UsdGeomPointBased, each element of the indices attribute would refer to an element of the Mesh's points attribute
  • edge: for any UsdGeomMesh, each pair of elements in the indices attribute would refer to a pair of points of the Mesh's points attribute that are connected as an implicit edge on the Mesh. These edges are derived from the Mesh's faceVertexIndices attribute. Edges are not currently defined for a UsdGeomTetMesh, but could be derived from all tetrahedron edges or surface face edges only if a specific use-case arises.
  • tetrahedron: for any UsdGeomTetMesh, each element of the indices attribute would refer to an element of the TetMesh's tetVertexIndices attribute.
Declaration uniform token elementType = "face"
C++ Type TfToken
Usd Type SdfValueTypeNames->Token
Variability SdfVariabilityUniform
Allowed Values face, point, edge, tetrahedron

◆ GetFamilyNameAttr()

USDGEOM_API UsdAttribute GetFamilyNameAttr ( ) const

The name of the family of subsets that this subset belongs to.

This is optional and is primarily useful when there are multiple families of subsets under a geometric prim. In some cases, this could also be used for achieving proper roundtripping of subset data between DCC apps. When multiple subsets belonging to a prim have the same familyName, they are said to belong to the family. A familyType value can be encoded on the owner of a family of subsets as a token using the static method UsdGeomSubset::SetFamilyType(). "familyType" can have one of the following values:

  • UsdGeomTokens->partition: implies that every element of the whole geometry appears exactly once in only one of the subsets belonging to the family.
  • UsdGeomTokens->nonOverlapping: an element that appears in one subset may not appear in any other subset belonging to the family, and appears only once in the subset in which it appears.
  • UsdGeomTokens->unrestricted: implies that there are no restrictions w.r.t. the membership of elements in the subsets. They could be overlapping and the union of all subsets in the family may not represent the whole.
Note
The validity of subset data is not enforced by the authoring APIs, however they can be checked using UsdGeomSubset::ValidateFamily().
Declaration uniform token familyName = ""
C++ Type TfToken
Usd Type SdfValueTypeNames->Token
Variability SdfVariabilityUniform

◆ GetFamilyType()

static USDGEOM_API TfToken GetFamilyType ( const UsdGeomImageable geom,
const TfToken familyName 
)
static

Returns the type of family that the GeomSubsets on the given geometric prim geom, with the given family name, familyName belong to.

This only returns the token that's encoded on geom and does not perform any actual validation on the family of GeomSubsets. Please use ValidateFamily() for such validation.

When familyType is not set on geom, the fallback value UsdTokens->unrestricted is returned.

◆ GetGeomSubsets()

static USDGEOM_API std::vector< UsdGeomSubset > GetGeomSubsets ( const UsdGeomImageable geom,
const TfToken elementType = TfToken(),
const TfToken familyName = TfToken() 
)
static

Returns all the GeomSubsets of the given elementType belonging to the specified family, familyName on the given imageable, geom.

If elementType is empty, then subsets containing all element types are returned. If familyName is left empty, then all subsets of the specified elementType will be returned.

◆ GetIndicesAttr()

USDGEOM_API UsdAttribute GetIndicesAttr ( ) const

The set of indices included in this subset.

The indices need not be sorted, but the same index should not appear more than once. Indices are invalid if outside the range [0, elementCount) for the given time on the parent geometric prim.

Declaration int[] indices = []
C++ Type VtArray<int>
Usd Type SdfValueTypeNames->IntArray

◆ GetSchemaAttributeNames()

static USDGEOM_API const TfTokenVector & GetSchemaAttributeNames ( bool  includeInherited = true)
static

Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.

Does not include attributes that may be authored by custom/extended methods of the schemas involved.

◆ GetUnassignedIndices() [1/2]

static USDGEOM_API VtIntArray GetUnassignedIndices ( const std::vector< UsdGeomSubset > &  subsets,
const size_t  elementCount,
const UsdTimeCode time = UsdTimeCode::EarliestTime() 
)
static
Deprecated:
Please use GetUnassignedIndices(geom, elementType, familyName, time) instead. Utility for getting the list of indices that are not assigned to any of the GeomSubsets in subsets at the timeCode, time, given the element count (total number of indices in the array being subdivided), elementCount.

◆ GetUnassignedIndices() [2/2]

static USDGEOM_API VtIntArray GetUnassignedIndices ( const UsdGeomImageable geom,
const TfToken elementType,
const TfToken familyName,
const UsdTimeCode time = UsdTimeCode::EarliestTime() 
)
static

Utility for getting the list of indices that are not assigned to any of the GeomSubsets in the familyName family on the given geom at the timeCode, time, given the element count (total number of indices in the array being subdivided).

For elementType UsdGeomTokens->edge, the output array of indices should be interpreted in pairs, as each sequential pair of indices corresponds to an edge between the two points. Each edge will be in the order (lowIndex, highIndex).

If the elementType is not applicable to the given geom, an empty array is returned and a coding error is issued.

◆ SetFamilyType()

static USDGEOM_API bool SetFamilyType ( const UsdGeomImageable geom,
const TfToken familyName,
const TfToken familyType 
)
static

This method is used to encode the type of family that the GeomSubsets on the given geometric prim geom, with the given family name, familyName belong to.

See UsdGeomSubset::GetFamilyNameAttr for the possible values for familyType.

When a family of GeomSubsets is tagged as a UsdGeomTokens->partition or UsdGeomTokens->nonOverlapping, the validity of the data (i.e. mutual exclusivity and/or wholeness) is not enforced by the authoring APIs. Use ValidateFamily() to validate the data in a family of GeomSubsets.

Returns
Returns false upon failure to create or set the appropriate attribute on geom.

◆ ValidateFamily()

static USDGEOM_API bool ValidateFamily ( const UsdGeomImageable geom,
const TfToken elementType,
const TfToken familyName,
std::string *const  reason 
)
static

Validates whether the family of subsets identified by the given familyName and elementType on the given imageable, geom contain valid data.

If the family is designated as a partition or as non-overlapping using SetFamilyType(), then the validity of the data is checked. If the familyType is "unrestricted", then this performs only bounds checking of the values in the "indices" arrays.

If reason is not NULL, then it is populated with a string explaining why the family is invalid, if it is invalid.

The python version of this method returns a tuple containing a (bool, string), where the bool has the validity of the family and the string contains the reason (if it's invalid).

◆ ValidateSubsets()

static USDGEOM_API bool ValidateSubsets ( const std::vector< UsdGeomSubset > &  subsets,
const size_t  elementCount,
const TfToken familyType,
std::string *const  reason 
)
static
Deprecated:
Please use UsdGeomSubset::ValidateFamily instead. Validates the data in the given set of GeomSubsets, subsets, given the total number of elements in the array being subdivided, elementCount and the familyType that the subsets belong to.

For proper validation of indices in subsets, all of the GeomSubsets must have the same 'elementType'.

If one or more subsets contain invalid data, then false is returned and reason is populated with a string explaining the reason why it is invalid.

The python version of this method returns a tuple containing a (bool, string), where the bool has the validity of the subsets and the string contains the reason (if they're invalid).

Friends And Related Function Documentation

◆ UsdSchemaRegistry

friend class UsdSchemaRegistry
friend

Definition at line 170 of file subset.h.

Member Data Documentation

◆ schemaKind

const UsdSchemaKind schemaKind = UsdSchemaKind::ConcreteTyped
static

Compile time constant representing what kind of schema this class is.

See also
UsdSchemaKind

Definition at line 92 of file subset.h.


The documentation for this class was generated from the following file: