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 two screens, a control panel and a window.

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

## Print ArUco markers from an ArUco dictionary

ArUco markers always belong to a set of markers called the ArUco marker dictionary.

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

Many ArUco marker dictionaries exist with properties concerning the format, the number of markers, or the difference between each marker to avoid errors 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 [ArUcoMarker](../../argaze.md/#argaze.ArUcoMarker.ArUcoMarker) pictures from a dictionary is illustrated in the code below:
 
```python
from argaze.ArUcoMarker import ArUcoMarkerDictionary

# Create a dictionary of specific April tags
aruco_dictionary = ArUcoMarkerDictionary.ArUcoMarkerDictionary('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 an **A4_DICT_APRILTAG_16h5_5cm_0-7.pdf** file located in *./src/argaze/ArUcoMarker/utils/* folder ready to be printed on an A4 paper sheet.

Let's print some of them before going further.

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

## Describe ArUco markers place

Once [ArUcoMarker](../../argaze.md/#argaze.ArUcoMarker.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)

Wherever the origin point is, all markers places need to be described on 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

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

``` obj
o DICT_APRILTAG_16h5#0_Marker
v 15.000000 0.378741 0.330527
v 20.000000 0.378741 0.330527
v 15.000000 5.120359 -1.255996
v 20.000000 5.120359 -1.255996
f 1 2 4 3
o DICT_APRILTAG_16h5#1_Marker
v 43.500000 31.428055 18.333317
v 48.500000 31.428055 18.333317
v 43.500000 36.428055 18.333317
v 48.500000 36.428055 18.333317
f 5 6 8 7
o DICT_APRILTAG_16h5#2_Marker
v 38.500000 2.678055 5.498381
v 43.500000 2.678055 5.498381
v 38.500000 5.178055 1.168253
v 43.500000 5.178055 1.168253
f 9 10 12 11
```

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

* Object line (starting with the *o* key) indicates marker dictionary and id by following this format: **DICTIONARY**#**ID**\_Marker.
* Vertice line (starting with the *v* key) indicates marker corners. The marker size will be automatically deducted from the geometry.
* Face line (starting with the *f* key) links vertice and normal indexes together.

!!! warning
	Markers have to belong to the same dictionary.

!!! note
    Markers can have different sizes.

### Edit JSON file description

the JSON file format allows for the description of marker places using translation and Euler angle rotation vectors.

``` json
{
    "dictionary": "DICT_APRILTAG_16h5",
    "places": {
        "0": {
            "translation": [17.5, 2.75, -0.5],
            "rotation": [-18.5, 0, 0],
            "size": 5
        },
        "1": {
            "translation": [46, 34, 18.333],
            "rotation": [0, 70, 0],
            "size": 5
        },
        "2": {
            "translation": [41, 4, 3.333],
            "rotation": [-60, 0, 0],
            "size": 5
        }
    }
}
```