API Docs

Class: Cursor

PD. Cursor

Stores an interactive cursor that can be used to manipulate a 3D model.

A cursor are essentially a collection of one or more hotspots within the scene that the user can click/touch and drag in order to undertake some action within the model. In this framework, as managed by the PD.SceneEditor, instances of the PD.Cursor class are the only way of interactively manipulating the model. Any click/tap or interaction that is not on or near a cursor is considered either a model selection event or a view manipulation.

For basic interactive editing, there are 6 types of cursor:

  1. POINT: Unrestricted movement in all 3 dimensions. Has a UV manipulator at the centre of the cursor and arrows in each of the ±U, ±V and ±W directions. The plane of movement varies between UV, VW and UW based on the 3D view angle.

  2. PLANE: Movement is restricted to an arbitrary 3D plane. Has a UV manipulator at the centre of the cursor and arrows in each of the ±U and ±V directions.

  3. VECTOR: Movement is restricted to an arbitrary 3D vector. Has either a single arrow or arrows in only the ±U directions.

  4. RECT: Used to edit the position, width and height of an arbitrarily oriented 3D rectangle. Movement is restricted to the plane of orientation of the rectangle. Has a UV manipulator at the centre of the cursor and arrows at the rectangle extents in the ±U and ±V directions to control width and height.

  5. RECT_CORNERS: The same as RECT, but with additional diagonal arrows in each corner.

  6. BOX: Used to edit the position, width, depth and height of an arbitrarily oriented 3D bounding box. Has a UV manipulator at the centre of the cursor and arrows at the bounding box extents in the ±U, ±V and ±W directions to control width, depth and height. The position has unrestricted movement in all 3 dimensions and the plane of movement varies between UV, VW and UW based on the 3D view angle.

  7. SECTION: Typically used to manipulate section planes. Movement is restricted to the 3D vector normal to the section plane. Has a single manipulator at the centre of the cursor, shaped as an architectural section symbol.

new Cursor(cursorType [, geometry] [, material])

Creates a new cursor for manipulating a 3D model.

Parameters:
Name Type Argument Default Description
cursorType PD.CURSOR

The type of cursor to create, defaults to PD.CURSOR.PLANE.
geometry THREE.BufferGeometry <optional>
 null

An optional geometry to overlay the cursor on.
material THREE.Material <optional>
 null

An optional material for the cursor overlay.
Author:
  • drajmarsh

Extends

  • THREE.Mesh

Classes

Box
CaptureAll
Polar
Rect

Members

:number

absoluteSize

Defines the calculated absolute size of the cursor within the model.

The scene manager that controls this cursor automatically calculates a view-specific 'point' size that things like text, dimensions and arrows can reference in order to be visible on the screen regardless of the size of the model. To be similarly visible, cursors also reference this model-specific size when rendering themselves.

Thus, this value is basically the view-specific 'point' size (this.sceneEditor.getPointSizeView()) multiplied by the base cursor size (PD.GlobalState.cursorBaseSize) multiplied by the dynamic view and position specific relative size (this.relativeSize).

Type
  • number
:boolean

altKey

Whether or not the ALT key was pressed for the last event.

Type
  • boolean
:THREE.Vector3

canvasPos

Stores the position of the cursor in the window coordinates.

Type
  • THREE.Vector3
:boolean

ctrlKey

Whether or not the CONTROL key was pressed for the last event.

Type
  • boolean
:PD.CURSOR

cursorType

The type of cursor this represents.

See the PD.CURSOR for details of how each cursor type work and how it is best used.

Type
:PD.Curve

dragCurve

A curve that the cursor and its manipulators should follow, if any.

Type
:THREE.Vector3

dragOrigin

The centre position of the cursor when the drag event started.

This remains static throughout each drag event and is used as the reference point from which the cursor as a whole is moved by the drag vector.

Type
  • THREE.Vector3
:THREE.Plane

