Merge remote-tracking branch 'origin/main' into HEAD

Author: SzabolcsGergely

README.md

@@ -31,30 +31,47 @@ See: [depthai-core dependencies](https://github.com/luxonis/depthai-core#depende
 
 ### Building
 
+The first time you build, the repository submodules need be initialized:
+```
+git submodule update --init --recursive
+
+# Tip: You can ask Git to do that automatically:
+git config submodule.recurse true
+```
+
+Later submodules also need to be updated.
+
+#### Local build with pip
 To build and install using pip:
 ```
 python3 -m pip install .
 ```
 Add parameter `-v` to see the output of the building process.
 
-
+#### Wheel with pip
 To build a wheel, execute the following
 ```
 python3 -m pip wheel . -w wheelhouse
 ```
 
+#### Shared library
 To build a shared library from source perform the following:
 
 > ℹ️ 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]`
 
 ```
-git submodule update --init --recursive
 cmake -H. -Bbuild
 cmake --build build
 ```
 To specify custom Python executable to build for, use `cmake -H. -Bbuild -D PYTHON_EXECUTABLE=/full/path/to/python`.
 
+#### Common issues
+
+* Many build fails due to missing dependencies. This also happens when submodules are missing or outdated (`git submodule update --recursive`).
+* If libraries and headers are not in standard places, or not on the search paths, CMake reports it cannot find what it needs (e.g. `libusb`). CMake can be hinted at where to look, for exmpale: `CMAKE_LIBRARY_PATH=/opt/local/lib CMAKE_INCLUDE_PATH=/opt/local/include pip install .`
+* Some distribution installers may not get the desired library. For example, an install on a RaspberryPi failed, missing `libusb`, as the default installation with APT led to v0.1.3 at the time, whereas the library here required v1.0.
+
 
 ## Running tests
 

depthai-core

@@ -40,26 +40,58 @@ If you want to use multiple devices on a host, check :ref:`Multiple DepthAI per
 Device queues
 #############
 
