Skip to content

Commit

Permalink
Refactor examples to match tutorial
Browse files Browse the repository at this point in the history
  • Loading branch information
nickw1 committed Dec 8, 2024
1 parent 169c201 commit b8cbe20
Show file tree
Hide file tree
Showing 20 changed files with 523 additions and 131 deletions.
4 changes: 2 additions & 2 deletions docs/01-helloworld/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@
<html>
<head>
<title>three.js</title>
<script type="module" crossorigin src="/locar.js/assets/01-helloworld-BK54cGeW.js"></script>
<link rel="modulepreload" crossorigin href="/locar.js/assets/locar.es-D2pHxP8J.js">
<script type="module" crossorigin src="/locar.js/assets/01-helloworld-DomqHtFg.js"></script>
<link rel="modulepreload" crossorigin href="/locar.js/assets/locar.es-C0jLPF0Z.js">
</head>
<body>
</body>
Expand Down
4 changes: 2 additions & 2 deletions docs/02-gps-and-sensors/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@
<html>
<head>
<title>three.js</title>
<script type="module" crossorigin src="/locar.js/assets/02-gps-and-sensors-La4_GML4.js"></script>
<link rel="modulepreload" crossorigin href="/locar.js/assets/locar.es-D2pHxP8J.js">
<script type="module" crossorigin src="/locar.js/assets/02-gps-and-sensors-DkTaubFC.js"></script>
<link rel="modulepreload" crossorigin href="/locar.js/assets/locar.es-C0jLPF0Z.js">
</head>
<body>
</body>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@
<html>
<head>
<title>three.js</title>
<script type="module" crossorigin src="/locar.js/assets/03-ar-objects-D3M74PcG.js"></script>
<link rel="modulepreload" crossorigin href="/locar.js/assets/locar.es-D2pHxP8J.js">
<script type="module" crossorigin src="/locar.js/assets/03-api-communication-DdMSg92Q.js"></script>
<link rel="modulepreload" crossorigin href="/locar.js/assets/locar.es-C0jLPF0Z.js">
</head>
<body>
</body>
Expand Down
10 changes: 0 additions & 10 deletions docs/04-api-communication/index.html

This file was deleted.

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 0 additions & 1 deletion docs/assets/03-ar-objects-D3M74PcG.js

This file was deleted.

Large diffs are not rendered by default.

