kinect2-python

Production-friendly Kinect v2 capture for Python on Linux.

一个基于 libfreenect2 与 pybind11 的 Kinect v2 Python 接口。它直接提供彩色、深度、红外、配准图、彩色点云、工厂标定、逐帧元数据、原始 JPEG，以及四通道麦克风数据。

当前状态：Beta，可在 Ubuntu/Debian 上通过一条安装脚本快速部署。由于 Kinect v2 需要原生驱动、USB udev 权限和 ALSA 系统库，本项目不是纯 Python 包，无法只靠一次普通的 pip install 配好一台全新电脑。

功能

数据	Python 输出	固定规格/单位
彩色图	uint8 (1080, 1920, 4)	BGRX，约 30 FPS
深度图	float32 (424, 512)	毫米
红外图	float32 (424, 512)	原始 IR 强度
配准彩色图	uint8 (424, 512, 4)	映射至深度坐标系，BGRX
去畸变深度图	float32 (424, 512)	毫米
彩色点云	XYZ、BGR、有效掩码	XYZ 为米；支持 NPZ/PLY 示例
工厂标定	嵌套 dict	深度内参、畸变、彩色映射多项式
帧元数据	每路独立 dict	时间戳、序号、曝光、增益等
原始彩色码流	bytes	相机产生的 1920×1080 JPEG
麦克风阵列	int32 (N, 4)	16 kHz、四通道、交错采样

Kinect v2 的硬件流分辨率由设备和 libfreenect2 固定，本包没有“切换采集分辨率”的 API。需要较小图像时，应在取帧后缩放；这不会降低 USB 带宽或深度计算负担。

30 秒安装

要求：Kinect for Windows v2 传感器及电源/USB 适配器、USB 3.x 控制器、64 位 Ubuntu/Debian、Conda 或 venv、可用的 sudo 和网络。

推荐创建独立 Conda 环境：

conda create -n kinect2 python=3.11 -y
conda activate kinect2
git clone https://github.com/hanzibo/kinect2-python.git
cd kinect2-python
bash scripts/install_ubuntu.sh

脚本会安装系统编译依赖，将固定版本 libfreenect2 v0.2.1 编译到当前 Python 环境，安装 udev 规则，再以 editable 模式安装本包及示例依赖。完成后拔插一次相机，运行：

python scripts/diagnose.py
python examples/quickstart.py
python examples/view_rgb_depth.py

预览窗口按 q 或 Esc 退出。不要同时运行 Protonect 或其他占用 Kinect 的程序。

最小 Python 示例

from kinect2 import Kinect2Camera

with Kinect2Camera() as camera:
    frames = camera.get_frames(timeout_ms=10_000)
    color_bgr = frames["color"][..., :3]  # (1080, 1920, 3), uint8
    depth_mm = frames["depth"]             # (424, 512), float32
    infrared = frames["ir"]               # (424, 512), float32
    print(camera.serial, frames["metadata"])

上下文管理器会自动 start() 和 close()，是推荐用法。所有返回数组都是独立副本，离开 get_frames() 后仍可安全使用。

示例目录

示例	用途	命令
quickstart.py	取一组帧并打印形状，无 OpenCV	python examples/quickstart.py
view_rgb_depth.py	实时显示彩色与伪彩深度	python examples/view_rgb_depth.py
capture_point_cloud.py	导出有组织 NPZ 或通用 PLY 点云	python examples/capture_point_cloud.py --format both
show_metadata_calibration.py	打印完整帧元数据与工厂标定	python examples/show_metadata_calibration.py
capture_raw_jpeg.py	保存相机原始 JPEG 码流	python examples/capture_raw_jpeg.py
record_microphone.py	录制五秒四通道 WAV	python examples/record_microphone.py
capture_image_audio.py	在同一进程采集图像和声音	python examples/capture_image_audio.py

配准与点云

with Kinect2Camera() as camera:
    frames = camera.get_frames(registered=True, point_cloud=True)

registered_bgr = frames["registered_color"][..., :3]
depth_mm = frames["undistorted_depth"]
xyz_m = frames["points"]            # (424, 512, 3), float32
colors_bgr = frames["point_colors"] # (424, 512, 3), uint8
valid = frames["valid_mask"]        # (424, 512), bool

“配准彩色图”是把彩色相机看到的颜色重新投影到深度相机的每个像素位置，因此它能与深度图逐像素对应。遮挡区域或超出彩色视野的位置可能没有有效对应。无效点的 XYZ 为 NaN，且 valid_mask 为 False。

标定与元数据

with Kinect2Camera() as camera:
    calibration = camera.calibration()
    frames = camera.get_frames()
    color_meta = frames["metadata"]["color"]

calibration()["depth"] 包含 fx, fy, cx, cy, k1, k2, k3, p1, p2。calibration()["color"] 包含 fx, fy, cx, cy, shift_d, shift_m 以及全部 mx_* / my_* 深度到彩色映射系数。这些映射系数不是传统的刚体外参 R, t。

每一路元数据均包含：timestamp、timestamp_ms、sequence、status、format、width、height、bytes_per_pixel、exposure、gain 和 gamma。timestamp_ms 按 libfreenect2 使用的 0.125 ms tick 换算。曝光、增益和 gamma 只对彩色帧有实际含义；深度/红外相应字段通常为零。

原始 JPEG

from kinect2 import Kinect2RawColorCamera

with Kinect2RawColorCamera() as camera:
    packet = camera.get_jpeg()

open("frame.jpg", "wb").write(packet["jpeg"])

Kinect2RawColorCamera 使用独占的 raw pipeline，不能和 Kinect2Camera 同时打开同一设备。这里返回的是传感器发送的 JPEG 字节，不经历解码和二次编码。

四通道麦克风

from kinect2 import Kinect2Microphone

with Kinect2Microphone() as microphone:
    samples = microphone.read(microphone.sample_rate)  # 1 秒，(16000, 4)

默认 ALSA 设备为 hw:CARD=Sensor,DEV=0。若系统分配了不同名字，可用 arecord -l 查询后传入 Kinect2Microphone(device="hw:...")。

图像与声音同时采集时，必须先打开相机，再打开麦克风：

with Kinect2Camera() as camera:
    with Kinect2Microphone() as microphone:
        frames = camera.get_frames()
        audio = microphone.read(1600)

原因是 libfreenect2 初始化传感器时会执行 USB reset；若 ALSA 句柄先打开，它会失效。

API 参考

Kinect2Camera(device_index=0)

• start()：启动彩色、深度和 IR 流；上下文管理器会自动调用。
• stop()：停止流但保持设备打开，可再次 start()。
• close()：释放设备；可重复调用。
• get_frames(timeout_ms=10000, registered=False, point_cloud=False)：等待同步帧。超时抛出 TimeoutError。
• calibration()：返回当前设备的工厂标定。
• serial: str、firmware_version: str：只读属性。

get_frames() 始终返回 color、depth、ir、timestamp、sequence、metadata。开启 registered 后增加 registered_color 与 undistorted_depth；开启 point_cloud 后增加 points、point_colors 与 valid_mask。point_cloud=True 会在内部自动执行配准，但不会额外返回两张配准图，除非同时设置 registered=True。

Kinect2RawColorCamera(device_index=0)

• start() / stop() / close()：管理 raw 彩色流。
• get_jpeg(timeout_ms=10000)：返回 {"jpeg": bytes, "metadata": dict}。
• serial: str：只读设备序列号。

Kinect2Microphone(device=..., sample_rate=16000, channels=4, latency_us=500000)

• read(frame_count, timeout_ms=5000)：返回 (frame_count, channels) 的 int32 NumPy 数组。
• close()：停止并释放 ALSA PCM 设备。
• sample_rate、channels、device_name：只读属性。

本包带有 PEP 561 类型标记和 .pyi 声明文件，支持 Pyright、mypy 和 IDE 自动补全。也可直接运行 help(Kinect2Camera) 查看原生方法文档。

手动构建

若已自行安装 libfreenect2，构建脚本会依次尝试：

1. LIBFREENECT2_INSTALL_PREFIX
2. CONDA_PREFIX
3. VIRTUAL_ENV
4. pkg-config freenect2
5. /usr/local 与 /usr

例如：

conda activate kinect2
python -m pip install "pybind11>=2.10" setuptools wheel
LIBFREENECT2_INSTALL_PREFIX="$CONDA_PREFIX" \
  python -m pip install -e '.[examples]' --no-build-isolation

如果把 libfreenect2 安装到 /usr/local 或 /usr，通常不需要设置变量。系统仍需 libasound2-dev 才能链接麦克风接口。

诊断与常见问题

先运行：

python scripts/diagnose.py
lsusb -t

• No Kinect v2 device found：检查独立电源、适配器，以及 lsusb 是否出现 Microsoft 045e:02d8 / 045e:02d9。拔插相机并关闭其他采集程序。
• USB 带宽不足、帧超时或日志反复报传输错误：确认设备实际连接在 USB 3.x 控制器；lsusb -t 应显示 5000M 或更高，而不是 480M。
• LIBUSB_ERROR_ACCESS / permission denied：确认 /etc/udev/rules.d/90-kinect2.rules 已安装，然后执行 sudo udevadm control --reload-rules && sudo udevadm trigger 并拔插相机。
• libfreenect2.so 找不到：激活安装时使用的环境；或设置 LIBFREENECT2_INSTALL_PREFIX 后重新安装本包。
• 麦克风打不开：运行 arecord -l，把实际设备名传给 Kinect2Microphone；并确认当前用户有音频设备权限。
• 窗口不能显示：远程 SSH/无桌面环境下不要运行 OpenCV viewer，改用 quickstart.py 或保存文件的示例。

已知边界

• 目前仅面向 Linux；没有 Windows/macOS 后端。
• 使用 CPU 深度 pipeline，优先保证可安装性；尚未暴露 OpenCL/CUDA pipeline 选择。
• Kinect v2 不提供由本包控制的可变硬件分辨率。
• 不包含人体骨架/手势追踪。这类功能需要额外算法，不属于 libfreenect2 原始数据接口。
• 同一时刻一个 Kinect 只能由一个图像 pipeline 独占。

License

本项目采用 Apache License 2.0。底层设备驱动 libfreenect2 由 OpenKinect 项目独立维护，并适用其自身的许可证条款。

项目结构

python/kinect2/            Python 包、类型声明
src/kinect2_bindings.cpp   pybind11/libfreenect2/ALSA 原生接口
examples/                  可直接运行的使用示例
scripts/install_ubuntu.sh  Ubuntu/Debian 引导安装
scripts/diagnose.py        非侵入式环境诊断

底层设备支持来自 OpenKinect/libfreenect2。