10 tips to enhance your AR.js app.

If you have tried AR.js but your app’s performances are not satisfying, it’s time to try these tips before give up.

Nicolò Carpignoli
Chialab Open Source
5 min readMay 11, 2019


This is part of a series of articles about AR.js. The following is the list of the articles written so far:

For the latest news about AR.js and Web AR, you can follow me!

AR.js markers over my laptop.

AR.js is getting more popular. As April 2019, AR.js repository has 13k stars and a growing community. If you are reading this, either you’re digging on AR.js stuff or you have given up because of his complexity.

AR.js is basically easy, but when it comes to add interaction and more advanced features to your app, it can become difficult to dig into the source code and find how things work. Also, I have seen a lot of developers give up because of performances and jerkiness of 3D content.

Sometimes, a lot of these problems can be avoided very easily. I will not repeat myself with advices I already wrote in other articles, but instead I want to offer ten straightforward ways to enhance AR.js performances. Some point will come with an explanation where needed. If you, for some reason, are not satisfied about your AR.js app, take a look at this list and see if you have already taken care of everything.

Disclaimer: I have tried personally every point of this list, and found most of all by myself. For points 2 to 5 I have to thank hoktok who first posted these hints on an AR.js issue on Github.

1. Use rotationally asymmetrical markers

First of all, jerkiness of 3D content is usually determined only by one factor: the capability of camera to recognize the marker. In fact, 3D models are ‘shaking’ if camera is not able to steadily recognize the marker. This can be avoided using rotationally asymmetrical markers.

I want to make it simple: markers are better not to be similar if looked from different angles. This feature can be more easily obtained with custom marker patterns, because barcode patterns are not fully customizable.

In order to create custom markers, you can use the online pattern marker generator. If you create a marker starting from an image that contains a simple, rotationally asymmetrical shape, the result will be far more stable in terms of 3D model jerkiness.

An example of rotationally asymmetrical marker.

2. From portrait to landscape and back

It seems that AR.js has not been optimized for portrait mode, unlike plain a-frame scenes. Sometimes switching from landscape to portrait mode makes the user unable to switch back to landscape. I personally have not found big problems with portrait mode, but I can confirm the performances issues on switching between the two modes.

3. Sync scale

When scaling models and a-frame entities (a-entity), in order to reduce 3D shaking effect, always scale in sync every axis (e.g. 2X scaling? From x=2, y=3, z=5 scale every axis 2X, so: x=4, y=6, z=10).

4. Marker size

Marker size is a common problem. I often receive messages asking me how to enhance marker recognization, what is the best marker size, the minimum marker size, and so on.

At the moment, there is no way to enhance marker recognization system. You can only find a trade-off between your case and marker real size.

As an empiric rule, marker has to be recognizable by human eye, without error, looking through the camera. Below 40–50 cm of distance from the marker, you can use a 3 cm² marker size. Above that distance, you have to make the marker bigger otherwise the camera will not recognize it.

Keep also in mind that using similar markers for different purposes from a great distance can make the camera confuse them.

5. Print the marker

Before blaming AR.js and his marker recognization system, first try to print the marker. Using markers directly from screen makes the recognization difficult because of brightness and other displays related aspects.

6. Light border around the marker

I already covered the importance of the color contrast between the black border of the marker and the surrounding area. Either if you are placing your marker on a table or you are displaying it on a screen (if so, see point 5!) be aware of the contrast between the colors.

To give you an empiric rule, your ‘light’ area sorrounding the marker should always be half the marker border width, at least.

A marker with the minimum light area width permitted.

7. Marker events

One of the last, great features added to AR.js 1.6.2 is the possibility to handle events triggered when a marker is found or lost. This enables a lot of applications also in conjuction with handling click events. See this merged Pull Request to know more about the API.

8. Chrome on iOS: we have a problem

On iOS, Chrome has a great, big issue from some time: it is not possible to receive the camera permission prompt, so the camera cannot be used. This means that, until Google get this bug fixed, we have no possibility to run any AR.js app on Chrome on iOS. As for now, Safari is your way to go.

9. Change camera resolution

If you think AR.js default camera resolution is too low for you, there is a way to change that. In fact, default parameters are 640x480px (see https://github.com/jeromeetienne/AR.js/blob/master/three.js/src/threex/threex-artoolkitsource.js).

If you want to set new values, change them on arjs attribute of the a-scene element. For example, for a FullHD camera, use this values:

<a-scene embedded arjs=’sourceType: webcam; sourceWidth:1280; sourceHeight:960; displayWidth: 1280; displayHeight: 960;’>

10. Get in touch with the community

Not everybody knows the best ways to get in touch with the AR.js community; based on your needs, these are your options:

10+1. Ask me!

I’m passionate about AR.js and I have been digging on it from more than a year. Also, I’m currently the main maintainer of the project. Feel free to ask me for quick help, a consultancy or a project.

You can also find me on Twitter @ https://twitter.com/nicolocarp.

See you next time. Have fun with AR.js!