Define a 3D AOI as a frame
==========================

When an 3D AOI of the scene contains others coplanar 3D AOI, like a screen with GUI elements displayed on, it is better to described them as 2D AOI inside 2D coordinates system related to the containing 3D AOI.

![3D AOI frame](../../img/aruco_camera_aoi_frame.png)

## Add ArFrame to ArUcoScene

The [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame) class defines a rectangular area where timestamped gaze positions are projected in and inside which they need to be analyzed.

Here is the previous extract where "Screen" AOI is defined as a frame into [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) configuration:

```json
{
    "name": "My FullHD camera",
    "size": [1920, 1080],
    ...
    "scenes": {
        "MyScene" : {
            "aruco_markers_group": {
                ...
            },
            "layers": {
                "MyLayer": {
                    "aoi_scene": {
                        "Sheet": [[14.2, -3, 28.35], [35.2, -3, 28.35], [14.2, -3, -1.35], [35.2, -3, -1.35]],
                        "Screen": [[2.75, 2.9, -0.5], [49.25, 2.9, -0.5], [2.75, 29.1, -0.5], [49.25, 29.1, -0.5]]
                    }
                }
            },
            "frames": {
            	"Screen": {
            		"size": [1920, 1080],
            		"layers": {
            			"MyLayer": {
            				"aoi_scene": {
                                "GeoSector": [[860, 160], [1380, 100], [1660, 400], [1380, 740], [1440, 960], [920, 920], [680, 800], [640, 560]],
                                "LeftPanel": {
                                    "Rectangle": {
                                        "x": 0,
                                        "y": 0,
                                        "width": 350,
                                        "height": 1080
                                    }
                                },
                                "CircularWidget": {
                                    "Circle": {
                                        "cx": 1800,
                                        "cy": 120,
                                        "radius": 80
                                    }
                                }
                            }
            			}
            		}
            	}
            }
        }
    }
    ...
}
```
Now, let's understand the meaning of each JSON entry.

### *frames*

An [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) instance can contains multiples [ArFrames](../../argaze.md/#argaze.ArFeatures.ArFrame) stored by name.

### Screen

The name of a 3D AOI **and** an [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame). Basically useful for visualisation purpose.

!!! warning "AOI / Frame names policy"

    An [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) layer 3D AOI is defined as an [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) frame, **provided they have the same name**.

!!! warning "Layer name policy"

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

!!! note

    [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) frame layers are projected into their dedicated [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) layers when the JSON configuration file is loaded.

## Pipeline execution

### Map ArUcoCamera image into ArUcoScenes frames

After camera image is passed to [ArUcoCamera.watch](../../argaze.md/#argaze.ArFeatures.ArCamera.watch) method, it is possible to apply a perpective transformation in order to project watched image into each [ArUcoScenes](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) [frames background](../../argaze.md/#argaze.ArFeatures.ArFrame) image.

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

# Assuming that the video reading is handled in a looping code block
...:

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

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

    # Map watched image into ArUcoScenes frames background
    aruco_camera.map()
```

### Analyse timestamped gaze positions into ArUcoScenes frames

[ArUcoScenes](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) frames benefits from all the services described in [gaze analysis pipeline section](../gaze_analysis_pipeline/introduction.md).

!!! note

    Timestamped gaze positions passed to [ArUcoCamera.look](../../argaze.md/#argaze.ArFeatures.ArFrame.look) method are projected into [ArUcoScenes](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) frames if applicable.

### Display each ArUcoScenes frames

All [ArUcoScenes](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) frames image can be displayed as any [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame).

```python
    ...

    # Display all ArUcoScenes frames
    for frame in aruco_camera.scene_frames:

        ... frame.image()
```