API Docs

Class: Snapper

PD. Snapper

A helper class for computing interactive snaps and displaying indicators.

new Snapper()

Creates a new interactive snap helper.

Author:
  • drajmarsh

Members

:boolean

active

Whether or not snapping is currently active.

When not active, all snapping is ignored.

Type
  • boolean
:number

baseSize

The base size of snap indicators, in model units.

The value of this property in initialised to suit the current model view on each call to the reset() method.

Type
  • number

checkGrid

Whether or not to snap to the current ground grid.

checkHover

Whether or not to snap to the closest point beneath the pointer when dragging.

checkLines

Whether or not to snap to line segments.

checkMidPoints

Whether or not to snap to the mid-points of line segments.

checkNormals

Whether or not to snap to points normal to line segment.

checkOrtho

Whether or not to restrict to orthographic and diagonal movement.

checkPath

Whether or not to align junctions with previous/next path segments.

checkPoints

Whether or not to snap to object vertices.

:object

closestSnap

Accumulates data when finding the closest point.

Type
  • object
:number

dashSize

The size dashes in indicator lines, in model units.

The value of this property in initialised to suit the current model view on each call to the reset() method.

Type
  • number
:boolean

directSnap

Whether the cursor is directly attached to a point or remote from it.

When directly attached, such as when dragging a point or junction, the cursor center will snap to other points that it is directly over. When not directly attached, such as when dragging the center of a polygon, only the polygon path points will snap to other points.

Type
  • boolean
:number

gridSize

The size of the snap grid, in mm.

Type
  • number

hoverRef

Stores a reference position that persists after the cursor detected a hover snap.

:boolean

isSnapper <readonly>

A flag identifying this object as a snap helper.

Type
  • boolean
:PD.PolyMesh

mesh

The dynamic mesh used for displaying snap indicators.

Type
:number

radius

The snap detection radius, in model units.

The value of this property in initialised to suit the current model view on each call to the reset() method.

Type
  • number
:Array

snapData

Stores the snap points in each axis (0:ANY, 1:X, 2:Y, 3:Z, 4:LINE).

This is basically an array with five entries - the first for a non-orthogonal snap point, and the following three for each of the relative U, V and W axis. When not snapping to a specific vector, these correspond directly to the X, Y and Z cartesian axis, as per PD.AXIS.

Type
  • Array
:number

tolerance

The tolerance value when testing for equivalence, in model units.

Type
  • number
:THREE.Plane

vectorPlane

The intersection plane to use when snapping along a specific vector.

Type
  • THREE.Plane
:THREE.Ray

vectorRay

The intersection ray to use when snapping along a specific vector.

Type
  • THREE.Ray
:number

vectorSnap

A flag indicating whether or not to snap to a specific vector.

This is a numeric value where zero means no vector snapping and any value greater than zero means that vector snapping is being applied. This value is initially set within the checkSnapToPath() method.

Type
  • number

Methods

applyAxialSnapXY(point, cursor [, axis])

Call this after you have tested all the features you wish to snap to.

This method checks all the snap points accumulated since the last call to the reset method, and applies them to the given point. If no snap points were found in any axis, a grid snap is applied to the point in each axis.

Parameters:
Name Type Argument Description
point THREE.Vector3

The point to apply the snap delta to.
cursor PD.Cursor

The cursor that the snaps are being generated for.
axis PD.AXIS <optional>

An optional axis override, defaults to cursor drag axis.
Returns:

Returns true if the point's position was changed.

Type
boolean

applyClosestHoverPoint(point, cursor [, axis])

Call this after you have found the closest point you wish to snap to.

This method snaps the point to the current closestSnap value.

Parameters:
Name Type Argument Description
point THREE.Vector3

The point to apply the snap delta to.
cursor PD.Cursor

The cursor that the snaps are being generated for.
axis PD.AXIS <optional>

An optional axis override, defaults to cursor drag axis.
Returns:

Returns true if the point's position was changed.

Type
boolean

applyClosestPointSnapOnVector(point, cursor [, axis])

Call this after you have found the closest point you wish to snap to.

This method snaps the point to the current closestSnap value.

Parameters:
Name Type Argument Description
point THREE.Vector3

The point to apply the snap delta to.
cursor PD.Cursor

The cursor that the snaps are being generated for.
axis PD.AXIS <optional>

An optional axis override, defaults to cursor drag axis.
Returns:

