Three Vue3Three Vue3
Guide
Demo
AI Agents
  • English
  • 简体中文
GitHub
Guide
Demo
AI Agents
  • English
  • 简体中文
GitHub
    • Getting Started
    • Scene
    • Parameter Bus
    • SkyBox
    • Model Loader

      • Component Loader
      • Function Loader
    • Popup
    • Callout
    • Movable Element
    • Animation
    • Model Rotator
    • Picker
      • Default Usage
      • Constructor
      • Methods
      • PickEvent
    • Fit Camera
    • Mesh

      • Wave Circle Mesh
      • Flow Line Mesh
    • Effect

      • Nature

        • Rain
        • Snow
        • Water
        • Water Pool
        • Sandy Beach
      • Sky & Atmosphere

        • Sky Dome
        • HeightFog
        • Nebula Galaxy
      • Light

        • Bloom
        • Sweep Light
        • Light Gradient
        • Light Pillar
        • Radar Sweep
        • Signal Wave
        • Force Shield
      • Particles & Sprites

        • Fireworks
        • Text Fireworks
        • Glow Sprite
    • GIS

      • Geographic Reference
      • GeoObject
      • GeoJsonLayer
      • Tile Layer

type

Class

Picker turns pointer events on the canvas into hover and click events. It coalesces pointer moves into one raycast per frame, optionally traverses descendants, and ignores drags so orbiting the camera does not fire a click.

Default Usage

Click me to view the codes
<template>
  <tv-scene class="scene" bg-color="rgb(40, 42, 54)" @created="created"></tv-scene>
</template>

<script lang="ts" setup>
import { onBeforeUnmount } from 'vue'
import * as THREE from 'three'
import { Picker } from 'three-vue3'

const COLORS = [0x4fc3f7, 0x81c784, 0xffb74d, 0xe57373, 0xba68c8, 0x4db6ac]
const POSITIONS: Array<[number, number, number]> = [
  [-3, 0, 0],
  [-1.8, 0, 0],
  [-0.6, 0, 0],
  [0.6, 0, 0],
  [1.8, 0, 0],
  [3, 0, 0]
]

let picker: Picker | undefined
let hovered: THREE.Mesh | null = null

const created = (scene, { camera, renderer }) => {
  camera.position.set(0, 1, 6)
  camera.lookAt(0, 0, 0)

  POSITIONS.forEach((position, index) => {
    const mesh = new THREE.Mesh(
      new THREE.BoxGeometry(0.8, 0.8, 0.8),
      new THREE.MeshStandardMaterial({ color: COLORS[index] })
    )
    mesh.position.set(...position)
    scene.add(mesh)
  })

  picker = new Picker(scene, camera, renderer.domElement)

  picker.on('hover', (event) => {
    if (hovered) {
      ;(hovered.material as THREE.MeshStandardMaterial).emissive.setHex(0x000000)
      hovered = null
    }
    if (event) {
      hovered = event.object as THREE.Mesh
      ;(hovered.material as THREE.MeshStandardMaterial).emissive.setHex(0x444444)
    }
    renderer.domElement.style.cursor = event ? 'pointer' : ''
  })

  picker.on('click', (event) => {
    if (!event) return
    const material = (event.object as THREE.Mesh).material as THREE.MeshStandardMaterial
    material.color.setHex(Math.floor(Math.random() * 0xffffff))
  })
}

onBeforeUnmount(() => {
  picker?.dispose()
  picker = undefined
})
</script>

<style>
.scene {
  margin-top: 10px;
  margin-bottom: 16px;
  width: 100%;
  height: 300px;
}
</style>

Constructor

const picker = new Picker(scene, camera, renderer.domElement, {
  targets: [model],
  filter: (object) => object.userData.selectable === true
})
NameTypeDefaultDescription
targetsTHREE.Object3D[]optional Objects to test, defaults to the scene.
recursivebooleantrueoptional Traverse descendants of the targets.
filter(object: THREE.Object3D) => booleanoptional Keep only the intersections passing it.
enableHoverbooleantrueoptional Emit hover events on pointer move.
clickThresholdnumber5optional Max pointer travel in pixels for a click.
layersnumber | number[]optional Camera layers to pick from.
near / farnumberoptional Raycaster near / far planes.

Methods

NameParametersDescription
on(type: 'click' | 'hover', listener) => () => voidSubscribes and returns an unsubscribe function.
off(type, listener) => voidUnsubscribes a listener.
pickAt(clientX: number, clientY: number) => PickEvent | nullRaycasts at a client position without an event.
setTargets(targets?: THREE.Object3D[]) => voidReplaces the objects, undefined picks the scene.
setFilter(filter?: (object) => boolean) => voidReplaces the intersection filter.
setEnabled(enabled: boolean) => voidEnables or disables picking without detaching.
getHovered() => THREE.Object3D | nullThe object currently under the pointer.
dispose() => voidDetaches listeners and releases references.

PickEvent

NameTypeDescription
objectTHREE.Object3DThe intersected object.
pointTHREE.Vector3Intersection point in world space.
distancenumberDistance from the camera to the point.
intersectionTHREE.IntersectionThe closest intersection that passed the filter.
intersectionsTHREE.Intersection[]All intersections, sorted by distance.
pointerTHREE.Vector2Pointer position in normalized device coordinates.
Edit this page on GitHub
Last Updated:
Contributors: Shing Rui
Prev
Model Rotator
Next
Fit Camera