Getting Started A-Frame

Getting Started with A-Frame AR

by Michael Colonna

A-Frame AR (aframe-ar from now on) is a library that enables A-Frame support for web AR, including three.ar.js as well as the experimental browsers WebARonARKit / WebARonARCore by Google and WebXR Viewer by Mozilla. 

Developing for aframe-ar

Developing for aframe-ar is very similar to developing for A-Frame. When developing a web AR experience, it's a good idea to use a code editor like Glitch that automatically hosts and deploys your code when it changes. This way, you can access your AR web app from any device and (mostly) any browser! For the remainder of this tutorial, I will be using Glitch to host and deploy code, however, you can use whatever you are most comfortable with.

How to Experience aframe-ar

In order to experience an application that uses aframe-ar, you must download at least one of the following browsers, according to your mobile OS:

WebARonARKit/Core must be built from their source and run on the user's device. Each has a tutorial on how to do this via the links above. NOTE: For WebARonARKit/Core browsers, you must be able to connect your mobile device to your computer!

Creating Our First aframe-ar App!

Assuming you have downloaded at least one of the experimental browsers above, we can now dive right into our first application.

(If you're using Glitch, create a new hello-webpage application!)

Let's create a new index.html file. Copy these <script> tags into the header:

    <!-- First, include whichever version of A-Frame you like. -->

    <script src="https://aframe.io/releases/0.7.1/aframe.min.js"></script>    

    <!-- Next, include three.ar.js; add the speech recognition polyfill if you want. -->

    <script src="https://rawgit.com/google-ar/three.ar.js/f9603ee/dist/three.ar.js"></script>

    <!-- Last, include aframe-ar. -->

    <script src="https://rawgit.com/chenzlabs/aframe-ar/47aa7fa/dist/aframe-ar.min.js"></script>

These tags will include the A-Frame library, three.ar.js, and finally aframe-ar.

Now, in the <body>, let's create a simple scene. Copy these components into the body:

    <a-scene ar>

      <a-box width="0.25" height="0.25" depth="0.25" position="-0.25 0.125 -0.75" rotation="0 45 0" color="#4CC3D9" shadow></a-box>

      <a-sphere position="0 0.3125 -1.25" radius="0.3125" color="#EF2D5E" shadow></a-sphere>

      <a-cylinder position="0.25 0.1875 -0.75" radius="0.125" height="0.375" color="#FFC65D" shadow></a-cylinder>

      <a-plane position="0 0 -1" rotation="-90 0 0" width="1" height="1" color="#7BC8A4" shadow></a-plane>

    </a-scene>

This sets up a typical A-Frame scene with some primitive objects. Notice the ar component in the <a-scene> tag. This is an aframe-ar exclusive component that tells the experimental browser to create an AR scene using your mobile device's camera.

Great! Now let's use an experimental browser and navigate to our app's URL to see if our AR is working. You should see something like this:

Using WebXR Viewer

Cool! Web AR up and running in only a few lines of HTML! Unfortunately, this code does not do much. Let's add some simple interactivity.

Simple Interactivity: Change Color on Click

For this interaction, we'll take advantage of A-Frame's component architecture and create a component that handles click events.

Let's create a new file events.js and copy this code into it:

AFRAME.registerComponent('change-color-on-click', {


  init: function () {

    var el = this.el;

    

    el.addEventListener('click', function(evt) {

      // random color

      const randColor = "#"+((1<<24)*Math.random()|0).toString(16);

      el.setAttribute('color', randColor);

    });

  }

});

This script creates an A-Frame component called change-color-on-click. When this component is added to an A-Frame entity, it creates an event listener that attaches to the entity and listens for the click event. When a click event (i.e. successive mousedown and mouseup events) is registered, the event listener executes the handler function. In this case, the handler function simply generates a random hexidecimal color and sets the entity's 'color' attribute accordingly.

Now, back in index.html, include the events.js script in the header with the following script tags:

<script src="/events.js></script>

Next, let's add the change-color-on-click component to each of the primitive objects in our scene, like so:

    <a-scene ar>

      <a-box change-color-on-click width="0.25" height="0.25" depth="0.25" position="-0.25 0.125 -0.75" rotation="0 45 0" color="#4CC3D9" shadow></a-box>

      <a-sphere change-color-on-click position="0 0.3125 -1.25" radius="0.3125" color="#EF2D5E" shadow></a-sphere>

      <a-cylinder change-color-on-click position="0.25 0.1875 -0.75" radius="0.125" height="0.375" color="#FFC65D" shadow></a-cylinder>

      <a-plane change-color-on-click position="0 0 -1" rotation="-90 0 0" width="1" height="1" color="#7BC8A4" shadow></a-plane>

    </a-scene>

However, this code will still not work. This is because A-Frame does not, by default, use the mouse cursor as the origin of raycasts. To fix this, add the following property to the <a-scene> tag:

<a-scene ar cursor="rayOrigin: mouse;">

Now, use an experimental browser to navigate to your app's URL. You should be able to tap on each object and watch them change color! (Note: there may be high latency due to the experimental nature of the browser)

Congrats! You've made your first Web AR app with aframe-ar!