RealityServer® Extras

Class: Camera

RS.Camera

The Camera class allows simple camera manipulation. Events are emitted whenever underlying properties are changed to allow the user to update RealityServer® or other system componenets as necessary.

new RS.Camera ()

Creates a perspective Y up camera with a 90 degree field of view.

Members

RS.Camera.Y_UP static

Enum representing a Y up camera

RS.Camera.Z_UP static

Enum representing a Z up camera

aperture Number

The aperture of the camera. When changed fires a RS.Camera#event:aperture-changed event.

clip_max

The clip max of the view frustum. When changed fires a RS.Camera#event:clip_max-changed event

clip_min

The clip min of the view frustum. When changed fires a RS.Camera#event:clip_min-changed event

direction RS.Vector3 readonly

The look direction vector of the camera.

field_of_view Number

The half field of view of the camera in radians. When changed fires a RS.Camera#event:aperture-changed event

focal Number

The focal length of the camera. When changed fires a RS.Camera#event:focal-changed event.

follow_target_point Boolean

Whether to follow the target point or not. When true the camera will always look at the target point, when false it can be rotated away. When set to true will fire a RS.Camera#event:transform-changed event.

Default Value:
  • true

location RS.Vector3 readonly

The position of the camera in world space.

matrix RS.Matrix4x4

The matrix of the transform. When set fires a RS.Camera#event:transform-changed event

orthographic Boolean

Whether the camera is orthographic or perspective. When changed fires a RS.Camera#event:orthographic-changed event

The right direction vector of the camera.

scene_up_direction Number

The nominal up direction of the camera. Can be either RS.Camera.Y_UP or RS.Camera.Z_UP. When set the camera will rotate to match the new up direction and fires a RS.Camera#event:up_direction-changed and RS.Camera#event:transform-changed event.

target_point RS.Vector3

The target point of the camera. When set fires a RS.Camera#event:target_point-changed event. If the camera is following the target point then it is rotated to look at the target point and fires a RS.Camera#event:transform-changed event.

transform RS.Transform_target

The transform of the camera. When changed fires a RS.Camera#event:transform-changed event and a RS.Camera#event:target_point-changed event.

up RS.Vector3 readonly

The actual up direction vector of the camera.

Methods

clone ()RS.Camera

Returns a copy of this Camera.

Returns:
Type Description
RS.Camera

dolly (depth, shift_target_point)

Dollies the camera.

Name Type Default Description
depth Number

The amount to move along the direction vector.
shift_target_point Boolean false optional

If true then dollies the target as well.
Fires:

elevate (vertical)

Elevates the camera and the target point

Name Type Description
vertical Number

The amount to move the camera up the up vector.
Fires:

equal (rhs)

Compares this camera to another. The camera are equal if the aperture, focal length, field of view and matrix are the same.

Name Type Description
rhs RS.Camera

the camera to compare

frame_points (fit_points, aspect, preserve_orientation)

Frames the camera around a set of points such that all points provided are visible within the camera frame.

Name Type Default Description
fit_points RS.Vector3

An array of RS.Vector3 points that the camera will be framed around.
aspect Number

The aspect ratio of the camera frame.
preserve_orientation Boolean true optional

When true the camera will keep pointing in the same direction, if false it will rotate to look at the center of the points.
Fires:

level_camera ()

Forces the camera to be horizontal.

Fires:

look_at_target_point (reset_up_vector)

Makes the camera look at the current target point whether it is following it or not.

Name Type Default Description
reset_up_vector Boolean true optional

if true then the camera roll will be reset.
Fires:

orbit (vertical_axis, horizontal_axis, orbit_point, level_camera)

Orbits the camera. This method orbits using the initial up and right reference vectors.

Name Type Default Description
vertical_axis Number

The amount to orbit around the up vector in radians.
horizontal_axis Number

The amount to orbit aroung the right vector in radians.
orbit_point RS.Vector3 null optional

The point to orbit around, if provided then this becomes the new target point.
level_camera Boolean true optional

if true then orbit around the nominal up direction so the camera remains level. If false then rotates around the cameras current Y axis.
Fires:

orbit_around_point (point, vertical_axis, horizontal_axis, shift_target_point, level_camera)

Orbits the camera around a point in world space. This method acts much like the standard orbit function however if you choose to orbit around a different point than the target point you can also rotate the target point as well.

Name Type Default Description
point RS.Vector3

The point to orbit around, this will NOT change the target point.
vertical_axis Number

The amount to rotate around the up vector in radians.
horizontal_axis Number

The amount to rorate aroung the right vector in radians.
shift_target_point Boolean false optional

If true the target point will also rotate around the point.
level_camera Boolean true optional

if true then orbit around the nominal up direction so the camera remains level. If false then rotates around the cameras current Y axis.
Fires:

pan (horizontal, vertical, shift_target_point)

Pans the camera.

Name Type Default Description
horizontal Number

The amount to pan in the right direction.
vertical Number

The amount to pan in the up direction.
shift_target_point Boolean true optional

If true then pans the target as well.
Fires:

project_point (point, result)RS.Vector4

Projects a world space point into the camera focal plane. The X and Y coordinates will be in camera space and the Z coordinate will contain the correct depth value.

Name Type Description
point RS.Vector4

