UsdGeomCamera#

Fully qualified name: usdrt::UsdGeomCamera

class UsdGeomCamera : public usdrt::UsdGeomXformable #

Transformable camera.

Describes optical properties of a camera via a common set of attributes that provide control over the camera’s frustum as well as its depth of field. For stereo, the left and right camera are individual prims tagged through the stereoRole attribute.

There is a corresponding class GfCamera, which can hold the state of a camera (at a particular time). UsdGeomCamera::GetCamera() and UsdGeomCamera::SetFromCamera() convert between a USD camera prim and a GfCamera.

To obtain the camera’s location in world space, call the following on a UsdGeomCamera ‘camera’:

GfMatrix4d camXform = camera.ComputeLocalToWorldTransform(time);

Units of Measure for Camera Properties#

Despite the familiarity of millimeters for specifying some physical camera properties, UsdGeomCamera opts for greater consistency with all other UsdGeom schemas, which measure geometric properties in scene units, as determined by UsdGeomGetStageMetersPerUnit(). We do make a concession, however, in that lens and filmback properties are measured in tenths of a scene unit rather than “raw” scene units. This means that with the fallback value of .01 for metersPerUnit - i.e. scene unit of centimeters - then these “tenth of scene unit” properties are effectively millimeters.

For any described attribute Fallback Value or Allowed Values below that are text/tokens, the actual token is published and defined in UsdGeomTokens. So to set an attribute to the value “rightHanded”, use UsdGeomTokens->rightHanded as the value.

See also

UsdGeom_LinAlgBasics

Note

Cameras in USD are always “Y up”, regardless of the stage’s orientation (i.e. UsdGeomGetStageUpAxis()). This means that the inverse of ‘camXform’ (the VIEW half of the MODELVIEW transform in OpenGL parlance) will transform the world such that the camera is at the origin, looking down the -Z axis, with +Y as the up axis, and +X pointing to the right. This describes a right handed coordinate system.

Note

If one adds a Camera prim to a UsdStage whose scene unit is not centimeters, the fallback values for filmback properties will be incorrect (or at the least, unexpected) in an absolute sense; however, proper imaging through a “default camera” with focusing disabled depends only on ratios of the other properties, so the camera is still usable. However, it follows that if even one property is authored in the correct scene units, then they all must be.

Public Functions

inline explicit UsdGeomCamera(const UsdPrim &prim = UsdPrim())#: Construct a UsdGeomCamera on UsdPrim prim. Equivalent to UsdGeomCamera::Get(prim.GetStage(), prim.GetPath()) for a valid prim , but will not immediately throw an error for an invalid prim.

inline explicit UsdGeomCamera(const UsdSchemaBase &schemaObj)#: Construct a UsdGeomCamera on the prim held by schemaObj . Should be preferred over UsdGeomCamera(schemaObj.GetPrim()), as it preserves SchemaBase state.

inline virtual ~UsdGeomCamera()#: Destructor.

inline UsdAttribute GetProjectionAttr() const#


Declaration	`token projection = "perspective"`
C++ Type	TfToken
Usd Type	SdfValueTypeNames->Token
Allowed Values	perspective, orthographic

inline UsdAttribute CreateProjectionAttr() const#: See GetProjectionAttr(), and also Create vs Get Property Methods for when to use Get vs Create. If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

inline UsdAttribute GetHorizontalApertureAttr() const#

Horizontal aperture in tenths of a scene unit; see Units of Measure for Camera Properties . Default is the equivalent of the standard 35mm spherical projector aperture.


Declaration	`float horizontalAperture = 20.955`
C++ Type	float
Usd Type	SdfValueTypeNames->Float

inline UsdAttribute CreateHorizontalApertureAttr() const#: See GetHorizontalApertureAttr(), and also Create vs Get Property Methods for when to use Get vs Create. If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

inline UsdAttribute GetVerticalApertureAttr() const#

Vertical aperture in tenths of a scene unit; see Units of Measure for Camera Properties . Default is the equivalent of the standard 35mm spherical projector aperture.


Declaration	`float verticalAperture = 15.2908`
C++ Type	float
Usd Type	SdfValueTypeNames->Float

inline UsdAttribute CreateVerticalApertureAttr() const#: See GetVerticalApertureAttr(), and also Create vs Get Property Methods for when to use Get vs Create. If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

inline UsdAttribute GetHorizontalApertureOffsetAttr() const#

