All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Encoding Stage Linear Units


class  UsdGeomLinearUnits


USDGEOM_API double UsdGeomGetStageMetersPerUnit (const UsdStageWeakPtr &stage)
USDGEOM_API bool UsdGeomStageHasAuthoredMetersPerUnit (const UsdStageWeakPtr &stage)
USDGEOM_API bool UsdGeomSetStageMetersPerUnit (const UsdStageWeakPtr &stage, double metersPerUnit)
USDGEOM_API bool UsdGeomLinearUnitsAre (double authoredUnits, double standardUnits, double epsilon=1e-5)

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

USDGEOM_API double UsdGeomGetStageMetersPerUnit ( const UsdStageWeakPtr stage)

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

See Also
Encoding Stage Linear Units
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);
// do something for meters
// do something for feet
false if either input is zero or negative, otherwise relative floating-point comparison between the two inputs.
See Also
Encoding Stage Linear Units
USDGEOM_API bool UsdGeomSetStageMetersPerUnit ( const UsdStageWeakPtr stage,
double  metersPerUnit 

Author stage's metersPerUnit.

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
USDGEOM_API bool UsdGeomStageHasAuthoredMetersPerUnit ( const UsdStageWeakPtr stage)

Return whether stage has an authored metersPerUnit.

See Also
Encoding Stage Linear Units