diff --git a/binding.gyp b/binding.gyp index dbb09c6..c0715c7 100644 --- a/binding.gyp +++ b/binding.gyp @@ -28,7 +28,10 @@ ] } ], - 'defines': [ 'NAPI_DISABLE_CPP_EXCEPTIONS' ], + 'defines': [ + 'NAPI_DISABLE_CPP_EXCEPTIONS', + 'NAPI_VERSION=<(napi_build_version)' + ] }, { "target_name": "action_after_build", diff --git a/package.json b/package.json index 680be14..88f78f2 100644 --- a/package.json +++ b/package.json @@ -12,9 +12,9 @@ "node": ">= 10.16.0" }, "scripts": { - "install": "prebuild-install || prebuild -t 4 -r napi || node-gyp rebuild", - "prebuild": "prebuild -t 4 -r napi", - "package": "prebuild -t 4 -r napi -u", + "install": "prebuild-install || prebuild -t 4 --runtime napi || node-gyp rebuild", + "prebuild": "prebuild -t 4 --runtime napi", + "package": "prebuild -t 4 --runtime napi -u", "start": "cd ./examples/electron && npm start", "prepublishOnly": "rimraf ./examples/**/node_modules", "copy-dlls": "xcopy \"C:\\Program Files\\Azure Kinect Body Tracking SDK\\tools\\\" . /H /C /Y" diff --git a/sdk/sensor-sdk-1.4.1/build/native/include/k4a/k4a.h b/sdk/sensor-sdk-1.4.1/build/native/include/k4a/k4a.h new file mode 100644 index 0000000..e7a9949 --- /dev/null +++ b/sdk/sensor-sdk-1.4.1/build/native/include/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 ::K4A_TRANSFORMATION_INTERPOLATION_TYPE_LINEAR for \p interpolation_type could create new values to \p + * transformed_custom_image which do no exist in \p custom_image. Using ::K4A_TRANSFORMATION_INTERPOLATION_TYPE_NEAREST + * will prevent this from happenning but will result in a 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/sdk/sensor-sdk-1.4.1/build/native/include/k4a/k4a.hpp b/sdk/sensor-sdk-1.4.1/build/native/include/k4a/k4a.hpp new file mode 100644 index 0000000..c862998 --- /dev/null +++ b/sdk/sensor-sdk-1.4.1/build/native/include/k4a/k4a.hpp @@ -0,0 +1,1462 @@ +/** \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 the other image + */ + 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 + */ + explicit operator bool() const noexcept + { + return is_valid(); + } + + /** Returns true if the image is valid, false otherwise + */ + bool is_valid() 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 the other image + */ + 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 + */ + explicit operator bool() const noexcept + { + return is_valid(); + } + + /** Returns true if the capture is valid, false otherwise + */ + bool is_valid() 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 + */ + explicit operator bool() const noexcept + { + return is_valid(); + } + + /** Returns true if the device is valid, false otherwise + */ + bool is_valid() 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, nullptr, &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/sdk/sensor-sdk-1.4.1/build/native/include/k4a/k4a_export.h b/sdk/sensor-sdk-1.4.1/build/native/include/k4a/k4a_export.h new file mode 100644 index 0000000..b291e75 --- /dev/null +++ b/sdk/sensor-sdk-1.4.1/build/native/include/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/sdk/sensor-sdk-1.4.1/build/native/include/k4a/k4atypes.h b/sdk/sensor-sdk-1.4.1/build/native/include/k4a/k4atypes.h new file mode 100644 index 0000000..e7d17bd --- /dev/null +++ b/sdk/sensor-sdk-1.4.1/build/native/include/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/sdk/sensor-sdk-1.4.1/build/native/include/k4a/k4aversion.h b/sdk/sensor-sdk-1.4.1/build/native/include/k4a/k4aversion.h new file mode 100644 index 0000000..e1e4993 --- /dev/null +++ b/sdk/sensor-sdk-1.4.1/build/native/include/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 4 +#define K4A_VERSION_PATCH 1 +#define K4A_VERSION_PRERELEASE "" +#define K4A_VERSION_BUILD_METADATA "" + +#define K4A_VERSION_STR "1.4.1" + +#endif + diff --git a/sdk/sensor-sdk-1.4.1/build/native/include/k4arecord/k4arecord_export.h b/sdk/sensor-sdk-1.4.1/build/native/include/k4arecord/k4arecord_export.h new file mode 100644 index 0000000..290ef48 --- /dev/null +++ b/sdk/sensor-sdk-1.4.1/build/native/include/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/sdk/sensor-sdk-1.4.1/build/native/include/k4arecord/playback.h b/sdk/sensor-sdk-1.4.1/build/native/include/k4arecord/playback.h new file mode 100644 index 0000000..6502ea8 --- /dev/null +++ b/sdk/sensor-sdk-1.4.1/build/native/include/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/sdk/sensor-sdk-1.4.1/build/native/include/k4arecord/playback.hpp b/sdk/sensor-sdk-1.4.1/build/native/include/k4arecord/playback.hpp new file mode 100644 index 0000000..7ec749a --- /dev/null +++ b/sdk/sensor-sdk-1.4.1/build/native/include/k4arecord/playback.hpp @@ -0,0 +1,517 @@ +/** \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 data_block playback.hpp + * Wrapper for \ref k4a_playback_data_block_t + * + * \sa k4a_playback_data_block_t + */ +class data_block +{ +public: + /** Creates a data_block from a k4a_playback_data_block_t + * Takes ownership of the handle, you should not call k4a_playback_data_block_release on the handle after + * giving it to the data_block; the data_block will take care of that. + */ + data_block(k4a_playback_data_block_t handle = nullptr) noexcept : m_handle(handle) {} + + // No Copies allowed + data_block(const data_block &) = delete; + data_block &operator=(const data_block &) = delete; + + /** Moves another data_block into a new data_block + */ + data_block(data_block &&other) noexcept + { + m_handle = other.m_handle; + other.m_handle = nullptr; + } + + ~data_block() + { + reset(); + } + + /** Moves another data_block into this data_block; other is set to invalid + */ + data_block &operator=(data_block &&other) noexcept + { + if (this != &other) + { + reset(); + m_handle = other.m_handle; + other.m_handle = nullptr; + } + return *this; + } + + /** Returns true if the data_block is valid, false otherwise + */ + explicit operator bool() const noexcept + { + return is_valid(); + } + + /** Returns true if the data_block is valid, false otherwise + */ + bool is_valid() const noexcept + { + return m_handle != nullptr; + } + + /** Releases the underlying k4a_playback_data_block_t; the data_block is set to invalid. + */ + void reset() noexcept + { + if (m_handle) + { + k4a_playback_data_block_release(m_handle); + m_handle = nullptr; + } + } + + /** Get the time stamp in micro seconds for the given data_block + * + * \sa k4a_playback_data_block_get_device_timestamp_usec + */ + std::chrono::microseconds get_device_timestamp_usec() const noexcept + { + return std::chrono::microseconds(k4a_playback_data_block_get_device_timestamp_usec(m_handle)); + } + + /** Get the size of the data_block buffer. + * + * \sa k4a_playback_data_block_get_buffer_size + */ + size_t get_buffer_size() const noexcept + { + return k4a_playback_data_block_get_buffer_size(m_handle); + } + + /** Get the data_block buffer. + * + * \sa k4a_playback_data_block_get_buffer + */ + const uint8_t *get_buffer() const noexcept + { + return k4a_playback_data_block_get_buffer(m_handle); + } + +private: + k4a_playback_data_block_t m_handle; +}; + +/** \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 + */ + explicit operator bool() const noexcept + { + return is_valid(); + } + + /** Returns true if the k4a::playback is valid, false otherwise + */ + bool is_valid() 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, nullptr, &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 previous 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 previous 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, nullptr, &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!"); + } + } + + /** Get the next data block in the recording. + * Returns true if a block was available, false if there are none left. + * Throws error on failure. + * + * \sa k4a_playback_get_next_data_block + */ + bool get_next_data_block(const char *track, data_block *block) + { + k4a_playback_data_block_t block_handle; + k4a_stream_result_t result = k4a_playback_get_next_data_block(m_handle, track, &block_handle); + + if (K4A_STREAM_RESULT_SUCCEEDED == result) + { + *block = data_block(block_handle); + return true; + } + else if (K4A_STREAM_RESULT_EOF == result) + { + return false; + } + + throw error("Failed to get next data block!"); + } + + /** Get the previous data block from the recording. + * Returns true if a block was available, false if there are none left. + * Throws error on failure. + * + * \sa k4a_playback_get_previous_data_block + */ + bool get_previous_data_block(const char *track, data_block *block) + { + k4a_playback_data_block_t block_handle; + k4a_stream_result_t result = k4a_playback_get_previous_data_block(m_handle, track, &block_handle); + + if (K4A_STREAM_RESULT_SUCCEEDED == result) + { + *block = data_block(block_handle); + return true; + } + else if (K4A_STREAM_RESULT_EOF == result) + { + return false; + } + + throw error("Failed to get previous data block!"); + } + + /** Get the attachment block from the recording. + * Returns true if the attachment was available, false if it was not found. + * Throws error on failure. + * + * \sa k4a_playback_get_attachment + */ + bool get_attachment(const char *attachment, std::vector *data) + { + size_t data_size = 0; + k4a_buffer_result_t result = k4a_playback_get_attachment(m_handle, attachment, nullptr, &data_size); + if (result == K4A_BUFFER_RESULT_TOO_SMALL) + { + data->resize(data_size); + result = k4a_playback_get_attachment(m_handle, attachment, &(*data)[0], &data_size); + if (result != K4A_BUFFER_RESULT_SUCCEEDED) + { + throw error("Failed to read attachment!"); + } + return true; + } + return false; + } + + /** 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/sdk/sensor-sdk-1.4.1/build/native/include/k4arecord/record.h b/sdk/sensor-sdk-1.4.1/build/native/include/k4arecord/record.h new file mode 100644 index 0000000..998ce3d --- /dev/null +++ b/sdk/sensor-sdk-1.4.1/build/native/include/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/sdk/sensor-sdk-1.4.1/build/native/include/k4arecord/record.hpp b/sdk/sensor-sdk-1.4.1/build/native/include/k4arecord/record.hpp new file mode 100644 index 0000000..62a6507 --- /dev/null +++ b/sdk/sensor-sdk-1.4.1/build/native/include/k4arecord/record.hpp @@ -0,0 +1,292 @@ +/** \file record.hpp + * Copyright (c) Microsoft Corporation. All rights reserved. + * Licensed under the MIT License. + * Kinect For Azure SDK - C++ wrapper. + */ +#ifndef K4A_RECORD_HPP +#define K4A_RECORD_HPP + +#include +#include + +namespace k4a +{ + +/** \class record record.hpp + * Wrapper for \ref k4a_record_t + * + * Wraps a handle for a record object + * + * \sa k4a_record_t + */ +class record +{ +public: + /** Creates a k4a::record from a k4a_record_t + * Takes ownership of the handle, i.e. you should not call + * k4a_record_close on the handle after giving it to the + * k4a::record; the k4a::record will take care of that. + */ + record(k4a_record_t handle = nullptr) noexcept : m_handle(handle) {} + + /** Moves another k4a::record into a new k4a::record + */ + record(record &&other) noexcept : m_handle(other.m_handle) + { + other.m_handle = nullptr; + } + + record(const record &) = delete; + + ~record() + { + // NOTE: flush is called internally when closing record + close(); + } + + record &operator=(const record &) = delete; + + /** Moves another k4a::record into this k4a::record; other is set to invalid + */ + record &operator=(record &&other) noexcept + { + if (this != &other) + { + close(); + m_handle = other.m_handle; + other.m_handle = nullptr; + } + + return *this; + } + + /** Returns true if the k4a::record is valid, false otherwise + */ + explicit operator bool() const noexcept + { + return is_valid(); + } + + /** Returns true if the k4a::record is valid, false otherwise + */ + bool is_valid() const noexcept + { + return m_handle != nullptr; + } + + /** Closes a K4A recording. + * + * \sa k4a_record_close + */ + void close() noexcept + { + if (is_valid()) + { + k4a_record_close(m_handle); + m_handle = nullptr; + } + } + + /** Flushes all pending recording data to disk + * + * \sa k4a_record_flush + */ + void flush() + { + if (m_handle) + { + k4a_result_t result = k4a_record_flush(m_handle); + + if (K4A_FAILED(result)) + { + throw error("Failed to flush!"); + } + } + } + + /** Adds a tag to the recording + * Throws error on failure + * + * \sa k4a_record_add_tag + */ + void add_tag(const char *name, const char *value) + { + k4a_result_t result = k4a_record_add_tag(m_handle, name, value); + + if (K4A_FAILED(result)) + { + throw error("Failed to add tag!"); + } + } + + /** Adds the track header for recording IMU + * Throws error on failure + * + * \sa k4a_record_add_imu_track + */ + void add_imu_track() + { + k4a_result_t result = k4a_record_add_imu_track(m_handle); + + if (K4A_FAILED(result)) + { + throw error("Failed to add imu_track!"); + } + } + + /** Adds an attachment to the recording + * Throws error on failure + * + * \sa k4a_record_add_attachment + */ + void add_attachment(const char *attachment_name, const uint8_t *buffer, size_t buffer_size) + { + k4a_result_t result = k4a_record_add_attachment(m_handle, attachment_name, buffer, buffer_size); + + if (K4A_FAILED(result)) + { + throw error("Failed to add attachment!"); + } + } + + /** Adds custom video tracks to the recording + * Throws error on failure + * + * \sa k4a_record_add_custom_video_track + */ + void add_custom_video_track(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) + { + k4a_result_t result = k4a_record_add_custom_video_track(m_handle, + track_name, + codec_id, + codec_context, + codec_context_size, + track_settings); + + if (K4A_FAILED(result)) + { + throw error("Failed to add custom video track!"); + } + } + + /** Adds custom subtitle tracks to the recording + * Throws error on failure + * + * \sa k4a_record_add_custom_subtitle_track + */ + void add_custom_subtitle_track(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) + { + k4a_result_t result = k4a_record_add_custom_subtitle_track(m_handle, + track_name, + codec_id, + codec_context, + codec_context_size, + track_settings); + + if (K4A_FAILED(result)) + { + throw error("Failed to add custom subtitle track!"); + } + } + + /** Writes the recording header and metadata to file + * Throws error on failure + * + * \sa k4a_record_write_header + */ + void write_header() + { + k4a_result_t result = k4a_record_write_header(m_handle); + + if (K4A_FAILED(result)) + { + throw error("Failed to write header!"); + } + } + + /** Writes a camera capture to file + * Throws error on failure + * + * \sa k4a_record_write_capture + */ + void write_capture(const capture &capture) + { + k4a_result_t result = k4a_record_write_capture(m_handle, capture.handle()); + + if (K4A_FAILED(result)) + { + throw error("Failed to write capture!"); + } + } + + /** Writes an imu sample to file + * Throws error on failure + * + * \sa k4a_record_write_imu_sample + */ + void write_imu_sample(const k4a_imu_sample_t &imu_sample) + { + k4a_result_t result = k4a_record_write_imu_sample(m_handle, imu_sample); + + if (K4A_FAILED(result)) + { + throw error("Failed to write imu sample!"); + } + } + + /** Writes data for a custom track to file + * Throws error on failure + * + * \sa k4a_record_write_custom_track_data + */ + void write_custom_track_data(const char *track_name, + const std::chrono::microseconds device_timestamp_usec, + uint8_t *custom_data, + size_t custom_data_size) + { + k4a_result_t result = k4a_record_write_custom_track_data(m_handle, + track_name, + internal::clamp_cast( + device_timestamp_usec.count()), + custom_data, + custom_data_size); + + if (K4A_FAILED(result)) + { + throw error("Failed to write custom track data!"); + } + } + + /** Opens a new recording file for writing + * Throws error on failure + * + * \sa k4a_record_create + */ + static record create(const char *path, const device &device, const k4a_device_configuration_t &device_configuration) + { + k4a_record_t handle = nullptr; + k4a_result_t result = k4a_record_create(path, device.handle(), device_configuration, &handle); + + if (K4A_FAILED(result)) + { + throw error("Failed to create recorder!"); + } + + return record(handle); + } + +private: + k4a_record_t m_handle; +}; + +} // namespace k4a + +#endif diff --git a/sdk/sensor-sdk-1.4.1/build/native/include/k4arecord/types.h b/sdk/sensor-sdk-1.4.1/build/native/include/k4arecord/types.h new file mode 100644 index 0000000..f3533f2 --- /dev/null +++ b/sdk/sensor-sdk-1.4.1/build/native/include/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 */