Skip to content

Commit

Permalink
Adds documentation from OpenDataCam
Browse files Browse the repository at this point in the history
Closes #74
  • Loading branch information
vsaw committed Nov 29, 2023
1 parent 888ed44 commit ace6aa4
Show file tree
Hide file tree
Showing 34 changed files with 1,682 additions and 548 deletions.
80 changes: 80 additions & 0 deletions docs/00-index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
---
slug: /
---

# Introduction

Welcome to the OpenDataCam Documentation.
Below is a quickstart guide to get you started with OpenDataCam.
Detailed information on installation options and configuration can be found in the respective subpages.

## Quickstart

The quickest way to get started with OpenDataCam is to use the existing Docker Images.

### Pre-Requesits

- You will need Docker and Docker-Compose installed.
- If you want to run OpenDataCam on a NVIDIA GPU you will additonally need
- [Nvidia CUDA 11 and cuDNN 8](https://developer.nvidia.com/cuda-downloads)
- [Nvidia Container toolkit installed](https://github.com/NVIDIA/nvidia-docker)
- You also need to install `nvidia-container-runtime`
- To run OpenDataCam on a NVIDIA Jetson device you will need [Jetpack 5.x](https://developer.nvidia.com/embedded/jetpack-sdk-512).

### Installation

```bash
# 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

# Note: You will be asked for sudo password when installing OpenDataCam

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

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

# Install command for a Laptop, Desktop or Server with NVIDIA GPU
./install-opendatacam.sh --platform desktop
```

This command will download and start a docker container on the machine.
After it finishes the docker container starts a webserver on port 8080 and run a demo video.

:::note

The docker container is started in auto-restart mode, so if you reboot your machine it will automaticaly start opendatacam on startup.
To stop it run `docker-compose down` in the same folder as the install script.

:::

### Next Steps

Now you can…

- Drag'n'Drop a video file into the browser window to have OpenDataCam analzye this file
- Change the [video input](/docs/configuration/#video-input) to run from a USB-Cam or other cameras
- Use custom [neural network weigts](/docs/configuration/#use-custom-neural-network-weights)

and much more. See [Configuration](/docs/configuration) for a full list of configuration options.

## How accurate is OpenDataCam?

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

We are working on [adding a benchmark](https://github.com/opendatacam/opendatacam/issues/87) to rank OpenDataCam on the [MOT Challenge (Multiple Object Tracking Benchmark)](https://motchallenge.net/)

## 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](documentation/CONFIG.md#Change-neural-network-weights)
62 changes: 62 additions & 0 deletions docs/02-installation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
# Installation

- You will need Docker and Docker-Compose installed.
- If you want to run OpenDataCam on a NVIDIA GPU you will additonally need
- [Nvidia CUDA 11 and cuDNN 8](https://developer.nvidia.com/cuda-downloads)
- [Nvidia Container toolkit installed](https://github.com/NVIDIA/nvidia-docker)
- You also need to install `nvidia-container-runtime`
- To run OpenDataCam on a NVIDIA Jetson device you will need [Jetpack 5.x](https://developer.nvidia.com/embedded/jetpack-sdk-512).

## As Docker Container (Recommended)

This is the recommended way to install OpenDataCam.
Follow the [Quickstart Guide](/docs/#quickstart)

## Kubernetes

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](https://k3s.io/), which can be installed in 30 seconds by running:

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

Then, to automatically download and deploy the services:

```bash
# 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](https://github.com/NVIDIA/k8s-device-plugin) for detecting GPUs on nodes in case you are managing a heterogeneous cluster.
Support for Jetson boards is being worked [here](https://gitlab.com/nvidia/kubernetes/device-plugin/-/merge_requests/20)
:::

## Balena

[![](https://www.balena.io/deploy.png)](https://dashboard.balena-cloud.com/deploy?repoUrl=https://github.com/balenalabs-incubator/opendatacam)

If you have a fleet of one or more devices, you can use [balena](https://www.balena.io/) to streamline deployment and management of OpenDataCam.
You can sign up for a free account [here](https://dashboard.balena-cloud.com/signup) 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](https://www.balena.io/blog/using-opendatacam-and-balena-to-quantify-the-world-with-ai/), or [view a screencast](https://www.youtube.com/watch?v=YfRvUeSLi0M&t=44m45s) of the deployment in action.

## Without Docker

See [How to install OpenDataCam without docker](/docs/development/install-without-docker/)
Loading

0 comments on commit ace6aa4

Please sign in to comment.