Creating augmented reality experiences on the web is much easier than you think. In less than 15 lines of HTML, you can use 2D objects as triggers for AR content. In this tutorial, led by the talented Anne Goodfriend, she’ll give you an in-depth introduction into HTML, AR JavaScript, and A-Frame. You’ll then be able to take these tools and use your phone to create your own AR experience, without installing any applications. Don’t worry — familiarity with HTML is not necessary, but your laptop, smartphone and curiosity definitely are.
Images: Yotam Kellner
Anne Goodfriend is a designer, technologist and educator that has been honing in on her calculated yet playful approach to the creative design process for over a decade. She’s worked on everything from app development to augmented reality and wearable technology, continually trying to perfect ideal user experiences. An ITP alum, Anne is passionate about sharing her skills in code, craft and engineering with others. She currently teaches robotics as a Lead Educator at the NYC FIRST STEM Center at Cornell Tech.
Zoe Bachman is an artist and educator and a curriculum product manager at Codecademy who finds new ways to make learning code more accessible and engaging based on her experience as a creative technologist. She’s constantly interested in the use of technology to promote alternative narratives and form unique identities through photography, video and animation. A recent ITP graduate, Zoe is passionately working to change the tech landscape through creative interventions and education initiatives.
This tutorial is part of Wix Playground Presents, a curated collection of online workshops, talks and portfolio reviews, by creatives for creatives. This collaboration is supported by ITP graduates Regina Sofia Cantu de Alba and Michelle Hesse.
Images: Yotam Kellner
Let’s Begin:
As part of this tutorial, we will be using the Glitch website. However, you’re also able to do this tutorial on your own computer, using a text editor such as VSCode and running a server on your terminal. We like Glitch because it’s easy to create templates and it takes care of the image and file hosting.
Like much emerging technology, what we are about to show you in this demo is likely to change fast. Make sure to read the documentation before starting a project to ensure that everything is up-to-date.
Step 1: Getting Set Up
Images: Yotam Kellner
Clone the aframe-ar-wixplayground Glitch repository by clicking on the Remix to Edit button. You do not need to have a Glitch account or be signed in when you do so. However, if you wish to save your work, you’ll need to sign in or create a new account. The template comes directly from the creators of AR.js.
Step 2: Read the Code
You should now have your own copy of the aframe-ar-wixplayground Glitch repository, with a new auto-generated name in the upper left hand corner (in this tutorial, it’s named miniature-cookies-citrus). You can change this name to whatever you’d like.
Let’s take a look at the basic setup:
Folders and Files
On the left-hand side, you’ll see a file navigation system. Currently, it includes:
assets - where we’ll host any 3D objects (.ob)j or media files (like mp3)
.env
README.md
index.html - where we’ll be writing our code
script.js
style.css
For this tutorial, we’ll be using only the assets folder and index.html. If you are familiar with CSS and JS, you may also edit those files while creating your AR piece, but we won’t be covering those topics here.
Assets folder
The assets folder is where we’ll be uploading content like 3D models. It operates like a CDN by hosting our content on a server and giving us a URL to retrieve it. That means that when we want to access our content, rather than using a file pattern as the source, we’ll be using the auto-generated URL. More on this in the working with 3D models section.
index.html file
The index.html file is where we’ll be writing our code (like we said, it’s an AR with HTML tutorial!). HTML is a markup language that allows us to add content to web pages and is often referred to as the skeleton of the web page. It’s ok if you’re not familiar with HTML - we’re going to walk through each line of code below.
<script>
Let’s dive into the index.html file. At the top, we can see two <script> tags.
The first script we include is the A-Frame webVR library. The second one is the AR.js library, which is built on top of A-Frame. We need to include both of these libraries to use elements beyond traditional HTML tags, such as cameras and primitive 3D shapes.
<body>
After the script tags, we have our <body> tag. For a website, the content that we see on a webpage is always within the <body> tag. Same goes for what we’re building - we will put everything that makes up our AR.js experience inside of this body tag.
Always make sure you are writing your code inside of the <body> tag
<scene>
Inside of the body tag is where stuff starts to get interesting.
First up we have the <a-scene> element. This tag comes from A-Frame and is used to define the scene that we’re creating, or in other words, what the user will see. We define it as an AR application instead of a VR application by including the attribute embedded arjs. Like with the <body> tag, we want to make sure that everything we’re using in our scene is included within the <a-scene> tag.
Always make sure you are adding AR elements inside of the <a-scene> tag
<marker>
The first thing inside of the <a-scene> element is the <a-marker> tag.
This tag is where we define what kind of AR marker we will be using. An AR marker is what the program uses to situate our AR experience. Once the camera on your device sees the marker, the AR experience will start.
In the template, we’ve gone with the hiro preset. We set the type of preset marker that we want to use with the attribute present=”hiro”. Here’s what the marker looks like:
Another marker preset is the kanji marker:
You can change the Hiro marker to Kanji by changing the value of the preset attribute: <a-marker preset="kanji"></a-marker>. You’re also able to create custom markers. We’ll discuss that more in the custom markers section.
In this tutorial, any of the content that you want to display in the scene must be within the <marker> tags.
Always make sure you are adding content inside of the <a-marker> tag
Camera
Lastly, let’s talk about how to add a camera.
The <a-entity> tag is a general tag in A-Frame that we can use to add things to a scene. In this case, we’re passing it to the camera attribute, so it becomes a camera.
Note: you can use the <a-camera> tag instead of this one if you’re only using one marker in your scene,but if you’re interested in doing a project with multiple markers, you’ll want to stick with the <a-entity> tag.
There you have it! Now you can understand every line of code in the template. In the next section, we’ll go over how to add content to your scene and how to test the app as you develop it.
Step 3: Adding Content
Let's get to the fun stuff — adding things to our scene! In this section we’ll discuss how to add:
A-Frame primitive shapes
Text
3D Models (.obj and .glTF 2.0)
We’ll also go over how you can see what you’re building as you develop it, so you can tweak your experience as you go.
A-Frame Primitive Shapes
A-Frame has several primitive shapes built in, like <a-box> and <a-sphere>. In this tutorial, we’re going to show you how to display a box and how to change how it looks by using different attributes like position, height, and color.
Add a Box
To add a box to our scene, we’ll write in the <a-box> tag between our <a-marker> opening and closing tags.
Test the AR App
Let’s take a second to make sure our box has now been added to the scene. To see your work in progress, make sure you have a copy of the Hiro marker printed out or viewable on a device, like a phone. Click the show button and click In a New Window:
This action will open up a new tab in your browser. Your browser will likely ask if it can use your camera, so click allow (otherwise, this won’t work!).
Hold up the printed Hiro marker, or your phone, and voila! You should see a simple white box.
Modify the Box
Now that we know our app works, we can start to modify it. Let’s change how the box looks by using different attributes, such as position, height, and color. To see more attributes, check out the documentation.
With the next few lines of code, we’re going to:
Raise the box above the marker
Turn the box into a rectangle
Make the box red
It should look like this at the end:
Position
The position attribute is how we define the placement of a primitive shape in virtual space. We give it three values, corresponding to its X, Y and Z coordinates.
Notice how we’ve adjusted the Y value, and when we look at our box it is now floating slightly above the marker, rather than sitting right on top of it.
Height
The height attribute is one of several attributes that we can use to define the size of a primitive shape. This attribute is particularly helpful if you’re working with imported 3D models, since they have a tendency to be quite large and need to be shrunk in order to be used in AR.
Color
The color attribute attribute sounds exactly like what it is — it allows us to define the color of a primitive shape using a recognized color value, like a hexadecimal value or certain color names. We recommend using an online color picker to find the value for a color you’re interested in using.
Text
In addition to shapes, we’re also able to add text to our scenes by using the <a-text> primitive element. <a-text> has a value attribute, and whatever you set it as equal to is what you want the text to be.
Just like with primitive shapes, you can modify a text primitive using the various attributes we discussed above, like position, height, and color. In this example, I changed the color to green.
Note: If you still have your box in the scene, it might be covering up the text. Make sure to remove or comment out the line with the box before adding text.
3D Models (.obj and .glTF)
What’s probably of interest to most folks is adding 3D models to a scene. This could be a model that you’ve created or one that you’ve found online. For this tutorial, we’ll use this corgi model from Google.
OBJ
OBJ models are very common, but a somewhat older file format for 3D models. In A-Frame, you can work with OBJs using the <a-obj-model> primitive. They also have additional documentation on working with OBJs available.
To start, download the obj version of the corgi model. It should download as a zip file to your computer. Rand rename it to something shorter, like corgi_obj. Unzip the folder, and you’ll see two files: materials.mtl and model.obj.
Head back to Glitch, and click on the assets folder and click on the Upload and Asset button:
Next, upload the two files in the folder, one at a time.
Your assets folder should now contain three items: scene.gltf (generated when we run <a-scene>, and the materials.mtl and model.obj files.
After the uploads have finished, navigate back to the index.html file and add the following line of code between the <marker> tags:
So far, we’ve created an <a-obj-model> element with a src and a mtl attributes. The value of those attributes are two URLs that link to where the files that make up the OBJ model are stored, one for the .obj file and the other for the .mtl file. To get those URLs, we need to go back to the assets folder, click on each file, and grab the CDN url. It should look something like this:
Throw these links into the placeholders that say URL and refresh your app to see your model!
If you want to change anything about the placement and size, use the position and height/width attributes.
glTF 2.0 Models
The recommended file type to use is glTF 2.0. There are two kinds of glTF - make sure to use glTF 2.0, as this is the file type supported by A-Frame. In A-Frame, you can work with glTFs using the <a-gltf-model> primitive. They also have additional documentation on working with glTFs.
Like we did with the OBJ files, download the updated glTF version of the corgi model. It should also download as a zip file to your computer. Rand rename it to something shorter, like corgi_gltf. Unzip the folder, and you’ll see two files: model.bin and model.gltf.
Like we did before, upload the glTF files to the assets folder. Grab the generated CDN link for the model.gltf file and add it to the src attribute, removing the URL placeholder:
Note: Most models have multiple file formats and some file formats work better than others. If you find a 3D model that you like, make sure to try both an OBJ, a glTF 1.0, and a glTF 2.0 to find the one that works for you. Similarly, try the primitive tags, but if they don’t work, try the <a-entity model name> tags. As a last resort, try changing the size —- sometimes models are REALLY big and we can’t see them in our view. I usually change the height to .01. If all else fails, try another model!
Step 5: Viewing Your Piece
So far you’ve been able to add content such as primitive shapes, text, and 3D models to your AR application. Up until now, we’ve been viewing our AR app in a web browser. In this next section, we’ll show you how to view your app on your phone so you can easily demonstrate your new awesome AR project to other folks!
As you may have already figured out, each Glitch Repository has its own URL. For example, the code we’ve been looking at so far is hosted at https://miniature-cookie-citrus.glitch.me/.
To see the AR app on your phone, type this URL into your phone’s browser (make sure to type everything, including the https://). If you are on a Mac and have an iPhone, you can airdrop the URL from Safari on computer to Safari on your phone.
Next, point your phone at your printed out marker (or, find a marker on your computer) and voila! You should be seeing your AR experience.
Congratulations! You’ve built a custom AR experience in the browser, using HTML with AR.js and A-Frame. We can’t wait to see what you’ll do next!
BONUS! Working with Custom Markers
If you’re not interested in working with the Hiro or Kanji markers, you can create your own markers. Jerome Etienne, the creator of AR.js has made a custom marker generator website. You can upload images to this website and it will create a marker for you that you can download and then print out. Follow this medium article if you want to learn more.
BONUS! Animation
One of the more fun things you can do is animate your content. A-Frame has an animation component that lets us animate and tween values (have values in between two values). glTF 2.0 models support animations too. To enable animations read the documentation provided by Don McCurdy on Github.
Images: Yotam Kellner
