dgpython-azurekinect 0.2.0
Azure Kinect module for dgpython
Requires Python: >=3.8

dgpython-azurekinect
--------------------

This is a Dataguzzler-Python/SpatialNDE2 driver for the Microsoft
Azure Kinect ("Kinect for Azure"/K4A) depth camera.

Note that this version requires SpatialNDE2 version 0.8.0 or later.


Installation
------------

This package requires the Azure Kinect SDK from Microsoft (uses the C
API), Dataguzzler-Python, Cython, and SpatialNDE2. You also need
some basic Python packages: setuptools, setuptools_scm,
build, wheel, and numpy.

The dgpython-azurekinect package installs with the usual "pip install .", but you probably need to tell it where to find the
Azure Kinect SDK files (see below). Make sure that you install into
the same Python environment you are using for SpatialNDE2 and
Dataguzzler-Python

To tell the setup script where to find the Azure Kinect SDK files,
you need to either modify setup.cfg configuring the path to the SDK
in the with-azurekinect parameter:

[build]
with-azurekinect=/usr/local/src/k4a-1.4.1_ubuntu1804

or you can create a new
setup_local.cfg (similar to setup.cfg) with your path configured.
If you do the latter, you must set the DIST_EXTRA_CONFIG environment
variable to point at your setup_local.cfg, as illustrated in
setupcmd.sh (Linux) and setupcmd.bat (Windows).

To perform the install, if you modified setup.cfg you can just
(possibly as root or administrator):

pip install --no-deps --no-build-isolation .

If you created setup_local.cfg, instead run:

sudo ./setupcmd.sh   (Linux; central install)

or,

./setupcmd.sh   (Linux; user install)

or,

.\setupcmd.bat  (Windows)  



NOTE: If you upgrade spatialnde2 it is highly recommended that, after
rebuilding and performing the Python reinstall ("python setup.py
install" from the spatialnde2 build directory) that you clean out your
dgpython-azurekinect build/ and dist/ directories and do a full
reinstall, e.g. from the dgpython-azurekinect directory:

      WINDOWS:
            rmdir /s build dest
            setupcmd.bat
      LINUX:
            rm -r build/ dest/
            bash setupcmd.sh

Usage
-----

This package is designed to be used from Dataguzzler-Python. In your
Dataguzzler-Python configuration (.dgp file):


  import dgpython_azurekinect as ak
  k4a = ak.K4A("k4a",recdb, None, "/k4achan" )
  k4a.running=True # Start capture

The above configuration will start live capture into the
"/k4achan" channel of the SpatialNDE2 recording database. 

The parameters to the K4A constructor are:
  1. The module name
  2. The SpatialNDE2 recording database
  3. The serial number of the camera to open, or None to open the
     only camera available
  4. Device recording database depth channel name
  5. Device recording database color channel name (optional)

There is an alternative class, K4AFile, that extracts frames from
a .mkv file saved by the k4arecorder application. The parameters
are the same except the device serial number is replaced by the
filename for the .mkv file.


Configuring the Azure Kinect camera
-----------------------------------

Configuration is controlled and queried through a number of
Python properties of the K4A object. These are assigned
similar to "k4a.running=True" in the example above.

Many of the properties currently use values enumerated
in the ak.syms dictionary that match the low level numbers
used in the Azure Kinect C API. A future version may convert
the numeric properties to string properties. See the Azure
Kinect API manual for more information. 

Property         Function         Type     Possible values
--------------------------------------------------------------
running          Enable capture   boolean  True, False
color_format     Color cam. fmt.  integer  ak.syms.K4A_IMAGE_FORMAT_COLOR_...
color_resolution Color cam. res.  integer  ak.syms.K4A_COLOR_RESOLUTION_...
depth_mode       Depth cam. res.  integer  ak.syms.K4A_DEPTH_MODE_...
camera_fps       Frames per sec.  integer  ak.syms.K4A_FRAMES_PER_SECOND_...
synchronized_images_only          boolean  True, False
depth_delay_off_color_usec        integer  Magn. less than one capt. period
wired_sync_mode  Multi-camera     integer  ak.syms.K4A_WIRED_SYNC_MODE_...
subordinate_delay_off_master_usec integer  Up to one capture period
disable_streaming_indicator       boolean  True, False
point_cloud_frame                 integer  K4A_CALIBRATION_TYPE_...
depth_data_mode  Depth cam. acq.  string   "IMAGE" or "POINTCLOUD"
depth_data_type  Depth cam. acq.  string   "INT" or "FLOAT"
calcsync         Wait for math    boolean  True, False

Dynamic Metadata
----------------
This driver supports dynamic metadata on live acquisitions.
Call the .dynamic_metadata.AddStaticMetaDatum() and/or
.dynamic_metadata.AddDynamicMetaDatum() methods, e.g.

  k4a.dynamic_metadata.AddStaticMetaDatum("/k4achan","testmd","testmd_value")
  k4a.dynamic_metadata.AddDynamicMetaDatum("/k4achan","testmd2",lambda: k4a.depth_mode)


Examples
--------
There is an example dataguzzler-python configuration for live capture,
demos/acquire_azurekinect.dgp. Run it with:
  dataguzzler-python acquire_azurekinect.dgp

There is an example dataguzzler-python configuration for playing back
sequences recorded using the k4arecorder application,
demos/playback_azurekinect.dgp. Run it with:
  dataguzzler-python playback_azurekinect.dgp --filename <file.mkv>