PickingPlugin

Example — Source Code — API Reference

Picking Plugin adds support for selecting and hovering over objects in the viewer with user interactions and selection widgets.

When the plugin is added to the viewer, it starts listening to the mouse move and click events over the canvas. When an object is clicked, it is selected, and if a UI plugin is added, the uiconfig for the selected object is populated in the interface. The events selectedObjectChanged, hoverObjectChanged, and hitObject can be listened to on the plugin.

Picking plugin internally uses ObjectPicker, check out the documentation or source code for more information.

import {ThreeViewer, PickingPlugin} from 'threepipe'

const viewer = new ThreeViewer({...})

const pickingPlugin = viewer.addPluginSync(new PickingPlugin())

// Hovering events are also supported, but since its computationally expensive for large scenes it is disabled by default.
pickingPlugin.hoverEnabled = true

pickingPlugin.addEventListener('hitObject', (e)=>{
  // This is fired when the user clicks on the canvas.
  // The selected object hasn't been changed yet, and we have the option to change it or disable selection at this point.
    
  // e.intersects.selectedObject contains the object that the user clicked on.
  console.log('Hit: ', e.intersects.selectedObject)
  // It can be changed here 
  // e.intersects.selectedObject = e.intersects.selectedObject.parent // select the parent
  // e.intersects.selectedObject = null // unselect
  
  // Check other properties on the event like intersects, mouse position, normal etc.
  console.log(e)
})

pickingPlugin.addEventListener('selectedObjectChanged', (e)=>{
  // This is fired when the selected object is changed.
  // e.object contains the new selected object. It can be null if nothing is selected.
  console.log('Selected: ', e.object)
})

// Objects can be programmatically selected and unselected

// to select
pickingPlugin.setSelectedObject(object)

// get the selected object
console.log(pickingPlugin.getSelectedObject())
// to unselect
pickingPlugin.setSelectedObject(null)

// Select object with camera animation to the object
pickingPlugin.setSelectedObject(object, true)

pickingPlugin.addEventListener('hoverObjectChanged', (e)=>{
  // This is fired when the hovered object is changed.
  // e.object contains the new hovered object.
  console.log('Hovering: ', e.object)
})

Multi-Selection

Picking Plugin supports selecting multiple objects simultaneously using modifier keys. Multi-selection is enabled by default and can be disabled:

pickingPlugin.multiSelectEnabled = false // disable Shift+Click multi-selection

Keyboard Shortcuts

Key	Action
Shift+Click	Toggle object in/out of selection
Ctrl/Cmd+Click	Toggle object in/out of selection
Click (no modifier)	Replace selection with single object
Ctrl/Cmd+A	Select all visible model objects
Escape	Clear entire selection

API

// Get all selected objects
const objects = pickingPlugin.getSelectedObjects()

// Toggle an object in/out of selection
pickingPlugin.toggleSelectedObject(object)

// Select all visible model objects
pickingPlugin.selectAll()

// Clear entire selection
pickingPlugin.clearSelection()

// The selectedObjectChanged event includes the full selection array
pickingPlugin.addEventListener('selectedObjectChanged', (e) => {
    console.log('Primary:', e.object)    // last clicked object
    console.log('All:', e.objects)        // full selection array
})

Multi-selection works with TransformControlsPlugin and PivotControlsPlugin for group transforms. PivotEditPlugin operates on single objects and exits edit mode when the selection changes.