Bläddra i källkod

Update docs

customisations
alemart 10 månader sedan
förälder
incheckning
ec1b74d008

+ 5
- 6
docs/getting-started/activate-your-webcam.md Visa fil

@@ -4,7 +4,7 @@ In this section we're going to learn how to use your webcam to capture the video
4 4
 
5 5
 ## Change the source of data
6 6
 
7
-Instead of using a video file, we're going to use your webcam. We simply need to change the source of data and instruct encantar.js to use your webcam. We'll do it with 1 new line of code!
7
+Instead of using a video file, we're going to use your webcam. We simply need to change the source of data and instruct encantar.js to use your webcam. We'll do it with one new line of code!
8 8
 
9 9
 ```js title="ar-demo.js" hl_lines="20-22"
10 10
 async function startARSession()
@@ -100,7 +100,7 @@ Here is the reference image in case you need it again:
100 100
 
101 101
 <figure markdown>
102 102
 [![/assets/my-reference-image.webp](../assets/my-reference-image.webp "Based on free image by ArtRose from https://pixabay.com/pt/vectors/bruxa-vassoura-gato-chap%c3%a9u-magia-5635225/"){ width=512 }](../assets/my-reference-image.webp){ ._blank }
103
-<figcaption>Reference Image</figure>
103
+<figcaption>Reference Image</figcaption>
104 104
 </figure>
105 105
 
106 106
 
@@ -111,7 +111,7 @@ Let's polish our work. When the tracker is scanning the physical scene, we'll di
111 111
 Save the image below as [scan.png](../assets/scan.png){ ._blank }:
112 112
 
113 113
 <figure markdown>
114
-<span class="transparent-background" style="display:inline-block">
114
+<span class="transparent-grid">
115 115
 [![scan.png](../assets/scan.png)](../assets/scan.png){ ._blank }
116 116
 </span>
117 117
 <figcaption>Scan gimmick</figcaption>
@@ -119,14 +119,13 @@ Save the image below as [scan.png](../assets/scan.png){ ._blank }:
119 119
 
120 120
 In order to display that scan gimmick, we need to create a HUD (<em>Heads-Up Display</em>). A HUD is an overlay used to display 2D content in front of the augmented scene. It's part of the viewport. Modify `index.html` and `ar-demo.js` as follows:
121 121
 
122
-```html title="index.html" hl_lines="10-13 16-20"
122
+```html title="index.html" hl_lines="9-12 15-19"
123 123
 <!doctype html>
124 124
 <html>
125 125
     <head>
126 126
         <meta charset="utf-8">
127 127
         <meta name="viewport" content="width=device-width,initial-scale=1">
128 128
         <title>encantar.js WebAR demo</title>
129
-        <!-- <script> tags of the rendering engine of your choice -->
130 129
         <script src="encantar.js"></script>
131 130
         <script src="ar-demo.js"></script>
132 131
         <style>
@@ -301,4 +300,4 @@ async function startARSession()
301 300
 }
302 301
 ```
303 302
 
304
-Open <http://localhost:8000>{ ._blank } again. Enjoy your WebAR experience! :wink:
303
+Open <http://localhost:8000>{ ._blank } again. Now we're ready to create the augmented scene! :wink:

docs/getting-started/create-the-augmented-scene.md → docs/getting-started/augment-the-scene.md Visa fil

@@ -1,26 +1,24 @@
1
-# Create the augmented scene
1
+# Augment the scene
2 2
 
3
-Now that the image is being tracked, the next step is to render a virtual scene on top of it. You need a 3D rendering technology to do that.
3
+We're already tracking an image of the physical world. The next step is to augment it with computer graphics. You'll use a different technology to render the graphics.
4 4
 
5 5
 ## Pick a 3D rendering technology
6 6
 