Returns true if the point's position was changed.

Type
boolean

applyClosestPointSnapXY(point, cursor [, axis])

Call this after you have found the closest point you wish to snap to.

This method snaps the point to the current closestSnap value.

Parameters:
Name Type Argument Description
point THREE.Vector3

The point to apply the snap delta to.
cursor PD.Cursor

The cursor that the snaps are being generated for.
axis PD.AXIS <optional>

An optional axis override, defaults to cursor drag axis.
Returns:

Returns true if the point's position was changed.

Type
boolean

applyGridSnap(point, cursor [, axis])

Applies a grid snap to the point in the cursor/given axis.

Parameters:
Name Type Argument Description
point THREE.Vector3

The point to apply the grid snap to.
cursor PD.Cursor

The cursor that the snaps are being generated for.
axis PD.AXIS <optional>

An optional axis override, defaults to cursor drag axis.
Returns:

Returns true if the point's position was changed.

Type
boolean

applyLineSnapXY(point1, point2, ray1, ray2, plane)

Call this after you have tested all the features you wish to snap to.

This method checks all the snap points accumulated since the last call to the reset method, and applies them to the given point. If no snap points were found in any axis, a grid snap is applied to the point in that axis.

Parameters:
Name Type Description
point1 THREE.Vector3

The start point of the line.
point2 THREE.Vector3

The end point of the line.
ray1 THREE.Ray

The ray of the line joining to the start point.
ray2 THREE.Ray

The ray of the line joining from the end point.
plane THREE.Plane

The plane for intersecting the rays.
Returns:

Returns true if the point's position was changed.

Type
boolean

checkOrthoToAxis(axis, point, cursor [, indicators])

Checks to modify the axis if ortho snap is on.

When ortho snap mode is on or the SHIFT key is pressed, the cursor is restricted to orthographic and diagonal movements only. This movement is relative to the cursor.refPos, which is a snapshot of the cursor target position just before the current drag started.

Parameters:
Name Type Argument Default Description
axis PD.AXIS

The current axis to use.
point THREE.Vector3

The point to apply the snap delta to.
cursor PD.Cursor

The cursor that the snaps are being generated for.
indicators Array <optional>
 null

An optional array of indicators to add to.
Returns:

Returns a potentially ortho-modified axis.

Type
PD.AXIS

checkSnapToPath(pt_test, cursor, junction)

Checks to constrain snapping to a vector relative to the previous/next path segment.

When PD.Snapper#checkPath is true or the SHIFT key is pressed, the given point is checked to see if it is close to a specific angle from the path segment leading to or away from the given junction. If close to 0, 45, 90, 135 or 180 degrees, then the cursor is restricted to that vector, which also becomes the X-axis of the local coordinate system.

This method only returns true if the test point lines up in both the U and V directions, meaning that an exact snap point was found an no further snap testing is required. If only one snap direction was found, it returns false but sets things up so that other snap tests are only checked in the other direction.

Parameters:
Name Type Description
pt_test THREE.Vector3

The point to check against the junction path.
cursor PD.Cursor

The cursor that the snaps are being generated for.
junction BIM.Junction

The path junction being to check the point against.
Returns:

Returns true if valid U and V path snaps were found.

Type
boolean

checkSnapToPathPoints(pt_test, cursor, junction)

Checks to snap to points on the same path.

Parameters:
Name Type Description
pt_test THREE.Vector3

The point to check against the junction path.
cursor PD.Cursor

The cursor that the snaps are being generated for.
junction BIM.Junction

The path junction being to check the point against.
Returns:

Returns true if a valid path snap was found.

Type
boolean

clearAxialSnap(axis)

Clears any snap points found in the given axis.

Parameters:
Name Type Description
axis PD.AXIS

The axis to clear of snap points.
Returns:

Returns true if there were snap points to clear.

Type
boolean

clearVerticalOffset()

Resets the vertical snap offset to zero.

Returns:

Returns this snap object to support method chaining.

Type
PD.Snapper

closestPointInContour3D(ray, pt_test, contour, closed)

Finds the closest point in the array to the given ray.

Parameters:
Name Type Default Description
ray THREE.Ray

The ray through the 3D cursor.
pt_test THREE.Vector3

The point to find a snap for.
contour Array.<PD.Point>

The array of PD.Point objects to test.
closed boolean false

Whether or not the contour is a closed loop.
Returns:

