This document is for a version of USD that is under development. See this page for the current release.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
GfCamera Class Reference

Object-based representation of a camera. More...

#include <camera.h>

Public Types

enum  Projection { Perspective = 0 , Orthographic }
 Projection type. More...
 
enum  FOVDirection { FOVHorizontal = 0 , FOVVertical }
 Direction used for Field of View or orthographic size. More...
 

Public Member Functions

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 SetProjection (const Projection &val)
 Sets the projection type.
 
GF_API void SetClippingRange (const GfRange1f &val)
 Sets the clipping range in world units.
 
GF_API void SetClippingPlanes (const std::vector< GfVec4f > &val)
 Sets additional arbitrarily oriented clipping planes.
 
GF_API void SetFStop (const float val)
 Sets the lens aperture, unitless.
 
GF_API void SetFocusDistance (const float val)
 Sets the focus distance in world units.
 
GF_API GfMatrix4d GetTransform () const
 Returns the transform of the filmback in world space.
 
GF_API Projection GetProjection () const
 Returns the projection type.
 
GF_API float GetHorizontalAperture () const
 Returns the width of the projector aperture in tenths of a world unit (e.g., mm if the world unit is assumed to be cm).
 
GF_API float GetVerticalAperture () const
 Returns the height of the projector aperture in tenths of a world unit (e.g., mm if the world unit is assumed to be cm).
 
GF_API float GetHorizontalApertureOffset () const
 Returns the horizontal offset of the projector aperture in tenths of a world unit (e.g., mm if the world unit is assumed to be cm).
 
GF_API float GetVerticalApertureOffset () const
 Returns the vertical offset of the projector aperture in tenths of a world unit (e.g., mm if the world unit is assumed to be cm).
 
GF_API float GetAspectRatio () const
 Returns the projector aperture aspect ratio.
 
GF_API float GetFocalLength () const
 Returns the focal length in tenths of a world unit (e.g., mm if the world unit is assumed to be cm).
 
GF_API float GetFieldOfView (FOVDirection direction) const
 Returns the horizontal or vertical field of view in degrees.
 
GF_API GfRange1f GetClippingRange () const
 Returns the clipping range in world units.
 
GF_API const std::vector< GfVec4f > & GetClippingPlanes () const
 Returns additional clipping planes.
 
GF_API GfFrustum GetFrustum () const
 Returns the computed, world-space camera frustum.
 
GF_API float GetFStop () const
 Returns the lens aperture.
 
GF_API float GetFocusDistance () const
 Returns the focus distance in world units.
 
GF_API bool operator== (const GfCamera &other) const
 Equality operator. true iff all parts match.
 
GF_API bool operator!= (const GfCamera &other) const
 
Physics based camera setup
GF_API void SetFocalLength (const float val)
 These are the values actually stored in the class and they correspond to measurements of an actual physical camera (in mm).
 
GF_API void SetHorizontalAperture (const float val)
 Sets the width of the projector aperture in tenths of a world unit (e.g., mm if the world unit is assumed to be cm).
 
GF_API void SetVerticalAperture (const float val)
 Sets the height of the projector aperture in tenths of a world unit (e.g., mm if the world unit is assumed to be cm).
 
GF_API void SetHorizontalApertureOffset (const float val)
 Sets the horizontal offset of the projector aperture in tenths of a world unit (e.g., mm if the world unit is assumed to be cm).
 
GF_API void SetVerticalApertureOffset (const float val)
 Sets the vertical offset of the projector aperture in tenths of a world unit (e.g., mm if the world unit is assumed to be cm).
 
Frustum geometry setup
GF_API void SetPerspectiveFromAspectRatioAndFieldOfView (float aspectRatio, float fieldOfView, FOVDirection direction, float horizontalAperture=DEFAULT_HORIZONTAL_APERTURE)
 Sets the frustum to be projective with the given aspectRatio and horizontal, respectively, vertical field of view fieldOfView (similar to gluPerspective when direction = FOVVertical).
 
GF_API void SetOrthographicFromAspectRatioAndSize (float aspectRatio, float orthographicSize, FOVDirection direction)
 Sets the frustum to be orthographic such that it has the given aspectRatio and such that the orthographic width, respectively, orthographic height (in cm) is equal to orthographicSize (depending on direction).
 