dragPlane

The plane in which the cursor is dragged once a manipulator is selected.

Type
  • THREE.Plane
:THREE.Vector3

dragPos

The position on the cursor plane that the manipulator is being dragged to.

This position starts out the same as pointerPos but is modified to remain on the vector of the manipulator, if any. The difference between this position and dragStart gives the initial drag vector by which the cursor moves.

Type
  • THREE.Vector3
:THREE.Vector3

dragStart

The point on the cursor plane that the user clicked when selecting the manipulator.

This remains static throughout each drag event and is the reference against which the new manipulator position is measured to obtain the raw and unmodified drag vector.

Type
  • THREE.Vector3
:THREE.Vector3

dragVector

The overall movement vector of the cursor during this drag.

This vector is initially calculated as the difference between dragPos and dragStart, but will often change due to grid and object snapping, as well as other modifications that may be made during drag processing.

To update the vector and get the very latest value, call the computeDragVector() method instead of accessing this property directly.

Type
  • THREE.Vector3
:boolean

dragging

Whether or not the cursor is currently selected and being dragged.

Type
  • boolean
:boolean

isCursor <readonly>

A flag identifying this object as a 3D cursor.

Type
  • boolean
:boolean

keepPlanar

Whether or not the cursor should stick to its base plane and not move in the 'W' axis.

Type
  • boolean
:THREE.Object3D

linkedObject

An associated geometry object that moves with the cursor.

Type
  • THREE.Object3D
:boolean

linkedObjectRotated

A flag indicating that the associated geometry object has been rotated with the view.

Type
  • boolean
:boolean

metaKey

Whether or not the META key was pressed for the last event.

Type
  • boolean
:function

onDragEnd

This callback is invoked when an interactive drag finished.

Type
  • function
:function

onDragMove

This callback is invoked each time the dragged position changes.

Type
  • function
:function

onDragRotate

This callback is invoked each time a rotation angle changes.

Type
  • function
:function

onDragStart

This callback is invoked whenever an interactive drag begins.

Type
  • function
:boolean

orientToView

Whether or not the drag plane and changes with the 3D view.

Type
  • boolean
:THREE.Vector3

position

The 3D position of the cursor in model space.

Type
  • THREE.Vector3
:THREE.Quaternion

quaternion

The 3D orientation of the cursor in model space.

Type
  • THREE.Quaternion
:number

relativeSize

Defines the relative size of the cursor within the current view.

In order to maintain a relatively static size relative to the view canvas, 3D cursors need to scale themselves when the view changes due to dolly/zoom or adding/removing geometric elements. Also, to remain at a size suitable for touch selection and dragging, the cursor still has to remain the same size when dragged directly towards or away from the camera in a 3D model view.

The information required for this is obtained directly from the scene manager that controls this cursor, but must be updated not only when the view changes, but also each time the cursor is dragged. This is effectively

Type
  • number
:THREE.Vector3

scale

The 3D scale of the cursor in model space.

Type
  • THREE.Vector3
:PD.SceneEditor|null

sceneEditor

The scene that is currently displaying/managing this cursor.

Type
:boolean

selected

Whether or not the selected manipulator is currently pressed.

Type
  • boolean
:PD.Cursors.Manipulator

selectedManipulator

Stores the currently selected manipulator.

Type
:boolean

shiftKey

Whether or not the SHIFT key was pressed for the last event.

Type
  • boolean
:HTMLElement|SVGElement

trackingElement

An associated HTML element that tracks and moves with the cursor.

Type
  • HTMLElement | SVGElement
:THREE.Vector3

uAxis

The local 'X' axis after transformation.

Type
  • THREE.Vector3
:THREE.Vector3

vAxis

The local 'Y' axis after transformation.

Type
  • THREE.Vector3
:THREE.Vector3

wAxis

The local 'Z' axis after transformation.

Type
  • THREE.Vector3
