So you want to get started with AR.js

~ 5 minutes - Published on Aug 3, 2018

Augmented Reality seems like it’s everywhere in 2018. Between Snapchat filters, Google stickers, IKEA’s furniture preview, and now Shopify’s AR Quick Look feature, putting 3D objects in the physical world seems to be more desirable than ever.

While an augmented reality feature might fit nicely into an established native application, there’s a downside to those non-app-based businesses who’d like to use AR for marketing purposes. For instance, say a handbag company wants to display a 3D model of a handbag above the box it ships in when the user points their camera at their logo on the box. Traditionally, they’d have to:

  • Develop a native application using ARKit/ARCore/ARToolkit/etc
  • Pay the requested fees to get it distributed to the Google Play/App Stores
  • Wait for approval from either of the above stores
  • Market the application to your prospective customers/users
  • Hope that the user downloads and then uses the app

All of this for what amounts to (on average) a 2–5 minute session playing around with the finished app. Additionally if it’s for a specific marketing campaign or time span, they’re more than likely not going to interact with it more than a few times.

The solution? AR.js, simple augmented reality directly in the browser and compatible with all modern mobile devices. Now, let’s get started!

 

What is AR.js?

To boil it down, it’s essentially a Javascript framework acting as a port of ARToolkit, while leveraging other packages like a-frame and three.js. The goal being augmented reality features directly on web browsers without sacrificing performance.

As far as compatibility goes, it works on any browser capable of WebGL + WebRTC. At the publishing time of this article, that would be Chrome, Firefox, Edge, and Safari. However, the current version of Chrome for iOS is not supported as of yet.

 

Getting a project set up

This assumes that you have a (local or otherwise) development environment already set up and secured with an SSL certificate. Why SSL? Chrome requires all sites that use scripts calling for camera access to be delivered strictly over https.

Following from Alexandra Etienne’s article we can have a working demo of AR.js up in just 8 lines of HTML.

Getting started with AR.js in just 8 lines of HTML

Throw that bad boy into an index.html file on your dev environment and open it up in your compatible browser of choice. You’ll get a request to access your camera, and on approval will see a live video feed from your device. Print out/load up the default hiro marker image and point it at the video feed. If everything went well, you should see a semi-clear white cube fixed over the marker.

Augmented reality, on the web!

Want to remove the debug boxes from the video display? Simply add the flag ‘debugUIEnabled: false;’ to the arjs prop in the a-scene element.

Code screenshot for how to remove debug information in AR.js

 

Using custom markers

This was honestly one of the most difficult pieces for me to get working properly when I was originally learning AR.js. There’s a few tutorials out there about how to get custom markers working, but between them there’s some conflicting information. I’m going to give the run-down of what worked best for me, broken down step by step.

Step 1. Decide on your marker image. For the best results this should be a simple, high-contrast, PNG image pre-cropped to be a square with a size of at least 512x512. This also has to be rotationally asymmetrical, meaning that it will always look unique regardless of the degree it’s rotated to. Here’s some good examples of marker images:

Examples of good AR.js markers

Step 2. Convert your image to a .patt file and an AR.js marker. Using this marker trainer, upload an image that you’d like to use as a marker. If it looks good to you, then go ahead and click:

  • Download Marker: The .patt file AR.js uses to recognize the marker and display your 3D content.
  • Download Image: The actual .png image with the appropriate black border to be used as the physical marker.

Step 3. Add the .patt file to your website. It really doesn’t matter where as long as it’s accessible to the application, I usually put mine in my assets folder using a structure like /img/patterns/my-marker.patt.

Step 4. Add the marker to your AR.js element. Using the a-frame method, this is very simple. All you need to do is add an a-marker element with a type prop of ‘pattern’, and the relative path to your pattern file as the ‘url’ prop.

Using this method we will also need to include an a-entity camera so that the virtual camera is included in the 3D environment being rendered.

Code screenshot of adding in a custom marker to an AR.js application

Step 5. Finally, add in the 3D model you would like to display. To complete this, we need to add in a model that’ll be shown when this marker is discovered. Thankfully, a-frame includes a bunch of primitive geometries that we can easily drop-in using some simple element names.

  • <a-box></a-box>
  • <a-box></a-box>
  • <a-cylinder></a-cylinder>
  • <a-plane></a-plane>

Each of these have a position prop that can be adjusted to allow you to move it around the 3D space relative to the marker position. This way your objects don’t need to sit directly on the marker but can float above it, or off to the side. For this example, I’m going to add in a red sphere that floats just slightly above the marker.

Adding in a 3D model to an AR.js application

Boom 💥

Replace the previous boilerplate with the new custom pattern code, and show your downloaded marker image to the camera. You should see a red sphere floating just above the marker icon!

A screenshot showing an example of a simple AR.js application

This might seem pretty simple, but when you consider that we did this in just a dozen lines of HTML the power and possibility of using AR.js really shines through.

 

More advanced stuff

Update from Sep 16: There's a follow-up post with some more advanced tips and tricks for your AR.js applications. Check it out here!

There will be a second article for some more advanced AR.js tips and tricks. Add event listeners to your sites that fire when markers are discovered or lost, adjust the thickness of a marker border, importing images as materials, using custom 3D models, and more!