GF_API void SetFromViewAndProjectionMatrix (const GfMatrix4d &viewMatrix, const GfMatrix4d &projMatix, const float focalLength=50.0)
 Sets the camera from a view and projection matrix.
 

Static Public Attributes

static GF_API const double APERTURE_UNIT
 The unit for horizontal and vertical aperture is one tenth of the world unit.
 
static GF_API const double FOCAL_LENGTH_UNIT
 The unit for focal length. Similar to APERTURE_UNIT.
 
static GF_API const double DEFAULT_HORIZONTAL_APERTURE
 Default horizontal and vertical aperture, based on a 35mm (non-anamorphic) projector aperture (0.825 x 0602 inches, converted to mm).
 
static GF_API const double DEFAULT_VERTICAL_APERTURE
 

Detailed Description

Object-based representation of a camera.

This class provides a thin wrapper on the camera data model, with a small number of computations.

Definition at line 32 of file camera.h.

Member Enumeration Documentation

◆ FOVDirection

Direction used for Field of View or orthographic size.

Definition at line 42 of file camera.h.

◆ Projection

enum Projection

Projection type.

Definition at line 36 of file camera.h.

Member Function Documentation

◆ GetAspectRatio()

GF_API float GetAspectRatio ( ) const

Returns the projector aperture aspect ratio.

◆ GetClippingPlanes()

GF_API const std::vector< GfVec4f > & GetClippingPlanes ( ) const

Returns additional clipping planes.

◆ GetClippingRange()

GF_API GfRange1f GetClippingRange ( ) const

Returns the clipping range in world units.

◆ GetFieldOfView()

GF_API float GetFieldOfView ( FOVDirection  direction) const

Returns the horizontal or vertical field of view in degrees.

◆ GetFocalLength()

GF_API float GetFocalLength ( ) const

Returns the focal length in tenths of a world unit (e.g., mm if the world unit is assumed to be cm).

◆ GetFocusDistance()

GF_API float GetFocusDistance ( ) const

Returns the focus distance in world units.

◆ GetFrustum()

GF_API GfFrustum GetFrustum ( ) const

Returns the computed, world-space camera frustum.

The frustum will always be that of a Y-up, -Z-looking camera.

◆ GetFStop()

GF_API float GetFStop ( ) const

Returns the lens aperture.

◆ GetHorizontalAperture()

GF_API float GetHorizontalAperture ( ) const

Returns the width of the projector aperture in tenths of a world unit (e.g., mm if the world unit is assumed to be cm).

◆ GetHorizontalApertureOffset()

GF_API float GetHorizontalApertureOffset ( ) const

Returns the horizontal offset of the projector aperture in tenths of a world unit (e.g., mm if the world unit is assumed to be cm).

In particular, an offset is necessary when writing out a stereo camera with finite convergence distance as two cameras.

◆ GetProjection()

GF_API Projection GetProjection ( ) const

Returns the projection type.

◆ GetTransform()

GF_API GfMatrix4d GetTransform ( ) const

Returns the transform of the filmback in world space.

This is exactly the transform specified via SetTransform().

◆ GetVerticalAperture()

GF_API float GetVerticalAperture ( ) const

Returns the height of the projector aperture in tenths of a world unit (e.g., mm if the world unit is assumed to be cm).

◆ GetVerticalApertureOffset()

GF_API float GetVerticalApertureOffset ( ) const

Returns the vertical offset of the projector aperture in tenths of a world unit (e.g., mm if the world unit is assumed to be cm).

◆ operator==()

GF_API bool operator== ( const GfCamera other) const

Equality operator. true iff all parts match.

◆ SetClippingPlanes()

GF_API void SetClippingPlanes ( const std::vector< GfVec4f > &  val)

Sets additional arbitrarily oriented clipping planes.

A vector (a,b,c,d) encodes a clipping plane that clips off points (x,y,z) with

   a * x + b * y + c * z + d * 1 < 0

where (x,y,z) are the coordinates in the camera's space.

