API Docs

Class: Selection

PD. Selection

Defines a data object for collecting interactive selection information.

This object both defines the basic parameters for the selection test and collects progressive selection results as it is passed around through the elements in the model. Depending on the type of selection, various methods will use the results to either continue or halt the selection process.

If a model editor is being used, it will propagate one of these objects throughout the model whenever the user clicks the pointer or taps within the model canvas.

The selection data object has the following properties:

Type Name Description
PD.SELECTED selectedType Stores the type of the most recent selection.
PD.SELECT_ACTION selectAction Specifies how the recent selection should affect the model selection.
THREE.Vector3 intersection A volatile point that external classes can use for ray intersection tests.
boolean keepExisting Whether or not the current selection is being adjusted.
boolean depthSort Whether or not to depth sort possible selections in 3D from the eye position.
PD.FILTER filter A bitwise flag of PD.FILTER values that determine which model features are selectable.
------------------------- -------------------------- -------------------------------
PD.SELECTED currentType The current model selection type in the selection manager.
BIM.Element currentElement The currently selected element in the selection manager.
BIM.Junction currentJunction The currently selected junction in the selection manager.
------------------------- -------------------------- -------------------------------
THREE.RayCaster rayCaster The raycaster object and ray to use for model selection.
THREE.Ray ray The selection ray cast by the raycaster object.
number radius The selection radius, typically received from the current scene.
number closestDepth The distance between the eye position and closest entity intersection point.
number closestRadius Starts off equal to radius, but is progressively refined as closer intersection points are found.
BIM.Element/null closestElement The editable element that either was selected or owns the closest item.
Array closestContour The path contour in which the closest junction/segment was found.
number closestContourIndex The index of the closest contour in element path's contours list.
BIM.Junction/null closestJunction The closest junction to the selection ray.
number closestJunctionIndex The index of the closest junction within the closest contour.
BIM.Junction/null closestSegment The junction the closest junction is connected to in the closest path contour.
number closestSegmentIndex The index of the junction that the closest junction is connected to in the closest path contour.
PD.Point/null closestNode The closest control node to the selection ray in the closest junction.
number closestNodeIndex The index of the closest control node within the closest junction's node list.
BIM.Aperture/null closestAperture The closest aperture to the selection ray within the closest junction.
number closestApertureIndex The index of the closest aperture within the closest junction's aperture list.
PD.Shell/null closestShell The shell containing the closest facet intersected by the selection ray.
PD.Polygon/null closestShellFacet The closest facet within the shell intersected by the selection ray.
number closestShellIndex The index of the closest facet within the selected shell.
PD.BRep/null closestSurface The surface containing the closest facet intersected by the selection ray.
PD.BRep.Face/null closestSurfaceFacet The closest facet within the surface intersected by the selection ray.
Array<PD.Point>/null closestSurfaceEdge The closest edge within the surface intersected by the selection ray.
PD.Point/null closestSurfaceVertex The closest vertex within the surface intersected by the selection ray.
BIM.Level/null closestLevel The closest selectable level to the selection ray.
BIM.Structure/null closestStructure The closest selectable structure to the selection ray.
THREE.Vector3 closestIntersection The intersection point of the selection ray and the closest entity.
THREE.Vector3/null closestPoint The closest editable point to the selection ray.
------------------------- -------------------------- -------------------------------
THREE.Frustum frustum The frustum object to use for region-based model selection.
boolean intersectFrustum Whether or not to select items that just intersect the frustum.
PD.SelectionSet foundItems A selection set containing the most recently selected items.

Model selection can use either a selection ray or a view frustum as the selection mechanism:

  • Ray-based selection typically selects just a single model item that is closest to the ray, and uses all the closest... properties to test, refine and store the selection.

  • Frustum-based selection typically selects all of the model items that are inside or intersect the frustum, and uses the foundItems selection set property to store them.

new Selection()

Creates a new selection data instance.

Author:
  • drajmarsh

Members

:BIM.Aperture|null

closestAperture

The closest intersected BIM.Aperture object.

Type
:number

closestApertureIndex

