Quickstart

Overview

Occupancy Heatmap is a reference workflow or application for video analytics that provide insights about space occupancy & people movement patterns. By observing people movement over a period of time, the application is able to identify hot spots and visually show the historical distribution of objects. These insights can be extremely valuable in many settings such as a retail stores, shopping malls, museums, etc.,

The heatmap is generated by a standalone Heatmap Overlay microservice, which is provided as a Docker container to the user. The microservice consumes input video, video metadata and the calibration file and produces an annotated video. Here is a graphical representation of the microservice’s batch process workflow:

Quick Deployment

Deploy

Before starting with the Occupancy Heatmap app, we recommend trying out the other reference apps of Metropolis Microservices first. To download and setup metropolis microservices, refer to the Quickstart Setup section.

To launch the Heatmap app, navigate to the metropolis-apps-standalone-deployment/docker-compose folder and run the command:

$ docker compose -f ./heatmap-app/mdx-heatmap-app.yml --env-file ./foundational/.env up -d --pull always --build --force-recreate

Shutdown

To gracefully stop and shut down all services (if they haven’t already), run the command:

$ docker compose -f ./heatmap-app/mdx-heatmap-app.yml --env-file ./foundational/.env down

Clean up (Optional)

Clean up data logs and images to ensure a clean re-deployment - highly recommended after any configuration or customization.

Clean up existing docker images and all docker cached volumes:

$ docker compose -f ./heatmap-app/mdx-heatmap-app.yml --env-file ./foundational/.env down --volumes --rmi all

Troubleshoot

To troubleshoot issues, developers can start with the FAQs.

Explore the Results

The Heatmap Overlay microservice might take minutes to produce the final video. Once complete, the heatmap can be viewed by playing the output video file created at:

metropolis-apps-data/videos/output_Nth_street_heatmap.mp4

Below is a picture taken from the output video. Regions of in front of the door and the card scanner are colored in red indicating significant people movement in those regions.

Functionality Tutorial Notebook

Explore further the functionalities of the application by applying it to your own videos. Follow the provided Jupyter notebook: metropolis-apps-standalone-deployment/notebooks/heatmap/occupancy-heatmap.ipynb.

Change directory to metropolis-apps-standalone-deployment/notebooks/occupancy-heatmap folder.
Install jupyterlab on your local system. Follow steps mentioned in the getting started page.
Run Jupyter lab:
```
jupyter lab
```
JupyterLab will open automatically in your browser. If not, navigate to http://localhost:8888/lab on your browser.
Open occupancy-heatmap.ipynb and follow through the cells.

Components

For the Occupancy Heatmap reference app, a single component is deployed.

Heatmap Overlay

The Heatmap Overlay component accumulates detected object location over time, creates a Gaussian-smoothed mesh grid using kernel density estimation, and renders the field of view with color indicating the distribution frame by frame.

Input

Video - For this reference app, a single sample video file is directly provided to the Heatmap Overlay microservice.
Sensor Metadata - Sensor metadata is generated by the sensor processing module and stored in ElasticSearch. For the purposes of this demo, a metadata file corresponding to the video is directly used. The metadata has the following format:
{
    "version":"5.0",
    "id":"286045",
    "@timestamp":"2021-09-02T10:08:59.493Z",
    "sensorId":"Camera D5",
    "objects":["10037|1506|801|1620|897|Person"]
}

The Key attributes of the message are:

* `version`: the version of the schema
* `id`: the video frame-ID
* `timestamp`: the the camera timestamp
* `sensorId`: unique sensor-ID
* `objects`: list of objects detected in a video frame, with each object element having a unique object ID, bounding box coordinates and object type.
Calibration File - The calibration file corresponding to a sensor. For details on calibration, refer to the Camera Calibration section.

Note

The heatmap module in V1.0 is case sensitive to detected object class and will only respond to “Person”. Please make sure the object class is “Person” with Upper-cased initial letter in the provided sensor metadata.

Output

Annotated video showing people movement.

Conclusion

Congratulations! You have successfully deployed a key microservice and built an Occupancy Heatmap application.

We encourage you to explore the remaining reference applications that are provided as part of Metropolis Microservices. Below are additional resources:

Quickstart Setup - Guide to deploy all reference applications in the standalone mode via Docker Compose.
Production Deployment Setup - Guide to deploying Metropolis microservices in a Kubernetes environment.
FAQs- A list of commonly asked questions.