:THREE.MeshBasicMaterial

HilightMaterial <static>

A default pink mesh material for highlighting the selected manipulator.

Type
  • THREE.MeshBasicMaterial
:THREE.LineBasicMaterial

HilightOutlineMaterial <static>

A default red line material for highlighting cursor outlines.

Type
  • THREE.LineBasicMaterial
:THREE.MeshBasicMaterial

MarkerMaterial <static>

A default red mesh material for displaying box and diamond markers.

Type
  • THREE.MeshBasicMaterial
:THREE.LineBasicMaterial

OutlineMaterial <static>

A default red line material for displaying cursor outlines.

Type
  • THREE.LineBasicMaterial
:THREE.MeshBasicMaterial

SurfaceMaterial <static>

A default white mesh material for displaying manipulator infill geometry.

Type
  • THREE.MeshBasicMaterial
:THREE.Texture

TextureAtlas <static>

The 2x2 texture atlas used for image-based manipulators.

Type
  • THREE.Texture

Methods

alignLocalCoords(coords [, origin])

Sets the given local coordinates to align with the cursor 'W' plane.

Parameters:
Name Type Argument Description
coords PD.LocalCoordinates

The local coordinates to set.
origin THREE.Vector3 <optional>

The origin of the local coordinates, defaults to cursor position.
Returns:

Returns the given updated local coordinates.

Type
PD.LocalCoordinates

clearRotation()

Clears any previous rotations or alignments of the cursor and its manipulators.

Returns:

Returns this cursor to support method chaining.

Type
PD.Cursor

clearViewAxis()

Clears the last closest axis angle.

Clearing this value ensures that the cursor will update immediately after its position is changed.

Returns:

Returns this cursor to support method chaining.

Type
PD.Cursor

computeDragVector()

Recalculates the drag vector from the current cursor position.

This method computes PD.Cursor#dragVector by subtracting the PD.Cursor#dragOrigin from PD.Cursor#position, and then return PD.Cursor#dragVector.

Returns:

Returns the computed vector.

Type
THREE.Vector3

computeRelativeAndAbsoluteSize()

Update the size of the cursor within the current view.

This computes both the relativeSize and absoluteSize properties from the current model size and camera view, and updates the scale property. This is called by the update() method whenever the view or cursor position changes.

The relative size is calculated using the camera-to-cursor view distance and the absolute size is then a function of this and the scene editor view-specific 'point' size (this.sceneEditor.getPointSizeView()) and the base cursor size (this.sceneEditor.cursorBaseSize).

Returns:

Returns the absolute size of the cursor in model units.

Type
number

createManipulators(type)

Creates the manipulators for the given type of cursor.

Parameters:
Name Type Description
type PD.CURSOR

The type of cursor to generate manipulators for.
Returns:

Returns an array of manipulators.

Type
Array

fade(state)

Fade the cursor out so that it doesn't obstruct detailed work.

If the PD.GlobalState.cursorFadeOnSelect option is set, this method fades out the opacity of the cursor as it is being dragged so that it does not obscure the detail in the model being snapped to.

Parameters:
Name Type Description
state boolean

Whether or not to fade.

findByRay(raycaster, event)

Checks if the given ray intersects any of the cursor manipulators.

If a manipulator is selected, this method computes and stores the initial drag origin and plane, and updates the cursor state appropriately.

Parameters:
Name Type Description
raycaster THREE.Raycaster

The ray cast into the current scene.
event object

The DOM event that triggered this selection.
Returns:

Returns true if any part of the cursor was selected.

Type
boolean

findClosestAxis(cameraPos)

Computes the axis closest to the vector between the given point and the cursor position.

Parameters:
Name Type Description
cameraPos THREE.Vector3

The current camera position.
Returns:

Returns the closest of the three axis.

Type
PD.AXIS

generateManipulatorMesh(manipulator)

Generates a mesh for the given manipulator based on cursor type.

