API Docs

Class: Polar

PD.Cursor. Polar

Defines a cursor for rotating about a specific point.

new Polar(cursorType [, config])

Creates a new 3D rotation cursor.

Parameters:
Name Type Argument Description
cursorType PD.CURSOR

The type of cursor to create, defaults to PD.CURSOR.POINT.
config object <optional>

An optional configuration object.
Properties of config:
Name Type Argument Description
xAngle number <optional>

Rotation around the X-axis, defaults to 0.
yAngle number <optional>

Rotation around the Y-axis, defaults to 0.
zAngle PD.ALIGN <optional>

Rotation around the Z-axis, defaults to 0.
Author:
  • drajmarsh

Extends

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
Inherited From:
Overrides:
:boolean

altKey

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

Type
  • boolean
Inherited From:
Overrides:
:number

altitude

The altitude angle upwards from the horizontal, in radians.

Type
  • number
:number

azimuth

The azimuth angle anti-clockwise from the +X axis, in radians.

Type
  • number
:THREE.Vector3

canvasPos

Stores the position of the cursor in the window coordinates.

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

ctrlKey

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

Type
  • boolean
Inherited From:
Overrides:
: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
Inherited From:
Overrides:
:PD.Curve

dragCurve

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

Type
Inherited From:
Overrides:
: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
Inherited From:
Overrides:
:THREE.Plane

dragPlane

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

Type
  • THREE.Plane
Inherited From:
Overrides:
: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
Inherited From:
Overrides:
: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
Inherited From:
Overrides:
: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
Inherited From:
Overrides:
:boolean

dragging

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

Type
  • boolean
Inherited From:
Overrides:
:THREE.Euler

eulerAngle

The current angle of the cursor.

Type
  • THREE.Euler
:boolean

isCursor <readonly>

A flag identifying this object as a 3D cursor.

Type
  • boolean
Inherited From:
Overrides:
:boolean

isCursorPolar <readonly>

A flag identifying this object as a 3D polar rotator 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
Inherited From:
Overrides:
:THREE.Object3D

linkedObject

An associated geometry object that moves with the cursor.

Type
  • THREE.Object3D
Inherited From:
Overrides:
:boolean

linkedObjectRotated

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

Type
  • boolean
Inherited From:
Overrides:
:boolean

metaKey

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

Type
  • boolean
Inherited From:
Overrides:
:function

onDragEnd

This callback is invoked when an interactive drag finished.

Type
  • function
Inherited From:
Overrides:
:function

onDragMove

This callback is invoked each time the dragged position changes.

Type
  • function
Inherited From:
Overrides:
:function

onDragRotate

This callback is invoked each time a rotation angle changes.

Type
  • function
Inherited From:
Overrides:
:function

onDragStart

This callback is invoked whenever an interactive drag begins.

Type
  • function
Inherited From:
Overrides:
:boolean

orientToView

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

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

position

The 3D position of the cursor in model space.

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

quaternion

The 3D orientation of the cursor in model space.

Type
  • THREE.Quaternion
Inherited From:
Overrides:
: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
Inherited From:
Overrides:
:THREE.Vector3

scale

The 3D scale of the cursor in model space.

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

sceneEditor

The scene that is currently displaying/managing this cursor.

Type
Inherited From:
Overrides:
:boolean

selected

Whether or not the selected manipulator is currently pressed.

Type
  • boolean
Inherited From:
Overrides:
:PD.Cursors.Manipulator

selectedManipulator

Stores the currently selected manipulator.

Type
Inherited From:
Overrides:
:boolean

shiftKey

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

Type
  • boolean
Inherited From:
Overrides:
:HTMLElement|SVGElement

trackingElement

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

Type
  • HTMLElement | SVGElement
Inherited From:
Overrides:
:THREE.Vector3

uAxis

The local 'X' axis after transformation.

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

vAxis

The local 'Y' axis after transformation.

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

wAxis

The local 'Z' axis after transformation.

Type
  • THREE.Vector3
Inherited From:
Overrides:

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.
Inherited From:
Overrides:
Returns:

Returns the given updated local coordinates.

Type
PD.LocalCoordinates

clearRotation()

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

Inherited From:
Overrides:
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.

Inherited From:
Overrides:
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.

Inherited From:
Overrides:
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).

Inherited From:
Overrides:
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.
Inherited From:
Overrides:
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.
Inherited From:
Overrides:

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.
Inherited From:
Overrides:
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.
Inherited From:
Overrides:
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.
Inherited From:
Overrides:
Returns:

Returns this cursor to support method chaining.

Type
PD.Cursor

getDragAxis()

Get the axis that is currently being dragged in.

Inherited From:
Overrides:
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.

Inherited From:
Overrides:
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.
Inherited From:
Overrides:
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.
Inherited From:
Overrides:
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.

Inherited From:
Overrides:
Returns:

Returns true if selected manipulator is constrained.

Type
boolean

moveByRay(raycaster, event)

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

Parameters:
Name Type Description
raycaster THREE.Raycaster

The ray cast into the current scene.
event object

The DOM event that triggered this selection.
Overrides:
Returns:

Returns true if any part of the cursor was selected.

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.
Inherited From:
Overrides:
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.
Inherited From:
Overrides:
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.
Inherited From:
Overrides:
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.
Inherited From:
Overrides:
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.
Inherited From:
Overrides:
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.
Inherited From:
Overrides:
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.
Inherited From:
Overrides:
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.
Inherited From:
Overrides:
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.
Inherited From:
Overrides:
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.
Inherited From:
Overrides:
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.
Inherited From:
Overrides:
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.
Inherited From:
Overrides:
Returns:

Returns true if a manipulator was changed.

Type
boolean

update()

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

Inherited From:
Overrides:
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.

Inherited From:
Overrides:
Returns:

Returns this cursor to support method chaining.

Type
PD.Cursor

updateManipulators()

Updates cursor manipulators when the arrow offset changes.

Inherited From:
Overrides:
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.
Inherited From:
Overrides:
Returns:

Returns this cursor to support method chaining.

Type
PD.Cursor

updateSelectionPlanes()

Recomputes the primary plane equations from axis and position.

Inherited From:
Overrides:
Returns:

Returns this cursor to support method chaining.

Type
PD.Cursor

updateTrackingElement()

Updates the screen position of any linked HTML element.

Inherited From:
Overrides:
Returns:

Returns true if the tracking element position was updated.

Type
boolean