API Docs

Class: Manipulator

PD.Cursors. Manipulator

Stores an interactive cursor manipulator.

A manipulator is typically an arrow or a shape that the user can click on to drag the cursor around. Manipulators manage their own hit testing and can constrain exactly how the cursor moves when the manipulator is dragged, either limiting it to a specific vector, rotating around the center, etc.

Manipulators are also their own separate mesh so that they can be rotated and scaled dynamically in order to best suit the current model view.

new Manipulator(cursor, shape, axis, offset [, vector])

Creates a new cursor manipulator.

Parameters:
Name Type Argument Default Description
cursor PD.Cursor

The cursor that hosts this manipulator.
shape PD.MANIPULATOR

The displayed shape of this manipulator.
axis PD.AXIS 0

The offset axis relative to the parent cursor.
offset number 0

The relative distance along the offset axis.
vector THREE.Vector3 <optional>
 null

An optional vector when the given axis is PD.AXIS.VECTOR.
Author:
  • drajmarsh
Throws:

Throws an error a valid host cursor is not given.

Type
Error
Returns:

Returns a new manipulator as a mesh object.

Type
THREE.Mesh

Extends

  • THREE.Mesh

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
:PD.AXIS

axis

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

Type
: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
:PD.Cursor

cursor

The cursor that hosts this manipulator.

Type
: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
:number

flipped

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

Type
  • number
:boolean

isManipulator <readonly>

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

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
:THREE.Vector3|null

plane

The plane used to select the manipulator with the cursor.

Type
  • THREE.Vector3 | null
:PD.MANIPULATOR

shape

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

Type
: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

Methods

checkToFlip(view_axis, elevation_view)

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.
elevation_view boolean

Whether the view is side-on.

computeSelectionDistance(cursor, point)

Calculates the selection distance to the given point.

This is used to determine the closest manipulator to the given point on the same plane.

Parameters:
Name Type Description
cursor PD.Cursor

The parent cursor requesting this distance.
point THREE.Vector3

The point to compute the distance to.
Returns:

Returns the selection distance.

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 move.
event object

The event that generated the move.

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.

resetAxis()

Resets the manipulator's rotation and selection plane.

Returns:

Returns this manipulator to support method chaining.

Type
PD.Cursors.Manipulator

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.

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.