7
-encantar.js is not a 3D rendering technology. It is an Augmented Reality technology that provides the data you need in order to augment your physical scenes. There are free and open-source 3D rendering technologies for the web that you can find online and use with encantar.js. Popular solutions include: [A-Frame](#a-frame), [Babylon.js](#babylonjs) and [Three.js](#threejs). You can also use other solutions. encantar.js lets you pick any 3D rendering technology.
7
+encantar.js is not a 3D rendering technology. It is an Augmented Reality technology that provides the data you need in order to augment your physical scenes. There are free and open-source 3D rendering technologies that you can use with encantar.js. Popular solutions include: [A-Frame](#a-frame), [Babylon.js](#babylonjs) and [Three.js](#threejs). You can also use other solutions. encantar.js lets you pick any web-based 3D rendering technology.
8 8
 
9 9
 Once you pick a 3D rendering technology, you need to integrate it with encantar.js. There is a code that is responsible for that integration. I call it a _plugin_. Among other things, a plugin transports the tracking results from encantar.js to the 3D rendering technology of your choice.
10 10
 
11 11
 ## Use a plugin
12 12
 
13
-Writing a plugin is a task of moderate complexity. It requires dealing with matrices, with performance issues, and with some idiosyncrasies of the 3D rendering technologies in order to make sure that it all works as intended. It is advisable to have specialized knowledge of computer graphics programming in order to write a plugin that works correctly.
14
-
15
-I provide easy-to-use plugins that work with different 3D rendering technologies, so that you don't need to deal with the complexity. Those plugins are JavaScript (.js) files. You just need to add a plugin to your web page, via a `<script>` tag, and then the integration will be done for you. It's really that simple!
13
+Writing a plugin is a task of moderate complexity. It requires dealing with maths and with some idiosyncrasies of the 3D rendering technologies in order to make sure that it all works as intended. I provide easy-to-use plugins that work with different 3D rendering technologies, so that you don't need to deal with that complexity yourself. Plugins are shipped as JavaScript (.js) files. You just need to add a plugin to your web page, and then the integration will be done for you!
16 14
 
17 15
 [Get the plugins](https://github.com/alemart/encantar-js/tree/master/plugins){ .md-button .md-button--primary ._blank }
18 16
 
19 17
 ## Create the virtual scene
20 18
 
21
-You will create the virtual scene using the 3D rendering technology of your choice. As soon as you combine it with a plugin, the physical scene will be automagically augmented with the virtual scene, thus creating the augmented scene.
19
+You will create the virtual scene using the 3D rendering technology of your choice. As soon as you combine it with an appropriate plugin, the physical scene will be automagically augmented with the virtual scene, thus creating the augmented scene.
22 20
 
23
-Let me tell you a bit more about the 3D rendering technologies I just mentioned.
21
+Let me tell you more about the 3D rendering technologies I just mentioned.
24 22
 
25 23
 ### A-Frame
26 24
 
@@ -32,15 +30,15 @@ A-Frame is built on top of [Three.js](#threejs) and extends it in powerful ways.
32 30
 
33 31
 ### Babylon.js
34 32
 
35
-[Babylon.js](https://www.babylonjs.com){ ._blank } is a powerful open-source game and 3D rendering engine for the web. It includes pretty much all features you commonly find in 3D rendering engines (scene graphs, lights, materials, meshes, etc.), plus systems that are specific to game engines (animation engine, audio engine, collision system, physics system, support for sprites, etc.), plus all kinds of sophisticated features for various applications.
33
+[Babylon.js](https://www.babylonjs.com){ ._blank } is a powerful open-source game and 3D rendering engine for the web. It includes pretty much all features you commonly find in 3D rendering engines (scene graphs, lights, materials, meshes, animations, etc.), plus systems that are specific to game engines (audio engine, collision system, physics system, support for sprites, etc.), plus all kinds of sophisticated features for various applications.
36 34
 
37
-Babylon.js has an amazing documentation with plenty of learning resources. Even though it can be used by beginners, it's recommended to have JavaScript experience before creating projects with it.
35
+Babylon.js has an amazing documentation with plenty of learning resources, as well as a helpful and friendly community! Even though it can be used by beginners, it's recommended to have experience with JavaScript before creating projects with it.
38 36
 
39 37
 [Launch a Babylon.js demo](/encantar-js/demos/hello-babylon/README.html){ ._blank .md-button }
40 38
 
41 39
 ### Three.js
42 40
 
43
-[Three.js](https://threejs.org){ ._blank } is a popular open-source JavaScript library used to render 3D graphics in web browsers. It supports many features, including: scene graphs, cameras, animations, lights, materials, loading of 3D models, mathematical utilities, special effects, and more. It has an active and vibrant community. Many community-made extensions are available.
41
+[Three.js](https://threejs.org){ ._blank } is a popular open-source JavaScript library used to render 3D graphics in web browsers. It has many features, including: scene graphs, cameras, animations, lights, materials, loading of 3D models, mathematical utilities, special effects, and more. It has an active and vibrant community. Many community-made extensions are available.
44 42
 
45 43
 Using Three.js requires more JavaScript experience than using A-Frame in most cases, but it's also a great choice if you're comfortable with coding. Compared to A-Frame, Three.js offers you additional freedom on how you can organize your code, because it's a library, not a framework.
46 44
 

+ 9
- 9
docs/getting-started/concepts.md Visa fil

@@ -2,7 +2,7 @@
2 2
 
3 3
 Before diving into AR with you, I need to introduce a few concepts. Please take the time to read them all. Feel free to come back to this page at any time.
4 4
 
5
-## Fundamental concepts
5
+## What is Augmented Reality?
6 6
 
7 7
 Let me clarify what I mean by terms such as Augmented Reality and WebAR:
8 8
 
@@ -10,7 +10,7 @@ Let me clarify what I mean by terms such as Augmented Reality and WebAR:
10 10
 
11 11
     1.1. **AR** is an abbreviation of Augmented Reality.
12 12
 
13
-2. An **Augmented Reality experience** is a computer program designed to let users directly experience Augmented Reality[^1]. Augmented Reality experiences come in different shapes. Some are designed for smartphones and tablets, others for special headsets, and so on.
13
+2. An **Augmented Reality experience**, or Augmented Reality program, is a computer program designed to let users experience Augmented Reality[^1]. Augmented Reality experiences come in different shapes. Some are designed for smartphones and tablets, others for special headsets, and so on.
14 14
 
15 15
 3. **WebAR** is a set of technologies used to create Augmented Reality experiences that run in web browsers. WebAR makes it easy for users to experience AR, because they can have immediate access to the AR experiences. All they have to do is open a web page. They are not tied to specific platforms and they also don't need to download apps.
16 16
 
@@ -18,17 +18,17 @@ Let me clarify what I mean by terms such as Augmented Reality and WebAR:
18 18
 
19 19
 5. **encantar.js** is a WebAR technology. I also call it a WebAR engine. Lots of computations have to be performed behind the scenes in order to make an Augmented Reality experience possible. encantar.js uses the GPU[^2] to accelerate many of those computations. In fact, the GPU and the CPU[^3] are used together. This approach improves the performance of the WebAR experience and ultimately leads to a better user experience.
20 20
 
21
-Now that those terms are clarified, I say this: you can use encantar.js to create amazing WebAR experiences! :wink:
21
+You can use encantar.js to create amazing WebAR experiences! :wink:
22 22
 
23
-[^1]: This definition of AR experience is convenient in different ways. For example, it makes the term "WebAR experience", which is arguably better than "WebAR app" (no apps are downloaded), well-defined. I make a distinction between AR experience and experience of AR. An experience of AR is an event in consciousness in which AR is experienced. I sometimes use the latter definition.
23
+[^1]: An experience of AR is an event in consciousness in which AR is experienced. I sometimes use the latter definition.
24 24
 [^2]: Graphics Processing Unit
25 25
 [^3]: Central Processing Unit
26 26
 
27
-## Practical concepts
27
+## Basic concepts
28 28
 
29 29
 Let me explain some concepts that you'll see over and over again when developing WebAR experiences with encantar.js:
30 30
 
31
-1. The experience of Augmented Reality is created by augmenting the physical scene with the virtual scene.
31
+1. An Augmented Reality experience augments a physical scene with a virtual scene.
32 32
 
33 33
     1.1. The **physical scene** is a scene of the physical world.
34 34
 
@@ -38,7 +38,7 @@ Let me explain some concepts that you'll see over and over again when developing
38 38
 
39 39
 2. A **session** is a central component of a WebAR experience. It handles the **main loop**. The main loop performs two central tasks: it analyzes the input data and then passes the result of that analysis to the user callback.
40 40
 
41
-    2.1. The **user callback** is a function that updates and renders the virtual scene.
41
+    2.1. The **user callback** is a function that updates and renders the virtual scene. It is repeated in an **animation loop**, which is part of the main loop.
42 42
     
43 43
     2.2. The main loop is repeated until the session ends. The session ends when the user closes the web page, or by deliberate command.
44 44
 
@@ -56,8 +56,8 @@ Let me explain some concepts that you'll see over and over again when developing
56 56
 
57 57
 7. A session has a **mode**. The mode can be either immersive or inline.
58 58
 
59
-    7.1. In immersive mode, the augmented scene is displayed in such a way that it occupies, in a best-fit manner, the entire area of the screen in which the web page is shown. Think of it as a kind of fullscreen. The immersive mode is what is typically wanted.
59
+    7.1. In immersive mode, the augmented scene is displayed in such a way that it occupies the entire area of the screen in which the web page is shown. Think of it as a kind of fullscreen. The immersive mode is what is typically wanted.
60 60
     
61 61
     7.2. In inline mode, the augmented scene is displayed in a way that is consistent with the typical flow of a web page. We can display the augmented scene in a web page such as this one - in the middle of text, links and other elements.
62 62
 
63
-Did you read it all? Cool, so let's create our first WebAR experience! It gets to be fun, I promise! :wink:
63
+Now let's create our first WebAR experience! It gets to be fun, I promise! :wink:

+ 5
- 5
docs/getting-started/introduction.md Visa fil

@@ -11,14 +11,10 @@ Traditionally, users were required to download (sometimes large) apps to experie
11 11
     <source src="../../img/demo-cool3.mp4" type="video/mp4" />
12 12
 </video>
13 13
 -->
14
-![Demo](../../img/mage.gif)
14
+![Demo](../img/mage.gif)
15 15
 <figcaption>Image Tracking</figcaption>
16 16
 </figure>
17 17
 
18
-!!! tip "In a hurry?"
19
-
20
-    This guide is an in-depth introduction to web-based Augmented Reality with encantar.js. If you're in a hurry, skip straight to the [Demos](../demos.md) section.
21
-
22 18
 ## What to expect from this guide
23 19
 
24 20
 We will create together an Augmented Reality experience that runs in web browsers. You will learn how to track an image in real-time. This is a common use case of Augmented Reality technology.
@@ -26,3 +22,7 @@ We will create together an Augmented Reality experience that runs in web browser
26 22
 No matter if you are a beginner, an expert, or somewhere in-between, set yourself at ease: this step-by-step guide can be followed by you.
27 23
 
28 24
 [Get started](concepts.md){ .md-button }
25
+
26
+!!! tip "In a hurry?"
27
+
28
+    This guide is an in-depth introduction to web-based Augmented Reality with encantar.js. If you're in a hurry, skip straight to the [Demos](../demos.md) section.

+ 1
- 31
docs/getting-started/next-steps.md Visa fil

@@ -26,37 +26,7 @@ async function startARSession()
26 26
         image: document.getElementById('my-reference-image')
27 27
     }]);
28 28
 
29
-    const viewport = AR.Viewport({
30
-        container: document.getElementById('ar-viewport'),
31
-        hudContainer: document.getElementById('ar-hud')
32
-    });
33
-
34
-    //const video = document.getElementById('my-video');
35
-    //const source = AR.Source.Video(video);
36
-    const source = AR.Source.Camera();
37
-
38
-    const session = await AR.startSession({
39
-        mode: 'immersive',
40
-        viewport: viewport,
41
-        trackers: [ tracker ],
42
-        sources: [ source ],
43
-        stats: true,
44
-        gizmos: true,
45
-    });
46
-
47
-    const scan = document.getElementById('scan');
48
-
49
-    tracker.addEventListener('targetfound', event => {
50
-        scan.hidden = true;
51
-        session.gizmos.visible = false;
52
-    });
53
-
54
-    tracker.addEventListener('targetlost', event => {
55
-        scan.hidden = false;
56
-        session.gizmos.visible = true;
57
-    });
58
-
59
-    return session;
29
+    // ...
60 30
 }
61 31
 ```
62 32
 

+ 4
- 2
docs/getting-started/set-up-the-session.md Visa fil

@@ -195,9 +195,9 @@ async function startARSession()
195 195
 
196 196
 Now all you have to do to start a new session is call `startARSession()`!
197 197
 
198
-## Write the user callback
198
+## Start the animation loop
199 199
 
200
-The user callback is a function responsible for updating and rendering the virtual scene. We have no virtual scene at the moment, but we can already set up that function. In order to do this, we must call `session.requestAnimationFrame()` and pass the user callback as an argument.
200
+The animation loop repeatedly calls the user callback. The user callback is a function responsible for updating and rendering the virtual scene. We have no virtual scene at the moment, but we'll already set up that function. Let's call `session.requestAnimationFrame()` and pass the user callback as an argument:
201 201
 
202 202
 ```js title="ar-demo.js" hl_lines="6-11"
203 203
 window.onload = async function()
@@ -223,6 +223,8 @@ async function startARSession()
223 223
 }
224 224
 ```
225 225
 
226
+Calling `session.requestAnimationFrame()` inside the user callback, `animate()` in this example, makes it loop until the session ends. Making that call outside the user callback starts the loop.
227
+
226 228
 !!! info "requestAnimationFrame"
227 229
 
228 230
     Note that `session.requestAnimationFrame()` is different from `window.requestAnimationFrame()`. The former is a call to the WebAR engine, whereas the latter is a standard call to the web browser.

+ 1
- 1
docs/getting-started/set-up-the-tracker.md Visa fil

@@ -10,7 +10,7 @@ Not all images are suitable for tracking. Images should be distinct, detailed an
10 10
 
11 11
 <figure markdown>
12 12
 [![../assets/my-reference-image.webp](../assets/my-reference-image.webp "Based on free image by ArtRose from https://pixabay.com/pt/vectors/bruxa-vassoura-gato-chap%c3%a9u-magia-5635225/"){ width=512 }](../assets/my-reference-image.webp){ ._blank }
13
-<figcaption>Reference Image</figure>
13
+<figcaption>Reference Image</figcaption>
14 14
 </figure>
15 15
 
16 16
 Download the image to the `ar-demo/` folder. Save it as [my-reference-image.webp](../assets/my-reference-image.webp){ ._blank }.

+ 5
- 3
docs_overrides/style/extra.css Visa fil

@@ -14,13 +14,15 @@
14 14
     animation: heart 1000ms infinite;
15 15
 }
16 16
 
17
-/* Buttons */
18
-
19 17
 .md-button {
20 18
     border-radius: 100px !important;
21 19
 }
22 20
 
23
-/* Responsive videos */
21
+.transparent-grid {
22
+    display: inline-block;
23
+    background: url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgAQMAAABJtOi3AAAABlBMVEWZmZlmZmZYfKrVAAAAE0lEQVQI12P4/5+BgZoEA3VNBADtvT/BrQ+bEwAAAABJRU5ErkJggg==);
24
+    background-repeat: repeat;
25
+}
24 26
 
25 27
 .md-typeset video {
26 28
     height: auto;

+ 1
- 1
mkdocs.yml Visa fil

@@ -55,8 +55,8 @@ nav:
55 55
       - 'Set up a web server': 'getting-started/set-up-a-web-server.md'
56 56
       - 'Set up the tracker': 'getting-started/set-up-the-tracker.md'
57 57
       - 'Set up the session': 'getting-started/set-up-the-session.md'
58
-      - 'Create the augmented scene': 'getting-started/create-the-augmented-scene.md'
59 58
       - 'Activate your webcam': 'getting-started/activate-your-webcam.md'
59
+      - 'Augment the scene': 'getting-started/augment-the-scene.md'
60 60
       - 'Next steps': 'getting-started/next-steps.md'
61 61
     - 'Guidelines for Images': 'getting-started/guidelines-for-images.md'
62 62
     - 'Questions & Answers': 'faq.md'

Laddar…
Avbryt
Spara