Project 3D AOI in the camera frame
================================

Once the [ArUcoScene pose is estimated](pose_estimation.md) and [3D AOI are described](aoi_3d_description.md), they can be projected in the [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) frame.

![3D AOI projection](../../img/aruco_camera_aoi_projection.png)

## Add ArLayer to ArUcoScene to load 3D AOI

The [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer) class allows you to load 3D AOI descriptions. 

Here is the previous extract, where one layer is added to [ArUcoScene](../../argaze.md/#argaze.ArUcoMarker.ArUcoScene) configuration:

```json
{
    "argaze.ArUcoMarker.ArUcoCamera.ArUcoCamera": {
        "name": "My FullHD camera",
        "size": [1920, 1080],
        ...
        "scenes": {
            "MyScene" : {
                "aruco_markers_group": {
                    ...
                },
                "layers": {
                    "MyLayer": {
                        "aoi_scene": {
                            "Left_Screen": [[0, 0, 0], [15, 0, 0], [0, 18.963333, -6.355470], [15, 18.963333, -6.355470]],
                            "Right_Screen": [[20, 0, 0], [35, 0, 0], [20, 18.963337, -6.355472], [35, 18.963337, -6.355472]],
                            "Control_Panel": [[49.5, 30, 18.333333], [55.5, 30, 18.333333], [49.5, 38, 18.333333], [55.5, 38, 18.333333]],
                            "Window": [[-57.8, 5.5, -33.5], [46, 15.5, -35], [1.5, 53, -1], [50.2, 61, 6], [-35.85, 35, -15]]
                        }
                    }
                } 
            }
        }
        ...
    }
}
```

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

### *layers*

An [ArUcoScene](../../argaze.md/#argaze.ArUcoMarker.ArUcoScene) instance can contain multiples [ArLayers](../../argaze.md/#argaze.ArFeatures.ArLayer) stored by name.

### MyLayer

The name of an [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer). Basically, it is useful for visualization purposes.

### *aoi_scene*

The set of 3D AOI into the layer, as defined in the [3D AOI description chapter](aoi_3d_description.md).

## Add ArLayer to ArUcoCamera to project 3D AOI into

Here is the previous extract, where one layer is added to the [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) configuration and displayed:

```json
{
    "argaze.ArUcoMarker.ArUcoCamera.ArUcoCamera": {
        "name": "My FullHD camera",
        "size": [1920, 1080],
        ...
        "scenes": {
            "MyScene" : {
                "aruco_markers_group": {
                    ...
                },
                "layers": {
                     "MyLayer": {
                        "aoi_scene": {
                            ...
                        }
                    } 
                } 
            }
        },
        "layers": {
            "MyLayer": {}
        }
        ...
        "image_parameters": {
            ...
            "draw_layers": {
                "MyLayer": {
                    "draw_aoi_scene": {
                        "draw_aoi": {
                            "color": [255, 255, 255],
                            "border_size": 1
                        }
                    }
                }
            }
        }
    }
}
```

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

### *layers*

An [ArUcoCamera](../../argaze.md/#argaze.ArFeatures.ArFrame) instance can contain multiples [ArLayers](../../argaze.md/#argaze.ArFeatures.ArLayer) stored by name.

### MyLayer

The name of an [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer). Basically, it is useful for visualization purposes.

!!! warning "Layer name policy"

    An [ArUcoScene](../../argaze.md/#argaze.ArUcoMarker.ArUcoScene) layer is projected into an [ ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) layer, **provided they have the same name**.

!!! note

    [ArUcoScene](../../argaze.md/#argaze.ArUcoMarker.ArUcoScene) layers are projected into their dedicated [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) layers when calling the [ArUcoCamera.watch](../../argaze.md/#argaze.ArFeatures.ArCamera.watch) method.

## Add AOI analysis features to ArUcoCamera layer

When a scene layer is projected into a camera layer, it means that the 3D scene's AOI are transformed into the 2D camera's AOI.

Therefore, it means that [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) benefits from all the services described in the [AOI analysis pipeline section](../gaze_analysis_pipeline/aoi_analysis.md).

Here is the previous extract, where AOI matcher, AOI scan path and AOI scan path analyzers were added to the [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) layer:

```json
{
    "argaze.ArUcoMarker.ArUcoCamera.ArUcoCamera": {
        "name": "My FullHD camera",
        "size": [1920, 1080],
        ...
        "scenes": {
            "MyScene" : {
                "aruco_markers_group": {
                    ...
                },
                "layers": {
                     "MyLayer": {
                        "aoi_scene": {
                            ...
                        }
                    } 
                } 
            }
        },
        "layers": {
            "MyLayer": {
                "aoi_matcher": {
                    "argaze.GazeAnalysis.DeviationCircleCoverage.AOIMatcher": {
                        "coverage_threshold": 0.5
                    }
                },
                "aoi_scan_path": {
                    "duration_max": 30000
                },
                "aoi_scan_path_analyzers": {
                    "argaze.GazeAnalysis.Basic.AOIScanPathAnalyzer": {},
                    "argaze.GazeAnalysis.TransitionMatrix.AOIScanPathAnalyzer": {},
                    "argaze.GazeAnalysis.NGram.AOIScanPathAnalyzer": {
                        "n_min": 3,
                        "n_max": 5
                    }
                }
            }
        }
        ...
    }
}
```

!!! warning

    Adding scan path and scan path analyzers to an [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) layer doesn't make sense, as the space viewed through the camera frame doesn't have to reflect the space the gaze is covering.