The index of the closest intersected BIM.Aperture in a junction's openingList array.

Type
  • number
:PD.BRep|null

closestBRep

The closest PD.BRep within an element.

This value is set when BIM.Element is selected by picking on one of the faces of the BRep that define its shape.

Type
:Array.<PD.Point>|null

closestBRepEdge

The closest edge within the closest surface.

This value is set when one of the edges of a PD.BRep that defines an element is selected.

Type
:PD.BRep.Face|null

closestBRepFace

The closest PD.BRep.Face within the surface of an element.

This value is set when one of the facets of a PD.BRep that defines an element's geometry is selected.

Type
:PD.Point|null

closestBRepVertex

The closest vertex within the closest surface.

This value is set when one of the vertices of a PD.BRep that defines an element is selected.

Type
:Array|null

closestContour

The contour of the selected element path that the closest vertex belongs to.

This value is set when a linear or curved path running between two vertices within the path of a building element is selected. This contour will always belong to closestElement.path.

Type
  • Array | null
:number

closestContourIndex

The index of the closest contour within the closest element path.

This is set when either a path vertex is selected directly or the ray is closest to the line between this vertex and the next within the path of a building element. It is the ordinal index within a closestElement.path contour.

Type
  • number
:number

closestDepth

The distance between the eye position and closest intersection point.

This is set within the found*() methods, typically measured from the selection ray origin to the PD.Selection#intersection position.

Type
  • number
:BIM.Element|null

closestElement

The BIM.Element object closest to the selection ray.

This value is set when the user selects an object or one of its features, such as a control point, vertex, segment, face or opening. This will always be set to a valid selectable element whenever the selectedType property is not set to PD.SELECTED.NONE.

Type
:THREE.Vector3

closestIntersection

The closest intersection point on a selected facet or line.

When a selection is made by intersection with a facet or closest point to a path segment, this value stores the intersection or closest point.

Type
  • THREE.Vector3
:PD.Point|null

closestJunction

The closest BIM.Junction position within the closest element or path.

This value is set when an actual vertex position within the path of an element is selected. This vertex will always be contained within PD.Selection#closestContour and PD.Selection#closestJunctionIndex will be its ordinal position within the array. Also, which, in turn, will always belong to closestElement.path.

Type
:number

closestJunctionIndex

The index of the closest BIM.Junction object within a path or element.

This is set when either a path vertex is selected or the ray is closest to the line between this vertex and the next within the path of a building element. It is the ordinal index within the PD.Selection#closestContour array.

Type
  • number
:BIM.Level|null

closestLevel

The closest BIM.Level within the current structure.

Type
:PD.Point|null

closestNode

The closest PD.Point control node within a selected junction.

Type
:number

closestNodeIndex

The index of the closest PD.Point control node within a selected junction.

Type
  • number
:BIM.Path|null

closestPath

The BIM.Path object selected within the closest element.

This value is set when the user selects an element or one of its features, such as a control point, vertex, segment, face or opening..

Type
:PD.Point|null

closestPoint

The closest editable point within the closest selection.

In some cases this will be the actual vertex of a path, but in others it may be the mid-point of a line or a curve control point that belongs to a path vertex.

This value is set when the user clicks on an something to select it.

Type
:number

closestRadius

Stores the distance from the selection ray to the closest selection.

Starts off equal to PD.Selection#radius at the beginning of selection testing, but is progressively refined as potential selections are found that are closer than the previous.

Type
  • number
:PD.Point|null

closestSegment

The closest BIM.Junction path segment within the closest element or path.

This value is set when a linear or curved path running between two vertices within a path or building element is selected.

Type
:number

closestSegmentIndex

The index of the next PD.Point objecting the selected path segment.

This value is set when a linear or curved path running between two vertices within a path or building element is selected. It is the ordinal index of the next point within the closestContour array.

Type
  • number
:PD.Shell|null

closestShell

The closest PD.Shell within an element.

This value is set when BIM.Element is selected by picking on one of the facets of the shell that define its shape.

Type
:PD.Polygon|null

closestShellFacet

