Skip to content
master
Switch branches/tags
Code

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
Oct 15, 2019
Aug 27, 2021
Aug 27, 2021

OpenDataCam 3.0.2 – 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
OpenDataCam 3.0 Demo OpenDataCam IoT

Table of content

💻 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 ⚡️

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

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 🔧

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.2/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/

🗃 Data export documentation

⁉️ Troubleshooting

Common errors with answers

🎛 Advanced uses

How to use opendatacam without docker

Read How to use opendatacam without docker

How to create / update the docker image

We host our docker images on Dockerhub

For jetson devices:

See How to create / update a docker image for a jetson device

For nvidia-docker machine:

See How to create / update a docker image for a nvidia-docker machine

🎯 How accurate is OpenDataCam ?

Accuracy depends on which YOLO weights your hardware is capable of running.

We are working on adding a benchmark to rank OpenDataCam on the MOT Challenge (Multiple Object Tracking Benchmark)

🚤 How fast is OpenDataCam ?

FPS depends on:

  • which hardware your are running OpenDataCam on
  • which YOLO weights you are using

We made the default settings to run at least at 10 FPS on any Jetson.

Learn more in the Customize OpenDataCam documentation

🛠 Development notes

See Development notes

Technical architecture overview:

Technical architecture

📫️ Contact

Issues should be raised directly in the repository. For business inquiries or professional support requests please contact @tdurand

💌 Acknowledgments