|
HDK
|
Functions | |
| USDGEOM_API TfToken | UsdGeomGetStageUpAxis (const UsdStageWeakPtr &stage) |
| USDGEOM_API bool | UsdGeomSetStageUpAxis (const UsdStageWeakPtr &stage, const TfToken &axis) |
| USDGEOM_API TfToken | UsdGeomGetFallbackUpAxis () |
Even if all UsdGeomCamera objects in a scene are encoded with a transformation that assumes the Y axis is up, that cannot always imply that the geometry contained in the scene was modeled with the Y axis pointing up, since some modeling applications assume Z is up, and others allow you to configure whether Y or Z is up. Rather than impose one axis or the other on all UsdGeom scenes - which would require either transposing point coordinates into and out of some applications, or making assumptions about where a -90 degree rotation has been applied and effectively, mysteriously swapping the roles of Y and Z coordinates - we allow each stage to carry, in its root layer, a declaration of the up axis for all the geometry contained in the stage, and require applications to consult it if they wish to create new cameras to view the scene in its intended orientation.
Note that because you can make only a Stage-level declaration of up axis, it must hold true for all referenced geometry and assets. A conscientious set/environment-construction tool could examine the up axis of referenced assets as they are being referenced, and apply a corrective rotation on the referencing prim as it is being added to the scene, when the referenced up axis differs from the set's.
We provide free functions for setting (UsdGeomSetStageUpAxis()), retrieving (UsdGeomGetStageUpAxis()), and declaring a site-level fallback up axis (UsdGeomGetFallbackUpAxis()) that can be configured with a PlugPlugin plugInfo.json file. See the individual methods for details.
The stage up axis is encoded as stage metadatum upAxis, whose legal values are "Y" and "Z", as represented by UsdGeomTokens->y and UsdGeomTokens->z. Of course, constructing a correct camera view of a scene depends not only on the up axis, but also on the handedness of the coordinate system. Like OpenGL and the fallback for UsdGeomGprim::GetOrientationAttr(), UsdGeom stipulates a right-handed coordinate system. Therefore, when viewing a UsdStage with a "Y" up axis, the stage's Z axis will be pointing out of the screen, and when viewing a UsdStage with a "Z" up axis, the stage's Y axis will be pointing into the screen.
| USDGEOM_API TfToken UsdGeomGetFallbackUpAxis | ( | ) |
Return the site-level fallback up axis as a TfToken.
In a generic installation of USD, the fallback will be "Y". This can be changed to "Z" by adding, in a plugInfo.json file discoverable by USD's PlugPlugin mechanism:
If more than one such entry is discovered and the values for upAxis differ, we will issue a warning during the first call to this function, and ignore all of them, so that we devolve to deterministic behavior of Y up axis until the problem is rectified.
| USDGEOM_API TfToken UsdGeomGetStageUpAxis | ( | const UsdStageWeakPtr & | stage | ) |
Fetch and return stage 's upAxis. If unauthored, will return the value provided by UsdGeomGetFallbackUpAxis(). Exporters, however, are strongly encouraged to always set the upAxis for every USD file they create.
| USDGEOM_API bool UsdGeomSetStageUpAxis | ( | const UsdStageWeakPtr & | stage, |
| const TfToken & | axis | ||
| ) |
Set stage 's upAxis to axis, which must be one of UsdGeomTokens->y or UsdGeomTokens->z
UpAxis is stage-level metadata, therefore see UsdStage::SetMetadata().
1.8.6 
