Configure and execute ArUcoCamera
=================================

Once [ArUco markers are placed into a scene](aruco_markers_description.md) and [areas of interest are described](aoi_description.md), everything is ready to setup an ArUco marker pipeline thanks to [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) class.

As it inherits from [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame), the [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) class benefits from all the services described in [gaze analysis pipeline section](./user_guide/gaze_analysis_pipeline/introduction.md).

![ArUco camera markers detection](../../img/aruco_camera_markers_detection.png)

## Load JSON configuration file

The [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) internal pipeline loads from a JSON configuration file thanks to [ArUcoCamera.from_json](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera.from_json) class method. 

Here is a simple JSON [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) configuration file example:

```json
{
	"name": "My FullHD camera",
	"size": [1920, 1080],
	"aruco_detector": {
        "dictionary": "DICT_APRILTAG_16h5",
        "marker_size": 5
    },
    "image_parameters": {
        "background_weight": 1,
        ...
        "draw_detected_markers": {
            "color": [0, 255, 0],
            "draw_axes": {
                "thickness": 3
            }
        }
    }
}
```

Then, here is how to load the JSON file:

```python
from argaze.ArUcoMarkers import ArUcoCamera

# Load ArUcoCamera
aruco_camera = ArUcoCamera.ArUcoCamera.from_json('./configuration.json')
```

Now, let's understand the meaning of each JSON entry.

### Name - *inherited from [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame)*

The name of the [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) frame. Basically useful for visualisation purpose.

### Size - *inherited from [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame)*

The size of the [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) frame  in pixels. Be aware that gaze positions have to be in the same range of value to be projected in.

### ArUco Detector

The first [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) pipeline step is to detect ArUco markers inside input image and estimate their poses.

The [ArUcoDetector](../../argaze.md/#argaze.ArUcoMarkers.ArUcoDetector) is in charge to detect all markers from a specific dictionary with a given size in centimeters.

!!! warning
    JSON *aruco_detector* entry is mandatory.

### Image parameters - *inherited from [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame)*

The usual [ArFrame visualisation parameters](./user_guide/gaze_analysis_pipeline/visualisation.md) plus one additional *draw_detected_markers* field.

## Pipeline execution

Pass each camera image to [ArUcoCamera.watch](../../argaze.md/#argaze.ArFeatures.ArCamera.watch) method to execute the whole intanciated pipeline.

```python
# Assuming that Full HD (1920x1080) video stream or file is opened
...

# Assuming there is a way to escape the while loop
while ...:

    # Capture image from video stream of file
    image = video_capture.read()

    # Detect ArUco markers and more...
    aruco_camera.watch(image)

    # Display ArUcoCamera frame image to check that ArUco markers are well detected and scene is well projected
    ... aruco_camera.image()
```

!!! warning
    ArUco markers pose estimation algorithm can lead to errors due to geometric ambiguities as explain in [this article](https://ieeexplore.ieee.org/document/1717461). To discard such ambiguous cases, markers should **not be parallel to camera plan**.

At this point, the [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) only detects ArUco markers as no scene description is provided.