kinect/codes/Azure-Kinect-Sensor-SDK/include/k4a/k4a.h

2279 lines
85 KiB
C
Raw Permalink Normal View History

2024-03-06 18:05:53 +00:00
/** \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 <cinttypes>
#else
#include <inttypes.h>
#endif
#include <k4a/k4aversion.h>
#include <k4a/k4atypes.h>
#include <k4a/k4a_export.h>
#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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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 a single image with voxels representing
* X, Y and Z-coordinates in millimeters 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
* <requirements>
* <requirement name="Header">k4a.h (include k4a/k4a.h)</requirement>
* <requirement name="Library">k4a.lib</requirement>
* <requirement name="DLL">k4a.dll</requirement>
* </requirements>
* \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 */