Merge pull request #214 from luxonis/develop_main_merge

Develop-main merge

Author: SzabolcsGergely

.gitignore

@@ -25,6 +25,10 @@ _builds/
 
 #git
 *.orig
+*_REMOTE_*
+*_LOCAL_*
+*_BACKUP_*
+*_BASE_*
 
 #ci
 wheelhouse/

README.md

@@ -10,46 +10,6 @@ Python bindings for C++ depthai-core library
 
 Documentation is available over at [Luxonis DepthAI API](https://docs.luxonis.com/projects/api/en/latest/)
 
-### Building documentation
-
-- **Using [Docker](https://docs.docker.com/) (with [Docker Compose](https://docs.docker.com/compose/install/))**
-
-     ```
-     cd docs
-     docker-compose build
-     docker-compose up
-     ```
-  
-     Then open [http://localhost:8000](http://localhost:8000).
-     
-     This docker container will watch changes in the `docs/source` directory and rebuild the docs automatically
-
-- **Linux**
-     
-     First, please install the required [dependencies](#Dependencies)
-  
-     Then run the following commands to build the docs website
-  
-     ```
-     python3 -m pip install -U pip
-     python3 -m pip install -r docs/requirements.txt
-     cmake -S . -B build -D DEPTHAI_BUILD_DOCS=ON -D DEPTHAI_PYTHON_BUILD_DOCS=ON
-     cmake --build build --target sphinx --parallel
-     python3 -m http.server --bind 0.0.0.0 8000 --directory build/docs/sphinx
-     ```
-  
-     Then open [http://localhost:8000](http://localhost:8000).
-
-     This will build documentation based on current sources, so if some new changes will be made, run this command
-     in a new terminal window to update the website source
-  
-     ```
-     cmake --build build --target sphinx --parallel
-     ```
-  
-     Then refresh your page - it should load the updated website that was just built
-  
-
 ## Installation
 
 Prebuilt wheels are available in [Luxonis repository](https://artifacts.luxonis.com/artifactory/luxonis-python-snapshot-local/)
@@ -110,6 +70,46 @@ ctest
 - Raspbian 10;
 - macOS 10.14.6, 10.15.4;
 
+### Building documentation
+
+- **Using [Docker](https://docs.docker.com/) (with [Docker Compose](https://docs.docker.com/compose/install/))**
+
+     ```
+     cd docs
+     sudo docker-compose build
+     sudo docker-compose up
+     ```
+
+     > ℹ️ You can leave out the `sudo` if you have added your user to the `docker` group (or are using rootless docker).
+     Then open [http://localhost:8000](http://localhost:8000).
+
+     This docker container will watch changes in the `docs/source` directory and rebuild the docs automatically
+
+- **Linux**
+
+     First, please install the required [dependencies](#Dependencies)
+
+     Then run the following commands to build the docs website
+
+     ```
+     python3 -m pip install -U pip
+     python3 -m pip install -r docs/requirements.txt
+     cmake -S . -B build -D DEPTHAI_BUILD_DOCS=ON -D DEPTHAI_PYTHON_BUILD_DOCS=ON
+     cmake --build build --parallel --target sphinx
+     python3 -m http.server --bind 0.0.0.0 8000 --directory build/docs/sphinx
+     ```
+
+     Then open [http://localhost:8000](http://localhost:8000).
+
+     This will build documentation based on current sources, so if some new changes will be made, run this command
+     in a new terminal window to update the website source
+
+     ```
+     cmake --build build --parallel --target sphinx
+     ```
+
+     Then refresh your page - it should load the updated website that was just built
+
 ## Troubleshooting
 
 ### Relocation link error
@@ -121,7 +121,7 @@ Build failure on Ubuntu 18.04 ("relocation ..." link error) with gcc 7.4.0 (defa
          sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-8 70
          sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-8 70
 ### Hunter
-Hunter is a CMake-only dependency manager for C/C++ projects. 
+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:
 ```
@@ -145,7 +145,7 @@ del C:/[user]/.hunter
 
 ### LTO - link time optimization
 
-If following message appears: 
+If following message appears:
 ```
 lto1: internal compiler error: in add_symbol_to_partition_1, at lto/lto-partition.c:152
 Please submit a full bug report,

depthai-core

@@ -82,11 +82,11 @@ html_static_path = ['_static']
 html_favicon = '_static/images/favicon.png'
 html_css_files = [
     'css/index.css',
-    'https://docs.luxonis.com/en/gen2/_static/css/navbar.css',
+    'https://docs.luxonis.com/en/latest/_static/css/navbar.css',
 ]
 html_js_files = [
-    'https://docs.luxonis.com/en/gen2/_static/js/navbar.js',
+    'https://docs.luxonis.com/en/latest/_static/js/navbar.js',
 ]
 html_title = 'DepthAI documentation | Luxonis'
 
-intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
+intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}

docs/conf.py.in

@@ -1,3 +1,4 @@
+version: "3"
 services:
   docs:
     build:

docs/docker-compose.yml

@@ -92,6 +92,8 @@ Now, pick a tutorial or code sample and start utilizing Gen2 capabilities
    samples/16_device_queue_event.rst
    samples/17_video_mobilenet.rst
    samples/18_rgb_encoding_mobilenet.rst
+   samples/19_mono_camera_control.rst
+   samples/20_color_rotate_warp.rst
    samples/22_1_tiny_yolo_v3_decoding_on_device.rst
    samples/22_2_tiny_yolo_v4_decoding_on_device.rst
    samples/23_autoexposure_roi.rst

docs/source/index.rst

@@ -16,14 +16,14 @@ Supported Platforms
 
 We keep up-to-date, pre-compiled, libraries for the following platforms.  Note that a new change is that for Ubuntu now also work unchanged for the Jetson/Xavier series:
 
-======================== =========================================== ================================================= ================================================================================
-Platform                 Instructions                                Tutorial                                          Support
-======================== =========================================== ================================================= ================================================================================
-Windows 10               :ref:`Platform dependencies <Windows>`      `Video tutorial <https://youtu.be/ekopKJfcWiE>`__ `Discord <https://discord.com/channels/790680891252932659/798284448323731456>`__
-macOS                    :ref:`Platform dependencies <macOS>`        `Video tutorial <https://youtu.be/0RGmmjed3Hc>`__ `Discord <https://discord.com/channels/790680891252932659/798283911989690368>`__
-Ubuntu & Jetson/Xavier   :ref:`Platform dependencies <Ubuntu>`       `Video tutorial <https://youtu.be/QXeXMaxj4cM>`__ `Discord <https://discord.com/channels/790680891252932659/798302162160451594>`__
-Raspberry Pi             :ref:`Platform dependencies <Raspberry Pi>` `Video tutorial <https://youtu.be/BpUMT-xqwqE>`__ `Discord <https://discord.com/channels/790680891252932659/798302708070350859>`__
-======================== =========================================== ================================================= ================================================================================
+======================== ============================================== ================================================================================
+Platform                 Instructions                                   Support
+======================== ============================================== ================================================================================
+Windows 10               :ref:`Platform dependencies <Windows>`         `Discord <https://discord.com/channels/790680891252932659/798284448323731456>`__
+macOS                    :ref:`Platform dependencies <macOS>`           `Discord <https://discord.com/channels/790680891252932659/798283911989690368>`__
+Ubuntu & Jetson/Xavier   :ref:`Platform dependencies <Ubuntu>`          `Discord <https://discord.com/channels/790680891252932659/798302162160451594>`__
+Raspberry Pi OS          :ref:`Platform dependencies <Raspberry Pi OS>` `Discord <https://discord.com/channels/790680891252932659/798302708070350859>`__
+======================== ============================================== ================================================================================
 
 And the following platforms are also supported by a combination of the community and Luxonis.
 
@@ -34,6 +34,7 @@ Fedora                                                                       `Di
 Robot Operating System                                                       `Discord <https://discord.com/channels/790680891252932659/795749142793420861>`__
 Windows 7              :ref:`WinUSB driver <Windows 7>`                      `Discord <https://discord.com/channels/790680891252932659/798284448323731456>`__
 Docker                 :ref:`Pull and run official images <Docker>`          `Discord <https://discord.com/channels/790680891252932659/796794747275837520>`__
+Kernel Virtual Machine :ref:`Run on KVM <KVM>`                               `Discord <https://discord.com/channels/790680891252932659/819663531003346994>`__
 ====================== ===================================================== ================================================================================
 
 macOS
@@ -147,6 +148,68 @@ Run the :code:`01_rgb_preview.py` example inside a Docker container on a Linux h
 To allow the container to update X11 you may need to run :code:`xhost local:root` on
 the host.
 
+KVM
+***
+
+To access the OAK-D camera in the `Kernel Virtual Machine <https://www.linux-kvm.org/page/Main_Page>`__,  there is a need to attach and detach USB 
+devices on the fly when the host machine detects changes in the USB bus.
+
+OAK-D camera changes the USB device type when it is used by DepthAI API. This happens in backgound when the camera is used natively. 
+But when the camera is used in a virtual environment the situation is different. 
+
+On your host machine, use the following code:
+
+.. code-block:: bash
+
+  SUBSYSTEM=="usb", ACTION=="bind", ENV{ID_VENDOR_ID}=="03e7", MODE="0666", RUN+="/usr/local/bin/movidius_usb_hotplug.sh depthai-vm"
+  SUBSYSTEM=="usb", ACTION=="remove", ENV{PRODUCT}=="3e7/2485/1", ENV{DEVTYPE}=="usb_device", MODE="0666", RUN+="/usr/local/bin/movidius_usb_hotplug.sh depthai-vm"
+  SUBSYSTEM=="usb", ACTION=="remove", ENV{PRODUCT}=="3e7/f63b/100", ENV{DEVTYPE}=="usb_device", MODE="0666", RUN+="/usr/local/bin/movidius_usb_hotplug.sh depthai-vm"
+
+The script that the udev rule is calling (movidius_usb_hotplug.sh) should then attach/detach the USB device to the virtual machine. 
+In this case we need to call :code:`virsh` command. For example, the script could do the following:
+
+.. code-block:: bash
+
+  #!/bin/bash
+  # Abort script execution on errors
+  set -e
+  if [ "${ACTION}" == 'bind' ]; then
+    COMMAND='attach-device'
+  elif [ "${ACTION}" == 'remove' ]; then
+    COMMAND='detach-device'
+    if [ "${PRODUCT}" == '3e7/2485/1' ]; then
+      ID_VENDOR_ID=03e7
+      ID_MODEL_ID=2485
+    fi
+    if [ "${PRODUCT}" == '3e7/f63b/100' ]; then
+      ID_VENDOR_ID=03e7
+      ID_MODEL_ID=f63b
+    fi
+  else
+    echo "Invalid udev ACTION: ${ACTION}" >&2
+    exit 1
+  fi
+  echo "Running virsh ${COMMAND} ${DOMAIN} for ${ID_VENDOR}." >&2
+  virsh "${COMMAND}" "${DOMAIN}" /dev/stdin <<END
+  <hostdev mode='subsystem' type='usb'>
+    <source>
+      <vendor id='0x${ID_VENDOR_ID}'/>
+      <product id='0x${ID_MODEL_ID}'/>
+    </source>
+  </hostdev>
+  END
+  exit 0
+
+
+Note that when the device is disconnected from the USB bus, some udev environmental variables are not available (:code:`ID_VENDOR_ID` or :code:`ID_MODEL_ID`), 
+that is why you need to use :code:`PRODUCT` environmental variable to identify which device has been disconnected.
+
+The virtual machine where DepthAI API application is running should have defined a udev rules that identify the OAK-D camera. 
+The udev rule is decribed `here <https://docs.luxonis.com/en/latest/pages/faq/#does-depthai-work-on-the-nvidia-jetson-series>`__
+
+Solution provided by `Manuel Segarra-Abad <https://github.com/maseabunikie>`__
+
+
 Install from PyPI
 #################
 

docs/source/install.rst

@@ -9,7 +9,7 @@ encoded video over XLINK to the host, saving it to disk as a video file.
 Pressing Ctrl+C will stop the recording and then convert it using ffmpeg into an mp4 to make it
 playable. Note that ffmpeg will need to be installed and runnable for the conversion to mp4 to succeed.
 
-Be careful, this example saves encoded video to your host storage. So if you leave them running,
+Be careful, this example saves encoded video to your host storage. So if you leave it running,
 you could fill up your storage on your host.
 
 

docs/source/samples/04_rgb_encoding.rst

@@ -8,7 +8,7 @@ each, all at 30FPS. Each encoded video stream is transferred over XLINK and save
 Pressing Ctrl+C will stop the recording and then convert it using ffmpeg into an mp4 to make it
 playable. Note that ffmpeg will need to be installed and runnable for the conversion to mp4 to succeed.
 
-Be careful, this example saves encoded video to your host storage. So if you leave them running,
+Be careful, this example saves encoded video to your host storage. So if you leave it running,
 you could fill up your storage on your host.
 
 Demo

docs/source/samples/05_rgb_mono_encoding.rst

@@ -8,7 +8,7 @@ uncompressed frames, processed by ISP, and raw - BayerRG (R_Gr_Gb_B), as read fr
 10-bit packed. See here for the pull request on this capability.
 
 Be careful, this example saves full resolution .png pictures to your host storage. So if you leave
-them running, you could fill up your storage on your host.
+it running, you could fill up your storage on your host.
 
 Demo
 ####