Python api development

src/python/k4a/README.md

@@ -0,0 +1,77 @@
+# Azure Kinect Python API(K4A)
+
+Welcome to the Azure Kinect Python API! We hope you can use it to build many great applications and participate in the project. Don't be shy to ask questions, and provide feedback. See [Azure.com/Kinect](https://Azure.com/kinect) for device
+info and available documentation.
+
+## Introduction
+
+**K4A** is a Python user mode API to read data from your Azure Kinect device.
+
+## Why use K4A
+
+K4A enables you to get the most out of your Azure Kinect camera. Features include:
+
+* Depth camera access
+* RGB camera access and control (e.g. exposure and white balance)
+* Motion sensor (gyroscope and accelerometer) access
+* Synchronized Depth-RGB camera streaming with configurable delay between cameras
+* External device synchronization control with configurable delay offset between devices
+* Camera frame meta-data access for image resolution, timestamp and temperature
+* Device calibration data access
+
+All image data is encapsulated in numpy arrays, allowing Python users to easily use the data in OpenCV
+and other packages that work with numpy arrays.
+
+## Documentation
+
+API documentation will soon be made available.
+
+## Building
+
+K4A uses Python's setuptools to build a wheel file for distribution. 
+For instructions on how to build this distributable, please see
+[building](docs/building.md).
+
+## Testing
+
+For information on writing or running tests, please see [testing](docs/testing.md).
+
+## Contribute
+
+We welcome your contributions! Please see the [contribution guidelines](../../../CONTRIBUTING.md).
+
+## Feedback
+
+For SDK feedback or to report a bug, please file a [GitHub Issue](https://github.com/Microsoft/Azure-Kinect-Sensor-SDK/issues). For general suggestions or ideas, visit our [feedback forum](https://aka.ms/azurekinectfeedback).
+
+## Sample Code
+
+Sample Python code that uses the Python API can be found in the examples/ folder. See [examples](docs/examples.md).
+
+## Q&A
+
+Welcome to the [Q&A](kinect-qa.md) corner!
+
+## Join Our Developer Program
+
+Complete your developer profile [here](https://aka.ms/iwantmr) to get connected with our Mixed Reality Developer Program. You will receive the latest on our developer tools, events, and early access offers.
+
+## Code of Conduct
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/)
+or contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
+
+## Reporting Security Issues
+Security issues and bugs should be reported privately, via email, to the
+Microsoft Security Response Center (MSRC) at <[[email protected]](mailto:[email protected])>.
+You should receive a response within 24 hours. If for some reason you do not, please follow up via
+email to ensure we received your original message. Further information, including the
+[MSRC PGP](https://technet.microsoft.com/en-us/security/dn606155) key, can be found in the
+[Security TechCenter](https://technet.microsoft.com/en-us/security/default).
+
+## License and Microsoft Support for Azure Kinect Sensor SDK
+
+[MIT License](../../../LICENSE)
+
+[Microsoft Support for Azure Kinect Sensor SDK](../../../microsoft-support.md)

src/python/k4a/build_wheel.csh

@@ -0,0 +1,80 @@
+#!/bin/bash
+
+# Script to automate creation of the Python wheel for the k4a library.
+# In Ubuntu, the command for the base installation of Python 3 is python3.
+# Also, pip and venv may need to be installed manually before running this
+# script since it may not come with the base installation of Python 3.
+# To get pip: sudo apt install python3-pip
+# To get venv: sudo apt install python3-venv
+# To get doxygen: sudo apt install doxygen
+
+# Get the directory where this script lives.
+SOURCE="${BASH_SOURCE[0]}"
+while [ -h "$SOURCE" ]; do # resolve $SOURCE until the file is no longer a symlink
+  DIR="$( cd -P "$( dirname "$SOURCE" )" >/dev/null 2>&1 && pwd )"
+  SOURCE="$(readlink "$SOURCE")"
+  [[ $SOURCE != /* ]] && SOURCE="$DIR/$SOURCE" # if $SOURCE was a relative symlink, we need to resolve it relative to the path where the symlink file was located
+done
+DIR="$( cd -P "$( dirname "$SOURCE" )" >/dev/null 2>&1 && pwd )"
+
+# Check that the k4a.so and depth_engine.so have been copied into the _libs/ folder.
+# Because these dlls may not be located in a standard place, leave it to the developer
+# to manually copy them into the _libs/ folder.
+if [ ! -f "$DIR/src/k4a/_libs/libk4a.so" ] && [ ! -h "$DIR/src/k4a/_libs/libk4a.so" ]; then
+    echo "File not found: $DIR/src/k4a/_libs/libk4a.so"
+    echo "Please manually copy the k4a library into that folder."
+    return 1
+fi
+
+if [ ! -f "$DIR/src/k4a/_libs/libk4a"*"/libdepthengine"* ] && [ ! -h "$DIR/src/k4a/_libs/libk4a"*"/libdepthengine"* ]; then
+    echo "File not found: $DIR/src/k4a/_libs/libk4a*/libdepthengine*"
+    echo "Please manually copy the depth engine library into that folder."
+    return 1
+fi
+
+# Create a virtual environment and activate it.
+echo "Creating a Python virtual environment."
+
+if [ -d "temp_build_venv" ]; then
+    rm -rf "temp_build_venv"
+fi
+
+if [ -d "build" ]; then
+    rm -rf "build"
+fi
+
+python3 -m venv temp_build_venv
+source ./temp_build_venv/bin/activate
+
+# Install the package in editable mode so that it installs dependencies. These are needed for sphinx docs.
+python -m pip install --upgrade pip
+pip install -e .
+
+# Build the .whl file and place it in a build/ folder.
+pip install wheel
+pip wheel . -w build
+
+# Build the docs and move them to the build/ folder. doxygen must be in the path.
+if command -v doxygen &> /dev/null
+then
+    mkdir ./build/docs
+    doxygen ./Doxyfile
+else
+    echo "doxygen not found, skipping building the documentation."
+fi
+
+# Create a convenient documentation.html that redirects to the index.html that doxygen generates.
+echo '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
+<meta http-equiv="X-UA-Compatible" content="IE=9"/>
+<meta http-equiv="REFRESH" content="0;URL=html/index.html">
+</html>' > ./build/docs/documentation.html
+
+
+# Deactivate virtual environment and delete it.
+deactivate
+rm -rf "temp_build_venv"
+
+echo "Done creating k4a package wheel."

src/python/k4a/build_wheel.ps1

@@ -0,0 +1,65 @@
+# Script to automate creation of the Python wheel for the k4a library.
+
+# Check that the k4a.dll and depth_engine.dll have been copied into the _libs/ folder.
+# Because these dlls may not be located in a standard place, leave it to the developer
+# to manually copy them into the _libs/ folder.
+If (-not (Test-Path -Path "$PSScriptRoot\src\k4a\_libs\k4a.dll")) {
+    Write-Host "File not found: $PSScriptRoot\src\k4a\_libs\k4a.dll"
+    Write-Host "Please manually copy the k4a library into that folder."
+    exit 1
+}
+
+If (-not(Test-Path -Path "$PSScriptRoot\src\k4a\_libs\depthengine*.dll")) {
+    Write-Host "File not found: $PSScriptRoot\src\k4a\_libs\depthengine*.dll"
+    Write-Host "Please manually copy the depth engine library into that folder."
+    exit 1
+}
+
+# Create a virtual environment and activate it.
+Write-Host "Creating a Python virtual environment."
+
+If (Test-Path -Path "temp_build_venv") {
+    Remove-Item -LiteralPath "temp_build_venv" -Force -Recurse
+}
+
+If (Test-Path -Path "build") {
+    Remove-Item -LiteralPath "build" -Force -Recurse
+}
+
+python -m venv temp_build_venv
+./temp_build_venv/Scripts/activate
+
+# Install the package in editable mode so that it installs dependencies. These are needed for sphinx docs.
+python -m pip install --upgrade pip
+pip install -e .
+
+# Build the .whl file and place it in a build/ folder.
+pip install wheel
+pip wheel . -w build
+Remove-Item ./build/* -Exclude k4a*.whl -Recurse -Force
+
+
+# Build the docs and move them to the build/ folder. doxygen must be in the path.
+if (Get-Command doxygen -errorAction SilentlyContinue) {
+    mkdir ./build/docs
+    doxygen ./Doxyfile
+
+    # Create a convenient documentation.html that redirects to the index.html that doxygen generates.
+    '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+    <html xmlns="http://www.w3.org/1999/xhtml">
+    <head>
+    <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
+    <meta http-equiv="X-UA-Compatible" content="IE=9"/>
+    <meta http-equiv="REFRESH" content="0;URL=html/index.html">
+    </html>' > ./build/docs/documentation.html
+}
+else {
+    Write-Host "doxygen not found, skipping building the documentation."
+}
+
+
+# Deactivate virtual environment and delete it.
+./temp_build_venv/Scripts/deactivate.bat
+Remove-Item -LiteralPath "temp_build_venv" -Force -Recurse
+
+Write-Host "Done creating k4a package wheel."

src/python/k4a/docs/building.md

@@ -0,0 +1,142 @@
+# Building Azure Kinect Python API(K4A)
+
+This information is for how to build your own copy of the Python wheel. 
+If you need to build from source, you have to clone the repository to ensure all the submodule dependencies in place.
+
+## Support Configurations
+
+Python:
+* Greater than or equal to version 3.6.
+
+Architectures: 
+* amd64
+* x86 (limited, no testing is performed)
+
+OS:
+* Windows
+* Linux
+
+## Dependencies
+
+Building on Windows and Linux requires an active internet connection. Part of the
+build will require downloading dependencies.
+
+The following dependencies are for both Windows and Linux:
+
+* [python3](https://www.python.org/getit/). During the install make sure to add
+  python to path.
+
+* [k4a library](../../../../docs/building.md)
+  The k4a library can be built from the repository or the SDK can be downloaded
+  for the binary. The Windows library is k4a.dll, and the Linux library is libk4a.so.
+  The k4a binary needs to be copied to the host system and added 
+  to the path src/python/k4a/src/k4a/_libs in this repository before building.
+
+* [Depth Engine](../../../../docs/depthengine.md). 
+  The depth engine (DE) is a closed source binary shipped with the
+  SDK installer. The DE binary needs to be copied to the host system and added 
+  to the path src/python/k4a/src/k4a/_libs in this repository before building.
+
+The following dependencies are for both Windows and Linux, but in Windows they seems to be
+automatically part of a Python installation, while on Linux they need to be installed
+separately:
+
+* Python module pip  
+   On Linux, install pip with:  
+   `sudo apt install python3-pip -y`  
+
+* Python module venv  
+   On Linux, install venv with:  
+   `sudo apt install python3-venv -y`
+
+The following tools are optional:
+
+* [doxygen](https://github.com/doxygen/doxygen)
+  Required for building documentation. If not installed, html documentation will not be built.
+
+
+## Building
+
+### Building using a powershell script (Windows)
+
+1. Copy the k4a and DE binaries into the folder src/python/k4a/src/k4a/_libs. 
+   The file name for the k4a library MUST be k4a.dll.
+
+    >**Note:** To create a Windows-only wheel, the .dll for Windows need to copied into the folder. 
+    >Python will look for "k4a.dll" which will also load the depth engine dll.
+
+    >**Note:** An example of the files in _libs for Windows are: 
+    >- k4a.dll
+    >- depthengine\_2\_0.dll
+
+2. In a powershell terminal, run the script src/python/k4a/build_wheel.ps1.
+   This will create the .whl file in a build/ folder.
+
+### Building using a bash script (Linux)
+
+1. Copy the k4a and DE binaries into the folder src/python/k4a/src/k4a/_libs.
+   The file name for the k4a library MUST be libk4a.so. The depth engine library must be in a
+   folder named libk4a\<ver\>, where \<ver\> is the version major.minor of the k4a library
+   (e.g. _libs constains libk4a1.4/libdepthengine.so.2.0).
+
+    >**Note:** To create a Linux-only wheel, the the .so for Linux need to copied into the folder. 
+    >Python will look for "libk4a.so" in Linux which will also load the depth engine dll.
+
+    >**Note:** An example of the files in _libs for Linux are: 
+    >- libk4a.so, a soft link to libk4a.1.4
+    >- libk4a.so.1.4, a soft link to libk4a.1.4.0
+    >- libk4a.so.1.4.1, the k4a library
+    >- depthengine.so.2.0, the depth engine library in a sub-folder
+
+2. In a terminal, source the script src/python/k4a/build_wheel.csh.
+   This will create the .whl file in a build/ folder.
+
+    `cd <repo_root>/src/python/k4a`  
+    `source build_wheel.csh`  
+
+### Building using a command line terminal (cross platform)
+
+1. Copy the k4a and DE binaries into the folder src/python/k4a/src/k4a/_libs.
+   The file names for the k4a library MUST be k4a.dll (for Windows) and libk4a.so (for Linux).
+
+    >**Note:** To create a cross-platform wheel, the .dll for Windows and the .so for Linux need to
+    >copied into the folder. Python will look for "k4a.dll" in Windows and "libk4a.so" in Linux.
+
+    >**Note:** An example of the files in _libs for cross-platform compatibility are: 
+    >- libk4a.so, a soft link to libk4a.1.4
+    >- libk4a.so.1.4, a soft link to libk4a.1.4.0
+    >- libk4a.so.1.4.1
+    >- depthengine.so.2.0
+    >- k4a.dll
+    >- depthengine\_2\_0.dll
+
+2. In a command line terminal, create a Python virtual environment and activate it (do not include brackets):
+    `cd <repo_root>/src/python/k4a`  
+    `python -m venv <env_name>`  
+    `./<env_name>/Scripts/activate`  
+
+3. Build the .whl file and place it in a build/ folder.
+    `pip install wheel`  
+    `pip wheel . -w build`  
+
+4. Deactivate the virtual environment and delete it.  
+    `./<env_name>/Scripts/deactivate.bat`  
+    Delete the directory `<env_name>`.
+
+### Building the HTML Documentation
+
+A Doxygen settings file is provided in the project directory. Run doxygen using the
+settings file to create the html documentation. 
+
+The build scripts will run doxygen as part of the build.
+
+## Installing
+
+The build process will create a k4a*.whl wheel file that can be installed via pip.
+The wheel file can be distributed and installed as follows.
+
+1. In a command line terminal, install the k4a python library via pip.
+   Replace <k4a*.whl> with the name of the wheel file.
+    `pip install <k4a*.whl>`
+
+Once installed, the user can "import k4a" in their python code.