ThreeAdapter

Wires XRSessionManager to a Three.js renderer

import { ThreeAdapter } from '@multisetai/vps/three';

Integrates XRSessionManager with a Three.js scene. Runs the XR render loop, synchronizes the camera each frame, downloads the map mesh on successful localization, and provides a worldFromMap matrix for content placement.

Constructor

new ThreeAdapter(options: IThreeAdapterOptions)

Options

Parameter	Type	Default	Description
session	XRSessionManager	Required	Session manager
renderer	THREE.WebGLRenderer	Required	Three.js renderer with xr.enabled = true
scene	THREE.Scene	Required	Three.js scene
camera	THREE.PerspectiveCamera	Required	Three.js camera
showMesh	boolean	false	Download and add the map mesh to the scene after localization
showGizmo	boolean	true	Show a transform gizmo at the map origin after localization
showObjectMeshes	boolean	false	Download and display 3D outline meshes for detected objects
useDefaultButton	boolean	true	Mount the built-in START AR / STOP AR button
buttonContainer	HTMLElement	—	Element to append the button to. Defaults to overlayRoot or document.body.
onButtonCreated	(button: HTMLButtonElement) => void	—	Called when the button is created
onXRFrame	(event: IXRFrameEvent) => void	—	Called every XR frame after camera sync, before rendering
onLocalizationSuccess	(result: ILocalizeAndMapDetails, worldFromMap: THREE.Matrix4) => void	—	Called after successful localization
onObjectMeshLoaded	(objectCode: string) => void	—	Called when an object mesh finishes loading. Requires showObjectMeshes: true.

Static Methods

Method	Returns	Description
ThreeAdapter.isSupported()	Promise<boolean>	Check if the browser supports immersive-ar

Instance Methods

Method	Returns	Description
initialize(buttonContainer?)	HTMLButtonElement | null	Start the preview loop, attach resize handler, and mount the AR button
startSession()	Promise<void>	Start the AR session. Must be called from a user gesture handler.
stopSession()	void	Stop the active session
localizeFrame()	Promise<ILocalizeAndMapDetails | null>	Capture and localize one frame
trackObjects()	Promise<IObjectTrackingResponse | null>	Capture and run object detection
isActive()	boolean	Whether an AR session is running
clearObjectMeshes()	void	Remove all loaded object meshes from the scene
dispose()	void	End session, remove listeners, release resources

Properties

Property	Type	Description
isLocalizing	boolean	Whether localization or tracking is in progress

The worldFromMap Matrix

onLocalizationSuccess receives a THREE.Matrix4 that converts map-local coordinates to Three.js world space. Use it to place objects at known positions within the map.

onLocalizationSuccess: (result, worldFromMap) => {
  // Place an object at map-local position (x=1, y=0, z=-2)
  const position = new THREE.Vector3(1, 0, -2);
  position.applyMatrix4(worldFromMap);
  myObject.position.copy(position);

  // Or apply the full transform to a group of objects
  const group = new THREE.Group();
  group.applyMatrix4(worldFromMap);
  scene.add(group);
}