pyKinectAzure

用于 Azure Kinect DK 传感器 SDK 的 Python 3 库。

类似解决方案

本仓库中的部分想法源自以下仓库：

• pyk4a：一个非常优秀且简洁的 Kinect Azure SDK Python3 封装库。
• Azure-Kinect-Python：另一个功能更全面的库，同样使用 ctypes 实现绑定，但缺少使用示例，且使用起来较为复杂。

本仓库的目标是结合上述两个仓库的优点，打造一个易于使用的库，支持 Kinect Azure 的大部分功能，并提供示例程序以展示其用法。

前置条件

• Azure-Kinect-Sensor-SDK：构建本库所必需。请参考该仓库的安装说明 此处 进行安装。
• ctypes：用于加载动态链接库。
• numpy：用于矩阵计算。
• opencv-python：用于图像变换和可视化。

安装

pip install pykinect_azure

使用方法

• 本库已在 Windows 10 和 Ubuntu 20.04 上使用 Kinect Azure SDK 1.4.0 和 1.4.1 版本进行测试，理论上也应适用于其他操作系统。

  • Windows：使用 pyKinectAzure 类时，需要指定 k4a.dll 模块的路径，请确保路径与您的 Kinect Azure SDK 版本匹配。默认路径为 C:\\Program Files\\Azure Kinect SDK v1.4.0\\sdk\\windows-desktop\\amd64\\release\\bin\\k4a.dll。

  • Linux：使用 pyKinectAzure 类时，需要指定 k4a.so 模块的路径，请确保路径与您的 Kinect Azure SDK 版本匹配。在 Linux 系统上，请将 module_path 设置为 /usr/lib/x86_64-linux-gnu/libk4a.so，并按照微软提供的 安装指南 安装必要的软件包。

  • Nvidia Jetson：使用 pyKinectAzure 类时，同样需要指定 k4a.so 模块的路径，请确保路径与您的 Kinect Azure SDK 版本匹配。在 Nvidia Jetson 上，请将 module_path 设置为 '/usr/lib/aarch64-linux-gnu/libk4a.so'，并遵循微软提供的 安装指南 安装相关依赖。

• pyKinectAzure 类是对 _k4a.py 模块的封装，旨在使库的使用更加直观。然而，pyKinectAzure 类仍然仅包含 Kinect Azure SDK 的部分方法。

• _k4a.py 模块则包含了 Kinect Azure SDK 的所有方法。因此，若需使用更高级的功能，请直接查阅 _k4a.py 模块。

示例

以下示例展示了如何获取并可视化 Azure Kinect DK 的深度数据，请参阅 exampleDepthImageOpenCV.py 脚本：

git clone https://github.com/ibaiGorordo/pyKinectAzure.git
cd pyKinectAzure/examples
python exampleDepthImageOpenCV.py

此外，还有一个示例展示了如何获取并可视化 Azure Kinect DK 的平滑深度图像，请运行 exampleSmoothDepthImageOpenCV.py 脚本：

python exampleSmoothDepthImageOpenCV.py

注意：在 Linux 平台上操作时，请确保用户拥有访问 USB 设备的权限，或者始终以 root 权限运行（即在命令前添加 sudo）。

贡献

欢迎提交 Pull Request。

同时也欢迎您报告问题，请尽可能提供详细信息。

待办事项：

Kinect Azure 数据的封装

• 创建读取深度图像的封装。
• 创建读取红外图像的封装。
• 创建读取 IMU 数据的封装。
• 创建根据图像类型将图像缓冲区转换为图像的函数。
• 创建将深度图像转换为彩色图像的封装。
• 创建将深度图像转换为 3D 点云的封装。
• 创建可视化 3D 点云的函数。

示例程序

• 深度图像可视化示例。
• 被动红外图像可视化示例。
• IMU 数据绘图示例。
• 将深度图像作为彩色图像进行可视化示例。
• 将深度彩色图像与真实图像进行 Alpha 混合叠加示例。
• 3D 点云可视化示例。

人体追踪

• 创建类似当前库的人体追踪 SDK 封装。
• 结合图像与骨骼数据。
• 实现 3D 骨骼可视化。

未来设想

• 在 Kinect 数据上运行深度学习模型（如 OpenPose 3D 骨骼、基于深度的语义分割、单目深度估计验证等）。
• 利用被动红外标记进行动作捕捉分析。

pyKinectAzure 快速上手指南

pyKinectAzure 是一个用于 Azure Kinect DK 传感器的 Python 3 库，旨在提供简洁易用的接口来调用 Kinect Azure SDK 的核心功能（如深度图、红外图、IMU 数据及点云转换等）。

1. 环境准备

在开始之前，请确保满足以下系统和依赖要求：

系统要求

本库已在以下环境中测试通过：

• Windows 10
• Ubuntu 20.04
• Nvidia Jetson (ARM64 架构)

前置依赖

必须预先安装微软官方的 Azure Kinect Sensor SDK，否则无法编译或使用本库。

• SDK 下载与安装: 请参考 Microsoft Azure-Kinect-Sensor-SDK 官方文档进行安装。
• Python 依赖包:
  • ctypes: 用于读取底层库文件。
  • numpy: 用于矩阵计算。
  • opencv-python: 用于图像变换和可视化。

注意 (Linux/Jetson 用户): 请确保当前用户对 USB 设备有访问权限，或在运行脚本时使用 sudo。

2. 安装步骤

推荐使用 pip 进行安装。国内开发者可使用清华或阿里镜像源加速下载。

标准安装

pip install pykinect_azure

使用国内镜像源加速安装

pip install pykinect_azure -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 基本使用

配置模块路径

在使用 pyKinectAzure 类之前，必须根据操作系统指定底层动态库的路径 (module_path)。

• Windows: 默认指向 C:\\Program Files\\Azure Kinect SDK v1.4.0\\sdk\\windows-desktop\\amd64\\release\\bin\\k4a.dll (请根据实际安装的 SDK 版本调整)。
• Linux (Ubuntu): 通常设置为 /usr/lib/x86_64-linux-gnu/libk4a.so。
• Nvidia Jetson: 通常设置为 /usr/lib/aarch64-linux-gnu/libk4a.so。

最简单的使用示例

以下示例展示如何获取并可视化深度图像。首先克隆仓库以获取示例脚本：

git clone https://github.com/ibaiGorordo/pyKinectAzure.git
cd pyKinectAzure/examples

运行深度图像示例：

python exampleDepthImageOpenCV.py

运行平滑深度图像示例：

python exampleSmoothDepthImageOpenCV.py

提示: 如果需要更高级的功能（如直接调用 SDK 所有方法），可以查阅源码中的 _k4a.py 模块；日常开发建议直接使用封装更好的 pyKinectAzure 类。