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 GF_CAMERA_H
25 #define 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  /// @}
151 
152  /// Sets the clipping range in world units.
153  GF_API void SetClippingRange(const GfRange1f &val);
154 
155  /// Sets additional arbitrarily oriented clipping planes.
156  /// A vector (a,b,c,d) encodes a clipping plane that clips off points
157  /// (x,y,z) with
158  ///
159  /// a * x + b * y + c * z + d * 1 < 0
160  ///
161  /// where (x,y,z) are the coordinates in the camera's space.
162  GF_API void SetClippingPlanes(const std::vector<GfVec4f> &val);
163 
164  /// Sets the lens aperture, unitless.
165  GF_API void SetFStop(const float val);
166 
167  /// Sets the focus distance in world units.
168  GF_API void SetFocusDistance(const float val);
169 
170  /// Returns the transform of the filmback in world space. This is
171  /// exactly the transform specified via SetTransform().
173 
174  /// Returns the projection type.
176 
177  /// Returns the width of the projector aperture in tenths of a world unit
178  /// (e.g., mm if the world unit is assumed to be cm).
179  GF_API float GetHorizontalAperture() const;
180 
181  /// Returns the height of the projector aperture in tenths of a world unit
182  /// (e.g., mm if the world unit is assumed to be cm).
183  GF_API float GetVerticalAperture() const;
184 
185  /// Returns the horizontal offset of the projector aperture in tenths of a
186  /// world unit (e.g., mm if the world unit is assumed to be cm).
187  /// In particular, an offset is necessary when writing out a stereo camera
188  /// with finite convergence distance as two cameras.
189  GF_API float GetHorizontalApertureOffset() const;
190 
191  /// Returns the vertical offset of the projector aperture in tenths of a
192  /// world unit (e.g., mm if the world unit is assumed to be cm).
193  GF_API float GetVerticalApertureOffset() const;
194 
195  /// Returns the projector aperture aspect ratio.
196  GF_API float GetAspectRatio() const;
197 
198  /// Returns the focal length in tenths of a world unit (e.g., mm if the
199  /// world unit is assumed to be cm).
200  GF_API float GetFocalLength() const;
201 
202  /// Returns the horizontal or vertical field of view in degrees.
204 
205  /// Returns the clipping range in world units.
207 
208  /// Returns additional clipping planes.
209  GF_API const std::vector<GfVec4f> &GetClippingPlanes() const;
210 
211  /// Returns the computed, world-space camera frustum. The frustum
212  /// will always be that of a Y-up, -Z-looking camera.
213  GF_API GfFrustum GetFrustum() const;
214 
215  /// Returns the lens aperture.
216  GF_API float GetFStop() const;
217 
218  /// Returns the focus distance in world units.
219  GF_API float GetFocusDistance() const;
220 
221  /// Equality operator. true iff all parts match.
222  GF_API bool operator==(const GfCamera& other) const;
223 
224  // Inequality operator. true iff not equality.
225  GF_API bool operator!=(const GfCamera& other) const;
226 
227 private:
228  // frustum
229  GfMatrix4d _transform;
230  Projection _projection;
231  float _horizontalAperture;
232  float _verticalAperture;
233  float _horizontalApertureOffset;
234  float _verticalApertureOffset;
235  float _focalLength;
236  GfRange1f _clippingRange;
237  std::vector<GfVec4f> _clippingPlanes;
238 
239  // focus
240  float _fStop;
241  float _focusDistance;
242 };
243 
245 
246 #endif // 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
GLuint GLenum GLenum transform
Definition: glew.h:14742
GF_API float GetHorizontalAperture() const
IMF_EXPORT IMATH_NAMESPACE::V3f direction(const IMATH_NAMESPACE::Box2i &dataWindow, const IMATH_NAMESPACE::V2f &pixelPosition)
GLuint const GLfloat * val
Definition: glew.h:2794
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.
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
GF_API void SetClippingPlanes(const std::vector< GfVec4f > &val)
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1245
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:83
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