Horizontal aperture offset in the same units as horizontalAperture. Defaults to 0.


Declaration	`float horizontalApertureOffset = 0`
C++ Type	float
Usd Type	SdfValueTypeNames->Float

inline UsdAttribute CreateHorizontalApertureOffsetAttr() const#: See GetHorizontalApertureOffsetAttr(), and also Create vs Get Property Methods for when to use Get vs Create. If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

inline UsdAttribute GetVerticalApertureOffsetAttr() const#

Vertical aperture offset in the same units as verticalAperture. Defaults to 0.


Declaration	`float verticalApertureOffset = 0`
C++ Type	float
Usd Type	SdfValueTypeNames->Float

inline UsdAttribute CreateVerticalApertureOffsetAttr() const#: See GetVerticalApertureOffsetAttr(), and also Create vs Get Property Methods for when to use Get vs Create. If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

inline UsdAttribute GetFocalLengthAttr() const#

Perspective focal length in tenths of a scene unit; see Units of Measure for Camera Properties .


Declaration	`float focalLength = 50`
C++ Type	float
Usd Type	SdfValueTypeNames->Float

inline UsdAttribute CreateFocalLengthAttr() const#: See GetFocalLengthAttr(), and also Create vs Get Property Methods for when to use Get vs Create. If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

inline UsdAttribute GetClippingRangeAttr() const#

Near and far clipping distances in scene units; see Units of Measure for Camera Properties .


Declaration	`float2 clippingRange = (1, 1000000)`
C++ Type	GfVec2f
Usd Type	SdfValueTypeNames->Float2

inline UsdAttribute CreateClippingRangeAttr() const#: See GetClippingRangeAttr(), and also Create vs Get Property Methods for when to use Get vs Create. If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

inline UsdAttribute GetClippingPlanesAttr() const#

