opendatacam

OpenDataCam 3.0.1 – An open source tool to quantify the world

OpenDataCam is an open source tool to quantify the world. It quantifies and tracks moving objects with live video analysis. It is designed to be an accessible, affordable and open-source solution to better understand interactions in urban environments.

OpenDataCam never records any photo or video data. The system only saves surveyed meta-data, in particular the path an object moved or number of counted objects at a certain point. The novelty of OpenDataCam is, that everything happens on location, while no visual data is saved or sent to online cloud processing.

OpenDataCam runs on Linux and CUDA GPU enabled hardware. It is optimized for the NVIDIA Jetson Board series. The most affordable setup runs on a Jetson Nano (low cost, credit-card sized GPU-computer) combined with other other off-the-shelf equipment (webcam, power supply, housing), this entire setup is priced around $150. All software is based on open source components and runs completely locally. The software features a friendly user interface and is currently optimised for detecting and counting traffic participants, but is not limited to that.

Both software and hardware setup are documented and offered as an open source project, to underline transparency and full disclosure on privacy questions. The simple OpenDataCam setup allows everybody to become an urban data miner.

OpenDataCam is very alpha and we do not provide any guarantee that this will work for your use case, but we conceived it as a starting point from where you can build-on & improve.

Until v3.0.0 OpenDataCam has been mainly supported by move lab. OpenDataCam was supported in part by a residency at the Frank-Ratchye STUDIO for Creative Inquiry at Carnegie Mellon University. We are currently looking into potential funding sources to keep pushing the project. If you are interested, please be in touch.

Demo Videos

👉 UI Walkthrough (2 min, OpenDataCam 3.0)	👉 UI Walkthrough (4 min, OpenDataCam 2.0)	👉 IoT Happy Hour #13: OpenDataCam 3.0

Table of content

OpenDataCam 3.0.1 – An open source tool to quantify the world

💻 Hardware pre-requisite

Nvidia Jetson Nano / Xavier NX / Xavier or any GNU/Linux x86_64 machine with a CUDA compatible GPU (Nvidia)
Webcam Logitech C222, C270, C310, C920 / Rasberry Pi cam for Jetson nano / a Video file / IP camera
A smartphone / tablet / laptop that you will use to operate the system

🎬 Get Started, quick setup

For Jetson Nano, you can follow this dedicated quick start guide

1. Software pre-requisite 📦

For Jetson: Flash Jetson board to jetpack 4.3 ⚡️

Jetpack 4.3 : How to find out your jetpack version, Guide to flash your jetson

!!! Warning !!! Note that there is a performance drop if you use Jetpack 4.4 DP (see nvidia forum open issue)

Docker compose (no official installer available for ARM64 devices)

sudo apt install python3-pip

sudo apt-get install -y libffi-dev
sudo apt-get install -y python-openssl
sudo apt-get install libssl-dev

sudo pip3 install docker-compose

For Desktop machine: Nvidia container toolkit 🔧

Docker installed
Docker compose installed
Nvidia drivers installed (you don’t need all CUDA but we didn’t found a easy install process for only the drivers)
Nvidia Container toolkit installed

For desktop there is a workaround to add with docker-compose to give access to the nvidia runtime. At the time of writing this documentation, GPUs for docker-compose aren’t well supported yet, see https://github.com/docker/compose/issues/6691

Open the daemon.json

sudo vim /etc/docker/daemon.json

Copy this inside and save the file

{
    "runtimes": {
        "nvidia": {
            "path": "/usr/bin/nvidia-container-runtime",
            "runtimeArgs": []
        }
    }
}

Restart docker

systemctl restart docker

You also need to install nvidia-container-runtime

sudo apt install nvidia-container-runtime

2. Install and start OpenDataCam 🚀

Open a terminal or ssh to you machine and run the following commands depending on your platform.

The install script will download a docker-compose.yml file and setup a default config.json depending on your platform.

Make sure you have previously installed docker-compose by running docker-compose --version

Install commands:

# Download install script
wget -N https://raw.githubusercontent.com/opendatacam/opendatacam/v3.0.1/docker/install-opendatacam.sh

# Give exec permission
chmod 777 install-opendatacam.sh

# NB: You will be asked for sudo password when installing the docker container
# You might want to stop all docker container running before starting OpenDataCam
# sudo docker stop $(sudo docker ps -aq)

# Install command for Jetson Nano
# NB: Will run from demo file, you can change this after install, see "5. Customize OpenDataCam"
./install-opendatacam.sh --platform nano

# Install command for Jetson Xavier / Xavier NX
# NB: Will run from demo file, you can change this after install, see "5. Customize OpenDataCam"
./install-opendatacam.sh --platform xavier

