Camera

Source (.js)Source (.d.ts)

Introduction

vtkCamera is a virtual camera for 3D rendering. It provides methods to position and orient the view point and focal point. Convenience methods for moving about the focal point also are provided. More complex methods allow the manipulation of the computer graphics model including view up vector, clipping planes, and camera perspective.

Methods

applyTransform

Apply a transform to the camera. The camera position, focal-point, and view-up are re-calculated using the transform's matrix to multiply the old points by the new transform.

Argument	Type	Required	Description
transformMat4	mat4	Yes	Transform matrix.

azimuth

Rotate the camera about the view up vector centered at the focal point.

Argument	Type	Required	Description
angle	Number	Yes	The angle value.

computeCameraLightTransform

computeClippingRange

Argument	Type	Required	Description
bounds	Bounds	Yes	The bounds value.

computeDistance

This method must be called when the focal point or camera position changes

computeViewParametersFromPhysicalMatrix

the provided matrix should include translation and orientation only mat is physical to view

Argument	Type	Required	Description
mat	mat4	Yes	The physical matrix.

computeViewParametersFromViewMatrix

Argument	Type	Required	Description
vmat	mat4	Yes	The view matrix.

deepCopy

Not implemented yet

Argument	Type	Required	Description
sourceCamera	vtkCamera	Yes	The camera source.

dolly

Move the position of the camera along the view plane normal. Moving towards the focal point (e.g., > 1) is a dolly-in, moving away from the focal point (e.g., < 1) is a dolly-out.

Argument	Type	Required	Description
amount	Number	Yes	The amount value.

elevation

Rotate the camera about the cross product of the negative of the direction of projection and the view up vector, using the focal point as the center of rotation.

Argument	Type	Required	Description
angle	Number	Yes	The angle value.

extend

Method use to decorate a given object (publicAPI+model) with vtkRenderer characteristics.

Argument	Type	Required	Description
publicAPI		Yes	object on which methods will be bounds (public)
model		Yes	object on which data structure will be bounds (protected)
initialValues	ICameraInitialValues	No	(default: {})

getCameraLightTransformMatrix

Not implemented yet

getClippingRange

Get the location of the near and far clipping planes along the direction of projection.

getClippingRangeByReference

Get the location of the near and far clipping planes along the direction of projection.

getCompositeProjectionMatrix

Argument	Type	Required	Description
aspect	Number	Yes	Camera frustum aspect ratio.
nearz	Number	Yes	Camera frustum near plane.
farz	Number	Yes	Camera frustum far plane.

getDirectionOfProjection

Get the vector in the direction from the camera position to the focal point.

getDirectionOfProjectionByReference

Get the vector in the direction from the camera position to the focal point.

getDistance

Get the distance from the camera position to the focal point.

getExplicitProjectionMatrix

Get the explicit projection matrix, or null when the camera computes its projection from its standard parameters.

getFocalPoint

Get the focal of the camera in world coordinates.

getFocalPointByReference

Get the focal of the camera in world coordinates.

getFreezeFocalPoint

Get the value of the FreezeDolly instance variable.

getFrustumPlanes

Get the plane equations that bound the view frustum.

Argument	Type	Required	Description
aspect	Number	No	Camera frustum aspect ratio (default: 1.0).
planes	Float64Array	No	Optional array to fill with the plane equations.

getModelTransformMatrix

Get the model transform matrix for the camera. This matrix could be used for model related transformations such as scale, shear, rotations and translations.

Returns

Type	Description
mat4	mat The value of the model transform matrix.

getOrientation

Not implemented yet Get the orientation of the camera.

getOrientationWXYZ

Not implemented yet Get the orientation of the camera.

getParallelProjection

Get the value of the ParallelProjection instance variable. This determines if the camera should do a perspective or parallel projection.

getParallelScale

Get the scaling used for a parallel projection.

getPhysicalScale

getPhysicalToWorldMatrix

Argument	Type	Required	Description
result	mat4	Yes	The world matrix.

getPhysicalTranslation

getPhysicalTranslationByReference

getPhysicalViewNorth

getPhysicalViewNorthByReference

getPhysicalViewUp

getPhysicalViewUpByReference

getPosition

Get the position of the camera in world coordinates.

getPositionByReference

Get the position of the camera in world coordinates.

getProjectionMatrix