Parameters:
Name Type Description
manipulator PD.Cursors.Manipulator

The manipulator to generate the mesh for.
Returns:

Returns this cursor to support method chaining.

Type
PD.Cursor

getDragAxis()

Get the axis that is currently being dragged in.

Returns:

Returns the axis of the currently selected manipulator or PD.AXIS.NONE if nothing selected.

Type
PD.AXIS

getLastRay()

Retrieves the last scene ray used to set the cursor position.

This value is updated by the PD.Cursor#moveByRay method, so the raycaster should typically only be used within the PD.Cursor#onDragStart, PD.Cursor#onDragMove and PD.Cursor#onDragEnd callbacks.

Returns:
Type
THREE.Ray | null

highlightSelectedManipulator(event)

Changes how the currently selected cursor is displayed.

Parameters:
Name Type Description
event object

The DOM event that triggered this change.
Returns:

Returns this cursor to support method chaining.

Type
PD.Cursor

hoverByRay(raycaster, event)

Checks if the given ray intersects any of the cursor manipulators.

Parameters:
Name Type Description
raycaster THREE.Raycaster

The ray cast into the current scene.
event object

The DOM event that triggered this selection.
Returns:

Returns true if any part of the cursor was selected.

Type
boolean

isConstrained()

Check whether or not the selected manipulator is constrained to a vector.

In most cursors, there is a central unconstrained manipulator surrounded by vector-constrained arrow manipulators. This method will return false if the central manipulator is being dragged and true for the arrow manipulators.

Returns:

Returns true if selected manipulator is constrained.

Type
boolean

moveByRay(raycaster, event)

Moves the cursor when the pointer is dragged if it is selected.

This method checks if the pointer has moved and, if so, calls onDragStart() the very first time and then lets the selected manipulator control the cursor movement.

Parameters:
Name Type Description
raycaster THREE.Raycaster

The ray cast into the current scene.
event object

The DOM event that triggered this move.
Returns:

Returns true if any part of the cursor was moved.

Type
boolean

moveComplete(event)

Updates the cursor after it has been interactively moved.

Parameters:
Name Type Description
event object

The DOM event that triggered the end move.
Returns:

Returns this cursor to support method chaining.

Type
PD.Cursor

rotateNormalToLine(from, to)

Sets the rotation of the cursor and all its manipulators.

This method rotates the cursor so that it's direction is normal to the line between the given points.

Parameters:
Name Type Description
from THREE.Vector3

The start point of the line.
to THREE.Vector3

The end point of the line.
Returns:

Returns this cursor to support method chaining.

Type
PD.Cursor

rotateToPlane(plane)

Sets the rotation of the cursor and all its manipulators.

This method rotates the cursor so that it's 'W' axis is normal to the given plane.

Parameters:
Name Type Description
plane THREE.Plane

The plane to set the cursor orientation.
Returns:

Returns this cursor to support method chaining.

Type
PD.Cursor

rotateToVector(direction)

Sets the rotation of the cursor and all its manipulators.

This method rotates the cursor so that it's vector is in the given direction.

Parameters:
Name Type Description
direction THREE.Vector3

The direction vector to use.
Returns:

Returns this cursor to support method chaining.

Type
PD.Cursor

setDetached(state)

Sets whether or not this cursor is actually attached to something.

Detaching the cursor allows you to drag the cursor to a new position without changing anything. A detached cursor is displayed in a slightly different color to differentiate it from an attached cursor.

Parameters:
Name Type Description
state boolean

The new attached state of this cursor.
Returns:

Returns this cursor to support method chaining.

Type
PD.Cursor

setPosition(new_pos)

Sets the position of the cursor and all its manipulators.

This provides an overridable method for subclasses that need to pre-process the cursor position before setting it.

Parameters:
Name Type Default Description
new_pos THREE.Vector3 null

The new position for the center of the cursor.
Returns:

