SelectionService

Manages object selection, hover, and multi-selection. Visual highlighting is delegated to a pluggable IHighlightStrategy (default: material swap).

Access

Registered under the name "selection". Depends on rendering, material, mesh.

import { SelectionService } from "@optellix/xviewr-sdk";

await viewer.ready();
const selection = viewer.getService<SelectionService>("selection");

Since 4.0

• Canvas-scoped input: pointer listeners attach to renderer.domElement (not window). Events that started outside the canvas are ignored.
• Raycasting respects the active cross-section clipping planes — meshes clipped by section planes at the hit point are filtered out.
• Edge hover and edge selection highlights: hovering or clicking loaded STEP edge overlays (userData.isEdges) produces a LineSegments2 highlight instead of a mesh highlight.
• Neighbour selection now delegates to AdvancedMeshService. selectNeighbourByContact(depth?) calls findContactNeighbours; selectNeighbourByRadius(radius, options?) calls findProximityNeighbours.
• Region selection: selectByScreenRegion(startX, startY, endX, endY, options?: SelectByScreenRegionOptions) with SelectionRegionMode ("intersects" or "contains") and a ScreenRect bounds shape.

Public API

Lifecycle

• activate(): void
• deactivate(): void
• updateConfig(config: Partial<SelectionConfig>): void

Selection

• selectObject(object: THREE.Object3D, addToSelection?: boolean): boolean
• deselectObject(object: THREE.Object3D): boolean
• toggleSelection(object: THREE.Object3D): boolean
• selectAll(): THREE.Object3D[]
• invertSelection(): THREE.Object3D[]
• clearSelection(): void
• getSelectedObjects(): THREE.Object3D[]
• isSelected(object: THREE.Object3D): boolean
• selectByBoundingBox(box: THREE.Box3): THREE.Object3D[]

Neighbour selection (requires MeshService)

• selectNeighbourByContact(depth?: number): THREE.Object3D[]
• selectNeighbourByRadius(radius: number, options?: MeshRadiusNeighbourOptions): THREE.Object3D[]

Hover

• setHoverObject(object: THREE.Object3D | null): void
• clearHover(): void
• getHoveredObject(): THREE.Object3D | null

Raycasting

• raycastAt(x: number, y: number): THREE.Object3D | null — canvas-relative coords. Respects active cross-section clipping planes.

Highlight strategy

• setHighlightStrategy(strategy: IHighlightStrategy): Promise<void> — disposes the previous strategy and reapplies highlights with the new one.

Events

Event	Payload
selection:activated	null
selection:deactivated	null
selection:config-updated	{ config, previousConfig }
selection:object-selected	{ object, selectedObjects }
selection:object-deselected	{ object, selectedObjects }
selection:all-selected	{ previousSelected, selectedObjects }
selection:inverted	{ previousSelected, selectedObjects }
selection:neighbour-selected	{ method, sourceObjects, neighbours, selectedObjects, ... }
selection:cleared	{ clearedObjects }
selection:changed	{ selected, previous }
selection:hover-changed	{ object }

Example

const selection = viewer.getService<SelectionService>("selection");

selection.updateConfig({
  multiSelect: true,
  highlightColor: "#1c66bc",
  hoverEnabled: true,
});

viewer.eventBus.on("selection:object-selected", ({ object }) => {
  console.log("selected:", object.name);
});

Configuration

interface SelectionConfig {
  enabled: boolean;
  multiSelect: boolean;
  hoverEnabled: boolean;
  selectableOnly: boolean;     // requires userData.isSelectable
  highlightColor: string;
  hoverColor: string;
  highlightIntensity: number;
  outlineWidth: number;
}

Custom highlight strategies

Implement IHighlightStrategy to override the visual treatment.

interface IHighlightStrategy {
  init(context: HighlightContext, config: HighlightStyleConfig): Promise<void>;
  apply(object: THREE.Object3D, type: "selected" | "hovered"): void;
  remove(object: THREE.Object3D): void;
  updateStyle(config: HighlightStyleConfig): void;
  dispose(): void;
}

interface HighlightContext {
  scene: THREE.Scene;
  camera: THREE.Camera;
  renderer: THREE.WebGLRenderer;
  materialService?: MaterialService | null;
}

interface HighlightStyleConfig {
  selectedColor: string;
  hoverColor: string;
  intensity: number;
  outlineWidth: number;
}