HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
metrics.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the Apache License, Version 2.0 (the "Apache License")
5 // with the following modification; you may not use this file except in
6 // compliance with the Apache License and the following modification to it:
7 // Section 6. Trademarks. is deleted and replaced with:
8 //
9 // 6. Trademarks. This License does not grant permission to use the trade
10 // names, trademarks, service marks, or product names of the Licensor
11 // and its affiliates, except as required to comply with Section 4(c) of
12 // the License and to reproduce the content of the NOTICE file.
13 //
14 // You may obtain a copy of the Apache License at
15 //
16 // http://www.apache.org/licenses/LICENSE-2.0
17 //
18 // Unless required by applicable law or agreed to in writing, software
19 // distributed under the Apache License with the above modification is
20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21 // KIND, either express or implied. See the Apache License for the specific
22 // language governing permissions and limitations under the Apache License.
23 //
24 #ifndef PXR_USD_USD_GEOM_METRICS_H
25 #define PXR_USD_USD_GEOM_METRICS_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/usd/usdGeom/api.h"
29 #include "pxr/base/tf/token.h"
30 #include "pxr/usd/usd/common.h"
31 
33 
34 
35 /// \file usdGeom/metrics.h
36 ///
37 /// Schema and utilities for encoding various spatial and geometric metrics of
38 /// a UsdStage and its contents.
39 ///
40 /// \defgroup UsdGeomUpAxis_group Encoding Stage UpAxis
41 ///
42 /// Even if all UsdGeomCamera objects in a scene are encoded with a
43 /// transformation that assumes the Y axis is up, that cannot always imply
44 /// that the geometry contained in the scene was modeled with the Y axis
45 /// pointing up, since some modeling applications assume Z is up, and others
46 /// allow you to configure whether Y or Z is up. Rather than impose one axis
47 /// or the other on all UsdGeom scenes - which would require either
48 /// transposing point coordinates into and out of some applications, or making
49 /// assumptions about where a -90 degree rotation has been applied and
50 /// effectively, mysteriously swapping the roles of Y and Z coordinates -
51 /// we allow each stage to carry, in its root layer, a declaration of the
52 /// up axis for all the geometry contained in the stage, and require
53 /// applications to consult it if they wish to create new cameras to view
54 /// the scene in its intended orientation.
55 ///
56 /// Note that because you can make only a Stage-level declaration of up axis,
57 /// it must hold true for all referenced geometry and assets. A conscientious
58 /// set/environment-construction tool could examine the up axis of referenced
59 /// assets as they are being referenced, and apply a corrective rotation
60 /// on the referencing prim as it is being added to the scene, when the
61 /// referenced up axis differs from the set's.
62 ///
63 /// We provide free functions for setting (UsdGeomSetStageUpAxis()),
64 /// retrieving (UsdGeomGetStageUpAxis()), and declaring a site-level
65 /// fallback up axis (UsdGeomGetFallbackUpAxis()) that can be configured
66 /// with a PlugPlugin plugInfo.json file. See the individual methods for
67 /// details.
68 ///
69 /// The stage up axis is encoded as stage metadatum \em upAxis, whose legal
70 /// values are "Y" and "Z", as represented by UsdGeomTokens->y and
71 /// UsdGeomTokens->z. Of course, constructing a correct camera view of a
72 /// scene depends not only on the up axis, but also on the handedness of the
73 /// coordinate system. Like OpenGL and the fallback for
74 /// UsdGeomGprim::GetOrientationAttr(), <b>UsdGeom stipulates a right-handed
75 /// coordinate system.</b> Therefore, when viewing a UsdStage with a "Y" up
76 /// axis, the stage's Z axis will be pointing out of the screen, and when
77 /// viewing a UsdStage with a "Z" up axis, the stage's Y axis will be
78 /// pointing into the screen.
79 ///
80 /// @{
81 
82 /// Fetch and return \p stage 's upAxis. If unauthored, will return the
83 /// value provided by UsdGeomGetFallbackUpAxis(). Exporters, however, are
84 /// strongly encouraged to always set the upAxis for every USD file they create.
85 ///
86 /// \return one of: UsdGeomTokens->y or UsdGeomTokens->z, unless there was
87 /// an error, in which case returns an empty TfToken
88 ///
89 /// \sa UsdGeomUpAxis_group
92 
93 /// Set \p stage 's upAxis to \p axis, which must be one of UsdGeomTokens->y
94 /// or UsdGeomTokens->z
95 ///
96 /// UpAxis is stage-level metadata, therefore see UsdStage::SetMetadata().
97 ///
98 /// \return true if upAxis was successfully set. The stage's UsdEditTarget
99 /// must be either its root layer or session layer.
100 /// \sa UsdGeomUpAxis_group
102 bool UsdGeomSetStageUpAxis(const UsdStageWeakPtr &stage, const TfToken &axis);
103 
104 /// Return the site-level fallback up axis as a TfToken.
105 ///
106 /// In a generic installation of USD, the fallback will be "Y". This can be
107 /// changed to "Z" by adding, in a plugInfo.json file discoverable by USD's
108 /// PlugPlugin mechanism:
109 /// \code{json}
110 /// "UsdGeomMetrics": {
111 /// "upAxis": "Z"
112 /// }
113 /// \endcode
114 ///
115 /// If more than one such entry is discovered and the values for upAxis differ,
116 /// we will issue a warning during the first call to this function, and ignore
117 /// all of them, so that we devolve to deterministic behavior of Y up axis
118 /// until the problem is rectified.
121 
122 /// @}
123 
124 /// \defgroup UsdGeomLinearUnits_group Encoding Stage Linear Units
125 ///
126 /// As with \ref UsdGeomUpAxis_group, we restrict the encoding of linear
127 /// units to be stage-wide; if assembling assets of different metrics, it is
128 /// the assembler's responsibility to apply suitable correctives to the
129 /// referenced data to bring it into the referencing stage's metric.
130 ///
131 /// We encode linear measure as **meters per unit** (stage-level metadata
132 /// *metersPerUnit*) rather than units-per-meter because it makes it easier
133 /// to encode precise imperial units (one imperial foot = 0.3048 meters exactly).
134 ///
135 /// If a UsdStage has no authored *metersPerUnit* we fall back to the value
136 /// \ref UsdGeomLinearUnits "UsdGeomLinearUnits::centimeters", i.e. 0.01.
137 ///
138 /// The specified *metersPerUnit* metric should only be applied to
139 /// **world space** (i.e. fully transformed) attributes of types:
140 /// - point3{h,f,d} (and Arrays thereof)
141 /// - vector3{h,f,d} (and Arrays thereof)
142 /// - schema attributes that define a length, such as Sphere.radius
143 /// and Boundable.extent
144 ///
145 /// It may be tempting to interpret raw attribute values, and even
146 /// xformOp:translate values in the *metersPerUnit* metric, but because any
147 /// xformOp:scale transformations will change the metric of the authored
148 /// attribute, and in fact we *require* this sort of scale change when
149 /// referencing assets of differing metrics, it is unreliable to do so.
150 
151 /// @{
152 
153 /// Return *stage*'s authored *metersPerUnit*, or 0.01 if unauthored.
154 /// \sa UsdGeomLinearUnits_group
156 double UsdGeomGetStageMetersPerUnit(const UsdStageWeakPtr &stage);
157 
158 /// Return whether *stage* has an authored *metersPerUnit*.
159 /// \sa UsdGeomLinearUnits_group
162 
163 /// Author *stage*'s *metersPerUnit*.
164 ///
165 /// \return true if metersPerUnit was successfully set. The stage's
166 /// UsdEditTarget must be either its root layer or session layer.
167 /// \sa UsdGeomLinearUnits_group
170  double metersPerUnit);
171 
172 /// Return *true* if the two given metrics are within the provided
173 /// relative *epsilon* of each other, when you need to know an absolute
174 /// metric rather than a scaling factor.
175 ///
176 /// Use like so:
177 /// \code
178 /// double stageUnits = UsdGeomGetStageMetersPerUnit(stage);
179 ///
180 /// if (UsdGeomLinearUnitsAre(stageUnits, UsdGeomLinearUnits::meters))
181 /// // do something for meters
182 /// else if (UsdGeomLinearUnitsAre(stageUnits, UsdGeomLinearUnits::feet))
183 /// // do something for feet
184 /// \endcode
185 ///
186 /// \return *false* if either input is zero or negative, otherwise relative
187 /// floating-point comparison between the two inputs.
188 /// \sa UsdGeomLinearUnits_group
190 bool UsdGeomLinearUnitsAre(double authoredUnits, double standardUnits,
191  double epsilon = 1e-5);
192 
193 /// \class UsdGeomLinearUnits
194 /// Container class for static double-precision symbols representing common
195 /// units of measure expressed in meters.
196 /// \sa UsdGeomLinearUnits_group
198 public:
199  static constexpr double nanometers = 1e-9;
200  static constexpr double micrometers = 1e-6;
201  static constexpr double millimeters = 0.001;
202  static constexpr double centimeters = 0.01;
203  static constexpr double meters = 1.0;
204  static constexpr double kilometers = 1000;
205 
206  /// Measured for one year = 365.25 days
207  static constexpr double lightYears = 9.4607304725808e15;
208 
209  static constexpr double inches = 0.0254;
210  static constexpr double feet = 0.3048;
211  static constexpr double yards = 0.9144;
212  static constexpr double miles = 1609.344;
213 };
214 
215 /// @}
216 
218 
219 #endif // PXR_USD_USD_GEOM_METRICS_H
static constexpr double nanometers
Definition: metrics.h:199
USDGEOM_API bool UsdGeomStageHasAuthoredMetersPerUnit(const UsdStageWeakPtr &stage)
static constexpr double centimeters
Definition: metrics.h:202
static constexpr double miles
Definition: metrics.h:212
UsdStagePtr UsdStageWeakPtr
Definition: common.h:55
USDGEOM_API TfToken UsdGeomGetStageUpAxis(const UsdStageWeakPtr &stage)
static constexpr double micrometers
Definition: metrics.h:200
Definition: token.h:87
static constexpr double feet
Definition: metrics.h:210
static constexpr double inches
Definition: metrics.h:209
static constexpr double lightYears
Measured for one year = 365.25 days.
Definition: metrics.h:207
USDGEOM_API bool UsdGeomLinearUnitsAre(double authoredUnits, double standardUnits, double epsilon=1e-5)
static constexpr double kilometers
Definition: metrics.h:204
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1432
static constexpr double yards
Definition: metrics.h:211
USDGEOM_API bool UsdGeomSetStageUpAxis(const UsdStageWeakPtr &stage, const TfToken &axis)
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
static constexpr double millimeters
Definition: metrics.h:201
USDGEOM_API bool UsdGeomSetStageMetersPerUnit(const UsdStageWeakPtr &stage, double metersPerUnit)
#define USDGEOM_API
Definition: api.h:40
static constexpr double meters
Definition: metrics.h:203
USDGEOM_API TfToken UsdGeomGetFallbackUpAxis()
USDGEOM_API double UsdGeomGetStageMetersPerUnit(const UsdStageWeakPtr &stage)