API Docs

Class: Rotator

PD.Cursors. Rotator

Stores an interactive rotation manipulator.

A rotator is basically a ring with a direction indicator that can be dynamically rotated around the center of the cursor. It typically has a radius that places it further out than any other manipulators so that it can be selected and dragged without interference.

new Rotator(cursor, axis, offset)

Creates a new rotation manipulator.

Parameters:
Name Type Default Description
cursor PD.Cursor

The cursor that hosts this manipulator.
axis PD.AXIS 0

The rotation axis relative to the parent cursor.
offset number 2.5

The radius of the rotator ring.
Author:
  • drajmarsh
Returns:

Returns a new manipulator as a mesh object.

Type
THREE.Mesh

Extends

Members

:boolean

active

Whether or not the manipulator is active.

NOTE: Prefer this flag over the visible property when activating or deactivating a manipulator as visibility is set dynamically based on view angle, etc.

Active manipulators are added as children of the parent cursor mesh so that they are rendered in the model when the cursor is rendered. Inactive manipulators are still stored and updated with all the other manipulators, but are removed from the parent cursor mesh so that they are not rendered.

Type
  • boolean
Inherited From:
Overrides:
:PD.AXIS

axis

Stores the value of the axis parameter used to create the manipulator.

Type
Inherited From:
Overrides:
:THREE.Vector3

center

Stores the position of the center of the manipulator in absolute model space units. This is the point used when testing for proximity as the position property of the manipulator mesh must remain in unscaled units relative to the cursor position. Thus, this gives the centre position of the actual arrow or indicator itself.

Type
  • THREE.Vector3
Inherited From:
Overrides:
:PD.Cursor

cursor

The cursor that hosts this manipulator.

Type
Inherited From:
Overrides:
:number

dragReferenceAngle

Stores the initial angle when manipulator is rotated.

Type
  • number
:THREE.Vector3

dragReferencePos

For some manipulators, their center may be different from the actual point they are dragging. This is mainly for cursors that set the size or scale of something - such as a bounding box. Whilst their center positions will likely be located outside the box, the point that they are actually dragging, and to which all snapping should be tested against, will actually be the corners of the box or the center of a face.

Type
  • THREE.Vector3
Inherited From:
Overrides:
:number

dragStartAngle

Stores the initial angle when manipulator was selected.

Type
  • number
:number

dragStartPos

Stores the initial angle when manipulator was selected.

Type
  • number
:number

flipped

The axis about which this manipulator is flipped within the current 3D view.

Type
  • number
Inherited From:
Overrides:
:boolean

isDirect

Whether or not the manipulator was clicked in the 'direction' area.

When dragging in the direction area, the cursor will look for hover points in the model so that the rotator can point directly at them.

Type
  • boolean
:boolean

isManipulator <readonly>

A flag identifying this object as a 3D cursor manipulator.

Type
  • boolean
Inherited From:
Overrides:
:boolean

isRotator <readonly>

A flag identifying this object as a 3D cursor rotator.

Type
  • boolean
:number

offset

The distance the manipulator is offset from the cursor center, measured from the center of this manipulator along the assigned vector line, if any. If no axis is given or the offset value is zero, the manipulator will be located at the center of the cursor or, if it is dragging a bounding box, exactly on one of its corners or faces.

Type
  • number
Inherited From:
Overrides:
:THREE.Vector3|null

plane

The plane used to select the manipulator with the cursor.

Type
  • THREE.Vector3 | null
Inherited From:
Overrides:
:PD.MANIPULATOR

shape

Stores the value of the shape parameter used to create the manipulator.

Type
Inherited From:
Overrides:
:THREE.Vector3|null

vector

A 3D vector defining the linear path or axis that this manipulator is constrained to. This is typically set automatically from the axis parameter, but can be given using the optional vector parameter.

Type
  • THREE.Vector3 | null
Inherited From:
Overrides:

Methods

checkToFlip(view_axis)

Flips the orientation of the manipulator by 90deg to best suit the view.

Parameters:
Name Type Description
view_axis THREE.Vector3

The axis closest to the view direction.
Inherited From:
Overrides:

computeSelectionDistance(cursor, point)

Calculates the selection distance to the given point.

This method is used to determine the closest manipulator to the given point on the same plane. As this is typically done when the manipulator is being selected, it also stores the start angle and drag reference position so that interactive dragging is both stable and accurate.

Parameters:
Name Type Description
cursor PD.Cursor

The parent cursor requesting the distance.
point THREE.Vector3

The point to compute the distance to.
Inherited From:
Overrides:
Returns:

Returns the selection distance.

Type
number

getRotation()

Retrieves the current axial rotation angle.

Returns:

Returns the angle in radians.

Type
number

getRotationAngle(point)

Calculates the new angle so that the angle .

Parameters:
Name Type Description
point THREE.Vector3

The point to compute the new angle from.
Returns:

Returns the absolute rotation angle in radians.

Type
number

handleMoveByRay(cursor, event)

Applies the effect of moving the manipulator to the host cursor.

Parameters:
Name Type Description
cursor PD.Cursor

The parent cursor undergoing the rotation.
event object

The event that generated the rotation.
Inherited From:
Overrides:

initialiseAxis(axis [, vector])

Sets up the manipulator based on the given axis.

Parameters:
Name Type Argument Description
axis PD.AXIS

The axis of the manipulator.
vector THREE.Vector3 | null <optional>

An optional vector when axis is PD.AXIS.VECTOR.
Overrides:

resetAxis()

Resets the manipulator's rotation and selection plane.

Inherited From:
Overrides:
Returns:

Returns this manipulator to support method chaining.

Type
PD.Cursors.Manipulator

setRotation(angle)

Sets the rotation angle of this cursor rotator.

Parameters:
Name Type Description
angle number

The new rotation angle, in radians.
Returns:

Returns true if the angle changed.

Type
boolean

setRotationFromPoint(point)

Sets a new absolute rotation angle towards the given point.

Parameters:
Name Type Description
point THREE.Vector3

The point to compute the new angle from.

setSelected(cursor, state)

Sets the selection state of this manipulator.

Parameters:
Name Type Description
cursor PD.Cursor

The parent cursor making the selection.
state boolean

Whether selected or de-selected.
Inherited From:
Overrides:

showStatusAngle(angle)

Displays the current angle as a status message.

Parameters:
Name Type Description
angle number

The current angle in radians.

startRelativeRotation(point)

Stores a reference position and current rotation of the manipulator.

This method must be called prior to any subsequent calls to updateRelativeRotation().

Parameters:
Name Type Description
point THREE.Vector3

The relative rotation reference point, defaults to cursor.pointerPos.

update(cursor_size [, abs_offset])

Update both the relative and absolute positions of manipulator.

Parameters:
Name Type Argument Default Description
cursor_size number

The size of the cursor in model units.
abs_offset number <optional>
 0

An optional additional offset in model units.
Overrides:

updateRelativeRotation(cursor, point [, snap])

Calculates the new angle relative to the centre and reference position.

The results of this method are only valid after a call to the startRelativeRotation() which snapshots the reference position and angle, on which this method is based.

Parameters:
Name Type Argument Default Description
cursor PD.Cursor

The parent cursor undergoing the rotation.
point THREE.Vector3

The point to compute the new angle from.
snap boolean <optional>
 true

Whether to apply angle snapping, defaults to true.
Returns:

Returns true if the rotation angle changed.

Type
boolean