Load and execute pipeline
=========================

Once [ArUco markers are placed into a scene](aruco_markers_description.md), they can be detected thanks to [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) class.

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

![ArUco camera frame](../../img/aruco_camera_frame.png)

## Load JSON configuration file

An [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) pipeline can be loaded from a JSON configuration file thanks to [argaze.load](../../argaze.md/#argaze.load) package method. 

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

```json
{
	"argaze.ArUcoMarkers.ArUcoCamera.ArUcoCamera": {
		"name": "My FullHD camera",
		"size": [1920, 1080],
		"aruco_detector": {
			"dictionary": "DICT_APRILTAG_16h5"
		},
		"gaze_movement_identifier": {
			"DispersionThresholdIdentification": {
				"deviation_max_threshold": 25,
				"duration_min_threshold": 150
			}
		},
		"image_parameters": {
			"background_weight": 1,
			"draw_detected_markers": {
				"color": [0, 255, 0],
				"draw_axes": {
					"thickness": 3
				}
			},
			"draw_gaze_positions": {
				"color": [0, 255, 255],
				"size": 2
			},
			"draw_fixations": {
				"deviation_circle_color": [255, 0, 255],
				"duration_border_color": [127, 0, 127],
				"duration_factor": 1e-2
			}, 
			"draw_saccades": {
				"line_color": [255, 0, 255]
			}
		}
	}
}
```

Then, here is how to load the JSON file:

```python
import argaze

# Load ArUcoCamera
with argaze.load('./configuration.json') as aruco_camera:

	# Do something with ArUcoCamera
	...
```

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

### *argaze.ArUcoMarkers.ArUcoCamera.ArUcoCamera*

The loaded object class name.

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

The name of the [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) frame. Basically useful for visualization 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.

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

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

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

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

The first [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame) pipeline step dedicated to identify fixations or saccades from consecutive timestamped gaze positions.

![Gaze movement identification](../../img/aruco_camera_gaze_movement_identification.png)

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

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

## Pipeline execution

### Detect ArUco markers, estimate scene pose and project 3D AOI

Pass each camera image to [ArUcoCamera.watch](../../argaze.md/#argaze.ArFeatures.ArCamera.watch) method to execute the whole pipeline dedicated to ArUco markers detection, scene pose estimation and 3D AOI projection.

!!! warning "Mandatory"

	The [ArUcoCamera.watch](../../argaze.md/#argaze.ArFeatures.ArCamera.watch) method must be called from a *try* block to catch pipeline exceptions.

```python
# Assuming that Full HD (1920x1080) timestamped images are available
...:

	try:

		# Detect ArUco markers, estimate scene pose then, project 3D AOI into camera frame
		aruco_camera.watch(image, timestamp=timestamp)

	# Do something with pipeline exception
	except Exception as e:

		...

	# Display ArUcoCamera frame image to display detected ArUco markers, scene pose, 2D AOI projection and ArFrame visualization.
	... aruco_camera.image()
```

### Analyse timestamped gaze positions into camera frame

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

Particularly, timestamped gaze positions can be passed one by one to [ArUcoCamera.look](../../argaze.md/#argaze.ArFeatures.ArFrame.look) method to execute the whole pipeline dedicated to gaze analysis.

!!! warning "Mandatory"

	The [ArUcoCamera.look](../../argaze.md/#argaze.ArFeatures.ArFrame.look) method must be called from a *try* block to catch pipeline exceptions.

```python
# Assuming that timestamped gaze positions are available
...

	try:

		# Look ArUcoCamera frame at a timestamped gaze position
		aruco_camera.look(timestamped_gaze_position)

	# Do something with pipeline exception
	except Exception as e:
		
		...
```

!!! note ""

	At this point, the [ArUcoCamera.watch](../../argaze.md/#argaze.ArFeatures.ArCamera.watch) method only detects ArUco markers and the [ArUcoCamera.look](../../argaze.md/#argaze.ArFeatures.ArCamera.look) method only processes gaze movement identification without any AOI support as no scene description is provided into the JSON configuration file.

	Read the next chapters to learn [how to estimate scene pose](pose_estimation.md), [how to describe 3D scene's AOI](aoi_3d_description.md) and [how to project them into camera frame](aoi_3d_projection.md).