Additional, arbitrarily oriented clipping planes. A vector (a,b,c,d) encodes a clipping plane that cuts off (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.


Declaration	`float4[] clippingPlanes = []`
C++ Type	VtArray<GfVec4f>
Usd Type	SdfValueTypeNames->Float4Array

inline UsdAttribute CreateClippingPlanesAttr() const#: See GetClippingPlanesAttr(), and also Create vs Get Property Methods for when to use Get vs Create. If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

inline UsdAttribute GetFStopAttr() const#

Lens aperture. Defaults to 0.0, which turns off focusing.


Declaration	`float fStop = 0`
C++ Type	float
Usd Type	SdfValueTypeNames->Float

inline UsdAttribute CreateFStopAttr() const#: See GetFStopAttr(), and also Create vs Get Property Methods for when to use Get vs Create. If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

inline UsdAttribute GetFocusDistanceAttr() const#

Distance from the camera to the focus plane in scene units; see Units of Measure for Camera Properties .


Declaration	`float focusDistance = 0`
C++ Type	float
Usd Type	SdfValueTypeNames->Float

inline UsdAttribute CreateFocusDistanceAttr() const#: See GetFocusDistanceAttr(), and also Create vs Get Property Methods for when to use Get vs Create. If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

inline UsdAttribute GetStereoRoleAttr() const#

If different from mono, the camera is intended to be the left or right camera of a stereo setup.


Declaration	`uniform token stereoRole = "mono"`
C++ Type	TfToken
Usd Type	SdfValueTypeNames->Token
Variability	SdfVariabilityUniform
Allowed Values	mono, left, right

inline UsdAttribute CreateStereoRoleAttr() const#: See GetStereoRoleAttr(), and also Create vs Get Property Methods for when to use Get vs Create. If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

inline UsdAttribute GetShutterOpenAttr() const#

Frame relative shutter open time in UsdTimeCode units (negative value indicates that the shutter opens before the current frame time). Used for motion blur.


Declaration	`double shutter:open = 0`
C++ Type	double
Usd Type	SdfValueTypeNames->Double

inline UsdAttribute CreateShutterOpenAttr() const#: See GetShutterOpenAttr(), and also Create vs Get Property Methods for when to use Get vs Create. If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

inline UsdAttribute GetShutterCloseAttr() const#

Frame relative shutter close time, analogous comments from shutter:open apply. A value greater or equal to shutter:open should be authored, otherwise there is no exposure and a renderer should produce a black image.


Declaration	`double shutter:close = 0`
C++ Type	double
Usd Type	SdfValueTypeNames->Double

inline UsdAttribute CreateShutterCloseAttr() const#: See GetShutterCloseAttr(), and also Create vs Get Property Methods for when to use Get vs Create. If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

inline UsdAttribute GetExposureAttr() const#

Exposure adjustment, as a log base-2 value. The default of 0.0 has no effect. A value of 1.0 will double the image-plane intensities in a rendered image; a value of -1.0 will halve them.


Declaration	`float exposure = 0`
C++ Type	float
Usd Type	SdfValueTypeNames->Float

inline UsdAttribute CreateExposureAttr() const#: See GetExposureAttr(), and also Create vs Get Property Methods for when to use Get vs Create. If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

inline UsdAttribute GetXformOpOrderAttr() const#

Encodes the sequence of transformation operations in the order in which they should be pushed onto a transform stack while visiting a UsdStage’s prims in a graph traversal that will effect the desired positioning for this prim and its descendant prims.

You should rarely, if ever, need to manipulate this attribute directly. It is managed by the AddXformOp(), SetResetXformStack(), and SetXformOpOrder(), and consulted by GetOrderedXformOps() and GetLocalTransformation().


Declaration	`uniform token[] xformOpOrder`
C++ Type	VtArray<TfToken>
Usd Type	SdfValueTypeNames->TokenArray
Variability	SdfVariabilityUniform

inline UsdAttribute CreateXformOpOrderAttr() const#: See GetXformOpOrderAttr(), and also Create vs Get Property Methods for when to use Get vs Create. If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

inline UsdAttribute GetVisibilityAttr() const#

Visibility is meant to be the simplest form of “pruning” visibility that is supported by most DCC apps. Visibility is animatable, allowing a sub-tree of geometry to be present for some segment of a shot, and absent from others; unlike the action of deactivating geometry prims, invisible geometry is still available for inspection, for positioning, for defining volumes, etc.


Declaration	`token visibility = "inherited"`
C++ Type	TfToken
Usd Type	SdfValueTypeNames->Token
Allowed Values	inherited, invisible

inline UsdAttribute CreateVisibilityAttr() const#: See GetVisibilityAttr(), and also Create vs Get Property Methods for when to use Get vs Create. If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

inline UsdAttribute GetPurposeAttr() const#

Purpose is a classification of geometry into categories that can each be independently included or excluded from traversals of prims on a stage, such as rendering or bounding-box computation traversals.

See UsdGeom_ImageablePurpose for more detail about how purpose is computed and used.


Declaration	`uniform token purpose = "default"`
C++ Type	TfToken
Usd Type	SdfValueTypeNames->Token
Variability	SdfVariabilityUniform
Allowed Values	default, render, proxy, guide

inline UsdAttribute CreatePurposeAttr() const#: See GetPurposeAttr(), and also Create vs Get Property Methods for when to use Get vs Create. If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

inline UsdRelationship GetProxyPrimRel() const#

The proxyPrim relationship allows us to link a prim whose purpose is “render” to its (single target) purpose=”proxy” prim. This is entirely optional, but can be useful in several scenarios:

In a pipeline that does pruning (for complexity management) by deactivating prims composed from asset references, when we deactivate a purpose=”render” prim, we will be able to discover and additionally deactivate its associated purpose=”proxy” prim, so that preview renders reflect the pruning accurately.

DCC importers may be able to make more aggressive optimizations for interactive processing and display if they can discover the proxy for a given render prim.

With a little more work, a Hydra-based application will be able to map a picked proxy prim back to its render geometry for selection.

Note

It is only valid to author the proxyPrim relationship on prims whose purpose is “render”.

inline UsdRelationship CreateProxyPrimRel() const#: See GetProxyPrimRel(), and also Create vs Get Property Methods for when to use Get vs Create.

UsdPrim GetPrim() const#: Return this schema object’s held prim.

SdfPath GetPath() const#: Return the SdfPath to this schema object’s held prim.

inline explicit operator bool() const#

Check if this schema object is compatible with it’s held prim and that the prim is valid.

A typed schema object is compatible if the held prim’s type is or is a subtype of the schema’s type. Based on prim.IsA().

An API schema object is compatible if the API is of type SingleApplyAPI or UsdSchemaType::MultipleApplyAPI, and the schema has been applied to the prim. Based on prim.HasAPI.

This method invokes polymorphic behaviour.