ar-hit-test
NOTE: This version of the documentation tracks unstable development happening on A-Frame’s
masterbranch. If you wish to try it out, grab the unstable build. Otherwise, head to the documentation for the current 1.6.0 version
This component uses the WebXR hit-test API to position virtual objects in the real world. Remember to request the hit-test optional feature to allow it work.
You add it to the scene element and then when the user is in Augmented Reality if they tap on the screen or select with a controller it will work out where the user is pointing to in the real world and place a reticle there and fire events.
If you have set a target property to be an element it will automatically make the reticle to be the same size as the footprint of the target and then when the user selects the object will be telepoted there. It will also set the visible state of the object to true so you can hide the object until the user has placed it for the first time. The hide-on-enter-ar component is useful for that.
You can toggle this component’s enabled state to not do any interactions until you are ready.
Example
<a-scene webxr="optionalFeatures: hit-test;" ar-hit-test="target:#myobject;"> |
Properties
| Property | Description | Default Value |
|---|---|---|
| target | The object to move around. | null |
| enabled | Whether to do hit-testing or not | true |
| src | Image to use for the reticle | See: Assets |
| type | ‘footprint’ or ‘map’ footprint is the shape of the model | “footprint” |
| footprintDepth | Amount of the model used for the footprint, 1 is full height | 0.1 |
| mapSize | If no target is set then this is the size of the map | 0.5 0.5 |
Events
| Event Name | Description |
|---|---|
| ar-hit-test-start | The AR Hit Test system has managed start scanning |
| ar-hit-test-achieved | The AR Hit Test system has managed to find a surface to start hit testing on |
| ar-hit-test-select | The user has stopped positioning the detail contains the latest position, orientation and inputSource that was used |