Deployed 603352d with MkDocs version: 1.1.2

index.html

@@ -206,15 +206,15 @@ <h2 id="import-the-library">Import the library</h2>
 <pre><code class="language-html">  &lt;script src=&quot;https://raw.githack.com/AR-js-org/AR.js/3.0.0/aframe/build/aframe-ar-nft.js&quot;&gt;
 </code></pre>
 <p><strong>Location-based AR.js</strong></p>
-<p>For the <em>A-Frame</em> version:</p>
+<p>For the <em>A-Frame</em> version, it's recommended to use version 3.4.5, rather than master:</p>
 <pre><code class="language-html">&lt;!-- A-Frame itself --&gt;
 &lt;script src=&quot;https://aframe.io/releases/1.3.0/aframe.min.js&quot;&gt;&lt;/script&gt;
 
 &lt;!-- Pure three.js code that the A-Frame components use for location-based AR --&gt;
-&lt;script type='text/javascript' src='https://raw.githack.com/AR-js-org/AR.js/master/three.js/build/ar-threex-location-only.js'&gt;&lt;/script&gt;
+&lt;script type='text/javascript' src='https://raw.githack.com/AR-js-org/AR.js/3.4.5/three.js/build/ar-threex-location-only.js'&gt;&lt;/script&gt;
 
 &lt;!-- AR.js A-Frame components --&gt;
-&lt;script type='text/javascript' src='https://raw.githack.com/AR-js-org/AR.js/master/aframe/build/aframe-ar.js'&gt;&lt;/script&gt;
+&lt;script type='text/javascript' src='https://raw.githack.com/AR-js-org/AR.js/3.4.5/aframe/build/aframe-ar.js'&gt;&lt;/script&gt;
 </code></pre>
 <p>For the <em>three.js</em> version, it's recommended to import AR.js as a module and build with a bundler such as Webpack. There is an example given in the location-based section.</p>
 <h2 id="requirements-and-known-issues">Requirements and Known Issues</h2>
@@ -225,6 +225,7 @@ <h2 id="requirements-and-known-issues">Requirements and Known Issues</h2>
 <li>You must ensure that you have matching versions of AR.js and A-Frame. AR.js 3.4.5 (the latest version) requires A-Frame 1.3.0 while AR.js 3.4.4 and below requires 1.0.4.</li>
 <li>Location-based AR will not work correctly on Firefox, due to the inability to obtain absolute device orientation (compass bearing)</li>
 <li>On Android/Chrome, you may <strong>encounter issues with location-based AR due to inaccuracies in compass calibration</strong> (incorrect north). This is likely to be a hardware limitation of the device.</li>
+<li>On some phones you may encounter problems with locating North due to inherent miscalibrations of the device sensors. This is a known problem recognised by the three.js developers: see <a href="https://github.com/mrdoob/three.js/issues/22654">here</a></li>
 <li>Please ensure you <strong>enable high accuracy</strong> location for your selected browser on Android. Sometimes high accuracy location is turned off by default, and this will lead to an inaccurate GPS location.</li>
 <li>There is currently a bug in location-based AR where the camera feed is stretched away from the centre of the screen, meaning that there is reduced accuracy in placement of objects further away from the centre. Work is ongoing to investigate this.</li>
 <li>On device with multi-cameras, Chrome may have problems on detecting the right one. Please use Firefox if you find that AR.js opens on the wrong camera. There is an open issue for this.</li>
@@ -328,8 +329,8 @@ <h3 id="location-based-example">Location Based Example</h3>
 &lt;head&gt;
 &lt;title&gt;AR.js A-Frame Location-based&lt;/title&gt;
 &lt;script src=&quot;https://aframe.io/releases/1.3.0/aframe.min.js&quot;&gt;&lt;/script&gt;
-&lt;script type='text/javascript' src='https://raw.githack.com/AR-js-org/AR.js/master/three.js/build/ar-threex-location-only.js'&gt;&lt;/script&gt;
-&lt;script type='text/javascript' src='https://raw.githack.com/AR-js-org/AR.js/master/aframe/build/aframe-ar.js'&gt;&lt;/script&gt;
+&lt;script type='text/javascript' src='https://raw.githack.com/AR-js-org/AR.js/3.4.5/three.js/build/ar-threex-location-only.js'&gt;&lt;/script&gt;
+&lt;script type='text/javascript' src='https://raw.githack.com/AR-js-org/AR.js/3.4.5/aframe/build/aframe-ar.js'&gt;&lt;/script&gt;
 &lt;/head&gt;
 &lt;body&gt;
 &lt;a-scene vr-mode-ui='enabled: false' arjs='sourceType: webcam; videoTexture: true; debugUIEnabled: false' renderer='antialias: true; alpha: true'&gt;
