Home > three-story-controls > CameraRig
The CameraRig holds the camera, and can respond to CameraActions such as Pan/Tilt/Dolly etc. It can also be controlled along a given path (in the form of an AnimationClip), or tweened to specified points.
Signature:
export declare class CameraRig extends EventDispatcher Extends: EventDispatcher
The rig is constructed of three objects, analagous to a body, head and eyes. The camera is nested in the eyes and is never transformed directly.
Instead of specifying the axis to rotate/translate the camera, CameraActions are used. The rotation order of actions is always Pan then Tilt then Roll. The mapping of these actions to axes depends on the up axis, which defaults to Y (but can be changed with the setUpAxis() method):
* CameraAction.Pan rotates around the Y axis
* CameraAction.Tilt rotates around the X axis
* CameraAction.Roll rotates around the Z axis
* CameraAction.Dolly translates on the Z axis
* CameraAction.Truck translates on the X axis
* CameraAction.Pedestal translates on the Y axis
Translations will be applied to the 'body' of the rig, and rotations to the 'eyes'. If an animation clip is provided, or the camera is tweened to a specific location, the rotations will be applied to the 'head', thus leaving the 'eyes' free to 'look around' from this base position.
Additionally, the default setup assumes that the rig will move forward/backward (Dolly) in the direction the camera is panned to. This can be configured through translateAlong property. It can also be overwritten by providing the component name to the do() method, see ThreeDOFControls implementation for an example.
To move the rig along a specified path, use the setAnimationClip() method, and set the names for the Translation and Rotation objects to match those of the clip. The clip should have a VectorKeyframeTrack for the outer position/translation object, and a QuaternionKeyframeTrack for the inner orientation/rotation object.
See CameraMoveStartEvent, CameraMoveUpdateEvent and CameraMoveEndEvent for emitted event signatures.
| Constructor | Modifiers | Description |
|---|---|---|
| (constructor)(camera, scene) | Constructs a new instance of the CameraRig class |
| Property | Modifiers | Type | Description |
|---|---|---|---|
| camera | Camera | ||
| scene | Scene | ||
| translateAlong | TranslateGuide |
| Method | Modifiers | Description |
|---|---|---|
| assemble() | Place the camera back in the rig | |
| disassemble() | Disassemble the camera from the rig and attach it to the scene. | |
| do(action, amount, rigComponent) | Main method for controlling the camera | |
| flyTo(position, quaternion, duration, ease, useSlerp) | Transition to a specific position and orientation in world space. Transform on eyes will be reset to 0 as a result of this. | |
| flyToKeyframe(frame, duration, ease) | Transition to a specific keyframe on the animation clip Transform on eyes will be reset to 0 as a result of this. | |
| getAxisFor(action) | Get the axis for a given action | |
| getAxisVectorFor(action) | Get the axis' vector for a given action | |
| getRotationOrder() | Get the rotation order as a string compatible with what three.js uses | |
| getWorldCoordinates() | Get world position and orientation of the camera | |
| isInRig() | Whether the camera is currently attached to the rig | |
| isMoving() | If the camera is in the middle of a transition | |
| packTransform() | Packs transfrom into the body and head, and 0s out transforms of the eyes. Useful for preparing the rig for control through an animation clip. | |
| setAnimationClip(clip, translationObjectName, rotationObjectName) | Set an animation clip for the rig | |
| setAnimationKeyframe(frame) | ||
| setAnimationPercentage(percentage) | ||
| setAnimationTime(time) | ||
| setUpAxis(axis) | Set the up axis for the camera | |
| setWorldCoordinates({ position, quaternion }) | Sets world coordinates for the camera, and configures rig component transforms accordingly. | |
| unpackTransform() | Unpacks the current camera world coordinates and distributes transforms across the rig componenets. |