Python c api update #1552

JonathanESantos · 2021-03-30T19:39:04Z

Fixes #40, #917

Description of the changes:

The public C API is modified:
- k4a_depth_mode_t removed from public C API (retained in k4ainternal/modes.h) and replaced with function k4a_device_get_depth_mode() which returns a k4a_depth_mode_info_t that holds the equivalent mode enum value and additional info about that depth mode.
- k4a_color_resolution_t removed from public C API (retained in k4ainternal/modes.h) and replaced with function k4a_device_get_color_mode() which returns a k4a_color_mode_info_t that holds the equivalent resolution enum value and additional info about that color resolution mode.
- k4a_fps_t removed from public C API (retained in k4ainternal/modes.h) and replaced with function k4a_device_get_fps_mode() which returns a k4a_fps_mode_info_t that holds the equivalent fps enum value and additional info about that fps mode.
- Added a function k4a_device_get_info() which returns some information about the attached device, including a list of capabilities that it supports (depth, color, IMU, etc.).
- All functions that accepted as input a k4a_depth_mode_t, k4a_color_resolution_t, or k4a_fps_t have been modified to accept the input as an int. The value to pass in should be the corresponding mode_id field of the structures k4a_depth_mode_info_t, k4a_color_mode_info_t, or k4a_fps_mode_info_t, respectively.
The corresponding changes have been applied to the C# API.
The corresponding changes have been applied to the C++ API.
The corresponding changes have been applied to the Python API.
The k4aviewer support for microphone recording is conditionally compiled based on a compiler DEFINE, which by default is set NOT to compile microphone support into the k4aviewer.

Before submitting a Pull Request:

I reviewed CONTRIBUTING.md
I built my changes locally
I ran the unit tests
I ran the functional tests with a device
I ran the performance tests with a device

I tested changes on:

Windows
Linux

C API was tested with automated unit tests and functional tests.
C# API was tested with automated unit tests and functional tests.
C++ API is untested.
Python API is tested with new automated unit tests and functional tests added.
k4arecorder is manually tested for all allowed combinations of color, depth, and fps modes.
k4aviewer is manually tested for all allowed combinations of color, depth, and fps modes, including playback.

…int the contents of the struct.

…s folder before making the wheel.

…t are exposed in the dll.

TODO: Test the following functions: k4a_calibration_3d_to_3d k4a_calibration_2d_to_3d k4a_calibration_3d_to_2d k4a_calibration_2d_to_2d k4a_calibration_color_2d_to_depth_2d k4a_transformation_create k4a_transformation_destroy k4a_transformation_depth_image_to_color_camera k4a_transformation_depth_image_to_color_camera_custom k4a_transformation_color_image_to_depth_camera k4a_transformation_depth_image_to_point_cloud

… for the transformation functions. The build_wheel.ps1 script will create a win-amd64 only python wheel.

…se tests that fail.

…library wheel file.

… folder. By doing this, when a user "import k4a", only the exported symbols will be visible. Everything else will be under a _bindings symbol.

…o that it aligns more with k4a.h and k4atypes.h.

…e. This seems redundant since the subpackage _bindings already has an underscore.

…device_handle.

…nd image functions and handles. Adding test files.

…e, causing import k4a to fail.

… Calibration classes. Fixing shallow copy and deep copy of Image objects.

Fixing minor bugs in the Transformation class, and fixing issues with the unit tests regarding starting and stopping the imu and getting imu samples.

…to generate the html documentation for the Python API.

… in the example code image_transformations.py.

…tion using doxygen. Fixing several bugs: 1. The build_wheel.ps1 had extra arguments that breaks the building of the wheel. 2. The Transformation class had some parameters renamed but the renamed vars were not changed in the functions accordingly. 3. The Transformation class removed an unneeded param in depth_image_to_color_camera_custom but did not remove it in the test code.

…and Linux. Adding a bash script to automate generating the wheel file in Ubuntu (Linux).

… both Windows and Linux. Doing it now.

…ll try to load. In Windows, the library names must be k4a.dll and depthengine.dll. In Linux, the library names must be libk4a.so and libdepthengine.so. If the libraries have different names, the user should create symlinks and point it to the actual library using relative addressing.

…engine.so and libk4a.so file names.