@@ -510,5 +511,5 @@ <h4 class="modal-title" id="keyboardModalLabel">Keyboard Shortcuts</h4>
 
 <!--
 MkDocs version : 1.1.2
-Build Date UTC : 2024-10-25 11:27:00.687174+00:00
+Build Date UTC : 2024-10-26 11:28:56.100280+00:00
 -->

location-based-aframe/index.html

@@ -126,7 +126,7 @@ <h2 id="basic-example">Basic example</h2>
 &lt;body&gt;
 &lt;a-scene vr-mode-ui='enabled: false' arjs='sourceType: webcam; videoTexture: true; debugUIEnabled: false' renderer='antialias: true; alpha: true'&gt;
     &lt;a-camera gps-new-camera='gpsMinDistance: 5'&gt;&lt;/a-camera&gt;
-    &lt;a-entity material='color: red' geometry='primitive: box' gps-new-entity-place=&quot;latitude: &lt;your-lat&gt;; longitude: &lt;your-loon&gt;&quot; scale=&quot;10 10 10&quot;&gt;&lt;/a-entity&gt;
+    &lt;a-box color=&quot;red&quot; gps-new-entity-place=&quot;latitude: &lt;your-lat&gt;; longitude: &lt;your-loon&gt;&quot; depth=&quot;10&quot; height=&quot;10&quot; width=&quot;10&quot;&gt;&lt;/a-box&gt;
 &lt;/a-scene&gt;
 &lt;/body&gt;
 &lt;/html&gt;

location-based/index.html

@@ -89,6 +89,14 @@
 
             <li class="nav-item" data-level="1"><a href="#location-based" class="nav-link">Location Based</a>
               <ul class="nav flex-column">
+            <li class="nav-item" data-level="2"><a href="#intro-to-location-based" class="nav-link">Intro to location-based</a>
+              <ul class="nav flex-column">
+              </ul>
+            </li>
+            <li class="nav-item" data-level="2"><a href="#limitations" class="nav-link">Limitations</a>
+              <ul class="nav flex-column">
+              </ul>
+            </li>
             <li class="nav-item" data-level="2"><a href="#a-frame" class="nav-link">A-Frame</a>
               <ul class="nav flex-column">
               </ul>
@@ -117,6 +125,9 @@
                     <div class="col-md-9" role="main">
 
 <h1 id="location-based">Location Based</h1>
+<p><strong>Important!</strong> You might want to check out the new AR.js <a href="https://github.com/AR-js-org/locar.js">LocAR</a> project if you are interested in location-based AR. This aims to provide a cleaner API, with just a single version, and more frequent updates. </p>
+<p>In the future, updates on the location-based side will be focused on LocAR.</p>
+<h2 id="intro-to-location-based">Intro to location-based</h2>
 <p><a href="https://medium.com/chialab-open-source/build-your-location-based-augmented-reality-web-app-c2442e716564">This article</a> gives you a first glance to Location Based on AR.js.</p>
 <p>It can be used for indoor (but with low precision) and outdoor geopositioning of AR content.</p>
 <p>You can load places statically, from HTML or from Javascript, or you can load your data from local/remote json, or even through API calls. Choice is yours. On the article above there are all the options explained, as tutorials.</p>
@@ -126,17 +137,24 @@ <h1 id="location-based">Location Based</h1>
 <li><a href="../location-based-aframe/">A-Frame location based</a></li>
 <li><a href="../location-based-three/">three.js location based</a></li>
 </ul>
+<h2 id="limitations">Limitations</h2>
+<p>Location-based AR with AR.js is subject to certain limitations.</p>
+<ul>
+<li>Your device must have a GPS chip, accelerometer and magnetometer.</li>
+<li>On some devices, the sensors may be miscalibrated, resulting in an incorrect North. See, for example, <a href="https://github.com/mrdoob/three.js/pull/22654">this three.js issue</a>. This is unfortunately a limitation of the device. This will be investigated further in <a href="https://github.com/AR-js-org/locar.js">LocAR</a>, for example, as to whether certain devices are consistently "out" by a certain bearing.</li>
+<li>The camera feed may appear "stretched". Again the focus on fixing this will be in LocAR.</li>
+</ul>
 <h2 id="a-frame">A-Frame</h2>
 <p>AR.js offers A-Frame components to implement location-based AR. There are three variants of the components, detailed as below:</p>
 <ul>
 <li>
