XR
XR Features
Galacean XR currently supports the following features:
Feature | Description |
---|
Anchor Tracking | Anchor tracking |
Plane Tracking | Plane tracking |
Image Tracking | Image tracking |
Hit Test | Collision detection |
Property | Description |
---|
trackingAnchors | (Read-only) Get anchors requested for tracking |
trackedAnchors | (Read-only) Get successfully tracked anchors |
Method | Description |
---|
addAnchor | Add a specific anchor |
removeAnchor | Remove a specific anchor |
clearAnchors | Remove all anchors |
addChangedListener | Add listener for anchor changes |
removeChangedListener | Remove anchor change listener |
Example code to add an anchor in XR space:
const anchorTracking = xrManager.getFeature(XRAnchorTracking);
const position = new Vector3();
const rotation = new Quaternion();
// Add an anchor
const anchor = anchorTracking.addAnchor(position, rotation);
// Remove this anchor
anchorTracking.removeAnchor(anchor);
// Listen for anchor changes
anchorTracking.addChangedListener(
(added: readonly XRAnchor[], updated: readonly XRAnchor[], removed: readonly XRAnchor[]) => {
// Handle added, updated, and removed anchors here
}
);
Property | Description |
---|
detectionMode | (Read-only) Plane detection type (horizontal, vertical, or all) |
trackedPlanes | (Read-only) Get successfully tracked planes |
Method | Description |
---|
addChangedListener | Add listener for plane changes |
removeChangedListener | Remove plane change listener |
Note: Plane detection type must be specified when enabling this feature.
// Set plane detection mode to "All" during initialization
xrManager.addFeature(XRPlaneTracking, XRPlaneMode.EveryThing);
You can detect real-world planes and mark them with transparent grids and coordinate systems.
Property | Description |
---|
trackingImages | (Read-only) Array of images requested for tracking (contains name, source, and size) |
trackedImages | (Read-only) Get successfully tracked images |
Method | Description |
---|
addChangedListener | Add listener for image changes |
removeChangedListener | Remove image change listener |
Note: Image tracking requires pre-defined reference images. In the engine, these are represented by XRReferenceImage
objects:
Property | Description |
---|
name | Name of the reference image (unique identifier) |
imageSource | Source of the image (typically an HtmlImageElement ) |
physicalWidth | Physical size of the image in the real world (default in meters, e.g., 0.08 means 8 cm) |
In WebXR, the same image will only be tracked once.
const image = new Image();
image.onload = () => {
// Create reference image
const refImage = new XRReferenceImage("test", image, 0.08);
// Enable image tracking and specify reference image
xrManager.addFeature(XRImageTracking, [refImage]);
};
image.src = "Image URL";
Method | Description |
---|
hitTest | Perform collision detection by casting a ray against real-world planes |
screenHitTest | Perform collision detection using screen space coordinates |
const pointer = engine.inputManager.pointers[0];
// Get plane hit point
if (pointer) {
const hitTest = xrManager.getFeature(XRHitTest);
const { position } = pointer;
// Perform screen-to-world collision detection
const result = hitTest.screenHitTest(position.x, position.y, TrackableType.Plane);
}