mirror of
https://github.com/google-ar/three.ar.js.git
synced 2026-01-18 13:56:33 +00:00
138 lines
6.3 KiB
Markdown
138 lines
6.3 KiB
Markdown
# 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.Object3D]s to be tracked and updated accurately as scene understanding improves via anchors. Extends `EventTarget`, so subscribe to events via:
|
|
|
|
```js
|
|
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.Object3D]s 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:
|
|
|
|
```js
|
|
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.
|
|
|
|
[VRDisplay]: https://developer.mozilla.org/en-US/docs/Web/API/VRDisplay
|
|
[THREE.WebGLRenderer]: https://threejs.org/docs/#api/renderers/WebGLRenderer
|
|
[THREE.PerspectiveCamera]: https://threejs.org/docs/#api/cameras/PerspectiveCamera
|
|
[THREE.Scene]: https://threejs.org/docs/#api/scenes/Scene
|
|
[THREE.Material]: https://threejs.org/docs/#api/materials/Material
|
|
[THREE.Mesh]: https://threejs.org/docs/#api/objects/Mesh
|
|
[THREE.Group]: https://threejs.org/docs/#api/objects/Group
|
|
[THREE.BufferGeometry]: https://threejs.org/docs/#api/core/BufferGeometry
|
|
[THREE.Color]: https://threejs.org/docs/#api/math/Color
|
|
[THREE.Object3D]: https://threejs.org/docs/#api/core/Object3D
|
|
[OBJLoader]: https://github.com/mrdoob/three.js/blob/master/examples/js/loaders/OBJLoader.js
|
|
[MTLLoader]: https://github.com/mrdoob/three.js/blob/master/examples/js/loaders/MTLLoader.js
|
|
[HTMLElement]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement
|
|
[VRHit]: webvr_ar_extension.idl
|
|
[Poly]: https://poly.google.com/
|