Encoding Stage Linear Units

Classes
class	UsdGeomLinearUnits

Functions
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:

• point3{h,f,d} (and Arrays thereof)
• vector3{h,f,d} (and Arrays thereof)
• schema attributes that define a length, such as Sphere.radius and Boundable.extent

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);

if (UsdGeomLinearUnitsAre(stageUnits, UsdGeomLinearUnits::meters))
    // do something for meters
else if (UsdGeomLinearUnitsAre(stageUnits, UsdGeomLinearUnits::feet))
    // do something for feet

Returns

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.

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

USDGEOM_API bool UsdGeomStageHasAuthoredMetersPerUnit

(

const UsdStageWeakPtr &

stage

)

Return whether stage has an authored metersPerUnit.

See Also

Encoding Stage Linear Units