• Stars
    star
    234
  • Rank 171,630 (Top 4 %)
  • Language
    C++
  • License
    MIT License
  • Created over 4 years ago
  • Updated about 1 month ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

DepthAI C++ Library

DepthAI C++ Library

License: MIT

Core C++ library

Documentation

Documentation is available over at Luxonis DepthAI API

Disclaimer

DepthAI library doesn't yet provide API stability guarantees. While we take care to properly deprecate old functions, some changes might still be breaking. We expect to provide API stability from version 3.0.0 onwards.

Dependencies

  • CMake >= 3.10
  • C/C++14 compiler
  • [optional] OpenCV 4 (required if building examples)

MacOS: Optional brew install opencv

Linux: Optional sudo apt install libopencv-dev

Building

Make sure submodules are updated

git submodule update --init --recursive

Then configure and build

cmake -S. -Bbuild
cmake --build build

ℹī¸ To speed up build times, use cmake --build build --parallel [num CPU cores] (CMake >= 3.12). For older versions use: Linux/macOS: cmake --build build -- -j[num CPU cores], MSVC: cmake --build build -- /MP[num CPU cores]

⚠ī¸ If any CMake commands error with CMake Error: The source directory "" does not exist. replace argument -S with -H

Dynamic library

To build dynamic version of library configure with following option added

cmake -S. -Bbuild -D'BUILD_SHARED_LIBS=ON'
cmake --build build

Android

Android is supported to some extent but not actively pursued nor tested. PRs with any improvements are welcome.

Steps:

  • Install Android NDK (for example via Android Studio).
  • Set the NDK path:
export ANDROID_HOME=$HOME/.local/lib/Android
export PATH=$PATH:$ANDROID_HOME/emulator:$ANDROID_HOME/platform-tools
export NDK=$ANDROID_HOME/ndk/23.1.7779620/ # Check version
  • Ensure a recent version of cmake (apt version is outdated, install snap install cmake --classic)
  • Run cmake, set your ABI and Platform as needed:
cmake -S. -Bbuild -DCMAKE_TOOLCHAIN_FILE=$NDK/build/cmake/android.toolchain.cmake -DANDROID_ABI=armeabi-v7a -DANDROID_PLATFORM=android-25
cmake --build build

Running examples

To build the examples configure with following option added

cmake -S. -Bbuild -D'DEPTHAI_BUILD_EXAMPLES=ON'
cmake --build build

Then navigate to build/examples folder and run a preferred example

cd build/examples
./MobileNet/rgb_mobilenet

ℹī¸ Multi-Config generators (like Visual Studio on Windows) will have the examples built in build/examples/MobileNet/[Debug/Release/...]/rgb_mobilenet

Integration

Under releases you may find prebuilt library for Windows, for use in either integration method. See Releases

CMake

Targets available to link to are:

  • depthai::core - Core library, without using opencv internally
  • depthai::opencv - Core + support for opencv related helper functions (requires OpenCV4)

Using find_package

Build static or dynamic version of library (See: Building and optionally Installing)

Add find_package and target_link_libraries to your project

find_package(depthai CONFIG REQUIRED)
...
target_link_libraries([my-app] PRIVATE depthai::opencv)

And point CMake to either build directory or install directory:

-D'depthai_DIR=depthai-core/build'

or

-D'depthai_DIR=depthai-core/build/install/lib/cmake/depthai'

If library was installed to default search path like /usr/local on Linux, specifying depthai_DIR isn't necessary as CMake will find it automatically.

Using add_subdirectory

This method is more intrusive but simpler as it doesn't require building the library separately.

Add add_subdirectory which points to depthai-core folder before project command. Then link to any required targets.

add_subdirectory(${CMAKE_CURRENT_LIST_DIR}/depthai-core EXCLUDE_FROM_ALL)
...
project(my-app)
...
target_link_libraries([my-app] PRIVATE depthai::opencv)

Non-CMake integration (Visual Studio, Xcode, CodeBlocks, ...)

To integrate into a different build system than CMake, prefered way is compiling as dynamic library and setting correct build options.

  1. First build as dynamic library: Building Dynamic library
  2. Then install: Installing