Returns the closest vertex, of null in nothing within radius.

Type
THREE.Vector3 | null

closestPointInContourXY(pt_test, contour, closed)

Finds the closest point in the array to the test point in the XY plane.

Parameters:
Name Type Default Description
pt_test THREE.Vector3

The point to find a snap for.
contour Array

The array of PD.Point objects to test.
closed boolean false

Whether or not the contour is a closed loop.
Returns:

Returns the closest vertex, of null in nothing within radius.

Type
THREE.Vector3 | null

closestPointOnAperture(ray, pt_test, aperture)

Finds the closest point in the aperture to the given ray.

Parameters:
Name Type Description
ray THREE.Ray

The ray through the 3D cursor.
pt_test THREE.Vector3

The point to find a snap for.
aperture BIM.Aperture

The aperture to search for snaps.
Returns:

Returns the closest point, of null in nothing within radius.

Type
THREE.Vector3 | null

dispose()

Cleans up the snapper and removes all event listeners.

NOTE: Only call this method when the snapper is no longer needed and you wish to free all its resources.

drawCircle( [multiplier])

Adds a circle at the local coordinate origin to the mesh.

Parameters:
Name Type Argument Description
multiplier number <optional>

An optional radius multiplier, defaults to 1.
Returns:

Returns this snap object to support method chaining.

Type
PD.Snapper

drawCross( [multiplier])

Adds an oblique cross at the local coordinate origin to the mesh.

Parameters:
Name Type Argument Description
multiplier number <optional>

An optional size multiplier, defaults to 1.
Returns:

Returns this snap object to support method chaining.

Type
PD.Snapper

drawDiagonalIndicator( [multiplier])

Adds a diamond indicator at the given position.

Parameters:
Name Type Argument Description
multiplier number <optional>

An optional radius multiplier, defaults to 1.
Returns:

Returns this snap object to support method chaining.

Type
PD.Snapper

drawDiamond( [multiplier])

Adds an outline diamond at the local coordinate origin to the mesh.

Parameters:
Name Type Argument Description
multiplier number <optional>

An optional size multiplier, defaults to 1.
Returns:

Returns this snap object to support method chaining.

Type
PD.Snapper

drawDiamondDot( [multiplier])

Adds a small diamond at the local coordinate origin to the mesh.

Parameters:
Name Type Argument Description
multiplier number <optional>

An optional size multiplier, defaults to 1.
Returns:

Returns this snap object to support method chaining.

Type
PD.Snapper

drawHoverIndicator(data [, axis])

Adds an appropriate indicator for the given snap.

Parameters:
Name Type Argument Description
data object

The snap point data to highlight.
axis PD.AXIS <optional>

An optional axis override, defaults to cursor drag axis.
Returns:

Returns this snap object to support method chaining.

Type
PD.Snapper

drawIndicator(data)

Adds an appropriate indicator for the given snap.

Parameters:
Name Type Description
data object

The snap point data to highlight.
Returns:

Returns this snap object to support method chaining.

Type
PD.Snapper

drawMidPointIndicator(axis [, multiplier])

Adds an hour-glass indicator at the given position.

Parameters:
Name Type Argument Description
axis PD.AXIS

The cartesian axis of the snap point.
multiplier number <optional>

An optional radius multiplier, defaults to 1.
Returns:

Returns this snap object to support method chaining.

Type
PD.Snapper

drawOrthoIndicator( [multiplier])

Adds a square indicator at the given position.

Parameters:
Name Type Argument Description
multiplier number <optional>

An optional radius multiplier, defaults to 1.
Returns:

Returns this snap object to support method chaining.

Type
PD.Snapper

drawPlus( [multiplier])

Adds an orthographic cross at the local coordinate origin to the mesh.

Parameters:
Name Type Argument Description
multiplier number <optional>

An optional size multiplier, defaults to 1.
Returns:

Returns this snap object to support method chaining.

Type
PD.Snapper

drawPointIndicator( [multiplier])

Adds an oblique cross with square indicator at the given position.

Parameters:
Name Type Argument Description
multiplier number <optional>

An optional radius multiplier, defaults to 1.
Returns:

Returns this snap object to support method chaining.

Type
PD.Snapper

drawSquare( [multiplier])

Adds an outline box at the local coordinate origin to the mesh.

Parameters:
Name Type Argument Description
multiplier number <optional>