The closest PD.Polygon within the shell of an element.

This value is set when one of the facets of a PD.Shell that defines an element is selected.

Type
:number

closestShellIndex

The index of the closest PD.Polygon within the closest shell.

This is the ordinal index of the closestShellFacet within the closestShell.facetList array.

Type
  • number
:BIM.Structure|null

closestStructure

The closest BIM.Structure within the current project.

Type
:PD.BRep|null

closestSurface

The closest PD.BRep within an element.

This value is set when BIM.Element is selected by picking on one of the facets of the surface that define its shape.

Type
:Array.<PD.Point>|null

closestSurfaceEdge

The closest edge within the closest surface.

This value is set when one of the edges of a PD.BRep that defines an element is selected.

Type
:PD.BRep.Face|null

closestSurfaceFacet

The closest PD.BRep.Face within the surface of an element.

This value is set when one of the facets of a PD.BRep that defines an element is selected.

Type
:PD.Point|null

closestSurfaceVertex

The closest vertex within the closest surface.

This value is set when one of the vertices of a PD.BRep that defines an element is selected.

Type
:BIM.Aperture|null

currentAperture

The currently selected aperture in the selection manager.

Type
:BIM.Element|null

currentElement

The currently selected element in the selection manager.

Type
:BIM.Junction|null

currentJunction

The currently selected junction in the selection manager.

Type
:PD.SELECTED

currentType

The current model selection type in the selection manager.

Type
:boolean

depthSort

Whether or not to bias potential selections to those closest to the eye position.

When selecting in a 3D model, you typically want to select the object closest to the current eye position. However, when selecting in plan view with an orthographic camera, all objects are effectively at the same depth, so distance testing is irrelevant.

Type
  • boolean
:PD.FILTER

filter

Stores any limits in the selectable features to check.

Type
:PD.SelectionSet

foundItems

Stores the selected items when using region-based selection.

Type
:THREE.Frustum

frustum

The selection frustum for region-based selection.

Type
:boolean

intersectFrustum

Whether or not to select items that just cross or intersect the frustum.

Type
  • boolean
:THREE.Vector3

intersection

A volatile point that external classes can use for ray intersection testing.

This point is set by several methods within the PD.ModelManager class and subsequently used in the found*() methods of this class when depth-sorting the selection. Its position is also sometimes copied into the PD.Selection#closestIntersection and PD.Selection#storedPoint properties of the closest selection data.

Type
  • THREE.Vector3
:boolean

isSelection <readonly>

A flag identifying this object as interactive selection data.

Type
  • boolean
:boolean

keepExisting

Whether or not the current selection is to be adjusted rather than completely replaced.

Type
  • boolean
:number

radius

The selection radius, typically set by the scene manager based on the overall size of the current scene and the current camera zoom factor.

Type
  • number
:THREE.Ray

ray

The selection ray cast by the raycaster object.

When generated by the scene manager during normal interactive user selection, the origin of this ray is the current camera position within the scene.

Thus, it can be used to sort the relative distances of potentially selected objects within the current view. The initial selection when viewing the model in 3D is typically biased to elements closest to the current eye position.

Type
  • THREE.Ray
:THREE.RayCaster

rayCaster

The raycaster object that generated the selection ray.

Type
  • THREE.RayCaster
:PD.SELECT_ACTION

selectAction

Determines how selected items are integrated with any existing model selection set.

Type
:PD.SELECTED

selectedType

The type of selection just made.

Type
:THREE.Vector3

storedPoint

The assigned stored point for proximity checks.

When a particular selection type doesn't have an obvious closest point to reference, the associated found*() methods of this class will set its position based on the selection ray intersection point and use it as the reference for PD.Selection#closestPoint to the selection.

Type
  • THREE.Vector3
:PD.FILTER

DefaultFilter <static>

The default filter for which features are interactively selectable.

Type

Methods

addClearClosestCallback(callback)

Add a callback function to be invoked whenever the clear method is called.

Parameters:
Name Type Description
callback function

The function to call when the selection is cleared.
Returns:

Returns the callback method so it can be removed.