…sts. Also renaming the tests so that they can be filtered into unit, functional_fast, functional, and perf tests.

…ll, which makes it more obvious what the intent is rather than a simple cast.

…from being set randomly.

…num.

…t users have direct access to the bitmap of capabilities.

…s that do not modify the instance.

…r file to consolidate the multiple definitions in various files into one file.

…n compilation unit and static library. This static library should only be used internally; external tools should use the k4a API. There is one notable place where an external tool uses this backdoor approach to get mode information: the recorder and playback. This is because the information saved in a matroska file consists only of the mode ids and not the full mode info struct. Upon playback, the mode info struct is reconstructed without the presence of a device by using this backdoor approach using k4ainternal/modes.h rather than through k4a/k4a.h. The consequence of this is that it is tied to Azure Kinect modes and will not work for other devices that have different modes. The optimal solution is to save the full mode info structs in the matroska file and reconstructed upon reading.

…o_t field was changed from uint32_t to a union, and when k4ainternal/modes.h implementation was put in its own library unit.

Merge branch 'develop' into python_c_api_update # Conflicts: # examples/fastpointcloud/main.cpp # examples/green_screen/main.cpp # examples/k4arecord_custom_track/main.c # examples/opencv_compatibility/main.cpp # examples/streaming/main.c # examples/transformation/main.cpp # examples/undistort/main.cpp # examples/viewer/opengl/main.cpp # src/csharp/SDK/ColorModeInfo.cs # src/csharp/SDK/DepthModeInfo.cs # src/csharp/SDK/DeviceInfo.cs # src/csharp/SDK/FPSModeInfo.cs # src/csharp/Tests/UnitTests/DeviceFunctionTests.cs # src/python/k4a/build_wheel.csh # src/python/k4a/build_wheel.ps1 # src/python/k4a/docs/building.md # src/python/k4a/docs/examples.md # src/python/k4a/docs/testing.md # src/python/k4a/examples/image_transformations.py # src/python/k4a/examples/simple_viewer.py # src/python/k4a/examples/the_basics.py # src/python/k4a/src/k4a/__init__.py # src/python/k4a/src/k4a/_bindings/calibration.py # src/python/k4a/src/k4a/_bindings/device.py # src/python/k4a/src/k4a/_bindings/image.py # src/python/k4a/src/k4a/_bindings/k4a.py # src/python/k4a/src/k4a/_bindings/k4atypes.py # src/python/k4a/src/k4a/_libs/README.md # src/python/k4a/tests/test_config.py # src/python/k4a/tests/test_functional_api_azurekinect.py # src/python/k4a/tests/test_functional_ctypes_azurekinect.py # src/python/k4a/tests/test_unit_k4atypes.py # tools/k4arecorder/main.cpp # tools/k4aviewer/k4adevicedockcontrol.cpp

…t so that in the logger callback, the context is passed in as the type of python object that the user passed in to the DLL. This makes it easier for the user since there is no casting required to get back the context that is passed in.

resuther-msft

Was able to run and pass all tests except for 9 transformation tests and 3 Ctypes tests. Transformation tests failing because some tests are not defined. Ctypes tests failing assertions. (see attached test results)
Script to build wheel should use script root for pip install commands to enable execution from anywhere.
Several lines in file src/python/k4a/src/k4a/_bindings/k4a.py should have spaces added surrounding = to maintain consistency.
akdk_PR1552_unit_tests_results.txt
Lines: 166, 172, 178, 184, 190, 196, 202, 208, 218, 233, 242, 248, 254, 260, 266, 272, 284, 290, 296, 302, 308, 314, 326, 332, 338, 344, 356.
Otherwise the python implementation looks good and all three examples run great.

resuther-msft · 2021-04-14T23:18:50Z

src/python/k4a/src/k4a/__init__.py

@@ -1,5 +1,6 @@
 from ._bindings.k4atypes import *
 from ._bindings.device import Device
+from ._bindings.device import logging_message_cb, set_logging_callback


Is there a reason you have lines 2 and 3 separate? ie. a reason not to combine the lines as "from ._bindings.device import Device, logging_message_cb, set_logging_callback"

resuther-msft · 2021-04-15T00:06:06Z

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

-#                                                   const k4a_depth_mode_t depth_mode,
-#                                                   const k4a_color_resolution_t color_resolution,
+#                                                   const uint32_t depth_mode_id,
+#                                                   const uint3_t color_mode_id,


This should be uint32_t not uint3_t

resuther-msft · 2021-04-15T00:19:01Z

src/python/k4a/src/k4a/_bindings/k4atypes.py

-        camera_fps:EFramesPerSecond=EFramesPerSecond.FPS_5,
+        color_mode_id:int=0, # 720P
+        depth_mode_id:int=0, # OFF
+        fps_mode_id:int=0, # FPS_0


Is default FPS really Zero (not Five)?

resuther-msft · 2021-04-15T00:27:59Z

src/python/k4a/tests/mock_k4a_dll_azurekinect.py

+
+    # Just return success.
+    status = k4a.EBufferStatus.SUCCEEDED
+    return status


No newline at end of file

resuther-msft · 2021-04-15T17:40:27Z

src/python/k4a/tests/test_functional_ctypes_azurekinect.py

+
+                        self.assertTrue(k4a.K4A_SUCCEEDED(status))
+                        self.assertEqual(valid_int_flag.value, 1)
+
 if __name__ == '__main__':
    unittest.main()


No newline at the end of file

resuther-msft · 2021-04-15T17:50:10Z

src/python/k4a/tests/test_unit_k4atypes.py

+
+        s = capability.__str__()
+        self.assertIsInstance(s, str)
+

 if __name__ == '__main__':
    unittest.main()


No newline at the end of file

resuther-msft · 2021-04-15T17:58:25Z

docs/refactor.md

@@ -0,0 +1,299 @@
+# Changes to the Kinect SDK API surface


Should have additional formatting to make the document easier to read. ie using code blocks for code, enum definitions, and struct definitions.

include/k4a/k4a.h

JonathanESantos and others added 30 commits January 28, 2021 12:00

Python k4a api: Adding __repr__() functions to structs in order to pr…

e2e4059

…int the contents of the struct.

Python k4a api: Adding a check that the required dlls are in the _lib…

f42a5c4

…s folder before making the wheel.

Python k4a api: Adding the rest of the bindings for the functions tha…

5070cf7

…t are exposed in the dll.

Python k4a: Adding missing enum in color resolution, and adding tests…

c9f4bef

… for the transformation functions. The build_wheel.ps1 script will create a win-amd64 only python wheel.

Python k4a: Changing @unittest.skip to @unittest.expectedfail for tho…

bce53d8

…se tests that fail.

Python k4a: Updating docs. Removing platform tag in building the k4a …

f83b712

…library wheel file.

Python API: Renaming enums and structs to Python naming convention.

3f6bd9d

Python API: Moving all internal files and symbols into the _bindings/…

715bbe6

… folder. By doing this, when a user "import k4a", only the exported symbols will be visible. Everything else will be under a _bindings symbol.

Python API: Moving handle structs from _k4a.py back to _k4atypes.py s…

3975dea

…o that it aligns more with k4a.h and k4atypes.h.

Renaming modules inside _bindings subpackage to not include underscor…

3035f3a

…e. This seems redundant since the subpackage _bindings already has an underscore.

Python api: Adding Device class which corresponds to a device with a …

33ec27a

…device_handle.

Python API: Adding capture and image classes to encapsulate capture a…

6b57ecb

…nd image functions and handles. Adding test files.

Python API: Bug in Image class was missing a height_pixels in one lin…

2e89eee

…e, causing import k4a to fail.

Python API: Adding Calibration and Transformation wrapper classes.

e939095

Python API: Renaming a test file.

e02b436

Python API: Adding more tests to test the Device, Capture, Image, and…

33dda28

… Calibration classes. Fixing shallow copy and deep copy of Image objects.

Python API: Fixing transformation functions and their tests.

15bc738

Python API: Adding example code that makes use of the Python API.

e966425

Fixing minor bugs in the Transformation class, and fixing issues with the unit tests regarding starting and stopping the imu and getting imu samples.

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

43c6123

…to generate the html documentation for the Python API.

Python API: Adding a main page to the documentation, and fixing a bug…

c17ebbf

… in the example code image_transformations.py.

