Python API: Adding docstrings *.py files and a Doxygen settings file …

…to generate the html documentation for the Python API.

src/python/k4a/docs/building.md

@@ -69,11 +69,18 @@ The following tools are optional:
       ./<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 this
+settings file to create the html documentation.
+
 ## 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>
+      pip install <k4a*.whl>
+
+Once installed, the user can "import k4a" in their python code.

src/python/k4a/docs/testing.md

@@ -29,7 +29,9 @@ The following are required in order to run the Python K4A tests.
       ./<env_name>/Scripts/activate
 
 3. Install the k4a package in development mode. This is required in order to
-   automatically install required Python packages for running the tests.
+   automatically install required Python packages for running the tests, as
+   well as to install the code with the k4a package as the root of the 
+   subpackages and modules.
       pip install -e .[test]   (include "[test]" with square brackets)
 
 4. Run the tests in python. To capture the results, use an additional --junit-xml=./test_results.xml option.

src/python/k4a/src/k4a/_bindings/calibration.py

@@ -1,9 +1,11 @@
-'''
-calibration.py
+'''!
+@file calibration.py
 
 Defines a Calibration class that is a container for a device calibration.
 
-Copyright (C) Microsoft Corporation. All rights reserved.
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+Kinect For Azure SDK.
 '''
 
 import ctypes as _ctypes
@@ -13,7 +15,18 @@
 from .k4a import k4a_calibration_get_from_raw
 
 class Calibration:
-
+    '''! Camera calibration contains intrinsic and extrinsic calibration
+    information for a camera.
+
+    Name              | Type                  | Description
+    ----------------- | --------------------- | ----------------------------------------------
+    extrinsics        | CalibrationExtrinsics | Extrinsic calibration data.
+    intrinsics        | CalibrationIntrinsics | Intrinsic calibration data.
+    resolution_width  | int                   | Resolution width of the calibration sensor.
+    resolution_height | int                   | Resolution height of the calibration sensor.
+    metric_radius     | float                 | Max FOV of the camera.
+    '''
+
     def __init__(self, _calibration:_Calibration=None):
         self._calibration = _calibration
         if self._calibration is None:

src/python/k4a/src/k4a/_bindings/capture.py

@@ -1,10 +1,12 @@
-'''
-capture.py
+'''!
+@file capture.py
 
 Defines a Capture class that is a container for a single capture of data
 from an Azure Kinect device.
 
-Copyright (C) Microsoft Corporation. All rights reserved.
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+Kinect For Azure SDK.
 '''
 
 import ctypes as _ctypes
@@ -22,8 +24,53 @@
 from .image import Image
 
 class Capture:
-
-    def __init__(self, capture_handle:_CaptureHandle=None):
+    '''! A class that represents a capture from an Azure Kinect device.
+
+    Property Name | Type  | R/W | Description
+    ------------- | ----- | --- | -----------------------------------------
+    color         | Image | R/W | The color image container.
+    depth         | Image | R/W | The depth image container.
+    ir            | Image | R/W | The IR image container.
+    temperature   | float | R/W | The temperature
+
+    @remarks 
+    - A capture represents a set of images that were captured by a 
+        device at approximately the same time. A capture may have a color, IR,
+        and depth image. A capture may have up to one image of each type. A 
+        capture may have no image for a given type as well.
+
+    @remarks 
+    - Do not use the Capture() constructor to get a Capture instance. It
+        will return an object that does not have a handle to the capture
+        resources held by the SDK. Instead, use the create() function.
+
+    @remarks 
+    - Captures also store a temperature value which represents the 
+        temperature of the device at the time of the capture.
+
+    @remarks 
+    - While all the images associated with the capture were collected at
+        approximately the same time, each image has an individual timestamp 
+        which may differ from each other. If the device was configured to 
+        capture depth and color images separated by a delay, 
+        Device.get_capture() will return a capture containing both image types 
+        separated by the configured delay.
+
+    @remarks 
+    - Empty captures are created with create().
+
+    @remarks 
+    - Captures can be obtained from a Device object using get_capture().
+
+    @remarks 
+    - A Capture object may be copied or deep copied. A shallow copy
+        shares the same images as the original, and any changes in one will
+        affect the other. A deep copy does not share any resources with the
+        original, and changes in one will not affect the other. In both shallow
+        and deep copies, deleting one will have no effects on the other.
+    '''
+
+    def __init__(self, capture_handle:_CaptureHandle):
         self._capture_handle = capture_handle
         self._color = None
         self._depth = None
@@ -32,6 +79,14 @@ def __init__(self, capture_handle:_CaptureHandle=None):
 
     @staticmethod
     def create():
+        '''! Create an empty capture object.
+
+        @returns Capture instance with empty contents.
+
+        @remarks 
+        - If unsuccessful, None is returned.
+        '''
+
         capture = None
 
         # Create a capture.