Type
function

clearSelection()

Calls all the registered clear selection callbacks.

Returns:

Returns this selection data to support method chaining.

Type
PD.Selection

foundApertureInJunction(element, contour_index, vertex_index1, vertex_index2, aperture, force_select)

Check to assign an aperture between two vertices as selected.

Parameters:
Name Type Description
element BIM.Element

The element containing the selected vertex.
contour_index number

The ordinal index of the contour in the element path.
vertex_index1 number

The ordinal index of the first vertex in the path contour.
vertex_index2 number

The ordinal index of the second vertex in the path contour.
aperture BIM.Aperture

The aperture belonging to the path junction.
force_select boolean

When true, ignores depth tests and forces selection.
Throws:

Throws an error if element does not have a path or the selected aperture is not found within it.

Type
Error
Returns:

Returns true if this is the closest intersection to eye position.

Type
boolean

foundControlNode(element, contour_index, junction_index, node_index, force_select)

Check to assign a curve control point as selected.

Parameters:
Name Type Description
element BIM.Element

The element containing the selected vertex.
contour_index number

The ordinal index of the contour in the element path.
junction_index number

The ordinal index of the junction in the path contour.
node_index number

The ordinal index of the control point in the junction curve.
force_select boolean

When true, ignores depth tests and forces selection.
Throws:

Throws an error if element does not have a path or the selected junction is not found within it.

Type
Error
Returns:

Returns true if this is the closest intersection to eye position.

Type
boolean

foundElement(element [, intersection] [, force_select])

Check to assign an element as selected.

Parameters:
Name Type Argument Default Description
element BIM.Element

The element to select.
intersection THREE.Vector3 <optional>
 null

The selection intersection point with the element.
force_select boolean <optional>
 false

When true, ignores depth tests and forces selection.
Throws:

Throws an error if element is not valid.

Type
Error
Returns:

Returns true if the element is valid and set as the current selection.

Type
boolean

foundFacetInShell(element, shell, facet, force_select)

Check to assign an aperture between two vertices as selected.

Parameters:
Name Type Description
element BIM.Element

The element containing the selected vertex.
shell PD.Shell

The shell that the facet belongs to.
facet PD.Polygon

The selected facet within the shell.
force_select boolean

When true, ignores depth tests and forces selection.
Throws:

Throws an error if shell is invalid or the selected facet was not found within it.

Type
Error
Returns:

Returns true if this is the closest intersection to eye position.

Type
boolean

foundLevel(level [, intersection] [, force_select])

Check to assign a level as selected.

Parameters:
Name Type Argument Default Description
level BIM.Level

The level to select.
intersection THREE.Vector3 <optional>
 null

The selection intersection point with the level.
force_select boolean <optional>
 false

When true, ignores depth tests and forces selection.
Throws:

Throws an error if level is not valid.

Type
Error
Returns:

Returns true if the level is valid and set as the current selection.

Type
boolean

foundPathJunction(element, contour_index, junction_index, force_select)

Check to assign a path junction as selected.

Parameters:
Name Type Description
element BIM.Element

The element containing the selected vertex.
contour_index number

The ordinal index of the contour in the element path.
junction_index number

The ordinal index of the junction in the path contour.
force_select boolean

When true, ignores depth tests and forces selection.
Throws:

Throws an error if element does not have a path or the selected vertex is not found within it.

Type
Error
Returns:

Returns true if this is the closest intersection to eye position.

Type
boolean

foundPathSegment(element, contour_index, junction_index1, junction_index2)

Check to assign a path segment between two vertices as selected.

Parameters:
Name Type Description
element BIM.Element

The element containing the selected junction.
contour_index number

The ordinal index of the contour in the element path.
junction_index1 number

The ordinal index of the first junction in the path contour.
junction_index2 number

The ordinal index of the second junction in the path contour.
Throws:

Throws an error if element does not have a path or the selected junction is not found within it.

Type
Error
Returns:

Returns true if this is the closest intersection to eye position.

Type
boolean