The point to transform.
result RS.Vector4

Receives the result of the transform.
Returns:
Type Description
RS.Vector4 The projected point.

project_point_to_pixel (point, resolution, pixel_aspect_ratio, result)RS.Vector4

Projects a world space point to a pixel coordinate. X/Y origin will be at the bottom left and Z coordinate will contain the correct depth value.

Name Type Description
point RS.Vector4

The point to transform.
resolution RS.Vector2

The image resolution to project to.
pixel_aspect_ratio Number optional

If provided the pixel aspect ratio to use, otherwise use 1. This would typically only be provided if non-square pixels are used.
result RS.Vector4

Receives the result of the transform.
Returns:
Type Description
RS.Vector4 The projected point.
Examples
// Project point <1,2,3> to Full HD resolution.
const point = camera.project_point_to_pixel(new RS.Vector4(1,2,3), { x: 1920, y: 1080 }, new RS.Vector4()));
// Project point <1,2,3> to Full HD resolution with rectangular pixels that have a 3:2 aspect ratio.
const point = camera.project_point_to_pixel(new RS.Vector4(1,2,3), { x: 1920, y: 1080 }, 3/2, new RS.Vector4()));

rotate (vertical_axis, horizontal_axis, direction_axis, shift_target_point)

Rotates the camera around itself.

Name Type Default Description
vertical_axis Number

Amount to rotate around the up vector in radians.
horizontal_axis Number

Amount to rotate around the right vector in radians.
direction_axis Number

Amount to rotate around the direction vector in radians (roll).
shift_target_point Boolean true optional

If true`` the target point will also rotate around the point. If false`` then only the direction_axis rotation will be applied.
Fires:

rotate_around_axis (axis, angle, in_camera_space, rotate_target_point)

Rotates the camera around a given axis.

Name Type Default Description
axis RS.Vector3

the axis to rotate around.
angle Number

the amount to rotate by in radians.
in_camera_space Boolean false optional

if true then the axis is in camera space, otherwise world.
rotate_target_point Boolean optional

if true then the target point is rotated by the same amount. Otherwise we keep looking at the current target point only.
Fires:

set_from_camera (camera)

Sets this camera from another.

Name Type Description
camera RS.Camera

the camera to set from or an object with the same properties.
Fires:

set_from_object (camera)

Sets the camera data from either an object with appropriate properties or from another Camera instance.

Name Type Description
camera RS.Camera

the camera to set from or an object with the same properties
Fires:

set_location (location, shift_target_point)

Moves the camera to a given location.

Name Type Default Description
location RS.Vector3

The position to move to.
shift_target_point Boolean true optional

If true then the target point is moved to be at the same relative location as previously. Otherwise the transform will look at the old target point after translation.
Fires:

set_target_point (target_point, reset_up_vector)

Sets the target point of the camera and, if following the target point, makes the camera look at it.

Name Type Default Description
target_point RS.Vector3

The new target point.
reset_up_vector Boolean true optional

if true, and following the target point, then the camera roll will be reset.
Fires:

spin (vertical_axis)

Spins the camera by rotating around the up vector of the camera. This also rotate the target point.

Name Type Description
vertical_axis Number

The amount, in radians, to spin.
Fires:

tilt (horizontal_axis)

Tilts the camera by rotating around the right vector of the camera. This also rotate the target point.

Name Type Description
horizontal_axis Number

The amount, in radians, to tilt.
Fires:

transform_direction (point, result)RS.Vector4

Transforms a world space direction into camera space.

Name Type Description
point RS.Vector4

The point to transform.
result RS.Vector4

Receives the result of the transform.
Returns:
Type Description
RS.Vector4 The transformed direction

transform_direction_to_world (direction, result)RS.Vector4

Transforms a camera space direction into world space.

Name Type Description
direction RS.Vector4

The direction to transform.
result RS.Vector4

Receives the result of the transform.
Returns:
Type Description
RS.Vector4 The transformed direction

transform_point (point, result)RS.Vector4

Transforms a world space point into camera space.

Name Type Description
point RS.Vector4

The point to transform.
result RS.Vector4

Receives the result of the transform.
Returns:
Type Description
RS.Vector4 The transformed point

transform_point_to_world (point, result)RS.Vector4

Transforms a camera space point into world space.

Name Type Description
point RS.Vector4

The point to transform.
result RS.Vector4

Receives the result of the transform.
Returns:
Type Description
RS.Vector4 The transformed point

translate (move, shift_target_point)

Moves the camera by the given amount

Name Type Default Description
move RS.Vector3

The vector to move along.
shift_target_point Boolean true optional

If true then the target point is moved as well, otherwise the camera will look at the old target point after translation.
Fires:

Events

aperture-changed

Aperture changed event.

Fired when the camera changes aperture

clip_max-changed

Clip max changed event.

Fired when the camera clip max changes

clip_min-changed

Clip max changed event.

Fired when the camera clip max changes

focal-changed

Focal changed event.

Fired when the camera changes focal

orthographic-changed

Orthographic changed event.

Fired when the camera changes between orthographic and perspective

target_point-changed

Target point changed event.

Fired when the camera target point

transform-changed

Transform changed event.

Fired whenever the underlying transform changes

up_direction-changed

Up direction changed event.

Fired when the camera up direction changes.