Get the projection matrix.

Argument	Type	Required	Description
aspect	Number	Yes	Camera frustum aspect ratio.
nearz	Number	Yes	Camera frustum near plane.
farz	Number	Yes	Camera frustum far plane.
out	mat4	No	Optional output matrix to mutate and return, instead of allocating a new one.

getRoll

Not implemented yet Get the roll angle of the camera about the direction of projection.

getScreenBottomLeft

Get top left corner point of the screen.

getScreenBottomLeftByReference

getScreenBottomRight

Get bottom left corner point of the screen

getScreenBottomRightByReference

getScreenTopRight

getScreenTopRightByReference

getThickness

Get the center of the window in viewport coordinates.

getUseHorizontalViewAngle

Get the value of the UseHorizontalViewAngle.

getUseOffAxisProjection

Get use offaxis frustum.

getViewAngle

Get the camera view angle.

getViewMatrix

Get the view transform

getViewPlaneNormal

Get the ViewPlaneNormal. This vector will point opposite to the direction of projection, unless you have created a sheared output view using SetViewShear/SetObliqueAngles.

getViewPlaneNormalByReference

Get the ViewPlaneNormal by reference.

getViewUp

Get ViewUp vector.

getViewUpByReference

Get ViewUp vector by reference.

getWindowCenter

Get the center of the window in viewport coordinates. The viewport coordinate range is ([-1,+1],[-1,+1]).

getWindowCenterByReference

getWorldToPhysicalMatrix

Argument	Type	Required	Description
result	mat4	Yes

newInstance

Method use to create a new instance of vtkCamera with its focal point at the origin, and position=(0,0,1). The view up is along the y-axis, view angle is 30 degrees, and the clipping range is (.1,1000).

Argument	Type	Required	Description
initialValues	ICameraInitialValues	No	for pre-setting some of its content

orthogonalizeViewUp

Recompute the ViewUp vector to force it to be perpendicular to camera.focalpoint vector.

physicalOrientationToWorldDirection

Argument	Type	Required	Description
ori	Array[Number]	Yes

pitch

Rotate the focal point about the cross product of the view up vector and the direction of projection, using the camera's position as the center of rotation.

Argument	Type	Required	Description
angle	Number	Yes	The value of the angle.

roll

Rotate the camera about the direction of projection.

Argument	Type	Required	Description
angle	Number	Yes	The value of the angle.

setClippingRange

Set the location of the near and far clipping planes along the direction of projection.

Argument	Type	Required	Description
clippingRange	Range	Yes

setClippingRange

Set the location of the near and far clipping planes along the direction of projection.

Argument	Type	Required	Description
near	Number	Yes	The near clipping planes.
far	Number	Yes	The far clipping planes.

setClippingRangeFrom

Set the location of the near and far clipping planes along the direction of projection.

Argument	Type	Required	Description
clippingRange	Range	Yes

setDeviceAngles

Used to handle convert js device orientation angles when you use this method the camera will adjust to the device orientation such that the physicalViewUp you set in world coordinates looks up, and the physicalViewNorth you set in world coorindates will (maybe) point north

NOTE WARNING - much of the documentation out there on how orientation works is seriously wrong. Even worse the Chrome device orientation simulator is completely wrong and should never be used. OMG it is so messed up.