-After initializing the device, one has to initialize the input/output queues as well. You can create an input queue with
-:code:`device.getInputQueue("input_name")` and output queue with :code:`device.getOutputQueue("output_name")`.
-
-
-When you define an output queue, the device can write to it at any point in time, and the host can read from it at any point in time.
-There might be a cases when the host is reading very fast from the queue, and the queue, no matter its size, will stay empty most of
-the time. But as we add things on the host side (additional processing, analysis etc), it may happen that the device will be writing to
-the queue faster than the host can read from it. And then the packets in the queue will start to add up - and both maxSize and blocking
-flags determine the behavior of the queue in this case.
-
-By default, the queue is blocking and its size is 30, so the device will put
-30 packets at most, and when the limit is reached, it will hang on queue put call and wait until it can successfully complete this
-call (so, waits for the host to consume the packet before putting a new one). Making the queue non-blocking will change its behavior
-in this situation - instead of waiting, it will discard the oldest packet and add the new one, and then continue it's processing
-loop (so it won't get blocked). maxSize determines the size of the queue and also
-helps to control the memory usage - if the packet have 5MB of data, and the queue size is 30, this queue effectively stores
-150MB of data in memory (the packets can also get really big, for instance a single 4K NV12 encoded frame takes about ~12MB).
-Decreasing the queue size to 1 and setting non-blocking behavior will effectively mean "I only want the latest packet from the queue".
-
-The size and behavior of the queue can be modified after the initialization by calling :code:`queue.setBlocking()` and :code:`queue.setMaxSize()`.
+After initializing the device, one has to initialize the input/output queues as well.
+
+.. code-block:: python
+
+  outputQueue = device.getOutputQueue("output_name")
+  inputQueue = device.getInputQueue("input_name")
+
+When you define an output queue, the device can push new messages to it at any point in time, and the host can read from it at any point in time.
+Usually, when the host is reading very fast from the queue, the queue (regardless of its size) will stay empty most of
+the time. But as we add things on the host side (additional processing, analysis, etc), it may happen that the device will be writing to
+the queue faster than the host can read from it. And then the messages in the queue will start to add up - and both maxSize and blocking
+flags determine the behavior of the queue in this case. You can set these flags with:
+
+.. code-block:: python
+
+  # When initializing the queue
+  queue = device.getOutputQueue(name="name", maxSize=5, blocking=False)
+
+  # Or afterwards
+  queue.setMaxSize(10)
+  queue.setBlocking(True)
+
+Blocking behaviour
+******************
+
+By default, queues are **blocking** and their size is **30**, so when the device fills up a queue and when the limit is
+reached, any additional messages from the device will be blocked and the library will wait until it can add new messages to the queue.
+It will wait for the host to consume (eg. :code:`queue.get()`) a message before putting a new one into the queue.
+
+.. note::
+    After the host queue gets filled up, the XLinkOut.input queue on the device will start filling up. If that queue is
+    set to blocking, other nodes that are sending messages to it will have to wait as well. This is a usual cause for a
+    blocked pipeline, where one of the queues isn't emptied in timely manner and the rest of the pipeline waits for it
+    to be empty again.
+
+Non-Blocking behaviour
+**********************
+Making the queue non-blocking will change the behavior in the situation described above - instead of waiting, the library will discard
+the oldest message and add the new one to the queue, and then continue its processing loop (so it won't get blocked).
+:code:`maxSize` determines the size of the queue and it also helps to control memory usage.
+
+For example, if a message has 5MB of data, and the queue size is 30, this queue can effectively store
+up to 150MB of data in the memory on the host (the messages can also get really big, for instance, a single 4K NV12 encoded frame takes about ~12MB).
+
+Some additional information
+***************************
+
+- Decreasing the queue size to 1 and setting non-blocking behavior will effectively mean "I only want the latest packet from the queue".
+- Queues are thread-safe - they can be accessed from any thread.
+- Queues are created such that each queue is its own thread which takes care of receiving, serializing/deserializing, and sending the messages forward (same for input/output queues).
+- The :code:`Device` object isn't fully thread-safe. Some RPC calls (eg. :code:`getLogLevel`, :code:`setLogLevel`, :code:`getDdrMemoryUsage`) will get thread-safe once the mutex is set in place (right now there could be races).
+
 
 Reference
 #########

docs/source/components/device.rst

@@ -0,0 +1,38 @@
+Calibration Flash
+=================
+
+This example shows how to flash calibration data of version 6 (gen2 calibration data) to the device.
+
+.. rubric:: Similiar samples:
+
+- :ref:`Calibration Flash v5`
+- :ref:`Calibration Reader`
+- :ref:`Calibration Load`
+
+Setup
+#####
+
+.. include::  /includes/install_from_pypi.rst
+
+Source code
+###########
+
+.. tabs::
+
+    .. tab:: Python
+
+        Also `available on GitHub <https://github.com/luxonis/depthai-python/blob/main/examples/calibration_flash.py>`__
+
+        .. literalinclude:: ../../../examples/calibration_flash.py
+           :language: python
+           :linenos:
+
+    .. tab:: C++
+
+        Also `available on GitHub <https://github.com/luxonis/depthai-core/blob/main/examples/src/calibration_flash.cpp>`__
+
+        .. literalinclude:: ../../../depthai-core/examples/src/calibration_flash.cpp
+           :language: cpp
+           :linenos:
+
+.. include::  /includes/footer-short.rst

docs/source/samples/calibration_flash.rst

@@ -0,0 +1,38 @@
+Calibration Flash v5
+====================
+
+This example shows how to flash calibration data of version 5 (gen1 calibration data) to the device.
+
+.. rubric:: Similiar samples:
+
+- :ref:`Calibration Flash`
+- :ref:`Calibration Reader`
+- :ref:`Calibration Load`
+
+Setup
+#####
+
+.. include::  /includes/install_from_pypi.rst
+
+Source code
+###########
+
+.. tabs::
+
+    .. tab:: Python
+
+        Also `available on GitHub <https://github.com/luxonis/depthai-python/blob/main/examples/calibration_flash_v5.py>`__
+
+        .. literalinclude:: ../../../examples/calibration_flash_v5.py
+           :language: python
+           :linenos:
+
+    .. tab:: C++
+
+        Also `available on GitHub <https://github.com/luxonis/depthai-core/blob/main/examples/src/calibration_flash_v5.cpp>`__
+
+        .. literalinclude:: ../../../depthai-core/examples/src/calibration_flash_v5.cpp
+           :language: cpp
+           :linenos:
+
+.. include::  /includes/footer-short.rst

docs/source/samples/calibration_flash_v5.rst

@@ -0,0 +1,38 @@
+Calibration Load
+================
+
+This example shows how to load and use calibration data of version6 (gen2 calibration data) in a pipeline.
+
+.. rubric:: Similiar samples:
+
+- :ref:`Calibration Flash v5`
+- :ref:`Calibration Flash`
+- :ref:`Calibration Reader`
+
+Setup
+#####
+
+.. include::  /includes/install_from_pypi.rst
+
+Source code
+###########
+
+.. tabs::
+
+    .. tab:: Python
+
+        Also `available on GitHub <https://github.com/luxonis/depthai-python/blob/main/examples/calibration_load.py>`__
+
+        .. literalinclude:: ../../../examples/calibration_load.py
+           :language: python
+           :linenos:
+
+    .. tab:: C++
+
+        Also `available on GitHub <https://github.com/luxonis/depthai-core/blob/main/examples/src/calibration_load.cpp>`__
+
+        .. literalinclude:: ../../../depthai-core/examples/src/calibration_load.cpp
+           :language: cpp
+           :linenos:
+
+.. include::  /includes/footer-short.rst

docs/source/samples/calibration_load.rst

@@ -0,0 +1,38 @@
+Calibration Reader
+==================
+
+This example shows how to read calibration data stored on device over XLink.
+
+.. rubric:: Similiar samples:
+
+- :ref:`Calibration Flash v5`
+- :ref:`Calibration Flash`
+- :ref:`Calibration Load`
+
+Setup
+#####
+
+.. include::  /includes/install_from_pypi.rst
+
+Source code
+###########
+
+.. tabs::
+
+    .. tab:: Python
+
+        Also `available on GitHub <https://github.com/luxonis/depthai-python/blob/main/examples/calibration_reader.py>`__
+
+        .. literalinclude:: ../../../examples/calibration_reader.py
+           :language: python
+           :linenos:
+
+    .. tab:: C++
+
+        Also `available on GitHub <https://github.com/luxonis/depthai-core/blob/main/examples/src/calibration_reader.cpp>`__
+
+        .. literalinclude:: ../../../depthai-core/examples/src/calibration_reader.cpp
+           :language: cpp
+           :linenos:
+
+.. include::  /includes/footer-short.rst

docs/source/samples/calibration_reader.rst

@@ -60,4 +60,8 @@ Code samples are used for automated testing. They are also a great starting poin
 - :ref:`System information` - Displays device system information (memory/cpu usage, temperature)
 - :ref:`OpenCV support` - Demonstrates how to retrieve an image frame as an OpenCV frame
 - :ref:`Device Queue Event` - Demonstrates how to use device queue events
-- :ref:`Queue add callback` - Demonstrates how to use queue callbacks
+- :ref:`Queue add callback` - Demonstrates how to use queue callbacks
+- :ref:`Calibration Flash v5` - Demonstrates how to flash calibration data of version 5 (gen1 calibration data) to the device
+- :ref:`Calibration Flash` - Demonstrates how to flash calibration data of version 6 (gen2 calibration data) to the device
+- :ref:`Calibration Reader` - Demonstrates how to read calibration data stored on device over XLink
+- :ref:`Calibration Load` - Demonstrates how to load and use calibration data of version6 (gen2 calibration data) in a pipeline

docs/source/tutorials/code_samples.rst

@@ -10,8 +10,16 @@ Mixed
    ../samples/opencv_support.rst
    ../samples/device_queue_event.rst
    ../samples/queue_add_callback.rst
+   ../samples/calibration_flash_v5.rst
+   ../samples/calibration_flash.rst
+   ../samples/calibration_reader.rst
+   ../samples/calibration_load.rst
 
 - :ref:`System information` - Displays device system information (memory/cpu usage, temperature)
 - :ref:`OpenCV support` - Demonstrates how to retrieve an image frame as an OpenCV frame
 - :ref:`Device Queue Event` - Demonstrates how to use device queue events
-- :ref:`Queue add callback` - Demonstrates how to use queue callbacks
+- :ref:`Queue add callback` - Demonstrates how to use queue callbacks
+- :ref:`Calibration Flash v5` - Demonstrates how to flash calibration data of version 5 (gen1 calibration data) to the device
+- :ref:`Calibration Flash` - Demonstrates how to flash calibration data of version 6 (gen2 calibration data) to the device
+- :ref:`Calibration Reader` - Demonstrates how to read calibration data stored on device over XLink
+- :ref:`Calibration Load` - Demonstrates how to load and use calibration data of version6 (gen2 calibration data) in a pipeline

docs/source/tutorials/mixed_samples.rst

@@ -124,4 +124,5 @@ add_python_example(stereo_depth_from_host stereo_depth_from_host.py)
 add_python_example(stereo_depth_video stereo_depth_video.py)
 add_python_example(imu_gyroscope_accelerometer imu_gyroscope_accelerometer.py)
 add_python_example(imu_rotation_vector imu_rotation_vector.py)
+add_python_example(rgb_depth_aligned rgb_depth_aligned.py)
 add_python_example(edge_detector edge_detector.py)