- Generated by
1.17.0
|
libfreenect2 0.4
Open source driver for the Kinect for Windows v2 (K4W2) sensor
|
Version 0.3 keeps the established device constructors, legacy filename-list replay, and SyncMultiFrameListener, while adding opt-in APIs for timing, reconnection, durable recording, decoder policy, and depth correction. The shared-library ABI changes from 0.2 to 0.3; rebuild applications and binary bindings against the new headers and library.
All supported builds now require C++11 and the standard threading library. The C++98/tinythread configuration has been removed. This also gives every supported build the same timed-condition behavior: waitForNewFrame(frames, timeout_ms) returns when its timeout expires rather than falling through to an untimed wait in one threading configuration.
Downstream CMake projects should request C++11 or newer and link the exported freenect2 target. Code that provided tinythread-specific definitions should remove them.
Frame::arrival_timestamp_us is the monotonic host timestamp of the first USB transfer contributing to a live frame. Replay assigns the actual replay delivery time. It is a host clock and cannot be compared across machines or process boots.
SyncMultiFrameListener is unchanged. Applications that need bounded software pairing can opt into:
The listener searches its bounded queues for the smallest wrap-safe device timestamp span and exposes delivery, drop, and delta statistics. This is software pairing, not hardware triggering or exposure synchronization.
KinectCapture OUTPUT remains the legacy snapshot form. KinectCapture snapshot OUTPUT enables timestamp-aligned capture and accepts --max-delta-ticks.
Freenect2Device::getState() and getLastError() provide thread-safe lifecycle diagnostics. Disconnects enter DeviceDisconnected; terminal USB stalls enter DeviceError. stop() and close() are idempotent after partial startup and shutdown failures.
Reconnection is explicit. Close the old device, wait for its serial with Freenect2::waitForDevice(serial, timeout_ms), and open a fresh device object. Pointers representing disconnected devices are never revived. See KinectReconnect for the complete flow.
After successful stream initialization, Freenect2Device::getCalibrationData() copies color parameters, IR parameters, and raw P0 tables into an immutable application-owned snapshot.
RecordingWriter stores raw JPEG color packets and raw Kinect depth packets in a versioned manifest directory. It uses bounded thread-safe queues and writes each payload through .part plus atomic rename before appending its journal entry. recording.complete is published only on clean close.
Freenect2Replay::openRecording() validates manifest version, calibration, paths, byte counts, and journal structure. Strict mode rejects incomplete recordings; ReplayOptions::salvage_incomplete accepts only validated complete journal lines. ReplayOptions::reproduce_timing uses interruptible waits. Existing filename-list openDevice() overloads retain their old behavior.
EnableBilateralFilter and EnableEdgeAwareFilter now work independently on CPU, OpenCL, CUDA, OpenGL, and Metal. All four combinations are deterministic; edge-only mode no longer consumes an unwritten backend mask or produces an empty frame. Applications that relied on the previous accidental coupling should set both switches explicitly.
The installed libfreenect2/vision.h API promotes the color conversion and depth-geometry logic formerly embedded in the MediaPipe demo. It converts BGRX/RGBX frames into caller-owned contiguous BGR/RGB buffers, reverses a depth-to-color map with nearest-depth collision resolution, searches for a coherent foreground depth sample, and lifts normalized color points to metric XYZ in batches.
Registration::apply() now validates documented BGRX and RGBX inputs. Its registered output inherits the input channel order, while undistorted and big-depth outputs are explicitly marked Frame::Float. The native ctypes MediaPipe bridge has moved to the maintained pylibfreenect3 example.
This validation is stricter than in 0.2: apply() requires the color frame's Frame::format to be BGRX or RGBX and the depth frame's to be Float, and undistortDepth() requires a Float depth frame. Frames delivered by the device pipelines always carry the correct format, but the Frame constructor defaults format to Invalid, so code that wraps its own buffers in Frame objects must now set format explicitly. Rejected calls log an error and leave the output frames untouched.
Every packet-pipeline constructor has a configuration-preserving overload that accepts PacketPipelineConfig. A non-Auto rgb_decoder choice overrides the environment. In Auto, LIBFREENECT2_RGB_PROCESSOR and LIBFREENECT2_VAAPI_DEVICE can override platform selection.
VAAPI accepts an explicit DRM render node and otherwise discovers JPEG-capable nodes deterministically. Automatic probing skips NVIDIA nodes. With fallback enabled, VAAPI initialization or runtime failure retries the current packet once through TurboJPEG and then remains on TurboJPEG. Strict explicit VAAPI selection leaves the pipeline unhealthy instead of publishing an error frame.
The CUDA and CUDA KDE kernels use project-owned vector math primitives. CUDA samples and helper_math.h are no longer dependencies. CUDA 12.3 compiles both pipelines in hosted CI without a GPU; runtime parity still requires NVIDIA hardware validation.
DepthCorrectionProfile applies scale * measured_mm + offset_mm only when an application explicitly calls apply. Invalid pixels are preserved. One known distance fits an offset-only model; two or more distinct distances fit scale and offset from per-distance medians. Profiles store device identity, ROI, samples, MADs, residuals, and RMSE.
Use KinectDepthCalibration with raw recording directories or prompted live measurements. KinectCapture --depth-correction PROFILE checks serial and firmware before applying it; mismatches require --allow-device-mismatch. Raw recording mode never applies correction.
1.17.0