how it seems to work on iOS is that the device orientation is specified in extrinsic angles with a alpha, beta, gamma convention with axes of Z, X, Y (the code below substitutes the physical coordinate system for these axes to get the right modified coordinate system.

Argument	Type	Required	Description
alpha	Number	Yes	The value of the alpha.
beta	Number	Yes	The value of the beta.
gamma	Number	Yes	The value of the gamma.
screen	Number	Yes	The value of the screen.

setDirectionOfProjection

Set the direction of projection.

Argument	Type	Required	Description
x	Number	Yes	The x coordinate.
y	Number	Yes	The y coordinate.
z	Number	Yes	The z coordinate.

setDistance

Move the focal point so that it is the specified distance from the camera position.

This distance must be positive.

Argument	Type	Required	Description
distance	Number	Yes	The value of the distance.

setExplicitProjectionMatrix

Set the explicit projection matrix, or null to use a projection computed from the camera's standard parameters.

setFocalPoint

Set the focal of the camera in world coordinates.

Argument	Type	Required	Description
x	Number	Yes	The x coordinate.
y	Number	Yes	The y coordinate.
z	Number	Yes	The z coordinate.

setFocalPointFrom

Set the focal of the camera in world coordinates.

Argument	Type	Required	Description
focalPoint	Vector3	Yes

setFreezeFocalPoint

Set the value of the FreezeDolly instance variable.

Argument	Type	Required	Description
freezeFocalPoint	Boolean	Yes

setModelTransformMatrix

Set the model transform matrix for the camera. This matrix could be used for model related transformations such as scale, shear, rotations and translations. It is applied to world coordinates before the camera transform, so the resulting view matrix is view * modelTransform. A common use is a global vertical exaggeration, e.g. a scale of (1, 1, 10) on world Z.

The matrix is in gl-matrix column-major order, like userMatrix on vtkProp3D, so a matrix from vtkTransform or vtkMatrixBuilder can be passed directly.

Note the camera pose (position, focalPoint, viewUp, clippingRange) is interpreted after this transform is applied, so it is expressed in transformed space rather than world space.

Argument	Type	Required	Description
mat	mat4	Yes	The value of the model transform matrix.

setObliqueAngles

Not implement yet Set the oblique viewing angles. The first angle, alpha, is the angle (measured from the horizontal) that rays along the direction of projection will follow once projected onto the 2D screen. The second angle, beta, is the angle between the view plane and the direction of projection. This creates a shear transform x' = x + dzcos(alpha)/tan(beta), y' = dzsin(alpha)/tan(beta) where dz is the distance of the point from the focal plane. The angles are (45,90) by default. Oblique projections commonly use (30,63.435).

Argument	Type	Required	Description
alpha	Number	Yes	The aplha angle value.
beta	Number	Yes	The beta angle value.

setOrientationWXYZ

Set the value of the OrientationWXYZ.

Argument	Type	Required	Description
degrees	Number	Yes
x	Number	Yes	The x coordinate.
y	Number	Yes	The y coordinate.
z	Number	Yes	The z coordinate.

setParallelProjection

Set the value of the ParallelProjection.

Argument	Type	Required	Description
parallelProjection	Boolean	Yes	The value of the parallelProjection.

setParallelScale

Set the value of the parallelScale.

Argument	Type	Required	Description
parallelScale	Number	Yes	The value of the parallelScale.

setPhysicalScale

Set the value of the physicalScale.

Argument	Type	Required	Description
physicalScale	Number	Yes	The value of the the physicalScale.

setPhysicalTranslation

Set the value of the physicalTranslation.

Argument	Type	Required	Description
x	Number	Yes	The x coordinate.
y	Number	Yes	The y coordinate.
z	Number	Yes	The z coordinate.

setPhysicalTranslationFrom

Set the value of the physicalTranslation.

Argument	Type	Required	Description
physicalTranslation	Array[Number]	Yes	The value of the physicalTranslation.

setPhysicalViewNorth

Argument	Type	Required	Description
x	Number	Yes	The x coordinate.
y	Number	Yes	The y coordinate.
z	Number	Yes	The z coordinate.

setPhysicalViewNorthFrom

Argument	Type	Required	Description
physicalViewNorth	Array[Number]	Yes

setPhysicalViewUp

Argument	Type	Required	Description
x	Number	Yes	The x coordinate.
y	Number	Yes	The y coordinate.
z	Number	Yes	The z coordinate.

setPhysicalViewUpFrom

Argument	Type	Required	Description
physicalViewUp	Array[Number]	Yes

setPosition

Set the position of the camera in world coordinates.

Argument	Type	Required	Description
x	Number	Yes	The x coordinate.
y	Number	Yes	The y coordinate.
z	Number	Yes	The z coordinate.

setPositionAndFocalPoint

Set the camera's position and focal point in world coordinates.

Argument	Type	Required	Description
position	Array[Number]	Yes	The position.
focalPoint	Array[Number]	Yes	The focal point.

setRoll

Set the roll angle of the camera about the direction of projection.

Argument	Type	Required	Description
angle	Number	Yes	The value of the roll angle.

setScreenBottomLeft

Set top left corner point of the screen.

This will be used only for offaxis frustum calculation.

Argument	Type	Required	Description
screenBottomLeft	Vector3	Yes	The screenBottomLeft coordiante.

setScreenBottomLeft

Set top left corner point of the screen.

This will be used only for offaxis frustum calculation.

Argument	Type	Required	Description
x	Number	Yes	The x coordinate.
y	Number	Yes	The y coordinate.
z	Number	Yes	The z coordinate.

setScreenBottomLeftFrom

Set top left corner point of the screen.

Argument	Type	Required	Description
screenBottomLeft	Vector3	Yes	The screenBottomLeft coordiante.

setScreenBottomRight

Set bottom right corner point of the screen.

Argument	Type	Required	Description
screenBottomRight	Vector3	Yes	The screenBottomRight coordiante.

setScreenBottomRight

Argument	Type	Required	Description
x	Number	Yes	The x coordinate.
y	Number	Yes	The y coordinate.
z	Number	Yes	The z coordinate.

setScreenBottomRightFrom

Set bottom right corner point of the screen.

Argument	Type	Required	Description
screenBottomRight	Vector3	Yes	The screenBottomRight coordiante.

setScreenTopRight

Set top right corner point of the screen.

This will be used only for offaxis frustum calculation.

Argument	Type	Required	Description
screenTopRight	Vector3	Yes	The screenTopRight coordiante.

setScreenTopRight

Set top right corner point of the screen.

This will be used only for offaxis frustum calculation.

Argument	Type	Required	Description
x	Number	Yes	The x coordinate.
y	Number	Yes	The y coordinate.
z	Number	Yes	The z coordinate.

setScreenTopRightFrom

Set top right corner point of the screen.

Argument	Type	Required	Description
screenTopRight	Vector3	Yes	The screenTopRight coordiante.

setThickness

Set the distance between clipping planes.

This method adjusts the far clipping plane to be set a distance 'thickness' beyond the near clipping plane.

Argument	Type	Required	Description
thickness	Number	Yes

setThicknessFromFocalPoint

Argument	Type	Required	Description
thickness	Number	Yes	The value of the thickness.

setUseHorizontalViewAngle

Set the value of the useHorizontalViewAngle.

Argument	Type	Required	Description
useHorizontalViewAngle	Boolean	Yes	The value of the useHorizontalViewAngle.

setUseOffAxisProjection

Set use offaxis frustum.

OffAxis frustum is used for off-axis frustum calculations specifically for stereo rendering. For reference see "High Resolution Virtual Reality", in Proc. SIGGRAPH '92, Computer Graphics, pages 195-202, 1992.

Argument	Type	Required	Description
useOffAxisProjection	Boolean	Yes	The value of the useOffAxisProjection.

setViewAngle

Set the camera view angle, which is the angular height of the camera view measured in degrees.

Argument	Type	Required	Description
viewAngle	Number	Yes	The value of the viewAngle.

setViewMatrix

Set the view matrix for the camera.

Argument	Type	Required	Description
mat	mat4	Yes	The value of the view matrix.

setViewUp

Set the view up direction for the camera.

Argument	Type	Required	Description
viewUp	Vector3	Yes	The viewUp coordinate.

setViewUp

Set the view up direction for the camera.

Argument	Type	Required	Description
x	Number	Yes	The x coordinate.
y	Number	Yes	The y coordinate.
z	Number	Yes	The z coordinate.

setViewUpFrom

Set the view up direction for the camera.

Argument	Type	Required	Description
viewUp	Vector3	Yes	The viewUp coordinate.

setWindowCenter

Set the center of the window in viewport coordinates.

The viewport coordinate range is ([-1,+1],[-1,+1]).

This method is for if you have one window which consists of several viewports, or if you have several screens which you want to act together as one large screen.

Argument	Type	Required	Description
x	Number	Yes	The x coordinate.
y	Number	Yes	The y coordinate.

setWindowCenterFrom

Set the center of the window in viewport coordinates from an array.

Argument	Type	Required	Description
windowCenter	Range	Yes

translate

Argument	Type	Required	Description
x	Number	Yes	The x coordinate.
y	Number	Yes	The y coordinate.
z	Number	Yes	The z coordinate.

yaw

Rotate the focal point about the view up vector, using the camera's position as the center of rotation.

Argument	Type	Required	Description
angle	Number	Yes	The value of the angle.

zoom

In perspective mode, decrease the view angle by the specified factor.

Argument	Type	Required	Description
factor	Number	Yes	The value of the zoom factor.