◆ SetClippingRange()

GF_API void SetClippingRange ( const GfRange1f val)

Sets the clipping range in world units.

◆ SetFocalLength()

GF_API void SetFocalLength ( const float  val)

These are the values actually stored in the class and they correspond to measurements of an actual physical camera (in mm).

Together with the clipping range, they determine the camera frustum. Sets the focal length in tenths of a world unit (e.g., mm if the world unit is assumed to be cm).

◆ SetFocusDistance()

GF_API void SetFocusDistance ( const float  val)

Sets the focus distance in world units.

◆ SetFromViewAndProjectionMatrix()

GF_API void SetFromViewAndProjectionMatrix ( const GfMatrix4d viewMatrix,
const GfMatrix4d projMatix,
const float  focalLength = 50.0 
)

Sets the camera from a view and projection matrix.

Note that the projection matrix does only determine the ratio of aperture to focal length, so there is a choice which defaults to 50mm (or more accurately, 50 tenths of a world unit).

◆ SetFStop()

GF_API void SetFStop ( const float  val)

Sets the lens aperture, unitless.

◆ SetHorizontalAperture()

GF_API void SetHorizontalAperture ( const float  val)

Sets the width of the projector aperture in tenths of a world unit (e.g., mm if the world unit is assumed to be cm).

◆ SetHorizontalApertureOffset()

GF_API void SetHorizontalApertureOffset ( const float  val)

Sets the horizontal offset of the projector aperture in tenths of a world unit (e.g., mm if the world unit is assumed to be cm).

◆ SetOrthographicFromAspectRatioAndSize()

GF_API void SetOrthographicFromAspectRatioAndSize ( float  aspectRatio,
float  orthographicSize,
FOVDirection  direction 
)

Sets the frustum to be orthographic such that it has the given aspectRatio and such that the orthographic width, respectively, orthographic height (in cm) is equal to orthographicSize (depending on direction).

◆ SetPerspectiveFromAspectRatioAndFieldOfView()

GF_API void SetPerspectiveFromAspectRatioAndFieldOfView ( float  aspectRatio,
float  fieldOfView,
FOVDirection  direction,
float  horizontalAperture = DEFAULT_HORIZONTAL_APERTURE 
)

Sets the frustum to be projective with the given aspectRatio and horizontal, respectively, vertical field of view fieldOfView (similar to gluPerspective when direction = FOVVertical).

Do not pass values for horionztalAperture unless you care about DepthOfField.

◆ SetProjection()

GF_API void SetProjection ( const Projection val)

Sets the projection type.

◆ SetTransform()

GF_API void SetTransform ( const GfMatrix4d val)

Sets the transform of the filmback in world space to val.

◆ SetVerticalAperture()

GF_API void SetVerticalAperture ( const float  val)

Sets the height of the projector aperture in tenths of a world unit (e.g., mm if the world unit is assumed to be cm).

◆ SetVerticalApertureOffset()

GF_API void SetVerticalApertureOffset ( const float  val)

Sets the vertical offset of the projector aperture in tenths of a world unit (e.g., mm if the world unit is assumed to be cm).

Member Data Documentation

◆ APERTURE_UNIT

GF_API const double APERTURE_UNIT
static

The unit for horizontal and vertical aperture is one tenth of the world unit.

Thus, if the world unit is assumed to be cm, the horizontal and vertical aperture unit is mm.

Definition at line 50 of file camera.h.

◆ DEFAULT_HORIZONTAL_APERTURE

GF_API const double DEFAULT_HORIZONTAL_APERTURE
static

Default horizontal and vertical aperture, based on a 35mm (non-anamorphic) projector aperture (0.825 x 0602 inches, converted to mm).

Definition at line 57 of file camera.h.

◆ DEFAULT_VERTICAL_APERTURE

GF_API const double DEFAULT_VERTICAL_APERTURE
static

Definition at line 58 of file camera.h.

◆ FOCAL_LENGTH_UNIT

GF_API const double FOCAL_LENGTH_UNIT
static

The unit for focal length. Similar to APERTURE_UNIT.

Definition at line 52 of file camera.h.


The documentation for this class was generated from the following file: