Merge pull request #917 from jakaskerl/main

Adding code examples in docs

docs/source/components/device.rst

@@ -55,6 +55,117 @@ subnet, you can specify the device (either with MxID, IP, or USB port name) you
   with depthai.Device(pipeline, device_info) as device:
       # ...
 
+
+Watchdog
+########
+
+Understanding the Watchdog Mechanism in POE Devices
+----------------------------------------------------
+
+The watchdog is a crucial component in the operation of POE (Power over Ethernet) devices with DepthAI. When DepthAI disconnects from a POE device, the watchdog mechanism is the first to respond, initiating a reset of the camera. This reset is followed by a complete system reboot, which includes the loading of the DepthAI bootloader and the initialization of the entire networking stack. 
+
+.. note::
+    This process is necessary to make the camera available for reconnection and typically takes about 10 seconds, which means the fastest possible reconnection time is 10 seconds.
+
+
+Customizing the Watchdog Timeout
+--------------------------------
+
+.. tabs::
+
+  .. tab:: **Linux/MacOS**
+
+    Set the environment variables `DEPTHAI_WATCHDOG_INITIAL_DELAY` and `DEPTHAI_BOOTUP_TIMEOUT` to your desired timeout values (in milliseconds) as follows:
+
+    .. code-block:: bash
+
+      DEPTHAI_WATCHDOG_INITIAL_DELAY=<my_value> DEPTHAI_BOOTUP_TIMEOUT=<my_value> python3 script.py
+
+  .. tab:: **Windows PowerShell**
+
+    For Windows PowerShell, set the environment variables like this:
+
+    .. code-block:: powershell
+
+      $env:DEPTHAI_WATCHDOG_INITIAL_DELAY=<my_value>
+      $env:DEPTHAI_BOOTUP_TIMEOUT=<my_value>
+      python3 script.py
+
+  .. tab:: **Windows CMD**
+
+    In Windows CMD, you can set the environment variables as follows:
+
+    .. code-block:: guess
+
+      set DEPTHAI_WATCHDOG_INITIAL_DELAY=<my_value>
+      set DEPTHAI_BOOTUP_TIMEOUT=<my_value>
+      python3 script.py
+
+Code-Based Configuration
+------------------------
+
+Alternatively, you can set the timeout directly in your code:
+
+.. code-block:: python
+
+  pipeline = depthai.Pipeline()
+
+  # Create a BoardConfig object
+  config = depthai.BoardConfig()
+
+  # Set the parameters
+  config.watchdogInitialDelayMs = <my_value>
+  config.watchdogTimeoutMs = <my_value>
+
+  pipeline.setBoardConfig(config)
+
+By adjusting these settings, you can tailor the watchdog functionality to better suit your specific requirements.
+
+
+Environment Variables
+#####################
+
+The following table lists various environment variables used in the system, along with their descriptions:
+
+.. list-table::
+   :widths: 50 50
+   :header-rows: 1
+
+   * - Environment Variable
+     - Description
+   * - `DEPTHAI_LEVEL`
+     - Sets logging verbosity, options: 'trace', 'debug', 'warn', 'error', 'off'
+   * - `XLINK_LEVEL`
+     - Sets logging verbosity of XLink library, options: 'debug', 'info', 'warn', 'error', 'fatal', '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.
+
+
+
 Multiple devices
 ################
 
@@ -120,7 +231,7 @@ Two examples would be:
 - encoding (most prominently H264/H265 as frame drops can lead to artifacts).
 
 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.
@@ -133,7 +244,8 @@ It will wait for the host to consume (eg. :code:`queue.get()`) a message before
     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.
@@ -142,7 +254,7 @@ For example, if a message has 5MB of data, and the queue size is 30, this queue
 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.

docs/source/components/nodes/uvc.rst