Returns true if the cursor moved to the new position.

Type
boolean

setSelectedManipulator(manipulator)

Sets the given manipulator as the selected one.

Call this method to select or deselect a manipulator so it can do some necessary housekeeping.

Parameters:
Name Type Description
manipulator PD.Cursors.Manipulator

The manipulator to select, or null to deselect.
Returns:

Returns this cursor to support method chaining.

Type
PD.Cursor

setXYRotation(angle)

Sets the rotation of the cursor and all its manipulators in the XY plane.

Parameters:
Name Type Description
angle angle

The new rotation angle about the center of the cursor.
Returns:

Returns this cursor to support method chaining.

Type
PD.Cursor

showManipulatorByIndex(index [, show])

Shows/hides a manipulator at the given index.

Parameters:
Name Type Argument Description
index number

The index of the manipulator in the PD.Cursor#manipulators list.
show boolean <optional>

The display state to set, defaults to true.
Returns:

Returns true if a manipulator was changed.

Type
boolean

showManipulatorsByAxis(axis [, show])

Shows/hides manipulators on the given axis.

Parameters:
Name Type Argument Description
axis PD.AXIS

The axis to show/hide manipulators on.
show boolean <optional>

The display state to set, defaults to true.
Returns:

Returns true if a manipulator was changed.

Type
boolean

showManipulatorsByType(type [, show])

Shows/hides manipulators on the given axis.

Parameters:
Name Type Argument Description
type PD.MANIPULATOR

The type ot manipulator to show/hide.
show boolean <optional>

The display state to set, defaults to true.
Returns:

Returns true if a manipulator was changed.

Type
boolean

showRotationManipulator(axis, angle [, show])

Shows/hides a rotation manipulator on the given axis and sets its angle.

Parameters:
Name Type Argument Description
axis PD.AXIS

The axis of the manipulator.
angle number

The new rotation angle, in radians.
show boolean <optional>

The display state to set, defaults to true.
Returns:

Returns true if a manipulator was changed.

Type
boolean

update()

Update the size/position of the cursor and all its manipulators.

Returns:

Returns this cursor to support method chaining.

Type
PD.Cursor

updateLinkedObjectOrientation()

Adjusts the orientation of any linked geometry object to point towards the camera.

Returns:

Returns this cursor to support method chaining.

Type
PD.Cursor

updateManipulators()

Updates cursor manipulators when the arrow offset changes.

Returns:

Returns this cursor to support method chaining.

Type
PD.Cursor

updateOrientation(camera, view_dist)

Scales and flips manipulators around their axis to best suit the camera view.

This method is automatically invoked by a callback in the scene manager whenever any of the view parameters change.

Parameters:
Name Type Description
camera THREE.Camera

The camera used in the current scene.
view_dist number

The reference distance between camera and center of view.
Returns:

Returns this cursor to support method chaining.

Type
PD.Cursor

updateSelectionPlanes()

Recomputes the primary plane equations from axis and position.

Returns:

Returns this cursor to support method chaining.

Type
PD.Cursor

updateTrackingElement()

Updates the screen position of any linked HTML element.

Returns:

Returns true if the tracking element position was updated.

Type
boolean

setOpacity(opacity [, cursor]) <static>

Fade the cursor out during detailed work.

Parameters:
Name Type Argument Description
opacity number

The new opacity of the cursor materials (0 to 1).
cursor PD.Cursor <optional>

A cursor instance to check selected manipulator.

setTextureAtlas(image) <static>

Loads the given 2x2 image atlas into the texture atlas.

Parameters:
Name Type Description
image ImageSource

The 2x2 image atlas to load.

style(style [, image_atlas]) <static>

Sets the color styles of the cursor.

Parameters:
Name Type Argument Description
style PD.CURSOR_STYLE

The new style to set.
image_atlas ImageSource <optional>

An optional 2x2 image atlas to use for manipulators.