DOCSEARCHbyAlgolia
Submit Docs

AR.js Documentation

repository·master·Indexed 26 days ago

https://github.com/ar-js-org/ar.js

A lightweight library for performing Augmented Reality on the web, supporting Image Tracking (NFT), Marker-based tracking, and Location-based AR. It provides dedicated builds for A-Frame and Three.js, including specialized components like gps-camera and gps-entity-place for geographic positioning, and supports ES6 module imports via import maps since version 3.4.6.

Tokens
4.7K
Snippets
7
Records
29
Agent score
90%

What's inside AR.js

  1. Use the new location-based components

    master
    AR.js provides a new set of location-based components designed to be simpler and easier to maintain than the original implementation. These components wrap the three.js location-based AR.js API and are recommended for new projects as they receive more active development and bug fixes. If you encounter issues with these new components, you can fall back to the original location-based components.

  3. Import AR.js Three.js modules using ES6 Import Maps

    master

    Since version 3.4.6, Three.js and AR.js modules (ar-threex.mjs, ar.mjs, and ar-threex-location-only.mjs) can be imported using standard ES module syntax via an import map. This is the recommended way to use AR.js in modern JavaScript environments.

    <script type="importmap">
{
  "imports": {
    "three": "https://cdn.jsdelivr.net/npm/three@0.164.0/build/three.module.js",
    "threex": "./path/to/ar-threex.mjs",
  }
}
</script>

<script type="module">
import * as THREE from 'three';
import { ArToolkitSource, ArToolkitContext, ArMarkerControls }  from 'threex'

// Your AR.js code here
</script>

  4. Select the appropriate AR.js build

    master

    AR.js provides several exclusive builds depending on your framework (A-Frame or Three.js) and the tracking features you require. Do not import more than one build into your project.

    A-Frame Builds

    • Image Tracking + Location Based AR: Use aframe-ar-nft.js.
    • Marker Tracking + Location Based AR: Use aframe-ar.js.

    Three.js Builds

    • Image Tracking + Marker Tracking: Use ar-threex.js (provides ARjs namespace via ar.js) or ar-threex.mjs (ES6 module).
    • Location Based AR only: Use ar-threex-location-only.js.

  5. Choose between original and new location-based components

    master

    AR.js provides two sets of location-based components for A-Frame.

    1. New Location-Based Components: These wrap the three.js location-based API and are the recommended choice for most developers as they receive more active development and bug fixes.
    2. Original Location-Based Components: These are legacy components developed in 2020 or earlier. You should only use these if the new components do not meet your specific requirements or fail to work in your implementation.

  6. Use AR.js Location Based Implementation with Pure Three.js

    master

    This implementation provides location-based Augmented Reality using pure Three.js.

    Platform Limitations & Requirements:

    • Browser Support: Currently only works reliably on Chrome due to limitations in obtaining compass bearing on other browsers.
    • OS Support: Tested on Android. Support for iOS/Webkit is unverified, though it may be possible via webkitCompassHeading.
    • Hardware: Requires a mobile device with GPS and a compass/magnetometer.

    Implementation Logic: When using the provided example logic, the behavior depends on the device's GPS state:

    1. GPS Enabled: You must manually modify the implementation code (e.g., example/location-based/index.js) to place Three.js meshes at specific geographic coordinates near your current location.
    2. GPS Disabled: A fakeGps mode will trigger, displaying four default meshes to demonstrate functionality.

  7. Use A-Frame components for Location-Based AR

    master

    The @ar-js-org/ar.js package provides several A-Frame components specifically designed for location-based augmented reality. These components allow you to control device orientation, manage the GPS camera, place entities at specific geographic coordinates, and handle projected camera views.

    Key components available for use in A-Frame scenes include:

    • arjs-look-controls: Controls for looking around the scene.
    • arjs-webcam-texture: Manages the webcam feed as a background texture.
    • ArjsDeviceOrientationControls: Handles device orientation for AR.
    • gps-camera: A camera component that uses GPS data to position the user in the virtual world.
    • gps-entity-place: A component for placing entities at specific latitude and longitude coordinates.
    • gps-projected-camera: A camera component for projected views.
    • gps-projected-entity-place: A component for placing entities in a projected coordinate system.

  8. Use AR.js A-Frame components

    master
    AR.js provides a suite of A-Frame components for Augmented Reality, including anchor tracking, hit testing, and location-based positioning. These components are designed to be attached to A-Frame entities within an <a-scene> to enable AR capabilities.

  9. Use the A-Frame Location-Based AR components

    master
    The @ar-js-org/ar.js package provides A-Frame components for the new location-based AR implementation. By importing this entrypoint, you gain access to components for webcam textures, GPS camera controls, and GPS-based entity placement. These components are designed to work within an A-Frame scene to enable location-aware augmented reality.

  10. Implement Location Based AR with A-Frame

    master

    To place content at specific geographic coordinates, use the aframe-ar-nft.js build (which supports location features) and the gps-entity-place component. You must also use a gps-camera to track the user's position.

    Requirements:

    • Activate GPS on the mobile device.
    • Use gps-entity-place="latitude: <lat>; longitude: <lng>;" on the entity you wish to place.
    • Use <a-camera gps-camera rotation-reader></a-camera>.
    <!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <script src="https://aframe.io/releases/1.6.0/aframe.min.js"></script>
    <script src="https://unpkg.com/aframe-look-at-component@1.0.0/dist/aframe-look-at-component.min.js"></script>
    <script src="https://raw.githack.com/AR-js-org/AR.js/master/aframe/build/aframe-ar-nft.js"></script>
  </head>
  <body>
    <a-scene
      vr-mode-ui="enabled: false"
      arjs="sourceType: webcam; videoTexture: true; debugUIEnabled: false;"
    >
      <a-text
        value="This content will always face you."
        look-at="[gps-camera]"
        scale="120 120 120"
        gps-entity-place="latitude: <add-your-latitude>; longitude: <add-your-longitude>;"
      ></a-text>
      <a-camera gps-camera rotation-reader> </a-camera>
    </a-scene>
  </body>