An optional size multiplier, defaults to 1.
Returns:

Returns this snap object to support method chaining.

Type
PD.Snapper

drawSquareDot( [multiplier])

Adds a small square at the local coordinate origin to the mesh.

Parameters:
Name Type Argument Description
multiplier number <optional>

An optional size multiplier, defaults to 1.
Returns:

Returns this snap object to support method chaining.

Type
PD.Snapper

getAxialDelta(axis)

Retrieves the delta for the given axis, or zero.

Parameters:
Name Type Description
axis PD.AXIS

The axis to get the delta for.
Returns:

Returns the delta for the given axis.

Type
number

hasAxialSnap(axis)

Determines whether a snap point was found in the given axis.

Parameters:
Name Type Description
axis PD.AXIS

The axis to check for a snap point.
Returns:

Returns true if axial snap exists.

Type
boolean

reset(scene)

Empties the snap indicators and clears the mesh.

Parameters:
Name Type Description
scene PD.SceneViewer

The scene to be snapped in.
Returns:

Returns this snap object to support method chaining.

Type
PD.Snapper

setVerticalOffset(offset)

Sets the vertical snap offset to accommodate differences in floor level.

Parameters:
Name Type Description
offset number

The vertical snap offset value.
Returns:

Returns this snap object to support method chaining.

Type
PD.Snapper

snapToContourXY(pt_test, contour, closed)

Updates the axial snaps with the closest points in the array, in the X and Y axis.

Parameters:
Name Type Default Description
pt_test THREE.Vector3

The point to find a snap for.
contour Array

The array of PD.Point objects to test.
closed boolean false

Whether or not the contour is a closed loop.
Returns:

Returns true if something in the contour was found and added to the snapper, otherwise false.

Type
boolean

snapToExtentsXY(pt_test, extents)

Finds the closest point on the extents of an object in the X and Y axis.

Parameters:
Name Type Description
pt_test THREE.Vector3

The point to find a snap for.
extents THREE.Box3

The minimum and maximum bounds in each axis.
Returns:

Returns true if as snap point was found and added to the snapper, otherwise false.

Type
boolean

snapToLineIn3D(pt_test, cursor, pt1, pt2 [, snapType])

Checks to snap the given point to the given 3D line (pt1 => pt2).

Parameters:
Name Type Argument Description
pt_test THREE.Vector3

The point to find a snap for.
cursor PD.Cursor

The cursor that the snaps are being generated for.
pt1 THREE.Vector3

The first point on the line segment.
pt2 THREE.Vector3

The second point on the line segment.
snapType PD.SNAP <optional>

The type of snap this point represents, defaults to PD.SNAP.LINES.
Returns:

Returns true if this point is the closest so far and was added to the list, otherwise false.

Type
boolean

snapToLineInXY(pt_test, pt1, pt2 [, snapType])

Checks if the given point is the closest snap in the X and Y axis.

Parameters:
Name Type Argument Description
pt_test THREE.Vector3

The point to find a snap for.
pt1 THREE.Vector3

The first point on the line segment.
pt2 THREE.Vector3

The second point on the line segment.
snapType PD.SNAP <optional>

The type of snap this point represents, defaults to PD.SNAP.LINES.
Returns:

Returns true if this point is the closest so far and was added to the list, otherwise false.

Type
boolean

snapToPointInXY(pt_test, pt_snap [, snapType])

Checks if the given point is the closest snap in the X and Y axis.

Parameters:
Name Type Argument Description
pt_test THREE.Vector3

The point to find a snap for.
pt_snap THREE.Vector3

The model point to check.
snapType PD.SNAP <optional>

The type of snap this point represents, defaults to PD.SNAP.POINTS.
Returns:

Returns true if this point is the closest so far and was added to the list, otherwise false.

Type
boolean

update( [show])

Updates snap indicators and the mesh.

Parameters:
Name Type Argument Description
show boolean <optional>

Whether or not to show the snap.
Returns:

Returns this snap object to support method chaining.

Type
PD.Snapper

validateAxialDelta(axis, tolerance)

Checks for the delta in the given axis.

If a snap exists and the delta is less than the threshold, the snap is cleared.

Parameters:
Name Type Default Description
axis PD.AXIS

The axis to get the delta for.
tolerance number 0.5

The distance tolerance in mm to test validity against, defaults to 0.5mm.
Returns:

Returns the delta for the given axis.

Type
number