foundPathSegmentByFacet(element, contour_index, junction_index1, junction_index2 [, intersection] [, force_select])

Check to assign a path segment between two vertices as selected.

Parameters:
Name Type Argument Description
element BIM.Element

The element containing the selected junction.
contour_index number

The ordinal index of the contour in the element path.
junction_index1 number

The ordinal index of the first junction in the path contour.
junction_index2 number

The ordinal index of the second junction in the path contour.
intersection THREE.Vector3 <optional>

The selection intersection point with the junction facet.
force_select boolean <optional>

When true, ignores depth tests and forces selection.
Throws:

Throws an error if element does not have a path or the selected junction is not found within it.

Type
Error
Returns:

Returns true if this is the closest intersection to eye position.

Type
boolean

foundStructure(structure [, intersection] [, force_select])

Check to assign a structure as selected.

Parameters:
Name Type Argument Default Description
structure BIM.Structure

The structure to select.
intersection THREE.Vector3 <optional>
 null

The selection intersection point with the structure.
force_select boolean <optional>
 false

When true, ignores depth tests and forces selection.
Throws:

Throws an error if structure is not valid.

Type
Error
Returns:

Returns true if the structure is valid and set as the current selection.

Type
boolean

foundSurfaceEdge(element, surface, edge, force_select)

Check to assign a surface edge as selected.

Parameters:
Name Type Description
element BIM.Element | null

The element containing the surface, if any.
surface PD.BRep

The surface that the edge belongs to.
edge Array.<PD.Point>

The selected edge within the surface.
force_select boolean

When true, ignores depth tests and forces selection.
Throws:

Throws an error if surface is invalid or the selected facet was not found within it.

Type
Error
Returns:

Returns true if this is the closest intersection to eye position.

Type
boolean

foundSurfaceFacet(element, surface, facet, force_select)

Check to assign a surface facet as selected.

Parameters:
Name Type Description
element BIM.Element | null

The element containing the surface, if any.
surface PD.BRep

The surface that the facet belongs to.
facet PD.BRep.Face

The selected facet within the surface.
force_select boolean

When true, ignores depth tests and forces selection.
Throws:

Throws an error if surface is invalid or the selected facet was not found within it.

Type
Error
Returns:

Returns true if this is the closest intersection to eye position.

Type
boolean

foundSurfaceVertex(element, surface, vertex, force_select)

Check to assign a surface vertex as selected.

Parameters:
Name Type Description
element BIM.Element | null

The element containing the surface, if any.
surface PD.BRep

The surface that the edge belongs to.
vertex PD.Point

The selected vertex within the surface.
force_select boolean

When true, ignores depth tests and forces selection.
Throws:

Throws an error if surface is invalid or the selected vertex was not found within it.

Type
Error
Returns:

Returns true if this is the closest intersection to eye position.

Type
boolean

getHandler(nameOrValue)

Retrieves the registered handler for the given selection type.

Parameters:
Name Type Description
nameOrValue string | number

A selection type.
Returns:

Returns the class instance for the given type, or null if not found.

Type
PD.SelectionHandler | null

hasFoundItems()

Checks if the last selection used a view frustum and whether any items were found.

Returns:

Returns true if items were found in frustum.

Type
boolean

removeClearClosestCallback(callback)

Add a callback function to be invoked whenever the clearSelection method is called.

Parameters:
Name Type Description
callback function

The callback function added to PD.Selection#addClearSelectionCallback.
Returns:

Returns true if the callback was present and removed.

Type
boolean

reset(selector [, radius] [, sort])

Reinitialises all selection data in order to begin a new selection.

NOTE: When generated by the SceneManager during normal interactive user-selection, the origin of the selection ray is also the current camera position.

Parameters:
Name Type Argument Description
selector THREE.Raycaster | THREE.Frustum

The ray caster or frustum to use for selection.
radius number <optional>

The selection radius threshold when using a selection ray, in model coordinates, defaults to default radius.
sort boolean <optional>

Whether or not to sort potential selections by distance when using a selection ray, defaults to false.
Returns:

Returns this selection data to support method chaining.

Type
PD.Selection