Skip to content

Commit 244b2b2

Browse files
authored
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.
2 parents b2a6c75 + 905f3ef commit 244b2b2

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

80 files changed

+112608
-41757
lines changed

.gitignore

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
doc/reference
22
node_modules
3-
build/libar.bc
3+
build/*.bc

README.md

Lines changed: 119 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,14 @@
11
# ARToolKit.js
22

3-
Emscripten port of [ARToolKit](https://github.com/artoolkit/artoolkit5) to JavaScript.
3+
Emscripten port of [ARToolKit](https://github.com/artoolkitx/artoolkit5) to JavaScript.
4+
5+
## MArkers Types
6+
7+
JSARToolKit5 support these types of markers:
8+
- Square pictorial markers
9+
- Square barcode markers
10+
- Multi square markers set
11+
- NFT (natural feature tracking) markers
412

513
---
614
**NOTE:**
@@ -19,18 +27,19 @@ When writing JavaScript and making changes be aware that the emscripten uglifier
1927
- `tools/` (build scripts for building ARToolKit.js)
2028

2129
## WebAssembly
22-
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:
30+
31+
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:
2332

2433
```js
2534
<script type='text/javascript'>
2635
var artoolkit_wasm_url = '../build/artoolkit_wasm.wasm';
2736
</script>
2837
<script src="../build/artoolkit_wasm.js"></script>
2938
```
30-
As loading the WebAssembly artefact is done asynchronous there is a callback that is called once everything is ready.
39+
As loading the WebAssembly artifact is done asynchronously, there is a callback that is called when everything is ready.
3140

3241
```js
33-
window.addEventListener('artoolkit-loaded', () => {
42+
window.addEventListener('artoolkit-loaded', () => {
3443
//do artoolkit stuff here
3544
});
3645
```
@@ -42,65 +51,77 @@ See examples/simple_image_wasm.html for details.
4251
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:
4352
- create a link in the `jsartoolkit5/emscripten/` directory that points to ARToolKit5 (`jsartoolkit5/emscripten/artoolkit5`) (Linux and macOS only)
4453
- or, set the `ARTOOLKIT5_ROOT` environment variable to point to your ARToolKit5 clone
45-
- or, change the `tools/makem.js` file to point to your artoolkit5 clone (line 62, 83, 107, 140)
54+
- or, change the `tools/makem.js` file to point to your artoolkit5 clone (line 20)
4655

47-
## Build Instructions
56+
## Build the project
4857

49-
### Build using Docker
50-
1. Install Docker (if you havn't already) [Docker](https://www.docker.com/) -> Get Docker
51-
3. From inside jsartoolkit5 directory run `docker run -dit --name emscripten -v $(pwd):/src trzeci/emscripten-slim:sdk-tag-1.37.34-64bit bash`
52-
4. `docker exec emscripten npm run build`
58+
### Recommended: Build using Docker
5359

60+
1. Install Docker (if you havn't already): [get Docker](https://www.docker.com/)
61+
2. Clone artoolkit5 repository on your machine: `git submodule update --init`
62+
3. `npm install`
63+
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
64+
5. `docker exec emscripten npm run build-local` to build JS version of artoolkit5
65+
6. `docker stop emscripten` to stop the container after the build, if needed
66+
7. `docker rm emscripten` to remove the container
67+
8. `docker rmi trzeci/emscripten-slim:latest` to remove the Docker image, if you don't need it anymore
68+
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
5469

55-
### Build with manual emscripten setup
70+
### ⚠️ Not recommended ⚠️ : Build local with manual emscripten setup
71+
72+
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.**
73+
** Not working on macOS!**
5674

5775
1. Install build tools
5876
1. Install node.js (https://nodejs.org/en/)
5977
2. Install python2 (https://www.python.org/downloads/)
60-
3. Install emscripten (http://kripken.github.io/emscripten-site/docs/getting_started/downloads.html#download-and-install)
78+
3. Install emscripten (https://emscripten.org/docs/getting_started/downloads.html#download-and-install)
79+
We used emscripten version **1.39.5-fastcomp** ~~1.38.44-fastcomp~~
6180

81+
jsartoolkit5 aim is to create a Javascript version of artoolkit5. First, you need the artoolkit5 repository on your machine:
6282
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:
6383
- create a link in the `jsartoolkit5/emscripten/` directory that points to ARToolKit5 (`jsartoolkit5/emscripten/artoolkit5`)
6484
- or, set the `ARTOOLKIT5_ROOT` environment variable to point to your ARToolKit5 clone
65-
- or, change the `tools/makem.js` file to point to your artoolkit5 clone (line 62, 83, 107, 140)
85+
- or, change the `tools/makem.js` file to point to your artoolkit5 clone (line 20)
6686

6787
3. Building
68-
1. Make sure `EMSCRIPTEN` env variable is set (e.g. `EMSCRIPTEN=/usr/lib/emsdk_portable/emscripten/master/`)
69-
3. Run `npm run build`
70-
88+
1. Make sure `EMSCRIPTEN` env variable is set (e.g. `EMSCRIPTEN=/usr/lib/emsdk_portable/emscripten/master/ node tools/makem.js`
89+
3. Run `npm install`
90+
4. Run `npm run build-local`
91+
7192
During development, you can run ```npm run watch```, it will rebuild the library everytime you change ```./js/``` directory.
7293

7394
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`.
7495

75-
# ARToolKit JS API
96+
## ARToolKit JS API
7697

7798
```js
78-
<script async src="build/artoolkit.min.js">
99+
<script src="../build/artoolkit.min.js">
79100
// include optimized ASM.js build and JS API
80101
</script>
81102
```
82103

83-
# ARToolKit JS debug build
104+
## ARToolKit JS debug build
84105

85106
```js
86-
<script src="build/artoolkit.debug.js">
107+
<script async src="../build/artoolkit.debug.js">
87108
// - include debug build
88109
</script>
89-
<script src="js/artoolkit.api.js">
110+
<script src="../js/artoolkit.api.js">
90111
// - include JS API
91112
</script>
92113
```
93114

94-
# ARToolKit Three.js helper API
115+
## ARToolKit Three.js helper API
95116

96117
```js
97-
<script async src="build/artoolkit.min.js">
118+
<script src="../build/artoolkit.min.js">
98119
// - include optimized ASM.js build and JS API
99120
</script>
100-
<script async src="three.min.js">
121+
<script src="js/third_party/three.js/three.min.js">
101122
// - include Three.js
102123
</script>
103-
<script async src="js/artoolkit.three.js">
124+
<script src="../js/artoolkit.three.js">
104125
// - include Three.js helper API
105126
</script>
106127
<script>
@@ -109,11 +130,11 @@ console.log("Three.js helper API loaded");
109130
};
110131
if (window.ARController && window.ARController.getUserMediaThreeScene) {
111132
ARThreeOnLoad();
112-
}
133+
};
113134
</script>
114135
```
115136

116-
# Examples
137+
## Examples
117138

118139
See `examples/` for examples on using the raw API and the Three.js helper API.
119140

@@ -126,8 +147,10 @@ The basic operation goes like this:
126147
5. Add a `'getMarker'` event listener
127148
6. Call `ARController.process(img)`
128149

150+
### Basic example with an image source and a pattern marker ( hiro )
151+
129152
```js
130-
<script src="build/artoolkit.min.js"></script>
153+
<script src="../build/artoolkit.min.js"></script>
131154
<script>
132155
var param = new ARCameraParam();
133156

@@ -142,7 +165,7 @@ The basic operation goes like this:
142165
// For pattern markers, use artoolkit.AR_TEMPLATE_MATCHING_COLOR
143166
//
144167
ar.setPatternDetectionMode(artoolkit.AR_TEMPLATE_MATCHING_COLOR_AND_MATRIX);
145-
168+
146169
ar.addEventListener('markerNum', function (ev) {
147170
console.log('got markers', markerNum);
148171
});
@@ -159,57 +182,47 @@ The basic operation goes like this:
159182
</script>
160183
```
161184

162-
## Public
185+
### Basic example with a worker and a NFT marker
163186

164-
*the calls your JS apps needs*
187+
**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).
165188

166-
- `artoolkit.init(path, camera_param_path)` - load path for artoolkit emscripten files
167-
- `artoolkit.onReady(callback)` - runs callback when artoolkit has completely downloaded, initalized and ready to run
168-
- `artoolkit.setup(width, height);` - initalize a buffer size for a canvas of width & height
169-
- `artoolkit.process(canvas);` - extracts a frame from a canvas and process it
170-
- `artoolkit.debugSetup()` - enables debugging, adds a threshold image to the dom
171-
- `artoolkit.getDetectedMarkers()` - returns an array of detected markers from last detection process
172-
- `artoolkit.getCameraMatrix()` - returns the projection matrix computed from camera parameters
173-
- `artoolkit.getTransformationMatrix()` - returns the 16-element WebGL transformation matrix
189+
In the code below a summarized example:
174190

175-
## Internals
176191

177-
*calls called from emscripten runtime -> artoolkit.js*
178-
179-
- `artoolkit.onFrameMalloc(object)` - gets called when frame buffer gets allocated for canvas
180-
- `artoolkit.onMarkerNum(number)` - gets called with the numbers of markers detected
181-
- `artoolkit.onGetMarker(object, index)` - gets called with the marker struct for the positioned marker
182-
183-
*calls available from js -> emscripten*
184-
185-
- `_setup(width, height)`
186-
- `_setThreshold(int)` - 0 to 255
187-
- `_process()`
188-
- `_setDebugMode(boolean)`
189-
- `_addMarker(string)`
190-
- `setThreshold`
191-
- `setThresholdMode()` eg. `Module.setThresholdMode(Module.AR_LABELING_THRESH_MODE_AUTO_MEDIAN / AR_LABELING_THRESH_MODE_AUTO_OTSU );
192-
- `setLabelingMode`
193-
- `setPatternDetectionMode`
194-
- `setMatrixCodeType()` : Eg. Module.setMatrixCodeType(Module.AR_MATRIX_CODE_3x3);
195-
- `setImageProcMode`
196-
- `setPattRatio`
197-
198-
## Examples
199-
200-
```
201-
artoolkit.init('', 'camera_para.dat').onReady(function() {
202-
artoolkit.setProjectionNearPlane(1);
203-
artoolkit.setProjectionFarPlane(1000);
204-
artoolkit.setPatternDetectionMode(artoolkit.CONSTANTS.AR_MATRIX_CODE_DETECTION);
205-
artoolkit.setMatrixCodeType(artoolkit.CONSTANTS.AR_MATRIX_CODE_4x4);
206-
})
207-
208-
artoolkit.init('', 'camera_para.dat').onReady(function() {
209-
artoolkit.addMarker('../bin/Data/patt.hiro', function(marker) {
210-
artoolkit.process(v);
211-
})
212-
})
192+
```js
193+
<div id="container">
194+
<video id="video"></video>
195+
<canvas style="position: absolute; left:0; top:0" id="canvas_draw"></canvas>
196+
</div>
197+
// main worker create the web worker see in the examples/nft_improved_worker for details
198+
<script src="main_worker.js"></script>
199+
<script>
200+
var container = document.getElementById('container');
201+
var video = document.getElementById('video');
202+
var canvas_draw = document.getElementById('canvas_draw');
203+
204+
if (navigator.mediaDevices && navigator.mediaDevices.getUserMedia) {
205+
var hint = {};
206+
if (isMobile()) {
207+
hint = {
208+
facingMode: {"ideal": "environment"},
209+
audio: false,
210+
video: {
211+
width: {min: 240, max: 240},
212+
height: {min: 360, max: 360},
213+
},
214+
};
215+
}
216+
217+
navigator.mediaDevices.getUserMedia({video: hint}).then(function (stream) {
218+
video.srcObject = stream;
219+
video.play();
220+
video.addEventListener("loadedmetadata", function() {
221+
start(container, markers["pinball"], video, video.videoWidth, video.videoHeight, canvas_draw, function() { statsMain.update() }, function() { statsWorker.update()) };
222+
});
223+
});
224+
}
225+
</script>
213226
```
214227
215228
## Constants
@@ -260,3 +273,33 @@ artoolkit.process(v);
260273
- AR_MARKER_INFO_CUTOFF_PHASE_POSE_ERROR_MULTI
261274
- AR_MARKER_INFO_CUTOFF_PHASE_HEURISTIC_TROUBLESOME_MATRIX_CODES
262275
```
276+
277+
## Build the tests
278+
279+
You can run an automated routine to make some tests, in the main jsartoolkit5 folder just run in a console the command:
280+
281+
```
282+
npm run test
283+
```
284+
285+
Then open the tests page:
286+
287+
```
288+
http://localhost:8085/tests/index.html
289+
```
290+
291+
## Build the documentation
292+
293+
It is possible to build the api documentation, run this command in the main jsartoolkit5 folder:
294+
295+
```
296+
npm run create-doc
297+
```
298+
299+
The api documentation will be created in the **doc** folder. Navigate to the **reference** folder to view the api docs.
300+
301+
## Issue tracker
302+
303+
If you found a bug or you have a feature request, or for any inquiries related to jsartoolkit5 development file an issue at:
304+
305+
[github.com/artoolkitx/jsartoolkit5/issues](https://github.com/artoolkitx/jsartoolkit5/issues)

build.sh

Lines changed: 0 additions & 46 deletions
This file was deleted.

0 commit comments

Comments
 (0)