</html>

  11. Implement Image Tracking with A-Frame (NFT)

    master

    To use Natural Feature Tracking (NFT) for image tracking in A-Frame, use the aframe-ar-nft.js build. You must provide a URL to the image descriptors (the url attribute in <a-nft>) and a GLTF model to display.

    Note on CORS: If your image descriptors or models are hosted on a different server, you will encounter CORS errors. Ensure all resources are hosted on the same server as your code or use a CORS proxy.

    <script src="https://cdn.jsdelivr.net/gh/aframevr/aframe@1.6.0/dist/aframe-master.min.js"></script>
<script src="https://raw.githack.com/AR-js-org/AR.js/master/aframe/build/aframe-ar-nft.js"></script>

<body style="margin : 0px; overflow: hidden;">
  <a-scene
    vr-mode-ui="enabled: false;"
    renderer="logarithmicDepthBuffer: true; precision: medium;"
    embedded
    arjs="trackingMethod: best; sourceType: webcam;debugUIEnabled: false;"
  >
    <a-nft
      type="nft"
      url="your-server/path/to/descriptors"
      smooth="true"
      smoothCount="10"
      smoothTolerance=".01"
      smoothThreshold="5"
    >
      <a-entity
        gltf-model="your-server/path/to/scene.gltf"
        scale="5 5 5"
        position="150 300 -100"
      >
      </a-entity>
    </a-nft>
    <a-entity camera></a-entity>
  </a-scene>
</body>

  12. Implement Marker Based AR with A-Frame

    master

    To use traditional marker tracking (e.g., the Hiro marker), use the aframe-ar.js build. You define a marker using the <a-marker> component with a preset attribute and place your content inside it.

    <!DOCTYPE html>
<html>
    <script src="https://aframe.io/releases/1.6.0/aframe.min.js"></script>
    <script src="https://raw.githack.com/AR-js-org/AR.js/master/aframe/build/aframe-ar.js"></script>
    <body style="margin : 0px; overflow: hidden;">
        <a-scene embedded arjs>
        <a-marker preset="hiro">
            <a-entity
            position="0 0 0"
            scale="0.05 0.05 0.05"
            gltf-model="your-server/path/to/scene.gltf"
            ></a-entity>
        </a-marker>
        <a-entity camera></a-entity>
        </a-scene>
    </body>
</html>