diff --git a/Cargo.toml b/Cargo.toml index 154e6983ec..476ceda799 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -30,7 +30,7 @@ imgui-opengl-renderer = "0.7.0" imgui-sdl2 = "0.9.0" # for imgui-opengl-renderer imgui-winit-support = "0.3.1" #k4a-sys = { path = "/home/bt/dev/3rd/k4a-sys", version = "=0.2.0" } # k4a-sys = "0.2.0" TODO: Check these modifications into source control -k4a-sys = { path = "/home/bt/dev/3rd/k4a-sys" } # branch = "working-version" +k4a-sys = { path = "./k4a-sys" } # branch = "working-version" libc = "0.2.68" log = "0.4.11" nalgebra = "0.21.1" # linear algebra and matrices, fantastic docs diff --git a/README.md b/README.md index f23255f686..cdd6566c1a 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,23 @@ Storyteller A startup, by Brandon Thomas. +Installation / Requirements +--------------------------- +Install the following packages on Linux: + +* clang +* cmake +* libopencv-dev +* libsdl2-dev +* libxcb-xfixes0-dev +* GLFW build requirements: + * libpthread (eg. libpthread-stubs0-dev) + * libx11-dev + * libxcursor-dev + * libxi-dev + * libxinerama-dev + * libxrandr-dev + Webcam ------ diff --git a/k4a-sys/.gitignore b/k4a-sys/.gitignore new file mode 100644 index 0000000000..698a4ba679 --- /dev/null +++ b/k4a-sys/.gitignore @@ -0,0 +1,5 @@ +/target +Cargo.lock +*~ +.*swp +*.swo diff --git a/k4a-sys/CHANGELOG.md b/k4a-sys/CHANGELOG.md new file mode 100644 index 0000000000..da7aea75aa --- /dev/null +++ b/k4a-sys/CHANGELOG.md @@ -0,0 +1,19 @@ +# Changelog +All notable changes to this project will be documented in this file. + + +## [0.2.1] - 2020-02-20 +### Removed + +- Vendored `.so`s as they are actually not used in the build. + +## [0.2.0] - 2020-02-05 +### Added + +- Initial linux bindings to `libk4a` version 1.3. + +## [0.1.0] - 2020-02-05 + +### Added + +- Initial windows bindings to `libk4a` version 1.3. diff --git a/k4a-sys/Cargo.toml b/k4a-sys/Cargo.toml new file mode 100644 index 0000000000..9beaaca807 --- /dev/null +++ b/k4a-sys/Cargo.toml @@ -0,0 +1,14 @@ +[package] +name = "k4a-sys" +version = "0.2.1" +authors = ["Amédée d'Aboville "] +edition = "2018" +description = "The Azure K4A API bindgen-ed to Rust." +repository = "https://gitlab.com/amedeedabo/k4a-sys" +license = "MIT" +gitlab = {repository = "amedeedabo/k4a-sys", branch = "master" } +documentation = "https://docs.rs/k4a-sys" +keywords = ["kinect"] + +[build-dependencies] +bindgen = "0.52.0" diff --git a/k4a-sys/LICENSE.md b/k4a-sys/LICENSE.md new file mode 100644 index 0000000000..810e7b9be0 --- /dev/null +++ b/k4a-sys/LICENSE.md @@ -0,0 +1,7 @@ +Copyright 2020 Amédée d'Aboville. + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/k4a-sys/README.md b/k4a-sys/README.md new file mode 100644 index 0000000000..c979c9a610 --- /dev/null +++ b/k4a-sys/README.md @@ -0,0 +1,34 @@ +k4a-sys +------- +A bingden wrapper for the Azure Kinect Sensor SDK, which should work on both Linux and Windows. + +Vendors the compiled SDK libs from version 1.3. + +On linux you need to install `libk4a1.3` to be able to use `libk4a.so` and `libdepthengine.so`. + +On windows you need to install the Sensor SDK to able to have the `libdepthengine.dll`. + +One future wish is to statically compile the SDK into this library, which would require modifying +the SDK's build to output a static library we could link against. + +It also might be possible to compile libk4a from source in the future, +but it looks time consuming. + +Examples +------ +There are two examples that match the SDK's. You can run them with eg: +``` +cargo run --example enumerate +cargo run --example streaming +``` + + +Future plans +------ +I've started also planning on writing a safe Rust wrapper library, `k4a-rs` to allow Rust-idiomatic (not raw pointers!) +access to the libraries. It will probably live in this repo and we'll move `k4a-sys` to a sub-directory here, the +same way [`bzip2-rs` and `bzip2-sys`](https://github.com/alexcrichton/bzip2-rs) work. + +I think in the near future we'll remove bindgen from the list of dependencies and only run it every library update, +that is, by hand/script instead of in the build.rs. This is because bindgen has ~60 dependencies, and should always +generate the same output file anyways. (It's possible to make the output cross platform). diff --git a/k4a-sys/build.rs b/k4a-sys/build.rs new file mode 100644 index 0000000000..92d33dcab6 --- /dev/null +++ b/k4a-sys/build.rs @@ -0,0 +1,32 @@ +extern crate bindgen; + +use std::env; +use std::env::consts; +use std::path::PathBuf; + +fn main() { + println!("cargo:rerun-if-changed=wrapper.h"); + if cfg!(target_os = "linux") { + println!("cargo:rustc-link-lib=dylib=k4a"); + } + if cfg!(target_os = "windows") { + println!("cargo:rustc-link-search=native=./vendor/lib/windows/{}", consts::ARCH); + println!("cargo:rustc-link-lib=native=k4a"); + } + + let bindings = bindgen::Builder::default() + .header("wrapper.h") + .clang_arg(format!("-I./vendor/include/{}", consts::OS)) + .whitelist_function("k4a.*") + .whitelist_type("_?[kK]4[aA].*") + .whitelist_var("[kK]4[aA].*") + .parse_callbacks(Box::new(bindgen::CargoCallbacks)) + .generate() + .expect("Unable to generate bindings"); + + // Write the bindings to the $OUT_DIR/bindings.rs file. + let out_path = PathBuf::from(env::var("OUT_DIR").unwrap()); + bindings + .write_to_file(out_path.join("bindings.rs")) + .expect("Couldn't write bindings!"); +} diff --git a/k4a-sys/examples/enumerate.rs b/k4a-sys/examples/enumerate.rs new file mode 100644 index 0000000000..762eb9b537 --- /dev/null +++ b/k4a-sys/examples/enumerate.rs @@ -0,0 +1,40 @@ +extern crate k4a_sys; +use std::ptr; +use k4a_sys::*; + +fn main() { + unsafe { + let mut device: k4a_sys::k4a_device_t = ptr::null_mut(); + + let device_count = k4a_device_get_installed_count(); + println!("Found {} connected devices:", device_count); + for device_idx in 0..device_count { + if k4a_device_open(device_idx, &mut device) != k4a_buffer_result_t_K4A_BUFFER_RESULT_SUCCEEDED { + println!("Failed to open device #{}", device_idx); + continue; + } + let mut serial_number_length: usize = 0; + + if k4a_device_get_serialnum(device, ptr::null_mut(), &mut serial_number_length) != + k4a_buffer_result_t_K4A_BUFFER_RESULT_TOO_SMALL { + println!("{}: Failed to get serial number length", device_idx); + k4a_device_close(device); + device = ptr::null_mut(); + continue; + } + + let mut serial_number = vec![0i8; serial_number_length]; + let serial_number_ptr = (&mut serial_number).as_mut_ptr(); + + if k4a_device_get_serialnum(device, serial_number_ptr, &mut serial_number_length) != + k4a_buffer_result_t_K4A_BUFFER_RESULT_SUCCEEDED { + println!("{}: Failed to get serial number", device_idx); + k4a_device_close(device); + device = ptr::null_mut(); + continue; + } + println!("{}: Device \"{:?}\"\n", device_idx, serial_number); + k4a_device_close(device); + } + } +} diff --git a/k4a-sys/examples/streaming.rs b/k4a-sys/examples/streaming.rs new file mode 100644 index 0000000000..385880e080 --- /dev/null +++ b/k4a-sys/examples/streaming.rs @@ -0,0 +1,122 @@ +#![allow(non_upper_case_globals)] +extern crate k4a_sys; +use std::ptr; +use std::env; +use k4a_sys::*; + +fn open_device() -> Option { + unsafe { + let device_count = k4a_sys::k4a_device_get_installed_count(); + let mut device: k4a_device_t = ptr::null_mut(); + if device_count == 0 { + println!("No K4A devices found"); + return None; + } + + if k4a_device_open(0, &mut device) != k4a_buffer_result_t_K4A_BUFFER_RESULT_SUCCEEDED { + println!("Failed to open device"); + return None; + } + Some(device) + } +} + +pub struct DeviceConfiguration (k4a_device_configuration_t); +impl DeviceConfiguration { + pub fn new() -> Self { + Self (k4a_sys::k4a_device_configuration_t { + color_format: k4a_image_format_t_K4A_IMAGE_FORMAT_COLOR_MJPG, + color_resolution: k4a_color_resolution_t_K4A_COLOR_RESOLUTION_720P, + depth_mode: k4a_depth_mode_t_K4A_DEPTH_MODE_WFOV_2X2BINNED, + camera_fps: 0, + synchronized_images_only: false, + depth_delay_off_color_usec: 0, + wired_sync_mode: 0, + subordinate_delay_off_master_usec: 0, + disable_streaming_indicator: false, + } + ) + } +} + +fn main() { + unsafe { + let timeout_in_ms = 1000; + + let args = env::args().collect::>(); + if args.len() < 2 { + println!("usage: {} FRAMECOUNT", args[0]); + println!("Capture FRAMECOUNT color and depth frames from the device using the separate get frame APIs"); + panic!("Missing FRAMECOUNT argument"); + } + + let capture_frame_count: i32 = args[1].parse().expect("Unable to parse frame count as a number"); + println!("Capturing {} frames", capture_frame_count); + + let device: k4a_device_t = open_device().expect("Unable to open device"); + let mut config = DeviceConfiguration::new(); + config.0.color_format = k4a_image_format_t_K4A_IMAGE_FORMAT_COLOR_MJPG; + config.0.color_resolution = k4a_color_resolution_t_K4A_COLOR_RESOLUTION_2160P; + config.0.depth_mode = k4a_depth_mode_t_K4A_DEPTH_MODE_NFOV_UNBINNED; + config.0.camera_fps = k4a_fps_t_K4A_FRAMES_PER_SECOND_30; + + if k4a_device_start_cameras(device, &(config.0)) != k4a_buffer_result_t_K4A_BUFFER_RESULT_SUCCEEDED { + panic!("Failed to start device"); + } + + let mut capture: k4a_capture_t = ptr::null_mut(); + for _ in 0..capture_frame_count { + match k4a_device_get_capture(device, &mut capture, timeout_in_ms) { + k4a_wait_result_t_K4A_WAIT_RESULT_SUCCEEDED => {} + k4a_wait_result_t_K4A_WAIT_RESULT_TIMEOUT => { + println!("Timed out waiting for a capture"); + continue; + } + k4a_wait_result_t_K4A_WAIT_RESULT_FAILED => { + panic!("Failed to read a capture"); + } + _ => panic!("Unknown result from device capture") + } + println!("Capture"); + + // Probe for a color image + let mut image = k4a_capture_get_color_image(capture); + if !image.is_null() { + print!(" | Color res:{:4}x{:4} stride:{:5} ", + k4a_image_get_height_pixels(image), + k4a_image_get_width_pixels(image), + k4a_image_get_stride_bytes(image)); + k4a_image_release(image); + } else { + print!(" | Color None "); + } + + // probe for a IR16 image + image = k4a_capture_get_ir_image(capture); + if !image.is_null() { + print!(" | Ir16 res:{:4}x{:4} stride:{:5} ", + k4a_image_get_height_pixels(image), + k4a_image_get_width_pixels(image), + k4a_image_get_stride_bytes(image)); + k4a_image_release(image); + } else { + print!(" | Ir16 None "); + } + + // Probe for a depth16 image + image = k4a_capture_get_depth_image(capture); + if !image.is_null() { + println!(" | Depth16 res:{:4}x{:4} stride:{:5}", + k4a_image_get_height_pixels(image), + k4a_image_get_width_pixels(image), + k4a_image_get_stride_bytes(image)); + k4a_image_release(image); + } + else { + println!(" | Depth16 None"); + } + // fflush(stdout); + } + k4a_device_close(device); + } +} diff --git a/k4a-sys/src/lib.rs b/k4a-sys/src/lib.rs new file mode 100644 index 0000000000..4a01ab794b --- /dev/null +++ b/k4a-sys/src/lib.rs @@ -0,0 +1,13 @@ +#![allow(non_upper_case_globals)] +#![allow(non_camel_case_types)] +#![allow(non_snake_case)] + +include!(concat!(env!("OUT_DIR"), "/bindings.rs")); + +#[cfg(test)] +mod tests { + #[test] + fn it_works() { + assert_eq!(2 + 2, 4); + } +} diff --git a/k4a-sys/vendor/include/linux/k4a/k4a.h b/k4a-sys/vendor/include/linux/k4a/k4a.h new file mode 100644 index 0000000000..2cf9e25bca --- /dev/null +++ b/k4a-sys/vendor/include/linux/k4a/k4a.h @@ -0,0 +1,2276 @@ +/** \file k4a.h + * Copyright (c) Microsoft Corporation. All rights reserved. + * Licensed under the MIT License. + * Kinect For Azure SDK. + */ + +#ifndef K4A_H +#define K4A_H + +#ifdef __cplusplus +#include +#else +#include +#endif +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * \defgroup Functions Functions + * \ingroup csdk + * + * Public functions of the API + * + * @{ + */ + +/** Gets the number of connected devices + * + * \returns Number of sensors connected to the PC. + * + * \relates k4a_device_t + * + * \remarks + * This API counts the number of Azure Kinect devices connected to the host PC. + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT uint32_t k4a_device_get_installed_count(void); + +/** Sets and clears the callback function to receive debug messages from the Azure Kinect device. + * + * \param message_cb + * The callback function to receive messages from. Set to NULL to unregister the callback function. + * + * \param message_cb_context + * The callback functions context. + * + * \param min_level + * The least critical error the user wants to be notified about. + * + * \return ::K4A_RESULT_SUCCEEDED if the callback function was set or cleared successfully. ::K4A_RESULT_FAILED if an + * error is encountered or the callback function has already been set. + * + * \remarks + * Call this function to set or clear the callback function that is used to deliver debug messages to the caller. This + * callback may be called concurrently, it is up to the implementation of the callback function to ensure the + * parallelization is handled. + * + * \remarks + * Clearing the callback function will block until all pending calls to the callback function have completed. + * + * \remarks + * To update \p min_level, \p k4a_set_debug_message_handler can be called with the same value \p message_cb and by + * specifying a new \p min_level. + * + * \remarks + * Logging provided via this API is independent of the logging controlled by the environmental variable controls \p + * K4A_ENABLE_LOG_TO_STDOUT, \p K4A_ENABLE_LOG_TO_A_FILE, and \p K4A_LOG_LEVEL. However there is a slight change in + * default behavior when using this function. By default, when \p k4a_set_debug_message_handler() has not been used to + * register a message callback, the default for environmental variable controls is to send debug messages as if + * K4A_ENABLE_LOG_TO_STDOUT=1 were set. If \p k4a_set_debug_message_handler registers a callback function before + * k4a_device_open() is called, then the default for environmental controls is as if K4A_ENABLE_LOG_TO_STDOUT=0 was + * specified. Physically specifying the environmental control will override the default. + * + * \p min_level + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_set_debug_message_handler(k4a_logging_message_cb_t *message_cb, + void *message_cb_context, + k4a_log_level_t min_level); + +/** Sets the callback functions for the SDK allocator + * + * \param allocate + * The callback function to allocate memory. When the SDK requires memory allocation this callback will be + * called and the application can provide a buffer and a context. + * + * \param free + * The callback function to free memory. The SDK will call this function when memory allocated by \p allocate + * is no longer needed. + * + * \return ::K4A_RESULT_SUCCEEDED if the callback function was set or cleared successfully. ::K4A_RESULT_FAILED if an + * error is encountered or the callback function has already been set. + * + * \remarks + * Call this function to hook memory allocation by the SDK. Calling with both \p allocate and \p free as NULL will + * clear the hook and reset to the default allocator. + * + * \remarks + * If this function is called after memory has been allocated, the previous version of \p free function may still be + * called in the future. The SDK will always call the \p free function that was set at the time that the memory + * was allocated. + * + * \remarks + * Not all memory allocation by the SDK is performed by this allocate function. Small allocations or allocations + * from special pools may come from other sources. + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_set_allocator(k4a_memory_allocate_cb_t allocate, k4a_memory_destroy_cb_t free); + +/** Open an Azure Kinect device. + * + * \param index + * The index of the device to open, starting with 0. Optionally pass in #K4A_DEVICE_DEFAULT. + * + * \param device_handle + * Output parameter which on success will return a handle to the device. + * + * \relates k4a_device_t + * + * \return ::K4A_RESULT_SUCCEEDED if the device was opened successfully. + * + * \remarks + * If successful, k4a_device_open() will return a device handle in the device_handle parameter. + * This handle grants exclusive access to the device and may be used in the other Azure Kinect API calls. + * + * \remarks + * When done with the device, close the handle with k4a_device_close() + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_device_open(uint32_t index, k4a_device_t *device_handle); + +/** Closes an Azure Kinect device. + * + * \param device_handle + * Handle obtained by k4a_device_open(). + * + * \relates k4a_device_t + * + * \remarks Once closed, the handle is no longer valid. + * + * \remarks Before closing the handle to the device, ensure that all \ref k4a_capture_t captures have been released with + * k4a_capture_release(). + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT void k4a_device_close(k4a_device_t device_handle); + +/** Reads a sensor capture. + * + * \param device_handle + * Handle obtained by k4a_device_open(). + * + * \param capture_handle + * If successful this contains a handle to a capture object. Caller must call k4a_capture_release() when its done using + * this capture. + * + * \param timeout_in_ms + * Specifies the time in milliseconds the function should block waiting for the capture. If set to 0, the function will + * return without blocking. Passing a value of #K4A_WAIT_INFINITE will block indefinitely until data is available, the + * device is disconnected, or another error occurs. + * + * \returns + * ::K4A_WAIT_RESULT_SUCCEEDED if a capture is returned. If a capture is not available before the timeout elapses, the + * function will return ::K4A_WAIT_RESULT_TIMEOUT. All other failures will return ::K4A_WAIT_RESULT_FAILED. + * + * \relates k4a_device_t + * + * \remarks + * Gets the next capture in the streamed sequence of captures from the camera. If a new capture is not currently + * available, this function will block until the timeout is reached. The SDK will buffer at least two captures worth + * of data before dropping the oldest capture. Callers needing to capture all data need to ensure they read the data as + * fast as the data is being produced on average. + * + * \remarks + * Upon successfully reading a capture this function will return success and populate \p capture. + * If a capture is not available in the configured \p timeout_in_ms, then the API will return ::K4A_WAIT_RESULT_TIMEOUT. + * + * \remarks + * If the call is successful and a capture is returned, callers must call k4a_capture_release() to return the allocated + * memory. + * + * \remarks + * This function needs to be called while the device is in a running state; + * after k4a_device_start_cameras() is called and before k4a_device_stop_cameras() is called. + * + * \remarks + * This function returns an error when an internal problem is encountered; such as loss of the USB connection, inability + * to allocate enough memory, and other unexpected issues. Any error returned by this function signals the end of + * streaming data, and caller should stop the stream using k4a_device_stop_cameras(). + * + * \remarks + * If this function is waiting for data (non-zero timeout) when k4a_device_stop_cameras() or k4a_device_close() is + * called on another thread, this function will return an error. + * + * \returns ::K4A_WAIT_RESULT_SUCCEEDED if a capture is returned. If a capture is not available before the timeout + * elapses, the function will return ::K4A_WAIT_RESULT_TIMEOUT. All other failures will return ::K4A_WAIT_RESULT_FAILED. + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + * + */ +K4A_EXPORT k4a_wait_result_t k4a_device_get_capture(k4a_device_t device_handle, + k4a_capture_t *capture_handle, + int32_t timeout_in_ms); + +/** Reads an IMU sample. + * + * \param device_handle + * Handle obtained by k4a_device_open(). + * + * \param imu_sample + * Pointer to the location for the API to write the IMU sample. + * + * \param timeout_in_ms + * Specifies the time in milliseconds the function should block waiting for the sample. If set to 0, the function will + * return without blocking. Passing a value of #K4A_WAIT_INFINITE will block indefinitely until data is available, the + * device is disconnected, or another error occurs. + * + * \returns + * ::K4A_WAIT_RESULT_SUCCEEDED if a sample is returned. If a sample is not available before the timeout elapses, the + * function will return ::K4A_WAIT_RESULT_TIMEOUT. All other failures will return ::K4A_WAIT_RESULT_FAILED. + * + * \relates k4a_device_t + * + * \remarks + * Gets the next sample in the streamed sequence of IMU samples from the device. If a new sample is not currently + * available, this function will block until the timeout is reached. The API will buffer at least two camera capture + * intervals worth of samples before dropping the oldest sample. Callers needing to capture all data need to ensure they + * read the data as fast as the data is being produced on average. + * + * \remarks + * Upon successfully reading a sample this function will return success and populate \p imu_sample. + * If a sample is not available in the configured \p timeout_in_ms, then the API will return ::K4A_WAIT_RESULT_TIMEOUT. + * + * \remarks + * This function needs to be called while the device is in a running state; + * after k4a_device_start_imu() is called and before k4a_device_stop_imu() is called. + * + * \remarks + * This function returns an error when an internal problem is encountered; such as loss of the USB connection, inability + * to allocate enough memory, and other unexpected issues. Any error returned by this function signals the end of + * streaming data, and caller should stop the stream using k4a_device_stop_imu(). + * + * \remarks + * If this function is waiting for data (non-zero timeout) when k4a_device_stop_imu() or k4a_device_close() is + * called on another thread, this function will return an error. + * + * \remarks + * The memory the IMU sample is written to is allocated and owned by the caller, so there is no need to call an Azure + * Kinect API to free or release the sample. + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_wait_result_t k4a_device_get_imu_sample(k4a_device_t device_handle, + k4a_imu_sample_t *imu_sample, + int32_t timeout_in_ms); + +/** Create an empty capture object. + * + * \param capture_handle + * Pointer to a location to store the handle. + * + * \relates k4a_capture_t + * + * \remarks + * Call this function to create a \ref k4a_capture_t handle for a new capture. Release it with k4a_capture_release(). + * + * The new capture is created with a reference count of 1. + * + * \returns + * Returns #K4A_RESULT_SUCCEEDED on success. Errors are indicated with #K4A_RESULT_FAILED and error specific data can be + * found in the log. + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_capture_create(k4a_capture_t *capture_handle); + +/** Release a capture. + * + * \param capture_handle + * Capture to release. + * + * \relates k4a_capture_t + * + * \remarks + * Call this function when finished using the capture. + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT void k4a_capture_release(k4a_capture_t capture_handle); + +/** Add a reference to a capture. + * + * \param capture_handle + * Capture to add a reference to. + * + * \relates k4a_capture_t + * + * \remarks + * Call this function to add an additional reference to a capture. This reference must be removed with + * k4a_capture_release(). + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT void k4a_capture_reference(k4a_capture_t capture_handle); + +/** Get the color image associated with the given capture. + * + * \param capture_handle + * Capture handle containing the image. + * + * \relates k4a_capture_t + * + * \remarks + * Call this function to access the color image part of this capture. Release the \ref k4a_image_t with + * k4a_image_release(); + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_image_t k4a_capture_get_color_image(k4a_capture_t capture_handle); + +/** Get the depth image associated with the given capture. + * + * \param capture_handle + * Capture handle containing the image. + * + * \relates k4a_capture_t + * + * \remarks + * Call this function to access the depth image part of this capture. Release the \ref k4a_image_t with + * k4a_image_release(); + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_image_t k4a_capture_get_depth_image(k4a_capture_t capture_handle); + +/** Get the IR image associated with the given capture. + * + * \param capture_handle + * Capture handle containing the image. + * + * \relates k4a_capture_t + * + * \remarks + * Call this function to access the IR image part of this capture. Release the \ref k4a_image_t with + * k4a_image_release(); + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_image_t k4a_capture_get_ir_image(k4a_capture_t capture_handle); + +/** Set or add a color image to the associated capture. + * + * \param capture_handle + * Capture handle to hold the image. + * + * \param image_handle + * Image handle containing the image. + * + * \relates k4a_capture_t + * + * \remarks + * When a \ref k4a_image_t is added to a \ref k4a_capture_t, the \ref k4a_capture_t will automatically add a reference + * to the \ref k4a_image_t. + * + * \remarks + * If there is already a color image contained in the capture, the existing image will be dereferenced and replaced with + * the new image. + * + * \remarks + * To remove a color image to the capture without adding a new image, this function can be called with a NULL + * image_handle. + * + * \remarks + * Any \ref k4a_image_t contained in this \ref k4a_capture_t will automatically be dereferenced when all references to + * the \ref k4a_capture_t are released with k4a_capture_release(). + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT void k4a_capture_set_color_image(k4a_capture_t capture_handle, k4a_image_t image_handle); + +/** Set or add a depth image to the associated capture. + * + * \param capture_handle + * Capture handle to hold the image. + * + * \param image_handle + * Image handle containing the image. + * + * \relates k4a_capture_t + * + * \remarks + * When a \ref k4a_image_t is added to a \ref k4a_capture_t, the \ref k4a_capture_t will automatically add a reference + * to the \ref k4a_image_t. + * + * \remarks + * If there is already an image depth image contained in the capture, the existing image will be dereferenced and + * replaced with the new image. + * + * \remarks + * To remove a depth image to the capture without adding a new image, this function can be called with a NULL + * image_handle. + * + * \remarks + * Any \ref k4a_image_t contained in this \ref k4a_capture_t will automatically be dereferenced when all references to + * the \ref k4a_capture_t are released with k4a_capture_release(). + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT void k4a_capture_set_depth_image(k4a_capture_t capture_handle, k4a_image_t image_handle); + +/** Set or add an IR image to the associated capture. + * + * \param capture_handle + * Capture handle to hold the image. + * + * \param image_handle + * Image handle containing the image. + * + * \relates k4a_capture_t + * + * \remarks + * When a \ref k4a_image_t is added to a \ref k4a_capture_t, the \ref k4a_capture_t will automatically add a reference + * to the \ref k4a_image_t. + * + * \remarks + * If there is already an IR image contained in the capture, the existing image will be dereferenced and replaced with + * the new image. + * + * \remarks + * To remove a IR image to the capture without adding a new image, this function can be called with a NULL image_handle. + * + * \remarks + * Any \ref k4a_image_t contained in this \ref k4a_capture_t will automatically be dereferenced when all references to + * the \ref k4a_capture_t are released with k4a_capture_release(). + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT void k4a_capture_set_ir_image(k4a_capture_t capture_handle, k4a_image_t image_handle); + +/** Set the temperature associated with the capture. + * + * \param capture_handle + * Capture handle to set the temperature on. + * + * \param temperature_c + * Temperature in Celsius to store. + * + * \relates k4a_capture_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT void k4a_capture_set_temperature_c(k4a_capture_t capture_handle, float temperature_c); + +/** Get the temperature associated with the capture. + * + * \param capture_handle + * Capture handle to retrieve the temperature from. + * + * \return + * This function returns the temperature of the device at the time of the capture in Celsius. If + * the temperature is unavailable, the function will return NAN. + * + * \relates k4a_capture_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT float k4a_capture_get_temperature_c(k4a_capture_t capture_handle); + +/** Create an image. + * + * \param format + * The format of the image that will be stored in this image container. + * + * \param width_pixels + * Width in pixels. + * + * \param height_pixels + * Height in pixels. + * + * \param stride_bytes + * The number of bytes per horizontal line of the image. + * + * \param image_handle + * Pointer to store image handle in. + * + * \remarks + * This function is used to create images of formats that have consistent stride. The function is not suitable for + * compressed formats that may not be represented by the same number of bytes per line. + * + * \remarks + * For most image formats, the function will allocate an image buffer of size \p height_pixels * \p stride_bytes. + * Buffers #K4A_IMAGE_FORMAT_COLOR_NV12 format will allocate an additional \p height_pixels / 2 set of lines (each of \p + * stride_bytes). This function cannot be used to allocate #K4A_IMAGE_FORMAT_COLOR_MJPG buffers. + * + * \remarks + * To create an image object without the API allocating memory, or to represent an image that has a non-deterministic + * stride, use k4a_image_create_from_buffer(). + * + * \remarks + * The \ref k4a_image_t is created with a reference count of 1. + * + * \remarks + * When finished using the created image, release it with k4a_image_release. + * + * \returns + * Returns #K4A_RESULT_SUCCEEDED on success. Errors are indicated with #K4A_RESULT_FAILED. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_image_create(k4a_image_format_t format, + int width_pixels, + int height_pixels, + int stride_bytes, + k4a_image_t *image_handle); + +/** Create an image from a pre-allocated buffer. + * + * \param format + * The format of the image that will be stored in this image container. + * + * \param width_pixels + * Width in pixels. + * + * \param height_pixels + * Height in pixels. + * + * \param stride_bytes + * The number of bytes per horizontal line of the image. + * + * \param buffer + * Pointer to a pre-allocated image buffer. + * + * \param buffer_size + * Size in bytes of the pre-allocated image buffer. + * + * \param buffer_release_cb + * Callback to the buffer free function, called when all references to the buffer have been released. This parameter is + * optional. + * + * \param buffer_release_cb_context + * Context for the buffer free function. This value will be called as a parameter to \p buffer_release_cb when + * the callback is invoked. + * + * \param image_handle + * Pointer to store image handle in. + * + * \remarks + * This function creates a \ref k4a_image_t from a pre-allocated buffer. When all references to this object reach zero + * the provided \p buffer_release_cb callback function is called so that the memory can be released. If this function + * fails, the API will not use the memory provided in \p buffer, and the API will not call \p buffer_release_cb. + * + * \remarks + * The \ref k4a_image_t is created with a reference count of 1. + * + * \remarks + * Release the reference on this function with k4a_image_release(). + * + * \returns + * Returns #K4A_RESULT_SUCCEEDED on success. Errors are indicated with #K4A_RESULT_FAILED and error specific data can be + * found in the log. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_image_create_from_buffer(k4a_image_format_t format, + int width_pixels, + int height_pixels, + int stride_bytes, + uint8_t *buffer, + size_t buffer_size, + k4a_memory_destroy_cb_t *buffer_release_cb, + void *buffer_release_cb_context, + k4a_image_t *image_handle); + +/** Get the image buffer. + * + * \param image_handle + * Handle of the image for which the get operation is performed on. + * + * \remarks + * Use this buffer to access the raw image data. + * + * \returns + * The function will return NULL if there is an error, and will normally return a pointer to the image buffer. + * Since all \ref k4a_image_t instances are created with an image buffer, this function should only return NULL if the + * \p image_handle is invalid. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT uint8_t *k4a_image_get_buffer(k4a_image_t image_handle); + +/** Get the image buffer size. + * + * \param image_handle + * Handle of the image for which the get operation is performed on. + * + * \remarks + * Use this function to know what the size of the image buffer is returned by k4a_image_get_buffer(). + * + * \returns + * The function will return 0 if there is an error, and will normally return the image size. + * Since all \ref k4a_image_t instances are created with an image buffer, this function should only return 0 if the + * \p image_handle is invalid. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT size_t k4a_image_get_size(k4a_image_t image_handle); + +/** Get the format of the image. + * + * \param image_handle + * Handle of the image for which the get operation is performed on. + * + * \remarks + * Use this function to determine the format of the image buffer. + * + * \returns + * This function is not expected to fail, all \ref k4a_image_t's are created with a known format. If the + * \p image_handle is invalid, the function will return ::K4A_IMAGE_FORMAT_CUSTOM. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_image_format_t k4a_image_get_format(k4a_image_t image_handle); + +/** Get the image width in pixels. + * + * \param image_handle + * Handle of the image for which the get operation is performed on. + * + * \returns + * This function is not expected to fail, all \ref k4a_image_t's are created with a known width. If the \p + * image_handle is invalid, the function will return 0. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT int k4a_image_get_width_pixels(k4a_image_t image_handle); + +/** Get the image height in pixels. + * + * \param image_handle + * Handle of the image for which the get operation is performed on. + * + * \returns + * This function is not expected to fail, all \ref k4a_image_t's are created with a known height. If the \p + * image_handle is invalid, the function will return 0. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT int k4a_image_get_height_pixels(k4a_image_t image_handle); + +/** Get the image stride in bytes. + * + * \param image_handle + * Handle of the image for which the get operation is performed on. + * + * \returns + * This function is not expected to fail, all \ref k4a_image_t's are created with a known stride. If the + * \p image_handle is invalid, or the image's format does not have a stride, the function will return 0. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT int k4a_image_get_stride_bytes(k4a_image_t image_handle); + +/** Get the image's device timestamp in microseconds. + * + * \param image_handle + * Handle of the image for which the get operation is performed on. + * + * \remarks + * Returns the device timestamp of the image. Timestamps are recorded by the device and represent the mid-point of + * exposure. They may be used for relative comparison, but their absolute value has no defined meaning. + * + * \returns + * If the \p image_handle is invalid or if no timestamp was set for the image, + * this function will return 0. It is also possible for 0 to be a valid timestamp originating from the beginning + * of a recording or the start of streaming. + * + * \deprecated + * Deprecated starting in 1.2.0. Please use k4a_image_get_device_timestamp_usec(). + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_DEPRECATED_EXPORT uint64_t k4a_image_get_timestamp_usec(k4a_image_t image_handle); + +/** Get the image's device timestamp in microseconds. + * + * \param image_handle + * Handle of the image for which the get operation is performed on. + * + * \remarks + * Returns the device timestamp of the image, as captured by the hardware. Timestamps are recorded by the device and + * represent the mid-point of exposure. They may be used for relative comparison, but their absolute value has no + * defined meaning. + * + * \returns + * If the \p image_handle is invalid or if no timestamp was set for the image, this function will return 0. It is also + * possible for 0 to be a valid timestamp originating from the beginning of a recording or the start of streaming. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT uint64_t k4a_image_get_device_timestamp_usec(k4a_image_t image_handle); + +/** Get the image's system timestamp in nanoseconds. + * + * \param image_handle + * Handle of the image for which the get operation is performed on. + * + * \remarks + * Returns the system timestamp of the image. Timestamps are recorded by the host. They may be used for relative + * comparision, as they are relative to the corresponding system clock. The absolute value is a monotonic count from + * an arbitrary point in the past. + * + * \remarks + * The system timestamp is captured at the moment host PC finishes receiving the image. + * + * \remarks + * On Linux the system timestamp is read from clock_gettime(CLOCK_MONOTONIC), which measures realtime and is not + * impacted by adjustments to the system clock. It starts from an arbitrary point in the past. On Windows the system + * timestamp is read from QueryPerformanceCounter(), it also measures realtime and is not impacted by adjustments to the + * system clock. It also starts from an arbitrary point in the past. + * + * \returns + * If the \p image_handle is invalid or if no timestamp was set for the image, this function will return 0. It is also + * possible for 0 to be a valid timestamp originating from the beginning of a recording or the start of streaming. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT uint64_t k4a_image_get_system_timestamp_nsec(k4a_image_t image_handle); + +/** Get the image exposure in microseconds. + * + * \param image_handle + * Handle of the image for which the get operation is performed on. + * + * \remarks + * Returns an exposure time in microseconds. This is only supported on color image formats. + * + * \returns + * If the \p image_handle is invalid, or no exposure was set on the image, the function will return 0. Otherwise, + * it will return the image exposure time in microseconds. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT uint64_t k4a_image_get_exposure_usec(k4a_image_t image_handle); + +/** Get the image white balance. + * + * \param image_handle + * Handle of the image for which the get operation is performed on. + * + * \remarks + * Returns the image's white balance. This function is only valid for color captures, and not for depth or IR captures. + * + * \returns + * Returns the image white balance in Kelvin. If \p image_handle is invalid, or the white balance was not set or + * not applicable to the image, the function will return 0. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT uint32_t k4a_image_get_white_balance(k4a_image_t image_handle); + +/** Get the image ISO speed. + * + * \param image_handle + * Handle of the image for which the get operation is performed on. + * + * \remarks + * This function is only valid for color captures, and not for depth or IR captures. + * + * \returns + * Returns the ISO speed of the image. 0 indicates the ISO speed was not available or an error occurred. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT uint32_t k4a_image_get_iso_speed(k4a_image_t image_handle); + +/** Set the device time stamp, in microseconds, of the image. + * + * \param image_handle + * Handle of the image to set the timestamp on. + * + * \param timestamp_usec + * Device timestamp of the image in microseconds. + * + * \remarks + * Use this function in conjunction with k4a_image_create() or k4a_image_create_from_buffer() to construct a + * \ref k4a_image_t. + * + * \remarks + * The device timestamp represents the mid-point of exposure of the image, as captured by the hardware. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT void k4a_image_set_device_timestamp_usec(k4a_image_t image_handle, uint64_t timestamp_usec); + +/** Set the device time stamp, in microseconds, of the image. + * + * \param image_handle + * Handle of the image to set the timestamp on. + * + * \param timestamp_usec + * Device timestamp of the image in microseconds. + * + * \remarks + * Use this function in conjunction with k4a_image_create() or k4a_image_create_from_buffer() to construct a + * \ref k4a_image_t. + * + * \remarks + * The device timestamp represents the mid-point of exposure of the image, as captured by the hardware. + * + * \relates k4a_image_t + * + * \deprecated + * Deprecated starting in 1.2.0. Please use k4a_image_set_device_timestamp_usec(). + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_DEPRECATED_EXPORT void k4a_image_set_timestamp_usec(k4a_image_t image_handle, uint64_t timestamp_usec); + +/** Set the system time stamp, in nanoseconds, of the image. + * + * \param image_handle + * Handle of the image to set the timestamp on. + * + * \param timestamp_nsec + * Timestamp of the image in nanoseconds. + * + * \remarks + * Use this function in conjunction with k4a_image_create() or k4a_image_create_from_buffer() to construct a + * \ref k4a_image_t. + * + * \remarks + * The system timestamp is a high performance and increasing clock (from boot). The timestamp represents the time + * immediately after the image buffer was read by the host PC. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT void k4a_image_set_system_timestamp_nsec(k4a_image_t image_handle, uint64_t timestamp_nsec); + +/** Set the exposure time, in microseconds, of the image. + * + * \param image_handle + * Handle of the image to set the exposure time on. + * + * \param exposure_usec + * Exposure time of the image in microseconds. + * + * \remarks + * Use this function in conjunction with k4a_image_create() or k4a_image_create_from_buffer() to construct a + * \ref k4a_image_t. An exposure time of 0 is considered invalid. Only color image formats are expected to have a valid + * exposure time. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT void k4a_image_set_exposure_usec(k4a_image_t image_handle, uint64_t exposure_usec); + +/** Set the exposure time, in microseconds, of the image. + * + * \param image_handle + * Handle of the image to set the exposure time on. + * + * \param exposure_usec + * Exposure time of the image in microseconds. + * + * \remarks + * Use this function in conjunction with k4a_image_create() or k4a_image_create_from_buffer() to construct a + * \ref k4a_image_t. An exposure time of 0 is considered invalid. Only color image formats are expected to have a valid + * exposure time. + * + * \deprecated + * Deprecated starting in 1.2.0. Please use k4a_image_set_exposure_usec(). + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_DEPRECATED_EXPORT void k4a_image_set_exposure_time_usec(k4a_image_t image_handle, uint64_t exposure_usec); + +/** Set the white balance of the image. + * + * \param image_handle + * Handle of the image to set the white balance on. + * + * \param white_balance + * White balance of the image in degrees Kelvin. + * + * \remarks + * Use this function in conjunction with k4a_image_create() or k4a_image_create_from_buffer() to construct a + * \ref k4a_image_t. A white balance of 0 is considered invalid. White balance is only meaningful for color images, + * and not expected on depth or IR images. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT void k4a_image_set_white_balance(k4a_image_t image_handle, uint32_t white_balance); + +/** Set the ISO speed of the image. + * + * \param image_handle + * Handle of the image to set the ISO speed on. + * + * \param iso_speed + * ISO speed of the image. + * + * \remarks + * Use this function in conjunction with k4a_image_create() or k4a_image_create_from_buffer() to construct a + * \ref k4a_image_t. An ISO speed of 0 is considered invalid. Only color images are expected to have a valid ISO speed. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT void k4a_image_set_iso_speed(k4a_image_t image_handle, uint32_t iso_speed); + +/** Add a reference to the k4a_image_t. + * + * \param image_handle + * Handle of the image for which the get operation is performed on. + * + * \remarks + * References manage the lifetime of the object. When the references reach zero the object is destroyed. A caller must + * not access the object after its reference is released. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT void k4a_image_reference(k4a_image_t image_handle); + +/** Remove a reference from the k4a_image_t. + * + * \param image_handle + * Handle of the image for which the get operation is performed on. + * + * \remarks + * References manage the lifetime of the object. When the references reach zero the object is destroyed. A caller must + * not access the object after its reference is released. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT void k4a_image_release(k4a_image_t image_handle); + +/** Starts color and depth camera capture. + * + * \param device_handle + * Handle obtained by k4a_device_open(). + * + * \param config + * The configuration we want to run the device in. This can be initialized with ::K4A_DEVICE_CONFIG_INIT_DISABLE_ALL. + * + * \returns + * ::K4A_RESULT_SUCCEEDED is returned on success. + * + * \relates k4a_device_t + * + * \remarks + * Individual sensors configured to run will now start to stream captured data. + * + * \remarks + * It is not valid to call k4a_device_start_cameras() a second time on the same \ref k4a_device_t until + * k4a_device_stop_cameras() has been called. + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_device_start_cameras(k4a_device_t device_handle, const k4a_device_configuration_t *config); + +/** Stops the color and depth camera capture. + * + * \param device_handle + * Handle obtained by k4a_device_open(). + * + * \relates k4a_device_t + * + * \remarks + * The streaming of individual sensors stops as a result of this call. Once called, k4a_device_start_cameras() may + * be called again to resume sensor streaming. + * + * \remarks + * This function may be called while another thread is blocking in k4a_device_get_capture(). + * Calling this function while another thread is in that function will result in that function returning a failure. + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT void k4a_device_stop_cameras(k4a_device_t device_handle); + +/** Starts the IMU sample stream. + * + * \param device_handle + * Handle obtained by k4a_device_open(). + * + * \returns + * ::K4A_RESULT_SUCCEEDED is returned on success. ::K4A_RESULT_FAILED if the sensor is already running or a failure is + * encountered + * + * \relates k4a_device_t + * + * \remarks + * Call this API to start streaming IMU data. It is not valid to call this function a second time on the same + * \ref k4a_device_t until k4a_device_stop_imu() has been called. + * + * \remarks + * This function is dependent on the state of the cameras. The color or depth camera must be started before the IMU. + * ::K4A_RESULT_FAILED will be returned if one of the cameras is not running. + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_device_start_imu(k4a_device_t device_handle); + +/** Stops the IMU capture. + * + * \param device_handle + * Handle obtained by k4a_device_open(). + * + * \relates k4a_device_t + * + * \remarks + * The streaming of the IMU stops as a result of this call. Once called, k4a_device_start_imu() may + * be called again to resume sensor streaming, so long as the cameras are running. + * + * \remarks + * This function may be called while another thread is blocking in k4a_device_get_imu_sample(). + * Calling this function while another thread is in that function will result in that function returning a failure. + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT void k4a_device_stop_imu(k4a_device_t device_handle); + +/** Get the Azure Kinect device serial number. + * + * \param device_handle + * Handle obtained by k4a_device_open(). + * + * \param serial_number + * Location to write the serial number to. If the function returns ::K4A_BUFFER_RESULT_SUCCEEDED, this will be a NULL + * terminated string of ASCII characters. If this input is NULL \p serial_number_size will still be updated to return + * the size of the buffer needed to store the string. + * + * \param serial_number_size + * On input, the size of the \p serial_number buffer if that pointer is not NULL. On output, this value is set to the + * actual number of bytes in the serial number (including the null terminator). + * + * \returns + * A return of ::K4A_BUFFER_RESULT_SUCCEEDED means that the \p serial_number has been filled in. If the buffer is too + * small the function returns ::K4A_BUFFER_RESULT_TOO_SMALL and the size of the serial number is + * returned in the \p serial_number_size parameter. All other failures return ::K4A_BUFFER_RESULT_FAILED. + * + * \relates k4a_device_t + * + * \remarks + * Queries the device for its serial number. If the caller needs to know the size of the serial number to allocate + * memory, the function should be called once with a NULL \p serial_number to get the needed size in the \p + * serial_number_size output, and then again with the allocated buffer. + * + * \remarks + * Only a complete serial number will be returned. If the caller's buffer is too small, the function will return + * ::K4A_BUFFER_RESULT_TOO_SMALL without returning any data in \p serial_number. + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_buffer_result_t k4a_device_get_serialnum(k4a_device_t device_handle, + char *serial_number, + size_t *serial_number_size); + +/** Get the version numbers of the device's subsystems. + * + * \param device_handle + * Handle obtained by k4a_device_open(). + * + * \param version + * Location to write the version info to. + * + * \returns A return of ::K4A_RESULT_SUCCEEDED means that the version structure has been filled in. + * All other failures return ::K4A_RESULT_FAILED. + * + * \relates k4a_device_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_device_get_version(k4a_device_t device_handle, k4a_hardware_version_t *version); + +/** Get the Azure Kinect color sensor control capabilities. + * + * \param device_handle + * Handle obtained by k4a_device_open(). + * + * \param command + * Color sensor control command. + * + * \param supports_auto + * Location to store whether the color sensor's control support auto mode or not. + * true if it supports auto mode, otherwise false. + * + * \param min_value + * Location to store the color sensor's control minimum value of /p command. + * + * \param max_value + * Location to store the color sensor's control maximum value of /p command. + * + * \param step_value + * Location to store the color sensor's control step value of /p command. + * + * \param default_value + * Location to store the color sensor's control default value of /p command. + * + * \param default_mode + * Location to store the color sensor's control default mode of /p command. + * + * \returns + * ::K4A_RESULT_SUCCEEDED if the value was successfully returned, ::K4A_RESULT_FAILED if an error occurred + * + * \relates k4a_device_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_device_get_color_control_capabilities(k4a_device_t device_handle, + k4a_color_control_command_t command, + bool *supports_auto, + int32_t *min_value, + int32_t *max_value, + int32_t *step_value, + int32_t *default_value, + k4a_color_control_mode_t *default_mode); + +/** Get the Azure Kinect color sensor control + * value. + * + * \param device_handle + * Handle obtained by k4a_device_open(). + * + * \param command + * Color sensor control command. + * + * \param mode + * Location to store the color sensor's control mode. This mode represents whether the command is in automatic or + * manual mode. + * + * \param value + * Location to store the color sensor's control value. This value is always written, but is only valid when the \p + * mode returned is ::K4A_COLOR_CONTROL_MODE_MANUAL for the current \p command. + * + * \returns + * ::K4A_RESULT_SUCCEEDED if the value was successfully returned, ::K4A_RESULT_FAILED if an error occurred + * + * \remarks + * Each control command may be set to manual or automatic. See the definition of \ref k4a_color_control_command_t on + * how to interpret the \p value for each command. + * + * \remarks + * Some control commands are only supported in manual mode. When a command is in automatic mode, the \p value for + * that command is not valid. + * + * \remarks + * Control values set on a device are reset only when the device is power cycled. The device will retain the + * settings even if the \ref k4a_device_t is closed or the application is restarted. + * + * \relates k4a_device_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_device_get_color_control(k4a_device_t device_handle, + k4a_color_control_command_t command, + k4a_color_control_mode_t *mode, + int32_t *value); + +/** Set the Azure Kinect color sensor control value. + * + * \param device_handle + * Handle obtained by k4a_device_open(). + * + * \param command + * Color sensor control command. + * + * \param mode + * Color sensor control mode to set. This mode represents whether the command is in automatic or manual mode. + * + * \param value + * Value to set the color sensor's control to. The value is only valid if \p mode + * is set to ::K4A_COLOR_CONTROL_MODE_MANUAL, and is otherwise ignored. + * + * \returns + * ::K4A_RESULT_SUCCEEDED if the value was successfully set, ::K4A_RESULT_FAILED if an error occurred + * + * \remarks + * Each control command may be set to manual or automatic. See the definition of \ref k4a_color_control_command_t on how + * to interpret the \p value for each command. + * + * \remarks + * Some control commands are only supported in manual mode. When a command is in automatic mode, the \p value for that + * command is not valid. + * + * \remarks + * Control values set on a device are reset only when the device is power cycled. The device will retain the settings + * even if the \ref k4a_device_t is closed or the application is restarted. + * + * \relates k4a_device_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_device_set_color_control(k4a_device_t device_handle, + k4a_color_control_command_t command, + k4a_color_control_mode_t mode, + int32_t value); + +/** Get the raw calibration blob for the entire Azure Kinect device. + * + * \param device_handle + * Handle obtained by k4a_device_open(). + * + * \param data + * Location to write the calibration data to. This field may optionally be set to NULL for the caller to query for + * the needed data size. + * + * \param data_size + * On passing \p data_size into the function this variable represents the available size of the \p data + * buffer. On return this variable is updated with the amount of data actually written to the buffer, or the size + * required to store the calibration buffer if \p data is NULL. + * + * \returns + * ::K4A_BUFFER_RESULT_SUCCEEDED if \p data was successfully written. If \p data_size points to a buffer size that is + * too small to hold the output or \p data is NULL, ::K4A_BUFFER_RESULT_TOO_SMALL is returned and \p data_size is + * updated to contain the minimum buffer size needed to capture the calibration data. + * + * \relates k4a_device_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_buffer_result_t k4a_device_get_raw_calibration(k4a_device_t device_handle, + uint8_t *data, + size_t *data_size); + +/** Get the camera calibration for the entire Azure Kinect device. + * + * \param device_handle + * Handle obtained by k4a_device_open(). + * + * \param depth_mode + * Mode in which depth camera is operated. + * + * \param color_resolution + * Resolution in which color camera is operated. + * + * \param calibration + * Location to write the calibration + * + * \returns + * ::K4A_RESULT_SUCCEEDED if \p calibration was successfully written. ::K4A_RESULT_FAILED otherwise. + * + * \remarks + * The \p calibration represents the data needed to transform between the camera views and may be + * different for each operating \p depth_mode and \p color_resolution the device is configured to operate in. + * + * \remarks + * The \p calibration output is used as input to all calibration and transformation functions. + * + * \see k4a_calibration_2d_to_2d() + * \see k4a_calibration_2d_to_3d() + * \see k4a_calibration_3d_to_2d() + * \see k4a_calibration_3d_to_3d() + * + * \relates k4a_device_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_device_get_calibration(k4a_device_t device_handle, + const k4a_depth_mode_t depth_mode, + const k4a_color_resolution_t color_resolution, + k4a_calibration_t *calibration); + +/** Get the device jack status for the synchronization in and synchronization out connectors. + * + * \param device_handle + * Handle obtained by k4a_device_open(). + * + * \param sync_in_jack_connected + * Upon successful return this value will be set to true if a cable is connected to this sync in jack. + * + * \param sync_out_jack_connected + * Upon successful return this value will be set to true if a cable is connected to this sync out jack. + * + * \returns + * ::K4A_RESULT_SUCCEEDED if the connector status was successfully read. + * + * \relates k4a_device_t + * + * \remarks + * If \p sync_out_jack_connected is true then \ref k4a_device_configuration_t wired_sync_mode mode can be set to \ref + * K4A_WIRED_SYNC_MODE_STANDALONE or \ref K4A_WIRED_SYNC_MODE_MASTER. If \p sync_in_jack_connected is true then \ref + * k4a_device_configuration_t wired_sync_mode mode can be set to \ref K4A_WIRED_SYNC_MODE_STANDALONE or \ref + * K4A_WIRED_SYNC_MODE_SUBORDINATE. + * + * \see k4a_device_start_cameras() + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_device_get_sync_jack(k4a_device_t device_handle, + bool *sync_in_jack_connected, + bool *sync_out_jack_connected); + +/** Get the camera calibration for a device from a raw calibration blob. + * + * \param raw_calibration + * Raw calibration blob obtained from a device or recording. The raw calibration must be NULL terminated. + * + * \param raw_calibration_size + * The size, in bytes, of raw_calibration including the NULL termination. + * + * \param depth_mode + * Mode in which depth camera is operated. + * + * \param color_resolution + * Resolution in which color camera is operated. + * + * \param calibration + * Location to write the calibration. + * + * \returns + * ::K4A_RESULT_SUCCEEDED if \p calibration was successfully written. ::K4A_RESULT_FAILED otherwise. + * + * \remarks + * The \p calibration represents the data needed to transform between the camera views and is + * different for each operating \p depth_mode and \p color_resolution the device is configured to operate in. + * + * \remarks + * The \p calibration output is used as input to all transformation functions. + * + * \see k4a_calibration_2d_to_2d() + * \see k4a_calibration_2d_to_3d() + * \see k4a_calibration_3d_to_2d() + * \see k4a_calibration_3d_to_3d() + * + * \relates k4a_device_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_calibration_get_from_raw(char *raw_calibration, + size_t raw_calibration_size, + const k4a_depth_mode_t depth_mode, + const k4a_color_resolution_t color_resolution, + k4a_calibration_t *calibration); + +/** Transform a 3D point of a source coordinate system into a 3D point of the target coordinate system + * + * \param calibration + * Location to read the camera calibration data. + * + * \param source_point3d_mm + * The 3D coordinates in millimeters representing a point in \p source_camera. + * + * \param source_camera + * The current camera. + * + * \param target_camera + * The target camera. + * + * \param target_point3d_mm + * Pointer to the output where the new 3D coordinates of the input point in the coordinate space of \p target_camera is + * stored in millimeters. + * + * \returns + * ::K4A_RESULT_SUCCEEDED if \p target_point3d_mm was successfully written. ::K4A_RESULT_FAILED if \p calibration + * contained invalid transformation parameters. + * + * \remarks + * This function is used to transform 3D points between depth and color camera coordinate systems. The function uses the + * extrinsic camera calibration. It computes the output via multiplication with a precomputed matrix encoding a 3D + * rotation and a 3D translation. If \p source_camera and \p target_camera are the same, then \p target_point3d_mm will + * be identical to \p source_point3d_mm. + * + * \relates k4a_calibration_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_calibration_3d_to_3d(const k4a_calibration_t *calibration, + const k4a_float3_t *source_point3d_mm, + const k4a_calibration_type_t source_camera, + const k4a_calibration_type_t target_camera, + k4a_float3_t *target_point3d_mm); + +/** Transform a 2D pixel coordinate with an associated depth value of the source camera into a 3D point of the target + * coordinate system. + * + * \param calibration + * Location to read the camera calibration obtained by k4a_device_get_calibration(). + * + * \param source_point2d + * The 2D pixel in \p source_camera coordinates. + * + * \param source_depth_mm + * The depth of \p source_point2d in millimeters. One way to derive the depth value in the color camera geometry is to + * use the function k4a_transformation_depth_image_to_color_camera(). + * + * \param source_camera + * The current camera. + * + * \param target_camera + * The target camera. + * + * \param target_point3d_mm + * Pointer to the output where the 3D coordinates of the input pixel in the coordinate system of \p target_camera is + * stored in millimeters. + * + * \param valid + * The output parameter returns a value of 1 if the \p source_point2d is a valid coordinate, and will return 0 if + * the coordinate is not valid in the calibration model. + * + * \returns + * ::K4A_RESULT_SUCCEEDED if \p target_point3d_mm was successfully written. ::K4A_RESULT_FAILED if \p calibration + * contained invalid transformation parameters. If the function returns ::K4A_RESULT_SUCCEEDED, but \p valid is 0, + * the transformation was computed, but the results in \p target_point3d_mm are outside of the range of valid + * calibration and should be ignored. + * + * \remarks + * This function applies the intrinsic calibration of \p source_camera to compute the 3D ray from the focal point of the + * camera through pixel \p source_point2d. The 3D point on this ray is then found using \p source_depth_mm. If \p + * target_camera is different from \p source_camera, the 3D point is transformed to \p target_camera using + * k4a_calibration_3d_to_3d(). In practice, \p source_camera and \p target_camera will often be identical. In this + * case, no 3D to 3D transformation is applied. + * + * \remarks + * If \p source_point2d is not considered as valid pixel coordinate + * according to the intrinsic camera model, \p valid is set to 0. If it is valid, \p valid will be set to 1. The user + * should not use the value of \p target_point3d_mm if \p valid was set to 0. + * + * \relates k4a_calibration_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_calibration_2d_to_3d(const k4a_calibration_t *calibration, + const k4a_float2_t *source_point2d, + const float source_depth_mm, + const k4a_calibration_type_t source_camera, + const k4a_calibration_type_t target_camera, + k4a_float3_t *target_point3d_mm, + int *valid); + +/** Transform a 3D point of a source coordinate system into a 2D pixel coordinate of the target camera. + * + * \param calibration + * Location to read the camera calibration obtained by k4a_device_get_calibration(). + * + * \param source_point3d_mm + * The 3D coordinates in millimeters representing a point in \p source_camera + * + * \param source_camera + * The current camera. + * + * \param target_camera + * The target camera. + * + * \param target_point2d + * Pointer to the output where the 2D pixel in \p target_camera coordinates is stored. + * + * \param valid + * The output parameter returns a value of 1 if the \p source_point3d_mm is a valid coordinate in the \p target_camera + * coordinate system, and will return 0 if the coordinate is not valid in the calibration model. + * + * \returns + * ::K4A_RESULT_SUCCEEDED if \p target_point2d was successfully written. ::K4A_RESULT_FAILED if \p calibration + * contained invalid transformation parameters. If the function returns ::K4A_RESULT_SUCCEEDED, but \p valid is 0, + * the transformation was computed, but the results in \p target_point2d are outside of the range of valid calibration + * and should be ignored. + * + * \remarks + * If \p target_camera is different from \p source_camera, \p source_point3d_mm is transformed to \p target_camera using + * k4a_calibration_3d_to_3d(). In practice, \p source_camera and \p target_camera will often be identical. In this + * case, no 3D to 3D transformation is applied. The 3D point in the coordinate system of \p target_camera is then + * projected onto the image plane using the intrinsic calibration of \p target_camera. + * + * \remarks + * If \p source_point3d_mm does not map to a valid 2D coordinate in the \p target_camera coordinate system, \p valid is + * set to 0. If it is valid, \p valid will be set to 1. The user should not use the value of \p target_point2d if \p + * valid was set to 0. + * + * \relates k4a_calibration_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_calibration_3d_to_2d(const k4a_calibration_t *calibration, + const k4a_float3_t *source_point3d_mm, + const k4a_calibration_type_t source_camera, + const k4a_calibration_type_t target_camera, + k4a_float2_t *target_point2d, + int *valid); + +/** Transform a 2D pixel coordinate with an associated depth value of the source camera into a 2D pixel coordinate of + * the target camera. + * + * \param calibration + * Location to read the camera calibration obtained by k4a_device_get_calibration(). + * + * \param source_point2d + * The 2D pixel in \p source_camera coordinates. + * + * \param source_depth_mm + * The depth of \p source_point2d in millimeters. One way to derive the depth value in the color camera geometry is to + * use the function k4a_transformation_depth_image_to_color_camera(). + * + * \param source_camera + * The current camera. + * + * \param target_camera + * The target camera. + * + * \param target_point2d + * The 2D pixel in \p target_camera coordinates. + * + * \param valid + * The output parameter returns a value of 1 if the \p source_point2d is a valid coordinate in the \p target_camera + * coordinate system, and will return 0 if the coordinate is not valid in the calibration model. + * + * \returns + * ::K4A_RESULT_SUCCEEDED if \p target_point2d was successfully written. ::K4A_RESULT_FAILED if \p calibration + * contained invalid transformation parameters. If the function returns ::K4A_RESULT_SUCCEEDED, but \p valid is 0, + * the transformation was computed, but the results in \p target_point2d are outside of the range of valid calibration + * and should be ignored. + * + * \remarks + * This function maps a pixel between the coordinate systems of the depth and color cameras. It is equivalent to calling + * k4a_calibration_2d_to_3d() to compute the 3D point corresponding to \p source_point2d and then using + * k4a_calibration_3d_to_2d() to map the 3D point into the coordinate system of the \p target_camera. + * + * \remarks + * If \p source_camera and \p target_camera are identical, the function immediately sets \p target_point2d to \p + * source_point2d and returns without computing any transformations. + * + * \remarks + * If \p source_point2d does not map to a valid 2D coordinate in the \p target_camera coordinate system, \p valid is set + * to 0. If it is valid, \p valid will be set to 1. The user should not use the value of \p target_point2d if \p valid + * was set to 0. + * + * \relates k4a_calibration_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_calibration_2d_to_2d(const k4a_calibration_t *calibration, + const k4a_float2_t *source_point2d, + const float source_depth_mm, + const k4a_calibration_type_t source_camera, + const k4a_calibration_type_t target_camera, + k4a_float2_t *target_point2d, + int *valid); + +/** Transform a 2D pixel coordinate from color camera into a 2D pixel coordinate of + * the depth camera. + * + * \param calibration + * Location to read the camera calibration obtained by k4a_device_get_calibration(). + * + * \param source_point2d + * The 2D pixel in \p color camera coordinates. + * + * \param depth_image + * Handle to input depth image. + * + * \param target_point2d + * The 2D pixel in \p depth camera coordinates. + * + * \param valid + * The output parameter returns a value of 1 if the \p source_point2d is a valid coordinate in the \p target_camera + * coordinate system, and will return 0 if the coordinate is not valid in the calibration model. + * + * \returns + * ::K4A_RESULT_SUCCEEDED if \p target_point2d was successfully written. ::K4A_RESULT_FAILED if \p calibration + * contained invalid transformation parameters. If the function returns ::K4A_RESULT_SUCCEEDED, but \p valid is 0, + * the transformation was computed, but the results in \p target_point2d are outside of the range of valid calibration + * and should be ignored. + * + * \remarks + * This function represents an alternative to k4a_calibration_2d_to_2d() if the number of pixels that need to be + * transformed is small. This function searches along an epipolar line in the depth image to find the corresponding + * depth pixel. If a larger number of pixels need to be transformed, it might be computationally cheaper to call + * k4a_transformation_depth_image_to_color_camera() to get correspondence depth values for these color pixels, then call + * the function k4a_calibration_2d_to_2d(). + * + * \remarks + * If \p source_point2d does not map to a valid 2D coordinate in the \p target_camera coordinate system, \p valid is set + * to 0. If it is valid, \p valid will be set to 1. The user should not use the value of \p target_point2d if \p valid + * was set to 0. + * + * \relates k4a_calibration_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_calibration_color_2d_to_depth_2d(const k4a_calibration_t *calibration, + const k4a_float2_t *source_point2d, + const k4a_image_t depth_image, + k4a_float2_t *target_point2d, + int *valid); + +/** Get handle to transformation handle. + * + * \param calibration + * A calibration structure obtained by k4a_device_get_calibration(). + * + * \returns + * A transformation handle. A NULL is returned if creation fails. + * + * \remarks + * The transformation handle is used to transform images from the coordinate system of one camera into the other. Each + * transformation handle requires some pre-computed resources to be allocated, which are retained until the handle is + * destroyed. + * + * \remarks + * The transformation handle must be destroyed with k4a_transformation_destroy() when it is no longer to be used. + * + * \relates k4a_calibration_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_transformation_t k4a_transformation_create(const k4a_calibration_t *calibration); + +/** Destroy transformation handle. + * + * \param transformation_handle + * Transformation handle to destroy. + * + * \relates k4a_transformation_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT void k4a_transformation_destroy(k4a_transformation_t transformation_handle); + +/** Transforms the depth map into the geometry of the color camera. + * + * \param transformation_handle + * Transformation handle. + * + * \param depth_image + * Handle to input depth image. + * + * \param transformed_depth_image + * Handle to output transformed depth image. + * + * \remarks + * This produces a depth image for which each pixel matches the corresponding pixel coordinates of the color camera. + * + * \remarks + * \p depth_image and \p transformed_depth_image must be of format ::K4A_IMAGE_FORMAT_DEPTH16. + * + * \remarks + * \p transformed_depth_image must have a width and height matching the width and height of the color camera in the mode + * specified by the \ref k4a_calibration_t used to create the \p transformation_handle with k4a_transformation_create(). + * + * \remarks + * The contents \p transformed_depth_image will be filled with the depth values derived from \p depth_image in the color + * camera's coordinate space. + * + * \remarks + * \p transformed_depth_image should be created by the caller using k4a_image_create() or + * k4a_image_create_from_buffer(). + * + * \returns + * ::K4A_RESULT_SUCCEEDED if \p transformed_depth_image was successfully written and ::K4A_RESULT_FAILED otherwise. + * + * \relates k4a_transformation_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_transformation_depth_image_to_color_camera(k4a_transformation_t transformation_handle, + const k4a_image_t depth_image, + k4a_image_t transformed_depth_image); + +/** Transforms depth map and a custom image into the geometry of the color camera. + * + * \param transformation_handle + * Transformation handle. + * + * \param depth_image + * Handle to input depth image. + * + * \param custom_image + * Handle to input custom image. + * + * \param transformed_depth_image + * Handle to output transformed depth image. + * + * \param transformed_custom_image + * Handle to output transformed custom image. + * + * \param interpolation_type + * Parameter that controls how pixels in \p custom_image should be interpolated when transformed to color camera space. + * K4A_TRANSFORMATION_INTERPOLATION_TYPE_LINEAR if linear interpolation should be used. + * K4A_TRANSFORMATION_INTERPOLATION_TYPE_NEAREST if nearest neighbor interpolation should be used. + * + * \param invalid_custom_value + * Defines the custom image pixel value that should be written to \p transformed_custom_image in case the corresponding + * depth pixel can not be transformed into the color camera space. + * + * \remarks + * This produces a depth image and a corresponding custom image for which each pixel matches the corresponding + * pixel coordinates of the color camera. + * + * \remarks + * \p depth_image and \p transformed_depth_image must be of format ::K4A_IMAGE_FORMAT_DEPTH16. + * + * \remarks + * \p custom_image and \p transformed_custom_image must be of format ::K4A_IMAGE_FORMAT_CUSTOM8 or + * ::K4A_IMAGE_FORMAT_CUSTOM16. + * + * \remarks + * \p transformed_depth_image and \p transformed_custom_image must have a width and height matching the width and + * height of the color camera in the mode specified by the \ref k4a_calibration_t used to create the + * \p transformation_handle with k4a_transformation_create(). + * + * \remarks + * \p custom_image must have a width and height matching the width and height of \p depth_image. + * + * \remarks + * The contents \p transformed_depth_image will be filled with the depth values derived from \p depth_image in the color + * camera's coordinate space. + * + * \remarks + * The contents \p transformed_custom_image will be filled with the values derived from \p custom_image in the color + * camera's coordinate space. + * + * \remarks + * \p transformed_depth_image and \p transformed_custom_image should be created by the caller using k4a_image_create() + * or k4a_image_create_from_buffer(). + * + * \remarks + * Using linear interpolation could create new values to \p transformed_custom_image which do no exist in \p + * custom_image. Setting \p use_linear_interpolation to false will prevent this from happenning but will result in less + * smooth image. + * + * \returns + * ::K4A_RESULT_SUCCEEDED if \p transformed_depth_image and \p transformed_custom_image were successfully written and + * ::K4A_RESULT_FAILED otherwise. + * + * \relates k4a_transformation_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t +k4a_transformation_depth_image_to_color_camera_custom(k4a_transformation_t transformation_handle, + const k4a_image_t depth_image, + const k4a_image_t custom_image, + k4a_image_t transformed_depth_image, + k4a_image_t transformed_custom_image, + k4a_transformation_interpolation_type_t interpolation_type, + uint32_t invalid_custom_value); + +/** Transforms a color image into the geometry of the depth camera. + * + * \param transformation_handle + * Transformation handle. + * + * \param depth_image + * Handle to input depth image. + * + * \param color_image + * Handle to input color image. + * + * \param transformed_color_image + * Handle to output transformed color image. + * + * \remarks + * This produces a color image for which each pixel matches the corresponding pixel coordinates of the depth camera. + * + * \remarks + * \p depth_image and \p color_image need to represent the same moment in time. The depth data will be applied to the + * color image to properly warp the color data to the perspective of the depth camera. + * + * \remarks + * \p depth_image must be of type ::K4A_IMAGE_FORMAT_DEPTH16. \p color_image must be of format + * ::K4A_IMAGE_FORMAT_COLOR_BGRA32. + * + * \remarks + * \p transformed_color_image image must be of format ::K4A_IMAGE_FORMAT_COLOR_BGRA32. \p transformed_color_image must + * have the width and height of the depth camera in the mode specified by the \ref k4a_calibration_t used to create + * the \p transformation_handle with k4a_transformation_create(). + * + * \remarks + * \p transformed_color_image should be created by the caller using k4a_image_create() or + * k4a_image_create_from_buffer(). + * + * \returns + * ::K4A_RESULT_SUCCEEDED if \p transformed_color_image was successfully written and ::K4A_RESULT_FAILED otherwise. + * + * \relates k4a_transformation_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_transformation_color_image_to_depth_camera(k4a_transformation_t transformation_handle, + const k4a_image_t depth_image, + const k4a_image_t color_image, + k4a_image_t transformed_color_image); + +/** Transforms the depth image into 3 planar images representing X, Y and Z-coordinates of corresponding 3D points. + * + * \param transformation_handle + * Transformation handle. + * + * \param depth_image + * Handle to input depth image. + * + * \param camera + * Geometry in which depth map was computed. + * + * \param xyz_image + * Handle to output xyz image. + * + * \remarks + * \p depth_image must be of format ::K4A_IMAGE_FORMAT_DEPTH16. + * + * \remarks + * The \p camera parameter tells the function what the perspective of the \p depth_image is. If the \p depth_image was + * captured directly from the depth camera, the value should be ::K4A_CALIBRATION_TYPE_DEPTH. If the \p depth_image is + * the result of a transformation into the color camera's coordinate space using + * k4a_transformation_depth_image_to_color_camera(), the value should be ::K4A_CALIBRATION_TYPE_COLOR. + * + * \remarks + * The format of \p xyz_image must be ::K4A_IMAGE_FORMAT_CUSTOM. The width and height of \p xyz_image must match the + * width and height of \p depth_image. \p xyz_image must have a stride in bytes of at least 6 times its width in pixels. + * + * \remarks + * Each pixel of the \p xyz_image consists of three int16_t values, totaling 6 bytes. The three int16_t values are the + * X, Y, and Z values of the point. + * + * \remarks + * \p xyz_image should be created by the caller using k4a_image_create() or k4a_image_create_from_buffer(). + * + * \returns + * ::K4A_RESULT_SUCCEEDED if \p xyz_image was successfully written and ::K4A_RESULT_FAILED otherwise. + * + * \relates k4a_transformation_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_transformation_depth_image_to_point_cloud(k4a_transformation_t transformation_handle, + const k4a_image_t depth_image, + const k4a_calibration_type_t camera, + k4a_image_t xyz_image); + +/** + * @} + */ + +#ifdef __cplusplus +} +#endif + +#endif /* K4A_H */ diff --git a/k4a-sys/vendor/include/linux/k4a/k4a.hpp b/k4a-sys/vendor/include/linux/k4a/k4a.hpp new file mode 100644 index 0000000000..6d9dea3311 --- /dev/null +++ b/k4a-sys/vendor/include/linux/k4a/k4a.hpp @@ -0,0 +1,1441 @@ +/** \file k4a.hpp + * Copyright (c) Microsoft Corporation. All rights reserved. + * Licensed under the MIT License. + * Kinect For Azure SDK - C++ wrapper. + */ + +#ifndef K4A_HPP +#define K4A_HPP + +#include "k4a.h" + +#include +#include +#include +#include +#include +#include +#include + +namespace k4a +{ + +/** + * \defgroup cppsdk C++ Reference + * + * Functions part of the SDK. + * + * @{ + */ + +/** Exception type thrown when a K4A API call fails + */ +class error : public std::runtime_error +{ +public: + using runtime_error::runtime_error; +}; + +// Helper functions not intended for use by client code +// +namespace internal +{ +/// @cond FALSE +/** Casts an arithmetic value, clamping to the supported range of the type being cast to + * + * \returns input represented in output_type + * + * \remarks + * Clamps to 0 for unsigned types + */ +template output_type clamp_cast(input_type input) +{ + static_assert(std::is_arithmetic::value, "clamp_cast only supports arithmetic types"); + static_assert(std::is_arithmetic::value, "clamp_cast only supports arithmetic types"); + const input_type min_value = std::is_signed() ? + static_cast(std::numeric_limits::min()) : + 0; + + input_type max_value = static_cast(std::numeric_limits::max()); + if (max_value < 0) + { + // Output type is of greater or equal size to input type and we've overflowed. + // + max_value = std::numeric_limits::max(); + } + input = std::min(input, max_value); + input = std::max(input, min_value); + return static_cast(input); +} +/// @endcond +} // namespace internal + +/** \class image k4a.hpp + * Wrapper for \ref k4a_image_t + * + * Wraps a handle for an image. Copying/moving is cheap, copies are shallow. + * + * \sa k4a_image_t + */ +class image +{ +public: + /** Creates an image from a k4a_image_t. + * Takes ownership of the handle, i.e. assuming that handle has a refcount + * of 1, you should not call k4a_image_release on the handle after giving + * it to the image; the image will take care of that. + */ + image(k4a_image_t handle = nullptr) noexcept : m_handle(handle) {} + + /** Creates a shallow copy of another image + */ + image(const image &other) noexcept : m_handle(other.m_handle) + { + if (m_handle != nullptr) + { + k4a_image_reference(m_handle); + } + } + + /** Moves another image into a new image + */ + image(image &&other) noexcept : m_handle(other.m_handle) + { + other.m_handle = nullptr; + } + + ~image() + { + reset(); + } + + /** Sets image to a shallow copy of other + */ + image &operator=(const image &other) noexcept + { + if (this != &other) + { + reset(); + m_handle = other.m_handle; + if (m_handle != nullptr) + { + k4a_image_reference(m_handle); + } + } + return *this; + } + + /** Moves another image into this image; other is set to invalid + */ + image &operator=(image &&other) noexcept + { + if (this != &other) + { + reset(); + m_handle = other.m_handle; + other.m_handle = nullptr; + } + return *this; + } + + /** Invalidates this image + */ + image &operator=(std::nullptr_t) noexcept + { + reset(); + return *this; + } + + /** Returns true if two images refer to the same k4a_image_t, false otherwise + */ + bool operator==(const image &other) const noexcept + { + return m_handle == other.m_handle; + } + + /** Returns false if the image is valid, true otherwise + */ + bool operator==(std::nullptr_t) const noexcept + { + return m_handle == nullptr; + } + + /** Returns true if two images wrap different k4a_image_t instances, false otherwise + */ + bool operator!=(const image &other) const noexcept + { + return m_handle != other.m_handle; + } + + /** Returns true if the image is valid, false otherwise + */ + bool operator!=(std::nullptr_t) const noexcept + { + return m_handle != nullptr; + } + + /** Returns true if the image is valid, false otherwise + */ + operator bool() const noexcept + { + return m_handle != nullptr; + } + + /** Returns the underlying k4a_image_t handle + * + * Note that this function does not increment the reference count on the k4a_image_t. + * The caller is responsible for incrementing the reference count on + * the k4a_image_t if the caller needs the k4a_image_t to outlive this C++ object. + * Otherwise, the k4a_image_t will be destroyed by this C++ object. + */ + k4a_image_t handle() const noexcept + { + return m_handle; + } + + /** Releases the underlying k4a_image_t; the image is set to invalid. + */ + void reset() noexcept + { + if (m_handle != nullptr) + { + k4a_image_release(m_handle); + m_handle = nullptr; + } + } + + /** Create a blank image + * Throws error on failure + * + * \sa k4a_image_create + */ + static image create(k4a_image_format_t format, int width_pixels, int height_pixels, int stride_bytes) + { + k4a_image_t handle = nullptr; + k4a_result_t result = k4a_image_create(format, width_pixels, height_pixels, stride_bytes, &handle); + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to create image!"); + } + return image(handle); + } + + /** Create an image from a pre-allocated buffer + * Throws error on failure + * + * \sa k4a_image_create_from_buffer + */ + static image create_from_buffer(k4a_image_format_t format, + int width_pixels, + int height_pixels, + int stride_bytes, + uint8_t *buffer, + size_t buffer_size, + k4a_memory_destroy_cb_t *buffer_release_cb, + void *buffer_release_cb_context) + { + k4a_image_t handle = nullptr; + k4a_result_t result = k4a_image_create_from_buffer(format, + width_pixels, + height_pixels, + stride_bytes, + buffer, + buffer_size, + buffer_release_cb, + buffer_release_cb_context, + &handle); + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to create image from buffer"); + } + return image(handle); + } + + /** Get the image buffer + * + * \sa k4a_image_get_buffer + */ + uint8_t *get_buffer() noexcept + { + return k4a_image_get_buffer(m_handle); + } + + /** Get the image buffer + * + * \sa k4a_image_get_buffer + */ + const uint8_t *get_buffer() const noexcept + { + return k4a_image_get_buffer(m_handle); + } + + /** Get the image buffer size in bytes + * + * \sa k4a_image_get_size + */ + size_t get_size() const noexcept + { + return k4a_image_get_size(m_handle); + } + + /** Get the image format of the image + * + * \sa k4a_image_get_format + */ + k4a_image_format_t get_format() const noexcept + { + return k4a_image_get_format(m_handle); + } + + /** Get the image width in pixels + * + * \sa k4a_image_get_width_pixels + */ + int get_width_pixels() const noexcept + { + return k4a_image_get_width_pixels(m_handle); + } + + /** Get the image height in pixels + * + * \sa k4a_image_get_height_pixels + */ + int get_height_pixels() const noexcept + { + return k4a_image_get_height_pixels(m_handle); + } + + /** Get the image stride in bytes + * + * \sa k4a_image_get_stride_bytes + */ + int get_stride_bytes() const noexcept + { + return k4a_image_get_stride_bytes(m_handle); + } + + /** Get the image's device timestamp in microseconds + * + * \sa k4a_image_get_device_timestamp_usec + */ + std::chrono::microseconds get_device_timestamp() const noexcept + { + return std::chrono::microseconds(k4a_image_get_device_timestamp_usec(m_handle)); + } + + /** Get the image's system timestamp in nanoseconds + * + * \sa k4a_image_get_system_timestamp_nsec + */ + std::chrono::nanoseconds get_system_timestamp() const noexcept + { + return std::chrono::nanoseconds(k4a_image_get_system_timestamp_nsec(m_handle)); + } + + /** Get the image exposure time in microseconds + * + * \sa k4a_image_get_exposure_usec + */ + std::chrono::microseconds get_exposure() const noexcept + { + return std::chrono::microseconds(k4a_image_get_exposure_usec(m_handle)); + } + + /** Get the image white balance in Kelvin (color images only) + * + * \sa k4a_image_get_white_balance + */ + uint32_t get_white_balance() const noexcept + { + return k4a_image_get_white_balance(m_handle); + } + + /** Get the image's ISO speed (color images only) + * + * \sa k4a_image_get_white_balance + */ + uint32_t get_iso_speed() const noexcept + { + return k4a_image_get_iso_speed(m_handle); + } + + /** Set the image's timestamp in microseconds + * + * \sa k4a_image_set_device_timestamp_usec + */ + void set_timestamp(std::chrono::microseconds timestamp) noexcept + { + k4a_image_set_device_timestamp_usec(m_handle, internal::clamp_cast(timestamp.count())); + } + + /** Set the image's exposure time in microseconds (color images only) + * + * \sa k4a_image_set_exposure_time_usec + */ + void set_exposure_time(std::chrono::microseconds exposure) noexcept + { + k4a_image_set_exposure_usec(m_handle, internal::clamp_cast(exposure.count())); + } + + /** Set the white balance of the image (color images only) + * + * \sa k4a_image_set_white_balance + */ + void set_white_balance(uint32_t white_balance) noexcept + { + k4a_image_set_white_balance(m_handle, white_balance); + } + + /** Set the ISO speed of the image (color images only) + * + * \sa k4a_image_set_iso_speed + */ + void set_iso_speed(uint32_t iso_speed) noexcept + { + k4a_image_set_iso_speed(m_handle, iso_speed); + } + +private: + k4a_image_t m_handle; +}; + +/** \class capture k4a.hpp + * Wrapper for \ref k4a_capture_t + * + * Wraps a handle for a capture. Copying/moving is cheap, copies are shallow. + */ +class capture +{ +public: + /** Creates a capture from a k4a_capture_t + * Takes ownership of the handle, i.e. assuming that handle has a refcount + * of 1, you should not call k4a_capture_release on the handle after giving + * it to the capture; the capture will take care of that. + */ + capture(k4a_capture_t handle = nullptr) noexcept : m_handle(handle) {} + + /** Creates a shallow copy of another capture + */ + capture(const capture &other) noexcept : m_handle(other.m_handle) + { + if (m_handle != nullptr) + { + k4a_capture_reference(m_handle); + } + } + + /** Moves another capture into a new capture + */ + capture(capture &&other) noexcept : m_handle(other.m_handle) + { + other.m_handle = nullptr; + } + + ~capture() + { + reset(); + } + + /** Sets capture to a shallow copy of other + */ + capture &operator=(const capture &other) noexcept + { + if (this != &other) + { + reset(); + m_handle = other.m_handle; + if (m_handle != nullptr) + { + k4a_capture_reference(m_handle); + } + } + return *this; + } + + /** Moves another capture into this capture; other is set to invalid + */ + capture &operator=(capture &&other) noexcept + { + if (this != &other) + { + reset(); + m_handle = other.m_handle; + other.m_handle = nullptr; + } + return *this; + } + + /** Invalidates this capture + */ + capture &operator=(std::nullptr_t) noexcept + { + reset(); + return *this; + } + + /** Returns true if two captures refer to the same k4a_capture_t, false otherwise + */ + bool operator==(const capture &other) const noexcept + { + return m_handle == other.m_handle; + } + + /** Returns false if the capture is valid, true otherwise + */ + bool operator==(std::nullptr_t) const noexcept + { + return m_handle == nullptr; + } + + /** Returns true if two captures wrap different k4a_capture_t instances, false otherwise + */ + bool operator!=(const capture &other) const noexcept + { + return m_handle != other.m_handle; + } + + /** Returns true if the capture is valid, false otherwise + */ + bool operator!=(std::nullptr_t) const noexcept + { + return m_handle != nullptr; + } + + /** Returns true if the capture is valid, false otherwise + */ + operator bool() const noexcept + { + return m_handle != nullptr; + } + + /** Returns the underlying k4a_capture_t handle + * + * Note that this function does not increment the reference count on the k4a_capture_t. + * The caller is responsible for incrementing the reference count on + * the k4a_capture_t if the caller needs the k4a_capture_t to outlive this C++ object. + * Otherwise, the k4a_capture_t will be destroyed by this C++ object. + */ + k4a_capture_t handle() const noexcept + { + return m_handle; + } + + /** Releases the underlying k4a_capture_t; the capture is set to invalid. + */ + void reset() noexcept + { + if (m_handle != nullptr) + { + k4a_capture_release(m_handle); + m_handle = nullptr; + } + } + + /** Get the color image associated with the capture + * + * \sa k4a_capture_get_color_image + */ + image get_color_image() const noexcept + { + return image(k4a_capture_get_color_image(m_handle)); + } + + /** Get the depth image associated with the capture + * + * \sa k4a_capture_get_depth_image + */ + image get_depth_image() const noexcept + { + return image(k4a_capture_get_depth_image(m_handle)); + } + + /** Get the IR image associated with the capture + * + * \sa k4a_capture_get_ir_image + */ + image get_ir_image() const noexcept + { + return image(k4a_capture_get_ir_image(m_handle)); + } + + /** Set / add a color image to the capture + * + * \sa k4a_capture_set_color_image + */ + void set_color_image(const image &color_image) noexcept + { + k4a_capture_set_color_image(m_handle, color_image.handle()); + } + + /** Set / add a depth image to the capture + * + * \sa k4a_capture_set_depth_image + */ + void set_depth_image(const image &depth_image) noexcept + { + k4a_capture_set_depth_image(m_handle, depth_image.handle()); + } + + /** Set / add an IR image to the capture + * + * \sa k4a_capture_set_ir_image + */ + void set_ir_image(const image &ir_image) noexcept + { + k4a_capture_set_ir_image(m_handle, ir_image.handle()); + } + + /** Set the temperature associated with the capture in Celsius. + * + * \sa k4a_capture_set_temperature_c + */ + void set_temperature_c(float temperature_c) noexcept + { + k4a_capture_set_temperature_c(m_handle, temperature_c); + } + + /** Get temperature (in Celsius) associated with the capture. + * + * \sa k4a_capture_get_temperature_c + */ + float get_temperature_c() const noexcept + { + return k4a_capture_get_temperature_c(m_handle); + } + + /** Create an empty capture object. + * Throws error on failure. + * + * \sa k4a_capture_create + */ + static capture create() + { + k4a_capture_t handle = nullptr; + k4a_result_t result = k4a_capture_create(&handle); + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to create capture!"); + } + return capture(handle); + } + +private: + k4a_capture_t m_handle; +}; + +/** \class calibration k4a.hpp + * Wrapper for \ref k4a_calibration_t + * + * Provides member functions for k4a_calibration_t. + */ +struct calibration : public k4a_calibration_t +{ + /** Transform a 3d point of a source coordinate system into a 3d point of the target coordinate system. + * Throws error on failure. + * + * \sa k4a_calibration_3d_to_3d + */ + k4a_float3_t convert_3d_to_3d(const k4a_float3_t &source_point3d, + k4a_calibration_type_t source_camera, + k4a_calibration_type_t target_camera) const + { + k4a_float3_t target_point3d; + k4a_result_t result = + k4a_calibration_3d_to_3d(this, &source_point3d, source_camera, target_camera, &target_point3d); + + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Calibration contained invalid transformation parameters!"); + } + return target_point3d; + } + + /** Transform a 2d pixel coordinate with an associated depth value of the source camera into a 3d point of the + * target coordinate system. + * Returns false if the point is invalid in the target coordinate system (and therefore target_point3d should not be + * used) + * Throws error if calibration contains invalid data. + * + * \sa k4a_calibration_2d_to_3d + */ + bool convert_2d_to_3d(const k4a_float2_t &source_point2d, + float source_depth, + k4a_calibration_type_t source_camera, + k4a_calibration_type_t target_camera, + k4a_float3_t *target_point3d) const + { + int valid = 0; + k4a_result_t result = k4a_calibration_2d_to_3d( + this, &source_point2d, source_depth, source_camera, target_camera, target_point3d, &valid); + + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Calibration contained invalid transformation parameters!"); + } + return static_cast(valid); + } + + /** Transform a 3d point of a source coordinate system into a 2d pixel coordinate of the target camera. + * Returns false if the point is invalid in the target coordinate system (and therefore target_point2d should not be + * used) + * Throws error if calibration contains invalid data. + * + * \sa k4a_calibration_3d_to_2d + */ + bool convert_3d_to_2d(const k4a_float3_t &source_point3d, + k4a_calibration_type_t source_camera, + k4a_calibration_type_t target_camera, + k4a_float2_t *target_point2d) const + { + int valid = 0; + k4a_result_t result = + k4a_calibration_3d_to_2d(this, &source_point3d, source_camera, target_camera, target_point2d, &valid); + + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Calibration contained invalid transformation parameters!"); + } + return static_cast(valid); + } + + /** Transform a 2d pixel coordinate with an associated depth value of the source camera into a 2d pixel coordinate + * of the target camera + * Returns false if the point is invalid in the target coordinate system (and therefore target_point2d should not be + * used) + * Throws error if calibration contains invalid data. + * + * \sa k4a_calibration_2d_to_2d + */ + bool convert_2d_to_2d(const k4a_float2_t &source_point2d, + float source_depth, + k4a_calibration_type_t source_camera, + k4a_calibration_type_t target_camera, + k4a_float2_t *target_point2d) const + { + int valid = 0; + k4a_result_t result = k4a_calibration_2d_to_2d( + this, &source_point2d, source_depth, source_camera, target_camera, target_point2d, &valid); + + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Calibration contained invalid transformation parameters!"); + } + return static_cast(valid); + } + + /** Transform a 2D pixel coordinate from color camera into a 2D pixel coordinate of the depth camera. This function + * searches along an epipolar line in the depth image to find the corresponding depth pixel. + * Returns false if the point is invalid in the target coordinate system (and therefore target_point2d should not be + * used) Throws error if calibration contains invalid data. + * + * \sa k4a_calibration_color_2d_to_depth_2d + */ + bool convert_color_2d_to_depth_2d(const k4a_float2_t &source_point2d, + const image &depth_image, + k4a_float2_t *target_point2d) const + { + int valid = 0; + k4a_result_t result = + k4a_calibration_color_2d_to_depth_2d(this, &source_point2d, depth_image.handle(), target_point2d, &valid); + + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Calibration contained invalid transformation parameters!"); + } + return static_cast(valid); + } + + /** Get the camera calibration for a device from a raw calibration blob. + * Throws error on failure. + * + * \sa k4a_calibration_get_from_raw + */ + static calibration get_from_raw(char *raw_calibration, + size_t raw_calibration_size, + k4a_depth_mode_t target_depth_mode, + k4a_color_resolution_t target_color_resolution) + { + calibration calib; + k4a_result_t result = k4a_calibration_get_from_raw(raw_calibration, + raw_calibration_size, + target_depth_mode, + target_color_resolution, + &calib); + + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to load calibration from raw calibration blob!"); + } + return calib; + } + + /** Get the camera calibration for a device from a raw calibration blob. + * Throws error on failure. + * + * \sa k4a_calibration_get_from_raw + */ + static calibration get_from_raw(uint8_t *raw_calibration, + size_t raw_calibration_size, + k4a_depth_mode_t target_depth_mode, + k4a_color_resolution_t target_color_resolution) + { + return get_from_raw(reinterpret_cast(raw_calibration), + raw_calibration_size, + target_depth_mode, + target_color_resolution); + } + + /** Get the camera calibration for a device from a raw calibration blob. + * Throws error on failure. + * + * \sa k4a_calibration_get_from_raw + */ + static calibration get_from_raw(std::vector &raw_calibration, + k4a_depth_mode_t target_depth_mode, + k4a_color_resolution_t target_color_resolution) + { + return get_from_raw(reinterpret_cast(raw_calibration.data()), + raw_calibration.size(), + target_depth_mode, + target_color_resolution); + } +}; + +/** \class transformation k4a.hpp + * Wrapper for \ref k4a_transformation_t + * + * Wraps a handle for a transformation. + */ +class transformation +{ +public: + /** Creates a transformation associated with calibration + * + * \sa k4a_transformation_create + */ + transformation(const k4a_calibration_t &calibration) noexcept : + m_handle(k4a_transformation_create(&calibration)), + m_color_resolution({ calibration.color_camera_calibration.resolution_width, + calibration.color_camera_calibration.resolution_height }), + m_depth_resolution({ calibration.depth_camera_calibration.resolution_width, + calibration.depth_camera_calibration.resolution_height }) + { + } + + /** Creates a transformation from a k4a_transformation_t + * Takes ownership of the handle, i.e. you should not call + * k4a_transformation_destroy on the handle after giving + * it to the transformation; the transformation will take care of that. + */ + transformation(k4a_transformation_t handle = nullptr) noexcept : m_handle(handle) {} + + /** Moves another tranformation into a new transformation + */ + transformation(transformation &&other) noexcept : + m_handle(other.m_handle), + m_color_resolution(other.m_color_resolution), + m_depth_resolution(other.m_depth_resolution) + { + other.m_handle = nullptr; + } + + transformation(const transformation &) = delete; + + ~transformation() + { + destroy(); + } + + /** Moves another image into this image; other is set to invalid + */ + transformation &operator=(transformation &&other) noexcept + { + if (this != &other) + { + destroy(); + m_handle = other.m_handle; + m_color_resolution = other.m_color_resolution; + m_depth_resolution = other.m_depth_resolution; + other.m_handle = nullptr; + } + + return *this; + } + + /** Invalidates this transformation + */ + transformation &operator=(std::nullptr_t) noexcept + { + destroy(); + return *this; + } + + transformation &operator=(const transformation &) = delete; + + /** Invalidates this transformation + */ + void destroy() noexcept + { + if (m_handle != nullptr) + { + k4a_transformation_destroy(m_handle); + m_handle = nullptr; + } + } + + /** Transforms the depth map into the geometry of the color camera. + * Throws error on failure + * + * \sa k4a_transformation_depth_image_to_color_camera + * Transforms the output in to the existing caller provided \p transformed_depth_image. + */ + void depth_image_to_color_camera(const image &depth_image, image *transformed_depth_image) const + { + k4a_result_t result = k4a_transformation_depth_image_to_color_camera(m_handle, + depth_image.handle(), + transformed_depth_image->handle()); + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to convert depth map to color camera geometry!"); + } + } + + /** Transforms the depth map into the geometry of the color camera. + * Throws error on failure + * + * \sa k4a_transformation_depth_image_to_color_camera + * Creates a new image with the output. + */ + image depth_image_to_color_camera(const image &depth_image) const + { + image transformed_depth_image = image::create(K4A_IMAGE_FORMAT_DEPTH16, + m_color_resolution.width, + m_color_resolution.height, + m_color_resolution.width * + static_cast(sizeof(uint16_t))); + depth_image_to_color_camera(depth_image, &transformed_depth_image); + return transformed_depth_image; + } + + /** Transforms depth map and a custom image into the geometry of the color camera. + * Throws error on failure + * + * \sa k4a_transformation_depth_image_to_color_camera_custom + * Transforms the output in to the existing caller provided \p transformed_depth_image \p transformed_custom_image. + */ + void depth_image_to_color_camera_custom(const image &depth_image, + const image &custom_image, + image *transformed_depth_image, + image *transformed_custom_image, + k4a_transformation_interpolation_type_t interpolation_type, + uint32_t invalid_custom_value) const + { + k4a_result_t result = k4a_transformation_depth_image_to_color_camera_custom(m_handle, + depth_image.handle(), + custom_image.handle(), + transformed_depth_image->handle(), + transformed_custom_image->handle(), + interpolation_type, + invalid_custom_value); + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to convert depth map and custom image to color camera geometry!"); + } + } + + /** Transforms depth map and a custom image into the geometry of the color camera. + * Throws error on failure + * + * \sa k4a_transformation_depth_image_to_color_camera_custom + * Creates a new image with the output. + */ + std::pair + depth_image_to_color_camera_custom(const image &depth_image, + const image &custom_image, + k4a_transformation_interpolation_type_t interpolation_type, + uint32_t invalid_custom_value) const + { + image transformed_depth_image = image::create(K4A_IMAGE_FORMAT_DEPTH16, + m_color_resolution.width, + m_color_resolution.height, + m_color_resolution.width * + static_cast(sizeof(uint16_t))); + int32_t bytes_per_pixel; + switch (custom_image.get_format()) + { + case K4A_IMAGE_FORMAT_CUSTOM8: + bytes_per_pixel = static_cast(sizeof(int8_t)); + break; + case K4A_IMAGE_FORMAT_CUSTOM16: + bytes_per_pixel = static_cast(sizeof(int16_t)); + break; + default: + throw error("Failed to support this format of custom image!"); + } + image transformed_custom_image = image::create(custom_image.get_format(), + m_color_resolution.width, + m_color_resolution.height, + m_color_resolution.width * bytes_per_pixel); + depth_image_to_color_camera_custom(depth_image, + custom_image, + &transformed_depth_image, + &transformed_custom_image, + interpolation_type, + invalid_custom_value); + return { std::move(transformed_depth_image), std::move(transformed_custom_image) }; + } + + /** Transforms the color image into the geometry of the depth camera. + * Throws error on failure + * + * \sa k4a_transformation_color_image_to_depth_camera + * Transforms the output in to the existing caller provided \p transformed_color_image. + */ + void color_image_to_depth_camera(const image &depth_image, + const image &color_image, + image *transformed_color_image) const + { + k4a_result_t result = k4a_transformation_color_image_to_depth_camera(m_handle, + depth_image.handle(), + color_image.handle(), + transformed_color_image->handle()); + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to convert color image to depth camera geometry!"); + } + } + + /** Transforms the color image into the geometry of the depth camera. + * Throws error on failure + * + * \sa k4a_transformation_color_image_to_depth_camera + * Creates a new image with the output. + */ + image color_image_to_depth_camera(const image &depth_image, const image &color_image) const + { + image transformed_color_image = image::create(K4A_IMAGE_FORMAT_COLOR_BGRA32, + m_depth_resolution.width, + m_depth_resolution.height, + m_depth_resolution.width * 4 * + static_cast(sizeof(uint8_t))); + color_image_to_depth_camera(depth_image, color_image, &transformed_color_image); + return transformed_color_image; + } + + /** Transforms the depth image into 3 planar images representing X, Y and Z-coordinates of corresponding 3d points. + * Throws error on failure. + * + * \sa k4a_transformation_depth_image_to_point_cloud + * Transforms the output in to the existing caller provided \p xyz_image. + */ + void depth_image_to_point_cloud(const image &depth_image, k4a_calibration_type_t camera, image *xyz_image) const + { + k4a_result_t result = + k4a_transformation_depth_image_to_point_cloud(m_handle, depth_image.handle(), camera, xyz_image->handle()); + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to transform depth image to point cloud!"); + } + } + + /** Transforms the depth image into 3 planar images representing X, Y and Z-coordinates of corresponding 3d points. + * Throws error on failure. + * + * \sa k4a_transformation_depth_image_to_point_cloud + * Creates a new image with the output. + */ + image depth_image_to_point_cloud(const image &depth_image, k4a_calibration_type_t camera) const + { + image xyz_image = image::create(K4A_IMAGE_FORMAT_CUSTOM, + depth_image.get_width_pixels(), + depth_image.get_height_pixels(), + depth_image.get_width_pixels() * 3 * static_cast(sizeof(int16_t))); + depth_image_to_point_cloud(depth_image, camera, &xyz_image); + return xyz_image; + } + +private: + k4a_transformation_t m_handle; + struct resolution + { + int32_t width; + int32_t height; + }; + resolution m_color_resolution; + resolution m_depth_resolution; +}; + +/** \class device k4a.hpp + * Wrapper for \ref k4a_device_t + * + * Wraps a handle for a device. + */ +class device +{ +public: + /** Creates a device from a k4a_device_t + * Takes ownership of the handle, i.e. you should not call + * k4a_device_close on the handle after giving it to the + * device; the device will take care of that. + */ + device(k4a_device_t handle = nullptr) noexcept : m_handle(handle) {} + + /** Moves another device into a new device + */ + device(device &&dev) noexcept : m_handle(dev.m_handle) + { + dev.m_handle = nullptr; + } + + device(const device &) = delete; + + ~device() + { + close(); + } + + device &operator=(const device &) = delete; + + /** Moves another device into this device; other is set to invalid + */ + device &operator=(device &&dev) noexcept + { + if (this != &dev) + { + close(); + m_handle = dev.m_handle; + dev.m_handle = nullptr; + } + return *this; + } + + /** Returns true if the device is valid, false otherwise + */ + operator bool() const noexcept + { + return m_handle != nullptr; + } + + /** Returns the underlying k4a_device_t handle + * + * Note the k4a_device_t handle does not have a reference count will be destroyed when the C++ object is destroyed. + * The caller is responsible for ensuring the C++ object outlives this handle. + */ + k4a_device_t handle() const noexcept + { + return m_handle; + } + + /** Closes a k4a device. + * + * \sa k4a_device_close + */ + void close() noexcept + { + if (m_handle != nullptr) + { + k4a_device_close(m_handle); + m_handle = nullptr; + } + } + + /** Reads a sensor capture into cap. Returns true if a capture was read, false if the read timed out. + * Throws error on failure. + * + * \sa k4a_device_get_capture + */ + bool get_capture(capture *cap, std::chrono::milliseconds timeout) + { + k4a_capture_t capture_handle = nullptr; + int32_t timeout_ms = internal::clamp_cast(timeout.count()); + k4a_wait_result_t result = k4a_device_get_capture(m_handle, &capture_handle, timeout_ms); + if (result == K4A_WAIT_RESULT_FAILED) + { + throw error("Failed to get capture from device!"); + } + else if (result == K4A_WAIT_RESULT_TIMEOUT) + { + return false; + } + + *cap = capture(capture_handle); + return true; + } + + /** Reads a sensor capture into cap. Returns true if a capture was read, false if the read timed out. + * Throws error on failure. This API assumes an inifinate timeout. + * + * \sa k4a_device_get_capture + */ + bool get_capture(capture *cap) + { + return get_capture(cap, std::chrono::milliseconds(K4A_WAIT_INFINITE)); + } + + /** Reads an IMU sample. Returns true if a sample was read, false if the read timed out. + * Throws error on failure. + * + * \sa k4a_device_get_imu_sample + */ + bool get_imu_sample(k4a_imu_sample_t *imu_sample, std::chrono::milliseconds timeout) + { + int32_t timeout_ms = internal::clamp_cast(timeout.count()); + k4a_wait_result_t result = k4a_device_get_imu_sample(m_handle, imu_sample, timeout_ms); + if (result == K4A_WAIT_RESULT_FAILED) + { + throw error("Failed to get IMU sample from device!"); + } + else if (result == K4A_WAIT_RESULT_TIMEOUT) + { + return false; + } + + return true; + } + + /** Reads an IMU sample. Returns true if a sample was read, false if the read timed out. + * Throws error on failure. This API assumes an infinate timeout. + * + * \sa k4a_device_get_imu_sample + */ + bool get_imu_sample(k4a_imu_sample_t *imu_sample) + { + return get_imu_sample(imu_sample, std::chrono::milliseconds(K4A_WAIT_INFINITE)); + } + + /** Starts the K4A device's cameras + * Throws error on failure. + * + * \sa k4a_device_start_cameras + */ + void start_cameras(const k4a_device_configuration_t *configuration) + { + k4a_result_t result = k4a_device_start_cameras(m_handle, configuration); + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to start cameras!"); + } + } + + /** Stops the K4A device's cameras + * + * \sa k4a_device_stop_cameras + */ + void stop_cameras() noexcept + { + k4a_device_stop_cameras(m_handle); + } + + /** Starts the K4A IMU + * Throws error on failure + * + * \sa k4a_device_start_imu + */ + void start_imu() + { + k4a_result_t result = k4a_device_start_imu(m_handle); + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to start IMU!"); + } + } + + /** Stops the K4A IMU + * + * \sa k4a_device_stop_imu + */ + void stop_imu() noexcept + { + k4a_device_stop_imu(m_handle); + } + + /** Get the K4A device serial number + * Throws error on failure. + * + * \sa k4a_device_get_serialnum + */ + std::string get_serialnum() const + { + std::string serialnum; + size_t buffer = 0; + k4a_buffer_result_t result = k4a_device_get_serialnum(m_handle, &serialnum[0], &buffer); + + if (result == K4A_BUFFER_RESULT_TOO_SMALL && buffer > 1) + { + serialnum.resize(buffer); + result = k4a_device_get_serialnum(m_handle, &serialnum[0], &buffer); + if (result == K4A_BUFFER_RESULT_SUCCEEDED && serialnum[buffer - 1] == 0) + { + // std::string expects there to not be as null terminator at the end of its data but + // k4a_device_get_serialnum adds a null terminator, so we drop the last character of the string after we + // get the result back. + serialnum.resize(buffer - 1); + } + } + + if (result != K4A_BUFFER_RESULT_SUCCEEDED) + { + throw error("Failed to read device serial number!"); + } + + return serialnum; + } + + /** Get the K4A color sensor control value + * Throws error on failure. + * + * \sa k4a_device_get_color_control + */ + void get_color_control(k4a_color_control_command_t command, k4a_color_control_mode_t *mode, int32_t *value) const + { + k4a_result_t result = k4a_device_get_color_control(m_handle, command, mode, value); + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to read color control!"); + } + } + + /** Set the K4A color sensor control value + * Throws error on failure. + * + * \sa k4a_device_set_color_control + */ + void set_color_control(k4a_color_control_command_t command, k4a_color_control_mode_t mode, int32_t value) + { + k4a_result_t result = k4a_device_set_color_control(m_handle, command, mode, value); + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to set color control!"); + } + } + + /** Get the raw calibration blob for the entire K4A device. + * Throws error on failure. + * + * \sa k4a_device_get_raw_calibration + */ + std::vector get_raw_calibration() const + { + std::vector calibration; + size_t buffer = 0; + k4a_buffer_result_t result = k4a_device_get_raw_calibration(m_handle, &calibration[0], &buffer); + + if (result == K4A_BUFFER_RESULT_TOO_SMALL && buffer > 1) + { + calibration.resize(buffer); + result = k4a_device_get_raw_calibration(m_handle, &calibration[0], &buffer); + } + + if (result != K4A_BUFFER_RESULT_SUCCEEDED) + { + throw error("Failed to read raw device calibration!"); + } + + return calibration; + } + + /** Get the camera calibration for the entire K4A device, which is used for all transformation functions. + * Throws error on failure. + * + * \sa k4a_device_get_calibration + */ + calibration get_calibration(k4a_depth_mode_t depth_mode, k4a_color_resolution_t color_resolution) const + { + calibration calib; + k4a_result_t result = k4a_device_get_calibration(m_handle, depth_mode, color_resolution, &calib); + + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to read device calibration!"); + } + return calib; + } + + /** Get the device jack status for the synchronization in connector + * Throws error on failure. + * + * \sa k4a_device_get_sync_jack + */ + bool is_sync_in_connected() const + { + bool sync_in_jack_connected, sync_out_jack_connected; + k4a_result_t result = k4a_device_get_sync_jack(m_handle, &sync_in_jack_connected, &sync_out_jack_connected); + + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to read sync jack status!"); + } + return sync_in_jack_connected; + } + + /** Get the device jack status for the synchronization out connector + * Throws error on failure. + * + * \sa k4a_device_get_sync_jack + */ + bool is_sync_out_connected() const + { + bool sync_in_jack_connected, sync_out_jack_connected; + k4a_result_t result = k4a_device_get_sync_jack(m_handle, &sync_in_jack_connected, &sync_out_jack_connected); + + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to read sync jack status!"); + } + return sync_out_jack_connected; + } + + /** Get the version numbers of the K4A subsystems' firmware + * Throws error on failure. + * + * \sa k4a_device_get_version + */ + k4a_hardware_version_t get_version() const + { + k4a_hardware_version_t version; + k4a_result_t result = k4a_device_get_version(m_handle, &version); + + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to read device firmware information!"); + } + return version; + } + + /** Open a k4a device. + * Throws error on failure. + * + * \sa k4a_device_open + */ + static device open(uint32_t index) + { + k4a_device_t handle = nullptr; + k4a_result_t result = k4a_device_open(index, &handle); + + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to open device!"); + } + return device(handle); + } + + /** Gets the number of connected devices + * + * \sa k4a_device_get_installed_count + */ + static uint32_t get_installed_count() noexcept + { + return k4a_device_get_installed_count(); + } + +private: + k4a_device_t m_handle; +}; + +/** + * @} + */ + +} // namespace k4a + +#endif diff --git a/k4a-sys/vendor/include/linux/k4a/k4a_export.h b/k4a-sys/vendor/include/linux/k4a/k4a_export.h new file mode 100644 index 0000000000..dadda0fc5f --- /dev/null +++ b/k4a-sys/vendor/include/linux/k4a/k4a_export.h @@ -0,0 +1,42 @@ + +#ifndef K4A_EXPORT_H +#define K4A_EXPORT_H + +#ifdef K4A_STATIC_DEFINE +# define K4A_EXPORT +# define K4A_NO_EXPORT +#else +# ifndef K4A_EXPORT +# ifdef k4a_EXPORTS + /* We are building this library */ +# define K4A_EXPORT __attribute__((visibility("default"))) +# else + /* We are using this library */ +# define K4A_EXPORT __attribute__((visibility("default"))) +# endif +# endif + +# ifndef K4A_NO_EXPORT +# define K4A_NO_EXPORT __attribute__((visibility("hidden"))) +# endif +#endif + +#ifndef K4A_DEPRECATED +# define K4A_DEPRECATED __attribute__ ((__deprecated__)) +#endif + +#ifndef K4A_DEPRECATED_EXPORT +# define K4A_DEPRECATED_EXPORT K4A_EXPORT K4A_DEPRECATED +#endif + +#ifndef K4A_DEPRECATED_NO_EXPORT +# define K4A_DEPRECATED_NO_EXPORT K4A_NO_EXPORT K4A_DEPRECATED +#endif + +#if 0 /* DEFINE_NO_DEPRECATED */ +# ifndef K4A_NO_DEPRECATED +# define K4A_NO_DEPRECATED +# endif +#endif + +#endif diff --git a/k4a-sys/vendor/include/linux/k4a/k4atypes.h b/k4a-sys/vendor/include/linux/k4a/k4atypes.h new file mode 100644 index 0000000000..e7d17bd339 --- /dev/null +++ b/k4a-sys/vendor/include/linux/k4a/k4atypes.h @@ -0,0 +1,1271 @@ +/** \file k4atypes.h + * Copyright (c) Microsoft Corporation. All rights reserved. + * Licensed under the MIT License. + * Kinect For Azure SDK Type definitions. + */ + +#ifndef K4ATYPES_H +#define K4ATYPES_H + +#ifdef __cplusplus +#include +#include +#include +#else +#include +#include +#include +#include +#endif + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * Declare an opaque handle type. + * + * \param _handle_name_ The type name of the handle + * + * \remarks + * This is used to define the public handle types for the Azure Kinect APIs. + * The macro is not intended to be used outside of the Azure Kinect headers. + */ +#define K4A_DECLARE_HANDLE(_handle_name_) \ + typedef struct _##_handle_name_ \ + { \ + size_t _rsvd; /**< Reserved, do not use. */ \ + } * _handle_name_; + +/** + * \defgroup csdk C Reference + * + */ +/** + * \defgroup Handles Handles + * \ingroup csdk + * Handles represent object instances. + * + * Handles are opaque pointers returned by the SDK which represent an object. + * + * @{ + */ + +/** \class k4a_device_t k4a.h + * Handle to an Azure Kinect device. + * + * \remarks + * Handles are created with k4a_device_open() and closed with k4a_device_close(). Invalid handles are set to 0. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +K4A_DECLARE_HANDLE(k4a_device_t); + +/** \class k4a_capture_t k4a.h + * Handle to an Azure Kinect capture. + * + * \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 + * 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, k4a_device_get_capture() will return a capture containing both image types separated by the + * configured delay. + * + * \remarks + * The capture will add a reference on any \ref k4a_image_t that is added to it with one of the setters like + * k4a_capture_set_color_image(). If an existing image is being replaced, the previous image will have the reference + * released. + * + * \remarks + * Once all references to the \ref k4a_capture_t are released, the capture will release the references it holds on any + * \ref k4a_image_t that are associated with it. + * + * \remarks + * When a capture returns an image to the caller with an accessor like k4a_capture_get_color_image(), a new reference is + * added to the \ref k4a_image_t and the caller is responsible for releasing that reference with k4a_image_release(). + * + * \remarks + * Empty captures are created with k4a_capture_create(). + * + * \remarks + * Captures can be obtained from a device using k4a_device_get_capture(). + * + * \remarks + * The caller must call k4a_capture_release() to release its reference to any \ref k4a_capture_t that it receives from + * an Azure Kinect API. + * + * \remarks + * Additional references to the capture may be obtained with k4a_capture_reference(). + * + * \remarks + * An invalid k4a_capture_t will be set to 0. + * + * \see k4a_image_t + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +K4A_DECLARE_HANDLE(k4a_capture_t); + +/** \class k4a_image_t k4a.h + * Handle to an Azure Kinect image. + * + * \remarks + * A \ref k4a_image_t manages an image buffer and associated metadata. + * + * \remarks + * The memory associated with the image buffer in an \ref k4a_image_t may have been allocated by the Azure Kinect APIs + * or by the application. If the \ref k4a_image_t was created by an Azure Kinect API, its memory will be freed when all + * references to the \ref k4a_image_t are released. All images retrieved directly from a device will have been created + * by the API. An application can create a \ref k4a_image_t using memory that it has allocated using + * k4a_image_create_from_buffer(). In that case the memory is not freed when the references are released but instead the + * application is provided with a callback. Applications need to create a k4a_image_t to provide as an output to the + * k4a_transformation_t transformation functions. + * + * \remarks + * An image has a number of metadata properties that can be set or retrieved using the accessor functions. Not all + * properties are applicable to images of all types. See the documentation for the individual accessors for more + * information on their applicability and meaning. + * + * \remarks + * Images may be of one of the standard \ref k4a_image_format_t formats, or may be of format ::K4A_IMAGE_FORMAT_CUSTOM. + * The format defines how the underlying image buffer should be interpreted. + * + * \remarks + * Images from a device are retrieved through a \ref k4a_capture_t object returned by k4a_device_get_capture(). + * + * \remarks + * Images stored in a k4a_capture_t are referenced by the k4a_capture_t until they are replaced or the k4a_capture_t is + * destroyed. + * + * \remarks + * The caller must call k4a_image_release() to release its reference to any \ref k4a_image_t that it receives from + * an Azure Kinect API. + * + * \remarks + * Additional references to the image may be obtained with k4a_image_reference(). + * + * \remarks + * An invalid k4a_image_t will be set to 0. + * + * \see k4a_capture_t + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +K4A_DECLARE_HANDLE(k4a_image_t); + +/** \class k4a_transformation_t k4a.h + * Handle to an Azure Kinect transformation context. + * + * \remarks + * Handles are created with k4a_transformation_create() and closed with k4a_transformation_destroy(). + * + * \remarks + * The transformation handle is used to transform images from the coordinate system of one camera into the other. Each + * transformation handle requires some pre-computed resources to be allocated, which are retained until the handle is + * destroyed. + * + * \remarks + * Invalid handles are set to 0. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +K4A_DECLARE_HANDLE(k4a_transformation_t); + +/** + * + * @} + * + * \defgroup Enumerations Enumerations + * \ingroup csdk + * + * Enumeration types used by APIs. + * + * @{ + */ + +/** Result code returned by Azure Kinect APIs. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef enum +{ + K4A_RESULT_SUCCEEDED = 0, /**< The result was successful */ + K4A_RESULT_FAILED, /**< The result was a failure */ +} k4a_result_t; + +/** Result code returned by Azure Kinect APIs. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef enum +{ + K4A_BUFFER_RESULT_SUCCEEDED = 0, /**< The result was successful */ + K4A_BUFFER_RESULT_FAILED, /**< The result was a failure */ + K4A_BUFFER_RESULT_TOO_SMALL, /**< The input buffer was too small */ +} k4a_buffer_result_t; + +/** Result code returned by Azure Kinect APIs. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef enum +{ + K4A_WAIT_RESULT_SUCCEEDED = 0, /**< The result was successful */ + K4A_WAIT_RESULT_FAILED, /**< The result was a failure */ + K4A_WAIT_RESULT_TIMEOUT, /**< The operation timed out */ +} k4a_wait_result_t; + +/** Verbosity levels of debug messaging + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef enum +{ + K4A_LOG_LEVEL_CRITICAL = 0, /**< Most severe level of debug messaging. */ + K4A_LOG_LEVEL_ERROR, /**< 2nd most severe level of debug messaging. */ + K4A_LOG_LEVEL_WARNING, /**< 3nd most severe level of debug messaging. */ + K4A_LOG_LEVEL_INFO, /**< 2nd least severe level of debug messaging. */ + K4A_LOG_LEVEL_TRACE, /**< Least severe level of debug messaging. */ + K4A_LOG_LEVEL_OFF, /**< No logging is performed */ +} k4a_log_level_t; + +/** Depth sensor capture modes. + * + * \remarks + * See the hardware specification for additional details on the field of view, and supported frame rates + * for each mode. + * + * \remarks + * NFOV and WFOV denote Narrow and Wide Field Of View configurations. + * + * \remarks + * Binned modes reduce the captured camera resolution by combining adjacent sensor pixels into a bin. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +// Be sure to update k4a_depth_mode_to_string in k4a.c if enum values are added. +typedef enum +{ + K4A_DEPTH_MODE_OFF = 0, /**< Depth sensor will be turned off with this setting. */ + K4A_DEPTH_MODE_NFOV_2X2BINNED, /**< Depth captured at 320x288. Passive IR is also captured at 320x288. */ + K4A_DEPTH_MODE_NFOV_UNBINNED, /**< Depth captured at 640x576. Passive IR is also captured at 640x576. */ + K4A_DEPTH_MODE_WFOV_2X2BINNED, /**< Depth captured at 512x512. Passive IR is also captured at 512x512. */ + K4A_DEPTH_MODE_WFOV_UNBINNED, /**< Depth captured at 1024x1024. Passive IR is also captured at 1024x1024. */ + K4A_DEPTH_MODE_PASSIVE_IR, /**< Passive IR only, captured at 1024x1024. */ +} k4a_depth_mode_t; + +/** Color sensor resolutions. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +// Be sure to update k4a_color_resolution_to_string in k4a.c if enum values are added. +typedef enum +{ + K4A_COLOR_RESOLUTION_OFF = 0, /**< Color camera will be turned off with this setting */ + K4A_COLOR_RESOLUTION_720P, /**< 1280 * 720 16:9 */ + K4A_COLOR_RESOLUTION_1080P, /**< 1920 * 1080 16:9 */ + K4A_COLOR_RESOLUTION_1440P, /**< 2560 * 1440 16:9 */ + K4A_COLOR_RESOLUTION_1536P, /**< 2048 * 1536 4:3 */ + K4A_COLOR_RESOLUTION_2160P, /**< 3840 * 2160 16:9 */ + K4A_COLOR_RESOLUTION_3072P, /**< 4096 * 3072 4:3 */ +} k4a_color_resolution_t; + +/** Image format type. + * + * \remarks + * The image format indicates how the \ref k4a_image_t buffer data is interpreted. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +// Be sure to update k4a_image_format_to_string in k4a.c if enum values are added. +typedef enum +{ + /** Color image type MJPG. + * + * \details + * The buffer for each image is encoded as a JPEG and can be decoded by a JPEG decoder. + * + * \details + * Because the image is compressed, the stride parameter for the \ref k4a_image_t is not applicable. + * + * \details + * Each MJPG encoded image in a stream may be of differing size depending on the compression efficiency. + */ + K4A_IMAGE_FORMAT_COLOR_MJPG = 0, + + /** Color image type NV12. + * + * \details + * NV12 images separate the luminance and chroma data such that all the luminance is at the + * beginning of the buffer, and the chroma lines follow immediately after. + * + * \details + * Stride indicates the length of each line in bytes and should be used to determine the start location of each line + * of the image in memory. Chroma has half as many lines of height and half the width in pixels of the luminance. + * Each chroma line has the same width in bytes as a luminance line. + */ + K4A_IMAGE_FORMAT_COLOR_NV12, + + /** Color image type YUY2. + * + * \details + * YUY2 stores chroma and luminance data in interleaved pixels. + * + * \details + * Stride indicates the length of each line in bytes and should be used to determine the start location of each + * line of the image in memory. + */ + K4A_IMAGE_FORMAT_COLOR_YUY2, + + /** Color image type BGRA32. + * + * \details + * Each pixel of BGRA32 data is four bytes. The first three bytes represent Blue, Green, + * and Red data. The fourth byte is the alpha channel and is unused in the Azure Kinect APIs. + * + * \details + * Stride indicates the length of each line in bytes and should be used to determine the start location of each + * line of the image in memory. + * + * \details + * The Azure Kinect device does not natively capture in this format. Requesting images of this format + * requires additional computation in the API. + * + */ + K4A_IMAGE_FORMAT_COLOR_BGRA32, + + /** Depth image type DEPTH16. + * + * \details + * Each pixel of DEPTH16 data is two bytes of little endian unsigned depth data. The unit of the data is in + * millimeters from the origin of the camera. + * + * \details + * Stride indicates the length of each line in bytes and should be used to determine the start location of each + * line of the image in memory. + */ + K4A_IMAGE_FORMAT_DEPTH16, + + /** Image type IR16. + * + * \details + * Each pixel of IR16 data is two bytes of little endian unsigned depth data. The value of the data represents + * brightness. + * + * \details + * This format represents infrared light and is captured by the depth camera. + * + * \details + * Stride indicates the length of each line in bytes and should be used to determine the start location of each + * line of the image in memory. + */ + K4A_IMAGE_FORMAT_IR16, + + /** Single channel image type CUSTOM8. + * + * \details + * Each pixel of CUSTOM8 is a single channel one byte of unsigned data. + * + * \details + * Stride indicates the length of each line in bytes and should be used to determine the start location of each + * line of the image in memory. + */ + K4A_IMAGE_FORMAT_CUSTOM8, + + /** Single channel image type CUSTOM16. + * + * \details + * Each pixel of CUSTOM16 is a single channel two bytes of little endian unsigned data. + * + * \details + * Stride indicates the length of each line in bytes and should be used to determine the start location of each + * line of the image in memory. + */ + K4A_IMAGE_FORMAT_CUSTOM16, + + /** Custom image format. + * + * \details + * Used in conjunction with user created images or images packing non-standard data. + * + * \details + * See the originator of the custom formatted image for information on how to interpret the data. + */ + K4A_IMAGE_FORMAT_CUSTOM, +} k4a_image_format_t; + +/** Transformation interpolation type. + * + * \remarks + * Interpolation type used with k4a_transformation_depth_image_to_color_camera_custom. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef enum +{ + K4A_TRANSFORMATION_INTERPOLATION_TYPE_NEAREST = 0, /**< Nearest neighbor interpolation */ + K4A_TRANSFORMATION_INTERPOLATION_TYPE_LINEAR, /**< Linear interpolation */ +} k4a_transformation_interpolation_type_t; + +/** Color and depth sensor frame rate. + * + * \remarks + * This enumeration is used to select the desired frame rate to operate the cameras. The actual + * frame rate may vary slightly due to dropped data, synchronization variation between devices, + * clock accuracy, or if the camera exposure priority mode causes reduced frame rate. + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +// Be sure to update k4a_fps_to_string in k4a.c if enum values are added. +typedef enum +{ + K4A_FRAMES_PER_SECOND_5 = 0, /**< 5 FPS */ + K4A_FRAMES_PER_SECOND_15, /**< 15 FPS */ + K4A_FRAMES_PER_SECOND_30, /**< 30 FPS */ +} k4a_fps_t; + +/** Color sensor control commands + * + * \remarks + * The current settings can be read with k4a_device_get_color_control(). The settings can be set with + * k4a_device_set_color_control(). + * + * \remarks + * Control values set on a device are reset only when the device is power cycled. The device will retain the settings + * even if the \ref k4a_device_t is closed or the application is restarted. + * + * \see k4a_color_control_mode_t + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef enum +{ + /** Exposure time setting. + * + * \details + * May be set to ::K4A_COLOR_CONTROL_MODE_AUTO or ::K4A_COLOR_CONTROL_MODE_MANUAL. + * + * \details + * The Azure Kinect supports a limited number of fixed expsore settings. When setting this, expect the exposure to + * be rounded up to the nearest setting. Exceptions are 1) The last value in the table is the upper limit, so a + * value larger than this will be overridden to the largest entry in the table. 2) The exposure time cannot be + * larger than the equivelent FPS. So expect 100ms exposure time to be reduced to 30ms or 33.33ms when the camera is + * started. The most recent copy of the table 'device_exposure_mapping' is in + * https://github.com/microsoft/Azure-Kinect-Sensor-SDK/blob/develop/src/color/color_priv.h + * + * \details + * Exposure time is measured in microseconds. + */ + K4A_COLOR_CONTROL_EXPOSURE_TIME_ABSOLUTE = 0, + + /** Exposure or Framerate priority setting. + * + * \details + * May only be set to ::K4A_COLOR_CONTROL_MODE_MANUAL. + * + * \details + * Value of 0 means framerate priority. Value of 1 means exposure priority. + * + * \details + * Using exposure priority may impact the framerate of both the color and depth cameras. + * + * \details + * Deprecated starting in 1.2.0. Please discontinue usage, firmware does not support this. + */ + K4A_COLOR_CONTROL_AUTO_EXPOSURE_PRIORITY, + + /** Brightness setting. + * + * \details + * May only be set to ::K4A_COLOR_CONTROL_MODE_MANUAL. + * + * \details + * The valid range is 0 to 255. The default value is 128. + */ + K4A_COLOR_CONTROL_BRIGHTNESS, + + /** Contrast setting. + * + * \details + * May only be set to ::K4A_COLOR_CONTROL_MODE_MANUAL. + */ + K4A_COLOR_CONTROL_CONTRAST, + + /** Saturation setting. + * + * \details + * May only be set to ::K4A_COLOR_CONTROL_MODE_MANUAL. + */ + K4A_COLOR_CONTROL_SATURATION, + + /** Sharpness setting. + * + * \details + * May only be set to ::K4A_COLOR_CONTROL_MODE_MANUAL. + */ + K4A_COLOR_CONTROL_SHARPNESS, + + /** White balance setting. + * + * \details + * May be set to ::K4A_COLOR_CONTROL_MODE_AUTO or ::K4A_COLOR_CONTROL_MODE_MANUAL. + * + * \details + * The unit is degrees Kelvin. The setting must be set to a value evenly divisible by 10 degrees. + */ + K4A_COLOR_CONTROL_WHITEBALANCE, + + /** Backlight compensation setting. + * + * \details + * May only be set to ::K4A_COLOR_CONTROL_MODE_MANUAL. + * + * \details + * Value of 0 means backlight compensation is disabled. Value of 1 means backlight compensation is enabled. + */ + K4A_COLOR_CONTROL_BACKLIGHT_COMPENSATION, + + /** Gain setting. + * + * \details + * May only be set to ::K4A_COLOR_CONTROL_MODE_MANUAL. + */ + K4A_COLOR_CONTROL_GAIN, + + /** Powerline frequency setting. + * + * \details + * May only be set to ::K4A_COLOR_CONTROL_MODE_MANUAL. + * + * \details + * Value of 1 sets the powerline compensation to 50 Hz. Value of 2 sets the powerline compensation to 60 Hz. + */ + K4A_COLOR_CONTROL_POWERLINE_FREQUENCY +} k4a_color_control_command_t; + +/** Color sensor control mode + * + * \remarks + * The current settings can be read with k4a_device_get_color_control(). The settings can be set with + * k4a_device_set_color_control(). + * + * \see k4a_color_control_command_t + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef enum +{ + K4A_COLOR_CONTROL_MODE_AUTO = 0, /**< set the associated k4a_color_control_command_t to auto*/ + K4A_COLOR_CONTROL_MODE_MANUAL, /**< set the associated k4a_color_control_command_t to manual*/ +} k4a_color_control_mode_t; + +/** Synchronization mode when connecting two or more devices together. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef enum +{ + K4A_WIRED_SYNC_MODE_STANDALONE, /**< Neither 'Sync In' or 'Sync Out' connections are used. */ + K4A_WIRED_SYNC_MODE_MASTER, /**< The 'Sync Out' jack is enabled and synchronization data it driven out the + connected wire. While in master mode the color camera must be enabled as part of the + multi device sync signalling logic. Even if the color image is not needed, the color + camera must be running.*/ + K4A_WIRED_SYNC_MODE_SUBORDINATE /**< The 'Sync In' jack is used for synchronization and 'Sync Out' is driven for the + next device in the chain. 'Sync Out' is a mirror of 'Sync In' for this mode. + */ +} k4a_wired_sync_mode_t; + +/** Calibration types. + * + * Specifies a type of calibration. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef enum +{ + K4A_CALIBRATION_TYPE_UNKNOWN = -1, /**< Calibration type is unknown */ + K4A_CALIBRATION_TYPE_DEPTH, /**< Depth sensor */ + K4A_CALIBRATION_TYPE_COLOR, /**< Color sensor */ + K4A_CALIBRATION_TYPE_GYRO, /**< Gyroscope sensor */ + K4A_CALIBRATION_TYPE_ACCEL, /**< Accelerometer sensor */ + K4A_CALIBRATION_TYPE_NUM, /**< Number of types excluding unknown type*/ +} k4a_calibration_type_t; + +/** Calibration model type. + * + * The model used interpret the calibration parameters. + * + * \remarks + * Azure Kinect devices are calibrated with Brown Conrady. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef enum +{ + K4A_CALIBRATION_LENS_DISTORTION_MODEL_UNKNOWN = 0, /**< Calibration model is unknown */ + K4A_CALIBRATION_LENS_DISTORTION_MODEL_THETA, /**< Deprecated (not supported). Calibration model is Theta (arctan). + */ + K4A_CALIBRATION_LENS_DISTORTION_MODEL_POLYNOMIAL_3K, /**< Deprecated (not supported). Calibration model is + Polynomial 3K. */ + K4A_CALIBRATION_LENS_DISTORTION_MODEL_RATIONAL_6KT, /**< Deprecated (only supported early internal devices). + Calibration model is Rational 6KT. */ + K4A_CALIBRATION_LENS_DISTORTION_MODEL_BROWN_CONRADY, /**< Calibration model is Brown Conrady (compatible with + * OpenCV) */ +} k4a_calibration_model_type_t; + +/** Firmware build type. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef enum +{ + K4A_FIRMWARE_BUILD_RELEASE, /**< Production firmware. */ + K4A_FIRMWARE_BUILD_DEBUG /**< Pre-production firmware. */ +} k4a_firmware_build_t; + +/** Firmware signature type. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef enum +{ + K4A_FIRMWARE_SIGNATURE_MSFT, /**< Microsoft signed firmware. */ + K4A_FIRMWARE_SIGNATURE_TEST, /**< Test signed firmware. */ + K4A_FIRMWARE_SIGNATURE_UNSIGNED /**< Unsigned firmware. */ +} k4a_firmware_signature_t; + +/** + * + * @} + * + * \defgroup Macros Macros + * \ingroup csdk + * + * Public macros for API consumers. + * + * @{ + */ + +/** Validate that a k4a_result_t is successful. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +#define K4A_SUCCEEDED(_result_) (_result_ == K4A_RESULT_SUCCEEDED) + +/** Validate that a k4a_result_t is failed. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +#define K4A_FAILED(_result_) (!K4A_SUCCEEDED(_result_)) + +/** + * + * @} + * + * \defgroup Logging Error and event logging + * + * The SDK can log data to the console, files, or to a custom handler. + * + * Environment Variables: + * + * K4A_ENABLE_LOG_TO_A_FILE / K4A_RECORD_ENABLE_LOG_TO_A_FILE + * Specifies the log file to save the log to. K4a.dll and k4arecord.dll can not log to the same file. + * + * K4A_ENABLE_LOG_TO_A_FILE = + * K4A_RECORD_ENABLE_LOG_TO_A_FILE = + * 0 - completely disable logging to a file + * log\custom.log - log all messages to the path and file specified - must end in '.log' to + * be considered a valid entry + * NOTE 1: When enabled this takes precedence over the value of K4A_ENABLE_LOG_TO_STDOUT. + * NOTE 2: This can not be set to the same value as K4A_RECORD_ENABLE_LOG_TO_A_FILE as they represent separate + * logger instance that do not allowed shared access to the file being written to. + * + * K4A_ENABLE_LOG_TO_STDOUT = + * 0 - disable logging to stdout + * all else - log all messages to stdout + * + * K4A_LOG_LEVEL = + * 'c' - log all messages of level 'critical' criticality + * 'e' - log all messages of level 'error' or higher criticality + * 'w' - log all messages of level 'warning' or higher criticality + * 'i' - log all messages of level 'info' or higher criticality + * 't' - log all messages of level 'trace' or higher criticality + * DEFAULT - log all message of level 'error' or higher criticality + * + * See remarks section of \p k4a_set_debug_message_handler + * + * @{ + * + * + */ + +/** + * + * @} + * + * \defgroup Prototypes Callback Function prototypes + * \ingroup csdk + * + * Prototypes used in callbacks. + * + * @{ + */ + +/** Callback function for debug messages being generated by the Azure Kinect SDK. + * + * \param context + * The context of the callback function. This is the context that was supplied by the caller to \p + * k4a_set_debug_message_handler. + * + * \param level + * The level of the message that has been created. + * + * \param file + * The file name of the source file that generated the message. + * + * \param line + * The line number of the source file that generated the message. + * + * \param message + * The messaged generated by the Azure Kinect SDK. + * + * \remarks + * The callback is called asynchronously when the Azure Kinext SDK generates a message at a \p level that is equal to + * or more critical than the level specified when calling \ref k4a_set_debug_message_handler() to register the callback. + * + * \remarks + * This callback can occur from any thread and blocks the calling thread. The k4a_logging_message_cb_t function user + * must protect it's logging resources from concurrent calls. All care should be made to minimize the amount of time + * locks are held. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + * + */ +typedef void(k4a_logging_message_cb_t)(void *context, + k4a_log_level_t level, + const char *file, + const int line, + const char *message); + +/** Callback function for a memory object being destroyed. + * + * \param buffer + * The buffer pointer that was supplied by the caller as \p buffer_release_cb to \ref k4a_image_create_from_buffer(). + * + * \param context + * The context for the memory object that needs to be destroyed that was supplied by the caller as \p + * buffer_release_cb_context to \ref k4a_image_create_from_buffer(). + * + * \remarks + * When all references for the memory object are released, this callback will be invoked as the final destroy for the + * given memory. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + * + */ +typedef void(k4a_memory_destroy_cb_t)(void *buffer, void *context); + +/** Callback function for a memory allocation. + * + * \param size + * Minimum size in bytes needed for the buffer. + * + * \param context + * Output parameter for a context that will be provided in the subsequent call to the \ref k4a_memory_destroy_cb_t + * callback. + * + * \return + * A pointer to the newly allocated memory. + * + * \remarks + * A callback of this type is provided when there is an application defined allocator. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + * + */ +typedef uint8_t *(k4a_memory_allocate_cb_t)(int size, void **context); + +/** + * + * @} + * + * \defgroup Structures Structures + * \ingroup csdk + * + * Structures used in the API. + * + * @{ + */ + +/** Configuration parameters for an Azure Kinect device. + * + * \remarks + * Used by k4a_device_start_cameras() to specify the configuration of the data capture. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef struct _k4a_device_configuration_t +{ + /** Image format to capture with the color camera. + * + * The color camera does not natively produce BGRA32 images. + * Setting ::K4A_IMAGE_FORMAT_COLOR_BGRA32 for color_format will result in higher CPU utilization. */ + k4a_image_format_t color_format; + + /** Image resolution to capture with the color camera. */ + k4a_color_resolution_t color_resolution; + + /** Capture mode for the depth camera. */ + k4a_depth_mode_t depth_mode; + + /** Desired frame rate for the color and depth camera. */ + k4a_fps_t camera_fps; + + /** Only produce k4a_capture_t objects if they contain synchronized color and depth images. + * + * \details + * This setting controls the behavior in which images are dropped when images are produced faster than they can be + * read, or if there are errors in reading images from the device. + * + * \details + * If set to true, \ref k4a_capture_t objects will only be produced with both color and depth images. + * If set to false, \ref k4a_capture_t objects may be produced only a single image when the corresponding image is + * dropped. + * + * \details + * Setting this to false ensures that the caller receives all of the images received from the camera, regardless of + * whether the corresponding images expected in the capture are available. + * + * \details + * If either the color or depth camera are disabled, this setting has no effect. + */ + bool synchronized_images_only; + + /** + * Desired delay between the capture of the color image and the capture of the depth image. + * + * \details + * A negative value indicates that the depth image should be captured before the color image. + * + * \details + * Any value between negative and positive one capture period is valid. + */ + int32_t depth_delay_off_color_usec; + + /** The external synchronization mode. */ + k4a_wired_sync_mode_t wired_sync_mode; + + /** + * The external synchronization timing. + * + * If this camera is a subordinate, this sets the capture delay between the color camera capture and the external + * input pulse. A setting of zero indicates that the master and subordinate color images should be aligned. + * + * This setting does not effect the 'Sync out' connection. + * + * This value must be positive and range from zero to one capture period. + * + * If this is not a subordinate, then this value is ignored. */ + uint32_t subordinate_delay_off_master_usec; + + /** + * Streaming indicator automatically turns on when the color or depth camera's are in use. + * + * This setting disables that behavior and keeps the LED in an off state. */ + bool disable_streaming_indicator; +} k4a_device_configuration_t; + +/** Extrinsic calibration data. + * + * \remarks + * Extrinsic calibration defines the physical relationship between two separate devices. + * + * \relates k4a_calibration_camera_t + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef struct _k4a_calibration_extrinsics_t +{ + float rotation[9]; /**< 3x3 Rotation matrix stored in row major order */ + float translation[3]; /**< Translation vector, x,y,z (in millimeters) */ +} k4a_calibration_extrinsics_t; + +/** Camera intrinsic calibration data. + * + * \remarks + * Intrinsic calibration represents the internal optical properties of the camera. + * + * \remarks + * Azure Kinect devices are calibrated with Brown Conrady which is compatible + * with OpenCV. + * + * \relates k4a_calibration_camera_t + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef union +{ + /** individual parameter or array representation of intrinsic model. */ + struct _param + { + float cx; /**< Principal point in image, x */ + float cy; /**< Principal point in image, y */ + float fx; /**< Focal length x */ + float fy; /**< Focal length y */ + float k1; /**< k1 radial distortion coefficient */ + float k2; /**< k2 radial distortion coefficient */ + float k3; /**< k3 radial distortion coefficient */ + float k4; /**< k4 radial distortion coefficient */ + float k5; /**< k5 radial distortion coefficient */ + float k6; /**< k6 radial distortion coefficient */ + float codx; /**< Center of distortion in Z=1 plane, x (only used for Rational6KT) */ + float cody; /**< Center of distortion in Z=1 plane, y (only used for Rational6KT) */ + float p2; /**< Tangential distortion coefficient 2 */ + float p1; /**< Tangential distortion coefficient 1 */ + float metric_radius; /**< Metric radius */ + } param; /**< Individual parameter representation of intrinsic model */ + float v[15]; /**< Array representation of intrinsic model parameters */ +} k4a_calibration_intrinsic_parameters_t; + +/** Camera sensor intrinsic calibration data. + * + * \remarks + * Intrinsic calibration represents the internal optical properties of the camera. + * + * \remarks + * Azure Kinect devices are calibrated with Brown Conrady which is compatible + * with OpenCV. + * + * \relates k4a_calibration_camera_t + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef struct _k4a_calibration_intrinsics_t +{ + k4a_calibration_model_type_t type; /**< Type of calibration model used*/ + unsigned int parameter_count; /**< Number of valid entries in parameters*/ + k4a_calibration_intrinsic_parameters_t parameters; /**< Calibration parameters*/ +} k4a_calibration_intrinsics_t; + +/** Camera calibration contains intrinsic and extrinsic calibration information for a camera. + * + * \relates k4a_calibration_camera_t + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef struct _k4a_calibration_camera_t +{ + k4a_calibration_extrinsics_t extrinsics; /**< Extrinsic calibration data. */ + k4a_calibration_intrinsics_t intrinsics; /**< Intrinsic calibration data. */ + int resolution_width; /**< Resolution width of the calibration sensor. */ + int resolution_height; /**< Resolution height of the calibration sensor. */ + float metric_radius; /**< Max FOV of the camera. */ +} k4a_calibration_camera_t; + +/** Calibration type representing device calibration. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef struct _k4a_calibration_t +{ + k4a_calibration_camera_t depth_camera_calibration; /**< Depth camera calibration. */ + + k4a_calibration_camera_t color_camera_calibration; /**< Color camera calibration. */ + + /** Extrinsic transformation parameters. + * + * The extrinsic parameters allow 3D coordinate conversions between depth camera, color camera, the IMU's gyroscope + * and accelerometer. To transform from a source to a target 3D coordinate system, use the parameters stored + * under extrinsics[source][target]. + */ + k4a_calibration_extrinsics_t extrinsics[K4A_CALIBRATION_TYPE_NUM][K4A_CALIBRATION_TYPE_NUM]; + + k4a_depth_mode_t depth_mode; /**< Depth camera mode for which calibration was obtained. */ + k4a_color_resolution_t color_resolution; /**< Color camera resolution for which calibration was obtained. */ +} k4a_calibration_t; + +/** Version information. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef struct _k4a_version_t +{ + uint32_t major; /**< Major version; represents a breaking change. */ + uint32_t minor; /**< Minor version; represents additional features, no regression from lower versions with same + major version. */ + uint32_t iteration; /**< Reserved. */ +} k4a_version_t; + +/** Structure to define hardware version. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef struct _k4a_hardware_version_t +{ + k4a_version_t rgb; /**< Color camera firmware version. */ + k4a_version_t depth; /**< Depth camera firmware version. */ + k4a_version_t audio; /**< Audio device firmware version. */ + k4a_version_t depth_sensor; /**< Depth sensor firmware version. */ + + k4a_firmware_build_t firmware_build; /**< Build type reported by the firmware. */ + k4a_firmware_signature_t firmware_signature; /**< Signature type of the firmware. */ +} k4a_hardware_version_t; + +/** Two dimensional floating point vector. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef union +{ + /** XY or array representation of vector */ + struct _xy + { + float x; /**< X component of a vector */ + float y; /**< Y component of a vector */ + } xy; /**< X, Y representation of a vector */ + float v[2]; /**< Array representation of a vector */ +} k4a_float2_t; + +/** Three dimensional floating point vector. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef union +{ + /** XYZ or array representation of vector. */ + struct _xyz + { + float x; /**< X component of a vector. */ + float y; /**< Y component of a vector. */ + float z; /**< Z component of a vector. */ + } xyz; /**< X, Y, Z representation of a vector. */ + float v[3]; /**< Array representation of a vector. */ +} k4a_float3_t; + +/** IMU sample. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef struct _k4a_imu_sample_t +{ + float temperature; /**< Temperature reading of this sample (Celsius). */ + k4a_float3_t acc_sample; /**< Accelerometer sample in meters per second squared. */ + uint64_t acc_timestamp_usec; /**< Timestamp of the accelerometer in microseconds. */ + k4a_float3_t gyro_sample; /**< Gyro sample in radians per second. */ + uint64_t gyro_timestamp_usec; /**< Timestamp of the gyroscope in microseconds */ +} k4a_imu_sample_t; + +/** + * + * @} + * + * \defgroup Definitions Definitions + * \ingroup csdk + * + * Definition of constant values. + * + * @{ + */ + +/** Default device index. + * + * Passed as an argument to \ref k4a_device_open() to open the default sensor + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +#define K4A_DEVICE_DEFAULT (0) + +/** An infinite wait time for functions that take a timeout parameter. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +#define K4A_WAIT_INFINITE (-1) + +/** Initial configuration setting for disabling all sensors. + * + * \remarks + * Use this setting to initialize a \ref k4a_device_configuration_t to a disabled state. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +static const k4a_device_configuration_t K4A_DEVICE_CONFIG_INIT_DISABLE_ALL = { K4A_IMAGE_FORMAT_COLOR_MJPG, + K4A_COLOR_RESOLUTION_OFF, + K4A_DEPTH_MODE_OFF, + K4A_FRAMES_PER_SECOND_30, + false, + 0, + K4A_WIRED_SYNC_MODE_STANDALONE, + 0, + false }; + +/** + * @} + */ + +#ifdef __cplusplus +} +#endif + +#endif /* K4ATYPES_H */ diff --git a/k4a-sys/vendor/include/linux/k4a/k4aversion.h b/k4a-sys/vendor/include/linux/k4a/k4aversion.h new file mode 100644 index 0000000000..32f39261f0 --- /dev/null +++ b/k4a-sys/vendor/include/linux/k4a/k4aversion.h @@ -0,0 +1,16 @@ +/* Copyright (c) Microsoft Corporation. All rights reserved. + Licensed under the MIT License. */ + +#ifndef K4AVERSION_H +#define K4AVERSION_H + +#define K4A_VERSION_MAJOR 1 +#define K4A_VERSION_MINOR 3 +#define K4A_VERSION_PATCH 0 +#define K4A_VERSION_PRERELEASE "private" +#define K4A_VERSION_BUILD_METADATA "" + +#define K4A_VERSION_STR "1.3.0-private" + +#endif + diff --git a/k4a-sys/vendor/include/linux/k4arecord/k4arecord_export.h b/k4a-sys/vendor/include/linux/k4arecord/k4arecord_export.h new file mode 100644 index 0000000000..0fa091ea2e --- /dev/null +++ b/k4a-sys/vendor/include/linux/k4arecord/k4arecord_export.h @@ -0,0 +1,42 @@ + +#ifndef K4ARECORD_EXPORT_H +#define K4ARECORD_EXPORT_H + +#ifdef K4ARECORD_STATIC_DEFINE +# define K4ARECORD_EXPORT +# define K4ARECORD_NO_EXPORT +#else +# ifndef K4ARECORD_EXPORT +# ifdef k4arecord_EXPORTS + /* We are building this library */ +# define K4ARECORD_EXPORT __attribute__((visibility("default"))) +# else + /* We are using this library */ +# define K4ARECORD_EXPORT __attribute__((visibility("default"))) +# endif +# endif + +# ifndef K4ARECORD_NO_EXPORT +# define K4ARECORD_NO_EXPORT __attribute__((visibility("hidden"))) +# endif +#endif + +#ifndef K4ARECORD_DEPRECATED +# define K4ARECORD_DEPRECATED __attribute__ ((__deprecated__)) +#endif + +#ifndef K4ARECORD_DEPRECATED_EXPORT +# define K4ARECORD_DEPRECATED_EXPORT K4ARECORD_EXPORT K4ARECORD_DEPRECATED +#endif + +#ifndef K4ARECORD_DEPRECATED_NO_EXPORT +# define K4ARECORD_DEPRECATED_NO_EXPORT K4ARECORD_NO_EXPORT K4ARECORD_DEPRECATED +#endif + +#if 0 /* DEFINE_NO_DEPRECATED */ +# ifndef K4ARECORD_NO_DEPRECATED +# define K4ARECORD_NO_DEPRECATED +# endif +#endif + +#endif diff --git a/k4a-sys/vendor/include/linux/k4arecord/playback.h b/k4a-sys/vendor/include/linux/k4arecord/playback.h new file mode 100644 index 0000000000..6502ea8fa3 --- /dev/null +++ b/k4a-sys/vendor/include/linux/k4arecord/playback.h @@ -0,0 +1,917 @@ +/** \file playback.h + * Copyright (c) Microsoft Corporation. All rights reserved. + * Licensed under the MIT License. + * Kinect For Azure Recording Playback SDK. + */ + +#ifndef K4A_PLAYBACK_H +#define K4A_PLAYBACK_H + +#include +#include + +#ifdef __cplusplus + +extern "C" { +#endif + +/** + * + * \addtogroup Functions + * + * @{ + */ + +/** Opens an existing recording file for reading. + * + * \param path + * Filesystem path of the existing recording. + * + * \param playback_handle + * If successful, this contains a pointer to the recording handle. Caller must call k4a_playback_close() when + * finished with the recording. + * + * \headerfile playback.h + * + * \returns ::K4A_RESULT_SUCCEEDED is returned on success + * + * \relates k4a_playback_t + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_result_t k4a_playback_open(const char *path, k4a_playback_t *playback_handle); + +/** Get the raw calibration blob for the Azure Kinect device used during recording. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param data + * Location to write the calibration data to. This field may optionally be set to NULL if the caller wants to query for + * the needed data size. + * + * \param data_size + * On passing \p data_size into the function this variable represents the available size to write the raw data to. On + * return this variable is updated with the amount of data actually written to the buffer. + * + * \returns + * ::K4A_BUFFER_RESULT_SUCCEEDED if \p data was successfully written. If \p data_size points to a buffer size that is + * too small to hold the output, ::K4A_BUFFER_RESULT_TOO_SMALL is returned and \p data_size is updated to contain the + * minimum buffer size needed to capture the calibration data. + * + * \remarks + * The raw calibration may not exist if the device was not specified during recording. + * + * \relates k4a_playback_t + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_buffer_result_t k4a_playback_get_raw_calibration(k4a_playback_t playback_handle, + uint8_t *data, + size_t *data_size); + +/** Get the camera calibration for Azure Kinect device used during recording. The output struct is used as input to all + * transformation functions. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param calibration + * Location to write the calibration. + * + * \returns + * ::K4A_RESULT_SUCCEEDED if \p calibration was successfully written. ::K4A_RESULT_FAILED otherwise. + * + * \remarks + * The calibration may not exist if the device was not specified during recording. + * + * \relates k4a_playback_t + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_result_t k4a_playback_get_calibration(k4a_playback_t playback_handle, + k4a_calibration_t *calibration); + +/** Get the device configuration used during recording. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param config + * Location to write the recording configuration. + * + * \returns + * ::K4A_RESULT_SUCCEEDED if \p config was successfully written. ::K4A_RESULT_FAILED otherwise. + * + * \relates k4a_playback_t + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_result_t k4a_playback_get_record_configuration(k4a_playback_t playback_handle, + k4a_record_configuration_t *config); + +/** Checks whether a track with the given track name exists in the playback file. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param track_name + * The track name to be checked to see whether it exists or not. + * + * \returns true if the track exists. + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT bool k4a_playback_check_track_exists(k4a_playback_t playback_handle, const char *track_name); + +/** Get the number of tracks in a playback file. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \returns the number of tracks in the playback file. + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT size_t k4a_playback_get_track_count(k4a_playback_t playback_handle); + +/** Gets the name of a track at a specific index. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param track_index + * The index of the track to read the name form. + * + * \param track_name + * Location to write the track name. This will be a UTF8 null terminated string. If a NULL buffer is specified, + * \p track_name_size will be set to the size of buffer needed to store the string. + * + * \param track_name_size + * On input, the size of the \p track_name buffer. On output, this is set to the length of the track_name value + * (including the null terminator). + * + * \returns + * A return of ::K4A_BUFFER_RESULT_SUCCEEDED means that the \p track_name has been filled in. If the buffer is too small + * the function returns ::K4A_BUFFER_RESULT_TOO_SMALL and the needed size of the \p track_name buffer is returned in the + * \p track_name_size parameter. ::K4A_BUFFER_RESULT_FAILED is returned if the track index does not exist. All other + * failures return ::K4A_BUFFER_RESULT_FAILED. + * + * \remarks + * When used along with k4a_playback_get_track_count(), this function can be used to enumerate all the available tracks + * in a playback file. Additionally k4a_playback_track_is_builtin() can be used to filter custom tracks. + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_buffer_result_t k4a_playback_get_track_name(k4a_playback_t playback_handle, + size_t track_index, + char *track_name, + size_t *track_name_size); + +/** Checks whether a track is one of the built-in tracks: "COLOR", "DEPTH", etc... + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param track_name + * The track name to be checked to see whether it is a built-in track. + * + * \returns true if the track is built-in. If the provided track name does not exist, false will be returned. + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT bool k4a_playback_track_is_builtin(k4a_playback_t playback_handle, const char *track_name); + +/** Gets the video-specific track information for a particular video track. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param track_name + * The track name to read video settings from. + * + * \param video_settings + * Location to write the track's video settings. + * + * \returns ::K4A_RESULT_SUCCEEDED is returned on success, ::K4A_RESULT_FAILED is returned if the specified track does + * not exist or is not a video track. + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_result_t k4a_playback_track_get_video_settings(k4a_playback_t playback_handle, + const char *track_name, + k4a_record_video_settings_t *video_settings); + +/** Gets the codec id string for a particular track. + * + * The codec ID is a string that corresponds to the codec of the track's data. Some of the existing formats are listed + * here: https://www.matroska.org/technical/specs/codecid/index.html. It can also be custom defined by the user. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param track_name + * The track name to read the codec id from. + * + * \param codec_id + * Location to write the codec id. This will be a UTF8 null terminated string. If a NULL buffer is specified, + * \p codec_id_size will be set to the size of buffer needed to store the string. + * + * \param codec_id_size + * On input, the size of the \p codec_id buffer. On output, this is set to the length of the codec_id value (including + * the null terminator). + * + * \returns + * A return of ::K4A_BUFFER_RESULT_SUCCEEDED means that the \p codec_id has been filled in. If the buffer is too small + * the function returns ::K4A_BUFFER_RESULT_TOO_SMALL and the needed size of the \p codec_id buffer is returned in the + * \p codec_id_size parameter. ::K4A_BUFFER_RESULT_FAILED is returned if the track_name does not exist. All other + * failures return ::K4A_BUFFER_RESULT_FAILED. + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_buffer_result_t k4a_playback_track_get_codec_id(k4a_playback_t playback_handle, + const char *track_name, + char *codec_id, + size_t *codec_id_size); + +/** Gets the codec context for a particular track. + * + * The codec context is a codec-specific buffer that contains any required codec metadata that is only known to the + * codec. It is mapped to the matroska Codec Private field. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param track_name + * The track name to read the codec context from. + * + * \param codec_context + * Location to write the codec context data. If a NULL buffer is specified, \p codec_context_size will be set to the + * size of buffer needed to store the data. + * + * \param codec_context_size + * On input, the size of the \p codec_context buffer. On output, this is set to the length of the codec_context data. + * + * \returns + * A return of ::K4A_BUFFER_RESULT_SUCCEEDED means that the \p codec_context has been filled in. If the buffer is too + * small the function returns ::K4A_BUFFER_RESULT_TOO_SMALL and the needed size of the \p codec_context buffer is + * returned in the \p codec_context_size parameter. ::K4A_BUFFER_RESULT_FAILED is returned if the track_name does not + * exist. All other failures return ::K4A_BUFFER_RESULT_FAILED. + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_buffer_result_t k4a_playback_track_get_codec_context(k4a_playback_t playback_handle, + const char *track_name, + uint8_t *codec_context, + size_t *codec_context_size); + +/** Read the value of a tag from a recording. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param name + * The name of the tag to read. + * + * \param value + * Location to write the tag value. This will be a UTF8 null terminated string. If a NULL buffer is specified, + * \p value_size will be set to the size of buffer needed to store the string. + * + * \param value_size + * On input, the size of the \p value buffer. On output, this is set to the length of the tag value (including the null + * terminator). + * + * \returns + * A return of ::K4A_BUFFER_RESULT_SUCCEEDED means that the \p value has been filled in. If the buffer is too small the + * function returns ::K4A_BUFFER_RESULT_TOO_SMALL and the needed size of the \p value buffer is returned in the + * \p value_size parameter. ::K4A_BUFFER_RESULT_FAILED is returned if the tag does not exist. All other failures return + * ::K4A_BUFFER_RESULT_FAILED. + * + * \remarks + * Tags are global to a file, and should store data related to the entire recording, such as camera configuration or + * recording location. + * + * \relates k4a_playback_t + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_buffer_result_t k4a_playback_get_tag(k4a_playback_t playback_handle, + const char *name, + char *value, + size_t *value_size); + +/** Set the image format that color captures will be converted to. By default the conversion format will be the same as + * the image format stored in the recording file, and no conversion will occur. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param target_format + * The target image format to be returned in captures. + * + * \returns + * ::K4A_RESULT_SUCCEEDED if the format conversion is supported. ::K4A_RESULT_FAILED otherwise. + * + * \remarks + * After the color conversion format is set, all \ref k4a_capture_t objects returned from the playback handle will have + * their color images converted to the \p target_format. + * + * \remarks + * Color format conversion occurs in the user-thread, so setting \p target_format to anything other than the format + * stored in the file may significantly increase the latency of \p k4a_playback_get_next_capture() and + * \p k4a_playback_get_previous_capture(). + * + * \relates k4a_playback_t + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_result_t k4a_playback_set_color_conversion(k4a_playback_t playback_handle, + k4a_image_format_t target_format); + +/** Reads an attachment file from a recording. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param file_name + * The attachment file name. + * + * \param data + * Location to write the attachment data. If a NULL buffer is specified, \p data_size will be set to the size of + * buffer needed to store the data. + * + * \param data_size + * On input, the size of the \p data buffer. On output, this is set to the length of the attachment data. + * + * \returns + * A return of ::K4A_BUFFER_RESULT_SUCCEEDED means that the \p data has been filled in. If the buffer is too small the + * function returns ::K4A_BUFFER_RESULT_TOO_SMALL and the needed size of the \p data buffer is returned in the + * \p data_size parameter. ::K4A_BUFFER_RESULT_FAILED is returned if the attachment \p file_name does not exist. All + * other failures return ::K4A_BUFFER_RESULT_FAILED. + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_buffer_result_t k4a_playback_get_attachment(k4a_playback_t playback_handle, + const char *file_name, + uint8_t *data, + size_t *data_size); + +/** Read the next capture in the recording sequence. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param capture_handle + * If successful this contains a handle to a capture object. Caller must call k4a_capture_release() when its done using + * this capture + * + * \returns + * ::K4A_STREAM_RESULT_SUCCEEDED if a capture is returned, or ::K4A_STREAM_RESULT_EOF if the end of the recording is + * reached. All other failures will return ::K4A_STREAM_RESULT_FAILED. + * + * \relates k4a_playback_t + * + * \remarks + * k4a_playback_get_next_capture() always returns the next capture in sequence after the most recently returned capture. + * + * \remarks + * The first call to k4a_playback_get_next_capture() after k4a_playback_seek_timestamp() will return the capture + * in the recording closest to the seek time with an image timestamp greater than or equal to the seek time. + * + * \remarks + * If a call was made to k4a_playback_get_previous_capture() that returned ::K4A_STREAM_RESULT_EOF, the playback + * position is at the beginning of the stream and k4a_playback_get_next_capture() will return the first capture in the + * recording. + * + * \remarks + * Capture objects returned by the playback API will always contain at least one image, but may have images missing if + * frames were dropped in the original recording. When calling k4a_capture_get_color_image(), + * k4a_capture_get_depth_image(), or k4a_capture_get_ir_image(), the image should be checked for NULL. + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_stream_result_t k4a_playback_get_next_capture(k4a_playback_t playback_handle, + k4a_capture_t *capture_handle); + +/** Read the previous capture in the recording sequence. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param capture_handle + * If successful this contains a handle to a capture object. Caller must call k4a_capture_release() when its done using + * this capture. + * + * \returns + * ::K4A_STREAM_RESULT_SUCCEEDED if a capture is returned, or ::K4A_STREAM_RESULT_EOF if the start of the recording is + * reached. All other failures will return ::K4A_STREAM_RESULT_FAILED. + * + * \relates k4a_playback_t + * + * \remarks + * k4a_playback_get_previous_capture() always returns the previous capture in the sequence before the most + * recently returned capture. + * + * \remarks + * If a call was made to k4a_playback_get_next_capture() that returned ::K4A_STREAM_RESULT_EOF, the playback position + * is at the end of the stream and k4a_playback_get_previous_capture() will return the last capture in + * the recording. + * + * \remarks + * The first call to k4a_playback_get_previous_capture() after k4a_playback_seek_timestamp() will return the + * capture in the recording closest to the seek time with all image timestamps less than the seek time. + * + * \remarks + * Capture objects returned by this API will always contain at least one image, but may have images missing if frames + * were dropped in the original recording. When calling k4a_capture_get_color_image(), k4a_capture_get_depth_image(), or + * k4a_capture_get_ir_image(), the image should be checked for NULL. + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_stream_result_t k4a_playback_get_previous_capture(k4a_playback_t playback_handle, + k4a_capture_t *capture_handle); + +/** Read the next IMU sample in the recording sequence. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param imu_sample + * The location to write the IMU sample. + * + * \returns + * ::K4A_STREAM_RESULT_SUCCEEDED if a sample is returned, or ::K4A_STREAM_RESULT_EOF if the end of the recording is + * reached. All other failures will return ::K4A_STREAM_RESULT_FAILED. + * + * \relates k4a_playback_t + * + * \remarks + * k4a_playback_get_next_imu_sample() always returns the IMU sample after the most recently returned sample. + * + * \remarks + * If a call was made to k4a_playback_get_previous_imu_sample() which returned ::K4A_STREAM_RESULT_EOF, then the + * playback position is at the beginning of the recording and k4a_playback_get_next_imu_sample() will return the first + * IMU sample in the recording. + * + * \remarks + * The first call to k4a_playback_get_next_imu_sample() after k4a_playback_seek_timestamp() will return the IMU + * sample in the recording closest to the seek time with a timestamp greater than or equal to the seek time. + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_stream_result_t k4a_playback_get_next_imu_sample(k4a_playback_t playback_handle, + k4a_imu_sample_t *imu_sample); + +/** Read the previous IMU sample in the recording sequence. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param imu_sample [OUT] + * The location to write the IMU sample. + * + * \returns + * ::K4A_STREAM_RESULT_SUCCEEDED if a sample is returned, or ::K4A_STREAM_RESULT_EOF if the start of the recording is + * reached. All other failures will return ::K4A_STREAM_RESULT_FAILED. + * + * \relates k4a_playback_t + * + * \remarks + * k4a_playback_get_previous_imu_sample() always returns the IMU sample before the most recently returned sample. + * + * \remarks + * If a call was made to to k4a_playback_get_next_imu_sample() which returned ::K4A_STREAM_RESULT_EOF, then the playback + * position is at the end of the recording and k4a_playback_get_previous_imu_sample() will return the last IMU sample in + * the recording. + * + * \remarks + * The first call to k4a_playback_get_previous_imu_sample() after k4a_playback_seek_timestamp() will return the + * IMU sample closest to the seek time with a timestamp less than the seek time. + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_stream_result_t k4a_playback_get_previous_imu_sample(k4a_playback_t playback_handle, + k4a_imu_sample_t *imu_sample); + +/** Read the next data block for a particular track. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param track_name + * The name of the track to read the next data block from. + * + * \param data_block_handle + * The location to write the data block handle. + * + * \returns + * ::K4A_STREAM_RESULT_SUCCEEDED if a data block is returned, or ::K4A_STREAM_RESULT_EOF if the end of the recording is + * reached. All other failures will return ::K4A_STREAM_RESULT_FAILED. + * + * \relates k4a_playback_t + * + * \remarks + * k4a_playback_get_next_data_block() always returns the data block after the most recently returned data block for a + * particular track. + * + * \remarks + * If a call was made to k4a_playback_get_previous_data_block() which returned ::K4A_STREAM_RESULT_EOF, then the + * playback position is at the beginning of the recording and calling k4a_playback_get_next_data_block() with the same + * track will return the first data block in the track. + * + * \remarks + * The first call to k4a_playback_get_next_data_block() after k4a_playback_seek_timestamp() will return the data + * block in the recording closest to the seek time with a timestamp greater than or equal to the seek time. + * + * \remarks + * k4a_playback_get_next_data_block() cannot be used with the built-in tracks: "COLOR", "DEPTH", etc... + * k4a_playback_track_is_builtin() can be used to determine if a track is a built-in track. + * + * \remarks + * If the call is successful, callers must call k4a_playback_data_block_release() to return the allocated memory for + * data_block_handle. + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_stream_result_t k4a_playback_get_next_data_block(k4a_playback_t playback_handle, + const char *track_name, + k4a_playback_data_block_t *data_block_handle); + +/** Read the previous data block for a particular track. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param track_name + * The name of the track to read the previous data block from. + * + * \param data_block_handle + * The location to write the data block. + * + * \returns + * ::K4A_STREAM_RESULT_SUCCEEDED if a sample is returned, or ::K4A_STREAM_RESULT_EOF if the start of the recording is + * reached. All other failures will return ::K4A_STREAM_RESULT_FAILED. + * + * \relates k4a_playback_t + * + * \remarks + * k4a_playback_get_previous_data_block() always returns the data block before the most recently returned data block for + * a particular track. + * + * \remarks + * If a call was made to to k4a_playback_get_next_data_block() which returned ::K4A_STREAM_RESULT_EOF, then the playback + * position is at the end of the recording and calling k4a_playback_get_previous_data_block() with the same track will + * return the last data block in the track. + * + * \remarks + * The first call to k4a_playback_get_previous_data_block() after k4a_playback_seek_timestamp() will return the + * data block closest to the seek time with a timestamp less than the seek time. + * + * \remarks + * If the call is successful, callers must call k4a_playback_data_block_release() to return the allocated memory for + * data_block_handle. + * + * \remarks + * k4a_playback_get_previous_data_block() cannot be used with the built-in tracks: "COLOR", "DEPTH", etc... + * k4a_playback_track_is_builtin() can be used to determine if a track is a built-in track. + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_stream_result_t k4a_playback_get_previous_data_block(k4a_playback_t playback_handle, + const char *track_name, + k4a_playback_data_block_t *data_block_handle); + +/** Get the device timestamp of a data block in microseconds. + * + * \param data_block_handle + * Handle obtained by k4a_playback_get_next_data_block() or k4a_playback_get_previous_data_block(). + * + * \returns + * Returns the device timestamp of the data block. If the \p data_block_handle is invalid this function will return 0. + * It is also possible for 0 to be a valid timestamp originating from when a device was first powered on. + * + * \relates k4a_playback_data_block_t + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT uint64_t +k4a_playback_data_block_get_device_timestamp_usec(k4a_playback_data_block_t data_block_handle); + +/** Get the buffer size of a data block. + * + * \param data_block_handle + * Handle obtained by k4a_playback_get_next_data_block() or k4a_playback_get_previous_data_block(). + * + * \returns + * Returns the buffer size of the data block, or 0 if the data block is invalid. + * + * \relates k4a_playback_data_block_t + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT size_t k4a_playback_data_block_get_buffer_size(k4a_playback_data_block_t data_block_handle); + +/** Get the buffer of a data block. + * + * \param data_block_handle + * Handle obtained by k4a_playback_get_next_data_block() or k4a_playback_get_previous_data_block(). + * + * \remarks + * Use this buffer to access the data written to a custom recording track. + * + * \returns + * Returns a pointer to the data block buffer, or NULL if the data block is invalid. + * + * \relates k4a_playback_data_block_t + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT uint8_t *k4a_playback_data_block_get_buffer(k4a_playback_data_block_t data_block_handle); + +/** Release a data block handle. + * + * \param data_block_handle + * Handle obtained by k4a_playback_get_next_data_block() or k4a_playback_get_previous_data_block(). + * + * \remarks + * Release the memory of a data block. The caller must not access the object after it is released. + * + * \relates k4a_playback_data_block_t + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT void k4a_playback_data_block_release(k4a_playback_data_block_t data_block_handle); + +/** Seek to a specific timestamp within a recording. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param offset_usec + * The timestamp offset to seek to, relative to \p origin + * + * \param origin + * Specifies how the given timestamp should be interpreted. Seek can be done relative to the beginning or end of the + * recording, or using an absolute device timestamp. + * + * \returns + * ::K4A_RESULT_SUCCEEDED if the seek operation was successful, or ::K4A_RESULT_FAILED if an error occured. The current + * seek position is left unchanged if a failure is returned. + * + * \relates k4a_playback_t + * + * \remarks + * The first device timestamp in a recording is usually non-zero. The recording file starts at the device timestamp + * defined by start_timestamp_offset_usec, which is accessible via k4a_playback_get_record_configuration(). + * + * \remarks + * The first call to k4a_playback_get_next_capture() after k4a_playback_seek_timestamp() will return the first capture + * containing an image timestamp greater than or equal to the seek time. + * + * \remarks + * The first call to k4a_playback_get_previous_capture() after k4a_playback_seek_timestamp() will return the first + * capture with all image timestamps less than the seek time. + * + * \remarks + * The first call to k4a_playback_get_next_imu_sample() after k4a_playback_seek_timestamp() will return the first imu + * sample with a timestamp greter than or equal to the seek time. + * + * \remarks + * The first call to k4a_playback_get_previous_imu_sample() after k4a_playback_seek_timestamp() will return the first + * imu sample with a timestamp less than the seek time. + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_result_t k4a_playback_seek_timestamp(k4a_playback_t playback_handle, + int64_t offset_usec, + k4a_playback_seek_origin_t origin); + +/** Returns the length of the recording in microseconds. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \returns + * The recording length, calculated as the difference between the first and last timestamp in the file. + * + * \relates k4a_playback_t + * + * \remarks + * The recording length may be longer than an individual track if, for example, the IMU continues to run after the last + * color image is recorded. + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT uint64_t k4a_playback_get_recording_length_usec(k4a_playback_t playback_handle); + +/** Gets the last timestamp in a recording, relative to the start of the recording. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \returns + * The file timestamp of the last capture image or IMU sample in microseconds. + * + * \relates k4a_playback_t + * + * \remarks + * This function returns a file timestamp, not an absolute device timestamp, meaning it is relative to the start of the + * recording. This function is equivalent to the length of the recording. + * + * \deprecated + * Deprecated starting in 1.2.0. Please use k4a_playback_get_recording_length_usec(). + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_DEPRECATED_EXPORT uint64_t k4a_playback_get_last_timestamp_usec(k4a_playback_t playback_handle); + +/** Closes a recording playback handle. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \headerfile playback.h + * + * \relates k4a_playback_t + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT void k4a_playback_close(k4a_playback_t playback_handle); + +/** + * @} + */ + +#ifdef __cplusplus +} // extern "C" +#endif + +#endif /* K4A_PLAYBACK_H */ diff --git a/k4a-sys/vendor/include/linux/k4arecord/playback.hpp b/k4a-sys/vendor/include/linux/k4arecord/playback.hpp new file mode 100644 index 0000000000..dc21174c6e --- /dev/null +++ b/k4a-sys/vendor/include/linux/k4arecord/playback.hpp @@ -0,0 +1,339 @@ +/** \file playback.hpp + * Copyright (c) Microsoft Corporation. All rights reserved. + * Licensed under the MIT License. + * Kinect For Azure SDK - C++ wrapper. + */ + +#ifndef K4A_PLAYBACK_HPP +#define K4A_PLAYBACK_HPP + +#include +#include + +#include +#include +#include +#include + +namespace k4a +{ + +/** \class playback playback.hpp + * Wrapper for \ref k4a_playback_t + * + * Wraps a handle for a playback object + * + * \sa k4a_playback_t + */ +class playback +{ +public: + /** Creates a k4a::playback from a k4a_playback_t + * Takes ownership of the handle, i.e. you should not call + * k4a_playback_close on the handle after giving it to the + * k4a::playback; the k4a::playback will take care of that. + */ + playback(k4a_playback_t handle = nullptr) noexcept : m_handle(handle) {} + + /** Moves another k4a::playback into a new k4a::playback + */ + playback(playback &&other) noexcept : m_handle(other.m_handle) + { + other.m_handle = nullptr; + } + + playback(const playback &) = delete; + + ~playback() + { + close(); + } + + playback &operator=(const playback &) = delete; + + /** Moves another k4a::playback into this k4a::playback; other is set to invalid + */ + playback &operator=(playback &&other) noexcept + { + if (this != &other) + { + close(); + m_handle = other.m_handle; + other.m_handle = nullptr; + } + + return *this; + } + + /** Returns true if the k4a::playback is valid, false otherwise + */ + operator bool() const noexcept + { + return m_handle != nullptr; + } + + /** Closes a K4A recording. + * + * \sa k4a_playback_close + */ + void close() noexcept + { + if (m_handle != nullptr) + { + k4a_playback_close(m_handle); + m_handle = nullptr; + } + } + + /** Get the raw calibration blob for the K4A device that made the recording. + * Throws error on failure. + * + * \sa k4a_playback_get_raw_calibration + */ + std::vector get_raw_calibration() const + { + std::vector calibration; + size_t buffer = 0; + k4a_buffer_result_t result = k4a_playback_get_raw_calibration(m_handle, &calibration[0], &buffer); + + if (result == K4A_BUFFER_RESULT_TOO_SMALL && buffer > 1) + { + calibration.resize(buffer); + result = k4a_playback_get_raw_calibration(m_handle, &calibration[0], &buffer); + } + + if (result != K4A_BUFFER_RESULT_SUCCEEDED) + { + throw error("Failed to read raw device calibration from recording!"); + } + + return calibration; + } + + /** Get the camera calibration for the K4A device that made the recording, which is used for all transformation + * functions. Throws error on failure. + * + * \sa k4a_playback_get_calibration + */ + calibration get_calibration() const + { + calibration calib; + k4a_result_t result = k4a_playback_get_calibration(m_handle, &calib); + + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to read device calibration from recording!"); + } + + return calib; + } + + /** Gets the configuration of the recording + * + * \sa k4a_playback_get_record_configuration + */ + k4a_record_configuration_t get_record_configuration() const + { + k4a_record_configuration_t config; + k4a_result_t result = k4a_playback_get_record_configuration(m_handle, &config); + + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to read record configuration!"); + } + + return config; + } + + /** Get the next capture in the recording + * Returns true if a capture was available, false if there are none left + * Throws error on failure. + * + * \sa k4a_playback_get_next_capture + */ + bool get_next_capture(capture *cap) + { + k4a_capture_t capture_handle; + k4a_stream_result_t result = k4a_playback_get_next_capture(m_handle, &capture_handle); + + if (K4A_STREAM_RESULT_SUCCEEDED == result) + { + *cap = capture(capture_handle); + return true; + } + else if (K4A_STREAM_RESULT_EOF == result) + { + return false; + } + + throw error("Failed to get next capture!"); + } + + /** Get the next capture in the recording + * Returns true if a capture was available, false if there are none left + * Throws error on failure. + * + * \sa k4a_playback_get_previous_capture + */ + bool get_previous_capture(capture *cap) + { + k4a_capture_t capture_handle; + k4a_stream_result_t result = k4a_playback_get_previous_capture(m_handle, &capture_handle); + + if (K4A_STREAM_RESULT_SUCCEEDED == result) + { + *cap = capture(capture_handle); + return true; + } + else if (K4A_STREAM_RESULT_EOF == result) + { + return false; + } + + throw error("Failed to get next capture!"); + } + + /** Reads the value of a tag from the recording + * Returns false if the tag does not exist. + * + * \sa k4a_playback_get_tag + */ + bool get_tag(const char *name, std::string *out) const + { + std::string tag; + size_t buffer = 0; + k4a_buffer_result_t result = k4a_playback_get_tag(m_handle, name, &tag[0], &buffer); + + if (result == K4A_BUFFER_RESULT_TOO_SMALL && buffer > 0) + { + tag.resize(buffer); + result = k4a_playback_get_tag(m_handle, name, &tag[0], &buffer); + if (result == K4A_BUFFER_RESULT_SUCCEEDED && tag[buffer - 1] == 0) + { + // std::string expects there to not be as null terminator at the end of its data but + // k4a_playback_get_tag adds a null terminator, so we drop the last character of the string after we + // get the result back. + tag.resize(buffer - 1); + } + } + + if (result != K4A_BUFFER_RESULT_SUCCEEDED) + { + return false; + } + + *out = std::move(tag); + + return true; + } + + /** Get the next IMU sample in the recording + * Returns true if a sample was available, false if there are none left + * Throws error on failure. + * + * \sa k4a_playback_get_next_imu_sample + */ + bool get_next_imu_sample(k4a_imu_sample_t *sample) + { + k4a_stream_result_t result = k4a_playback_get_next_imu_sample(m_handle, sample); + + if (K4A_STREAM_RESULT_SUCCEEDED == result) + { + return true; + } + else if (K4A_STREAM_RESULT_EOF == result) + { + return false; + } + + throw error("Failed to get next IMU sample!"); + } + + /** Get the previous IMU sample in the recording + * Returns true if a sample was available, false if there are none left + * Throws error on failure. + * + * \sa k4a_playback_get_previous_imu_sample + */ + bool get_previous_imu_sample(k4a_imu_sample_t *sample) + { + k4a_stream_result_t result = k4a_playback_get_previous_imu_sample(m_handle, sample); + + if (K4A_STREAM_RESULT_SUCCEEDED == result) + { + return true; + } + else if (K4A_STREAM_RESULT_EOF == result) + { + return false; + } + + throw error("Failed to get previous IMU sample!"); + } + + /** Seeks to a specific time point in the recording + * Throws error on failure. + * + * \sa k4a_playback_seek_timestamp + */ + void seek_timestamp(std::chrono::microseconds offset, k4a_playback_seek_origin_t origin) + { + k4a_result_t result = k4a_playback_seek_timestamp(m_handle, offset.count(), origin); + + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to seek recording!"); + } + } + + /** Get the last valid timestamp in the recording + * + * \sa k4a_playback_get_recording_length_usec + */ + std::chrono::microseconds get_recording_length() const noexcept + { + return std::chrono::microseconds(k4a_playback_get_recording_length_usec(m_handle)); + } + + /** Set the image format that color captures will be converted to. By default the conversion format will be the same + * as the image format stored in the recording file, and no conversion will occur. + * + * Throws error on failure. + * + * \sa k4a_playback_set_color_conversion + */ + void set_color_conversion(k4a_image_format_t format) + { + k4a_result_t result = k4a_playback_set_color_conversion(m_handle, format); + + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to set color conversion!"); + } + } + + /** Opens a K4A recording for playback. + * Throws error on failure. + * + * \sa k4a_playback_open + */ + static playback open(const char *path) + { + k4a_playback_t handle = nullptr; + k4a_result_t result = k4a_playback_open(path, &handle); + + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to open recording!"); + } + + return playback(handle); + } + +private: + k4a_playback_t m_handle; +}; + +} // namespace k4a + +#endif diff --git a/k4a-sys/vendor/include/linux/k4arecord/record.h b/k4a-sys/vendor/include/linux/k4arecord/record.h new file mode 100644 index 0000000000..998ce3d693 --- /dev/null +++ b/k4a-sys/vendor/include/linux/k4arecord/record.h @@ -0,0 +1,473 @@ +/** \file record.h + * Copyright (c) Microsoft Corporation. All rights reserved. + * Licensed under the MIT License. + * Kinect For Azure Recording SDK. + */ + +#ifndef K4A_RECORD_H +#define K4A_RECORD_H + +#include +#include + +#ifdef __cplusplus + +extern "C" { +#endif + +/** + * + * \addtogroup Functions + * + * @{ + */ + +/** Opens a new recording file for writing. + * + * \param path + * Filesystem path for the new recording. + * + * \param device + * The Azure Kinect device that is being recorded. The device handle is used to store device calibration and serial + * number information. May be NULL if recording user-generated data. + * + * \param device_config + * The configuration the Azure Kinect device was started with. + * + * \param recording_handle + * If successful, this contains a pointer to the new recording handle. Caller must call k4a_record_close() + * when finished with recording. + * + * \remarks + * The file will be created if it doesn't exist, or overwritten if an existing file is specified. + * + * \remarks + * Streaming does not need to be started on the device at the time this function is called, but when it is started + * it should be started with the same configuration provided in \p device_config. + * + * \remarks + * Subsequent calls to k4a_record_write_capture() will need to have images in the resolution and format defined + * in \p device_config. + * + * \headerfile record.h + * + * \returns ::K4A_RESULT_SUCCEEDED is returned on success + * + * \relates k4a_record_t + * + * \xmlonly + * + * record.h (include k4arecord/record.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_result_t k4a_record_create(const char *path, + k4a_device_t device, + const k4a_device_configuration_t device_config, + k4a_record_t *recording_handle); + +/** Adds a tag to the recording. + * + * \param recording_handle + * The handle of a new recording, obtained by k4a_record_create(). + * + * \param name + * The name of the tag to write. + * + * \param value + * The string value to store in the tag. + * + * \headerfile record.h + * + * \relates k4a_record_t + * + * \returns ::K4A_RESULT_SUCCEEDED is returned on success. + * + * \remarks + * Tags are global to a file, and should store data related to the entire recording, such as camera configuration or + * recording location. + * + * \remarks + * Tag names must be ALL CAPS and may only contain A-Z, 0-9, '-' and '_'. + * + * \remarks + * All tags need to be added before the recording header is written. + * + * \xmlonly + * + * record.h (include k4arecord/record.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_result_t k4a_record_add_tag(k4a_record_t recording_handle, const char *name, const char *value); + +/** Adds the track header for recording IMU. + * + * \param recording_handle + * The handle of a new recording, obtained by k4a_record_create(). + * + * \headerfile record.h + * + * \relates k4a_record_t + * + * \returns ::K4A_RESULT_SUCCEEDED is returned on success + * + * \remarks + * The track needs to be added before the recording header is written. + * + * \xmlonly + * + * record.h (include k4arecord/record.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_result_t k4a_record_add_imu_track(k4a_record_t recording_handle); + +/** Adds an attachment to the recording. + * + * \param recording_handle + * The handle of a new recording, obtained by k4a_record_create(). + * + * \param attachment_name + * The name of the attachment to be stored in the recording file. This name should be a valid filename with an + * extension. + * + * \param buffer + * The attachment data buffer. + * + * \param buffer_size + * The size of the attachment data buffer. + * + * \headerfile record.h + * + * \relates k4a_record_t + * + * \returns ::K4A_RESULT_SUCCEEDED is returned on success + * + * \remarks + * All attachments need to be added before the recording header is written. + * + * \xmlonly + * + * record.h (include k4arecord/record.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_result_t k4a_record_add_attachment(const k4a_record_t recording_handle, + const char *attachment_name, + const uint8_t *buffer, + size_t buffer_size); + +/** Adds custom video tracks to the recording. + * + * \param recording_handle + * The handle of a new recording, obtained by k4a_record_create(). + * + * \param track_name + * The name of the custom video track to be added. + * + * \param codec_id + * A UTF8 null terminated string containing the codec ID of the track. Some of the existing formats are listed here: + * https://www.matroska.org/technical/specs/codecid/index.html. The codec ID can also be custom defined by the user. + * Video codec ID's should start with 'V_'. + * + * \param codec_context + * The codec context is a codec-specific buffer that contains any required codec metadata that is only known to the + * codec. It is mapped to the matroska 'CodecPrivate' element. + * + * \param codec_context_size + * The size of the codec context buffer. + * + * \param track_settings + * Additional metadata for the video track such as resolution and framerate. + * + * \headerfile record.h + * + * \relates k4a_record_t + * + * \returns ::K4A_RESULT_SUCCEEDED is returned on success + * + * \remarks + * Built-in video tracks like the DEPTH, IR, and COLOR tracks will be created automatically when the k4a_record_create() + * API is called. This API can be used to add additional video tracks to save custom data. + * + * \remarks + * Track names must be ALL CAPS and may only contain A-Z, 0-9, '-' and '_'. + * + * \remarks + * All tracks need to be added before the recording header is written. + * + * \remarks + * Call k4a_record_write_custom_track_data() with the same track_name to write data to this track. + * + * \xmlonly + * + * record.h (include k4arecord/record.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_result_t k4a_record_add_custom_video_track(const k4a_record_t recording_handle, + const char *track_name, + const char *codec_id, + const uint8_t *codec_context, + size_t codec_context_size, + const k4a_record_video_settings_t *track_settings); + +/** Adds custom subtitle tracks to the recording. + * + * \param recording_handle + * The handle of a new recording, obtained by k4a_record_create(). + * + * \param track_name + * The name of the custom subtitle track to be added. + * + * \param codec_id + * A UTF8 null terminated string containing the codec ID of the track. Some of the existing formats are listed here: + * https://www.matroska.org/technical/specs/codecid/index.html. The codec ID can also be custom defined by the user. + * Subtitle codec ID's should start with 'S_'. + * + * \param codec_context + * The codec context is a codec-specific buffer that contains any required codec metadata that is only known to the + * codec. It is mapped to the matroska 'CodecPrivate' element. + * + * \param codec_context_size + * The size of the codec context buffer. + * + * \param track_settings + * Additional metadata for the subtitle track. If NULL, the default settings will be used. + * + * \headerfile record.h + * + * \relates k4a_record_t + * + * \returns ::K4A_RESULT_SUCCEEDED is returned on success + * + * \remarks + * Built-in subtitle tracks like the IMU track will be created automatically when the k4a_record_add_imu_track() API is + * called. This API can be used to add additional subtitle tracks to save custom data. + * + * \remarks + * Track names must be ALL CAPS and may only contain A-Z, 0-9, '-' and '_'. + * + * \remarks + * All tracks need to be added before the recording header is written. + * + * \remarks + * Call k4a_record_write_custom_track_data() with the same track_name to write data to this track. + * + * \xmlonly + * + * record.h (include k4arecord/record.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_result_t +k4a_record_add_custom_subtitle_track(const k4a_record_t recording_handle, + const char *track_name, + const char *codec_id, + const uint8_t *codec_context, + size_t codec_context_size, + const k4a_record_subtitle_settings_t *track_settings); + +/** Writes the recording header and metadata to file. + * + * \param recording_handle + * The handle of a new recording, obtained by k4a_record_create(). + * + * \headerfile record.h + * + * \relates k4a_record_t + * + * \returns ::K4A_RESULT_SUCCEEDED is returned on success + * + * \remarks + * This must be called before captures or any track data can be written. + * + * \xmlonly + * + * record.h (include k4arecord/record.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_result_t k4a_record_write_header(k4a_record_t recording_handle); + +/** Writes a camera capture to file. + * + * \param recording_handle + * The handle of a new recording, obtained by k4a_record_create(). + * + * \param capture_handle + * The handle of a capture to write to file. + * + * \headerfile record.h + * + * \relates k4a_record_t + * + * \returns ::K4A_RESULT_SUCCEEDED is returned on success + * + * \remarks + * Captures must be written in increasing order of timestamp, and the file's header must already be written. + * + * \remarks + * k4a_record_write_capture() will write all images in the capture to the corresponding tracks in the recording file. + * If any of the images fail to write, other images will still be written before a failure is returned. + * + * \xmlonly + * + * record.h (include k4arecord/record.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_result_t k4a_record_write_capture(k4a_record_t recording_handle, k4a_capture_t capture_handle); + +/** Writes an imu sample to file. + * + * \param recording_handle + * The handle of a new recording, obtained by k4a_record_create(). + * + * \param imu_sample + * A structure containing the imu sample data and timestamps. + * + * \headerfile record.h + * + * \relates k4a_record_t + * + * \returns ::K4A_RESULT_SUCCEEDED is returned on success + * + * \remarks + * Samples must be written in increasing order of timestamp, and the file's header must already be written. + * + * \remarks + * When writing imu samples at the same time as captures, the samples should be within 1 second of the most recently + * written capture. + * + * \xmlonly + * + * record.h (include k4arecord/record.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_result_t k4a_record_write_imu_sample(k4a_record_t recording_handle, k4a_imu_sample_t imu_sample); + +/** Writes data for a custom track to file. + * + * \param recording_handle + * The handle of a new recording, obtained by k4a_record_create(). + * + * \param track_name + * The name of the custom track that the data is going to be written to. + * + * \param device_timestamp_usec + * The timestamp in microseconds for the custom track data. This timestamp should be in the same time domain as the + * device timestamp used for recording. + * + * \param custom_data + * The buffer of custom track data. + * + * \param custom_data_size + * The size of the custom track data buffer. + * + * \headerfile record.h + * + * \relates k4a_record_t + * + * \returns ::K4A_RESULT_SUCCEEDED is returned on success + * + * \remarks + * Custom track data must be written in increasing order of timestamp, and the file's header must already be written. + * When writing custom track data at the same time as captures or IMU data, the custom data should be within 1 second of + * the most recently written timestamp. + * + * \xmlonly + * + * record.h (include k4arecord/record.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_result_t k4a_record_write_custom_track_data(const k4a_record_t recording_handle, + const char *track_name, + uint64_t device_timestamp_usec, + uint8_t *custom_data, + size_t custom_data_size); + +/** Flushes all pending recording data to disk. + * + * \param recording_handle + * Handle obtained by k4a_record_create(). + * + * \headerfile record.h + * + * \relates k4a_record_t + * + * \returns ::K4A_RESULT_SUCCEEDED is returned on success, or ::K4A_RESULT_FAILED if an error occurred. + * + * \remarks + * k4a_record_flush() ensures that all data passed to the recording API prior to calling flush is written to disk. + * If continuing to write recording data, care must be taken to ensure no new timestamps are added from before the + * flush. + * + * \remarks + * If an error occurs, best effort is made to flush as much data to disk as possible, but the integrity of the file is + * not guaranteed. + * + * \xmlonly + * + * record.h (include k4arecord/record.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_result_t k4a_record_flush(k4a_record_t recording_handle); + +/** Closes a recording handle. + * + * \param recording_handle + * Handle obtained by k4a_record_create(). + * + * \headerfile record.h + * + * \relates k4a_record_t + * + * \remarks + * If there is any unwritten data it will be flushed to disk before closing the recording. + * + * \xmlonly + * + * record.h (include k4arecord/record.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT void k4a_record_close(k4a_record_t recording_handle); + +/** + * @} + */ + +#ifdef __cplusplus +} // extern "C" +#endif + +#endif /* K4A_RECORD_H */ diff --git a/k4a-sys/vendor/include/linux/k4arecord/types.h b/k4a-sys/vendor/include/linux/k4arecord/types.h new file mode 100644 index 0000000000..f3533f2125 --- /dev/null +++ b/k4a-sys/vendor/include/linux/k4arecord/types.h @@ -0,0 +1,261 @@ +/** \file types.h + * Copyright (c) Microsoft Corporation. All rights reserved. + * Licensed under the MIT License. + * Kinect For Azure Playback/Record type definitions. + */ + +#ifndef K4ARECORD_TYPES_H +#define K4ARECORD_TYPES_H + +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * \addtogroup Handles + * @{ + */ + +/** \class k4a_record_t types.h + * Handle to a k4a recording opened for writing. + * + * \remarks + * Handles are created with k4a_record_create(), and closed with k4a_record_close(). + * Invalid handles are set to 0. + * + * \xmlonly + * + * types.h (include k4arecord/types.h) + * + * \endxmlonly + */ +K4A_DECLARE_HANDLE(k4a_record_t); + +/** \class k4a_playback_t types.h + * Handle to a k4a recording opened for playback. + * + * \remarks + * Handles are created with k4a_playback_open(), and closed with k4a_playback_close(). + * Invalid handles are set to 0. + * + * \xmlonly + * + * types.h (include k4arecord/types.h) + * + * \endxmlonly + */ +K4A_DECLARE_HANDLE(k4a_playback_t); + +/** \class k4a_playback_data_block_t types.h + * Handle to a block of data read from a k4a_playback_t custom track. + * + * \remarks + * Handles are obtained from k4a_playback_get_next_data_block() or k4a_playback_get_previous_data_block(), and released + * with k4a_playback_data_block_release(). Invalid handles are set to 0. + * + * \xmlonly + * + * types.h (include k4arecord/types.h) + * + * \endxmlonly + */ +K4A_DECLARE_HANDLE(k4a_playback_data_block_t) + +/** + * @} + * + * \addtogroup Definitions + * @{ + */ + +/** Name of the built-in color track used in recordings. + * + * \xmlonly + * + * types.h (include k4arecord/types.h) + * + * \endxmlonly + */ +#define K4A_TRACK_NAME_COLOR "COLOR" + +/** Name of the built-in depth track used in recordings. + * + * \xmlonly + * + * types.h (include k4arecord/types.h) + * + * \endxmlonly + */ +#define K4A_TRACK_NAME_DEPTH "DEPTH" + +/** Name of the built-in IR track used in recordings. + * + * \xmlonly + * + * types.h (include k4arecord/types.h) + * + * \endxmlonly + */ +#define K4A_TRACK_NAME_IR "IR" + +/** Name of the built-in imu track used in recordings. + * + * \xmlonly + * + * types.h (include k4arecord/types.h) + * + * \endxmlonly + */ +#define K4A_TRACK_NAME_IMU "IMU" + +/** + * @} + * + * \addtogroup Enumerations + * @{ + */ + +/** Return codes returned by Azure Kinect playback API. + * + * \xmlonly + * + * types.h (include k4arecord/types.h) + * + * \endxmlonly + */ +typedef enum +{ + K4A_STREAM_RESULT_SUCCEEDED = 0, /**< The result was successful. */ + K4A_STREAM_RESULT_FAILED, /**< The result was a failure. */ + K4A_STREAM_RESULT_EOF, /**< The end of the data stream was reached. */ +} k4a_stream_result_t; + +/** Playback seeking positions. + * + * \xmlonly + * + * types.h (include k4arecord/types.h) + * + * \endxmlonly + */ +typedef enum +{ + K4A_PLAYBACK_SEEK_BEGIN, /**< Seek relative to the beginning of a recording. */ + K4A_PLAYBACK_SEEK_END, /**< Seek relative to the end of a recording. */ + K4A_PLAYBACK_SEEK_DEVICE_TIME /**< Seek to an absolute device timestamp. */ +} k4a_playback_seek_origin_t; + +/** + * @} + * + * \addtogroup Structures + * @{ + */ + +/** Structure containing the device configuration used to record. + * + * \see k4a_device_configuration_t + * \see k4a_playback_get_record_configuration() + * + * \xmlonly + * + * types.h (include k4arecord/types.h) + * + * \endxmlonly + */ +typedef struct _k4a_record_configuration_t +{ + /** Image format used to record the color camera. */ + k4a_image_format_t color_format; + + /** Image resolution used to record the color camera. */ + k4a_color_resolution_t color_resolution; + + /** Mode used to record the depth camera. */ + k4a_depth_mode_t depth_mode; + + /** Frame rate used to record the color and depth camera. */ + k4a_fps_t camera_fps; + + /** True if the recording contains Color camera frames. */ + bool color_track_enabled; + + /** True if the recording contains Depth camera frames. */ + bool depth_track_enabled; + + /** True if the recording contains IR camera frames. */ + bool ir_track_enabled; + + /** True if the recording contains IMU sample data. */ + bool imu_track_enabled; + + /** + * The delay between color and depth images in the recording. + * A negative delay means depth images are first, and a positive delay means color images are first. + */ + int32_t depth_delay_off_color_usec; + + /** External synchronization mode */ + k4a_wired_sync_mode_t wired_sync_mode; + + /** + * The delay between this recording and the externally synced master camera. + * This value is 0 unless \p wired_sync_mode is set to ::K4A_WIRED_SYNC_MODE_SUBORDINATE + */ + uint32_t subordinate_delay_off_master_usec; + + /** + * The timestamp offset of the start of the recording. All recorded timestamps are offset by this value such that + * the recording starts at timestamp 0. This value can be used to synchronize timestamps between 2 recording files. + */ + uint32_t start_timestamp_offset_usec; +} k4a_record_configuration_t; + +/** Structure containing additional metadata specific to custom video tracks. + * + * \xmlonly + * + * types.h (include k4arecord/types.h) + * + * \endxmlonly + */ +typedef struct _k4a_record_video_settings_t +{ + uint64_t width; /**< Frame width of the video */ + uint64_t height; /**< Frame height of the video */ + uint64_t frame_rate; /**< Frame rate (frames-per-second) of the video */ +} k4a_record_video_settings_t; + +/** Structure containing additional metadata specific to custom subtitle tracks. + * + * \xmlonly + * + * types.h (include k4arecord/types.h) + * + * \endxmlonly + */ +typedef struct _k4a_record_subtitle_settings_t +{ + /** + * If true, data will be grouped together in batches to reduce overhead. In this mode, only a single timestamp will + * be stored per batch, and an estimated timestamp will be used by k4a_playback_seek_timestamp() and + * k4a_playback_data_block_get_timestamp_usec(). The estimated timestamp is calculated with the assumption that + * blocks are evenly spaced within a batch. If precise timestamps are required, the timestamp should be added to + * each data block itself. + * + * If false, data will be stored as individual blocks with full timestamp information (Default). + */ + bool high_freq_data; +} k4a_record_subtitle_settings_t; + +/** + * @} + */ + +#ifdef __cplusplus +} +#endif + +#endif /* K4ARECORD_TYPES_H */ diff --git a/k4a-sys/vendor/include/windows/k4a/k4a.h b/k4a-sys/vendor/include/windows/k4a/k4a.h new file mode 100644 index 0000000000..5f673dad2b --- /dev/null +++ b/k4a-sys/vendor/include/windows/k4a/k4a.h @@ -0,0 +1,2277 @@ +/** \file k4a.h + * Copyright (c) Microsoft Corporation. All rights reserved. + * Licensed under the MIT License. + * Kinect For Azure SDK. + */ + +#ifndef K4A_H +#define K4A_H + +#ifdef __cplusplus +#include +#else +#include +#endif +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * \defgroup Functions Functions + * \ingroup csdk + * + * Public functions of the API + * + * @{ + */ + +/** Gets the number of connected devices + * + * \returns Number of sensors connected to the PC. + * + * \relates k4a_device_t + * + * \remarks + * This API counts the number of Azure Kinect devices connected to the host PC. + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT uint32_t k4a_device_get_installed_count(void); + +/** Sets and clears the callback function to receive debug messages from the Azure Kinect device. + * + * \param message_cb + * The callback function to receive messages from. Set to NULL to unregister the callback function. + * + * \param message_cb_context + * The callback functions context. + * + * \param min_level + * The least critical error the user wants to be notified about. + * + * \return ::K4A_RESULT_SUCCEEDED if the callback function was set or cleared successfully. ::K4A_RESULT_FAILED if an + * error is encountered or the callback function has already been set. + * + * \remarks + * Call this function to set or clear the callback function that is used to deliver debug messages to the caller. This + * callback may be called concurrently, it is up to the implementation of the callback function to ensure the + * parallelization is handled. + * + * \remarks + * Clearing the callback function will block until all pending calls to the callback function have completed. + * + * \remarks + * To update \p min_level, \p k4a_set_debug_message_handler can be called with the same value \p message_cb and by + * specifying a new \p min_level. + * + * \remarks + * Logging provided via this API is independent of the logging controlled by the environmental variable controls \p + * K4A_ENABLE_LOG_TO_STDOUT, \p K4A_ENABLE_LOG_TO_A_FILE, and \p K4A_LOG_LEVEL. However there is a slight change in + * default behavior when using this function. By default, when \p k4a_set_debug_message_handler() has not been used to + * register a message callback, the default for environmental variable controls is to send debug messages as if + * K4A_ENABLE_LOG_TO_STDOUT=1 were set. If \p k4a_set_debug_message_handler registers a callback function before + * k4a_device_open() is called, then the default for environmental controls is as if K4A_ENABLE_LOG_TO_STDOUT=0 was + * specified. Physically specifying the environmental control will override the default. + * + * \p min_level + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_set_debug_message_handler(k4a_logging_message_cb_t *message_cb, + void *message_cb_context, + k4a_log_level_t min_level); + +/** Sets the callback functions for the SDK allocator + * + * \param allocate + * The callback function to allocate memory. When the SDK requires memory allocation this callback will be + * called and the application can provide a buffer and a context. + * + * \param free + * The callback function to free memory. The SDK will call this function when memory allocated by \p allocate + * is no longer needed. + * + * \return ::K4A_RESULT_SUCCEEDED if the callback function was set or cleared successfully. ::K4A_RESULT_FAILED if an + * error is encountered or the callback function has already been set. + * + * \remarks + * Call this function to hook memory allocation by the SDK. Calling with both \p allocate and \p free as NULL will + * clear the hook and reset to the default allocator. + * + * \remarks + * If this function is called after memory has been allocated, the previous version of \p free function may still be + * called in the future. The SDK will always call the \p free function that was set at the time that the memory + * was allocated. + * + * \remarks + * Not all memory allocation by the SDK is performed by this allocate function. Small allocations or allocations + * from special pools may come from other sources. + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_set_allocator(k4a_memory_allocate_cb_t allocate, k4a_memory_destroy_cb_t free); + +/** Open an Azure Kinect device. + * + * \param index + * The index of the device to open, starting with 0. Optionally pass in #K4A_DEVICE_DEFAULT. + * + * \param device_handle + * Output parameter which on success will return a handle to the device. + * + * \relates k4a_device_t + * + * \return ::K4A_RESULT_SUCCEEDED if the device was opened successfully. + * + * \remarks + * If successful, k4a_device_open() will return a device handle in the device_handle parameter. + * This handle grants exclusive access to the device and may be used in the other Azure Kinect API calls. + * + * \remarks + * When done with the device, close the handle with k4a_device_close() + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_device_open(uint32_t index, k4a_device_t *device_handle); + +/** Closes an Azure Kinect device. + * + * \param device_handle + * Handle obtained by k4a_device_open(). + * + * \relates k4a_device_t + * + * \remarks Once closed, the handle is no longer valid. + * + * \remarks Before closing the handle to the device, ensure that all \ref k4a_capture_t captures have been released with + * k4a_capture_release(). + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT void k4a_device_close(k4a_device_t device_handle); + +/** Reads a sensor capture. + * + * \param device_handle + * Handle obtained by k4a_device_open(). + * + * \param capture_handle + * If successful this contains a handle to a capture object. Caller must call k4a_capture_release() when its done using + * this capture. + * + * \param timeout_in_ms + * Specifies the time in milliseconds the function should block waiting for the capture. If set to 0, the function will + * return without blocking. Passing a value of #K4A_WAIT_INFINITE will block indefinitely until data is available, the + * device is disconnected, or another error occurs. + * + * \returns + * ::K4A_WAIT_RESULT_SUCCEEDED if a capture is returned. If a capture is not available before the timeout elapses, the + * function will return ::K4A_WAIT_RESULT_TIMEOUT. All other failures will return ::K4A_WAIT_RESULT_FAILED. + * + * \relates k4a_device_t + * + * \remarks + * Gets the next capture in the streamed sequence of captures from the camera. If a new capture is not currently + * available, this function will block until the timeout is reached. The SDK will buffer at least two captures worth + * of data before dropping the oldest capture. Callers needing to capture all data need to ensure they read the data as + * fast as the data is being produced on average. + * + * \remarks + * Upon successfully reading a capture this function will return success and populate \p capture. + * If a capture is not available in the configured \p timeout_in_ms, then the API will return ::K4A_WAIT_RESULT_TIMEOUT. + * + * \remarks + * If the call is successful and a capture is returned, callers must call k4a_capture_release() to return the allocated + * memory. + * + * \remarks + * This function needs to be called while the device is in a running state; + * after k4a_device_start_cameras() is called and before k4a_device_stop_cameras() is called. + * + * \remarks + * This function returns an error when an internal problem is encountered; such as loss of the USB connection, inability + * to allocate enough memory, and other unexpected issues. Any error returned by this function signals the end of + * streaming data, and caller should stop the stream using k4a_device_stop_cameras(). + * + * \remarks + * If this function is waiting for data (non-zero timeout) when k4a_device_stop_cameras() or k4a_device_close() is + * called on another thread, this function will return an error. + * + * \returns ::K4A_WAIT_RESULT_SUCCEEDED if a capture is returned. If a capture is not available before the timeout + * elapses, the function will return ::K4A_WAIT_RESULT_TIMEOUT. All other failures will return ::K4A_WAIT_RESULT_FAILED. + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + * + */ +K4A_EXPORT k4a_wait_result_t k4a_device_get_capture(k4a_device_t device_handle, + k4a_capture_t *capture_handle, + int32_t timeout_in_ms); + +/** Reads an IMU sample. + * + * \param device_handle + * Handle obtained by k4a_device_open(). + * + * \param imu_sample + * Pointer to the location for the API to write the IMU sample. + * + * \param timeout_in_ms + * Specifies the time in milliseconds the function should block waiting for the sample. If set to 0, the function will + * return without blocking. Passing a value of #K4A_WAIT_INFINITE will block indefinitely until data is available, the + * device is disconnected, or another error occurs. + * + * \returns + * ::K4A_WAIT_RESULT_SUCCEEDED if a sample is returned. If a sample is not available before the timeout elapses, the + * function will return ::K4A_WAIT_RESULT_TIMEOUT. All other failures will return ::K4A_WAIT_RESULT_FAILED. + * + * \relates k4a_device_t + * + * \remarks + * Gets the next sample in the streamed sequence of IMU samples from the device. If a new sample is not currently + * available, this function will block until the timeout is reached. The API will buffer at least two camera capture + * intervals worth of samples before dropping the oldest sample. Callers needing to capture all data need to ensure they + * read the data as fast as the data is being produced on average. + * + * \remarks + * Upon successfully reading a sample this function will return success and populate \p imu_sample. + * If a sample is not available in the configured \p timeout_in_ms, then the API will return ::K4A_WAIT_RESULT_TIMEOUT. + * + * \remarks + * This function needs to be called while the device is in a running state; + * after k4a_device_start_imu() is called and before k4a_device_stop_imu() is called. + * + * \remarks + * This function returns an error when an internal problem is encountered; such as loss of the USB connection, inability + * to allocate enough memory, and other unexpected issues. Any error returned by this function signals the end of + * streaming data, and caller should stop the stream using k4a_device_stop_imu(). + * + * \remarks + * If this function is waiting for data (non-zero timeout) when k4a_device_stop_imu() or k4a_device_close() is + * called on another thread, this function will return an error. + * + * \remarks + * The memory the IMU sample is written to is allocated and owned by the caller, so there is no need to call an Azure + * Kinect API to free or release the sample. + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_wait_result_t k4a_device_get_imu_sample(k4a_device_t device_handle, + k4a_imu_sample_t *imu_sample, + int32_t timeout_in_ms); + +/** Create an empty capture object. + * + * \param capture_handle + * Pointer to a location to store the handle. + * + * \relates k4a_capture_t + * + * \remarks + * Call this function to create a \ref k4a_capture_t handle for a new capture. Release it with k4a_capture_release(). + * + * The new capture is created with a reference count of 1. + * + * \returns + * Returns #K4A_RESULT_SUCCEEDED on success. Errors are indicated with #K4A_RESULT_FAILED and error specific data can be + * found in the log. + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_capture_create(k4a_capture_t *capture_handle); + +/** Release a capture. + * + * \param capture_handle + * Capture to release. + * + * \relates k4a_capture_t + * + * \remarks + * Call this function when finished using the capture. + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT void k4a_capture_release(k4a_capture_t capture_handle); + +/** Add a reference to a capture. + * + * \param capture_handle + * Capture to add a reference to. + * + * \relates k4a_capture_t + * + * \remarks + * Call this function to add an additional reference to a capture. This reference must be removed with + * k4a_capture_release(). + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT void k4a_capture_reference(k4a_capture_t capture_handle); + +/** Get the color image associated with the given capture. + * + * \param capture_handle + * Capture handle containing the image. + * + * \relates k4a_capture_t + * + * \remarks + * Call this function to access the color image part of this capture. Release the \ref k4a_image_t with + * k4a_image_release(); + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_image_t k4a_capture_get_color_image(k4a_capture_t capture_handle); + +/** Get the depth image associated with the given capture. + * + * \param capture_handle + * Capture handle containing the image. + * + * \relates k4a_capture_t + * + * \remarks + * Call this function to access the depth image part of this capture. Release the \ref k4a_image_t with + * k4a_image_release(); + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_image_t k4a_capture_get_depth_image(k4a_capture_t capture_handle); + +/** Get the IR image associated with the given capture. + * + * \param capture_handle + * Capture handle containing the image. + * + * \relates k4a_capture_t + * + * \remarks + * Call this function to access the IR image part of this capture. Release the \ref k4a_image_t with + * k4a_image_release(); + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_image_t k4a_capture_get_ir_image(k4a_capture_t capture_handle); + +/** Set or add a color image to the associated capture. + * + * \param capture_handle + * Capture handle to hold the image. + * + * \param image_handle + * Image handle containing the image. + * + * \relates k4a_capture_t + * + * \remarks + * When a \ref k4a_image_t is added to a \ref k4a_capture_t, the \ref k4a_capture_t will automatically add a reference + * to the \ref k4a_image_t. + * + * \remarks + * If there is already a color image contained in the capture, the existing image will be dereferenced and replaced with + * the new image. + * + * \remarks + * To remove a color image to the capture without adding a new image, this function can be called with a NULL + * image_handle. + * + * \remarks + * Any \ref k4a_image_t contained in this \ref k4a_capture_t will automatically be dereferenced when all references to + * the \ref k4a_capture_t are released with k4a_capture_release(). + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT void k4a_capture_set_color_image(k4a_capture_t capture_handle, k4a_image_t image_handle); + +/** Set or add a depth image to the associated capture. + * + * \param capture_handle + * Capture handle to hold the image. + * + * \param image_handle + * Image handle containing the image. + * + * \relates k4a_capture_t + * + * \remarks + * When a \ref k4a_image_t is added to a \ref k4a_capture_t, the \ref k4a_capture_t will automatically add a reference + * to the \ref k4a_image_t. + * + * \remarks + * If there is already an image depth image contained in the capture, the existing image will be dereferenced and + * replaced with the new image. + * + * \remarks + * To remove a depth image to the capture without adding a new image, this function can be called with a NULL + * image_handle. + * + * \remarks + * Any \ref k4a_image_t contained in this \ref k4a_capture_t will automatically be dereferenced when all references to + * the \ref k4a_capture_t are released with k4a_capture_release(). + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT void k4a_capture_set_depth_image(k4a_capture_t capture_handle, k4a_image_t image_handle); + +/** Set or add an IR image to the associated capture. + * + * \param capture_handle + * Capture handle to hold the image. + * + * \param image_handle + * Image handle containing the image. + * + * \relates k4a_capture_t + * + * \remarks + * When a \ref k4a_image_t is added to a \ref k4a_capture_t, the \ref k4a_capture_t will automatically add a reference + * to the \ref k4a_image_t. + * + * \remarks + * If there is already an IR image contained in the capture, the existing image will be dereferenced and replaced with + * the new image. + * + * \remarks + * To remove a IR image to the capture without adding a new image, this function can be called with a NULL image_handle. + * + * \remarks + * Any \ref k4a_image_t contained in this \ref k4a_capture_t will automatically be dereferenced when all references to + * the \ref k4a_capture_t are released with k4a_capture_release(). + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT void k4a_capture_set_ir_image(k4a_capture_t capture_handle, k4a_image_t image_handle); + +/** Set the temperature associated with the capture. + * + * \param capture_handle + * Capture handle to set the temperature on. + * + * \param temperature_c + * Temperature in Celsius to store. + * + * \relates k4a_capture_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT void k4a_capture_set_temperature_c(k4a_capture_t capture_handle, float temperature_c); + +/** Get the temperature associated with the capture. + * + * \param capture_handle + * Capture handle to retrieve the temperature from. + * + * \return + * This function returns the temperature of the device at the time of the capture in Celsius. If + * the temperature is unavailable, the function will return NAN. + * + * \relates k4a_capture_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT float k4a_capture_get_temperature_c(k4a_capture_t capture_handle); + +/** Create an image. + * + * \param format + * The format of the image that will be stored in this image container. + * + * \param width_pixels + * Width in pixels. + * + * \param height_pixels + * Height in pixels. + * + * \param stride_bytes + * The number of bytes per horizontal line of the image. + * If set to 0, the stride will be set to the minimum size given the \p format and \p width_pixels. + * + * \param image_handle + * Pointer to store image handle in. + * + * \remarks + * This function is used to create images of formats that have consistent stride. The function is not suitable for + * compressed formats that may not be represented by the same number of bytes per line. + * + * \remarks + * For most image formats, the function will allocate an image buffer of size \p height_pixels * \p stride_bytes. + * Buffers #K4A_IMAGE_FORMAT_COLOR_NV12 format will allocate an additional \p height_pixels / 2 set of lines (each of \p + * stride_bytes). This function cannot be used to allocate #K4A_IMAGE_FORMAT_COLOR_MJPG buffers. + * + * \remarks + * To create an image object without the API allocating memory, or to represent an image that has a non-deterministic + * stride, use k4a_image_create_from_buffer(). + * + * \remarks + * The \ref k4a_image_t is created with a reference count of 1. + * + * \remarks + * When finished using the created image, release it with k4a_image_release. + * + * \returns + * Returns #K4A_RESULT_SUCCEEDED on success. Errors are indicated with #K4A_RESULT_FAILED. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_image_create(k4a_image_format_t format, + int width_pixels, + int height_pixels, + int stride_bytes, + k4a_image_t *image_handle); + +/** Create an image from a pre-allocated buffer. + * + * \param format + * The format of the image that will be stored in this image container. + * + * \param width_pixels + * Width in pixels. + * + * \param height_pixels + * Height in pixels. + * + * \param stride_bytes + * The number of bytes per horizontal line of the image. + * + * \param buffer + * Pointer to a pre-allocated image buffer. + * + * \param buffer_size + * Size in bytes of the pre-allocated image buffer. + * + * \param buffer_release_cb + * Callback to the buffer free function, called when all references to the buffer have been released. This parameter is + * optional. + * + * \param buffer_release_cb_context + * Context for the buffer free function. This value will be called as a parameter to \p buffer_release_cb when + * the callback is invoked. + * + * \param image_handle + * Pointer to store image handle in. + * + * \remarks + * This function creates a \ref k4a_image_t from a pre-allocated buffer. When all references to this object reach zero + * the provided \p buffer_release_cb callback function is called so that the memory can be released. If this function + * fails, the API will not use the memory provided in \p buffer, and the API will not call \p buffer_release_cb. + * + * \remarks + * The \ref k4a_image_t is created with a reference count of 1. + * + * \remarks + * Release the reference on this function with k4a_image_release(). + * + * \returns + * Returns #K4A_RESULT_SUCCEEDED on success. Errors are indicated with #K4A_RESULT_FAILED and error specific data can be + * found in the log. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_image_create_from_buffer(k4a_image_format_t format, + int width_pixels, + int height_pixels, + int stride_bytes, + uint8_t *buffer, + size_t buffer_size, + k4a_memory_destroy_cb_t *buffer_release_cb, + void *buffer_release_cb_context, + k4a_image_t *image_handle); + +/** Get the image buffer. + * + * \param image_handle + * Handle of the image for which the get operation is performed on. + * + * \remarks + * Use this buffer to access the raw image data. + * + * \returns + * The function will return NULL if there is an error, and will normally return a pointer to the image buffer. + * Since all \ref k4a_image_t instances are created with an image buffer, this function should only return NULL if the + * \p image_handle is invalid. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT uint8_t *k4a_image_get_buffer(k4a_image_t image_handle); + +/** Get the image buffer size. + * + * \param image_handle + * Handle of the image for which the get operation is performed on. + * + * \remarks + * Use this function to know what the size of the image buffer is returned by k4a_image_get_buffer(). + * + * \returns + * The function will return 0 if there is an error, and will normally return the image size. + * Since all \ref k4a_image_t instances are created with an image buffer, this function should only return 0 if the + * \p image_handle is invalid. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT size_t k4a_image_get_size(k4a_image_t image_handle); + +/** Get the format of the image. + * + * \param image_handle + * Handle of the image for which the get operation is performed on. + * + * \remarks + * Use this function to determine the format of the image buffer. + * + * \returns + * This function is not expected to fail, all \ref k4a_image_t's are created with a known format. If the + * \p image_handle is invalid, the function will return ::K4A_IMAGE_FORMAT_CUSTOM. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_image_format_t k4a_image_get_format(k4a_image_t image_handle); + +/** Get the image width in pixels. + * + * \param image_handle + * Handle of the image for which the get operation is performed on. + * + * \returns + * This function is not expected to fail, all \ref k4a_image_t's are created with a known width. If the \p + * image_handle is invalid, the function will return 0. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT int k4a_image_get_width_pixels(k4a_image_t image_handle); + +/** Get the image height in pixels. + * + * \param image_handle + * Handle of the image for which the get operation is performed on. + * + * \returns + * This function is not expected to fail, all \ref k4a_image_t's are created with a known height. If the \p + * image_handle is invalid, the function will return 0. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT int k4a_image_get_height_pixels(k4a_image_t image_handle); + +/** Get the image stride in bytes. + * + * \param image_handle + * Handle of the image for which the get operation is performed on. + * + * \returns + * This function is not expected to fail, all \ref k4a_image_t's are created with a known stride. If the + * \p image_handle is invalid, or the image's format does not have a stride, the function will return 0. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT int k4a_image_get_stride_bytes(k4a_image_t image_handle); + +/** Get the image's device timestamp in microseconds. + * + * \param image_handle + * Handle of the image for which the get operation is performed on. + * + * \remarks + * Returns the device timestamp of the image. Timestamps are recorded by the device and represent the mid-point of + * exposure. They may be used for relative comparison, but their absolute value has no defined meaning. + * + * \returns + * If the \p image_handle is invalid or if no timestamp was set for the image, + * this function will return 0. It is also possible for 0 to be a valid timestamp originating from the beginning + * of a recording or the start of streaming. + * + * \deprecated + * Deprecated starting in 1.2.0. Please use k4a_image_get_device_timestamp_usec(). + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_DEPRECATED_EXPORT uint64_t k4a_image_get_timestamp_usec(k4a_image_t image_handle); + +/** Get the image's device timestamp in microseconds. + * + * \param image_handle + * Handle of the image for which the get operation is performed on. + * + * \remarks + * Returns the device timestamp of the image, as captured by the hardware. Timestamps are recorded by the device and + * represent the mid-point of exposure. They may be used for relative comparison, but their absolute value has no + * defined meaning. + * + * \returns + * If the \p image_handle is invalid or if no timestamp was set for the image, this function will return 0. It is also + * possible for 0 to be a valid timestamp originating from the beginning of a recording or the start of streaming. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT uint64_t k4a_image_get_device_timestamp_usec(k4a_image_t image_handle); + +/** Get the image's system timestamp in nanoseconds. + * + * \param image_handle + * Handle of the image for which the get operation is performed on. + * + * \remarks + * Returns the system timestamp of the image. Timestamps are recorded by the host. They may be used for relative + * comparision, as they are relative to the corresponding system clock. The absolute value is a monotonic count from + * an arbitrary point in the past. + * + * \remarks + * The system timestamp is captured at the moment host PC finishes receiving the image. + * + * \remarks + * On Linux the system timestamp is read from clock_gettime(CLOCK_MONOTONIC), which measures realtime and is not + * impacted by adjustments to the system clock. It starts from an arbitrary point in the past. On Windows the system + * timestamp is read from QueryPerformanceCounter(), it also measures realtime and is not impacted by adjustments to the + * system clock. It also starts from an arbitrary point in the past. + * + * \returns + * If the \p image_handle is invalid or if no timestamp was set for the image, this function will return 0. It is also + * possible for 0 to be a valid timestamp originating from the beginning of a recording or the start of streaming. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT uint64_t k4a_image_get_system_timestamp_nsec(k4a_image_t image_handle); + +/** Get the image exposure in microseconds. + * + * \param image_handle + * Handle of the image for which the get operation is performed on. + * + * \remarks + * Returns an exposure time in microseconds. This is only supported on color image formats. + * + * \returns + * If the \p image_handle is invalid, or no exposure was set on the image, the function will return 0. Otherwise, + * it will return the image exposure time in microseconds. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT uint64_t k4a_image_get_exposure_usec(k4a_image_t image_handle); + +/** Get the image white balance. + * + * \param image_handle + * Handle of the image for which the get operation is performed on. + * + * \remarks + * Returns the image's white balance. This function is only valid for color captures, and not for depth or IR captures. + * + * \returns + * Returns the image white balance in Kelvin. If \p image_handle is invalid, or the white balance was not set or + * not applicable to the image, the function will return 0. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT uint32_t k4a_image_get_white_balance(k4a_image_t image_handle); + +/** Get the image ISO speed. + * + * \param image_handle + * Handle of the image for which the get operation is performed on. + * + * \remarks + * This function is only valid for color captures, and not for depth or IR captures. + * + * \returns + * Returns the ISO speed of the image. 0 indicates the ISO speed was not available or an error occurred. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT uint32_t k4a_image_get_iso_speed(k4a_image_t image_handle); + +/** Set the device time stamp, in microseconds, of the image. + * + * \param image_handle + * Handle of the image to set the timestamp on. + * + * \param timestamp_usec + * Device timestamp of the image in microseconds. + * + * \remarks + * Use this function in conjunction with k4a_image_create() or k4a_image_create_from_buffer() to construct a + * \ref k4a_image_t. + * + * \remarks + * The device timestamp represents the mid-point of exposure of the image, as captured by the hardware. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT void k4a_image_set_device_timestamp_usec(k4a_image_t image_handle, uint64_t timestamp_usec); + +/** Set the device time stamp, in microseconds, of the image. + * + * \param image_handle + * Handle of the image to set the timestamp on. + * + * \param timestamp_usec + * Device timestamp of the image in microseconds. + * + * \remarks + * Use this function in conjunction with k4a_image_create() or k4a_image_create_from_buffer() to construct a + * \ref k4a_image_t. + * + * \remarks + * The device timestamp represents the mid-point of exposure of the image, as captured by the hardware. + * + * \relates k4a_image_t + * + * \deprecated + * Deprecated starting in 1.2.0. Please use k4a_image_set_device_timestamp_usec(). + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_DEPRECATED_EXPORT void k4a_image_set_timestamp_usec(k4a_image_t image_handle, uint64_t timestamp_usec); + +/** Set the system time stamp, in nanoseconds, of the image. + * + * \param image_handle + * Handle of the image to set the timestamp on. + * + * \param timestamp_nsec + * Timestamp of the image in nanoseconds. + * + * \remarks + * Use this function in conjunction with k4a_image_create() or k4a_image_create_from_buffer() to construct a + * \ref k4a_image_t. + * + * \remarks + * The system timestamp is a high performance and increasing clock (from boot). The timestamp represents the time + * immediately after the image buffer was read by the host PC. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT void k4a_image_set_system_timestamp_nsec(k4a_image_t image_handle, uint64_t timestamp_nsec); + +/** Set the exposure time, in microseconds, of the image. + * + * \param image_handle + * Handle of the image to set the exposure time on. + * + * \param exposure_usec + * Exposure time of the image in microseconds. + * + * \remarks + * Use this function in conjunction with k4a_image_create() or k4a_image_create_from_buffer() to construct a + * \ref k4a_image_t. An exposure time of 0 is considered invalid. Only color image formats are expected to have a valid + * exposure time. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT void k4a_image_set_exposure_usec(k4a_image_t image_handle, uint64_t exposure_usec); + +/** Set the exposure time, in microseconds, of the image. + * + * \param image_handle + * Handle of the image to set the exposure time on. + * + * \param exposure_usec + * Exposure time of the image in microseconds. + * + * \remarks + * Use this function in conjunction with k4a_image_create() or k4a_image_create_from_buffer() to construct a + * \ref k4a_image_t. An exposure time of 0 is considered invalid. Only color image formats are expected to have a valid + * exposure time. + * + * \deprecated + * Deprecated starting in 1.2.0. Please use k4a_image_set_exposure_usec(). + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_DEPRECATED_EXPORT void k4a_image_set_exposure_time_usec(k4a_image_t image_handle, uint64_t exposure_usec); + +/** Set the white balance of the image. + * + * \param image_handle + * Handle of the image to set the white balance on. + * + * \param white_balance + * White balance of the image in degrees Kelvin. + * + * \remarks + * Use this function in conjunction with k4a_image_create() or k4a_image_create_from_buffer() to construct a + * \ref k4a_image_t. A white balance of 0 is considered invalid. White balance is only meaningful for color images, + * and not expected on depth or IR images. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT void k4a_image_set_white_balance(k4a_image_t image_handle, uint32_t white_balance); + +/** Set the ISO speed of the image. + * + * \param image_handle + * Handle of the image to set the ISO speed on. + * + * \param iso_speed + * ISO speed of the image. + * + * \remarks + * Use this function in conjunction with k4a_image_create() or k4a_image_create_from_buffer() to construct a + * \ref k4a_image_t. An ISO speed of 0 is considered invalid. Only color images are expected to have a valid ISO speed. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT void k4a_image_set_iso_speed(k4a_image_t image_handle, uint32_t iso_speed); + +/** Add a reference to the k4a_image_t. + * + * \param image_handle + * Handle of the image for which the get operation is performed on. + * + * \remarks + * References manage the lifetime of the object. When the references reach zero the object is destroyed. A caller must + * not access the object after its reference is released. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT void k4a_image_reference(k4a_image_t image_handle); + +/** Remove a reference from the k4a_image_t. + * + * \param image_handle + * Handle of the image for which the get operation is performed on. + * + * \remarks + * References manage the lifetime of the object. When the references reach zero the object is destroyed. A caller must + * not access the object after its reference is released. + * + * \relates k4a_image_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT void k4a_image_release(k4a_image_t image_handle); + +/** Starts color and depth camera capture. + * + * \param device_handle + * Handle obtained by k4a_device_open(). + * + * \param config + * The configuration we want to run the device in. This can be initialized with ::K4A_DEVICE_CONFIG_INIT_DISABLE_ALL. + * + * \returns + * ::K4A_RESULT_SUCCEEDED is returned on success. + * + * \relates k4a_device_t + * + * \remarks + * Individual sensors configured to run will now start to stream captured data. + * + * \remarks + * It is not valid to call k4a_device_start_cameras() a second time on the same \ref k4a_device_t until + * k4a_device_stop_cameras() has been called. + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_device_start_cameras(k4a_device_t device_handle, const k4a_device_configuration_t *config); + +/** Stops the color and depth camera capture. + * + * \param device_handle + * Handle obtained by k4a_device_open(). + * + * \relates k4a_device_t + * + * \remarks + * The streaming of individual sensors stops as a result of this call. Once called, k4a_device_start_cameras() may + * be called again to resume sensor streaming. + * + * \remarks + * This function may be called while another thread is blocking in k4a_device_get_capture(). + * Calling this function while another thread is in that function will result in that function returning a failure. + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT void k4a_device_stop_cameras(k4a_device_t device_handle); + +/** Starts the IMU sample stream. + * + * \param device_handle + * Handle obtained by k4a_device_open(). + * + * \returns + * ::K4A_RESULT_SUCCEEDED is returned on success. ::K4A_RESULT_FAILED if the sensor is already running or a failure is + * encountered + * + * \relates k4a_device_t + * + * \remarks + * Call this API to start streaming IMU data. It is not valid to call this function a second time on the same + * \ref k4a_device_t until k4a_device_stop_imu() has been called. + * + * \remarks + * This function is dependent on the state of the cameras. The color or depth camera must be started before the IMU. + * ::K4A_RESULT_FAILED will be returned if one of the cameras is not running. + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_device_start_imu(k4a_device_t device_handle); + +/** Stops the IMU capture. + * + * \param device_handle + * Handle obtained by k4a_device_open(). + * + * \relates k4a_device_t + * + * \remarks + * The streaming of the IMU stops as a result of this call. Once called, k4a_device_start_imu() may + * be called again to resume sensor streaming, so long as the cameras are running. + * + * \remarks + * This function may be called while another thread is blocking in k4a_device_get_imu_sample(). + * Calling this function while another thread is in that function will result in that function returning a failure. + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT void k4a_device_stop_imu(k4a_device_t device_handle); + +/** Get the Azure Kinect device serial number. + * + * \param device_handle + * Handle obtained by k4a_device_open(). + * + * \param serial_number + * Location to write the serial number to. If the function returns ::K4A_BUFFER_RESULT_SUCCEEDED, this will be a NULL + * terminated string of ASCII characters. If this input is NULL \p serial_number_size will still be updated to return + * the size of the buffer needed to store the string. + * + * \param serial_number_size + * On input, the size of the \p serial_number buffer if that pointer is not NULL. On output, this value is set to the + * actual number of bytes in the serial number (including the null terminator). + * + * \returns + * A return of ::K4A_BUFFER_RESULT_SUCCEEDED means that the \p serial_number has been filled in. If the buffer is too + * small the function returns ::K4A_BUFFER_RESULT_TOO_SMALL and the size of the serial number is + * returned in the \p serial_number_size parameter. All other failures return ::K4A_BUFFER_RESULT_FAILED. + * + * \relates k4a_device_t + * + * \remarks + * Queries the device for its serial number. If the caller needs to know the size of the serial number to allocate + * memory, the function should be called once with a NULL \p serial_number to get the needed size in the \p + * serial_number_size output, and then again with the allocated buffer. + * + * \remarks + * Only a complete serial number will be returned. If the caller's buffer is too small, the function will return + * ::K4A_BUFFER_RESULT_TOO_SMALL without returning any data in \p serial_number. + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_buffer_result_t k4a_device_get_serialnum(k4a_device_t device_handle, + char *serial_number, + size_t *serial_number_size); + +/** Get the version numbers of the device's subsystems. + * + * \param device_handle + * Handle obtained by k4a_device_open(). + * + * \param version + * Location to write the version info to. + * + * \returns A return of ::K4A_RESULT_SUCCEEDED means that the version structure has been filled in. + * All other failures return ::K4A_RESULT_FAILED. + * + * \relates k4a_device_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_device_get_version(k4a_device_t device_handle, k4a_hardware_version_t *version); + +/** Get the Azure Kinect color sensor control capabilities. + * + * \param device_handle + * Handle obtained by k4a_device_open(). + * + * \param command + * Color sensor control command. + * + * \param supports_auto + * Location to store whether the color sensor's control support auto mode or not. + * true if it supports auto mode, otherwise false. + * + * \param min_value + * Location to store the color sensor's control minimum value of /p command. + * + * \param max_value + * Location to store the color sensor's control maximum value of /p command. + * + * \param step_value + * Location to store the color sensor's control step value of /p command. + * + * \param default_value + * Location to store the color sensor's control default value of /p command. + * + * \param default_mode + * Location to store the color sensor's control default mode of /p command. + * + * \returns + * ::K4A_RESULT_SUCCEEDED if the value was successfully returned, ::K4A_RESULT_FAILED if an error occurred + * + * \relates k4a_device_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_device_get_color_control_capabilities(k4a_device_t device_handle, + k4a_color_control_command_t command, + bool *supports_auto, + int32_t *min_value, + int32_t *max_value, + int32_t *step_value, + int32_t *default_value, + k4a_color_control_mode_t *default_mode); + +/** Get the Azure Kinect color sensor control + * value. + * + * \param device_handle + * Handle obtained by k4a_device_open(). + * + * \param command + * Color sensor control command. + * + * \param mode + * Location to store the color sensor's control mode. This mode represents whether the command is in automatic or + * manual mode. + * + * \param value + * Location to store the color sensor's control value. This value is always written, but is only valid when the \p + * mode returned is ::K4A_COLOR_CONTROL_MODE_MANUAL for the current \p command. + * + * \returns + * ::K4A_RESULT_SUCCEEDED if the value was successfully returned, ::K4A_RESULT_FAILED if an error occurred + * + * \remarks + * Each control command may be set to manual or automatic. See the definition of \ref k4a_color_control_command_t on + * how to interpret the \p value for each command. + * + * \remarks + * Some control commands are only supported in manual mode. When a command is in automatic mode, the \p value for + * that command is not valid. + * + * \remarks + * Control values set on a device are reset only when the device is power cycled. The device will retain the + * settings even if the \ref k4a_device_t is closed or the application is restarted. + * + * \relates k4a_device_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_device_get_color_control(k4a_device_t device_handle, + k4a_color_control_command_t command, + k4a_color_control_mode_t *mode, + int32_t *value); + +/** Set the Azure Kinect color sensor control value. + * + * \param device_handle + * Handle obtained by k4a_device_open(). + * + * \param command + * Color sensor control command. + * + * \param mode + * Color sensor control mode to set. This mode represents whether the command is in automatic or manual mode. + * + * \param value + * Value to set the color sensor's control to. The value is only valid if \p mode + * is set to ::K4A_COLOR_CONTROL_MODE_MANUAL, and is otherwise ignored. + * + * \returns + * ::K4A_RESULT_SUCCEEDED if the value was successfully set, ::K4A_RESULT_FAILED if an error occurred + * + * \remarks + * Each control command may be set to manual or automatic. See the definition of \ref k4a_color_control_command_t on how + * to interpret the \p value for each command. + * + * \remarks + * Some control commands are only supported in manual mode. When a command is in automatic mode, the \p value for that + * command is not valid. + * + * \remarks + * Control values set on a device are reset only when the device is power cycled. The device will retain the settings + * even if the \ref k4a_device_t is closed or the application is restarted. + * + * \relates k4a_device_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_device_set_color_control(k4a_device_t device_handle, + k4a_color_control_command_t command, + k4a_color_control_mode_t mode, + int32_t value); + +/** Get the raw calibration blob for the entire Azure Kinect device. + * + * \param device_handle + * Handle obtained by k4a_device_open(). + * + * \param data + * Location to write the calibration data to. This field may optionally be set to NULL for the caller to query for + * the needed data size. + * + * \param data_size + * On passing \p data_size into the function this variable represents the available size of the \p data + * buffer. On return this variable is updated with the amount of data actually written to the buffer, or the size + * required to store the calibration buffer if \p data is NULL. + * + * \returns + * ::K4A_BUFFER_RESULT_SUCCEEDED if \p data was successfully written. If \p data_size points to a buffer size that is + * too small to hold the output or \p data is NULL, ::K4A_BUFFER_RESULT_TOO_SMALL is returned and \p data_size is + * updated to contain the minimum buffer size needed to capture the calibration data. + * + * \relates k4a_device_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_buffer_result_t k4a_device_get_raw_calibration(k4a_device_t device_handle, + uint8_t *data, + size_t *data_size); + +/** Get the camera calibration for the entire Azure Kinect device. + * + * \param device_handle + * Handle obtained by k4a_device_open(). + * + * \param depth_mode + * Mode in which depth camera is operated. + * + * \param color_resolution + * Resolution in which color camera is operated. + * + * \param calibration + * Location to write the calibration + * + * \returns + * ::K4A_RESULT_SUCCEEDED if \p calibration was successfully written. ::K4A_RESULT_FAILED otherwise. + * + * \remarks + * The \p calibration represents the data needed to transform between the camera views and may be + * different for each operating \p depth_mode and \p color_resolution the device is configured to operate in. + * + * \remarks + * The \p calibration output is used as input to all calibration and transformation functions. + * + * \see k4a_calibration_2d_to_2d() + * \see k4a_calibration_2d_to_3d() + * \see k4a_calibration_3d_to_2d() + * \see k4a_calibration_3d_to_3d() + * + * \relates k4a_device_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_device_get_calibration(k4a_device_t device_handle, + const k4a_depth_mode_t depth_mode, + const k4a_color_resolution_t color_resolution, + k4a_calibration_t *calibration); + +/** Get the device jack status for the synchronization in and synchronization out connectors. + * + * \param device_handle + * Handle obtained by k4a_device_open(). + * + * \param sync_in_jack_connected + * Upon successful return this value will be set to true if a cable is connected to this sync in jack. + * + * \param sync_out_jack_connected + * Upon successful return this value will be set to true if a cable is connected to this sync out jack. + * + * \returns + * ::K4A_RESULT_SUCCEEDED if the connector status was successfully read. + * + * \relates k4a_device_t + * + * \remarks + * If \p sync_out_jack_connected is true then \ref k4a_device_configuration_t wired_sync_mode mode can be set to \ref + * K4A_WIRED_SYNC_MODE_STANDALONE or \ref K4A_WIRED_SYNC_MODE_MASTER. If \p sync_in_jack_connected is true then \ref + * k4a_device_configuration_t wired_sync_mode mode can be set to \ref K4A_WIRED_SYNC_MODE_STANDALONE or \ref + * K4A_WIRED_SYNC_MODE_SUBORDINATE. + * + * \see k4a_device_start_cameras() + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_device_get_sync_jack(k4a_device_t device_handle, + bool *sync_in_jack_connected, + bool *sync_out_jack_connected); + +/** Get the camera calibration for a device from a raw calibration blob. + * + * \param raw_calibration + * Raw calibration blob obtained from a device or recording. The raw calibration must be NULL terminated. + * + * \param raw_calibration_size + * The size, in bytes, of raw_calibration including the NULL termination. + * + * \param depth_mode + * Mode in which depth camera is operated. + * + * \param color_resolution + * Resolution in which color camera is operated. + * + * \param calibration + * Location to write the calibration. + * + * \returns + * ::K4A_RESULT_SUCCEEDED if \p calibration was successfully written. ::K4A_RESULT_FAILED otherwise. + * + * \remarks + * The \p calibration represents the data needed to transform between the camera views and is + * different for each operating \p depth_mode and \p color_resolution the device is configured to operate in. + * + * \remarks + * The \p calibration output is used as input to all transformation functions. + * + * \see k4a_calibration_2d_to_2d() + * \see k4a_calibration_2d_to_3d() + * \see k4a_calibration_3d_to_2d() + * \see k4a_calibration_3d_to_3d() + * + * \relates k4a_device_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_calibration_get_from_raw(char *raw_calibration, + size_t raw_calibration_size, + const k4a_depth_mode_t depth_mode, + const k4a_color_resolution_t color_resolution, + k4a_calibration_t *calibration); + +/** Transform a 3D point of a source coordinate system into a 3D point of the target coordinate system + * + * \param calibration + * Location to read the camera calibration data. + * + * \param source_point3d_mm + * The 3D coordinates in millimeters representing a point in \p source_camera. + * + * \param source_camera + * The current camera. + * + * \param target_camera + * The target camera. + * + * \param target_point3d_mm + * Pointer to the output where the new 3D coordinates of the input point in the coordinate space of \p target_camera is + * stored in millimeters. + * + * \returns + * ::K4A_RESULT_SUCCEEDED if \p target_point3d_mm was successfully written. ::K4A_RESULT_FAILED if \p calibration + * contained invalid transformation parameters. + * + * \remarks + * This function is used to transform 3D points between depth and color camera coordinate systems. The function uses the + * extrinsic camera calibration. It computes the output via multiplication with a precomputed matrix encoding a 3D + * rotation and a 3D translation. If \p source_camera and \p target_camera are the same, then \p target_point3d_mm will + * be identical to \p source_point3d_mm. + * + * \relates k4a_calibration_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_calibration_3d_to_3d(const k4a_calibration_t *calibration, + const k4a_float3_t *source_point3d_mm, + const k4a_calibration_type_t source_camera, + const k4a_calibration_type_t target_camera, + k4a_float3_t *target_point3d_mm); + +/** Transform a 2D pixel coordinate with an associated depth value of the source camera into a 3D point of the target + * coordinate system. + * + * \param calibration + * Location to read the camera calibration obtained by k4a_device_get_calibration(). + * + * \param source_point2d + * The 2D pixel in \p source_camera coordinates. + * + * \param source_depth_mm + * The depth of \p source_point2d in millimeters. One way to derive the depth value in the color camera geometry is to + * use the function k4a_transformation_depth_image_to_color_camera(). + * + * \param source_camera + * The current camera. + * + * \param target_camera + * The target camera. + * + * \param target_point3d_mm + * Pointer to the output where the 3D coordinates of the input pixel in the coordinate system of \p target_camera is + * stored in millimeters. + * + * \param valid + * The output parameter returns a value of 1 if the \p source_point2d is a valid coordinate, and will return 0 if + * the coordinate is not valid in the calibration model. + * + * \returns + * ::K4A_RESULT_SUCCEEDED if \p target_point3d_mm was successfully written. ::K4A_RESULT_FAILED if \p calibration + * contained invalid transformation parameters. If the function returns ::K4A_RESULT_SUCCEEDED, but \p valid is 0, + * the transformation was computed, but the results in \p target_point3d_mm are outside of the range of valid + * calibration and should be ignored. + * + * \remarks + * This function applies the intrinsic calibration of \p source_camera to compute the 3D ray from the focal point of the + * camera through pixel \p source_point2d. The 3D point on this ray is then found using \p source_depth_mm. If \p + * target_camera is different from \p source_camera, the 3D point is transformed to \p target_camera using + * k4a_calibration_3d_to_3d(). In practice, \p source_camera and \p target_camera will often be identical. In this + * case, no 3D to 3D transformation is applied. + * + * \remarks + * If \p source_point2d is not considered as valid pixel coordinate + * according to the intrinsic camera model, \p valid is set to 0. If it is valid, \p valid will be set to 1. The user + * should not use the value of \p target_point3d_mm if \p valid was set to 0. + * + * \relates k4a_calibration_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_calibration_2d_to_3d(const k4a_calibration_t *calibration, + const k4a_float2_t *source_point2d, + const float source_depth_mm, + const k4a_calibration_type_t source_camera, + const k4a_calibration_type_t target_camera, + k4a_float3_t *target_point3d_mm, + int *valid); + +/** Transform a 3D point of a source coordinate system into a 2D pixel coordinate of the target camera. + * + * \param calibration + * Location to read the camera calibration obtained by k4a_device_get_calibration(). + * + * \param source_point3d_mm + * The 3D coordinates in millimeters representing a point in \p source_camera + * + * \param source_camera + * The current camera. + * + * \param target_camera + * The target camera. + * + * \param target_point2d + * Pointer to the output where the 2D pixel in \p target_camera coordinates is stored. + * + * \param valid + * The output parameter returns a value of 1 if the \p source_point3d_mm is a valid coordinate in the \p target_camera + * coordinate system, and will return 0 if the coordinate is not valid in the calibration model. + * + * \returns + * ::K4A_RESULT_SUCCEEDED if \p target_point2d was successfully written. ::K4A_RESULT_FAILED if \p calibration + * contained invalid transformation parameters. If the function returns ::K4A_RESULT_SUCCEEDED, but \p valid is 0, + * the transformation was computed, but the results in \p target_point2d are outside of the range of valid calibration + * and should be ignored. + * + * \remarks + * If \p target_camera is different from \p source_camera, \p source_point3d_mm is transformed to \p target_camera using + * k4a_calibration_3d_to_3d(). In practice, \p source_camera and \p target_camera will often be identical. In this + * case, no 3D to 3D transformation is applied. The 3D point in the coordinate system of \p target_camera is then + * projected onto the image plane using the intrinsic calibration of \p target_camera. + * + * \remarks + * If \p source_point3d_mm does not map to a valid 2D coordinate in the \p target_camera coordinate system, \p valid is + * set to 0. If it is valid, \p valid will be set to 1. The user should not use the value of \p target_point2d if \p + * valid was set to 0. + * + * \relates k4a_calibration_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_calibration_3d_to_2d(const k4a_calibration_t *calibration, + const k4a_float3_t *source_point3d_mm, + const k4a_calibration_type_t source_camera, + const k4a_calibration_type_t target_camera, + k4a_float2_t *target_point2d, + int *valid); + +/** Transform a 2D pixel coordinate with an associated depth value of the source camera into a 2D pixel coordinate of + * the target camera. + * + * \param calibration + * Location to read the camera calibration obtained by k4a_device_get_calibration(). + * + * \param source_point2d + * The 2D pixel in \p source_camera coordinates. + * + * \param source_depth_mm + * The depth of \p source_point2d in millimeters. One way to derive the depth value in the color camera geometry is to + * use the function k4a_transformation_depth_image_to_color_camera(). + * + * \param source_camera + * The current camera. + * + * \param target_camera + * The target camera. + * + * \param target_point2d + * The 2D pixel in \p target_camera coordinates. + * + * \param valid + * The output parameter returns a value of 1 if the \p source_point2d is a valid coordinate in the \p target_camera + * coordinate system, and will return 0 if the coordinate is not valid in the calibration model. + * + * \returns + * ::K4A_RESULT_SUCCEEDED if \p target_point2d was successfully written. ::K4A_RESULT_FAILED if \p calibration + * contained invalid transformation parameters. If the function returns ::K4A_RESULT_SUCCEEDED, but \p valid is 0, + * the transformation was computed, but the results in \p target_point2d are outside of the range of valid calibration + * and should be ignored. + * + * \remarks + * This function maps a pixel between the coordinate systems of the depth and color cameras. It is equivalent to calling + * k4a_calibration_2d_to_3d() to compute the 3D point corresponding to \p source_point2d and then using + * k4a_calibration_3d_to_2d() to map the 3D point into the coordinate system of the \p target_camera. + * + * \remarks + * If \p source_camera and \p target_camera are identical, the function immediately sets \p target_point2d to \p + * source_point2d and returns without computing any transformations. + * + * \remarks + * If \p source_point2d does not map to a valid 2D coordinate in the \p target_camera coordinate system, \p valid is set + * to 0. If it is valid, \p valid will be set to 1. The user should not use the value of \p target_point2d if \p valid + * was set to 0. + * + * \relates k4a_calibration_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_calibration_2d_to_2d(const k4a_calibration_t *calibration, + const k4a_float2_t *source_point2d, + const float source_depth_mm, + const k4a_calibration_type_t source_camera, + const k4a_calibration_type_t target_camera, + k4a_float2_t *target_point2d, + int *valid); + +/** Transform a 2D pixel coordinate from color camera into a 2D pixel coordinate of + * the depth camera. + * + * \param calibration + * Location to read the camera calibration obtained by k4a_device_get_calibration(). + * + * \param source_point2d + * The 2D pixel in \p color camera coordinates. + * + * \param depth_image + * Handle to input depth image. + * + * \param target_point2d + * The 2D pixel in \p depth camera coordinates. + * + * \param valid + * The output parameter returns a value of 1 if the \p source_point2d is a valid coordinate in the \p target_camera + * coordinate system, and will return 0 if the coordinate is not valid in the calibration model. + * + * \returns + * ::K4A_RESULT_SUCCEEDED if \p target_point2d was successfully written. ::K4A_RESULT_FAILED if \p calibration + * contained invalid transformation parameters. If the function returns ::K4A_RESULT_SUCCEEDED, but \p valid is 0, + * the transformation was computed, but the results in \p target_point2d are outside of the range of valid calibration + * and should be ignored. + * + * \remarks + * This function represents an alternative to k4a_calibration_2d_to_2d() if the number of pixels that need to be + * transformed is small. This function searches along an epipolar line in the depth image to find the corresponding + * depth pixel. If a larger number of pixels need to be transformed, it might be computationally cheaper to call + * k4a_transformation_depth_image_to_color_camera() to get correspondence depth values for these color pixels, then call + * the function k4a_calibration_2d_to_2d(). + * + * \remarks + * If \p source_point2d does not map to a valid 2D coordinate in the \p target_camera coordinate system, \p valid is set + * to 0. If it is valid, \p valid will be set to 1. The user should not use the value of \p target_point2d if \p valid + * was set to 0. + * + * \relates k4a_calibration_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_calibration_color_2d_to_depth_2d(const k4a_calibration_t *calibration, + const k4a_float2_t *source_point2d, + const k4a_image_t depth_image, + k4a_float2_t *target_point2d, + int *valid); + +/** Get handle to transformation handle. + * + * \param calibration + * A calibration structure obtained by k4a_device_get_calibration(). + * + * \returns + * A transformation handle. A NULL is returned if creation fails. + * + * \remarks + * The transformation handle is used to transform images from the coordinate system of one camera into the other. Each + * transformation handle requires some pre-computed resources to be allocated, which are retained until the handle is + * destroyed. + * + * \remarks + * The transformation handle must be destroyed with k4a_transformation_destroy() when it is no longer to be used. + * + * \relates k4a_calibration_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_transformation_t k4a_transformation_create(const k4a_calibration_t *calibration); + +/** Destroy transformation handle. + * + * \param transformation_handle + * Transformation handle to destroy. + * + * \relates k4a_transformation_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT void k4a_transformation_destroy(k4a_transformation_t transformation_handle); + +/** Transforms the depth map into the geometry of the color camera. + * + * \param transformation_handle + * Transformation handle. + * + * \param depth_image + * Handle to input depth image. + * + * \param transformed_depth_image + * Handle to output transformed depth image. + * + * \remarks + * This produces a depth image for which each pixel matches the corresponding pixel coordinates of the color camera. + * + * \remarks + * \p depth_image and \p transformed_depth_image must be of format ::K4A_IMAGE_FORMAT_DEPTH16. + * + * \remarks + * \p transformed_depth_image must have a width and height matching the width and height of the color camera in the mode + * specified by the \ref k4a_calibration_t used to create the \p transformation_handle with k4a_transformation_create(). + * + * \remarks + * The contents \p transformed_depth_image will be filled with the depth values derived from \p depth_image in the color + * camera's coordinate space. + * + * \remarks + * \p transformed_depth_image should be created by the caller using k4a_image_create() or + * k4a_image_create_from_buffer(). + * + * \returns + * ::K4A_RESULT_SUCCEEDED if \p transformed_depth_image was successfully written and ::K4A_RESULT_FAILED otherwise. + * + * \relates k4a_transformation_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_transformation_depth_image_to_color_camera(k4a_transformation_t transformation_handle, + const k4a_image_t depth_image, + k4a_image_t transformed_depth_image); + +/** Transforms depth map and a custom image into the geometry of the color camera. + * + * \param transformation_handle + * Transformation handle. + * + * \param depth_image + * Handle to input depth image. + * + * \param custom_image + * Handle to input custom image. + * + * \param transformed_depth_image + * Handle to output transformed depth image. + * + * \param transformed_custom_image + * Handle to output transformed custom image. + * + * \param interpolation_type + * Parameter that controls how pixels in \p custom_image should be interpolated when transformed to color camera space. + * K4A_TRANSFORMATION_INTERPOLATION_TYPE_LINEAR if linear interpolation should be used. + * K4A_TRANSFORMATION_INTERPOLATION_TYPE_NEAREST if nearest neighbor interpolation should be used. + * + * \param invalid_custom_value + * Defines the custom image pixel value that should be written to \p transformed_custom_image in case the corresponding + * depth pixel can not be transformed into the color camera space. + * + * \remarks + * This produces a depth image and a corresponding custom image for which each pixel matches the corresponding + * pixel coordinates of the color camera. + * + * \remarks + * \p depth_image and \p transformed_depth_image must be of format ::K4A_IMAGE_FORMAT_DEPTH16. + * + * \remarks + * \p custom_image and \p transformed_custom_image must be of format ::K4A_IMAGE_FORMAT_CUSTOM8 or + * ::K4A_IMAGE_FORMAT_CUSTOM16. + * + * \remarks + * \p transformed_depth_image and \p transformed_custom_image must have a width and height matching the width and + * height of the color camera in the mode specified by the \ref k4a_calibration_t used to create the + * \p transformation_handle with k4a_transformation_create(). + * + * \remarks + * \p custom_image must have a width and height matching the width and height of \p depth_image. + * + * \remarks + * The contents \p transformed_depth_image will be filled with the depth values derived from \p depth_image in the color + * camera's coordinate space. + * + * \remarks + * The contents \p transformed_custom_image will be filled with the values derived from \p custom_image in the color + * camera's coordinate space. + * + * \remarks + * \p transformed_depth_image and \p transformed_custom_image should be created by the caller using k4a_image_create() + * or k4a_image_create_from_buffer(). + * + * \remarks + * Using linear interpolation could create new values to \p transformed_custom_image which do no exist in \p + * custom_image. Setting \p use_linear_interpolation to false will prevent this from happenning but will result in less + * smooth image. + * + * \returns + * ::K4A_RESULT_SUCCEEDED if \p transformed_depth_image and \p transformed_custom_image were successfully written and + * ::K4A_RESULT_FAILED otherwise. + * + * \relates k4a_transformation_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t +k4a_transformation_depth_image_to_color_camera_custom(k4a_transformation_t transformation_handle, + const k4a_image_t depth_image, + const k4a_image_t custom_image, + k4a_image_t transformed_depth_image, + k4a_image_t transformed_custom_image, + k4a_transformation_interpolation_type_t interpolation_type, + uint32_t invalid_custom_value); + +/** Transforms a color image into the geometry of the depth camera. + * + * \param transformation_handle + * Transformation handle. + * + * \param depth_image + * Handle to input depth image. + * + * \param color_image + * Handle to input color image. + * + * \param transformed_color_image + * Handle to output transformed color image. + * + * \remarks + * This produces a color image for which each pixel matches the corresponding pixel coordinates of the depth camera. + * + * \remarks + * \p depth_image and \p color_image need to represent the same moment in time. The depth data will be applied to the + * color image to properly warp the color data to the perspective of the depth camera. + * + * \remarks + * \p depth_image must be of type ::K4A_IMAGE_FORMAT_DEPTH16. \p color_image must be of format + * ::K4A_IMAGE_FORMAT_COLOR_BGRA32. + * + * \remarks + * \p transformed_color_image image must be of format ::K4A_IMAGE_FORMAT_COLOR_BGRA32. \p transformed_color_image must + * have the width and height of the depth camera in the mode specified by the \ref k4a_calibration_t used to create + * the \p transformation_handle with k4a_transformation_create(). + * + * \remarks + * \p transformed_color_image should be created by the caller using k4a_image_create() or + * k4a_image_create_from_buffer(). + * + * \returns + * ::K4A_RESULT_SUCCEEDED if \p transformed_color_image was successfully written and ::K4A_RESULT_FAILED otherwise. + * + * \relates k4a_transformation_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_transformation_color_image_to_depth_camera(k4a_transformation_t transformation_handle, + const k4a_image_t depth_image, + const k4a_image_t color_image, + k4a_image_t transformed_color_image); + +/** Transforms the depth image into 3 planar images representing X, Y and Z-coordinates of corresponding 3D points. + * + * \param transformation_handle + * Transformation handle. + * + * \param depth_image + * Handle to input depth image. + * + * \param camera + * Geometry in which depth map was computed. + * + * \param xyz_image + * Handle to output xyz image. + * + * \remarks + * \p depth_image must be of format ::K4A_IMAGE_FORMAT_DEPTH16. + * + * \remarks + * The \p camera parameter tells the function what the perspective of the \p depth_image is. If the \p depth_image was + * captured directly from the depth camera, the value should be ::K4A_CALIBRATION_TYPE_DEPTH. If the \p depth_image is + * the result of a transformation into the color camera's coordinate space using + * k4a_transformation_depth_image_to_color_camera(), the value should be ::K4A_CALIBRATION_TYPE_COLOR. + * + * \remarks + * The format of \p xyz_image must be ::K4A_IMAGE_FORMAT_CUSTOM. The width and height of \p xyz_image must match the + * width and height of \p depth_image. \p xyz_image must have a stride in bytes of at least 6 times its width in pixels. + * + * \remarks + * Each pixel of the \p xyz_image consists of three int16_t values, totaling 6 bytes. The three int16_t values are the + * X, Y, and Z values of the point. + * + * \remarks + * \p xyz_image should be created by the caller using k4a_image_create() or k4a_image_create_from_buffer(). + * + * \returns + * ::K4A_RESULT_SUCCEEDED if \p xyz_image was successfully written and ::K4A_RESULT_FAILED otherwise. + * + * \relates k4a_transformation_t + * + * \xmlonly + * + * k4a.h (include k4a/k4a.h) + * k4a.lib + * k4a.dll + * + * \endxmlonly + */ +K4A_EXPORT k4a_result_t k4a_transformation_depth_image_to_point_cloud(k4a_transformation_t transformation_handle, + const k4a_image_t depth_image, + const k4a_calibration_type_t camera, + k4a_image_t xyz_image); + +/** + * @} + */ + +#ifdef __cplusplus +} +#endif + +#endif /* K4A_H */ diff --git a/k4a-sys/vendor/include/windows/k4a/k4a.hpp b/k4a-sys/vendor/include/windows/k4a/k4a.hpp new file mode 100644 index 0000000000..6d9dea3311 --- /dev/null +++ b/k4a-sys/vendor/include/windows/k4a/k4a.hpp @@ -0,0 +1,1441 @@ +/** \file k4a.hpp + * Copyright (c) Microsoft Corporation. All rights reserved. + * Licensed under the MIT License. + * Kinect For Azure SDK - C++ wrapper. + */ + +#ifndef K4A_HPP +#define K4A_HPP + +#include "k4a.h" + +#include +#include +#include +#include +#include +#include +#include + +namespace k4a +{ + +/** + * \defgroup cppsdk C++ Reference + * + * Functions part of the SDK. + * + * @{ + */ + +/** Exception type thrown when a K4A API call fails + */ +class error : public std::runtime_error +{ +public: + using runtime_error::runtime_error; +}; + +// Helper functions not intended for use by client code +// +namespace internal +{ +/// @cond FALSE +/** Casts an arithmetic value, clamping to the supported range of the type being cast to + * + * \returns input represented in output_type + * + * \remarks + * Clamps to 0 for unsigned types + */ +template output_type clamp_cast(input_type input) +{ + static_assert(std::is_arithmetic::value, "clamp_cast only supports arithmetic types"); + static_assert(std::is_arithmetic::value, "clamp_cast only supports arithmetic types"); + const input_type min_value = std::is_signed() ? + static_cast(std::numeric_limits::min()) : + 0; + + input_type max_value = static_cast(std::numeric_limits::max()); + if (max_value < 0) + { + // Output type is of greater or equal size to input type and we've overflowed. + // + max_value = std::numeric_limits::max(); + } + input = std::min(input, max_value); + input = std::max(input, min_value); + return static_cast(input); +} +/// @endcond +} // namespace internal + +/** \class image k4a.hpp + * Wrapper for \ref k4a_image_t + * + * Wraps a handle for an image. Copying/moving is cheap, copies are shallow. + * + * \sa k4a_image_t + */ +class image +{ +public: + /** Creates an image from a k4a_image_t. + * Takes ownership of the handle, i.e. assuming that handle has a refcount + * of 1, you should not call k4a_image_release on the handle after giving + * it to the image; the image will take care of that. + */ + image(k4a_image_t handle = nullptr) noexcept : m_handle(handle) {} + + /** Creates a shallow copy of another image + */ + image(const image &other) noexcept : m_handle(other.m_handle) + { + if (m_handle != nullptr) + { + k4a_image_reference(m_handle); + } + } + + /** Moves another image into a new image + */ + image(image &&other) noexcept : m_handle(other.m_handle) + { + other.m_handle = nullptr; + } + + ~image() + { + reset(); + } + + /** Sets image to a shallow copy of other + */ + image &operator=(const image &other) noexcept + { + if (this != &other) + { + reset(); + m_handle = other.m_handle; + if (m_handle != nullptr) + { + k4a_image_reference(m_handle); + } + } + return *this; + } + + /** Moves another image into this image; other is set to invalid + */ + image &operator=(image &&other) noexcept + { + if (this != &other) + { + reset(); + m_handle = other.m_handle; + other.m_handle = nullptr; + } + return *this; + } + + /** Invalidates this image + */ + image &operator=(std::nullptr_t) noexcept + { + reset(); + return *this; + } + + /** Returns true if two images refer to the same k4a_image_t, false otherwise + */ + bool operator==(const image &other) const noexcept + { + return m_handle == other.m_handle; + } + + /** Returns false if the image is valid, true otherwise + */ + bool operator==(std::nullptr_t) const noexcept + { + return m_handle == nullptr; + } + + /** Returns true if two images wrap different k4a_image_t instances, false otherwise + */ + bool operator!=(const image &other) const noexcept + { + return m_handle != other.m_handle; + } + + /** Returns true if the image is valid, false otherwise + */ + bool operator!=(std::nullptr_t) const noexcept + { + return m_handle != nullptr; + } + + /** Returns true if the image is valid, false otherwise + */ + operator bool() const noexcept + { + return m_handle != nullptr; + } + + /** Returns the underlying k4a_image_t handle + * + * Note that this function does not increment the reference count on the k4a_image_t. + * The caller is responsible for incrementing the reference count on + * the k4a_image_t if the caller needs the k4a_image_t to outlive this C++ object. + * Otherwise, the k4a_image_t will be destroyed by this C++ object. + */ + k4a_image_t handle() const noexcept + { + return m_handle; + } + + /** Releases the underlying k4a_image_t; the image is set to invalid. + */ + void reset() noexcept + { + if (m_handle != nullptr) + { + k4a_image_release(m_handle); + m_handle = nullptr; + } + } + + /** Create a blank image + * Throws error on failure + * + * \sa k4a_image_create + */ + static image create(k4a_image_format_t format, int width_pixels, int height_pixels, int stride_bytes) + { + k4a_image_t handle = nullptr; + k4a_result_t result = k4a_image_create(format, width_pixels, height_pixels, stride_bytes, &handle); + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to create image!"); + } + return image(handle); + } + + /** Create an image from a pre-allocated buffer + * Throws error on failure + * + * \sa k4a_image_create_from_buffer + */ + static image create_from_buffer(k4a_image_format_t format, + int width_pixels, + int height_pixels, + int stride_bytes, + uint8_t *buffer, + size_t buffer_size, + k4a_memory_destroy_cb_t *buffer_release_cb, + void *buffer_release_cb_context) + { + k4a_image_t handle = nullptr; + k4a_result_t result = k4a_image_create_from_buffer(format, + width_pixels, + height_pixels, + stride_bytes, + buffer, + buffer_size, + buffer_release_cb, + buffer_release_cb_context, + &handle); + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to create image from buffer"); + } + return image(handle); + } + + /** Get the image buffer + * + * \sa k4a_image_get_buffer + */ + uint8_t *get_buffer() noexcept + { + return k4a_image_get_buffer(m_handle); + } + + /** Get the image buffer + * + * \sa k4a_image_get_buffer + */ + const uint8_t *get_buffer() const noexcept + { + return k4a_image_get_buffer(m_handle); + } + + /** Get the image buffer size in bytes + * + * \sa k4a_image_get_size + */ + size_t get_size() const noexcept + { + return k4a_image_get_size(m_handle); + } + + /** Get the image format of the image + * + * \sa k4a_image_get_format + */ + k4a_image_format_t get_format() const noexcept + { + return k4a_image_get_format(m_handle); + } + + /** Get the image width in pixels + * + * \sa k4a_image_get_width_pixels + */ + int get_width_pixels() const noexcept + { + return k4a_image_get_width_pixels(m_handle); + } + + /** Get the image height in pixels + * + * \sa k4a_image_get_height_pixels + */ + int get_height_pixels() const noexcept + { + return k4a_image_get_height_pixels(m_handle); + } + + /** Get the image stride in bytes + * + * \sa k4a_image_get_stride_bytes + */ + int get_stride_bytes() const noexcept + { + return k4a_image_get_stride_bytes(m_handle); + } + + /** Get the image's device timestamp in microseconds + * + * \sa k4a_image_get_device_timestamp_usec + */ + std::chrono::microseconds get_device_timestamp() const noexcept + { + return std::chrono::microseconds(k4a_image_get_device_timestamp_usec(m_handle)); + } + + /** Get the image's system timestamp in nanoseconds + * + * \sa k4a_image_get_system_timestamp_nsec + */ + std::chrono::nanoseconds get_system_timestamp() const noexcept + { + return std::chrono::nanoseconds(k4a_image_get_system_timestamp_nsec(m_handle)); + } + + /** Get the image exposure time in microseconds + * + * \sa k4a_image_get_exposure_usec + */ + std::chrono::microseconds get_exposure() const noexcept + { + return std::chrono::microseconds(k4a_image_get_exposure_usec(m_handle)); + } + + /** Get the image white balance in Kelvin (color images only) + * + * \sa k4a_image_get_white_balance + */ + uint32_t get_white_balance() const noexcept + { + return k4a_image_get_white_balance(m_handle); + } + + /** Get the image's ISO speed (color images only) + * + * \sa k4a_image_get_white_balance + */ + uint32_t get_iso_speed() const noexcept + { + return k4a_image_get_iso_speed(m_handle); + } + + /** Set the image's timestamp in microseconds + * + * \sa k4a_image_set_device_timestamp_usec + */ + void set_timestamp(std::chrono::microseconds timestamp) noexcept + { + k4a_image_set_device_timestamp_usec(m_handle, internal::clamp_cast(timestamp.count())); + } + + /** Set the image's exposure time in microseconds (color images only) + * + * \sa k4a_image_set_exposure_time_usec + */ + void set_exposure_time(std::chrono::microseconds exposure) noexcept + { + k4a_image_set_exposure_usec(m_handle, internal::clamp_cast(exposure.count())); + } + + /** Set the white balance of the image (color images only) + * + * \sa k4a_image_set_white_balance + */ + void set_white_balance(uint32_t white_balance) noexcept + { + k4a_image_set_white_balance(m_handle, white_balance); + } + + /** Set the ISO speed of the image (color images only) + * + * \sa k4a_image_set_iso_speed + */ + void set_iso_speed(uint32_t iso_speed) noexcept + { + k4a_image_set_iso_speed(m_handle, iso_speed); + } + +private: + k4a_image_t m_handle; +}; + +/** \class capture k4a.hpp + * Wrapper for \ref k4a_capture_t + * + * Wraps a handle for a capture. Copying/moving is cheap, copies are shallow. + */ +class capture +{ +public: + /** Creates a capture from a k4a_capture_t + * Takes ownership of the handle, i.e. assuming that handle has a refcount + * of 1, you should not call k4a_capture_release on the handle after giving + * it to the capture; the capture will take care of that. + */ + capture(k4a_capture_t handle = nullptr) noexcept : m_handle(handle) {} + + /** Creates a shallow copy of another capture + */ + capture(const capture &other) noexcept : m_handle(other.m_handle) + { + if (m_handle != nullptr) + { + k4a_capture_reference(m_handle); + } + } + + /** Moves another capture into a new capture + */ + capture(capture &&other) noexcept : m_handle(other.m_handle) + { + other.m_handle = nullptr; + } + + ~capture() + { + reset(); + } + + /** Sets capture to a shallow copy of other + */ + capture &operator=(const capture &other) noexcept + { + if (this != &other) + { + reset(); + m_handle = other.m_handle; + if (m_handle != nullptr) + { + k4a_capture_reference(m_handle); + } + } + return *this; + } + + /** Moves another capture into this capture; other is set to invalid + */ + capture &operator=(capture &&other) noexcept + { + if (this != &other) + { + reset(); + m_handle = other.m_handle; + other.m_handle = nullptr; + } + return *this; + } + + /** Invalidates this capture + */ + capture &operator=(std::nullptr_t) noexcept + { + reset(); + return *this; + } + + /** Returns true if two captures refer to the same k4a_capture_t, false otherwise + */ + bool operator==(const capture &other) const noexcept + { + return m_handle == other.m_handle; + } + + /** Returns false if the capture is valid, true otherwise + */ + bool operator==(std::nullptr_t) const noexcept + { + return m_handle == nullptr; + } + + /** Returns true if two captures wrap different k4a_capture_t instances, false otherwise + */ + bool operator!=(const capture &other) const noexcept + { + return m_handle != other.m_handle; + } + + /** Returns true if the capture is valid, false otherwise + */ + bool operator!=(std::nullptr_t) const noexcept + { + return m_handle != nullptr; + } + + /** Returns true if the capture is valid, false otherwise + */ + operator bool() const noexcept + { + return m_handle != nullptr; + } + + /** Returns the underlying k4a_capture_t handle + * + * Note that this function does not increment the reference count on the k4a_capture_t. + * The caller is responsible for incrementing the reference count on + * the k4a_capture_t if the caller needs the k4a_capture_t to outlive this C++ object. + * Otherwise, the k4a_capture_t will be destroyed by this C++ object. + */ + k4a_capture_t handle() const noexcept + { + return m_handle; + } + + /** Releases the underlying k4a_capture_t; the capture is set to invalid. + */ + void reset() noexcept + { + if (m_handle != nullptr) + { + k4a_capture_release(m_handle); + m_handle = nullptr; + } + } + + /** Get the color image associated with the capture + * + * \sa k4a_capture_get_color_image + */ + image get_color_image() const noexcept + { + return image(k4a_capture_get_color_image(m_handle)); + } + + /** Get the depth image associated with the capture + * + * \sa k4a_capture_get_depth_image + */ + image get_depth_image() const noexcept + { + return image(k4a_capture_get_depth_image(m_handle)); + } + + /** Get the IR image associated with the capture + * + * \sa k4a_capture_get_ir_image + */ + image get_ir_image() const noexcept + { + return image(k4a_capture_get_ir_image(m_handle)); + } + + /** Set / add a color image to the capture + * + * \sa k4a_capture_set_color_image + */ + void set_color_image(const image &color_image) noexcept + { + k4a_capture_set_color_image(m_handle, color_image.handle()); + } + + /** Set / add a depth image to the capture + * + * \sa k4a_capture_set_depth_image + */ + void set_depth_image(const image &depth_image) noexcept + { + k4a_capture_set_depth_image(m_handle, depth_image.handle()); + } + + /** Set / add an IR image to the capture + * + * \sa k4a_capture_set_ir_image + */ + void set_ir_image(const image &ir_image) noexcept + { + k4a_capture_set_ir_image(m_handle, ir_image.handle()); + } + + /** Set the temperature associated with the capture in Celsius. + * + * \sa k4a_capture_set_temperature_c + */ + void set_temperature_c(float temperature_c) noexcept + { + k4a_capture_set_temperature_c(m_handle, temperature_c); + } + + /** Get temperature (in Celsius) associated with the capture. + * + * \sa k4a_capture_get_temperature_c + */ + float get_temperature_c() const noexcept + { + return k4a_capture_get_temperature_c(m_handle); + } + + /** Create an empty capture object. + * Throws error on failure. + * + * \sa k4a_capture_create + */ + static capture create() + { + k4a_capture_t handle = nullptr; + k4a_result_t result = k4a_capture_create(&handle); + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to create capture!"); + } + return capture(handle); + } + +private: + k4a_capture_t m_handle; +}; + +/** \class calibration k4a.hpp + * Wrapper for \ref k4a_calibration_t + * + * Provides member functions for k4a_calibration_t. + */ +struct calibration : public k4a_calibration_t +{ + /** Transform a 3d point of a source coordinate system into a 3d point of the target coordinate system. + * Throws error on failure. + * + * \sa k4a_calibration_3d_to_3d + */ + k4a_float3_t convert_3d_to_3d(const k4a_float3_t &source_point3d, + k4a_calibration_type_t source_camera, + k4a_calibration_type_t target_camera) const + { + k4a_float3_t target_point3d; + k4a_result_t result = + k4a_calibration_3d_to_3d(this, &source_point3d, source_camera, target_camera, &target_point3d); + + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Calibration contained invalid transformation parameters!"); + } + return target_point3d; + } + + /** Transform a 2d pixel coordinate with an associated depth value of the source camera into a 3d point of the + * target coordinate system. + * Returns false if the point is invalid in the target coordinate system (and therefore target_point3d should not be + * used) + * Throws error if calibration contains invalid data. + * + * \sa k4a_calibration_2d_to_3d + */ + bool convert_2d_to_3d(const k4a_float2_t &source_point2d, + float source_depth, + k4a_calibration_type_t source_camera, + k4a_calibration_type_t target_camera, + k4a_float3_t *target_point3d) const + { + int valid = 0; + k4a_result_t result = k4a_calibration_2d_to_3d( + this, &source_point2d, source_depth, source_camera, target_camera, target_point3d, &valid); + + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Calibration contained invalid transformation parameters!"); + } + return static_cast(valid); + } + + /** Transform a 3d point of a source coordinate system into a 2d pixel coordinate of the target camera. + * Returns false if the point is invalid in the target coordinate system (and therefore target_point2d should not be + * used) + * Throws error if calibration contains invalid data. + * + * \sa k4a_calibration_3d_to_2d + */ + bool convert_3d_to_2d(const k4a_float3_t &source_point3d, + k4a_calibration_type_t source_camera, + k4a_calibration_type_t target_camera, + k4a_float2_t *target_point2d) const + { + int valid = 0; + k4a_result_t result = + k4a_calibration_3d_to_2d(this, &source_point3d, source_camera, target_camera, target_point2d, &valid); + + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Calibration contained invalid transformation parameters!"); + } + return static_cast(valid); + } + + /** Transform a 2d pixel coordinate with an associated depth value of the source camera into a 2d pixel coordinate + * of the target camera + * Returns false if the point is invalid in the target coordinate system (and therefore target_point2d should not be + * used) + * Throws error if calibration contains invalid data. + * + * \sa k4a_calibration_2d_to_2d + */ + bool convert_2d_to_2d(const k4a_float2_t &source_point2d, + float source_depth, + k4a_calibration_type_t source_camera, + k4a_calibration_type_t target_camera, + k4a_float2_t *target_point2d) const + { + int valid = 0; + k4a_result_t result = k4a_calibration_2d_to_2d( + this, &source_point2d, source_depth, source_camera, target_camera, target_point2d, &valid); + + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Calibration contained invalid transformation parameters!"); + } + return static_cast(valid); + } + + /** Transform a 2D pixel coordinate from color camera into a 2D pixel coordinate of the depth camera. This function + * searches along an epipolar line in the depth image to find the corresponding depth pixel. + * Returns false if the point is invalid in the target coordinate system (and therefore target_point2d should not be + * used) Throws error if calibration contains invalid data. + * + * \sa k4a_calibration_color_2d_to_depth_2d + */ + bool convert_color_2d_to_depth_2d(const k4a_float2_t &source_point2d, + const image &depth_image, + k4a_float2_t *target_point2d) const + { + int valid = 0; + k4a_result_t result = + k4a_calibration_color_2d_to_depth_2d(this, &source_point2d, depth_image.handle(), target_point2d, &valid); + + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Calibration contained invalid transformation parameters!"); + } + return static_cast(valid); + } + + /** Get the camera calibration for a device from a raw calibration blob. + * Throws error on failure. + * + * \sa k4a_calibration_get_from_raw + */ + static calibration get_from_raw(char *raw_calibration, + size_t raw_calibration_size, + k4a_depth_mode_t target_depth_mode, + k4a_color_resolution_t target_color_resolution) + { + calibration calib; + k4a_result_t result = k4a_calibration_get_from_raw(raw_calibration, + raw_calibration_size, + target_depth_mode, + target_color_resolution, + &calib); + + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to load calibration from raw calibration blob!"); + } + return calib; + } + + /** Get the camera calibration for a device from a raw calibration blob. + * Throws error on failure. + * + * \sa k4a_calibration_get_from_raw + */ + static calibration get_from_raw(uint8_t *raw_calibration, + size_t raw_calibration_size, + k4a_depth_mode_t target_depth_mode, + k4a_color_resolution_t target_color_resolution) + { + return get_from_raw(reinterpret_cast(raw_calibration), + raw_calibration_size, + target_depth_mode, + target_color_resolution); + } + + /** Get the camera calibration for a device from a raw calibration blob. + * Throws error on failure. + * + * \sa k4a_calibration_get_from_raw + */ + static calibration get_from_raw(std::vector &raw_calibration, + k4a_depth_mode_t target_depth_mode, + k4a_color_resolution_t target_color_resolution) + { + return get_from_raw(reinterpret_cast(raw_calibration.data()), + raw_calibration.size(), + target_depth_mode, + target_color_resolution); + } +}; + +/** \class transformation k4a.hpp + * Wrapper for \ref k4a_transformation_t + * + * Wraps a handle for a transformation. + */ +class transformation +{ +public: + /** Creates a transformation associated with calibration + * + * \sa k4a_transformation_create + */ + transformation(const k4a_calibration_t &calibration) noexcept : + m_handle(k4a_transformation_create(&calibration)), + m_color_resolution({ calibration.color_camera_calibration.resolution_width, + calibration.color_camera_calibration.resolution_height }), + m_depth_resolution({ calibration.depth_camera_calibration.resolution_width, + calibration.depth_camera_calibration.resolution_height }) + { + } + + /** Creates a transformation from a k4a_transformation_t + * Takes ownership of the handle, i.e. you should not call + * k4a_transformation_destroy on the handle after giving + * it to the transformation; the transformation will take care of that. + */ + transformation(k4a_transformation_t handle = nullptr) noexcept : m_handle(handle) {} + + /** Moves another tranformation into a new transformation + */ + transformation(transformation &&other) noexcept : + m_handle(other.m_handle), + m_color_resolution(other.m_color_resolution), + m_depth_resolution(other.m_depth_resolution) + { + other.m_handle = nullptr; + } + + transformation(const transformation &) = delete; + + ~transformation() + { + destroy(); + } + + /** Moves another image into this image; other is set to invalid + */ + transformation &operator=(transformation &&other) noexcept + { + if (this != &other) + { + destroy(); + m_handle = other.m_handle; + m_color_resolution = other.m_color_resolution; + m_depth_resolution = other.m_depth_resolution; + other.m_handle = nullptr; + } + + return *this; + } + + /** Invalidates this transformation + */ + transformation &operator=(std::nullptr_t) noexcept + { + destroy(); + return *this; + } + + transformation &operator=(const transformation &) = delete; + + /** Invalidates this transformation + */ + void destroy() noexcept + { + if (m_handle != nullptr) + { + k4a_transformation_destroy(m_handle); + m_handle = nullptr; + } + } + + /** Transforms the depth map into the geometry of the color camera. + * Throws error on failure + * + * \sa k4a_transformation_depth_image_to_color_camera + * Transforms the output in to the existing caller provided \p transformed_depth_image. + */ + void depth_image_to_color_camera(const image &depth_image, image *transformed_depth_image) const + { + k4a_result_t result = k4a_transformation_depth_image_to_color_camera(m_handle, + depth_image.handle(), + transformed_depth_image->handle()); + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to convert depth map to color camera geometry!"); + } + } + + /** Transforms the depth map into the geometry of the color camera. + * Throws error on failure + * + * \sa k4a_transformation_depth_image_to_color_camera + * Creates a new image with the output. + */ + image depth_image_to_color_camera(const image &depth_image) const + { + image transformed_depth_image = image::create(K4A_IMAGE_FORMAT_DEPTH16, + m_color_resolution.width, + m_color_resolution.height, + m_color_resolution.width * + static_cast(sizeof(uint16_t))); + depth_image_to_color_camera(depth_image, &transformed_depth_image); + return transformed_depth_image; + } + + /** Transforms depth map and a custom image into the geometry of the color camera. + * Throws error on failure + * + * \sa k4a_transformation_depth_image_to_color_camera_custom + * Transforms the output in to the existing caller provided \p transformed_depth_image \p transformed_custom_image. + */ + void depth_image_to_color_camera_custom(const image &depth_image, + const image &custom_image, + image *transformed_depth_image, + image *transformed_custom_image, + k4a_transformation_interpolation_type_t interpolation_type, + uint32_t invalid_custom_value) const + { + k4a_result_t result = k4a_transformation_depth_image_to_color_camera_custom(m_handle, + depth_image.handle(), + custom_image.handle(), + transformed_depth_image->handle(), + transformed_custom_image->handle(), + interpolation_type, + invalid_custom_value); + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to convert depth map and custom image to color camera geometry!"); + } + } + + /** Transforms depth map and a custom image into the geometry of the color camera. + * Throws error on failure + * + * \sa k4a_transformation_depth_image_to_color_camera_custom + * Creates a new image with the output. + */ + std::pair + depth_image_to_color_camera_custom(const image &depth_image, + const image &custom_image, + k4a_transformation_interpolation_type_t interpolation_type, + uint32_t invalid_custom_value) const + { + image transformed_depth_image = image::create(K4A_IMAGE_FORMAT_DEPTH16, + m_color_resolution.width, + m_color_resolution.height, + m_color_resolution.width * + static_cast(sizeof(uint16_t))); + int32_t bytes_per_pixel; + switch (custom_image.get_format()) + { + case K4A_IMAGE_FORMAT_CUSTOM8: + bytes_per_pixel = static_cast(sizeof(int8_t)); + break; + case K4A_IMAGE_FORMAT_CUSTOM16: + bytes_per_pixel = static_cast(sizeof(int16_t)); + break; + default: + throw error("Failed to support this format of custom image!"); + } + image transformed_custom_image = image::create(custom_image.get_format(), + m_color_resolution.width, + m_color_resolution.height, + m_color_resolution.width * bytes_per_pixel); + depth_image_to_color_camera_custom(depth_image, + custom_image, + &transformed_depth_image, + &transformed_custom_image, + interpolation_type, + invalid_custom_value); + return { std::move(transformed_depth_image), std::move(transformed_custom_image) }; + } + + /** Transforms the color image into the geometry of the depth camera. + * Throws error on failure + * + * \sa k4a_transformation_color_image_to_depth_camera + * Transforms the output in to the existing caller provided \p transformed_color_image. + */ + void color_image_to_depth_camera(const image &depth_image, + const image &color_image, + image *transformed_color_image) const + { + k4a_result_t result = k4a_transformation_color_image_to_depth_camera(m_handle, + depth_image.handle(), + color_image.handle(), + transformed_color_image->handle()); + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to convert color image to depth camera geometry!"); + } + } + + /** Transforms the color image into the geometry of the depth camera. + * Throws error on failure + * + * \sa k4a_transformation_color_image_to_depth_camera + * Creates a new image with the output. + */ + image color_image_to_depth_camera(const image &depth_image, const image &color_image) const + { + image transformed_color_image = image::create(K4A_IMAGE_FORMAT_COLOR_BGRA32, + m_depth_resolution.width, + m_depth_resolution.height, + m_depth_resolution.width * 4 * + static_cast(sizeof(uint8_t))); + color_image_to_depth_camera(depth_image, color_image, &transformed_color_image); + return transformed_color_image; + } + + /** Transforms the depth image into 3 planar images representing X, Y and Z-coordinates of corresponding 3d points. + * Throws error on failure. + * + * \sa k4a_transformation_depth_image_to_point_cloud + * Transforms the output in to the existing caller provided \p xyz_image. + */ + void depth_image_to_point_cloud(const image &depth_image, k4a_calibration_type_t camera, image *xyz_image) const + { + k4a_result_t result = + k4a_transformation_depth_image_to_point_cloud(m_handle, depth_image.handle(), camera, xyz_image->handle()); + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to transform depth image to point cloud!"); + } + } + + /** Transforms the depth image into 3 planar images representing X, Y and Z-coordinates of corresponding 3d points. + * Throws error on failure. + * + * \sa k4a_transformation_depth_image_to_point_cloud + * Creates a new image with the output. + */ + image depth_image_to_point_cloud(const image &depth_image, k4a_calibration_type_t camera) const + { + image xyz_image = image::create(K4A_IMAGE_FORMAT_CUSTOM, + depth_image.get_width_pixels(), + depth_image.get_height_pixels(), + depth_image.get_width_pixels() * 3 * static_cast(sizeof(int16_t))); + depth_image_to_point_cloud(depth_image, camera, &xyz_image); + return xyz_image; + } + +private: + k4a_transformation_t m_handle; + struct resolution + { + int32_t width; + int32_t height; + }; + resolution m_color_resolution; + resolution m_depth_resolution; +}; + +/** \class device k4a.hpp + * Wrapper for \ref k4a_device_t + * + * Wraps a handle for a device. + */ +class device +{ +public: + /** Creates a device from a k4a_device_t + * Takes ownership of the handle, i.e. you should not call + * k4a_device_close on the handle after giving it to the + * device; the device will take care of that. + */ + device(k4a_device_t handle = nullptr) noexcept : m_handle(handle) {} + + /** Moves another device into a new device + */ + device(device &&dev) noexcept : m_handle(dev.m_handle) + { + dev.m_handle = nullptr; + } + + device(const device &) = delete; + + ~device() + { + close(); + } + + device &operator=(const device &) = delete; + + /** Moves another device into this device; other is set to invalid + */ + device &operator=(device &&dev) noexcept + { + if (this != &dev) + { + close(); + m_handle = dev.m_handle; + dev.m_handle = nullptr; + } + return *this; + } + + /** Returns true if the device is valid, false otherwise + */ + operator bool() const noexcept + { + return m_handle != nullptr; + } + + /** Returns the underlying k4a_device_t handle + * + * Note the k4a_device_t handle does not have a reference count will be destroyed when the C++ object is destroyed. + * The caller is responsible for ensuring the C++ object outlives this handle. + */ + k4a_device_t handle() const noexcept + { + return m_handle; + } + + /** Closes a k4a device. + * + * \sa k4a_device_close + */ + void close() noexcept + { + if (m_handle != nullptr) + { + k4a_device_close(m_handle); + m_handle = nullptr; + } + } + + /** Reads a sensor capture into cap. Returns true if a capture was read, false if the read timed out. + * Throws error on failure. + * + * \sa k4a_device_get_capture + */ + bool get_capture(capture *cap, std::chrono::milliseconds timeout) + { + k4a_capture_t capture_handle = nullptr; + int32_t timeout_ms = internal::clamp_cast(timeout.count()); + k4a_wait_result_t result = k4a_device_get_capture(m_handle, &capture_handle, timeout_ms); + if (result == K4A_WAIT_RESULT_FAILED) + { + throw error("Failed to get capture from device!"); + } + else if (result == K4A_WAIT_RESULT_TIMEOUT) + { + return false; + } + + *cap = capture(capture_handle); + return true; + } + + /** Reads a sensor capture into cap. Returns true if a capture was read, false if the read timed out. + * Throws error on failure. This API assumes an inifinate timeout. + * + * \sa k4a_device_get_capture + */ + bool get_capture(capture *cap) + { + return get_capture(cap, std::chrono::milliseconds(K4A_WAIT_INFINITE)); + } + + /** Reads an IMU sample. Returns true if a sample was read, false if the read timed out. + * Throws error on failure. + * + * \sa k4a_device_get_imu_sample + */ + bool get_imu_sample(k4a_imu_sample_t *imu_sample, std::chrono::milliseconds timeout) + { + int32_t timeout_ms = internal::clamp_cast(timeout.count()); + k4a_wait_result_t result = k4a_device_get_imu_sample(m_handle, imu_sample, timeout_ms); + if (result == K4A_WAIT_RESULT_FAILED) + { + throw error("Failed to get IMU sample from device!"); + } + else if (result == K4A_WAIT_RESULT_TIMEOUT) + { + return false; + } + + return true; + } + + /** Reads an IMU sample. Returns true if a sample was read, false if the read timed out. + * Throws error on failure. This API assumes an infinate timeout. + * + * \sa k4a_device_get_imu_sample + */ + bool get_imu_sample(k4a_imu_sample_t *imu_sample) + { + return get_imu_sample(imu_sample, std::chrono::milliseconds(K4A_WAIT_INFINITE)); + } + + /** Starts the K4A device's cameras + * Throws error on failure. + * + * \sa k4a_device_start_cameras + */ + void start_cameras(const k4a_device_configuration_t *configuration) + { + k4a_result_t result = k4a_device_start_cameras(m_handle, configuration); + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to start cameras!"); + } + } + + /** Stops the K4A device's cameras + * + * \sa k4a_device_stop_cameras + */ + void stop_cameras() noexcept + { + k4a_device_stop_cameras(m_handle); + } + + /** Starts the K4A IMU + * Throws error on failure + * + * \sa k4a_device_start_imu + */ + void start_imu() + { + k4a_result_t result = k4a_device_start_imu(m_handle); + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to start IMU!"); + } + } + + /** Stops the K4A IMU + * + * \sa k4a_device_stop_imu + */ + void stop_imu() noexcept + { + k4a_device_stop_imu(m_handle); + } + + /** Get the K4A device serial number + * Throws error on failure. + * + * \sa k4a_device_get_serialnum + */ + std::string get_serialnum() const + { + std::string serialnum; + size_t buffer = 0; + k4a_buffer_result_t result = k4a_device_get_serialnum(m_handle, &serialnum[0], &buffer); + + if (result == K4A_BUFFER_RESULT_TOO_SMALL && buffer > 1) + { + serialnum.resize(buffer); + result = k4a_device_get_serialnum(m_handle, &serialnum[0], &buffer); + if (result == K4A_BUFFER_RESULT_SUCCEEDED && serialnum[buffer - 1] == 0) + { + // std::string expects there to not be as null terminator at the end of its data but + // k4a_device_get_serialnum adds a null terminator, so we drop the last character of the string after we + // get the result back. + serialnum.resize(buffer - 1); + } + } + + if (result != K4A_BUFFER_RESULT_SUCCEEDED) + { + throw error("Failed to read device serial number!"); + } + + return serialnum; + } + + /** Get the K4A color sensor control value + * Throws error on failure. + * + * \sa k4a_device_get_color_control + */ + void get_color_control(k4a_color_control_command_t command, k4a_color_control_mode_t *mode, int32_t *value) const + { + k4a_result_t result = k4a_device_get_color_control(m_handle, command, mode, value); + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to read color control!"); + } + } + + /** Set the K4A color sensor control value + * Throws error on failure. + * + * \sa k4a_device_set_color_control + */ + void set_color_control(k4a_color_control_command_t command, k4a_color_control_mode_t mode, int32_t value) + { + k4a_result_t result = k4a_device_set_color_control(m_handle, command, mode, value); + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to set color control!"); + } + } + + /** Get the raw calibration blob for the entire K4A device. + * Throws error on failure. + * + * \sa k4a_device_get_raw_calibration + */ + std::vector get_raw_calibration() const + { + std::vector calibration; + size_t buffer = 0; + k4a_buffer_result_t result = k4a_device_get_raw_calibration(m_handle, &calibration[0], &buffer); + + if (result == K4A_BUFFER_RESULT_TOO_SMALL && buffer > 1) + { + calibration.resize(buffer); + result = k4a_device_get_raw_calibration(m_handle, &calibration[0], &buffer); + } + + if (result != K4A_BUFFER_RESULT_SUCCEEDED) + { + throw error("Failed to read raw device calibration!"); + } + + return calibration; + } + + /** Get the camera calibration for the entire K4A device, which is used for all transformation functions. + * Throws error on failure. + * + * \sa k4a_device_get_calibration + */ + calibration get_calibration(k4a_depth_mode_t depth_mode, k4a_color_resolution_t color_resolution) const + { + calibration calib; + k4a_result_t result = k4a_device_get_calibration(m_handle, depth_mode, color_resolution, &calib); + + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to read device calibration!"); + } + return calib; + } + + /** Get the device jack status for the synchronization in connector + * Throws error on failure. + * + * \sa k4a_device_get_sync_jack + */ + bool is_sync_in_connected() const + { + bool sync_in_jack_connected, sync_out_jack_connected; + k4a_result_t result = k4a_device_get_sync_jack(m_handle, &sync_in_jack_connected, &sync_out_jack_connected); + + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to read sync jack status!"); + } + return sync_in_jack_connected; + } + + /** Get the device jack status for the synchronization out connector + * Throws error on failure. + * + * \sa k4a_device_get_sync_jack + */ + bool is_sync_out_connected() const + { + bool sync_in_jack_connected, sync_out_jack_connected; + k4a_result_t result = k4a_device_get_sync_jack(m_handle, &sync_in_jack_connected, &sync_out_jack_connected); + + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to read sync jack status!"); + } + return sync_out_jack_connected; + } + + /** Get the version numbers of the K4A subsystems' firmware + * Throws error on failure. + * + * \sa k4a_device_get_version + */ + k4a_hardware_version_t get_version() const + { + k4a_hardware_version_t version; + k4a_result_t result = k4a_device_get_version(m_handle, &version); + + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to read device firmware information!"); + } + return version; + } + + /** Open a k4a device. + * Throws error on failure. + * + * \sa k4a_device_open + */ + static device open(uint32_t index) + { + k4a_device_t handle = nullptr; + k4a_result_t result = k4a_device_open(index, &handle); + + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to open device!"); + } + return device(handle); + } + + /** Gets the number of connected devices + * + * \sa k4a_device_get_installed_count + */ + static uint32_t get_installed_count() noexcept + { + return k4a_device_get_installed_count(); + } + +private: + k4a_device_t m_handle; +}; + +/** + * @} + */ + +} // namespace k4a + +#endif diff --git a/k4a-sys/vendor/include/windows/k4a/k4a_export.h b/k4a-sys/vendor/include/windows/k4a/k4a_export.h new file mode 100644 index 0000000000..b291e752c5 --- /dev/null +++ b/k4a-sys/vendor/include/windows/k4a/k4a_export.h @@ -0,0 +1,42 @@ + +#ifndef K4A_EXPORT_H +#define K4A_EXPORT_H + +#ifdef K4A_STATIC_DEFINE +# define K4A_EXPORT +# define K4A_NO_EXPORT +#else +# ifndef K4A_EXPORT +# ifdef k4a_EXPORTS + /* We are building this library */ +# define K4A_EXPORT __declspec(dllexport) +# else + /* We are using this library */ +# define K4A_EXPORT __declspec(dllimport) +# endif +# endif + +# ifndef K4A_NO_EXPORT +# define K4A_NO_EXPORT +# endif +#endif + +#ifndef K4A_DEPRECATED +# define K4A_DEPRECATED __declspec(deprecated) +#endif + +#ifndef K4A_DEPRECATED_EXPORT +# define K4A_DEPRECATED_EXPORT K4A_EXPORT K4A_DEPRECATED +#endif + +#ifndef K4A_DEPRECATED_NO_EXPORT +# define K4A_DEPRECATED_NO_EXPORT K4A_NO_EXPORT K4A_DEPRECATED +#endif + +#if 0 /* DEFINE_NO_DEPRECATED */ +# ifndef K4A_NO_DEPRECATED +# define K4A_NO_DEPRECATED +# endif +#endif + +#endif /* K4A_EXPORT_H */ diff --git a/k4a-sys/vendor/include/windows/k4a/k4atypes.h b/k4a-sys/vendor/include/windows/k4a/k4atypes.h new file mode 100644 index 0000000000..e7d17bd339 --- /dev/null +++ b/k4a-sys/vendor/include/windows/k4a/k4atypes.h @@ -0,0 +1,1271 @@ +/** \file k4atypes.h + * Copyright (c) Microsoft Corporation. All rights reserved. + * Licensed under the MIT License. + * Kinect For Azure SDK Type definitions. + */ + +#ifndef K4ATYPES_H +#define K4ATYPES_H + +#ifdef __cplusplus +#include +#include +#include +#else +#include +#include +#include +#include +#endif + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * Declare an opaque handle type. + * + * \param _handle_name_ The type name of the handle + * + * \remarks + * This is used to define the public handle types for the Azure Kinect APIs. + * The macro is not intended to be used outside of the Azure Kinect headers. + */ +#define K4A_DECLARE_HANDLE(_handle_name_) \ + typedef struct _##_handle_name_ \ + { \ + size_t _rsvd; /**< Reserved, do not use. */ \ + } * _handle_name_; + +/** + * \defgroup csdk C Reference + * + */ +/** + * \defgroup Handles Handles + * \ingroup csdk + * Handles represent object instances. + * + * Handles are opaque pointers returned by the SDK which represent an object. + * + * @{ + */ + +/** \class k4a_device_t k4a.h + * Handle to an Azure Kinect device. + * + * \remarks + * Handles are created with k4a_device_open() and closed with k4a_device_close(). Invalid handles are set to 0. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +K4A_DECLARE_HANDLE(k4a_device_t); + +/** \class k4a_capture_t k4a.h + * Handle to an Azure Kinect capture. + * + * \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 + * 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, k4a_device_get_capture() will return a capture containing both image types separated by the + * configured delay. + * + * \remarks + * The capture will add a reference on any \ref k4a_image_t that is added to it with one of the setters like + * k4a_capture_set_color_image(). If an existing image is being replaced, the previous image will have the reference + * released. + * + * \remarks + * Once all references to the \ref k4a_capture_t are released, the capture will release the references it holds on any + * \ref k4a_image_t that are associated with it. + * + * \remarks + * When a capture returns an image to the caller with an accessor like k4a_capture_get_color_image(), a new reference is + * added to the \ref k4a_image_t and the caller is responsible for releasing that reference with k4a_image_release(). + * + * \remarks + * Empty captures are created with k4a_capture_create(). + * + * \remarks + * Captures can be obtained from a device using k4a_device_get_capture(). + * + * \remarks + * The caller must call k4a_capture_release() to release its reference to any \ref k4a_capture_t that it receives from + * an Azure Kinect API. + * + * \remarks + * Additional references to the capture may be obtained with k4a_capture_reference(). + * + * \remarks + * An invalid k4a_capture_t will be set to 0. + * + * \see k4a_image_t + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +K4A_DECLARE_HANDLE(k4a_capture_t); + +/** \class k4a_image_t k4a.h + * Handle to an Azure Kinect image. + * + * \remarks + * A \ref k4a_image_t manages an image buffer and associated metadata. + * + * \remarks + * The memory associated with the image buffer in an \ref k4a_image_t may have been allocated by the Azure Kinect APIs + * or by the application. If the \ref k4a_image_t was created by an Azure Kinect API, its memory will be freed when all + * references to the \ref k4a_image_t are released. All images retrieved directly from a device will have been created + * by the API. An application can create a \ref k4a_image_t using memory that it has allocated using + * k4a_image_create_from_buffer(). In that case the memory is not freed when the references are released but instead the + * application is provided with a callback. Applications need to create a k4a_image_t to provide as an output to the + * k4a_transformation_t transformation functions. + * + * \remarks + * An image has a number of metadata properties that can be set or retrieved using the accessor functions. Not all + * properties are applicable to images of all types. See the documentation for the individual accessors for more + * information on their applicability and meaning. + * + * \remarks + * Images may be of one of the standard \ref k4a_image_format_t formats, or may be of format ::K4A_IMAGE_FORMAT_CUSTOM. + * The format defines how the underlying image buffer should be interpreted. + * + * \remarks + * Images from a device are retrieved through a \ref k4a_capture_t object returned by k4a_device_get_capture(). + * + * \remarks + * Images stored in a k4a_capture_t are referenced by the k4a_capture_t until they are replaced or the k4a_capture_t is + * destroyed. + * + * \remarks + * The caller must call k4a_image_release() to release its reference to any \ref k4a_image_t that it receives from + * an Azure Kinect API. + * + * \remarks + * Additional references to the image may be obtained with k4a_image_reference(). + * + * \remarks + * An invalid k4a_image_t will be set to 0. + * + * \see k4a_capture_t + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +K4A_DECLARE_HANDLE(k4a_image_t); + +/** \class k4a_transformation_t k4a.h + * Handle to an Azure Kinect transformation context. + * + * \remarks + * Handles are created with k4a_transformation_create() and closed with k4a_transformation_destroy(). + * + * \remarks + * The transformation handle is used to transform images from the coordinate system of one camera into the other. Each + * transformation handle requires some pre-computed resources to be allocated, which are retained until the handle is + * destroyed. + * + * \remarks + * Invalid handles are set to 0. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +K4A_DECLARE_HANDLE(k4a_transformation_t); + +/** + * + * @} + * + * \defgroup Enumerations Enumerations + * \ingroup csdk + * + * Enumeration types used by APIs. + * + * @{ + */ + +/** Result code returned by Azure Kinect APIs. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef enum +{ + K4A_RESULT_SUCCEEDED = 0, /**< The result was successful */ + K4A_RESULT_FAILED, /**< The result was a failure */ +} k4a_result_t; + +/** Result code returned by Azure Kinect APIs. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef enum +{ + K4A_BUFFER_RESULT_SUCCEEDED = 0, /**< The result was successful */ + K4A_BUFFER_RESULT_FAILED, /**< The result was a failure */ + K4A_BUFFER_RESULT_TOO_SMALL, /**< The input buffer was too small */ +} k4a_buffer_result_t; + +/** Result code returned by Azure Kinect APIs. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef enum +{ + K4A_WAIT_RESULT_SUCCEEDED = 0, /**< The result was successful */ + K4A_WAIT_RESULT_FAILED, /**< The result was a failure */ + K4A_WAIT_RESULT_TIMEOUT, /**< The operation timed out */ +} k4a_wait_result_t; + +/** Verbosity levels of debug messaging + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef enum +{ + K4A_LOG_LEVEL_CRITICAL = 0, /**< Most severe level of debug messaging. */ + K4A_LOG_LEVEL_ERROR, /**< 2nd most severe level of debug messaging. */ + K4A_LOG_LEVEL_WARNING, /**< 3nd most severe level of debug messaging. */ + K4A_LOG_LEVEL_INFO, /**< 2nd least severe level of debug messaging. */ + K4A_LOG_LEVEL_TRACE, /**< Least severe level of debug messaging. */ + K4A_LOG_LEVEL_OFF, /**< No logging is performed */ +} k4a_log_level_t; + +/** Depth sensor capture modes. + * + * \remarks + * See the hardware specification for additional details on the field of view, and supported frame rates + * for each mode. + * + * \remarks + * NFOV and WFOV denote Narrow and Wide Field Of View configurations. + * + * \remarks + * Binned modes reduce the captured camera resolution by combining adjacent sensor pixels into a bin. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +// Be sure to update k4a_depth_mode_to_string in k4a.c if enum values are added. +typedef enum +{ + K4A_DEPTH_MODE_OFF = 0, /**< Depth sensor will be turned off with this setting. */ + K4A_DEPTH_MODE_NFOV_2X2BINNED, /**< Depth captured at 320x288. Passive IR is also captured at 320x288. */ + K4A_DEPTH_MODE_NFOV_UNBINNED, /**< Depth captured at 640x576. Passive IR is also captured at 640x576. */ + K4A_DEPTH_MODE_WFOV_2X2BINNED, /**< Depth captured at 512x512. Passive IR is also captured at 512x512. */ + K4A_DEPTH_MODE_WFOV_UNBINNED, /**< Depth captured at 1024x1024. Passive IR is also captured at 1024x1024. */ + K4A_DEPTH_MODE_PASSIVE_IR, /**< Passive IR only, captured at 1024x1024. */ +} k4a_depth_mode_t; + +/** Color sensor resolutions. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +// Be sure to update k4a_color_resolution_to_string in k4a.c if enum values are added. +typedef enum +{ + K4A_COLOR_RESOLUTION_OFF = 0, /**< Color camera will be turned off with this setting */ + K4A_COLOR_RESOLUTION_720P, /**< 1280 * 720 16:9 */ + K4A_COLOR_RESOLUTION_1080P, /**< 1920 * 1080 16:9 */ + K4A_COLOR_RESOLUTION_1440P, /**< 2560 * 1440 16:9 */ + K4A_COLOR_RESOLUTION_1536P, /**< 2048 * 1536 4:3 */ + K4A_COLOR_RESOLUTION_2160P, /**< 3840 * 2160 16:9 */ + K4A_COLOR_RESOLUTION_3072P, /**< 4096 * 3072 4:3 */ +} k4a_color_resolution_t; + +/** Image format type. + * + * \remarks + * The image format indicates how the \ref k4a_image_t buffer data is interpreted. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +// Be sure to update k4a_image_format_to_string in k4a.c if enum values are added. +typedef enum +{ + /** Color image type MJPG. + * + * \details + * The buffer for each image is encoded as a JPEG and can be decoded by a JPEG decoder. + * + * \details + * Because the image is compressed, the stride parameter for the \ref k4a_image_t is not applicable. + * + * \details + * Each MJPG encoded image in a stream may be of differing size depending on the compression efficiency. + */ + K4A_IMAGE_FORMAT_COLOR_MJPG = 0, + + /** Color image type NV12. + * + * \details + * NV12 images separate the luminance and chroma data such that all the luminance is at the + * beginning of the buffer, and the chroma lines follow immediately after. + * + * \details + * Stride indicates the length of each line in bytes and should be used to determine the start location of each line + * of the image in memory. Chroma has half as many lines of height and half the width in pixels of the luminance. + * Each chroma line has the same width in bytes as a luminance line. + */ + K4A_IMAGE_FORMAT_COLOR_NV12, + + /** Color image type YUY2. + * + * \details + * YUY2 stores chroma and luminance data in interleaved pixels. + * + * \details + * Stride indicates the length of each line in bytes and should be used to determine the start location of each + * line of the image in memory. + */ + K4A_IMAGE_FORMAT_COLOR_YUY2, + + /** Color image type BGRA32. + * + * \details + * Each pixel of BGRA32 data is four bytes. The first three bytes represent Blue, Green, + * and Red data. The fourth byte is the alpha channel and is unused in the Azure Kinect APIs. + * + * \details + * Stride indicates the length of each line in bytes and should be used to determine the start location of each + * line of the image in memory. + * + * \details + * The Azure Kinect device does not natively capture in this format. Requesting images of this format + * requires additional computation in the API. + * + */ + K4A_IMAGE_FORMAT_COLOR_BGRA32, + + /** Depth image type DEPTH16. + * + * \details + * Each pixel of DEPTH16 data is two bytes of little endian unsigned depth data. The unit of the data is in + * millimeters from the origin of the camera. + * + * \details + * Stride indicates the length of each line in bytes and should be used to determine the start location of each + * line of the image in memory. + */ + K4A_IMAGE_FORMAT_DEPTH16, + + /** Image type IR16. + * + * \details + * Each pixel of IR16 data is two bytes of little endian unsigned depth data. The value of the data represents + * brightness. + * + * \details + * This format represents infrared light and is captured by the depth camera. + * + * \details + * Stride indicates the length of each line in bytes and should be used to determine the start location of each + * line of the image in memory. + */ + K4A_IMAGE_FORMAT_IR16, + + /** Single channel image type CUSTOM8. + * + * \details + * Each pixel of CUSTOM8 is a single channel one byte of unsigned data. + * + * \details + * Stride indicates the length of each line in bytes and should be used to determine the start location of each + * line of the image in memory. + */ + K4A_IMAGE_FORMAT_CUSTOM8, + + /** Single channel image type CUSTOM16. + * + * \details + * Each pixel of CUSTOM16 is a single channel two bytes of little endian unsigned data. + * + * \details + * Stride indicates the length of each line in bytes and should be used to determine the start location of each + * line of the image in memory. + */ + K4A_IMAGE_FORMAT_CUSTOM16, + + /** Custom image format. + * + * \details + * Used in conjunction with user created images or images packing non-standard data. + * + * \details + * See the originator of the custom formatted image for information on how to interpret the data. + */ + K4A_IMAGE_FORMAT_CUSTOM, +} k4a_image_format_t; + +/** Transformation interpolation type. + * + * \remarks + * Interpolation type used with k4a_transformation_depth_image_to_color_camera_custom. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef enum +{ + K4A_TRANSFORMATION_INTERPOLATION_TYPE_NEAREST = 0, /**< Nearest neighbor interpolation */ + K4A_TRANSFORMATION_INTERPOLATION_TYPE_LINEAR, /**< Linear interpolation */ +} k4a_transformation_interpolation_type_t; + +/** Color and depth sensor frame rate. + * + * \remarks + * This enumeration is used to select the desired frame rate to operate the cameras. The actual + * frame rate may vary slightly due to dropped data, synchronization variation between devices, + * clock accuracy, or if the camera exposure priority mode causes reduced frame rate. + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +// Be sure to update k4a_fps_to_string in k4a.c if enum values are added. +typedef enum +{ + K4A_FRAMES_PER_SECOND_5 = 0, /**< 5 FPS */ + K4A_FRAMES_PER_SECOND_15, /**< 15 FPS */ + K4A_FRAMES_PER_SECOND_30, /**< 30 FPS */ +} k4a_fps_t; + +/** Color sensor control commands + * + * \remarks + * The current settings can be read with k4a_device_get_color_control(). The settings can be set with + * k4a_device_set_color_control(). + * + * \remarks + * Control values set on a device are reset only when the device is power cycled. The device will retain the settings + * even if the \ref k4a_device_t is closed or the application is restarted. + * + * \see k4a_color_control_mode_t + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef enum +{ + /** Exposure time setting. + * + * \details + * May be set to ::K4A_COLOR_CONTROL_MODE_AUTO or ::K4A_COLOR_CONTROL_MODE_MANUAL. + * + * \details + * The Azure Kinect supports a limited number of fixed expsore settings. When setting this, expect the exposure to + * be rounded up to the nearest setting. Exceptions are 1) The last value in the table is the upper limit, so a + * value larger than this will be overridden to the largest entry in the table. 2) The exposure time cannot be + * larger than the equivelent FPS. So expect 100ms exposure time to be reduced to 30ms or 33.33ms when the camera is + * started. The most recent copy of the table 'device_exposure_mapping' is in + * https://github.com/microsoft/Azure-Kinect-Sensor-SDK/blob/develop/src/color/color_priv.h + * + * \details + * Exposure time is measured in microseconds. + */ + K4A_COLOR_CONTROL_EXPOSURE_TIME_ABSOLUTE = 0, + + /** Exposure or Framerate priority setting. + * + * \details + * May only be set to ::K4A_COLOR_CONTROL_MODE_MANUAL. + * + * \details + * Value of 0 means framerate priority. Value of 1 means exposure priority. + * + * \details + * Using exposure priority may impact the framerate of both the color and depth cameras. + * + * \details + * Deprecated starting in 1.2.0. Please discontinue usage, firmware does not support this. + */ + K4A_COLOR_CONTROL_AUTO_EXPOSURE_PRIORITY, + + /** Brightness setting. + * + * \details + * May only be set to ::K4A_COLOR_CONTROL_MODE_MANUAL. + * + * \details + * The valid range is 0 to 255. The default value is 128. + */ + K4A_COLOR_CONTROL_BRIGHTNESS, + + /** Contrast setting. + * + * \details + * May only be set to ::K4A_COLOR_CONTROL_MODE_MANUAL. + */ + K4A_COLOR_CONTROL_CONTRAST, + + /** Saturation setting. + * + * \details + * May only be set to ::K4A_COLOR_CONTROL_MODE_MANUAL. + */ + K4A_COLOR_CONTROL_SATURATION, + + /** Sharpness setting. + * + * \details + * May only be set to ::K4A_COLOR_CONTROL_MODE_MANUAL. + */ + K4A_COLOR_CONTROL_SHARPNESS, + + /** White balance setting. + * + * \details + * May be set to ::K4A_COLOR_CONTROL_MODE_AUTO or ::K4A_COLOR_CONTROL_MODE_MANUAL. + * + * \details + * The unit is degrees Kelvin. The setting must be set to a value evenly divisible by 10 degrees. + */ + K4A_COLOR_CONTROL_WHITEBALANCE, + + /** Backlight compensation setting. + * + * \details + * May only be set to ::K4A_COLOR_CONTROL_MODE_MANUAL. + * + * \details + * Value of 0 means backlight compensation is disabled. Value of 1 means backlight compensation is enabled. + */ + K4A_COLOR_CONTROL_BACKLIGHT_COMPENSATION, + + /** Gain setting. + * + * \details + * May only be set to ::K4A_COLOR_CONTROL_MODE_MANUAL. + */ + K4A_COLOR_CONTROL_GAIN, + + /** Powerline frequency setting. + * + * \details + * May only be set to ::K4A_COLOR_CONTROL_MODE_MANUAL. + * + * \details + * Value of 1 sets the powerline compensation to 50 Hz. Value of 2 sets the powerline compensation to 60 Hz. + */ + K4A_COLOR_CONTROL_POWERLINE_FREQUENCY +} k4a_color_control_command_t; + +/** Color sensor control mode + * + * \remarks + * The current settings can be read with k4a_device_get_color_control(). The settings can be set with + * k4a_device_set_color_control(). + * + * \see k4a_color_control_command_t + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef enum +{ + K4A_COLOR_CONTROL_MODE_AUTO = 0, /**< set the associated k4a_color_control_command_t to auto*/ + K4A_COLOR_CONTROL_MODE_MANUAL, /**< set the associated k4a_color_control_command_t to manual*/ +} k4a_color_control_mode_t; + +/** Synchronization mode when connecting two or more devices together. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef enum +{ + K4A_WIRED_SYNC_MODE_STANDALONE, /**< Neither 'Sync In' or 'Sync Out' connections are used. */ + K4A_WIRED_SYNC_MODE_MASTER, /**< The 'Sync Out' jack is enabled and synchronization data it driven out the + connected wire. While in master mode the color camera must be enabled as part of the + multi device sync signalling logic. Even if the color image is not needed, the color + camera must be running.*/ + K4A_WIRED_SYNC_MODE_SUBORDINATE /**< The 'Sync In' jack is used for synchronization and 'Sync Out' is driven for the + next device in the chain. 'Sync Out' is a mirror of 'Sync In' for this mode. + */ +} k4a_wired_sync_mode_t; + +/** Calibration types. + * + * Specifies a type of calibration. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef enum +{ + K4A_CALIBRATION_TYPE_UNKNOWN = -1, /**< Calibration type is unknown */ + K4A_CALIBRATION_TYPE_DEPTH, /**< Depth sensor */ + K4A_CALIBRATION_TYPE_COLOR, /**< Color sensor */ + K4A_CALIBRATION_TYPE_GYRO, /**< Gyroscope sensor */ + K4A_CALIBRATION_TYPE_ACCEL, /**< Accelerometer sensor */ + K4A_CALIBRATION_TYPE_NUM, /**< Number of types excluding unknown type*/ +} k4a_calibration_type_t; + +/** Calibration model type. + * + * The model used interpret the calibration parameters. + * + * \remarks + * Azure Kinect devices are calibrated with Brown Conrady. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef enum +{ + K4A_CALIBRATION_LENS_DISTORTION_MODEL_UNKNOWN = 0, /**< Calibration model is unknown */ + K4A_CALIBRATION_LENS_DISTORTION_MODEL_THETA, /**< Deprecated (not supported). Calibration model is Theta (arctan). + */ + K4A_CALIBRATION_LENS_DISTORTION_MODEL_POLYNOMIAL_3K, /**< Deprecated (not supported). Calibration model is + Polynomial 3K. */ + K4A_CALIBRATION_LENS_DISTORTION_MODEL_RATIONAL_6KT, /**< Deprecated (only supported early internal devices). + Calibration model is Rational 6KT. */ + K4A_CALIBRATION_LENS_DISTORTION_MODEL_BROWN_CONRADY, /**< Calibration model is Brown Conrady (compatible with + * OpenCV) */ +} k4a_calibration_model_type_t; + +/** Firmware build type. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef enum +{ + K4A_FIRMWARE_BUILD_RELEASE, /**< Production firmware. */ + K4A_FIRMWARE_BUILD_DEBUG /**< Pre-production firmware. */ +} k4a_firmware_build_t; + +/** Firmware signature type. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef enum +{ + K4A_FIRMWARE_SIGNATURE_MSFT, /**< Microsoft signed firmware. */ + K4A_FIRMWARE_SIGNATURE_TEST, /**< Test signed firmware. */ + K4A_FIRMWARE_SIGNATURE_UNSIGNED /**< Unsigned firmware. */ +} k4a_firmware_signature_t; + +/** + * + * @} + * + * \defgroup Macros Macros + * \ingroup csdk + * + * Public macros for API consumers. + * + * @{ + */ + +/** Validate that a k4a_result_t is successful. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +#define K4A_SUCCEEDED(_result_) (_result_ == K4A_RESULT_SUCCEEDED) + +/** Validate that a k4a_result_t is failed. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +#define K4A_FAILED(_result_) (!K4A_SUCCEEDED(_result_)) + +/** + * + * @} + * + * \defgroup Logging Error and event logging + * + * The SDK can log data to the console, files, or to a custom handler. + * + * Environment Variables: + * + * K4A_ENABLE_LOG_TO_A_FILE / K4A_RECORD_ENABLE_LOG_TO_A_FILE + * Specifies the log file to save the log to. K4a.dll and k4arecord.dll can not log to the same file. + * + * K4A_ENABLE_LOG_TO_A_FILE = + * K4A_RECORD_ENABLE_LOG_TO_A_FILE = + * 0 - completely disable logging to a file + * log\custom.log - log all messages to the path and file specified - must end in '.log' to + * be considered a valid entry + * NOTE 1: When enabled this takes precedence over the value of K4A_ENABLE_LOG_TO_STDOUT. + * NOTE 2: This can not be set to the same value as K4A_RECORD_ENABLE_LOG_TO_A_FILE as they represent separate + * logger instance that do not allowed shared access to the file being written to. + * + * K4A_ENABLE_LOG_TO_STDOUT = + * 0 - disable logging to stdout + * all else - log all messages to stdout + * + * K4A_LOG_LEVEL = + * 'c' - log all messages of level 'critical' criticality + * 'e' - log all messages of level 'error' or higher criticality + * 'w' - log all messages of level 'warning' or higher criticality + * 'i' - log all messages of level 'info' or higher criticality + * 't' - log all messages of level 'trace' or higher criticality + * DEFAULT - log all message of level 'error' or higher criticality + * + * See remarks section of \p k4a_set_debug_message_handler + * + * @{ + * + * + */ + +/** + * + * @} + * + * \defgroup Prototypes Callback Function prototypes + * \ingroup csdk + * + * Prototypes used in callbacks. + * + * @{ + */ + +/** Callback function for debug messages being generated by the Azure Kinect SDK. + * + * \param context + * The context of the callback function. This is the context that was supplied by the caller to \p + * k4a_set_debug_message_handler. + * + * \param level + * The level of the message that has been created. + * + * \param file + * The file name of the source file that generated the message. + * + * \param line + * The line number of the source file that generated the message. + * + * \param message + * The messaged generated by the Azure Kinect SDK. + * + * \remarks + * The callback is called asynchronously when the Azure Kinext SDK generates a message at a \p level that is equal to + * or more critical than the level specified when calling \ref k4a_set_debug_message_handler() to register the callback. + * + * \remarks + * This callback can occur from any thread and blocks the calling thread. The k4a_logging_message_cb_t function user + * must protect it's logging resources from concurrent calls. All care should be made to minimize the amount of time + * locks are held. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + * + */ +typedef void(k4a_logging_message_cb_t)(void *context, + k4a_log_level_t level, + const char *file, + const int line, + const char *message); + +/** Callback function for a memory object being destroyed. + * + * \param buffer + * The buffer pointer that was supplied by the caller as \p buffer_release_cb to \ref k4a_image_create_from_buffer(). + * + * \param context + * The context for the memory object that needs to be destroyed that was supplied by the caller as \p + * buffer_release_cb_context to \ref k4a_image_create_from_buffer(). + * + * \remarks + * When all references for the memory object are released, this callback will be invoked as the final destroy for the + * given memory. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + * + */ +typedef void(k4a_memory_destroy_cb_t)(void *buffer, void *context); + +/** Callback function for a memory allocation. + * + * \param size + * Minimum size in bytes needed for the buffer. + * + * \param context + * Output parameter for a context that will be provided in the subsequent call to the \ref k4a_memory_destroy_cb_t + * callback. + * + * \return + * A pointer to the newly allocated memory. + * + * \remarks + * A callback of this type is provided when there is an application defined allocator. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + * + */ +typedef uint8_t *(k4a_memory_allocate_cb_t)(int size, void **context); + +/** + * + * @} + * + * \defgroup Structures Structures + * \ingroup csdk + * + * Structures used in the API. + * + * @{ + */ + +/** Configuration parameters for an Azure Kinect device. + * + * \remarks + * Used by k4a_device_start_cameras() to specify the configuration of the data capture. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef struct _k4a_device_configuration_t +{ + /** Image format to capture with the color camera. + * + * The color camera does not natively produce BGRA32 images. + * Setting ::K4A_IMAGE_FORMAT_COLOR_BGRA32 for color_format will result in higher CPU utilization. */ + k4a_image_format_t color_format; + + /** Image resolution to capture with the color camera. */ + k4a_color_resolution_t color_resolution; + + /** Capture mode for the depth camera. */ + k4a_depth_mode_t depth_mode; + + /** Desired frame rate for the color and depth camera. */ + k4a_fps_t camera_fps; + + /** Only produce k4a_capture_t objects if they contain synchronized color and depth images. + * + * \details + * This setting controls the behavior in which images are dropped when images are produced faster than they can be + * read, or if there are errors in reading images from the device. + * + * \details + * If set to true, \ref k4a_capture_t objects will only be produced with both color and depth images. + * If set to false, \ref k4a_capture_t objects may be produced only a single image when the corresponding image is + * dropped. + * + * \details + * Setting this to false ensures that the caller receives all of the images received from the camera, regardless of + * whether the corresponding images expected in the capture are available. + * + * \details + * If either the color or depth camera are disabled, this setting has no effect. + */ + bool synchronized_images_only; + + /** + * Desired delay between the capture of the color image and the capture of the depth image. + * + * \details + * A negative value indicates that the depth image should be captured before the color image. + * + * \details + * Any value between negative and positive one capture period is valid. + */ + int32_t depth_delay_off_color_usec; + + /** The external synchronization mode. */ + k4a_wired_sync_mode_t wired_sync_mode; + + /** + * The external synchronization timing. + * + * If this camera is a subordinate, this sets the capture delay between the color camera capture and the external + * input pulse. A setting of zero indicates that the master and subordinate color images should be aligned. + * + * This setting does not effect the 'Sync out' connection. + * + * This value must be positive and range from zero to one capture period. + * + * If this is not a subordinate, then this value is ignored. */ + uint32_t subordinate_delay_off_master_usec; + + /** + * Streaming indicator automatically turns on when the color or depth camera's are in use. + * + * This setting disables that behavior and keeps the LED in an off state. */ + bool disable_streaming_indicator; +} k4a_device_configuration_t; + +/** Extrinsic calibration data. + * + * \remarks + * Extrinsic calibration defines the physical relationship between two separate devices. + * + * \relates k4a_calibration_camera_t + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef struct _k4a_calibration_extrinsics_t +{ + float rotation[9]; /**< 3x3 Rotation matrix stored in row major order */ + float translation[3]; /**< Translation vector, x,y,z (in millimeters) */ +} k4a_calibration_extrinsics_t; + +/** Camera intrinsic calibration data. + * + * \remarks + * Intrinsic calibration represents the internal optical properties of the camera. + * + * \remarks + * Azure Kinect devices are calibrated with Brown Conrady which is compatible + * with OpenCV. + * + * \relates k4a_calibration_camera_t + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef union +{ + /** individual parameter or array representation of intrinsic model. */ + struct _param + { + float cx; /**< Principal point in image, x */ + float cy; /**< Principal point in image, y */ + float fx; /**< Focal length x */ + float fy; /**< Focal length y */ + float k1; /**< k1 radial distortion coefficient */ + float k2; /**< k2 radial distortion coefficient */ + float k3; /**< k3 radial distortion coefficient */ + float k4; /**< k4 radial distortion coefficient */ + float k5; /**< k5 radial distortion coefficient */ + float k6; /**< k6 radial distortion coefficient */ + float codx; /**< Center of distortion in Z=1 plane, x (only used for Rational6KT) */ + float cody; /**< Center of distortion in Z=1 plane, y (only used for Rational6KT) */ + float p2; /**< Tangential distortion coefficient 2 */ + float p1; /**< Tangential distortion coefficient 1 */ + float metric_radius; /**< Metric radius */ + } param; /**< Individual parameter representation of intrinsic model */ + float v[15]; /**< Array representation of intrinsic model parameters */ +} k4a_calibration_intrinsic_parameters_t; + +/** Camera sensor intrinsic calibration data. + * + * \remarks + * Intrinsic calibration represents the internal optical properties of the camera. + * + * \remarks + * Azure Kinect devices are calibrated with Brown Conrady which is compatible + * with OpenCV. + * + * \relates k4a_calibration_camera_t + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef struct _k4a_calibration_intrinsics_t +{ + k4a_calibration_model_type_t type; /**< Type of calibration model used*/ + unsigned int parameter_count; /**< Number of valid entries in parameters*/ + k4a_calibration_intrinsic_parameters_t parameters; /**< Calibration parameters*/ +} k4a_calibration_intrinsics_t; + +/** Camera calibration contains intrinsic and extrinsic calibration information for a camera. + * + * \relates k4a_calibration_camera_t + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef struct _k4a_calibration_camera_t +{ + k4a_calibration_extrinsics_t extrinsics; /**< Extrinsic calibration data. */ + k4a_calibration_intrinsics_t intrinsics; /**< Intrinsic calibration data. */ + int resolution_width; /**< Resolution width of the calibration sensor. */ + int resolution_height; /**< Resolution height of the calibration sensor. */ + float metric_radius; /**< Max FOV of the camera. */ +} k4a_calibration_camera_t; + +/** Calibration type representing device calibration. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef struct _k4a_calibration_t +{ + k4a_calibration_camera_t depth_camera_calibration; /**< Depth camera calibration. */ + + k4a_calibration_camera_t color_camera_calibration; /**< Color camera calibration. */ + + /** Extrinsic transformation parameters. + * + * The extrinsic parameters allow 3D coordinate conversions between depth camera, color camera, the IMU's gyroscope + * and accelerometer. To transform from a source to a target 3D coordinate system, use the parameters stored + * under extrinsics[source][target]. + */ + k4a_calibration_extrinsics_t extrinsics[K4A_CALIBRATION_TYPE_NUM][K4A_CALIBRATION_TYPE_NUM]; + + k4a_depth_mode_t depth_mode; /**< Depth camera mode for which calibration was obtained. */ + k4a_color_resolution_t color_resolution; /**< Color camera resolution for which calibration was obtained. */ +} k4a_calibration_t; + +/** Version information. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef struct _k4a_version_t +{ + uint32_t major; /**< Major version; represents a breaking change. */ + uint32_t minor; /**< Minor version; represents additional features, no regression from lower versions with same + major version. */ + uint32_t iteration; /**< Reserved. */ +} k4a_version_t; + +/** Structure to define hardware version. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef struct _k4a_hardware_version_t +{ + k4a_version_t rgb; /**< Color camera firmware version. */ + k4a_version_t depth; /**< Depth camera firmware version. */ + k4a_version_t audio; /**< Audio device firmware version. */ + k4a_version_t depth_sensor; /**< Depth sensor firmware version. */ + + k4a_firmware_build_t firmware_build; /**< Build type reported by the firmware. */ + k4a_firmware_signature_t firmware_signature; /**< Signature type of the firmware. */ +} k4a_hardware_version_t; + +/** Two dimensional floating point vector. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef union +{ + /** XY or array representation of vector */ + struct _xy + { + float x; /**< X component of a vector */ + float y; /**< Y component of a vector */ + } xy; /**< X, Y representation of a vector */ + float v[2]; /**< Array representation of a vector */ +} k4a_float2_t; + +/** Three dimensional floating point vector. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef union +{ + /** XYZ or array representation of vector. */ + struct _xyz + { + float x; /**< X component of a vector. */ + float y; /**< Y component of a vector. */ + float z; /**< Z component of a vector. */ + } xyz; /**< X, Y, Z representation of a vector. */ + float v[3]; /**< Array representation of a vector. */ +} k4a_float3_t; + +/** IMU sample. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +typedef struct _k4a_imu_sample_t +{ + float temperature; /**< Temperature reading of this sample (Celsius). */ + k4a_float3_t acc_sample; /**< Accelerometer sample in meters per second squared. */ + uint64_t acc_timestamp_usec; /**< Timestamp of the accelerometer in microseconds. */ + k4a_float3_t gyro_sample; /**< Gyro sample in radians per second. */ + uint64_t gyro_timestamp_usec; /**< Timestamp of the gyroscope in microseconds */ +} k4a_imu_sample_t; + +/** + * + * @} + * + * \defgroup Definitions Definitions + * \ingroup csdk + * + * Definition of constant values. + * + * @{ + */ + +/** Default device index. + * + * Passed as an argument to \ref k4a_device_open() to open the default sensor + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +#define K4A_DEVICE_DEFAULT (0) + +/** An infinite wait time for functions that take a timeout parameter. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +#define K4A_WAIT_INFINITE (-1) + +/** Initial configuration setting for disabling all sensors. + * + * \remarks + * Use this setting to initialize a \ref k4a_device_configuration_t to a disabled state. + * + * \xmlonly + * + * k4atypes.h (include k4a/k4a.h) + * + * \endxmlonly + */ +static const k4a_device_configuration_t K4A_DEVICE_CONFIG_INIT_DISABLE_ALL = { K4A_IMAGE_FORMAT_COLOR_MJPG, + K4A_COLOR_RESOLUTION_OFF, + K4A_DEPTH_MODE_OFF, + K4A_FRAMES_PER_SECOND_30, + false, + 0, + K4A_WIRED_SYNC_MODE_STANDALONE, + 0, + false }; + +/** + * @} + */ + +#ifdef __cplusplus +} +#endif + +#endif /* K4ATYPES_H */ diff --git a/k4a-sys/vendor/include/windows/k4a/k4aversion.h b/k4a-sys/vendor/include/windows/k4a/k4aversion.h new file mode 100644 index 0000000000..da8ec264c9 --- /dev/null +++ b/k4a-sys/vendor/include/windows/k4a/k4aversion.h @@ -0,0 +1,16 @@ +/* Copyright (c) Microsoft Corporation. All rights reserved. + Licensed under the MIT License. */ + +#ifndef K4AVERSION_H +#define K4AVERSION_H + +#define K4A_VERSION_MAJOR 1 +#define K4A_VERSION_MINOR 3 +#define K4A_VERSION_PATCH 0 +#define K4A_VERSION_PRERELEASE "" +#define K4A_VERSION_BUILD_METADATA "" + +#define K4A_VERSION_STR "1.3.0" + +#endif + diff --git a/k4a-sys/vendor/include/windows/k4arecord/k4arecord_export.h b/k4a-sys/vendor/include/windows/k4arecord/k4arecord_export.h new file mode 100644 index 0000000000..290ef48f64 --- /dev/null +++ b/k4a-sys/vendor/include/windows/k4arecord/k4arecord_export.h @@ -0,0 +1,42 @@ + +#ifndef K4ARECORD_EXPORT_H +#define K4ARECORD_EXPORT_H + +#ifdef K4ARECORD_STATIC_DEFINE +# define K4ARECORD_EXPORT +# define K4ARECORD_NO_EXPORT +#else +# ifndef K4ARECORD_EXPORT +# ifdef k4arecord_EXPORTS + /* We are building this library */ +# define K4ARECORD_EXPORT __declspec(dllexport) +# else + /* We are using this library */ +# define K4ARECORD_EXPORT __declspec(dllimport) +# endif +# endif + +# ifndef K4ARECORD_NO_EXPORT +# define K4ARECORD_NO_EXPORT +# endif +#endif + +#ifndef K4ARECORD_DEPRECATED +# define K4ARECORD_DEPRECATED __declspec(deprecated) +#endif + +#ifndef K4ARECORD_DEPRECATED_EXPORT +# define K4ARECORD_DEPRECATED_EXPORT K4ARECORD_EXPORT K4ARECORD_DEPRECATED +#endif + +#ifndef K4ARECORD_DEPRECATED_NO_EXPORT +# define K4ARECORD_DEPRECATED_NO_EXPORT K4ARECORD_NO_EXPORT K4ARECORD_DEPRECATED +#endif + +#if 0 /* DEFINE_NO_DEPRECATED */ +# ifndef K4ARECORD_NO_DEPRECATED +# define K4ARECORD_NO_DEPRECATED +# endif +#endif + +#endif /* K4ARECORD_EXPORT_H */ diff --git a/k4a-sys/vendor/include/windows/k4arecord/playback.h b/k4a-sys/vendor/include/windows/k4arecord/playback.h new file mode 100644 index 0000000000..6502ea8fa3 --- /dev/null +++ b/k4a-sys/vendor/include/windows/k4arecord/playback.h @@ -0,0 +1,917 @@ +/** \file playback.h + * Copyright (c) Microsoft Corporation. All rights reserved. + * Licensed under the MIT License. + * Kinect For Azure Recording Playback SDK. + */ + +#ifndef K4A_PLAYBACK_H +#define K4A_PLAYBACK_H + +#include +#include + +#ifdef __cplusplus + +extern "C" { +#endif + +/** + * + * \addtogroup Functions + * + * @{ + */ + +/** Opens an existing recording file for reading. + * + * \param path + * Filesystem path of the existing recording. + * + * \param playback_handle + * If successful, this contains a pointer to the recording handle. Caller must call k4a_playback_close() when + * finished with the recording. + * + * \headerfile playback.h + * + * \returns ::K4A_RESULT_SUCCEEDED is returned on success + * + * \relates k4a_playback_t + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_result_t k4a_playback_open(const char *path, k4a_playback_t *playback_handle); + +/** Get the raw calibration blob for the Azure Kinect device used during recording. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param data + * Location to write the calibration data to. This field may optionally be set to NULL if the caller wants to query for + * the needed data size. + * + * \param data_size + * On passing \p data_size into the function this variable represents the available size to write the raw data to. On + * return this variable is updated with the amount of data actually written to the buffer. + * + * \returns + * ::K4A_BUFFER_RESULT_SUCCEEDED if \p data was successfully written. If \p data_size points to a buffer size that is + * too small to hold the output, ::K4A_BUFFER_RESULT_TOO_SMALL is returned and \p data_size is updated to contain the + * minimum buffer size needed to capture the calibration data. + * + * \remarks + * The raw calibration may not exist if the device was not specified during recording. + * + * \relates k4a_playback_t + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_buffer_result_t k4a_playback_get_raw_calibration(k4a_playback_t playback_handle, + uint8_t *data, + size_t *data_size); + +/** Get the camera calibration for Azure Kinect device used during recording. The output struct is used as input to all + * transformation functions. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param calibration + * Location to write the calibration. + * + * \returns + * ::K4A_RESULT_SUCCEEDED if \p calibration was successfully written. ::K4A_RESULT_FAILED otherwise. + * + * \remarks + * The calibration may not exist if the device was not specified during recording. + * + * \relates k4a_playback_t + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_result_t k4a_playback_get_calibration(k4a_playback_t playback_handle, + k4a_calibration_t *calibration); + +/** Get the device configuration used during recording. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param config + * Location to write the recording configuration. + * + * \returns + * ::K4A_RESULT_SUCCEEDED if \p config was successfully written. ::K4A_RESULT_FAILED otherwise. + * + * \relates k4a_playback_t + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_result_t k4a_playback_get_record_configuration(k4a_playback_t playback_handle, + k4a_record_configuration_t *config); + +/** Checks whether a track with the given track name exists in the playback file. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param track_name + * The track name to be checked to see whether it exists or not. + * + * \returns true if the track exists. + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT bool k4a_playback_check_track_exists(k4a_playback_t playback_handle, const char *track_name); + +/** Get the number of tracks in a playback file. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \returns the number of tracks in the playback file. + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT size_t k4a_playback_get_track_count(k4a_playback_t playback_handle); + +/** Gets the name of a track at a specific index. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param track_index + * The index of the track to read the name form. + * + * \param track_name + * Location to write the track name. This will be a UTF8 null terminated string. If a NULL buffer is specified, + * \p track_name_size will be set to the size of buffer needed to store the string. + * + * \param track_name_size + * On input, the size of the \p track_name buffer. On output, this is set to the length of the track_name value + * (including the null terminator). + * + * \returns + * A return of ::K4A_BUFFER_RESULT_SUCCEEDED means that the \p track_name has been filled in. If the buffer is too small + * the function returns ::K4A_BUFFER_RESULT_TOO_SMALL and the needed size of the \p track_name buffer is returned in the + * \p track_name_size parameter. ::K4A_BUFFER_RESULT_FAILED is returned if the track index does not exist. All other + * failures return ::K4A_BUFFER_RESULT_FAILED. + * + * \remarks + * When used along with k4a_playback_get_track_count(), this function can be used to enumerate all the available tracks + * in a playback file. Additionally k4a_playback_track_is_builtin() can be used to filter custom tracks. + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_buffer_result_t k4a_playback_get_track_name(k4a_playback_t playback_handle, + size_t track_index, + char *track_name, + size_t *track_name_size); + +/** Checks whether a track is one of the built-in tracks: "COLOR", "DEPTH", etc... + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param track_name + * The track name to be checked to see whether it is a built-in track. + * + * \returns true if the track is built-in. If the provided track name does not exist, false will be returned. + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT bool k4a_playback_track_is_builtin(k4a_playback_t playback_handle, const char *track_name); + +/** Gets the video-specific track information for a particular video track. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param track_name + * The track name to read video settings from. + * + * \param video_settings + * Location to write the track's video settings. + * + * \returns ::K4A_RESULT_SUCCEEDED is returned on success, ::K4A_RESULT_FAILED is returned if the specified track does + * not exist or is not a video track. + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_result_t k4a_playback_track_get_video_settings(k4a_playback_t playback_handle, + const char *track_name, + k4a_record_video_settings_t *video_settings); + +/** Gets the codec id string for a particular track. + * + * The codec ID is a string that corresponds to the codec of the track's data. Some of the existing formats are listed + * here: https://www.matroska.org/technical/specs/codecid/index.html. It can also be custom defined by the user. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param track_name + * The track name to read the codec id from. + * + * \param codec_id + * Location to write the codec id. This will be a UTF8 null terminated string. If a NULL buffer is specified, + * \p codec_id_size will be set to the size of buffer needed to store the string. + * + * \param codec_id_size + * On input, the size of the \p codec_id buffer. On output, this is set to the length of the codec_id value (including + * the null terminator). + * + * \returns + * A return of ::K4A_BUFFER_RESULT_SUCCEEDED means that the \p codec_id has been filled in. If the buffer is too small + * the function returns ::K4A_BUFFER_RESULT_TOO_SMALL and the needed size of the \p codec_id buffer is returned in the + * \p codec_id_size parameter. ::K4A_BUFFER_RESULT_FAILED is returned if the track_name does not exist. All other + * failures return ::K4A_BUFFER_RESULT_FAILED. + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_buffer_result_t k4a_playback_track_get_codec_id(k4a_playback_t playback_handle, + const char *track_name, + char *codec_id, + size_t *codec_id_size); + +/** Gets the codec context for a particular track. + * + * The codec context is a codec-specific buffer that contains any required codec metadata that is only known to the + * codec. It is mapped to the matroska Codec Private field. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param track_name + * The track name to read the codec context from. + * + * \param codec_context + * Location to write the codec context data. If a NULL buffer is specified, \p codec_context_size will be set to the + * size of buffer needed to store the data. + * + * \param codec_context_size + * On input, the size of the \p codec_context buffer. On output, this is set to the length of the codec_context data. + * + * \returns + * A return of ::K4A_BUFFER_RESULT_SUCCEEDED means that the \p codec_context has been filled in. If the buffer is too + * small the function returns ::K4A_BUFFER_RESULT_TOO_SMALL and the needed size of the \p codec_context buffer is + * returned in the \p codec_context_size parameter. ::K4A_BUFFER_RESULT_FAILED is returned if the track_name does not + * exist. All other failures return ::K4A_BUFFER_RESULT_FAILED. + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_buffer_result_t k4a_playback_track_get_codec_context(k4a_playback_t playback_handle, + const char *track_name, + uint8_t *codec_context, + size_t *codec_context_size); + +/** Read the value of a tag from a recording. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param name + * The name of the tag to read. + * + * \param value + * Location to write the tag value. This will be a UTF8 null terminated string. If a NULL buffer is specified, + * \p value_size will be set to the size of buffer needed to store the string. + * + * \param value_size + * On input, the size of the \p value buffer. On output, this is set to the length of the tag value (including the null + * terminator). + * + * \returns + * A return of ::K4A_BUFFER_RESULT_SUCCEEDED means that the \p value has been filled in. If the buffer is too small the + * function returns ::K4A_BUFFER_RESULT_TOO_SMALL and the needed size of the \p value buffer is returned in the + * \p value_size parameter. ::K4A_BUFFER_RESULT_FAILED is returned if the tag does not exist. All other failures return + * ::K4A_BUFFER_RESULT_FAILED. + * + * \remarks + * Tags are global to a file, and should store data related to the entire recording, such as camera configuration or + * recording location. + * + * \relates k4a_playback_t + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_buffer_result_t k4a_playback_get_tag(k4a_playback_t playback_handle, + const char *name, + char *value, + size_t *value_size); + +/** Set the image format that color captures will be converted to. By default the conversion format will be the same as + * the image format stored in the recording file, and no conversion will occur. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param target_format + * The target image format to be returned in captures. + * + * \returns + * ::K4A_RESULT_SUCCEEDED if the format conversion is supported. ::K4A_RESULT_FAILED otherwise. + * + * \remarks + * After the color conversion format is set, all \ref k4a_capture_t objects returned from the playback handle will have + * their color images converted to the \p target_format. + * + * \remarks + * Color format conversion occurs in the user-thread, so setting \p target_format to anything other than the format + * stored in the file may significantly increase the latency of \p k4a_playback_get_next_capture() and + * \p k4a_playback_get_previous_capture(). + * + * \relates k4a_playback_t + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_result_t k4a_playback_set_color_conversion(k4a_playback_t playback_handle, + k4a_image_format_t target_format); + +/** Reads an attachment file from a recording. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param file_name + * The attachment file name. + * + * \param data + * Location to write the attachment data. If a NULL buffer is specified, \p data_size will be set to the size of + * buffer needed to store the data. + * + * \param data_size + * On input, the size of the \p data buffer. On output, this is set to the length of the attachment data. + * + * \returns + * A return of ::K4A_BUFFER_RESULT_SUCCEEDED means that the \p data has been filled in. If the buffer is too small the + * function returns ::K4A_BUFFER_RESULT_TOO_SMALL and the needed size of the \p data buffer is returned in the + * \p data_size parameter. ::K4A_BUFFER_RESULT_FAILED is returned if the attachment \p file_name does not exist. All + * other failures return ::K4A_BUFFER_RESULT_FAILED. + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_buffer_result_t k4a_playback_get_attachment(k4a_playback_t playback_handle, + const char *file_name, + uint8_t *data, + size_t *data_size); + +/** Read the next capture in the recording sequence. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param capture_handle + * If successful this contains a handle to a capture object. Caller must call k4a_capture_release() when its done using + * this capture + * + * \returns + * ::K4A_STREAM_RESULT_SUCCEEDED if a capture is returned, or ::K4A_STREAM_RESULT_EOF if the end of the recording is + * reached. All other failures will return ::K4A_STREAM_RESULT_FAILED. + * + * \relates k4a_playback_t + * + * \remarks + * k4a_playback_get_next_capture() always returns the next capture in sequence after the most recently returned capture. + * + * \remarks + * The first call to k4a_playback_get_next_capture() after k4a_playback_seek_timestamp() will return the capture + * in the recording closest to the seek time with an image timestamp greater than or equal to the seek time. + * + * \remarks + * If a call was made to k4a_playback_get_previous_capture() that returned ::K4A_STREAM_RESULT_EOF, the playback + * position is at the beginning of the stream and k4a_playback_get_next_capture() will return the first capture in the + * recording. + * + * \remarks + * Capture objects returned by the playback API will always contain at least one image, but may have images missing if + * frames were dropped in the original recording. When calling k4a_capture_get_color_image(), + * k4a_capture_get_depth_image(), or k4a_capture_get_ir_image(), the image should be checked for NULL. + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_stream_result_t k4a_playback_get_next_capture(k4a_playback_t playback_handle, + k4a_capture_t *capture_handle); + +/** Read the previous capture in the recording sequence. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param capture_handle + * If successful this contains a handle to a capture object. Caller must call k4a_capture_release() when its done using + * this capture. + * + * \returns + * ::K4A_STREAM_RESULT_SUCCEEDED if a capture is returned, or ::K4A_STREAM_RESULT_EOF if the start of the recording is + * reached. All other failures will return ::K4A_STREAM_RESULT_FAILED. + * + * \relates k4a_playback_t + * + * \remarks + * k4a_playback_get_previous_capture() always returns the previous capture in the sequence before the most + * recently returned capture. + * + * \remarks + * If a call was made to k4a_playback_get_next_capture() that returned ::K4A_STREAM_RESULT_EOF, the playback position + * is at the end of the stream and k4a_playback_get_previous_capture() will return the last capture in + * the recording. + * + * \remarks + * The first call to k4a_playback_get_previous_capture() after k4a_playback_seek_timestamp() will return the + * capture in the recording closest to the seek time with all image timestamps less than the seek time. + * + * \remarks + * Capture objects returned by this API will always contain at least one image, but may have images missing if frames + * were dropped in the original recording. When calling k4a_capture_get_color_image(), k4a_capture_get_depth_image(), or + * k4a_capture_get_ir_image(), the image should be checked for NULL. + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_stream_result_t k4a_playback_get_previous_capture(k4a_playback_t playback_handle, + k4a_capture_t *capture_handle); + +/** Read the next IMU sample in the recording sequence. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param imu_sample + * The location to write the IMU sample. + * + * \returns + * ::K4A_STREAM_RESULT_SUCCEEDED if a sample is returned, or ::K4A_STREAM_RESULT_EOF if the end of the recording is + * reached. All other failures will return ::K4A_STREAM_RESULT_FAILED. + * + * \relates k4a_playback_t + * + * \remarks + * k4a_playback_get_next_imu_sample() always returns the IMU sample after the most recently returned sample. + * + * \remarks + * If a call was made to k4a_playback_get_previous_imu_sample() which returned ::K4A_STREAM_RESULT_EOF, then the + * playback position is at the beginning of the recording and k4a_playback_get_next_imu_sample() will return the first + * IMU sample in the recording. + * + * \remarks + * The first call to k4a_playback_get_next_imu_sample() after k4a_playback_seek_timestamp() will return the IMU + * sample in the recording closest to the seek time with a timestamp greater than or equal to the seek time. + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_stream_result_t k4a_playback_get_next_imu_sample(k4a_playback_t playback_handle, + k4a_imu_sample_t *imu_sample); + +/** Read the previous IMU sample in the recording sequence. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param imu_sample [OUT] + * The location to write the IMU sample. + * + * \returns + * ::K4A_STREAM_RESULT_SUCCEEDED if a sample is returned, or ::K4A_STREAM_RESULT_EOF if the start of the recording is + * reached. All other failures will return ::K4A_STREAM_RESULT_FAILED. + * + * \relates k4a_playback_t + * + * \remarks + * k4a_playback_get_previous_imu_sample() always returns the IMU sample before the most recently returned sample. + * + * \remarks + * If a call was made to to k4a_playback_get_next_imu_sample() which returned ::K4A_STREAM_RESULT_EOF, then the playback + * position is at the end of the recording and k4a_playback_get_previous_imu_sample() will return the last IMU sample in + * the recording. + * + * \remarks + * The first call to k4a_playback_get_previous_imu_sample() after k4a_playback_seek_timestamp() will return the + * IMU sample closest to the seek time with a timestamp less than the seek time. + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_stream_result_t k4a_playback_get_previous_imu_sample(k4a_playback_t playback_handle, + k4a_imu_sample_t *imu_sample); + +/** Read the next data block for a particular track. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param track_name + * The name of the track to read the next data block from. + * + * \param data_block_handle + * The location to write the data block handle. + * + * \returns + * ::K4A_STREAM_RESULT_SUCCEEDED if a data block is returned, or ::K4A_STREAM_RESULT_EOF if the end of the recording is + * reached. All other failures will return ::K4A_STREAM_RESULT_FAILED. + * + * \relates k4a_playback_t + * + * \remarks + * k4a_playback_get_next_data_block() always returns the data block after the most recently returned data block for a + * particular track. + * + * \remarks + * If a call was made to k4a_playback_get_previous_data_block() which returned ::K4A_STREAM_RESULT_EOF, then the + * playback position is at the beginning of the recording and calling k4a_playback_get_next_data_block() with the same + * track will return the first data block in the track. + * + * \remarks + * The first call to k4a_playback_get_next_data_block() after k4a_playback_seek_timestamp() will return the data + * block in the recording closest to the seek time with a timestamp greater than or equal to the seek time. + * + * \remarks + * k4a_playback_get_next_data_block() cannot be used with the built-in tracks: "COLOR", "DEPTH", etc... + * k4a_playback_track_is_builtin() can be used to determine if a track is a built-in track. + * + * \remarks + * If the call is successful, callers must call k4a_playback_data_block_release() to return the allocated memory for + * data_block_handle. + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_stream_result_t k4a_playback_get_next_data_block(k4a_playback_t playback_handle, + const char *track_name, + k4a_playback_data_block_t *data_block_handle); + +/** Read the previous data block for a particular track. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param track_name + * The name of the track to read the previous data block from. + * + * \param data_block_handle + * The location to write the data block. + * + * \returns + * ::K4A_STREAM_RESULT_SUCCEEDED if a sample is returned, or ::K4A_STREAM_RESULT_EOF if the start of the recording is + * reached. All other failures will return ::K4A_STREAM_RESULT_FAILED. + * + * \relates k4a_playback_t + * + * \remarks + * k4a_playback_get_previous_data_block() always returns the data block before the most recently returned data block for + * a particular track. + * + * \remarks + * If a call was made to to k4a_playback_get_next_data_block() which returned ::K4A_STREAM_RESULT_EOF, then the playback + * position is at the end of the recording and calling k4a_playback_get_previous_data_block() with the same track will + * return the last data block in the track. + * + * \remarks + * The first call to k4a_playback_get_previous_data_block() after k4a_playback_seek_timestamp() will return the + * data block closest to the seek time with a timestamp less than the seek time. + * + * \remarks + * If the call is successful, callers must call k4a_playback_data_block_release() to return the allocated memory for + * data_block_handle. + * + * \remarks + * k4a_playback_get_previous_data_block() cannot be used with the built-in tracks: "COLOR", "DEPTH", etc... + * k4a_playback_track_is_builtin() can be used to determine if a track is a built-in track. + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_stream_result_t k4a_playback_get_previous_data_block(k4a_playback_t playback_handle, + const char *track_name, + k4a_playback_data_block_t *data_block_handle); + +/** Get the device timestamp of a data block in microseconds. + * + * \param data_block_handle + * Handle obtained by k4a_playback_get_next_data_block() or k4a_playback_get_previous_data_block(). + * + * \returns + * Returns the device timestamp of the data block. If the \p data_block_handle is invalid this function will return 0. + * It is also possible for 0 to be a valid timestamp originating from when a device was first powered on. + * + * \relates k4a_playback_data_block_t + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT uint64_t +k4a_playback_data_block_get_device_timestamp_usec(k4a_playback_data_block_t data_block_handle); + +/** Get the buffer size of a data block. + * + * \param data_block_handle + * Handle obtained by k4a_playback_get_next_data_block() or k4a_playback_get_previous_data_block(). + * + * \returns + * Returns the buffer size of the data block, or 0 if the data block is invalid. + * + * \relates k4a_playback_data_block_t + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT size_t k4a_playback_data_block_get_buffer_size(k4a_playback_data_block_t data_block_handle); + +/** Get the buffer of a data block. + * + * \param data_block_handle + * Handle obtained by k4a_playback_get_next_data_block() or k4a_playback_get_previous_data_block(). + * + * \remarks + * Use this buffer to access the data written to a custom recording track. + * + * \returns + * Returns a pointer to the data block buffer, or NULL if the data block is invalid. + * + * \relates k4a_playback_data_block_t + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT uint8_t *k4a_playback_data_block_get_buffer(k4a_playback_data_block_t data_block_handle); + +/** Release a data block handle. + * + * \param data_block_handle + * Handle obtained by k4a_playback_get_next_data_block() or k4a_playback_get_previous_data_block(). + * + * \remarks + * Release the memory of a data block. The caller must not access the object after it is released. + * + * \relates k4a_playback_data_block_t + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT void k4a_playback_data_block_release(k4a_playback_data_block_t data_block_handle); + +/** Seek to a specific timestamp within a recording. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \param offset_usec + * The timestamp offset to seek to, relative to \p origin + * + * \param origin + * Specifies how the given timestamp should be interpreted. Seek can be done relative to the beginning or end of the + * recording, or using an absolute device timestamp. + * + * \returns + * ::K4A_RESULT_SUCCEEDED if the seek operation was successful, or ::K4A_RESULT_FAILED if an error occured. The current + * seek position is left unchanged if a failure is returned. + * + * \relates k4a_playback_t + * + * \remarks + * The first device timestamp in a recording is usually non-zero. The recording file starts at the device timestamp + * defined by start_timestamp_offset_usec, which is accessible via k4a_playback_get_record_configuration(). + * + * \remarks + * The first call to k4a_playback_get_next_capture() after k4a_playback_seek_timestamp() will return the first capture + * containing an image timestamp greater than or equal to the seek time. + * + * \remarks + * The first call to k4a_playback_get_previous_capture() after k4a_playback_seek_timestamp() will return the first + * capture with all image timestamps less than the seek time. + * + * \remarks + * The first call to k4a_playback_get_next_imu_sample() after k4a_playback_seek_timestamp() will return the first imu + * sample with a timestamp greter than or equal to the seek time. + * + * \remarks + * The first call to k4a_playback_get_previous_imu_sample() after k4a_playback_seek_timestamp() will return the first + * imu sample with a timestamp less than the seek time. + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_result_t k4a_playback_seek_timestamp(k4a_playback_t playback_handle, + int64_t offset_usec, + k4a_playback_seek_origin_t origin); + +/** Returns the length of the recording in microseconds. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \returns + * The recording length, calculated as the difference between the first and last timestamp in the file. + * + * \relates k4a_playback_t + * + * \remarks + * The recording length may be longer than an individual track if, for example, the IMU continues to run after the last + * color image is recorded. + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT uint64_t k4a_playback_get_recording_length_usec(k4a_playback_t playback_handle); + +/** Gets the last timestamp in a recording, relative to the start of the recording. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \returns + * The file timestamp of the last capture image or IMU sample in microseconds. + * + * \relates k4a_playback_t + * + * \remarks + * This function returns a file timestamp, not an absolute device timestamp, meaning it is relative to the start of the + * recording. This function is equivalent to the length of the recording. + * + * \deprecated + * Deprecated starting in 1.2.0. Please use k4a_playback_get_recording_length_usec(). + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_DEPRECATED_EXPORT uint64_t k4a_playback_get_last_timestamp_usec(k4a_playback_t playback_handle); + +/** Closes a recording playback handle. + * + * \param playback_handle + * Handle obtained by k4a_playback_open(). + * + * \headerfile playback.h + * + * \relates k4a_playback_t + * + * \xmlonly + * + * playback.h (include k4arecord/playback.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT void k4a_playback_close(k4a_playback_t playback_handle); + +/** + * @} + */ + +#ifdef __cplusplus +} // extern "C" +#endif + +#endif /* K4A_PLAYBACK_H */ diff --git a/k4a-sys/vendor/include/windows/k4arecord/playback.hpp b/k4a-sys/vendor/include/windows/k4arecord/playback.hpp new file mode 100644 index 0000000000..dc21174c6e --- /dev/null +++ b/k4a-sys/vendor/include/windows/k4arecord/playback.hpp @@ -0,0 +1,339 @@ +/** \file playback.hpp + * Copyright (c) Microsoft Corporation. All rights reserved. + * Licensed under the MIT License. + * Kinect For Azure SDK - C++ wrapper. + */ + +#ifndef K4A_PLAYBACK_HPP +#define K4A_PLAYBACK_HPP + +#include +#include + +#include +#include +#include +#include + +namespace k4a +{ + +/** \class playback playback.hpp + * Wrapper for \ref k4a_playback_t + * + * Wraps a handle for a playback object + * + * \sa k4a_playback_t + */ +class playback +{ +public: + /** Creates a k4a::playback from a k4a_playback_t + * Takes ownership of the handle, i.e. you should not call + * k4a_playback_close on the handle after giving it to the + * k4a::playback; the k4a::playback will take care of that. + */ + playback(k4a_playback_t handle = nullptr) noexcept : m_handle(handle) {} + + /** Moves another k4a::playback into a new k4a::playback + */ + playback(playback &&other) noexcept : m_handle(other.m_handle) + { + other.m_handle = nullptr; + } + + playback(const playback &) = delete; + + ~playback() + { + close(); + } + + playback &operator=(const playback &) = delete; + + /** Moves another k4a::playback into this k4a::playback; other is set to invalid + */ + playback &operator=(playback &&other) noexcept + { + if (this != &other) + { + close(); + m_handle = other.m_handle; + other.m_handle = nullptr; + } + + return *this; + } + + /** Returns true if the k4a::playback is valid, false otherwise + */ + operator bool() const noexcept + { + return m_handle != nullptr; + } + + /** Closes a K4A recording. + * + * \sa k4a_playback_close + */ + void close() noexcept + { + if (m_handle != nullptr) + { + k4a_playback_close(m_handle); + m_handle = nullptr; + } + } + + /** Get the raw calibration blob for the K4A device that made the recording. + * Throws error on failure. + * + * \sa k4a_playback_get_raw_calibration + */ + std::vector get_raw_calibration() const + { + std::vector calibration; + size_t buffer = 0; + k4a_buffer_result_t result = k4a_playback_get_raw_calibration(m_handle, &calibration[0], &buffer); + + if (result == K4A_BUFFER_RESULT_TOO_SMALL && buffer > 1) + { + calibration.resize(buffer); + result = k4a_playback_get_raw_calibration(m_handle, &calibration[0], &buffer); + } + + if (result != K4A_BUFFER_RESULT_SUCCEEDED) + { + throw error("Failed to read raw device calibration from recording!"); + } + + return calibration; + } + + /** Get the camera calibration for the K4A device that made the recording, which is used for all transformation + * functions. Throws error on failure. + * + * \sa k4a_playback_get_calibration + */ + calibration get_calibration() const + { + calibration calib; + k4a_result_t result = k4a_playback_get_calibration(m_handle, &calib); + + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to read device calibration from recording!"); + } + + return calib; + } + + /** Gets the configuration of the recording + * + * \sa k4a_playback_get_record_configuration + */ + k4a_record_configuration_t get_record_configuration() const + { + k4a_record_configuration_t config; + k4a_result_t result = k4a_playback_get_record_configuration(m_handle, &config); + + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to read record configuration!"); + } + + return config; + } + + /** Get the next capture in the recording + * Returns true if a capture was available, false if there are none left + * Throws error on failure. + * + * \sa k4a_playback_get_next_capture + */ + bool get_next_capture(capture *cap) + { + k4a_capture_t capture_handle; + k4a_stream_result_t result = k4a_playback_get_next_capture(m_handle, &capture_handle); + + if (K4A_STREAM_RESULT_SUCCEEDED == result) + { + *cap = capture(capture_handle); + return true; + } + else if (K4A_STREAM_RESULT_EOF == result) + { + return false; + } + + throw error("Failed to get next capture!"); + } + + /** Get the next capture in the recording + * Returns true if a capture was available, false if there are none left + * Throws error on failure. + * + * \sa k4a_playback_get_previous_capture + */ + bool get_previous_capture(capture *cap) + { + k4a_capture_t capture_handle; + k4a_stream_result_t result = k4a_playback_get_previous_capture(m_handle, &capture_handle); + + if (K4A_STREAM_RESULT_SUCCEEDED == result) + { + *cap = capture(capture_handle); + return true; + } + else if (K4A_STREAM_RESULT_EOF == result) + { + return false; + } + + throw error("Failed to get next capture!"); + } + + /** Reads the value of a tag from the recording + * Returns false if the tag does not exist. + * + * \sa k4a_playback_get_tag + */ + bool get_tag(const char *name, std::string *out) const + { + std::string tag; + size_t buffer = 0; + k4a_buffer_result_t result = k4a_playback_get_tag(m_handle, name, &tag[0], &buffer); + + if (result == K4A_BUFFER_RESULT_TOO_SMALL && buffer > 0) + { + tag.resize(buffer); + result = k4a_playback_get_tag(m_handle, name, &tag[0], &buffer); + if (result == K4A_BUFFER_RESULT_SUCCEEDED && tag[buffer - 1] == 0) + { + // std::string expects there to not be as null terminator at the end of its data but + // k4a_playback_get_tag adds a null terminator, so we drop the last character of the string after we + // get the result back. + tag.resize(buffer - 1); + } + } + + if (result != K4A_BUFFER_RESULT_SUCCEEDED) + { + return false; + } + + *out = std::move(tag); + + return true; + } + + /** Get the next IMU sample in the recording + * Returns true if a sample was available, false if there are none left + * Throws error on failure. + * + * \sa k4a_playback_get_next_imu_sample + */ + bool get_next_imu_sample(k4a_imu_sample_t *sample) + { + k4a_stream_result_t result = k4a_playback_get_next_imu_sample(m_handle, sample); + + if (K4A_STREAM_RESULT_SUCCEEDED == result) + { + return true; + } + else if (K4A_STREAM_RESULT_EOF == result) + { + return false; + } + + throw error("Failed to get next IMU sample!"); + } + + /** Get the previous IMU sample in the recording + * Returns true if a sample was available, false if there are none left + * Throws error on failure. + * + * \sa k4a_playback_get_previous_imu_sample + */ + bool get_previous_imu_sample(k4a_imu_sample_t *sample) + { + k4a_stream_result_t result = k4a_playback_get_previous_imu_sample(m_handle, sample); + + if (K4A_STREAM_RESULT_SUCCEEDED == result) + { + return true; + } + else if (K4A_STREAM_RESULT_EOF == result) + { + return false; + } + + throw error("Failed to get previous IMU sample!"); + } + + /** Seeks to a specific time point in the recording + * Throws error on failure. + * + * \sa k4a_playback_seek_timestamp + */ + void seek_timestamp(std::chrono::microseconds offset, k4a_playback_seek_origin_t origin) + { + k4a_result_t result = k4a_playback_seek_timestamp(m_handle, offset.count(), origin); + + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to seek recording!"); + } + } + + /** Get the last valid timestamp in the recording + * + * \sa k4a_playback_get_recording_length_usec + */ + std::chrono::microseconds get_recording_length() const noexcept + { + return std::chrono::microseconds(k4a_playback_get_recording_length_usec(m_handle)); + } + + /** Set the image format that color captures will be converted to. By default the conversion format will be the same + * as the image format stored in the recording file, and no conversion will occur. + * + * Throws error on failure. + * + * \sa k4a_playback_set_color_conversion + */ + void set_color_conversion(k4a_image_format_t format) + { + k4a_result_t result = k4a_playback_set_color_conversion(m_handle, format); + + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to set color conversion!"); + } + } + + /** Opens a K4A recording for playback. + * Throws error on failure. + * + * \sa k4a_playback_open + */ + static playback open(const char *path) + { + k4a_playback_t handle = nullptr; + k4a_result_t result = k4a_playback_open(path, &handle); + + if (K4A_RESULT_SUCCEEDED != result) + { + throw error("Failed to open recording!"); + } + + return playback(handle); + } + +private: + k4a_playback_t m_handle; +}; + +} // namespace k4a + +#endif diff --git a/k4a-sys/vendor/include/windows/k4arecord/record.h b/k4a-sys/vendor/include/windows/k4arecord/record.h new file mode 100644 index 0000000000..998ce3d693 --- /dev/null +++ b/k4a-sys/vendor/include/windows/k4arecord/record.h @@ -0,0 +1,473 @@ +/** \file record.h + * Copyright (c) Microsoft Corporation. All rights reserved. + * Licensed under the MIT License. + * Kinect For Azure Recording SDK. + */ + +#ifndef K4A_RECORD_H +#define K4A_RECORD_H + +#include +#include + +#ifdef __cplusplus + +extern "C" { +#endif + +/** + * + * \addtogroup Functions + * + * @{ + */ + +/** Opens a new recording file for writing. + * + * \param path + * Filesystem path for the new recording. + * + * \param device + * The Azure Kinect device that is being recorded. The device handle is used to store device calibration and serial + * number information. May be NULL if recording user-generated data. + * + * \param device_config + * The configuration the Azure Kinect device was started with. + * + * \param recording_handle + * If successful, this contains a pointer to the new recording handle. Caller must call k4a_record_close() + * when finished with recording. + * + * \remarks + * The file will be created if it doesn't exist, or overwritten if an existing file is specified. + * + * \remarks + * Streaming does not need to be started on the device at the time this function is called, but when it is started + * it should be started with the same configuration provided in \p device_config. + * + * \remarks + * Subsequent calls to k4a_record_write_capture() will need to have images in the resolution and format defined + * in \p device_config. + * + * \headerfile record.h + * + * \returns ::K4A_RESULT_SUCCEEDED is returned on success + * + * \relates k4a_record_t + * + * \xmlonly + * + * record.h (include k4arecord/record.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_result_t k4a_record_create(const char *path, + k4a_device_t device, + const k4a_device_configuration_t device_config, + k4a_record_t *recording_handle); + +/** Adds a tag to the recording. + * + * \param recording_handle + * The handle of a new recording, obtained by k4a_record_create(). + * + * \param name + * The name of the tag to write. + * + * \param value + * The string value to store in the tag. + * + * \headerfile record.h + * + * \relates k4a_record_t + * + * \returns ::K4A_RESULT_SUCCEEDED is returned on success. + * + * \remarks + * Tags are global to a file, and should store data related to the entire recording, such as camera configuration or + * recording location. + * + * \remarks + * Tag names must be ALL CAPS and may only contain A-Z, 0-9, '-' and '_'. + * + * \remarks + * All tags need to be added before the recording header is written. + * + * \xmlonly + * + * record.h (include k4arecord/record.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_result_t k4a_record_add_tag(k4a_record_t recording_handle, const char *name, const char *value); + +/** Adds the track header for recording IMU. + * + * \param recording_handle + * The handle of a new recording, obtained by k4a_record_create(). + * + * \headerfile record.h + * + * \relates k4a_record_t + * + * \returns ::K4A_RESULT_SUCCEEDED is returned on success + * + * \remarks + * The track needs to be added before the recording header is written. + * + * \xmlonly + * + * record.h (include k4arecord/record.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_result_t k4a_record_add_imu_track(k4a_record_t recording_handle); + +/** Adds an attachment to the recording. + * + * \param recording_handle + * The handle of a new recording, obtained by k4a_record_create(). + * + * \param attachment_name + * The name of the attachment to be stored in the recording file. This name should be a valid filename with an + * extension. + * + * \param buffer + * The attachment data buffer. + * + * \param buffer_size + * The size of the attachment data buffer. + * + * \headerfile record.h + * + * \relates k4a_record_t + * + * \returns ::K4A_RESULT_SUCCEEDED is returned on success + * + * \remarks + * All attachments need to be added before the recording header is written. + * + * \xmlonly + * + * record.h (include k4arecord/record.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_result_t k4a_record_add_attachment(const k4a_record_t recording_handle, + const char *attachment_name, + const uint8_t *buffer, + size_t buffer_size); + +/** Adds custom video tracks to the recording. + * + * \param recording_handle + * The handle of a new recording, obtained by k4a_record_create(). + * + * \param track_name + * The name of the custom video track to be added. + * + * \param codec_id + * A UTF8 null terminated string containing the codec ID of the track. Some of the existing formats are listed here: + * https://www.matroska.org/technical/specs/codecid/index.html. The codec ID can also be custom defined by the user. + * Video codec ID's should start with 'V_'. + * + * \param codec_context + * The codec context is a codec-specific buffer that contains any required codec metadata that is only known to the + * codec. It is mapped to the matroska 'CodecPrivate' element. + * + * \param codec_context_size + * The size of the codec context buffer. + * + * \param track_settings + * Additional metadata for the video track such as resolution and framerate. + * + * \headerfile record.h + * + * \relates k4a_record_t + * + * \returns ::K4A_RESULT_SUCCEEDED is returned on success + * + * \remarks + * Built-in video tracks like the DEPTH, IR, and COLOR tracks will be created automatically when the k4a_record_create() + * API is called. This API can be used to add additional video tracks to save custom data. + * + * \remarks + * Track names must be ALL CAPS and may only contain A-Z, 0-9, '-' and '_'. + * + * \remarks + * All tracks need to be added before the recording header is written. + * + * \remarks + * Call k4a_record_write_custom_track_data() with the same track_name to write data to this track. + * + * \xmlonly + * + * record.h (include k4arecord/record.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_result_t k4a_record_add_custom_video_track(const k4a_record_t recording_handle, + const char *track_name, + const char *codec_id, + const uint8_t *codec_context, + size_t codec_context_size, + const k4a_record_video_settings_t *track_settings); + +/** Adds custom subtitle tracks to the recording. + * + * \param recording_handle + * The handle of a new recording, obtained by k4a_record_create(). + * + * \param track_name + * The name of the custom subtitle track to be added. + * + * \param codec_id + * A UTF8 null terminated string containing the codec ID of the track. Some of the existing formats are listed here: + * https://www.matroska.org/technical/specs/codecid/index.html. The codec ID can also be custom defined by the user. + * Subtitle codec ID's should start with 'S_'. + * + * \param codec_context + * The codec context is a codec-specific buffer that contains any required codec metadata that is only known to the + * codec. It is mapped to the matroska 'CodecPrivate' element. + * + * \param codec_context_size + * The size of the codec context buffer. + * + * \param track_settings + * Additional metadata for the subtitle track. If NULL, the default settings will be used. + * + * \headerfile record.h + * + * \relates k4a_record_t + * + * \returns ::K4A_RESULT_SUCCEEDED is returned on success + * + * \remarks + * Built-in subtitle tracks like the IMU track will be created automatically when the k4a_record_add_imu_track() API is + * called. This API can be used to add additional subtitle tracks to save custom data. + * + * \remarks + * Track names must be ALL CAPS and may only contain A-Z, 0-9, '-' and '_'. + * + * \remarks + * All tracks need to be added before the recording header is written. + * + * \remarks + * Call k4a_record_write_custom_track_data() with the same track_name to write data to this track. + * + * \xmlonly + * + * record.h (include k4arecord/record.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_result_t +k4a_record_add_custom_subtitle_track(const k4a_record_t recording_handle, + const char *track_name, + const char *codec_id, + const uint8_t *codec_context, + size_t codec_context_size, + const k4a_record_subtitle_settings_t *track_settings); + +/** Writes the recording header and metadata to file. + * + * \param recording_handle + * The handle of a new recording, obtained by k4a_record_create(). + * + * \headerfile record.h + * + * \relates k4a_record_t + * + * \returns ::K4A_RESULT_SUCCEEDED is returned on success + * + * \remarks + * This must be called before captures or any track data can be written. + * + * \xmlonly + * + * record.h (include k4arecord/record.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_result_t k4a_record_write_header(k4a_record_t recording_handle); + +/** Writes a camera capture to file. + * + * \param recording_handle + * The handle of a new recording, obtained by k4a_record_create(). + * + * \param capture_handle + * The handle of a capture to write to file. + * + * \headerfile record.h + * + * \relates k4a_record_t + * + * \returns ::K4A_RESULT_SUCCEEDED is returned on success + * + * \remarks + * Captures must be written in increasing order of timestamp, and the file's header must already be written. + * + * \remarks + * k4a_record_write_capture() will write all images in the capture to the corresponding tracks in the recording file. + * If any of the images fail to write, other images will still be written before a failure is returned. + * + * \xmlonly + * + * record.h (include k4arecord/record.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_result_t k4a_record_write_capture(k4a_record_t recording_handle, k4a_capture_t capture_handle); + +/** Writes an imu sample to file. + * + * \param recording_handle + * The handle of a new recording, obtained by k4a_record_create(). + * + * \param imu_sample + * A structure containing the imu sample data and timestamps. + * + * \headerfile record.h + * + * \relates k4a_record_t + * + * \returns ::K4A_RESULT_SUCCEEDED is returned on success + * + * \remarks + * Samples must be written in increasing order of timestamp, and the file's header must already be written. + * + * \remarks + * When writing imu samples at the same time as captures, the samples should be within 1 second of the most recently + * written capture. + * + * \xmlonly + * + * record.h (include k4arecord/record.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_result_t k4a_record_write_imu_sample(k4a_record_t recording_handle, k4a_imu_sample_t imu_sample); + +/** Writes data for a custom track to file. + * + * \param recording_handle + * The handle of a new recording, obtained by k4a_record_create(). + * + * \param track_name + * The name of the custom track that the data is going to be written to. + * + * \param device_timestamp_usec + * The timestamp in microseconds for the custom track data. This timestamp should be in the same time domain as the + * device timestamp used for recording. + * + * \param custom_data + * The buffer of custom track data. + * + * \param custom_data_size + * The size of the custom track data buffer. + * + * \headerfile record.h + * + * \relates k4a_record_t + * + * \returns ::K4A_RESULT_SUCCEEDED is returned on success + * + * \remarks + * Custom track data must be written in increasing order of timestamp, and the file's header must already be written. + * When writing custom track data at the same time as captures or IMU data, the custom data should be within 1 second of + * the most recently written timestamp. + * + * \xmlonly + * + * record.h (include k4arecord/record.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_result_t k4a_record_write_custom_track_data(const k4a_record_t recording_handle, + const char *track_name, + uint64_t device_timestamp_usec, + uint8_t *custom_data, + size_t custom_data_size); + +/** Flushes all pending recording data to disk. + * + * \param recording_handle + * Handle obtained by k4a_record_create(). + * + * \headerfile record.h + * + * \relates k4a_record_t + * + * \returns ::K4A_RESULT_SUCCEEDED is returned on success, or ::K4A_RESULT_FAILED if an error occurred. + * + * \remarks + * k4a_record_flush() ensures that all data passed to the recording API prior to calling flush is written to disk. + * If continuing to write recording data, care must be taken to ensure no new timestamps are added from before the + * flush. + * + * \remarks + * If an error occurs, best effort is made to flush as much data to disk as possible, but the integrity of the file is + * not guaranteed. + * + * \xmlonly + * + * record.h (include k4arecord/record.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT k4a_result_t k4a_record_flush(k4a_record_t recording_handle); + +/** Closes a recording handle. + * + * \param recording_handle + * Handle obtained by k4a_record_create(). + * + * \headerfile record.h + * + * \relates k4a_record_t + * + * \remarks + * If there is any unwritten data it will be flushed to disk before closing the recording. + * + * \xmlonly + * + * record.h (include k4arecord/record.h) + * k4arecord.lib + * k4arecord.dll + * + * \endxmlonly + */ +K4ARECORD_EXPORT void k4a_record_close(k4a_record_t recording_handle); + +/** + * @} + */ + +#ifdef __cplusplus +} // extern "C" +#endif + +#endif /* K4A_RECORD_H */ diff --git a/k4a-sys/vendor/include/windows/k4arecord/types.h b/k4a-sys/vendor/include/windows/k4arecord/types.h new file mode 100644 index 0000000000..f3533f2125 --- /dev/null +++ b/k4a-sys/vendor/include/windows/k4arecord/types.h @@ -0,0 +1,261 @@ +/** \file types.h + * Copyright (c) Microsoft Corporation. All rights reserved. + * Licensed under the MIT License. + * Kinect For Azure Playback/Record type definitions. + */ + +#ifndef K4ARECORD_TYPES_H +#define K4ARECORD_TYPES_H + +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * \addtogroup Handles + * @{ + */ + +/** \class k4a_record_t types.h + * Handle to a k4a recording opened for writing. + * + * \remarks + * Handles are created with k4a_record_create(), and closed with k4a_record_close(). + * Invalid handles are set to 0. + * + * \xmlonly + * + * types.h (include k4arecord/types.h) + * + * \endxmlonly + */ +K4A_DECLARE_HANDLE(k4a_record_t); + +/** \class k4a_playback_t types.h + * Handle to a k4a recording opened for playback. + * + * \remarks + * Handles are created with k4a_playback_open(), and closed with k4a_playback_close(). + * Invalid handles are set to 0. + * + * \xmlonly + * + * types.h (include k4arecord/types.h) + * + * \endxmlonly + */ +K4A_DECLARE_HANDLE(k4a_playback_t); + +/** \class k4a_playback_data_block_t types.h + * Handle to a block of data read from a k4a_playback_t custom track. + * + * \remarks + * Handles are obtained from k4a_playback_get_next_data_block() or k4a_playback_get_previous_data_block(), and released + * with k4a_playback_data_block_release(). Invalid handles are set to 0. + * + * \xmlonly + * + * types.h (include k4arecord/types.h) + * + * \endxmlonly + */ +K4A_DECLARE_HANDLE(k4a_playback_data_block_t) + +/** + * @} + * + * \addtogroup Definitions + * @{ + */ + +/** Name of the built-in color track used in recordings. + * + * \xmlonly + * + * types.h (include k4arecord/types.h) + * + * \endxmlonly + */ +#define K4A_TRACK_NAME_COLOR "COLOR" + +/** Name of the built-in depth track used in recordings. + * + * \xmlonly + * + * types.h (include k4arecord/types.h) + * + * \endxmlonly + */ +#define K4A_TRACK_NAME_DEPTH "DEPTH" + +/** Name of the built-in IR track used in recordings. + * + * \xmlonly + * + * types.h (include k4arecord/types.h) + * + * \endxmlonly + */ +#define K4A_TRACK_NAME_IR "IR" + +/** Name of the built-in imu track used in recordings. + * + * \xmlonly + * + * types.h (include k4arecord/types.h) + * + * \endxmlonly + */ +#define K4A_TRACK_NAME_IMU "IMU" + +/** + * @} + * + * \addtogroup Enumerations + * @{ + */ + +/** Return codes returned by Azure Kinect playback API. + * + * \xmlonly + * + * types.h (include k4arecord/types.h) + * + * \endxmlonly + */ +typedef enum +{ + K4A_STREAM_RESULT_SUCCEEDED = 0, /**< The result was successful. */ + K4A_STREAM_RESULT_FAILED, /**< The result was a failure. */ + K4A_STREAM_RESULT_EOF, /**< The end of the data stream was reached. */ +} k4a_stream_result_t; + +/** Playback seeking positions. + * + * \xmlonly + * + * types.h (include k4arecord/types.h) + * + * \endxmlonly + */ +typedef enum +{ + K4A_PLAYBACK_SEEK_BEGIN, /**< Seek relative to the beginning of a recording. */ + K4A_PLAYBACK_SEEK_END, /**< Seek relative to the end of a recording. */ + K4A_PLAYBACK_SEEK_DEVICE_TIME /**< Seek to an absolute device timestamp. */ +} k4a_playback_seek_origin_t; + +/** + * @} + * + * \addtogroup Structures + * @{ + */ + +/** Structure containing the device configuration used to record. + * + * \see k4a_device_configuration_t + * \see k4a_playback_get_record_configuration() + * + * \xmlonly + * + * types.h (include k4arecord/types.h) + * + * \endxmlonly + */ +typedef struct _k4a_record_configuration_t +{ + /** Image format used to record the color camera. */ + k4a_image_format_t color_format; + + /** Image resolution used to record the color camera. */ + k4a_color_resolution_t color_resolution; + + /** Mode used to record the depth camera. */ + k4a_depth_mode_t depth_mode; + + /** Frame rate used to record the color and depth camera. */ + k4a_fps_t camera_fps; + + /** True if the recording contains Color camera frames. */ + bool color_track_enabled; + + /** True if the recording contains Depth camera frames. */ + bool depth_track_enabled; + + /** True if the recording contains IR camera frames. */ + bool ir_track_enabled; + + /** True if the recording contains IMU sample data. */ + bool imu_track_enabled; + + /** + * The delay between color and depth images in the recording. + * A negative delay means depth images are first, and a positive delay means color images are first. + */ + int32_t depth_delay_off_color_usec; + + /** External synchronization mode */ + k4a_wired_sync_mode_t wired_sync_mode; + + /** + * The delay between this recording and the externally synced master camera. + * This value is 0 unless \p wired_sync_mode is set to ::K4A_WIRED_SYNC_MODE_SUBORDINATE + */ + uint32_t subordinate_delay_off_master_usec; + + /** + * The timestamp offset of the start of the recording. All recorded timestamps are offset by this value such that + * the recording starts at timestamp 0. This value can be used to synchronize timestamps between 2 recording files. + */ + uint32_t start_timestamp_offset_usec; +} k4a_record_configuration_t; + +/** Structure containing additional metadata specific to custom video tracks. + * + * \xmlonly + * + * types.h (include k4arecord/types.h) + * + * \endxmlonly + */ +typedef struct _k4a_record_video_settings_t +{ + uint64_t width; /**< Frame width of the video */ + uint64_t height; /**< Frame height of the video */ + uint64_t frame_rate; /**< Frame rate (frames-per-second) of the video */ +} k4a_record_video_settings_t; + +/** Structure containing additional metadata specific to custom subtitle tracks. + * + * \xmlonly + * + * types.h (include k4arecord/types.h) + * + * \endxmlonly + */ +typedef struct _k4a_record_subtitle_settings_t +{ + /** + * If true, data will be grouped together in batches to reduce overhead. In this mode, only a single timestamp will + * be stored per batch, and an estimated timestamp will be used by k4a_playback_seek_timestamp() and + * k4a_playback_data_block_get_timestamp_usec(). The estimated timestamp is calculated with the assumption that + * blocks are evenly spaced within a batch. If precise timestamps are required, the timestamp should be added to + * each data block itself. + * + * If false, data will be stored as individual blocks with full timestamp information (Default). + */ + bool high_freq_data; +} k4a_record_subtitle_settings_t; + +/** + * @} + */ + +#ifdef __cplusplus +} +#endif + +#endif /* K4ARECORD_TYPES_H */ diff --git a/k4a-sys/vendor/lib/windows/x86/k4a.lib b/k4a-sys/vendor/lib/windows/x86/k4a.lib new file mode 100644 index 0000000000..30127a8add Binary files /dev/null and b/k4a-sys/vendor/lib/windows/x86/k4a.lib differ diff --git a/k4a-sys/vendor/lib/windows/x86/k4arecord.lib b/k4a-sys/vendor/lib/windows/x86/k4arecord.lib new file mode 100644 index 0000000000..084fde5f1e Binary files /dev/null and b/k4a-sys/vendor/lib/windows/x86/k4arecord.lib differ diff --git a/k4a-sys/vendor/lib/windows/x86_64/k4a.lib b/k4a-sys/vendor/lib/windows/x86_64/k4a.lib new file mode 100644 index 0000000000..60ea0870bf Binary files /dev/null and b/k4a-sys/vendor/lib/windows/x86_64/k4a.lib differ diff --git a/k4a-sys/vendor/lib/windows/x86_64/k4arecord.lib b/k4a-sys/vendor/lib/windows/x86_64/k4arecord.lib new file mode 100644 index 0000000000..6953e99860 Binary files /dev/null and b/k4a-sys/vendor/lib/windows/x86_64/k4arecord.lib differ diff --git a/k4a-sys/wrapper.h b/k4a-sys/wrapper.h new file mode 100644 index 0000000000..f181122063 --- /dev/null +++ b/k4a-sys/wrapper.h @@ -0,0 +1 @@ +#include