RealityServer® Extras

Class: Transform_target

RS.Transform_target

The Transform_target class adds look at functionality to the RS.Transform class.

new RS.Transform_target (location, target_point, up, nominal_up)

The default constructor initializes with an identity matrix looking at the point 0, 0, -1.

If location, target_point and up are provided then a look at is performed with those values. Note that the provided up direction will not be set as the nominal up direction.

If an explicit nominal_up is passed this will be used as the nominal up direction. If this is done without look up parameters then the target point will be set to ensure that the up and look direction do not coincide.

If called with only 1 argument then this is used as the nominal up.

Name Type Description
location RS.Vector3 optional

the transform location.
target_point RS.Vector3 optional

the point to look at.
up RS.Vector3 optional

the up direction for the look at.
nominal_up RS.Vector3 optional

the nominal up direction.
Example
const z_up_transform = new Transform_target(Transform.Z_AXIS);

Members

follow_target_point Boolean

Whether the target point should be followed. If true then the transform will be locked to looking at the target point. If not then operations will still occur relative to the target point however the transform direction will remain the same.

Default Value:
  • true

target_point RS.Vector3

The target point

up_direction RS.Vector4

The nominal up direction. When performing look at operations the transform will attempt to keep it's Y axis aligned with this direction. When set the transform will re-orient itself to the new up.

Default Value:
  • {x: 0, y: 1, z: 0}

Methods

clone ()RS.Transform_target

returns a copy of this Transform_target.

Returns:
Type Description
RS.Transform_target

look_at (location, target_point, up)

Makes the transform look at the given point from the given location using the optional given up vector. If up is not provided then the nominal up direction is used. If it is provided it does not change the internal nominal up direction.

Name Type Description
location RS.Vector3

the location.
target_point RS.Vector3

the point to look at.
up RS.Vector3 optional

the up direction.

look_at_target_point (reset_y_vector)

Rotate the transform to look at the target point.

Name Type Default Description
reset_y_vector Boolean false optional

if true then the transform will reset to be oriented up. Otherwise the current roll will be preserved.

orbit_around_target_point (dx, dy, dz, maintain_up)

Orbits around the target point by the given amount.

Name Type Default Description
dx Number

the X rotation in radians.
dy Number

the Y rotation in radians.
dz Number

the Z rotation in radians.
maintain_up Boolean true optional

if true then dy rotates around the nominal up direction so the rotation remains 'vertical'. If false then rotates around the transforms current Y axis.

rotate (dx, dy, dz, rotate_target_point)

Performs an Euler rotation on the transform in ZYX order. If rotate_target_point is set to true (or if follow_target_point is false) then the target point will be rotated around the translation vector.

If rotate_target_point is false, and we are following the target point then this will only apply the dz rotation as we must keep looking at the target point.

Name Type Default Description
dx Number

X rotation in radians.
dy Number

Y rotation in radians.
dz Number

Z rotation in radians.
rotate_target_point Boolean true optional

if true then the target point is rotated by the same amount.

rotate_around_axis (axis, angle, in_object_space, rotate_target_point)

Rotates the transform about the given axis by the given angle in radians. If in_object_space is true, then the axis will be transform into object space first. If rotate_target_point is true then the target point is also rotated.

Name Type Default Description
axis RS.Vector3

the axis to rotate around.
angle Number

the amount to rotate by in radians.
in_object_space Boolean true optional

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

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

rotate_around_point (point, dx, dy, dz, rotate_target_point, maintain_up)

Performs a ZYX Euter rotation around a given world space point. If `rotate_target_point`` is true and the target point is not at the same location as the given point, then the target point is also rotated around the point.

Name Type Default Description
point RS.Vector3

the point to rotate around.
dx Number

the X rotation in radians.
dy Number

the Y rotation in radians.
dz Number

the Z rotation in radians.
rotate_target_point Boolean true optional

if true then the target point is rotated by the same amount. Otherwise we keep looking at the current target point.
maintain_up Boolean true optional

if true then dy rotates around the nominal up direction so the rotation remains 'vertical'. If false then rotates around the transforms current Y axis.

set_rotation (x, y, z, rotate_target_point)

This sets the rotation of the transform. If rotate_target_point is `true`` then the target point will be rotated around the translation vector.

If rotate_target_point is false, and we are following the target point then this will only apply the z rotation as we must keep looking at the target point.

Name Type Default Description
x Number

X rotation in radians.
y Number

Y rotation in radians.
z Number

Z rotation in radians.
rotate_target_point Boolean true optional

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

set_rotation_around_axis (axis, angle, rotate_target_point)

Sets the rotation of the transform about the given axis by the given angle in radians. If rotate_target_point is set to true then the target point is also rotated.

Name Type Default Description
axis RS.Vector3

the axis to rotate around.
angle Number

the amount to rotate by in radians.
rotate_target_point Boolean true optional

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

set_target_point (target_point, reset_y_vector)

Sets the target point. Target point CANNOT be the same as the translation vector.

Name Type Default Description
target_point RS.Vector3

the target point.
reset_y_vector Boolean true optional

if true and we are following the target point then the transform will reset to be oriented up. Otherwise the current roll will be preserved.

set_translation (x, y, z, translate_target)

Sets the translation in world space. Resulting translation CANNOT be the same as the target point.

Name Type Default Description
x Number

the X translation.
y Number

the Y translation.
z Number

the Z translation.
translate_target 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.

translate (dx, dy, dz, in_object_space, translate_target)

Translates the transform either world space or object space. Resulting target point CANNOT be the same as translation vector.

Name Type Default Description
dx Number

the amount to translate in X.
dy Number

the amount to translate in Y.
dz Number

the amount to translate in Z.
in_object_space Boolean true optional

if true then translates in object space, otherwise world.
translate_target Boolean true optional

if true then the target point is translated by the same amount. Otherwise the transform will look at the old target point after translation.

translate_target_point (dx, dy, dz, in_object_space)

Translates the target point in either world space or object space. Resulting target point CANNOT be the same as translation vector.

Name Type Default Description
dx Number

the amount to translate in X.
dy Number

the amount to translate in Y.
dz Number

the amount to translate in Z.
in_object_space Boolean true optional

if true then translates in object space, otherwise world.