Engagement Analytics Usage Instructions

engagement-analytics service 0.1.0

Engagement Analytics Service is in charge of managing engagement statistics. It reads detection/direction messages from Redis and based on the given configuration it calculates the person engagement and then posts statistics in both Redis and InfluxDB.

The detection/direction messages use the DirectionSchemaGenerator from rrms-utils and are expected to have the following format:

{
    "id": 1,
    "cameraid": "cam1",
    "timestamp": "2025-01-01T00:00:00Z",
    "width": 1920,
    "height": 1080,
    "detections": [
        {
            "objectid": "object1",
            "position": {
                "x": 10,
                "y": 20
            },
            "direction": {
                "x": 1,
                "y": 0
            }
        }
    ]
}

The generated statistics are sent through Redis or stored in a database using InfluxDB, below you can find the descriptions of the statistics for each case:

Redis:
- Engagement: This is a redis message with key <personid>:engagement and content {engaged:<int 0/1 indicating if the person is engaged>, engagement:<engagement in seconds>,"last-seen":<time when the person was last seen>}. The messages are posted in redis with an expiration time so they will disappear if not updated (the person hasn’t been seen) for the given time.
- Heatmap: Heatmap of engaged people over a configrable period of time. This message uses the HeatmapSchemaGenerator from rrms-utils and has the following format: "heatmap":[{"position":{"x":int, "y": int}, "intensity":float, "radius": int}, {"position":{"x":int, "y": int}, "intensity":float, "radius": int}, ...]
InfluxDB: InfluxDB is used for the data monitoring service so here is where the monitored statistics are posted. All influx data is stored in a bucket called jetson_metrics in Ridgerun organization. The following data is stored:
- engagement_metrics: This is a measurement used to store the following engagement related metrics:
  - detected_people: The amount of people that has been detected.
  - total_engaged_people: The amount of people that has been engaged.
  - total_engagement: The total amount of engagement in seconds.
  - total_seconds: The amount of seconds the service has been running collecting statistics.
- Engaged persons: This measurement is used to report the amount of persons engaged per hour. It used the following field: {persons: <number of persons>}
- Engagement: This measurement is used to report 2 statistics using 2 different tags: average to report the average engagement and by hour to report the engagement per hour. The engagement is reported in a a filed {engagement: <engagement time in seconds>}
- Real Time: This measurement is used to report real time data. The data is collected in a window of time equals to db_update_period. It has the following fields:
  - detected_people: Amount of unique persons detected in the time window.
  - engaged_people: Amount of people engaged in the time window.
  - engagement_time: The total engagement time in the time window. This is, the sum of the engagement time of all the engaged people.
  - person_id: This field is used to report the detected IDs. It is sent with the detections tag if it is a regular detection (not engaged) and with the engaged tag if the id is engaged.

Service Configuration

The service is configured via a configuration file with the following content:

{
    "heatmap": {
        "window_seconds": 3600,
        "eps": 40,
        "min_samples": 2,
        "update_period": 10
    },
    "engagement": [
        {
            "id": "cam0",
            "roi": [
                {
                    "x": 0,
                    "y": 1079
                },
                {
                    "x": 1919,
                    "y": 1079
                }
            ]
        },
        {
            "id": "cam1",
            "roi": [
                {
                    "x": 0,
                    "y": 1079
                },
                {
                    "x": 1919,
                    "y": 1079
                }
            ]
        }
    ],
    "db_update_period": 5,
    "message_expiration": 5
}

heatmap: This is the configuration for the heatmap generation.
- window_seconds: This is the window of time that will be used for the heatmap generation. Any sample older than this time will be discarded.
- eps: This is the maximum distance between 2 samples to be considered part of the same group.
- min_samples: This is the minimum number of samples in a group to be considered. Any group with less that this number of samples will be discarded.
- update_period: This is the period used to generate and update the heatmap. Data will be constantly collected but the heatmap will be calculated and posted in redis with this period in seconds.
engagement: This is the data for engagement calculation. It is an array with one element per camera.
- id: The id of the camera.
- roi: This is the target region for the engagement. Any person whose direction points to this defined region is considered to be engaged. It supports 1 or 2 points. In case of one point, the person is considered to be engaged if it is looking at that point. In case of 2 points, the person is considered to be engaged if it is looking at the rect defined by the 2 points.
db_update_period: This is the period of time used to update the influx database with statistics.
message_expiration: This is the amount of seconds used for engagement messages expiration. If a person is not seen for this configured amount of time, the entry will automatically disappear from redis.

Running the service

The project is configured (via setup.py) to install the service with the name analytics. So to install it run:

pip install .

Then you will have the service with the following options:

engagement-analytics --help
usage: engagement-analytics [-h] [--port PORT] [--host HOST] --config-file CONFIG_FILE [--retry]

optional arguments:
  -h, --help            show this help message and exit
  --port PORT           Port for server
  --host HOST           Server ip address
  --config-file CONFIG_FILE
                        Configuration JSON file
  --retry               Keep trying to start the server if it fails initially

To start the service in address 127.0.0.1 and port 5053 just run:

enagagement-analytics --config-file <path to configuraiton file> --retry

Docker support

Building the docker image

You can build the service docker image using the Dockerfile in the docker directory. First, we need to prepare a context directory for this build, you need to create a directory and include this repository and the rrms-utils project. The Dockerfile will look for both packages in the context directory and will copy them to the container. The context directory should look like this:

docker/context/
├── engagement-analytics
└── rrms-utils

Make sure the Dockerfile is in the same directory as your context. it should look like this:

docker
├── context
│   ├── engagement-analytics
│   └── rrms-utils
└── Dockerfile

Then, in order to build the image, from the directory containing the Dockerfile and your context run:

docker build --network=host --tag ridgerun/engagement-analytics-service -f Dockerfile context/

NOTE: Change context with the name you gave to your context directory.

Running the docker container

Once the docker image was created, you can run the service container with the following command:

docker run -it --rm \
--network host \
--volume <path to directory containing your configuration file>:/configs \
-e INFLUXDB_TOKEN=<your influx db token> \
--name engagement-analytics-service  \
ridgerun/engagement-analytics-service:latest  \
--host 0.0.0.0 \
--config-file /configs/<your configuration file name> \
--retry

NOTE: Make sure to use the proper configuration path and file name.

This will start the service in a docker container called engagement-analytics-service.