-<p>The <code>new-location-based</code> components. These have been available since AR.js 3.4.0, incorporate various bug fixes, use simpler code, and provide a thin wrapper round the three.js API shown below. These are recommended for most uses, though do not support all the <a href="../ui-events/">events</a> of the older components due to a different internal implementation. Nonetheless they the components likely to see further development - the older variants are unlikely to see further work besides bug fixes.</p>
+<p>The <code>new-location-based</code> components. <strong>In most cases, these are recommended</strong>. These have been available since AR.js 3.4.0, incorporate various bug fixes, use simpler code, and provide a thin wrapper round the three.js API shown below. These are recommended for most uses, though do not support all the <a href="../ui-events/">events</a> of the older components due to a different internal implementation. Nonetheless they the components likely to see further development - the older variants are unlikely to see further work besides bug fixes.</p>
 </li>
 <li>
-<p>The <code>projected</code> components. These have been available since AR.js 3.3.1, use largely the same internal implementation as the classic components, and were the first to offer projection of latitude/longitude into Spherical Mercator, discussed below.</p>
+<p>The <code>projected</code> components. These have been available since AR.js 3.3.1, use largely the same internal implementation as the classic components, and were the first to offer projection of latitude/longitude into Spherical Mercator, discussed below. They are generally <strong>not recommended</strong> unless you have problems with <code>new-location-based</code>.</p>
 </li>
 <li>
-<p>The classic components, available before AR.js 3.3.1. These are similar to the <code>projected</code> components but do not offer the facility to convert between latitude/longitude and the projected coordinates used for augmented reality, which can cause problems for more specialist uses such as showing roads and paths in augmented reality.</p>
+<p>The classic components, available before AR.js 3.3.1. These are similar to the <code>projected</code> components but do not offer the facility to convert between latitude/longitude and the projected coordinates used for augmented reality, which can cause problems for more specialist uses such as showing roads and paths in augmented reality. For most use cases it is preferred to use <code>new-location-based</code> but some uses, such as embedded AR scenes, only work with the classic components.</p>
 </li>
 </ul>
 <h3 id="the-components">The components</h3>
@@ -308,6 +326,7 @@ <h3 id="calculating-world-coordinates-of-arbitrary-augmented-content">Calculatin
 <p><code>gps-new-camera</code> implements projection via the underlying AR.js three.js <code>LocationBased</code> object (see three.js documentation, below) which is responsible for the actual projection. </p>
 <p><code>gps-projected-camera</code> provides similar functionality but via a different method and with some implementation differences. In <code>gps-projected-camera</code>, unlike <code>gps-new-camera</code>, the <strong>original GPS position</strong> is set as the world origin.</p>
 <h2 id="threejs">three.js</h2>
+<p>For pure three.js (no A-Frame) it is recommended to use <a href="https://github.com/AR-js-org/locar.js">LocAR</a>. The notes below, however, refer to the three.js version in the main AR.js repository.</p>
 <p>The three.js API keeps track of your current GPS location (or allows you to set a fake location) and allows you to add three.js objects at a given latitude and longitude. It includes these classes:</p>
 <ul>
 <li><code>THREEx.LocationBased</code> - general manager class for the three.js location-based API.</li>

sitemap.xml

@@ -1,27 +1,27 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"><url>
      <loc>None</loc>
-     <lastmod>2024-10-25</lastmod>
+     <lastmod>2024-10-26</lastmod>
      <changefreq>daily</changefreq>
     </url><url>
      <loc>None</loc>
-     <lastmod>2024-10-25</lastmod>
+     <lastmod>2024-10-26</lastmod>
      <changefreq>daily</changefreq>
     </url><url>
      <loc>None</loc>
-     <lastmod>2024-10-25</lastmod>
+     <lastmod>2024-10-26</lastmod>
      <changefreq>daily</changefreq>
     </url><url>
      <loc>None</loc>
-     <lastmod>2024-10-25</lastmod>
+     <lastmod>2024-10-26</lastmod>
      <changefreq>daily</changefreq>
     </url><url>
      <loc>None</loc>
-     <lastmod>2024-10-25</lastmod>
+     <lastmod>2024-10-26</lastmod>
      <changefreq>daily</changefreq>
     </url><url>
      <loc>None</loc>
-     <lastmod>2024-10-25</lastmod>
+     <lastmod>2024-10-26</lastmod>
      <changefreq>daily</changefreq>
     </url>
 </urlset>