8 changes: 4 additions & 4 deletions docs/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,10 @@
</div>
<h1>LocAR.js examples</h1>
<ol>
<li><a href='01-helloworld/index.html'>Hello World</a>: Display a red cube just to the north of a fake GPS location. Can be tested on a desktop or laptop.</li>
<li><a href='02-gps-and-sensors/index.html'>GPS and Sensors</a>: Requires a mobile device wih GPS and sensors. Demonstrates use of the GPS and the device sensors to show real AR. Gets your initial location and displays four coloured boxes to the north (red), south (yellow), west (blue) and east (green) of your initial location. Can be used as a test to check whether your device sensors are accurate; if the red box does not appear to the North, your device sensors may be mis-calibrated.</li>
<li><a href='03-ar-objects/index.html'>AR Objects</a>: shows how you can add real AR objects with a given latitude and longitude and properties. Also shows how you can detect clicks on objects. Uses a hard-coded "fake" location and hard-coded objects, and you can rotate the three.js camera using the mouse, so will work on a desktop or laptop.</li>
<li><a href='04-api-communication/index.html'>API Communication</a>: shows how you can communicate with a live GeoJSON API (OpenStreetMap-based). The GeoJSON is parsed, and AR objects created from each GeoJSON feature in the feed. Uses your current real GPS location and the device sensors, so <strong>requires a real mobile device.</strong>. It also uses each object's OpenStreetMap ID to cache objects in memory as they are added, preventing the same object being added twice. Note that a new request to the server is performed if you move 100 metres; a better solution to minimise the number of server requests would be to implement a tiling system. This will hopefully appear soon! <strong>The live example only works in Europe and Turkey due to the coverage of the underlying API, but can easily be modified to work with any GeoJSON API covering other parts of the world.</strong></li>
<li><a href='/locar.js/01-helloworld/index.html'>Hello World</a>: Display a red cube just to the north of a fake GPS location. Can be tested on a desktop or laptop.</li>
<li><a href='/locar.js/02-gps-and-sensors/index.html'>GPS and Sensors</a>: Requires a mobile device wih GPS and sensors. Demonstrates use of the GPS and the device sensors to show real AR. Gets your initial location and displays four coloured boxes to the north (red), south (yellow), west (blue) and east (green) of your initial location. Can be used as a test to check whether your device sensors are accurate; if the red box does not appear to the North, your device sensors may be mis-calibrated.</li>
<li><a href='/locar.js/03-api-communication/index.html'>API Communication</a>: shows how you can communicate with a live GeoJSON API (OpenStreetMap-based). The GeoJSON is parsed, and AR objects created from each GeoJSON feature in the feed. Uses your current real GPS location and the device sensors, so <strong>requires a real mobile device.</strong>. It also uses each object's OpenStreetMap ID to cache objects in memory as they are added, preventing the same object being added twice. Note that a new request to the server is performed if you move 100 metres; a better solution to minimise the number of server requests would be to implement a tiling system. This will hopefully appear soon! <strong>The live example only works in Europe and Turkey due to the coverage of the underlying API, but can easily be modified to work with any GeoJSON API covering other parts of the world.</strong></li>
</ol>
<p>Also see the <a href='tutorial'>tutorial</a>.</p>
</body>
</html>
41 changes: 41 additions & 0 deletions docs/tutorial/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# LocAR.js - Develop a simple Points of Interest app

[LocAR.js](https://github.com/AR-js-org/locar.js) is the new - still in early development - standalone location-based API for AR.js.

Here is a series of tutorials taking you through how to use LocAR.js, from the basics to a more advanced example: a simple but working Points of Interest app using a live web API.

It is expected that you have some understanding of the absolute basics of [three.js](https://threejs.org). You might want to read the introductory "Creating a Scene" section of the [three.js manual](https://three.js.org/docs/index.html#manual/en). (Note that there is currently a formatting issue on Firefox with the source code samples, so you should use another browser such as Chrome. There is a fix imminent on Firefox, however).

You should also have very basic knowledge of [Vite](https://vitejs.dev) and the concept of JavaScript build tools and bundling. Vite is a build and development tool which, as well as bundling your code for production, provides a development server allowing you to develop client-side web apps "live" so that when you make a change to your code or its dependencies, your code is reloaded and changes appear instantly. See the Vite docs for more.

**Do note that it is not recommended to use Firefox on a mobile device due to limitations of the device orientation API. Chrome on Android is recommended.**

## Installing and developing

Here is a sample `package.json` containing three.js and LocAR.js as dependencies, and Vite as a dev dependency.

```
{
"dependencies": {
"three": "^0.169.0",
"locar": "^0.0.2"
},
"devDependencies": {
"vite": "^5.4.8"
},
"scripts": {
"dev" : "vite dev",
"build": "vite build"
}
}
```
As is standard in Vite, you should place your `index.html` inside your project's main directory and the JavaScript source, e.g. `main.js`, inside the `src` directory. You can then, as is normal with Vite, run in dev mode with `npm run dev`, which will start up a dev server on port 5173 and allow you to make live changes to your code which will be updated instantly.

You can also build a bundle with `npm run build`, which will create a production app (a JavaScript bundle plus a version of `index.html` linking to the bundle) in the `dist` directory.

### Contents

- [Part 1: Hello World](part1.md)
- [Part 2: Using the GPS and Device Orientation](part2.md)
- [Part 3: Connecting to a web API](part3.md)

Loading

0 comments on commit b8cbe20

Please sign in to comment.