@@ -17,307 +17,36 @@ Logo by [Simon Poulter](https://twitter.com/viralinfo)
...
@@ -17,307 +17,36 @@ Logo by [Simon Poulter](https://twitter.com/viralinfo)
AR.js is a lightweight library for Augmented Reality on the Web, coming with features like Marker based and Location based AR.
AR.js is a lightweight library for Augmented Reality on the Web, coming with features like Marker based and Location based AR.
Welcome to the official repository!
# ⚠️ This project repository has been moved to a Github organization account ⚠️
This project has been created by [@jeromeetienne](https://github.com/jeromeetienne) and it is now maintained by [@nicolocarpignoli](https://github.com/nicolocarpignoli).
## You can find the maintened version of AR.js at [this link](https://github.com/AR-js-org/AR.js).
🚀For frequent updates on AR.js you can follow [@nicolocarp](https://twitter.com/nicolocarp) and Watch this repo!
The old repository (the one you are now) will be left up, so all links and CDNs will continue to be available, but this version **will not be updated anymore**.
**Key points**:
Please, open issues and Pull Requests on the new repository. Thank you.
-**Very Fast** : it runs efficiently even on phones - [60 fps on my 2 year-old phone](https://twitter.com/jerome_etienne/status/831333879810236421)!
## Why move AR.js
-**Web-based** : It is a pure web solution, so no installation required. Full javascript based on three.js + jsartoolkit5
-**Open Source** : It is completely open source and free of charge!
-**Standards** : It works on any phone with [webgl](http://caniuse.com/#feat=webgl) and [webrtc](http://caniuse.com/#feat=stream)
# AR.js v2.0.0 is out!🌍
AR.js was among those great projects, that you can find on Github, with great technologies, often disruptive ones, that eventually are left alone by their authors.
AR.js v2.0.0 introduces, for the first time, another type of Augmented Reality: **Location Based**.
We tried to carry on the author's terrific work by maintaining this project, handling new versions, issues, pull requests, the community itself. We continued promoting this project through blogs, Medium articles, socials. And we released new features, like the Location Based AR that was not initially present on AR.js.
AR.js can now be used with its default Marker Based feature, with Location Based or both combined.
Now, that we are also ready to ship a new feature, Image Tracking, we feel ready to start a new path, and so we have created a new repository that is not owned by individuals, but by one organization.
See the project that has been integrated into AR.js: [GeoAR.js](https://github.com/nicolocarpignoli/GeoAR.js).
Anyone can be added to it, and more people will manage it, in order to make the project more collaborative and avoid single-point-of-failures, when someone wants/has to exit the project.
You can find additional details below.
We feel this is a new chapter for this project, to not let it die alone. We feel the current Web Augmented Reality market really needed something like AR.js, but owned by no-one apart from the community itself. A technology free and Open Source, created by users for the users.
# Try it on Mobile
We'd like to thank all contributors and passionate people who help us in this journey.
It works on all platforms. Android, IOS and window phone. It runs on **any browser with WebGL and WebRTC** (for iOS, you need to update to iOS11),
See you on new [AR.js org](https://github.com/AR-js-org).
To try it on your phone, it is only 2 easy steps, check it out!
*Nicolò Carpignoli*
1. Open this [hiro marker image](https://jeromeetienne.github.io/AR.js/data/images/HIRO.jpg) in your desktop browser.
_____
1. Open this [augmented reality webapps](https://codepen.io/nicolocarpignoli/full/vMBgob) in your phone browser, and point it at your screen.
**You are done!** It will open a webpage which read the phone webcam, localize a hiro marker and add a 3D model on top of it!
AR.js is a free and Open Source software, created by [@jeromeetienne](https://github.com/jeromeetienne) and maintained by [@nicolocarpignoli](https://github.com/nicolocarpignoli). Check the LICENSE.txt to learn more.
# What "Marker Based" means
AR.js uses `artoolkit`, and so it is marker based.
`artoolkit` is a software with years of experience doing augmented reality. It is able to do a lot!
It supports a wide range of markers: multiple types of markers [pattern](https://github.com/artoolkit/artoolkit5/tree/master/doc/patterns)/[barcode](https://github.com/artoolkit/artoolkit-docs/blob/master/3_Marker_Training/marker_barcode.md)
multiple independent markers at the same time, or [multiple markers acting as a single marker](https://github.com/artoolkit/artoolkit-docs/blob/master/3_Marker_Training/marker_multi.md) up to you to choose.
More details about markers:
*[Artoolkit Open Doc](https://github.com/artoolkit/artoolkit-docs/tree/master/3_Marker_Training)
*[Detailed Article about markers](https://medium.com/@nicolcarpignoli/ar-js-the-simplest-way-to-get-cross-browser-augmented-reality-on-the-web-10cbc721debc) by [@nicolocarpignoli](https://twitter.com/nicolocarp)
# What "Location Based" means
### Check out the Location Based documentation: [here](https://github.com/jeromeetienne/AR.js/blob/master/aframe/README.md#location-based).
AR.js, on its `aframe` implementation, comes with few custom components that make possible to integrate data from GPS sensors.
Basically, you can add `gps-entity-place` - custom `aframe` entities that have a specific longitude/latitude values.
You can add them with a script, loading them from APIs (Foursquare, Google Maps, and so on) or just add them statically on your HTML.
Once you have added one or more gps-entities, and added the `gps-camera` on the `camera` entity, the system calculates, at every frame, your position and the distance of places from you.
Using your phone sensors for orientation/position, AR.js is able to show on your camera a content for each place on its 'physical' place (so if you point the camera towards the place in real life, you will see the content near it).
If you move the camera, it calculates again orientation and position. If places are far, it shows smaller content. If places are near you, it shows it bigger.
Learn more with [this article](https://medium.com/@nicolcarpignoli/location-based-gps-augmented-reality-on-the-web-7a540c515b3c).
Every example uses the `places.js` script to load places. You set your places using static data, with specific coordinates, adding these info in the first lines of code (there are comments to explain it better).
Otherwise, as default, the script searches for places of interest near the user using Foursquare APIs. Please retrieve valid API credentials [here](https://developer.foursquare.com/) in order to use it. Place credentials (replace both Client Secret and Client Id) on `places.js`.
You can also use GeoAR.js **without** the script, adding `gps-entity-place` entities directly on the `index.html` file.as documentated [here](https://github.com/jeromeetienne/AR.js/blob/master/aframe/README.md).
# Index
*[Get Started](#Get-Started)
*[Guides for Beginners](#Guides-for-beginners)
*[Advanced Guides](#Advanced-Guides)
*[Examples](#Examples)
*[Augmented Website](#Augmented-Website)
*[Tools](#Tools)
*[Performance](#Performance)
*[Status](#Status)
*[Folders](#Folders)
*[Browser Support](#Browser-Support)
*[Licenses](#Licenses)
⚠️ *Please always give a look for new undocumented features on the [Changelog](https://github.com/jeromeetienne/AR.js/blob/master/CHANGELOG.md) until the documentation has been updated.*
# Get Started
## Augmented Reality for the Web in less than 10 lines of HTML
-[AR.js introduction and insight on markers](https://medium.com/@nicolcarpignoli/ar-js-the-simplest-way-to-get-cross-browser-augmented-reality-on-the-web-10cbc721debc)
-[Details about 3D models that can be used with AR.js](https://medium.com/@akashkuttappa/using-3d-models-with-ar-js-and-a-frame-84d462efe498)
-["WebVR for Augmented Reality - Using WebVR to write cross-platform AR applications"](https://medium.com/arjs/webvr-for-augmented-reality-f1e69a505902)
by [@jerome_etienne](https://twitter.com/jerome_etienne)
-["AR-Code:a Fast Path to Augmented Reality - From QR Code to AR.js content"](https://medium.com/arjs/ar-code-a-fast-path-to-augmented-reality-60e51be3cbdf)
by [@jerome_etienne](https://twitter.com/jerome_etienne)
### Location Based
-[Location Based (GPS) Augmented Reality on the Web](https://medium.com/@nicolcarpignoli/location-based-gps-augmented-reality-on-the-web-7a540c515b3c)
-[Tutorial for Location Based Augmented Reality on the Web](https://medium.com/chialab-open-source/build-your-location-based-augmented-reality-web-app-c2442e716564)
## Advanced guides
### Marker Based
-[How to deliver AR.js only with a QR Code](https://medium.com/@nicolcarpignoli/how-to-deliver-ar-on-the-web-only-with-a-qr-code-139bb90e82f1)
-[How to handle click with AR.js](https://medium.com/@nicolcarpignoli/how-to-handle-click-events-on-ar-js-f397ea5994d)
-[10 tips to enhance your AR.js app performances](https://medium.com/@nicolcarpignoli/10-tips-to-enhance-your-ar-js-app-8b44c6faffca)
-["Area Learning with Multi-Markers in AR.js - For a Larger & More Stable Augmented Reality"](https://medium.com/arjs/area-learning-with-multi-markers-in-ar-js-1ff03a2f9fbe)
by [@AndraConnect](https://twitter.com/AndraConnect)
- Great post about [WebAR for designer](http://www.nexusinteractivearts.com/webar/)
by [nexus interactive arts](http://www.nexusinteractivearts.com/)
# Examples
Try to get inspired by this great works:
### Marker Based
-[Examples from official AR.js doc](https://jeromeetienne.github.io/AR.js-docs/misc/EXAMPLES.html)
### Location Based
-[Click Places](./aframe/examples/click-places) - set up remote credentials to fetch remote places (`places.js` file)
-[Places Name](./aframe/examples/places-name) - add new places statically on javascript (`places.js` file)
-[Only HTML](./aframe/examples/only-html) - add new places statically on html (`index.html` file)
-[Only HTML](./aframe/examples/always-face-user) - like only-html but here content always face the user (`index.html` file)
# Related Projects
-[Examples inspired from AR.js - not AR.js based](https://github.com/stemkoski/AR-Examples) from [@stemkoski](https://github.com/stemkoski)
-[AR-gif](https://github.com/rodrigocam/ar-gif):
Easy to use web components to do web augmented reality. Currently supporting gifs, but open for contributions to
add 3d objects, videos and so on.
## Augmented Website
[Seminal post](https://medium.com/arjs/augmenting-the-web-page-e893f2d199b8) explaining the concept.
The service is available [webxr.io/augmented-website](https://webxr.io/augmented-website/)
# Community
- AR.js on gitter: https://gitter.im/AR-js/Lobby
- Trello board for ongoing work: https://trello.com/b/63F7JlvD/arjs
We are still early in the project but here are some initial numbers to give you an idea.
- I got 60fps stable on nexus6p
- Some reports [Sony Xperia Z2 (2.5 years old) runs around 50fps](https://twitter.com/leinadkalpot/status/834121238087925763) - this is a 170euro phone
- Some reports [~50fps on a old nexus5, and ~60fps on nexus 9](https://twitter.com/Ellyll/status/834312442926751744) - nexus5 is 3.5 years old!
- Some reports it working on windows phone edge!! [13fps on Lumia 950](https://twitter.com/leinadkalpot/status/834299384510763012) for some.
[40-45fps on lumia 930](https://twitter.com/fastclemmy/status/834817155665391616) for others.
Obviously you mileage may vary. The performance you get will depend on 3 things: How heavy your 3D is, How you tune your parameters
and the hardware that you are using.
# Standing on the Shoulders of Giants
So we shown it is now possible to do 60fps web-based augmented reality on a phone.
This is great for sure but how did we get here ? **By standing on the shoulders of giants!**
It is thanks to the hard work from others, that we can today reach this mythic 60fps AR.
So I would like to thanks :
-**three.js** for being a great library to do 3d on the web.
-**artoolkit**! years of development and experiences on doing augmented reality
-**emscripten and asm.js**! thus we could compile artoolkit c into javascript
-**chromium**! thanks for being so fast!
Only thanks to all of them, I could do my part : Optimizing performance from 5fps on high-end
phone, to 60fps on 2years old phone.
After all this work done by a lot of people, we have a *web-based augmented reality solution fast enough for mobile*!
Now, many people got a phone powerful enough to do web AR in their pocket.
I think this performance improvement makes web AR a reality.
i am all exited by what people are gonna with it :)
Recently, we’ve been getting creative and working on developing new things with AR.js. One of them is playing around with [shadows](https://twitter.com/jerome_etienne/status/837240034847764480), syncing the position of virtual lights with reality for a more life-like finish:
We’ve been collaborating very closely with [Fredrick Blomqvist](https://twitter.com/snigelpaogat). His input has had a great impact on AR.js innovation and we want to thank him. Together, we’ve been implementing [refraction](https://twitter.com/jerome_etienne/status/838749280999518208), giving the 3d a transparent/glassy effect. It ended up having a nice polished look. What do you guys think?
Other crazy ideas we’ve been working on include a [hole in the wall](https://twitter.com/jerome_etienne/status/836754117964017664) and a [portal into another world](https://twitter.com/jerome_etienne/status/838404908235776000). We want to take AR.js to new dimensions.
# Status
- At the three.js level is the main one. It is working well and efficiently
- a-frame component - it export ```<a-marker>``` tag. It becomes real easy to use.
It allows the things three.js extension does. Here are some slides
