HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
camera.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_BASE_GF_CAMERA_H
25 #define PXR_BASE_GF_CAMERA_H
26 
27 /// \file gf/camera.h
28 /// \ingroup group_gf_BasicGeometry
29 
30 #include "pxr/pxr.h"
31 #include "pxr/base/gf/matrix4d.h"
32 #include "pxr/base/gf/range1f.h"
33 #include "pxr/base/gf/vec4f.h"
34 #include "pxr/base/gf/api.h"
35 
36 #include <vector>
37 
39 
40 class GfFrustum;
41 
42 /// \class GfCamera
43 /// \ingroup group_gf_BasicGeometry
44 /// \brief Object-based representation of a camera.
45 ///
46 /// This class provides a thin wrapper on the camera data model,
47 /// with a small number of computations.
48 ///
49 class GfCamera
50 {
51 public:
52  /// Projection type.
53  enum Projection {
56  };
57 
58  /// Direction used for Field of View or orthographic size
59  enum FOVDirection {
62  };
63 
64  /// The unit for horizontal and vertical aperture is one tenth of the
65  /// world unit. Thus, if the world unit is assumed to be cm, the horizontal
66  /// and vertical aperture unit is mm.
67  GF_API static const double APERTURE_UNIT;
68  /// The unit for focal length. Similar to APERTURE_UNIT.
69  GF_API static const double FOCAL_LENGTH_UNIT;
70 
71  /// Default horizontal and vertical aperture, based on a 35mm
72  /// (non-anamorphic) projector aperture (0.825 x 0602 inches, converted to
73  /// mm).
74  GF_API static const double DEFAULT_HORIZONTAL_APERTURE;
75  GF_API static const double DEFAULT_VERTICAL_APERTURE;
76 
77 public:
79  const GfMatrix4d &transform = GfMatrix4d(1.0),
80  Projection projection = Perspective,
81  float horizontalAperture = DEFAULT_HORIZONTAL_APERTURE,
82  float verticalAperture = DEFAULT_VERTICAL_APERTURE,
83  float horizontalApertureOffset = 0.0,
84  float verticalApertureOffset = 0.0,
85  float focalLength = 50.0,
86  const GfRange1f &clippingRange = GfRange1f(1, 1000000),
87  const std::vector<GfVec4f> &clippingPlanes = std::vector<GfVec4f>(),
88  float fStop = 0.0,
89  float focusDistance = 0.0);
90 
91  /// Sets the transform of the filmback in world space to \p val.
92  GF_API void SetTransform(const GfMatrix4d &val);
93 
94  /// Sets the projection type.
95  GF_API void SetProjection(const Projection &val);
96 
97  /// \name Physics based camera setup
98 
99  /// These are the values actually stored in the class and they correspond
100  /// to measurements of an actual physical camera (in mm).
101  /// Together with the clipping range, they determine the camera frustum.
102 
103  /// @{
104 
105  /// Sets the focal length in tenths of a world unit (e.g., mm if the world
106  /// unit is assumed to be cm).
107  GF_API void SetFocalLength(const float val);
108 
109  /// Sets the width of the projector aperture in tenths of a world unit
110  /// (e.g., mm if the world unit is assumed to be cm).
111  GF_API void SetHorizontalAperture(const float val);
112 
113  /// Sets the height of the projector aperture in tenths of a world unit
114  /// (e.g., mm if the world unit is assumed to be cm).
115  GF_API void SetVerticalAperture(const float val);
116 
117  /// Sets the horizontal offset of the projector aperture in tenths of a
118  /// world unit (e.g., mm if the world unit is assumed to be cm).
119  GF_API void SetHorizontalApertureOffset(const float val);
120 
121  /// Sets the vertical offset of the projector aperture in tenths of a
122  /// world unit (e.g., mm if the world unit is assumed to be cm).
123  GF_API void SetVerticalApertureOffset(const float val);
124  /// @}
125 
126  /// \name Frustum geometry setup
127  /// @{
128 
129  /// Sets the frustum to be projective with the given \p aspectRatio
130  /// and horizontal, respectively, vertical field of view \p fieldOfView
131  /// (similar to gluPerspective when direction = FOVVertical).
132  ///
133  /// Do not pass values for \p horionztalAperture unless you care about
134  /// DepthOfField.
135 
137  float aspectRatio,
138  float fieldOfView,
140  float horizontalAperture = DEFAULT_HORIZONTAL_APERTURE);
141 
142  /// Sets the frustum to be orthographic such that it has the given
143  /// \p aspectRatio and such that the orthographic width, respectively,
144  /// orthographic height (in cm) is equal to \p orthographicSize
145  /// (depending on direction).
146 
148  float aspectRatio, float orthographicSize, FOVDirection direction);
149 
150  /// Sets the camera from a view and projection matrix.
151  ///
152  /// Note that the projection matrix does only determine the ratio
153  /// of aperture to focal length, so there is a choice which defaults
154  /// to 50mm (or more accurately, 50 tenths of a world unit).
155 
157  const GfMatrix4d &viewMatrix, const GfMatrix4d &projMatix,
158  const float focalLength = 50.0);
159 
160  /// @}
161 
162  /// Sets the clipping range in world units.
163  GF_API void SetClippingRange(const GfRange1f &val);
164 
165  /// Sets additional arbitrarily oriented clipping planes.
166  /// A vector (a,b,c,d) encodes a clipping plane that clips off points
167  /// (x,y,z) with
168  ///
169  /// a * x + b * y + c * z + d * 1 < 0
170  ///
171  /// where (x,y,z) are the coordinates in the camera's space.
172  GF_API void SetClippingPlanes(const std::vector<GfVec4f> &val);
173 
174  /// Sets the lens aperture, unitless.
175  GF_API void SetFStop(const float val);
176 
177  /// Sets the focus distance in world units.
178  GF_API void SetFocusDistance(const float val);
179 
180  /// Returns the transform of the filmback in world space. This is
181  /// exactly the transform specified via SetTransform().
183 
184  /// Returns the projection type.
186 
187  /// Returns the width of the projector aperture in tenths of a world unit
188  /// (e.g., mm if the world unit is assumed to be cm).
189  GF_API float GetHorizontalAperture() const;
190 
191  /// Returns the height of the projector aperture in tenths of a world unit
192  /// (e.g., mm if the world unit is assumed to be cm).
193  GF_API float GetVerticalAperture() const;
194 
195  /// Returns the horizontal offset of the projector aperture in tenths of a
196  /// world unit (e.g., mm if the world unit is assumed to be cm).
197  /// In particular, an offset is necessary when writing out a stereo camera
198  /// with finite convergence distance as two cameras.
199  GF_API float GetHorizontalApertureOffset() const;
200 
201  /// Returns the vertical offset of the projector aperture in tenths of a
202  /// world unit (e.g., mm if the world unit is assumed to be cm).
203  GF_API float GetVerticalApertureOffset() const;
204 
205  /// Returns the projector aperture aspect ratio.
206  GF_API float GetAspectRatio() const;
207 
208  /// Returns the focal length in tenths of a world unit (e.g., mm if the
209  /// world unit is assumed to be cm).
210  GF_API float GetFocalLength() const;
211 
212  /// Returns the horizontal or vertical field of view in degrees.
214 
215  /// Returns the clipping range in world units.
217 
218  /// Returns additional clipping planes.
219  GF_API const std::vector<GfVec4f> &GetClippingPlanes() const;
220 
221  /// Returns the computed, world-space camera frustum. The frustum
222  /// will always be that of a Y-up, -Z-looking camera.
223  GF_API GfFrustum GetFrustum() const;
224 
225  /// Returns the lens aperture.
226  GF_API float GetFStop() const;
227 
228  /// Returns the focus distance in world units.
229  GF_API float GetFocusDistance() const;
230 
231  /// Equality operator. true iff all parts match.
232  GF_API bool operator==(const GfCamera& other) const;
233 
234  // Inequality operator. true iff not equality.
235  GF_API bool operator!=(const GfCamera& other) const;
236 
237 private:
238  // frustum
239  GfMatrix4d _transform;
240  Projection _projection;
241  float _horizontalAperture;
242  float _verticalAperture;
243  float _horizontalApertureOffset;
244  float _verticalApertureOffset;
245  float _focalLength;
246  GfRange1f _clippingRange;
247  std::vector<GfVec4f> _clippingPlanes;
248 
249  // focus
250  float _fStop;
251  float _focusDistance;
252 };
253 
255 
256 #endif // PXR_BASE_GF_CAMERA_H
GF_API const std::vector< GfVec4f > & GetClippingPlanes() const
Returns additional clipping planes.
FOVDirection
Direction used for Field of View or orthographic size.
Definition: camera.h:59
GF_API void SetVerticalAperture(const float val)
Object-based representation of a camera.
Definition: camera.h:49
GF_API float GetHorizontalAperture() const
IMF_EXPORT IMATH_NAMESPACE::V3f direction(const IMATH_NAMESPACE::Box2i &dataWindow, const IMATH_NAMESPACE::V2f &pixelPosition)
GF_API void SetProjection(const Projection &val)
Sets the projection type.
GF_API GfFrustum GetFrustum() const
GF_API void SetHorizontalApertureOffset(const float val)
GF_API GfMatrix4d GetTransform() const
static GF_API const double DEFAULT_VERTICAL_APERTURE
Definition: camera.h:75
GF_API void SetFocalLength(const float val)
GF_API void SetClippingRange(const GfRange1f &val)
Sets the clipping range in world units.
GLuint GLenum GLenum transform
Definition: glew.h:15055
GF_API float GetFStop() const
Returns the lens aperture.
GF_API void SetPerspectiveFromAspectRatioAndFieldOfView(float aspectRatio, float fieldOfView, FOVDirection direction, float horizontalAperture=DEFAULT_HORIZONTAL_APERTURE)
GF_API void SetFocusDistance(const float val)
Sets the focus distance in world units.
GF_API float GetVerticalApertureOffset() const
GF_API GfCamera(const GfMatrix4d &transform=GfMatrix4d(1.0), Projection projection=Perspective, float horizontalAperture=DEFAULT_HORIZONTAL_APERTURE, float verticalAperture=DEFAULT_VERTICAL_APERTURE, float horizontalApertureOffset=0.0, float verticalApertureOffset=0.0, float focalLength=50.0, const GfRange1f &clippingRange=GfRange1f(1, 1000000), const std::vector< GfVec4f > &clippingPlanes=std::vector< GfVec4f >(), float fStop=0.0, float focusDistance=0.0)
GF_API void SetTransform(const GfMatrix4d &val)
Sets the transform of the filmback in world space to val.
GF_API void SetVerticalApertureOffset(const float val)
GF_API Projection GetProjection() const
Returns the projection type.
GF_API float GetAspectRatio() const
Returns the projector aperture aspect ratio.
GF_API float GetHorizontalApertureOffset() const
GF_API void SetFStop(const float val)
Sets the lens aperture, unitless.
static GF_API const double FOCAL_LENGTH_UNIT
The unit for focal length. Similar to APERTURE_UNIT.
Definition: camera.h:69
static GF_API const double DEFAULT_HORIZONTAL_APERTURE
Definition: camera.h:74
GLuint GLfloat * val
Definition: glcorearb.h:1607
GF_API void SetClippingPlanes(const std::vector< GfVec4f > &val)
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1375
GF_API void SetFromViewAndProjectionMatrix(const GfMatrix4d &viewMatrix, const GfMatrix4d &projMatix, const float focalLength=50.0)
static GF_API const double APERTURE_UNIT
Definition: camera.h:67
GF_API float GetFocusDistance() const
Returns the focus distance in world units.
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
GF_API float GetFieldOfView(FOVDirection direction) const
Returns the horizontal or vertical field of view in degrees.
GF_API bool operator!=(const GfCamera &other) const
Projection
Projection type.
Definition: camera.h:53
GF_API void SetOrthographicFromAspectRatioAndSize(float aspectRatio, float orthographicSize, FOVDirection direction)
GF_API float GetVerticalAperture() const
GF_API GfRange1f GetClippingRange() const
Returns the clipping range in world units.
GF_API float GetFocalLength() const
GF_API bool operator==(const GfCamera &other) const
Equality operator. true iff all parts match.
GF_API void SetHorizontalAperture(const float val)
#define GF_API
Definition: api.h:40