# Install command for a Desktop machine
# NB: Will run from demo file, you can change this after install, see "5. Customize OpenDataCam"
./install-opendatacam.sh --platform desktop

# Install command for Jetson TX2
# Docker build for Jetson TX2 isn't available please install without docker (see in avanced use)

This command will download and start a docker container on the machine. After it finishes the docker container starts a webserver on port 8080 (ports 8070 and 8090 are also used).

The docker container is started in auto-restart mode, so if you reboot your machine it will automaticaly start opendatacam on startup. (Learn more about the specificities of docker on jetson)

You can also use opendatacam without docker

Kubernetes Install:

If you prefer to deploy OpenDataCam on Kubernetes rather than with Docker Compose, use the --orchestrator flag for changing the engine.

Apart from that, a Kubernetes distribution custom made for the embedded world would be K3s, which can be installed in 30 seconds by running:

curl -sfL https://get.k3s.io | sh -

Then, to automatically download and deploy the services:

# Download install script
wget -N https://raw.githubusercontent.com/opendatacam/opendatacam/master/docker/install-opendatacam.sh

# Give exec permission
chmod 777 install-opendatacam.sh

# Install command for Jetson Nano
./install-opendatacam.sh --platform nano --orchestrator k8s

# Install command for Jetson Xavier / Xavier NX
./install-opendatacam.sh --platform xavier --orchestrator k8s

# Install command for a Desktop machine
./install-opendatacam.sh --platform desktop --orchestrator k8s

Note: NVIDIA offers a Kubernetes device plugin for detecting GPUs on nodes in case you are managing a heterogeneous cluster. Support for Jetson boards is being worked here

balenaCloud Install:

If you have a fleet of one or more devices, you can use balena to streamline deployment and management of OpenDataCam. You can sign up for a free account here and add up to ten devices at no charge. Use the button below to build OpenDataCam for a Jetson Nano, TX2, or Xavier. You can then download an image containing the OS, burn it to an SD card, and use balenaCloud to push OpenDataCam to your devices.

You can learn more about this deployment option along with a step-by-step guide in this recent blog post, or view a screencast of the deployment in action.

(optional) Upgrade OpenDataCam

If you have modified the config.json, save it somewhere
Remove config.json, docker-compose.yml
Run the install steps again (previous section), this will download a new default config.json file compatible with the opendatacam version you are installing and setup a new docker container
Open the newly downloaded config.json script and modify with the things you had changed previously

NB: we do not handle auto update of the config.json file

3. Use OpenDataCam 🖖

Open your browser at http://IPOFJETSON:8080 .

If you are running with the jetson connected to a screen: http://localhost:8080

NB: OpenDataCam only supports one client at a time, if you open the UI on two different devices, the stream will stop in one of them.

See Docker playbook ️📚 how to restart / stop OpenDataCam.

(optional) Run on USB Camera

By default, OpenDataCam will start on a demo file, but if you want to run from an usbcam you should

Verify an USB Camera is connected

ls /dev/video*
# Output should be: /dev/video1

Change "VIDEO_INPUT" in config.json

"VIDEO_INPUT": "usbcam"

Restart docker

sudo docker-compose restart

(optional) Change file

To run on another file, just drag & drop it on the UI

4. Customize OpenDataCam ️️⚙️

We offer several customization options:

Video input: run from a file, change webcam resolution, change camera type (raspberry cam, usb cam…)
Neural network: change YOLO weights files depending on your hardware capacity, desired FPS
Change display classes: We default to mobility classes (car, bus, person…), but you can change this

Learn how to customize OpenDataCam

5. Configure your Wifi hotspot 📲

In order to operate opendatacam from your phone / tablet / computer.

See Make jetson device / machine accessible via WIFI

6. Docker playbook ️📚

How to show OpenDataCam logs

# Go to the directory you ran install script (where is your docker-compose.yml file)

# List containers
sudo docker-compose logs

How to stop / restart OpenDataCam

# Go to the directory you ran install script (where is your docker-compose.yml file)

# Stop container
sudo docker-compose down

# Stop all docker container
sudo docker stop $(sudo docker ps -aq)

# If docker (and opendatacam) doesn't start at startup enable it
sudo systemctl enable docker

# Start container
# detached mode
sudo docker-compose up -d
# interactive mode
sudo docker-compose up

# Restart container (after modifying the config.json file for example)
sudo docker-compose restart

# Install a newer version of opendatacam
# Follow the 1. Install and start OpenDataCam

# See stats ( CPU , memory usage ...)
sudo docker stats opendatacam

# Clear all docker container, images ...
sudo docker system prune -a

# Restart docker
sudo service docker restart

🔌 API Documentation

In order to solve use cases that aren’t taken care by our opendatacam base app, you might be able to build on top of our API instead of forking the project.

https://opendatacam.github.io/opendatacam/apidoc/