In your non-CMake project (new Visual Studio project, ...)

  1. Set needed library directories:
    • build/install/lib (for linking to either depthai-core or depthai-opencv)
    • build/install/bin (for .dll's)
  2. And include directories
    • build/install/include (library headers)
    • build/install/include/depthai-shared/3rdparty (shared 3rdparty headers)
    • build/install/lib/cmake/depthai/dependencies/include (dependency headers)

ℹī¸ Threading library might need to be linked to explicitly.

ℹī¸ Check build/depthai-core-integration.txt or build/depthai-opencv-integration.txt for up to date define options. The generated integration file also specifies include paths without requiring installation.

Installing

To install specify optional prefix and build target install

cmake -S. -Bbuild -D'CMAKE_INSTALL_PREFIX=[path/to/install/dir]'
cmake --build build --target install

If CMAKE_INSTALL_PREFIX isn't specified, the library is installed under build folder install.

Environment variables

The following environment variables can be set to alter default behavior of the library without having to recompile

Environment variable Description
DEPTHAI_LEVEL Sets logging verbosity, 'trace', 'debug', 'warn', 'error' and 'off'
XLINK_LEVEL Sets logging verbosity of XLink library, 'debug'. 'info', 'warn', 'error', 'fatal' and 'off'
DEPTHAI_INSTALL_SIGNAL_HANDLER Set to 0 to disable installing Backward signal handler for stack trace printing
DEPTHAI_WATCHDOG Sets device watchdog timeout. Useful for debugging (DEPTHAI_WATCHDOG=0), to prevent device reset while the process is paused.
DEPTHAI_WATCHDOG_INITIAL_DELAY Specifies delay after which the device watchdog starts.
DEPTHAI_SEARCH_TIMEOUT Specifies timeout in milliseconds for device searching in blocking functions.
DEPTHAI_CONNECT_TIMEOUT Specifies timeout in milliseconds for establishing a connection to a given device.
DEPTHAI_BOOTUP_TIMEOUT Specifies timeout in milliseconds for waiting the device to boot after sending the binary.
DEPTHAI_PROTOCOL Restricts default search to the specified protocol. Options: any, usb, tcpip.
DEPTHAI_DEVICE_MXID_LIST Restricts default search to the specified MXIDs. Accepts comma separated list of MXIDs. Lists filter results in an "AND" manner and not "OR"
DEPTHAI_DEVICE_ID_LIST Alias to MXID list. Lists filter results in an "AND" manner and not "OR"
DEPTHAI_DEVICE_NAME_LIST Restricts default search to the specified NAMEs. Accepts comma separated list of NAMEs. Lists filter results in an "AND" manner and not "OR"
DEPTHAI_DEVICE_BINARY Overrides device Firmware binary. Mostly for internal debugging purposes.
DEPTHAI_BOOTLOADER_BINARY_USB Overrides device USB Bootloader binary. Mostly for internal debugging purposes.
DEPTHAI_BOOTLOADER_BINARY_ETH Overrides device Network Bootloader binary. Mostly for internal debugging purposes.
DEPTHAI_ALLOW_FACTORY_FLASHING Internal use only

Running tests

To run the tests build the library with the following options

cmake -S. -Bbuild -D'DEPTHAI_TEST_EXAMPLES=ON' -D'DEPTHAI_BUILD_TESTS=ON' -D'DEPTHAI_BUILD_EXAMPLES=ON'
cmake --build build

Then navigate to build folder and run ctest with specified labels that denote device type to test on. Currently available labels:

  • usb
  • poe
cd build
# Run tests on USB devices
ctest -L usb
# Run tests on PoE devices
ctest -L poe

Style check

The library uses clang format to enforce a certain coding style. If a style check is failing, run the clangformat target, check the output and push changes.

To use this target clang format must be installed, preferably clang-format-10

sudo apt install clang-format-10

And to apply formatting

cmake --build build --target clangformat

Documentation generation

Doxygen is used to generate documentation. Follow doxygen download and install the required binaries for your platform.

After that specify CMake define -D'DEPTHAI_BUILD_DOCS=ON' and build the target doxygen

Debugging tips

Debugging can be done using Visual Studio Code and either GDB or LLDB (extension 'CodeLLDB'). LLDB in some cases was much faster to step with and resolved more incomplete_type variables than GDB. Your mileage may vary though.

If there is a need to step into Hunter libraries, that can be achieved by removing previous built artifacts

rm -r ~/.hunter

And configuring the project with the following CMake option set to ON

cmake . -D'HUNTER_KEEP_PACKAGE_SOURCES=ON'

This retains the libraries source code, so that debugger can step through it (the paths are already set up correctly)

Troubleshooting

Build fails with missing OpenCV dependency

If your build process happen to fail due to OpenCV library not being found, but you have the OpenCV installed, please run build with additional -D'OpenCV_DIR=...' flag (replacing default Ubuntu path /usr/lib/x86_64-linux-gnu/cmake/opencv4 with yours)

cmake -S. -Bbuild -D'OpenCV_DIR=/usr/lib/x86_64-linux-gnu/cmake/opencv4'

Now the build process should correctly discover your OpenCV installation

Hunter

Hunter is a CMake-only dependency manager for C/C++ projects.

If you are stuck with error message which mentions external libraries (subdirectory of .hunter) like the following:

/usr/bin/ld: /home/[user]/.hunter/_Base/062a19a/ccfed35/a84a713/Install/lib/liblzma.a(stream_flags_decoder.c.o): warning: relocation against `lzma_footer_magic' in read-only section `.text'

Try erasing the Hunter cache folder.

Linux/MacOS:

rm -r ~/.hunter

Windows:

del C:/.hunter

or

del C:/[user]/.hunter

More Repositories

1

depthai

DepthAI Python API utilities, examples, and tutorials.
Python
933
star
2

depthai-experiments

Experimental projects we've done with DepthAI.
Jupyter Notebook
829
star
3

depthai-hardware

Altium Designs for DepthAI Carrier Boards
HTML
447
star
4

depthai-python

DepthAI Python Library
C++
357
star
5

depthai-ros

Official ROS Driver for DepthAI Sensors.
C++
255
star
6

depthai-unity

DepthAI Unity Library, Unity projects and examples (OAK For Unity)
C#
200
star
7

depthai-ml-training

Some Example Neural Models that we've trained along with the training scripts
Jupyter Notebook
119
star
8

datadreamer

Creation of annotated datasets from scratch using Generative AI and Foundation Computer Vision models
Python
77
star
9

depthai-gui

DepthAI Pipeline Builder GUI
Python
75
star
10

depthai-ros-examples

Python
41
star
11

depthai-tutorials

Source code for DepthAI tutorials published @ https://docs.luxonis.com
Python
40
star
12

depthai-model-zoo

DepthAI Model Zoo is a collection of open-source neural network models and datasets created and maintained by DepthAI developers and community
Python
35
star
13

rae-ros

Implementation of RAE ROS and gazebo stack
Python
32
star
14

esp32-spi-message-demo

ESP32 reference app for interfacing with DepthAI over SPI
C++
31
star
15

tools

Various tools for OAK-D camera
Jupyter Notebook
28
star
16

depthai-docs-website

The documentation site for Luxonis DepthAI
CSS
26
star
17

Factory-calibration-DepthAI

Factory Calibration for DepthAI Stereo-capable models.
Python
17
star
18

depthai-shared

DepthAI Shared code and data
C++
16
star
19

blobconverter

Web-based tool to convert model into MyriadX blob
Python
15
star
20

depthai-core-example

CMake C++ example project using depthai library
CMake
14
star
21

models

Repository of lightweight models for classification, object detection, segmentation and more. Deployable to OAK-D, OpenVINO, and ONNX.
Python
14
star
22

luxonis-ml

Luxonis ML library which abstracts logging, tracking, and other useful functionalities.
Python
13
star
23

XLink

A cross-platform library for communicating with devices over various physical links.
C
12
star
24

DepthAI-PyFlow

OUTDATED, see here - https://github.com/luxonis/depthai-gui
Python
11
star
25

yolo2openvino

YoloV3, YoloV4, YoloV3-tiny, and YoloV4-tiny conversion to Tensorflow and OpenVINO.
Python
10
star
26

luxonis-train

Training framework for easy creation, training and exporting of deep learning models.
Python
10
star
27

depthai-docker

Python
8
star
28

modelconverter

Model converter for Luxonis' cameras. Convert your model from ONNX, TF, ... to a model compatible with any generation of Luxonis camera.
Python
8
star
29

remote-monitoring

JavaScript
7
star
30

depthai-poe-webapp

DepthAI WebApp for PoE devices
Python
7
star
31

robothub-images

Shell
6
star
32

robothub-examples

Python
4
star
33

depthai-spi-api

C++
4
star
34

robothub-public-apps

Python
3
star
35

depthai-boards

Files with hardware descriptions for depthai boards
Python
3
star
36

simulation

3
star
37

depthai-calibration

Python
2
star
38

tusb926x-flash-burner

TUSB926x modern libusb/hidapi Linux flasher
C++
2
star
39

depthai-ros-release

Release repository of depthai-ros
2
star
40

depthai-spi-library

DepthAI SPI Library
C
2
star
41

depthai-bootloader-shared

Shared code and data for depthai-bootloader
C++
2
star
42

depthai-nodes

Python nodes for on-host depthai augmentation.
Python
2
star
43

python-api-analyzer-to-json

Python
1
star
44

robothub

Python
1
star
45

SBR

Library and utility to view and manipulate SBR images
C
1
star
46

depthai-node

CMake
1
star
47

rp2040_u2if

Interface with RP2040 running U2IF FW
Python
1
star
48

rae-unity

RAE Unity plugin and Simulation
1
star