Cookie-cutter template app

Quickest way to get started with Luxonis ecosystem is to use the template app. This app is a starting point for your own applications and includes all the necessary components to get you up and running. Apps range from very simple pipelines (e.g. camera stream) to complex and wide-encompassing (e.g using custom AI models and nodes).

Install

Get up and running in under 5 minutes:

Command Line

1# Install core packages
2pip install depthai --force-reinstall
3# Clone the template app
4git clone https://github.com/luxonis/oak-template.git
5# Change directory to the template app
6cd oak-template
7# Install requirements
8pip install -r requirements.txt

This will download the template / cookie-cutter app to your current directory.

Text

1template-app/
2├── main.py
3├── oakapp.toml
4├── requirements.txt
5├── media/ # Optional media files
6└── utils/ # Optional helper functions

main.py

This is where your main logic resides. The downloaded script will use "Camera + NN + Hub" as a default pipeline. Feel free to swap it with any of the other examples below if you don't need the NN or Hub functionality.

Camera + NN + HUB (default)

Camera stream

Depth

Python

1import depthai as dai
2import os
3
4from depthai_nodes.node import SnapsUploader
5from depthai_nodes.node.parsing_neural_network import ParsingNeuralNetwork
6from utils.snaps_producer import SnapsProducer
7from dotenv import load_dotenv
8
9# Assumes `DEPTHAI_HUB_API_KEY` is defined in the workspace root `.env` file.
10# Load environment variables before initializing the pipeline.
11load_dotenv(override=True)
12
13model = "luxonis/yolov6-nano:r2-coco-512x288"
14time_interval = 10.0  # min nr of seconds between snaps uploading
15
16visualizer = dai.RemoteConnection(httpPort=8082)
17device = dai.Device()
18
19with dai.Pipeline(device) as pipeline:
20    print("Creating pipeline...")
21
22    model_description = dai.NNModelDescription(model)
23    platform = device.getPlatformAsString()
24    model_description.platform = platform
25    nn_archive = dai.NNArchive(
26        dai.getModelFromZoo(
27            model_description,
28        )
29    )
30
31    input_node = pipeline.create(dai.node.Camera).build()
32
33    nn_with_parser = pipeline.create(ParsingNeuralNetwork).build(
34        input_node, nn_archive
35    )
36
37    visualizer.addTopic("Video", nn_with_parser.passthrough, "images")
38    visualizer.addTopic("Visualizations", nn_with_parser.out, "images")
39
40    snaps_producer = pipeline.create(SnapsProducer).build(
41        frame=nn_with_parser.passthrough,
42        detections=nn_with_parser.out,
43        time_interval=time_interval
44    )
45
46    snaps_uploader = pipeline.create(SnapsUploader).build(snaps_producer.out)
47
48    print("Pipeline created.")
49
50    pipeline.start()
51    visualizer.registerPipeline(pipeline)
52
53    while pipeline.isRunning():
54        key = visualizer.waitKey(1)
55        if key == ord("q"):
56            print("Got q key from the remote connection!")
57            break

DepthAI Examples

If you wish to use a different pipeline, you can find a list of available nodes and their examples

oakapp.toml

This is where you define the build process for your container. For template apps, we recommend using the Luxonis base image and installing Python dependencies from requirements.txt. You can find more information here.

Toml

1identifier = "custom.oakapp"
2app_version = "1.0.0"
3
4prepare_container = [
5    { type = "RUN", command = "apt-get update" },
6    { type = "RUN", command = "apt-get install -y python3 python3-pip wget git" },
7]
8
9prepare_build_container = []
10
11build_steps = ["pip3 install -r /app/requirements.txt --break-system-packages"]
12
13entrypoint = ["bash", "-c", "python3 /app/main.py"]
14
15[base_image]
16api_url = "https://registry-1.docker.io"
17service = "registry.docker.io"
18oauth_url = "https://auth.docker.io/token"
19auth_type = "repository"
20auth_name = "luxonis/oakapp-base"
21image_name = "luxonis/oakapp-base"
22image_tag = "1.2.6"

Hub authentication (optional)

If you are working with Luxonis Hub as is the case in the "Camera + NN + HUB (default)" example you will need to authenticate with Hub API Key. The simplest way to do that safely is to create an .env file in the root folder of the app and insert:

Command Line

1# content of .env file
2DEPTHAI_HUB_API_KEY=<INSERT_YOUR_HUB_APIKEY_HERE>

To get the API Key you will first need to create a Luxonis Hub account and then navigate to team settings and click Create API Key button.This is safe because .env files are automatically ignored by git so there is no danger of uploading your private API Key to a public repo where everybody can see it. Variables in .env files are set up by the dotenv library, and authentication is then automatically done with the key stored in the DEPTHAI_HUB_API_KEY environment variable. Please check our API Key Security - Good Practices page to get to know other examples for safely passing API Keys to apps.

Deploy

Now that you have your main.py and oakapp.toml, you can deploy your application in one of these ways:

Standalone

This is the simplest option. Just run the following command in the same directory as your main.py and oakapp.toml files:

Command Line

1oakctl app run .

This command builds your app into a container and runs it directly on the OAK device, with no host-side app process required. Results can be viewed with the visualizer webapp at http://<device-ip>:8082.

Peripheral

This option is for when you want to run your application from your host machine. No containerization is needed in this mode, but you need a steady connection to the device. To run your application in peripheral mode, run the following command:

Command Line

1python3 main.py

Results can be viewed with the visualizer webapp at http://<host-ip>:8082.

Next steps

Continue developing

Follow the tutorials and guides in OAK Apps section to continue developing your app.

Open OAK Apps overview

Publish the app to Luxonis Hub

Build and publish the app so your team can install it from Hub.

Go to app publishing