Add an ArUcoScene
=================

An [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) class defines a space where [areas of interest description](aoi_description.md) is mapped onto [ArUco markers description](aruco_markers_description.md).

![ArUco scene](../../img/aruco_scene.png)

## Add ArUcoScene to ArUcoCamera JSON configuration file

An [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) instance can contains multiples [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene).

Here is an extract from the JSON [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) configuration file with a sample where one scene is added:

```json
{
	"name": "My FullHD camera",
	"size": [1920, 1080],
	...
    "scenes": {
        "MyScene" : {
            "aruco_markers_group": {
                "dictionary": "DICT_APRILTAG_16h5",
                "marker_size": 5,
                "places": {
                    "0": {
                        "translation": [2.5, 2.5, 0],
                        "rotation": [0, 0, 0]
                    },
                    "1": {
                        "translation": [0, 25.5, 2],
                        "rotation": [0, 45, 0]
                    },
                    "2": {
                        "translation": [35.5, 0, 3],
                        "rotation": [-45, 0, 0]
                    }
                }
            } 
        }
    }
    ...
}
```

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

### "MyScene"

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

### ArUco markers group

The 3D places of ArUco markers into the scene as defined at [ArUco markers description chapter](aruco_markers_description.md). Thanks to this description, it is possible to estimate the pose of [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) in [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) frame.

!!! note

    [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) pose estimation is done when calling the [ArUcoCamera.watch](../../argaze.md/#argaze.ArFeatures.ArCamera.watch) method.

## Add ArLayer to ArUcoScene to load AOI

The [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer) class allows to load areas of interest description. An [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) instance can contains multiples [ArLayers](../../argaze.md/#argaze.ArFeatures.ArLayer).

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

```json
{
    "name": "My FullHD camera",
    "size": [1920, 1080],
    ...
    "scenes": {
        "MyScene" : {
            "aruco_markers_group": {
                ...
            },
            "layers": {
                "MyLayer": {
                    "aoi_scene": {
                        "YellowSquare": [[6.2, -7.275252, 25.246159], [31.2, -7.275252, 25.246159], [31.2, 1.275252, 1.753843], [6.2, 1.275252, 1.753843]],
                        "GrayRectangle": [[2.5, 2.5, -0.5], [37.5, 2.5, -0.5], [37.5, 27.5, -0.5], [2.5, 27.5, -0.5]],
                        "BlueTriangle": [[12.5, 7.5, -0.5], [27.5, 7.5, -0.5], [20, 22.5, -0.5]]
                    }
                }
            } 
        }
    }
    ...
}
```

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

### "MyLayer"

The name of the [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer). Basically useful for visualisation purpose.

### AOI Scene

The [AOIScene](../../argaze.md/#argaze.AreaOfInterest.AOIFeatures.AOIScene) defines a set of 3D [AreaOfInterest](../../argaze.md/#argaze.AreaOfInterest.AOIFeatures.AreaOfInterest) registered by name.

## Add ArLayer to ArUcoCamera to project AOI

Here is the previous extract where one layer is added to the [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera):

```json
{
    "name": "My FullHD camera",
    "size": [1920, 1080],
    ...
    "scenes": {
        "MyScene" : {
            "aruco_markers_group": {
                ...
            },
            "layers": {
                 "MyLayer": {
                    "aoi_scene": {
                        ...
                    }
                } 
            } 
        }
    },
    "layers": {
        "MyLayer": {
            "aoi_matcher": {
                ...
            },
            "aoi_scan_path": {
                "duration_max": 30000
            },
            "aoi_scan_path_analyzers": {
                ...
            }
        }
    }
    ...
}
```

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

### "MyLayer"

The name of the [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer). Basically useful for visualisation purpose.

!!! warning

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

!!! note

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

## Add GazeMovementIdentifier to ArUcocamera to enable gaze movement identification

Here is the previous extract where gaze movement identifier is added to the [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera):

```json
{
    "name": "My FullHD camera",
    "size": [1920, 1080],
    ...
    "scenes": {
        "MyScene" : {
            "aruco_markers_group": {
                ...
            },
            "layers": {
                 "MyLayer": {
                    "aoi_scene": {
                        ...
                    }
                } 
            } 
        }
    },
    "layers": {
        "MyLayer": {}
    },
    "gaze_movement_identifier": {
        "DispersionThresholdIdentification": {
            "deviation_max_threshold": 50,
            "duration_min_threshold": 200
        }
    }
    ...
}
```
!!! note

    Timestamped gaze positions are [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) layers execution is done when calling the [ArUcoCamera.look](../../argaze.md/#argaze.ArFeatures.ArCamera.look) method.

## Add AOIMatcher, AOIScanPath and AOIScanPathAnalyzers to ArUcoCamera layer to enable gaze analysis

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

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

!!! warning

    Adding scan path and scan path analyzers to [an ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) layer doesn't make sense if the camera is moving.