Skip to content

Commit 905f3ef

Browse files
authored
Merge pull request #25 from kalwalt/api-doc-improvements
Api doc improvements and deleted old documentation in the Readme.md
2 parents 53fb34a + 2bc9b51 commit 905f3ef

File tree

2 files changed

+160
-66
lines changed

2 files changed

+160
-66
lines changed

README.md

Lines changed: 93 additions & 63 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:**
@@ -43,7 +51,7 @@ See examples/simple_image_wasm.html for details.
4351
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:
4452
- create a link in the `jsartoolkit5/emscripten/` directory that points to ARToolKit5 (`jsartoolkit5/emscripten/artoolkit5`) (Linux and macOS only)
4553
- or, set the `ARTOOLKIT5_ROOT` environment variable to point to your ARToolKit5 clone
46-
- 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)
4755

4856
## Build the project
4957

@@ -68,13 +76,13 @@ To prevent issues with Emscripten setup and to not have to maintain several buil
6876
1. Install node.js (https://nodejs.org/en/)
6977
2. Install python2 (https://www.python.org/downloads/)
7078
3. Install emscripten (https://emscripten.org/docs/getting_started/downloads.html#download-and-install)
71-
We used emscripten version **1.38.44-fastcomp**
79+
We used emscripten version **1.39.5-fastcomp** ~~1.38.44-fastcomp~~
7280

7381
jsartoolkit5 aim is to create a Javascript version of artoolkit5. First, you need the artoolkit5 repository on your machine:
7482
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:
7583
- create a link in the `jsartoolkit5/emscripten/` directory that points to ARToolKit5 (`jsartoolkit5/emscripten/artoolkit5`)
7684
- or, set the `ARTOOLKIT5_ROOT` environment variable to point to your ARToolKit5 clone
77-
- 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)
7886

7987
3. Building
8088
1. Make sure `EMSCRIPTEN` env variable is set (e.g. `EMSCRIPTEN=/usr/lib/emsdk_portable/emscripten/master/ node tools/makem.js`
@@ -85,35 +93,35 @@ During development, you can run ```npm run watch```, it will rebuild the library
8593

8694
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`.
8795

88-
# ARToolKit JS API
96+
## ARToolKit JS API
8997

9098
```js
91-
<script async src="build/artoolkit.min.js">
99+
<script src="../build/artoolkit.min.js">
92100
// include optimized ASM.js build and JS API
93101
</script>
94102
```
95103

96-
# ARToolKit JS debug build
104+
## ARToolKit JS debug build
97105

98106
```js
99-
<script src="build/artoolkit.debug.js">
107+
<script async src="../build/artoolkit.debug.js">
100108
// - include debug build
101109
</script>
102-
<script src="js/artoolkit.api.js">
110+
<script src="../js/artoolkit.api.js">
103111
// - include JS API
104112
</script>
105113
```
106114

107-
# ARToolKit Three.js helper API
115+
## ARToolKit Three.js helper API
108116

109117
```js
110-
<script async src="build/artoolkit.min.js">
118+
<script src="../build/artoolkit.min.js">
111119
// - include optimized ASM.js build and JS API
112120
</script>
113-
<script async src="three.min.js">
121+
<script src="js/third_party/three.js/three.min.js">
114122
// - include Three.js
115123
</script>
116-
<script async src="js/artoolkit.three.js">
124+
<script src="../js/artoolkit.three.js">
117125
// - include Three.js helper API
118126
</script>
119127
<script>
@@ -122,11 +130,11 @@ console.log("Three.js helper API loaded");
122130
};
123131
if (window.ARController && window.ARController.getUserMediaThreeScene) {
124132
ARThreeOnLoad();
125-
}
133+
};
126134
</script>
127135
```
128136

129-
# Examples
137+
## Examples
130138

131139
See `examples/` for examples on using the raw API and the Three.js helper API.
132140

@@ -139,8 +147,10 @@ The basic operation goes like this:
139147
5. Add a `'getMarker'` event listener
140148
6. Call `ARController.process(img)`
141149

150+
### Basic example with an image source and a pattern marker ( hiro )
151+
142152
```js
143-
<script src="build/artoolkit.min.js"></script>
153+
<script src="../build/artoolkit.min.js"></script>
144154
<script>
145155
var param = new ARCameraParam();
146156

@@ -172,57 +182,47 @@ The basic operation goes like this:
172182
</script>
173183
```
174184

175-
## Public
176-
177-
*the calls your JS apps needs*
178-
179-
- `artoolkit.init(path, camera_param_path)` - load path for artoolkit emscripten files
180-
- `artoolkit.onReady(callback)` - runs callback when artoolkit has completely downloaded, initalized and ready to run
181-
- `artoolkit.setup(width, height);` - initalize a buffer size for a canvas of width & height
182-
- `artoolkit.process(canvas);` - extracts a frame from a canvas and process it
183-
- `artoolkit.debugSetup()` - enables debugging, adds a threshold image to the dom
184-
- `artoolkit.getDetectedMarkers()` - returns an array of detected markers from last detection process
185-
- `artoolkit.getCameraMatrix()` - returns the projection matrix computed from camera parameters
186-
- `artoolkit.getTransformationMatrix()` - returns the 16-element WebGL transformation matrix
187-
188-
## Internals
185+
### Basic example with a worker and a NFT marker
189186

190-
*calls called from emscripten runtime -> artoolkit.js*
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).
191188

192-
- `artoolkit.onFrameMalloc(object)` - gets called when frame buffer gets allocated for canvas
193-
- `artoolkit.onMarkerNum(number)` - gets called with the numbers of markers detected
194-
- `artoolkit.onGetMarker(object, index)` - gets called with the marker struct for the positioned marker
189+
In the code below a summarized example:
195190

196-
*calls available from js -> emscripten*
197191

198-
- `_setup(width, height)`
199-
- `_setThreshold(int)` - 0 to 255
200-
- `_process()`
201-
- `_setDebugMode(boolean)`
202-
- `_addMarker(string)`
203-
- `setThreshold`
204-
- `setThresholdMode()` eg. `Module.setThresholdMode(Module.AR_LABELING_THRESH_MODE_AUTO_MEDIAN / AR_LABELING_THRESH_MODE_AUTO_OTSU );
205-
- `setLabelingMode`
206-
- `setPatternDetectionMode`
207-
- `setMatrixCodeType()` : Eg. Module.setMatrixCodeType(Module.AR_MATRIX_CODE_3x3);
208-
- `setImageProcMode`
209-
- `setPattRatio`
210-
211-
## Examples
212-
213-
```
214-
artoolkit.init('', 'camera_para.dat').onReady(function() {
215-
artoolkit.setProjectionNearPlane(1);
216-
artoolkit.setProjectionFarPlane(1000);
217-
artoolkit.setPatternDetectionMode(artoolkit.CONSTANTS.AR_MATRIX_CODE_DETECTION);
218-
artoolkit.setMatrixCodeType(artoolkit.CONSTANTS.AR_MATRIX_CODE_4x4);
219-
})
220-
221-
artoolkit.init('', 'camera_para.dat').onReady(function() {
222-
artoolkit.addMarker('../bin/Data/patt.hiro', function(marker) {
223-
artoolkit.process(v);
224-
})
225-
})
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>
226226
```
227227
228228
## Constants
@@ -273,3 +273,33 @@ artoolkit.process(v);
273273
- AR_MARKER_INFO_CUTOFF_PHASE_POSE_ERROR_MULTI
274274
- AR_MARKER_INFO_CUTOFF_PHASE_HEURISTIC_TROUBLESOME_MATRIX_CODES
275275
```
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)

js/artoolkit.api.js

Lines changed: 67 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -363,7 +363,10 @@
363363
this.debugDraw();
364364
}
365365
};
366-
366+
/**
367+
Detects the NFT markers in the process() function,
368+
with the given tracked id.
369+
*/
367370
ARController.prototype.detectNFTMarker = function () {
368371
artoolkit.detectNFTMarker(this.id);
369372
}
@@ -822,7 +825,18 @@
822825
return artoolkit.markerInfo;
823826
}
824827
};
828+
/**
829+
Get the NFT marker info struct for the given NFT marker index in detected markers.
830+
The returned object is the global artoolkit.NFTMarkerInfo object and will be overwritten
831+
by subsequent calls.
832+
833+
Returns undefined if no marker was found.
834+
835+
A markerIndex of -1 is used to access the global custom marker.
825836
837+
@param {number} markerIndex The index of the NFT marker to query.
838+
@returns {Object} The NFTmarkerInfo struct.
839+
*/
826840
ARController.prototype.getNFTMarker = function (markerIndex) {
827841
if (0 === artoolkit.getNFTMarker(this.id, markerIndex)) {
828842
return artoolkit.NFTMarkerInfo;
@@ -951,32 +965,64 @@
951965
/**
952966
Sets the logging level to use by ARToolKit.
953967
954-
@param
968+
@param {number} mode type for the log level.
955969
*/
956970
ARController.prototype.setLogLevel = function (mode) {
957971
return artoolkit.setLogLevel(mode);
958972
};
959973

974+
/**
975+
Gets the logging level used by ARToolKit.
976+
@return {number} return the log level in use.
977+
*/
960978
ARController.prototype.getLogLevel = function () {
961979
return artoolkit.getLogLevel();
962980
};
963981

982+
/**
983+
Sets the dir (direction) of the marker. Direction that tells about the rotation
984+
about the marker (possible values are 0, 1, 2 or 3).
985+
This parameter makes it possible to tell about the line order of the detected marker
986+
(so which line is the first one) and so find the first vertex.
987+
This is important to compute the transformation matrix in arGetTransMat().
988+
@param {number} markerIndex the index of the marker
989+
@param {number} dir direction of the marker (possible values are 0, 1, 2 or 3).
990+
@return {number} 0 (void)
991+
*/
964992
ARController.prototype.setMarkerInfoDir = function (markerIndex, dir) {
965993
return artoolkit.setMarkerInfoDir(this.id, markerIndex, dir);
966994
};
967995

996+
/**
997+
Sets the value of the near plane of the camera.
998+
@param {number} value the value of the near plane
999+
@return {number} 0 (void)
1000+
*/
9681001
ARController.prototype.setProjectionNearPlane = function (value) {
9691002
return artoolkit.setProjectionNearPlane(this.id, value);
9701003
};
9711004

1005+
/**
1006+
Gets the value of the near plane of the camera with the give id.
1007+
@return {number} the value of the near plane.
1008+
*/
9721009
ARController.prototype.getProjectionNearPlane = function () {
9731010
return artoolkit.getProjectionNearPlane(this.id);
9741011
};
9751012

1013+
/**
1014+
Sets the value of the far plane of the camera.
1015+
@param {number} value the value of the far plane
1016+
@return {number} 0 (void)
1017+
*/
9761018
ARController.prototype.setProjectionFarPlane = function (value) {
9771019
return artoolkit.setProjectionFarPlane(this.id, value);
9781020
};
9791021

1022+
/**
1023+
Gets the value of the far plane of the camera with the give id.
1024+
@return {number} the value of the far plane.
1025+
*/
9801026
ARController.prototype.getProjectionFarPlane = function () {
9811027
return artoolkit.getProjectionFarPlane(this.id);
9821028
};
@@ -1212,6 +1258,7 @@
12121258
Draw the black and white image and debug markers to the ARController canvas.
12131259
12141260
See setDebugMode.
1261+
@return 0 (void)
12151262
*/
12161263
ARController.prototype.debugDraw = function () {
12171264
var debugBuffer = new Uint8ClampedArray(Module.HEAPU8.buffer, this._bwpointer, this.framesize);
@@ -1243,6 +1290,11 @@
12431290

12441291
// private methods
12451292

1293+
/**
1294+
This function init the ArController with the necessary parmeters and variables.
1295+
Don't call directly this but instead instantiate a new ArController.
1296+
@return {number} 0 (void)
1297+
*/
12461298
ARController.prototype._initialize = function () {
12471299
this.id = artoolkit.setup(this.width, this.height, this.cameraParam.id);
12481300

@@ -1273,10 +1325,18 @@
12731325
}.bind(this), 1);
12741326
};
12751327

1328+
/**
1329+
Init the necessary kpm handle for NFT and the settings for the CPU.
1330+
@return {number} 0 (void)
1331+
*/
12761332
ARController.prototype._initNFT = function () {
12771333
artoolkit.setupAR2(this.id);
12781334
};
12791335

1336+
/**
1337+
Copy the Image data to the HEAP for the debugSetup function.
1338+
@return {number} 0 (void)
1339+
*/
12801340
ARController.prototype._copyImageToHeap = function (image) {
12811341
if (!image) {
12821342
image = this.image;
@@ -1322,7 +1382,11 @@
13221382
return false;
13231383
};
13241384

1325-
1385+
/**
1386+
Draw a square black border around the detect marker with
1387+
red circle in the center. Used for debugging porpouse in debugSetup.
1388+
@return {number} 0 (void)
1389+
*/
13261390
ARController.prototype._debugMarker = function (marker) {
13271391
var vertex, pos;
13281392
vertex = marker.vertex;

0 commit comments

Comments
 (0)