@@ -0,0 +1,62 @@
+UVC
+===
+
+The DepthAI UVC (`USB Video Class <https://en.wikipedia.org/wiki/USB_video_device_class>`__) node allows OAK devices to function as standard webcams. This feature is particularly useful for integrating OAK devices into applications that require video input, such as video conferencing tools or custom video processing applications.
+
+What is UVC?
+############
+
+UVC refers to the USB Video Class standard, which is a USB device class that describes devices capable of streaming video. This standard allows video devices to interface with computers and other devices without needing specific drivers, making them immediately compatible with a wide range of systems and software.
+
+How Does the UVC Node Work?
+###########################
+
+The UVC node in DepthAI leverages this standard to stream video from OAK devices. When the UVC node is enabled, the OAK device is recognized as a standard webcam by the host system. This allows the device to be used in any application that supports webcam input, such as Zoom, Skype, or custom video processing software.
+
+The UVC node streams video data over a USB connection. It is important to use a USB3 cable for this purpose, as USB2 may not provide the necessary bandwidth for stable video streaming.
+
+.. note::
+
+    The UVC node can currently handle NV12 video streams from OAK devices. For streams in other formats, conversion to NV12 is necessary, which can be achieved using the :ref:`ImageManip` node. It's important to note that streams incompatible with NV12 conversion, like depth streams, are not supported by the UVC node.
+
+Examples of UVC Node Usage
+##########################
+
+1. **DepthAI Demo Script**: The DepthAI demo script includes a UVC application that can be run to enable the UVC node on an OAK device.
+
+   .. code-block:: bash
+
+       python3 depthai_demo.py --app uvc
+
+2. **Custom Python Script**: A custom Python script can be written to enable the UVC node and configure the video stream parameters. Here are some pre-written examples:
+
+   - :ref:`UVC & Color Camera`
+   - :ref:`UVC & Mono Camera`
+   - :ref:`UVC & Disparity`
+
+
+3. **OBS Forwarding**: For applications where direct UVC node usage is not possible, OBS Studio can be used to forward the UVC stream.
+
+
+Reference
+#########
+
+.. tabs::
+
+  .. tab:: Python
+
+    .. autoclass:: depthai.node.UVC
+      :members:
+      :inherited-members:
+      :noindex:
+
+  .. tab:: C++
+
+    .. doxygenclass:: dai::node::UVC
+      :project: depthai-core
+      :members:
+      :private-members:
+      :undoc-members:
+
+
+.. include:: ../../includes/footer-short.rst

docs/source/samples/FeatureTracker/feature_motion_estimation.rst

