This document is for a version of USD that is under development. See this page for the current release.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
Encoding Stage Linear Units

As with Encoding Stage UpAxis, we restrict the encoding of linear units to be stage-wide; if assembling assets of different metrics, it is the assembler's responsibility to apply suitable correctives to the referenced data to bring it into the referencing stage's metric. More...

Classes

class  UsdGeomLinearUnits
 Container class for static double-precision symbols representing common units of measure expressed in meters. More...
 

Functions

USDGEOM_API double UsdGeomGetStageMetersPerUnit (const UsdStageWeakPtr &stage)
 Return stage's authored metersPerUnit, or 0.01 if unauthored.
 
USDGEOM_API bool UsdGeomStageHasAuthoredMetersPerUnit (const UsdStageWeakPtr &stage)
 Return whether stage has an authored metersPerUnit.
 
USDGEOM_API bool UsdGeomSetStageMetersPerUnit (const UsdStageWeakPtr &stage, double metersPerUnit)
 Author stage's metersPerUnit.
 
USDGEOM_API bool UsdGeomLinearUnitsAre (double authoredUnits, double standardUnits, double epsilon=1e-5)
 Return true if the two given metrics are within the provided relative epsilon of each other, when you need to know an absolute metric rather than a scaling factor.
 

Detailed Description

As with Encoding Stage UpAxis, we restrict the encoding of linear units to be stage-wide; if assembling assets of different metrics, it is the assembler's responsibility to apply suitable correctives to the referenced data to bring it into the referencing stage's metric.

We encode linear measure as meters per unit (stage-level metadata metersPerUnit) rather than units-per-meter because it makes it easier to encode precise imperial units (one imperial foot = 0.3048 meters exactly).

If a UsdStage has no authored metersPerUnit we fall back to the value UsdGeomLinearUnits::centimeters, i.e. 0.01.

The specified metersPerUnit metric should only be applied to world space (i.e. fully transformed) attributes of types:

It may be tempting to interpret raw attribute values, and even xformOp:translate values in the metersPerUnit metric, but because any xformOp:scale transformations will change the metric of the authored attribute, and in fact we require this sort of scale change when referencing assets of differing metrics, it is unreliable to do so.

Function Documentation

◆ UsdGeomGetStageMetersPerUnit()

USDGEOM_API double UsdGeomGetStageMetersPerUnit ( const UsdStageWeakPtr &  stage)

Return stage's authored metersPerUnit, or 0.01 if unauthored.

See also
Encoding Stage Linear Units

◆ UsdGeomLinearUnitsAre()

USDGEOM_API bool UsdGeomLinearUnitsAre ( double  authoredUnits,
double  standardUnits,
double  epsilon = 1e-5 
)

Return true if the two given metrics are within the provided relative epsilon of each other, when you need to know an absolute metric rather than a scaling factor.


Use like so:

double stageUnits = UsdGeomGetStageMetersPerUnit(stage);
if (UsdGeomLinearUnitsAre(stageUnits, UsdGeomLinearUnits::meters))
// do something for meters
else if (UsdGeomLinearUnitsAre(stageUnits, UsdGeomLinearUnits::feet))
// do something for feet
USDGEOM_API bool UsdGeomLinearUnitsAre(double authoredUnits, double standardUnits, double epsilon=1e-5)
Return true if the two given metrics are within the provided relative epsilon of each other,...
USDGEOM_API double UsdGeomGetStageMetersPerUnit(const UsdStageWeakPtr &stage)
Return stage's authored metersPerUnit, or 0.01 if unauthored.
Returns
false if either input is zero or negative, otherwise relative floating-point comparison between the two inputs.
See also
Encoding Stage Linear Units

◆ UsdGeomSetStageMetersPerUnit()

USDGEOM_API bool UsdGeomSetStageMetersPerUnit ( const UsdStageWeakPtr &  stage,
double  metersPerUnit 
)

Author stage's metersPerUnit.

Returns
true if metersPerUnit was successfully set. The stage's UsdEditTarget must be either its root layer or session layer.
See also
Encoding Stage Linear Units

◆ UsdGeomStageHasAuthoredMetersPerUnit()

USDGEOM_API bool UsdGeomStageHasAuthoredMetersPerUnit ( const UsdStageWeakPtr &  stage)

Return whether stage has an authored metersPerUnit.

See also
Encoding Stage Linear Units