Merge pull request #86 from kalwalt/fixing-nft

Adding NFT ( Natural Feature Tracking ) to the master branch

Many thanks to @kalwalt @nicolocarpignoli @Carnaux and many more who I simply can't find their GitHub names. If someone has them please tag them inside a comment.

We are finally there. jsartoolkit5 with NFT support. It runs smoothly on phones! This is so awesome and exciting and I feel so honored to merge that into the main branch. 

Exciting times ahead.

.gitignore

@@ -1,3 +1,3 @@
 doc/reference
 node_modules
-build/libar.bc
+build/*.bc

README.md

@@ -1,6 +1,14 @@
 # ARToolKit.js
 
-Emscripten port of [ARToolKit](https://github.com/artoolkit/artoolkit5) to JavaScript.
+Emscripten port of [ARToolKit](https://github.com/artoolkitx/artoolkit5) to JavaScript.
+
+## MArkers Types
+
+JSARToolKit5 support these types of markers:
+- Square pictorial markers
+- Square barcode markers
+- Multi square markers set
+- NFT (natural feature tracking) markers
 
 ---
 **NOTE:**
@@ -19,18 +27,19 @@ When writing JavaScript and making changes be aware that the emscripten uglifier
 - `tools/` (build scripts for building ARToolKit.js)
 
 ## WebAssembly
-JSARToolKit5 supports WebAssembly. The libary builds two WebAssembly artefacts during the build process. These are ```build/artoolkit_wasm.js``` and ```build/artoolkit_wasm.wasm```. To use those include the artoolkit_wasm.js into your html page and define ```var artoolkit_wasm_url = '<<PATH TO>>/artoolkit_wasm.wasm';``` prior to loading the artoolkit_wasm.js file, like so:
+
+JSARToolKit5 supports WebAssembly. The libary builds two WebAssembly artifacts during the build process. These are ```build/artoolkit_wasm.js``` and ```build/artoolkit_wasm.wasm```. To use those, include the artoolkit_wasm.js into your html page and define ```var artoolkit_wasm_url = '<<PATH TO>>/artoolkit_wasm.wasm';``` before loading the artoolkit_wasm.js file, like this:
 
 ```js
 <script type='text/javascript'>
       var artoolkit_wasm_url = '../build/artoolkit_wasm.wasm';
 </script>
 <script src="../build/artoolkit_wasm.js"></script>
 ```
-As loading the WebAssembly artefact is done asynchronous there is a callback that is called once everything is ready. 
+As loading the WebAssembly artifact is done asynchronously, there is a callback that is called when everything is ready.
 
 ```js
-window.addEventListener('artoolkit-loaded', () => {  
+window.addEventListener('artoolkit-loaded', () => {
     //do artoolkit stuff here
 });
 ```
@@ -42,65 +51,77 @@ See examples/simple_image_wasm.html for details.
 2. Clone ARToolKit5 project to get the latest source files. From within jsartoolkit5 directory do `git submodule update --init`. If you already cloned ARToolKit5 to a different directory you can:
   - create a link in the `jsartoolkit5/emscripten/` directory that points to ARToolKit5 (`jsartoolkit5/emscripten/artoolkit5`) (Linux and macOS only)
   - or, set the `ARTOOLKIT5_ROOT` environment variable to point to your ARToolKit5 clone
-  - or, change the `tools/makem.js` file to point to your artoolkit5 clone (line 62, 83, 107, 140)
+  - or, change the `tools/makem.js` file to point to your artoolkit5 clone (line 20)
 
-## Build Instructions
+## Build the project
 
-### Build using Docker
-1. Install Docker (if you havn't already) [Docker](https://www.docker.com/) -> Get Docker
-3. From inside jsartoolkit5 directory run `docker run -dit --name emscripten -v $(pwd):/src trzeci/emscripten-slim:sdk-tag-1.37.34-64bit bash`
-4. `docker exec emscripten npm run build`
+### Recommended: Build using Docker
 
+1. Install Docker (if you havn't already): [get Docker](https://www.docker.com/)
+2. Clone artoolkit5 repository on your machine: `git submodule update --init`
+3. `npm install`
+4. From inside jsartoolkit5 directory run `docker run -dit --name emscripten -v $(pwd):/src trzeci/emscripten-slim:latest bash` to download and start the container, in preparation for the build
+5. `docker exec emscripten npm run build-local` to build JS version of artoolkit5
+6. `docker stop emscripten` to stop the container after the build, if needed
+7. `docker rm emscripten` to remove the container
+8. `docker rmi trzeci/emscripten-slim:latest` to remove the Docker image, if you don't need it anymore
+9. The build artifacts will appear in `/build`. There's a build with debug symbols in `artoolkit.debug.js` file and the optimized build with bundled JS API in `artoolkit.min.js`; also, a WebAssembly build artoolkit_wasm.js and artoolkit_wasm.wasm
 
-### Build with manual emscripten setup
+### ⚠️ Not recommended ⚠️ : Build local with manual emscripten setup
+
+To prevent issues with Emscripten setup and to not have to maintain several build environments (macOS, Windows, Linux) we only maintain the **Build using Docker**. Following are the instructions of the last know build on Linux which we verified are working. **Use at own risk.**
+** Not working on macOS!**
 
 1. Install build tools
   1. Install node.js (https://nodejs.org/en/)
   2. Install python2 (https://www.python.org/downloads/)
-  3. Install emscripten (http://kripken.github.io/emscripten-site/docs/getting_started/downloads.html#download-and-install)
+  3. Install emscripten (https://emscripten.org/docs/getting_started/downloads.html#download-and-install)
+     We used emscripten version **1.39.5-fastcomp** ~~1.38.44-fastcomp~~
 
+jsartoolkit5 aim is to create a Javascript version of artoolkit5. First, you need the artoolkit5 repository on your machine:
 2. Clone ARToolKit5 project to get the latest source files. From within jsartoolkit5 directory do `git submodule update --init`. If you already cloned ARToolKit5 to a different directory you can:
   - create a link in the `jsartoolkit5/emscripten/` directory that points to ARToolKit5 (`jsartoolkit5/emscripten/artoolkit5`)
   - or, set the `ARTOOLKIT5_ROOT` environment variable to point to your ARToolKit5 clone
-  - or, change the `tools/makem.js` file to point to your artoolkit5 clone (line 62, 83, 107, 140)
+  - or, change the `tools/makem.js` file to point to your artoolkit5 clone (line 20)
 
 3. Building
-  1. Make sure `EMSCRIPTEN` env variable is set (e.g. `EMSCRIPTEN=/usr/lib/emsdk_portable/emscripten/master/`)
-  3. Run `npm run build`
-
+  1. Make sure `EMSCRIPTEN` env variable is set (e.g. `EMSCRIPTEN=/usr/lib/emsdk_portable/emscripten/master/ node tools/makem.js`
+  3. Run `npm install`
+  4. Run `npm run build-local`
+
 During development, you can run ```npm run watch```, it will rebuild the library everytime you change ```./js/``` directory.
 
 4. The built ASM.js files are in `/build`. There's a build with debug symbols in `artoolkit.debug.js` and the optimized build with bundled JS API in `artoolkit.min.js`.
 
-# ARToolKit JS API
+## ARToolKit JS API
 
 ```js
-<script async src="build/artoolkit.min.js">
+<script src="../build/artoolkit.min.js">
 // include optimized ASM.js build and JS API
 </script>
 ```
 
-# ARToolKit JS debug build
+## ARToolKit JS debug build
 
 ```js
-<script src="build/artoolkit.debug.js">
+<script async src="../build/artoolkit.debug.js">
 // - include debug build
 </script>
-<script src="js/artoolkit.api.js">
+<script src="../js/artoolkit.api.js">
 // - include JS API
 </script>
 ```
 
-# ARToolKit Three.js helper API
+## ARToolKit Three.js helper API
 
 ```js
-<script async src="build/artoolkit.min.js">
+<script src="../build/artoolkit.min.js">
 // - include optimized ASM.js build and JS API
 </script>
-<script async src="three.min.js">
+<script src="js/third_party/three.js/three.min.js">
 // - include Three.js
 </script>
-<script async src="js/artoolkit.three.js">
+<script src="../js/artoolkit.three.js">
 // - include Three.js helper API
 </script>
 <script>
@@ -109,11 +130,11 @@ console.log("Three.js helper API loaded");
 };
 if (window.ARController && window.ARController.getUserMediaThreeScene) {
 ARThreeOnLoad();
-}
+};
 </script>
 ```
 
-# Examples
+## Examples
 
 See `examples/` for examples on using the raw API and the Three.js helper API.
 
@@ -126,8 +147,10 @@ The basic operation goes like this:
 5. Add a `'getMarker'` event listener
 6. Call `ARController.process(img)`
 
+### Basic example with an image source and a pattern marker ( hiro )
+
 ```js
-<script src="build/artoolkit.min.js"></script>
+<script src="../build/artoolkit.min.js"></script>
 <script>
   var param = new ARCameraParam();
 
@@ -142,7 +165,7 @@ The basic operation goes like this:
     // For pattern markers, use artoolkit.AR_TEMPLATE_MATCHING_COLOR
     //
     ar.setPatternDetectionMode(artoolkit.AR_TEMPLATE_MATCHING_COLOR_AND_MATRIX);
-    
+
     ar.addEventListener('markerNum', function (ev) {
       console.log('got markers', markerNum);
     });
@@ -159,57 +182,47 @@ The basic operation goes like this:
 </script>
 ```
 
-## Public
+### Basic example with a worker and a NFT marker
 
-*the calls your JS apps needs*
+**NFT** (**N**atural **F**eature **T**racking) is a markerless technology that let you track almost any images you want. To use this feature take a look at the **nft_improved_worker** example folder. If you want to create your custom NFT marker you can use the online tool [NFT-Marker-Creator](https://carnaux.github.io/NFT-Marker-Creator/). Before proceeding with the creation of your markers, carefully read the information on the [wiki](https://github.com/Carnaux/NFT-Marker-Creator/wiki/Creating-good-markers).
 
-- `artoolkit.init(path, camera_param_path)` - load path for artoolkit emscripten files
-- `artoolkit.onReady(callback)` - runs callback when artoolkit has completely downloaded, initalized and ready to run
-- `artoolkit.setup(width, height);` - initalize a buffer size for a canvas of width & height
-- `artoolkit.process(canvas);` - extracts a frame from a canvas and process it
-- `artoolkit.debugSetup()` - enables debugging, adds a threshold image to the dom
-- `artoolkit.getDetectedMarkers()` - returns an array of detected markers from last detection process
-- `artoolkit.getCameraMatrix()` - returns the projection matrix computed from camera parameters
-- `artoolkit.getTransformationMatrix()` - returns the 16-element WebGL transformation matrix
+In the code below a summarized example:
 
-## Internals
 
-*calls called from emscripten runtime -> artoolkit.js*
-
-- `artoolkit.onFrameMalloc(object)` - gets called when frame buffer gets allocated for canvas
-- `artoolkit.onMarkerNum(number)` - gets called with the numbers of markers detected
-- `artoolkit.onGetMarker(object, index)` - gets called with the marker struct for the positioned marker
-
-*calls available from js -> emscripten*
-
-- `_setup(width, height)`
-- `_setThreshold(int)` - 0 to 255
-- `_process()`
-- `_setDebugMode(boolean)`
-- `_addMarker(string)`
-- `setThreshold`
-- `setThresholdMode()` eg. `Module.setThresholdMode(Module.AR_LABELING_THRESH_MODE_AUTO_MEDIAN / AR_LABELING_THRESH_MODE_AUTO_OTSU );
-- `setLabelingMode`
-- `setPatternDetectionMode`
-- `setMatrixCodeType()` : Eg. Module.setMatrixCodeType(Module.AR_MATRIX_CODE_3x3);
-- `setImageProcMode`
-- `setPattRatio`
-
-## Examples
-
-```
-artoolkit.init('', 'camera_para.dat').onReady(function() {
-artoolkit.setProjectionNearPlane(1);
-artoolkit.setProjectionFarPlane(1000);
-artoolkit.setPatternDetectionMode(artoolkit.CONSTANTS.AR_MATRIX_CODE_DETECTION);
-artoolkit.setMatrixCodeType(artoolkit.CONSTANTS.AR_MATRIX_CODE_4x4);
-})
-
-artoolkit.init('', 'camera_para.dat').onReady(function() {
-artoolkit.addMarker('../bin/Data/patt.hiro', function(marker) {
-artoolkit.process(v);
-})
-})
+```js
+<div id="container">
+    <video id="video"></video>
+    <canvas style="position: absolute; left:0; top:0" id="canvas_draw"></canvas>
+</div>
+// main worker create the web worker see in the examples/nft_improved_worker for details
+<script src="main_worker.js"></script>
+<script>
+var container = document.getElementById('container');
+var video = document.getElementById('video');
+var canvas_draw = document.getElementById('canvas_draw');
+
+if (navigator.mediaDevices && navigator.mediaDevices.getUserMedia) {
+    var hint = {};
+    if (isMobile()) {
+        hint = {
+            facingMode: {"ideal": "environment"},
+            audio: false,
+            video: {
+                width: {min: 240, max: 240},
+                height: {min: 360, max: 360},
+            },
+        };
+    }
+
+    navigator.mediaDevices.getUserMedia({video: hint}).then(function (stream) {
+        video.srcObject = stream;
+        video.play();
+        video.addEventListener("loadedmetadata", function() {
+            start(container, markers["pinball"], video, video.videoWidth, video.videoHeight, canvas_draw, function() { statsMain.update() }, function() { statsWorker.update()) };
+        });
+    });
+}
+</script>
 ```
 
 ## Constants
@@ -260,3 +273,33 @@ artoolkit.process(v);
 - AR_MARKER_INFO_CUTOFF_PHASE_POSE_ERROR_MULTI
 - AR_MARKER_INFO_CUTOFF_PHASE_HEURISTIC_TROUBLESOME_MATRIX_CODES
 ```
+
+## Build the tests
+
+You can run an automated routine to make some tests, in the main jsartoolkit5 folder just run in a console the command:
+
+```
+npm run test
+```
+
+Then open the tests page:
+
+```
+http://localhost:8085/tests/index.html
+```
+
+## Build the documentation
+
+It is possible to build the api documentation, run this command in the main jsartoolkit5 folder:
+
+```
+npm run create-doc
+```
+
+The api documentation will be created in the **doc** folder. Navigate to the **reference** folder to view the api docs.
+
+## Issue tracker
+
+If you found a bug or you have a feature request, or for any inquiries related to jsartoolkit5 development file an issue at:
+
+[github.com/artoolkitx/jsartoolkit5/issues](https://github.com/artoolkitx/jsartoolkit5/issues)