@@ -0,0 +1,37 @@
+Feature Tracker with Motion Estimation
+======================================
+
+This example demonstrates the capabilities of the :ref:`FeatureTracker` combined with motion estimation. It detects and tracks features between consecutive frames using optical flow. 
+Each feature is assigned a unique ID. The motion of the camera is estimated based on the tracked features, and the estimated motion (e.g., Up, Down, Left, Right, Rotating) is displayed on screen. 
+
+The :ref:`Feature Detector` example only detects features without estimating motion.
+
+Demo
+####
+
+.. image:: ../../../../docs/source/_static/images/examples/feature_motion_estimation.gif
+    :alt: Feature Tracker with Motion Estimation Demo
+    :width: 100%
+    :align: center
+
+
+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/FeatureTracker/feature_motion_estimation.py>`__
+
+        .. literalinclude:: ../../../../examples/FeatureTracker/feature_motion_estimation.py
+           :language: python
+           :linenos:
+
+
+.. include::  /includes/footer-short.rst

docs/source/samples/UVC/uvc_disparity.rst

@@ -0,0 +1,70 @@
+UVC & Disparity
+===============
+
+This example demonstrates how to use your OAK device as a UVC webcam. The UVC feature allows you to use your OAK device as a regular webcam in applications like OpenCV's :code:`cv2.VideoCapture()`, native camera apps, and more.
+
+.. rubric:: How It Works:
+
+The :ref:`StereoDepth` node outputs image data in the UINT8 format. However, the :ref:`UVC` node expects the data in NV12 format. To bridge this gap, an intermediary :ref:`ImageManip` node is used to convert the GRAY8 output from the MonoCamera node to NV12 format, which is then passed to the UVC node for streaming.
+This doesn't work with stereo depth output, since depth is UINT16 which we cannot convert to NV12.
+
+This example won't work if we enable the subpixel disparity feature, since that outputs UINT16 as well.
+
+.. rubric:: Similar samples:
+
+- :ref:`UVC & Color Camera`
+- :ref:`UVC & Mono Camera`
+
+
+Setup
+#####
+
+.. include::  /includes/install_from_pypi.rst
+
+Code used for testing
+#####################
+
+.. code-block:: python
+
+    import cv2
+
+    # Initialize the VideoCapture object to use the default camera (camera index 0 is webcam)
+    cap = cv2.VideoCapture(1)
+
+    # Check if the camera opened successfully
+    if not cap.isOpened():
+        print("Error: Could not open camera.")
+        exit()
+
+    # Loop to continuously get frames from the camera
+    while True:
+        ret, frame = cap.read()
+
+        if not ret:
+            print("Error: Could not read frame.")
+            break
+
+        cv2.imshow('Video Feed', frame)
+
+        if cv2.waitKey(1) & 0xFF == ord('q'):
+            break
+
+    cap.release()
+    cv2.destroyAllWindows()
+
+
+Source code
+###########
+
+.. tabs::
+
+    .. tab:: Python
+
+        Also `available on GitHub <https://github.com/luxonis/depthai-python/blob/main/examples/UVC/uvc_disparity.py>`__
+
+        .. literalinclude:: ../../../../examples/UVC/uvc_disparity.py
+           :language: python
+           :linenos:
+
+
+.. include::  /includes/footer-short.rst

docs/source/samples/UVC/uvc_mono.rst

@@ -0,0 +1,69 @@
+UVC & Mono Camera
+=================
+
+This example demonstrates how to use a mono camera on your OAK device to function as a webcam. The UVC feature allows you to use your OAK device as a regular webcam in applications like OpenCV's :code:`cv2.VideoCapture()`, native camera apps, and more.
+
+.. rubric:: How It Works:
+
+The :ref:`MonoCamera` node outputs image data in the GRAY8 format. However, the :ref:`UVC` node expects the data in NV12 format. To bridge this gap, an intermediary :ref:`ImageManip` node is used to convert the GRAY8 output from the MonoCamera node to NV12 format, which is then passed to the UVC node for streaming.
+
+
+.. rubric:: Similar samples:
+
+- :ref:`UVC & Color Camera`
+- :ref:`UVC & Disparity`
+
+
+Setup
+#####
+
+.. include::  /includes/install_from_pypi.rst
+
+Code used for testing
+#####################
+
+.. code-block:: python
+
+    import cv2
+
+    # Initialize the VideoCapture object to use the default camera (camera index 0 is webcam)
+    cap = cv2.VideoCapture(1)
+
+    # Check if the camera opened successfully
+    if not cap.isOpened():
+        print("Error: Could not open camera.")
+        exit()
+
+    # Loop to continuously get frames from the camera
+    while True:
+        ret, frame = cap.read()
+
+        if not ret:
+            print("Error: Could not read frame.")
+            break
+
+        cv2.imshow('Video Feed', frame)
+
+        if cv2.waitKey(1) & 0xFF == ord('q'):
+            break
+
+    cap.release()
+    cv2.destroyAllWindows()
+
+
+
+Source code
+###########
+
+.. tabs::
+
+    .. tab:: Python
+
+        Also `available on GitHub <https://github.com/luxonis/depthai-python/blob/main/examples/UVC/uvc_mono.py>`__
+
+        .. literalinclude:: ../../../../examples/UVC/uvc_mono.py
+           :language: python
+           :linenos:
+
+
+.. include::  /includes/footer-short.rst