Set up ArUco markers
====================

First of all, ArUco markers needs to be printed and placed into the scene. 

Here is an example scene where markers are surrounding a workspace with a screen and a sheet on the table.

![Scene](../../img/scene.png)

## Print ArUco markers from an ArUco dictionary

ArUco markers always belongs to a set of markers called ArUco markers dictionary.

![ArUco dictionaries](../../img/aruco_dictionaries.png)

Many ArUco dictionaries exist with properties concerning the format, the number of markers or the difference between each markers to avoid error in tracking.

Here is the documention [about ArUco markers dictionaries](https://docs.opencv.org/3.4/d9/d6a/group__aruco.html#gac84398a9ed9dd01306592dd616c2c975).

The creation of [ArUcoMarkers](../../argaze.md/#argaze.ArUcoMarkers.ArUcoMarker) pictures from a dictionary is illustrated in the code below:
 
``` python
from argaze.ArUcoMarkers import ArUcoMarkersDictionary

# Create a dictionary of specific April tags
aruco_dictionary = ArUcoMarkersDictionary.ArUcoMarkersDictionary('DICT_APRILTAG_16h5')

# Export marker n°5 as 3.5 cm picture with 300 dpi resolution
aruco_dictionary.create_marker(5, 3.5).save('./markers/', 300)

# Export all dictionary markers as 3.5 cm pictures with 300 dpi resolution
aruco_dictionary.save('./markers/', 3.5, 300)
```

!!! note
      There is **A4_DICT_APRILTAG_16h5_5cm_0-7.pdf** file located in *./src/argaze/ArUcoMarkers/utils/* folder ready to be printed on A4 paper sheet.

Let's print some of them before to go further.

!!! warning
	Print markers with a blank zone around them to help in their detection.

## Describe ArUco markers place

Once [ArUcoMarkers](../../argaze.md/#argaze.ArUcoMarkers.ArUcoMarker) pictures are placed into a scene it is possible to describe their 3D places into a file.

![ArUco markers description](../../img/aruco_markers_description.png)

Where ever the origin point is, all markers places need to be described in a [right-handed 3D axis](https://robotacademy.net.au/lesson/right-handed-3d-coordinate-frame/) where:

* +X is pointing to the right,
* +Y is pointing to the top,
* +Z is pointing to the backward.

!!! warning
	All ArUco markers spatial values must be given in **centimeters**.

### Edit OBJ file description

OBJ file format could be exported from most 3D editors.

``` obj
o DICT_APRILTAG_16h5#0_Marker
v 0.000000 0.000000 0.000000
v 5.000000 0.000000 0.000000
v 0.000000 5.000000 0.000000
v 5.000000 5.000000 0.000000
vn 0.0000 0.0000 1.0000
s off
f 1//1 2//1 4//1 3//1
o DICT_APRILTAG_16h5#1_Marker
v -0.855050 24.000002 4.349232
v 0.855050 24.000002 -0.349231
v -0.855050 29.000002 4.349232
v 0.855050 29.000002 -0.349231
vn 0.9397 0.0000 0.3420
s off
f 5//2 6//2 8//2 7//2
o DICT_APRILTAG_16h5#2_Marker
v 44.000000 0.000000 9.500000
v 49.000000 0.000000 9.500000
v 44.000000 -0.000000 4.500000
v 49.000000 -0.000000 4.500000
vn 0.0000 1.0000 -0.0000
s off
f 9//3 10//3 12//3 11//3
```

Here are common OBJ file features needed to describe ArUco markers places:  

* Object lines (starting with *o* key) indicate markers dictionary and id by following this format: **DICTIONARY**#**ID**\_Marker.
* Vertice lines (starting with *v* key) indicate markers corners. The marker size will be automatically deducted from the geometry.
* Plane normals (starting with *vn* key) need to be exported for further pose estimation.
* Face (starting with *f* key) link vertices and normals indexes together.

!!! warning
	All markers must have the same size and belong to the same dictionary.

### Edit JSON file description

JSON file format allows to describe markers places using translation and euler angle rotation vectors.

``` json
{
    "dictionary": "DICT_APRILTAG_16h5",
    "marker_size": 5,
    "places": {
        "0": {
            "translation": [2.5, 2.5, 0],
            "rotation": [0, 0, 0]
        },
        "1": {
            "translation": [0, 26.5, 2],
            "rotation": [0, 70, 0]
        },
        "2": {
            "translation": [46.5, 0, 7],
            "rotation": [-90, 0, 0]
        }
    }
}
```