Skip to content
This repository has been archived by the owner on Jun 1, 2022. It is now read-only.

Latest commit

 

History

History
137 lines (89 loc) · 6.3 KB

API.md

File metadata and controls

137 lines (89 loc) · 6.3 KB
Raw

three.ar.js API

new THREE.ARView(vrDisplay, renderer)

Creates an ARView with a VRDisplay and a THREE.WebGLRenderer. Handles the pass through camera differences between ARCore and ARKit platforms, and renders the camera behind your scene.

THREE.ARView#render()

Renders the pass through camera. Usually called on every frame in a render loop before rendering other objects in the scene.

new THREE.ARAnchorManager(vrDisplay)

Creates an ARAnchorManager with a VRDisplay. Allows the adding of THREE.Object3Ds to be tracked and updated accurately as scene understanding improves via anchors. Extends EventTarget, so subscribe to events via:

  anchorManager.addEventListener('anchorsupdated', e => {
    e.anchors.forEach(obj => console.log('updated', obj));
  });

Currently there's only the anchorsupdated event has an anchors property containing an array of all updated THREE.Object3Ds when an anchor update occurs.

ARAnchorManager THREE.ARAnchorManager#add(object)

Takes a THREE.Object3D and sets an anchor at its current position. If anchor is updated, the object will be updated accordingly, and a anchorsupdated event will be fired on the ARAnchorManager. Returns the ARAnchorManager.

boolean THREE.ARAnchorManager#remove(object)

Removes the anchor from THREE.Object3D and will no longer be updated when an anchor changes. Returns a boolean indicating if the object was being tracked initially.

new THREE.ARReticle(vrDisplay, innerRadius, outerRadius, color, easing)

Creates a THREE.Mesh reticle to render via hit tests with the VRDisplay.

void THREE.ARReticle#update(x, y)

Performs a hit test at x and y normalized coordinates and lerps the reticle to the position. Usually called every frame to perform a hit test and cause the reticle to "trace" along surfaces for placing additional objects.

new THREE.ARPerspectiveCamera(vrDisplay, fov, aspect, near, far)

A subclass of THREE.PerspectiveCamera, used to create a perspective camera that matches your device's perspective and keep the projection matrix in sync with a device. Use this camera to render your three.js objects ontop of an AR see through camera. If a vrDisplay is not provided, or not an AR-capable display, falls back to a regular THREE.PerspectiveCamera with supplied values. Only the projectionMatrix is updated if using an AR-capable device, and the fov, aspect, near, far properties are not applicable.

void THREE.ARPerspectiveCamera#getProjectionMatrix()

If given a VRDisplay in constructor, generates the projection matrix from the API to match the native camera intrinsics. To use the cached projection matrix, just access the projectionMatrix property instead.

new THREE.ARDebug(vrDisplay, scene?, config)

Creates an ARDebug panel to display hit and pose information. Use getElement() to return the element managed by the ARDebug panel to inject into your content. Optionally takes THREE.Scene scene, needed for rendering of planes via showPlanes: true.

config is defined with defaults as follows:

config = {
  showPoseStatus: true,
  showLastHit: true,
  showPlanes: false,
};

THREE.ARDebug#open()

Opens the ARDebug panel.

THREE.ARDebug#close()

Closes the ARDebug panel.

HTMLElement THREE.ARDebug#getElement()

Returns the HTMLElement for the debug panel to inject into the content.

THREE.ARUtils

Not a constructor but an object storing several utility functions listed below.

Promise<VRDisplay?> THREE.ARUtils.getARDisplay()

Returns a promise that resolves to a VRDisplay with AR capabilities or null if device is unsupported.

boolean THREE.ARUtils.isARDisplay(vrDisplay)

Takes a VRDisplay instance and returns a boolean whether or not this is considered an AR display. Will most likely be featured-based in the future.

boolean THREE.ARUtils.isTango(vrDisplay)

Takes a VRDisplay instance and returns a boolean whether or not this is a Tango-backed/ARCore Android device.

boolean THREE.ARUtils.isARKit(vrDisplay)

Takes a VRDisplay instance and returns a boolean whether or not this is an ARKit-based iOS device.

Promise<THREE.Group> THREE.ARUtils.loadModel(config)

Takes configuration to load an OBJ model, and optionally a path for an MTL material and returns a promise resolving to a THREE.Group loaded with the appropriate material. Can be used on downloaded models from Poly.

config takes the following properties:

  • objPath: path to the OBJ model. Required.
  • mtlPath: path to the MTL material. Optional.
  • OBJLoader: A constructor for THREE's OBJLoader. Defaults to window.THREE.OBJLoader. Useful to specify when in an ES6 module environment.
  • MTLLoader: A constructor for THREE's MTLLoader. Defaults to window.THREE.MTLLoader. Useful to specify when in an ES6 module environment.

void THREE.ARUtils.placeObjectAtHit(object, hit, easing=1, applyOrientation=false)

Takes a THREE.Object3D and a VRHit object from a VRDisplay.prototype.hitTest call, and positions, and optionally orients, the object to the hit's model matrix. Optionally can use easing to lerp between the object's current transform to the hit's transform.

void THREE.ARUtils.displayUnsupportedMessage()

Generates an element and injects into the DOM a message notifying the user that their browser does not support prototype AR features. See examples of common usage.