Making minor changes to get this k4a package to work in both Windows …

b294cde

…and Linux. Adding a bash script to automate generating the wheel file in Ubuntu (Linux).

Forgot to commit the minor changes to get this k4a package to work in…

1ac1abe

… both Windows and Linux. Doing it now.

Python API: Modifying the build_wheel.csh script to look for libdepth…

d1b46ce

…engine.so and libk4a.so file names.

Python API: Updating building.md for clarity.

ebd650e

Python API: Fixing bug in tests that causes failure in some of the te…

3d66cba

…sts. Also renaming the tests so that they can be filtered into unit, functional_fast, functional, and perf tests.

Fix broken Linux build.

a5f6512

k4a: ninja clangformat made these formatting changes.

b4df263

AntonClaytonBursch and others added 24 commits March 29, 2021 10:41

minor fixes to examples

3a9d29a

clangformat changes, and deleting a file that should not be checked in.

708bd79

more minor fixes to examples

8ea7069

quick clang format error in streaming example

5adee35

Adding a conversion function to go from k4a_fps_t to fps.

938c1f6

Reverting converting from k4a_fps_t to uint32_t back to a function ca…

f4a7835

…ll, which makes it more obvious what the intent is rather than a simple cast.

Fixing an issue with multidevice.cpp that could prevent an FPS value …

13d103c

…from being set randomly.

Simplifying parsing the --fps parameter and converting to k4a_fps_t e…

2c6c3c7

…num.

Making the capabilities field of the k4a_device_info_t a union so tha…

b25dcc5

…t users have direct access to the bitmap of capabilities.

Putting const qualifier in k4atypes.hpp for new Device class function…

2bf8ab6

…s that do not modify the instance.

Moving definition of usb vendor id and product ids into its own heade…

141901e

…r file to consolidate the multiple definitions in various files into one file.

Removing stale comments in k4a.c.

ee5596d

code revisions

2ed3382

moved get device mode ids into seperate functions in the examples

516186b

get mode id from mode info structs in get mode ids functions in examples

776453d

Fixing build errors in Linux that were introduced when k4a_device_inf…

d8f8161

…o_t field was changed from uint32_t to a union, and when k4ainternal/modes.h implementation was put in its own library unit.

Fixing a misnamed variable in fastpointcloud/main.cpp.

acfda75

change for code revision

74b9009

More code review changes.

8982502

Adding docstrings to k4a_device_capabilities_t enum.

f88df9a

Removing doxygen output files. They should not be tracked.

1fb283b

resuther-msft suggested changes Apr 15, 2021

View reviewed changes

jaygullapalli requested review from scotthsu98052 and qm13 April 26, 2021 22:31

scotthsu98052 reviewed Apr 26, 2021

View reviewed changes

include/k4a/k4a.h Show resolved Hide resolved

qm13 approved these changes May 20, 2021

View reviewed changes

scotthsu98052 approved these changes May 20, 2021

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Python c api update #1552

Python c api update #1552

JonathanESantos commented Mar 30, 2021 •

edited

resuther-msft left a comment

resuther-msft Apr 14, 2021

resuther-msft Apr 15, 2021

resuther-msft Apr 15, 2021

resuther-msft Apr 15, 2021

resuther-msft Apr 15, 2021

resuther-msft Apr 15, 2021

resuther-msft Apr 15, 2021

Python c api update #1552

Are you sure you want to change the base?

Python c api update #1552

Conversation

JonathanESantos commented Mar 30, 2021 • edited

Fixes #40, #917

Description of the changes:

Before submitting a Pull Request:

I tested changes on:

resuther-msft left a comment

Choose a reason for hiding this comment

resuther-msft Apr 14, 2021

Choose a reason for hiding this comment

resuther-msft Apr 15, 2021

Choose a reason for hiding this comment

resuther-msft Apr 15, 2021

Choose a reason for hiding this comment

resuther-msft Apr 15, 2021

Choose a reason for hiding this comment

resuther-msft Apr 15, 2021

Choose a reason for hiding this comment

resuther-msft Apr 15, 2021

Choose a reason for hiding this comment

resuther-msft Apr 15, 2021

Choose a reason for hiding this comment

JonathanESantos commented Mar 30, 2021 •

edited