From e1c94cd006aab0dcb27e4dd27a7f83a17a66a1c3 Mon Sep 17 00:00:00 2001 From: BrentA-Microsoft Date: Tue, 5 Mar 2019 10:52:16 -0800 Subject: [PATCH 1/9] Documentation edits (In progress) (#105) * Documentation edits (cherry picked from commit ee21c9345aaf1974a7b26625b1a3c218774bc7b7) --- include/k4a/k4a.h | 201 ++++++++++++++++++++++++++++------------------ 1 file changed, 124 insertions(+), 77 deletions(-) diff --git a/include/k4a/k4a.h b/include/k4a/k4a.h index 29025040..271c1bd3 100644 --- a/include/k4a/k4a.h +++ b/include/k4a/k4a.h @@ -22,10 +22,10 @@ extern "C" { /** Gets the number of connected devices * - * \returns number of sensors connected to the PC + * \returns Number of sensors connected to the PC. * * \remarks - * This API counts the number of K4A devices connected to the host PC + * This API counts the number of K4A devices connected to the host PC. * * \xmlonly * @@ -43,9 +43,9 @@ K4A_EXPORT uint32_t k4a_device_get_installed_count(void); * 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 + * Output parameter which on success will return a handle to the device. * - * \return ::K4A_RESULT_SUCCEEDED if the device was opened successfully + * \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. @@ -67,14 +67,14 @@ K4A_EXPORT k4a_result_t k4a_device_open(uint32_t index, k4a_device_t *device_han /** Closes a k4a device. * * \param device_handle - * Handle obtained by k4a_device_open() + * 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 k4a_capture_t captures have been released with - * k4a_capture_release() + * k4a_capture_release(). * * \xmlonly * @@ -92,12 +92,13 @@ K4A_EXPORT void k4a_device_close(k4a_device_t 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 it's done - * using this capture + * 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. 0 is a check of the queue - * without blocking. Passing a value of #K4A_WAIT_INFINITE will block indefinitely. + * 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 @@ -107,24 +108,30 @@ K4A_EXPORT void k4a_device_close(k4a_device_t device_handle); * * \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 up 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 call this - * function at least once per capture interval on average. Capture data read must call k4a_capture_release() to return - * the allocated memory to the SDK. + * 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 returns an error when an internal problem is encountered, such as loss of the USB connection, a low - * memory condition, or other unexpected issues. Once an error is returned, the API will continue to return an error - * until k4a_device_stop_cameras() is called to clear the condition. + * 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, this function will return an error. 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. + * called on another thread, this function will return an error. * * \xmlonly * @@ -144,12 +151,13 @@ K4A_EXPORT k4a_wait_result_t k4a_device_get_capture(k4a_device_t device_handle, * \param device_handle * Handle obtained by k4a_device_open(). * - * \param imu_sample [out] - * pointer to a location to write the IMU sample to + * \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 IMU sample. 0 is a check of the queue - * without blocking. Passing a value of #K4A_WAIT_INFINITE will block indefinitely. + * 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 @@ -158,27 +166,31 @@ K4A_EXPORT k4a_wait_result_t k4a_device_get_capture(k4a_device_t device_handle, * \relates k4a_device_t * * \remarks - * Gets the next sample in the streamed sequence of samples from the device. If a new sample is not currently - * available, this function will block up until the timeout is reached. The SDK will buffer at least two samples worth - * of data before dropping the oldest sample. Callers needing to see all data must ensure they call this - * function at least once per IMU sample interval on average. + * 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 returns an error when an internal problem is encountered; such as loss of the USB connection, a low - * memory condition, or other unexpected issues. Once an error is returned, the API will continue to return an error - * until k4a_device_stop_imu() is called to clear the condition. - * - * \remarks - * If this function is waiting for data (non-zero timeout) when k4a_device_stop_imu() or k4a_device_close() is - * called, this function will return an error. This function needs to be called while the device is in a running state; + * 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 - * There is no need to free the imu_sample after using imu_sample. + * 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 a k4a API + * to free or release the sample. * * \xmlonly * @@ -192,20 +204,20 @@ K4A_EXPORT k4a_wait_result_t k4a_device_get_imu_sample(k4a_device_t device_handl k4a_imu_sample_t *imu_sample, int32_t timeout_in_ms); -/** create an empty capture object +/** Create an empty capture object. * * \param capture_handle - * Pointer to a location to write an empty capture handle + * Pointer to a location to store the handle. * * \relates k4a_capture_t * * \remarks - * Call this function to create a capture handle. Release it with k4a_capture_release(). + * Call this function to create a k4a_capture_t handle for a new capture. Release it with k4a_capture_release(). * - * k4a_capture_t is created with a reference of 1. + * The new capture is created with a reference of 1. * * \returns - * Returns K4A_RESULT_SUCCEEDED on success. Errors are indicated with K4A_RESULT_FAILED and error specific data can be + * Returns #K4A_RESULT_SUCCEEDED on success. Errors are indicated with #K4A_RESULT_FAILED and error specific data can be * found in the log. * * \xmlonly @@ -218,16 +230,15 @@ K4A_EXPORT k4a_wait_result_t k4a_device_get_imu_sample(k4a_device_t device_handl */ K4A_EXPORT k4a_result_t k4a_capture_create(k4a_capture_t *capture_handle); -/** Release a capture back to the SDK +/** Release a capture. * * \param capture_handle - * capture to return to SDK + * Capture to release. * * \relates k4a_capture_t * * \remarks - * Called when the user is finished using the capture. All captures must be released prior to calling - * k4a_device_close(), not doing so will result in undefined behavior. + * Call this function when finished using the capture. * * \xmlonly * @@ -239,16 +250,16 @@ K4A_EXPORT k4a_result_t k4a_capture_create(k4a_capture_t *capture_handle); */ K4A_EXPORT void k4a_capture_release(k4a_capture_t capture_handle); -/** Add a reference to a capture +/** Add a reference to a capture. * * \param capture_handle - * capture to add a reference to + * Capture to add a reference to. * * \relates k4a_capture_t * * \remarks - * Called when the user wants to add an additional reference to a capture. This reference must be removed with - * k4a_capture_release() to allow the capture to be released. + * Call this function to add an additional reference to a capture. This reference must be removed with + * k4a_capture_release(). * * \xmlonly * @@ -260,15 +271,15 @@ K4A_EXPORT void k4a_capture_release(k4a_capture_t capture_handle); */ K4A_EXPORT void k4a_capture_reference(k4a_capture_t capture_handle); -/** Get the color image associated with the given capture +/** Get the color image associated with the given capture. * * \param capture_handle - * Capture handle containing the image + * Capture handle containing the image. * * \relates k4a_capture_t * * \remarks - * Call this function to access the given image. Release the image with k4a_image_release(); + * Call this function to access the color image part of this capture. Release the k4a_image_t with k4a_image_release(); * * \xmlonly * @@ -280,15 +291,15 @@ K4A_EXPORT void k4a_capture_reference(k4a_capture_t capture_handle); */ K4A_EXPORT k4a_image_t k4a_capture_get_color_image(k4a_capture_t capture_handle); -/** Get the depth image associated with the given capture +/** Get the depth image associated with the given capture. * * \param capture_handle - * Capture handle containing the image + * Capture handle containing the image. * * \relates k4a_capture_t * * \remarks - * Call this function to access the given image. Release the image with k4a_image_release(); + * Call this function to access the depth image part of this capture. Release the k4a_image_t with k4a_image_release(); * * \xmlonly * @@ -300,15 +311,15 @@ K4A_EXPORT k4a_image_t k4a_capture_get_color_image(k4a_capture_t capture_handle) */ K4A_EXPORT k4a_image_t k4a_capture_get_depth_image(k4a_capture_t capture_handle); -/** Get the ir image associated with the given capture +/** Get the IR image associated with the given capture. * * \param capture_handle - * Capture handle containing the image + * Capture handle containing the image. * * \relates k4a_capture_t * * \remarks - * Call this function to access the given image. Release the image with k4a_image_release(); + * Call this function to access the IR image part of this capture. Release the k4a_image_t with k4a_image_release(); * * \xmlonly * @@ -320,20 +331,31 @@ K4A_EXPORT k4a_image_t k4a_capture_get_depth_image(k4a_capture_t capture_handle) */ K4A_EXPORT k4a_image_t k4a_capture_get_ir_image(k4a_capture_t capture_handle); -/** Set / add a color image to the associated capture +/** Set or add a color image to the associated capture. * * \param capture_handle - * Capture handle containing to hold the image + * Capture handle to hold the image. * * \param image_handle - * Image handle containing the image + * Image handle containing the image. * * \relates k4a_capture_t * * \remarks - * If there is already an image of this type contained by the capture, it will be dropped. The caller can pass in a NULL - * image to drop the existing image without having to add a new one. Calling capture_release() will also remove the - * image reference the capture has on the image and may result in the image being freed. + * When a k4a_image_t is added to a k4a_capture_t, the k4a_capture_t will automatically add a reference to the + * 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 k4a_image_t contained in this k4a_capture_t will automatically be dereferenced when all references to the + * k4a_capture_t are released with k4a_capture_release(). * * \xmlonly * @@ -345,20 +367,31 @@ K4A_EXPORT k4a_image_t k4a_capture_get_ir_image(k4a_capture_t capture_handle); */ K4A_EXPORT void k4a_capture_set_color_image(k4a_capture_t capture_handle, k4a_image_t image_handle); -/** Set / add a depth image to the associated capture +/** Set or add a depth image to the associated capture. * * \param capture_handle - * Capture handle containing to hold the image + * Capture handle to hold the image. * * \param image_handle - * Image handle containing the image + * Image handle containing the image. * * \relates k4a_capture_t * * \remarks - * If there is already an image of this type contained by the capture, it will be dropped. The caller can pass in a NULL - * image to drop the existing image without having to add a new one. Calling capture_release() will also remove the - * image reference the capture has on the image and may result in the image being freed. + * When a k4a_image_t is added to a k4a_capture_t, the k4a_capture_t will automatically add a reference to the + * 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 k4a_image_t contained in this k4a_capture_t will automatically be dereferenced when all references to the + * k4a_capture_t are released with k4a_capture_release(). * * \xmlonly * @@ -370,20 +403,30 @@ K4A_EXPORT void k4a_capture_set_color_image(k4a_capture_t capture_handle, k4a_im */ K4A_EXPORT void k4a_capture_set_depth_image(k4a_capture_t capture_handle, k4a_image_t image_handle); -/** Set / add an IR image to the associated capture +/** Set or add an IR image to the associated capture. * * \param capture_handle - * Capture handle containing to hold the image + * Capture handle to hold the image. * * \param image_handle - * Image handle containing the image + * Image handle containing the image. * * \relates k4a_capture_t * * \remarks - * If there is already an image of this type contained by the capture, it will be dropped. The caller can pass in a NULL - * image to drop the existing image without having to add a new one. Calling capture_release() will also remove the - * image reference the capture has on the image and may result in the image being freed. + * When a k4a_image_t is added to a k4a_capture_t, the k4a_capture_t will automatically add a reference to the + * 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 k4a_image_t contained in this k4a_capture_t will automatically be dereferenced when all references to the + * k4a_capture_t are released with k4a_capture_release(). * * \xmlonly * @@ -398,7 +441,7 @@ K4A_EXPORT void k4a_capture_set_ir_image(k4a_capture_t capture_handle, k4a_image /** Set the temperature associated with the capture. * * \param capture_handle - * Capture handle for the temperature to modify + * Capture handle to set the temperature on. * * \param temperature_c * Temperature in Celsius to store. @@ -418,7 +461,11 @@ K4A_EXPORT void k4a_capture_set_temperature_c(k4a_capture_t capture_handle, floa /** Get the temperature associated with the capture. * * \param capture_handle - * Capture handle for the temperature to access + * 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 * From ad0b6105a454b942ec0940ddc0b422912d23ae8a Mon Sep 17 00:00:00 2001 From: BrentA-Microsoft Date: Wed, 6 Mar 2019 14:40:38 -0800 Subject: [PATCH 2/9] Documentation review changes (#114) * Documentation edits (cherry picked from commit 20a83620b5248aeee4beaf0d7159cad9281f27d4) --- Doxyfile.in | 2 +- include/k4a/k4a.h | 624 ++++++++++++++--------- include/k4a/k4atypes.h | 6 +- include/k4ainternal/deloader.h | 2 +- include/{k4a => k4ainternal}/k4aplugin.h | 83 +-- include/k4arecord/playback.h | 6 +- include/k4arecord/types.h | 2 +- src/deloader/deloader.c | 1 - tools/deversion/main.c | 2 +- 9 files changed, 419 insertions(+), 309 deletions(-) rename include/{k4a => k4ainternal}/k4aplugin.h (88%) diff --git a/Doxyfile.in b/Doxyfile.in index c1222f58..c49fd2af 100644 --- a/Doxyfile.in +++ b/Doxyfile.in @@ -454,7 +454,7 @@ EXTRACT_PACKAGE = NO # included in the documentation. # The default value is: NO. -EXTRACT_STATIC = NO +EXTRACT_STATIC = YES # If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined # locally in source files will be included in the documentation. If set to NO, diff --git a/include/k4a/k4a.h b/include/k4a/k4a.h index 271c1bd3..4cd5d46a 100644 --- a/include/k4a/k4a.h +++ b/include/k4a/k4a.h @@ -73,7 +73,7 @@ K4A_EXPORT k4a_result_t k4a_device_open(uint32_t index, k4a_device_t *device_han * * \remarks Once closed, the handle is no longer valid. * - * \remarks Before closing the handle to the device, ensure that all k4a_capture_t captures have been released with + * \remarks Before closing the handle to the device, ensure that all \ref k4a_capture_t captures have been released with * k4a_capture_release(). * * \xmlonly @@ -116,7 +116,7 @@ K4A_EXPORT void k4a_device_close(k4a_device_t device_handle); * 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 + * \remarks * If the call is successful and a capture is returned, callers must call k4a_capture_release() to return the allocated * memory. * @@ -133,6 +133,9 @@ K4A_EXPORT void k4a_device_close(k4a_device_t device_handle); * 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) @@ -212,9 +215,9 @@ K4A_EXPORT k4a_wait_result_t k4a_device_get_imu_sample(k4a_device_t device_handl * \relates k4a_capture_t * * \remarks - * Call this function to create a k4a_capture_t handle for a new capture. Release it with k4a_capture_release(). + * 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 of 1. + * 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 @@ -279,7 +282,8 @@ K4A_EXPORT void k4a_capture_reference(k4a_capture_t capture_handle); * \relates k4a_capture_t * * \remarks - * Call this function to access the color image part of this capture. Release the k4a_image_t with k4a_image_release(); + * Call this function to access the color image part of this capture. Release the \ref k4a_image_t with + * k4a_image_release(); * * \xmlonly * @@ -299,7 +303,8 @@ K4A_EXPORT k4a_image_t k4a_capture_get_color_image(k4a_capture_t capture_handle) * \relates k4a_capture_t * * \remarks - * Call this function to access the depth image part of this capture. Release the k4a_image_t with k4a_image_release(); + * Call this function to access the depth image part of this capture. Release the \ref k4a_image_t with + * k4a_image_release(); * * \xmlonly * @@ -319,7 +324,8 @@ K4A_EXPORT k4a_image_t k4a_capture_get_depth_image(k4a_capture_t capture_handle) * \relates k4a_capture_t * * \remarks - * Call this function to access the IR image part of this capture. Release the k4a_image_t with k4a_image_release(); + * Call this function to access the IR image part of this capture. Release the \ref k4a_image_t with + * k4a_image_release(); * * \xmlonly * @@ -342,8 +348,8 @@ K4A_EXPORT k4a_image_t k4a_capture_get_ir_image(k4a_capture_t capture_handle); * \relates k4a_capture_t * * \remarks - * When a k4a_image_t is added to a k4a_capture_t, the k4a_capture_t will automatically add a reference to the - * k4a_image_t. + * 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 @@ -354,8 +360,8 @@ K4A_EXPORT k4a_image_t k4a_capture_get_ir_image(k4a_capture_t capture_handle); * image_handle. * * \remarks - * Any k4a_image_t contained in this k4a_capture_t will automatically be dereferenced when all references to the - * k4a_capture_t are released with k4a_capture_release(). + * 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 * @@ -378,8 +384,8 @@ K4A_EXPORT void k4a_capture_set_color_image(k4a_capture_t capture_handle, k4a_im * \relates k4a_capture_t * * \remarks - * When a k4a_image_t is added to a k4a_capture_t, the k4a_capture_t will automatically add a reference to the - * k4a_image_t. + * 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 @@ -390,8 +396,8 @@ K4A_EXPORT void k4a_capture_set_color_image(k4a_capture_t capture_handle, k4a_im * image_handle. * * \remarks - * Any k4a_image_t contained in this k4a_capture_t will automatically be dereferenced when all references to the - * k4a_capture_t are released with k4a_capture_release(). + * 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 * @@ -414,8 +420,8 @@ K4A_EXPORT void k4a_capture_set_depth_image(k4a_capture_t capture_handle, k4a_im * \relates k4a_capture_t * * \remarks - * When a k4a_image_t is added to a k4a_capture_t, the k4a_capture_t will automatically add a reference to the - * k4a_image_t. + * 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 @@ -425,8 +431,8 @@ K4A_EXPORT void k4a_capture_set_depth_image(k4a_capture_t capture_handle, k4a_im * 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 k4a_image_t contained in this k4a_capture_t will automatically be dereferenced when all references to the - * k4a_capture_t are released with k4a_capture_release(). + * 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 * @@ -479,36 +485,42 @@ K4A_EXPORT void k4a_capture_set_temperature_c(k4a_capture_t capture_handle, floa */ K4A_EXPORT float k4a_capture_get_temperature_c(k4a_capture_t capture_handle); -/** Create an image +/** Create an image. * * \param format - * The format of the image that will be stored in this image container + * The format of the image that will be stored in this image container. * * \param width_pixels - * width in pixels + * Width in pixels. * * \param height_pixels - * height in pixels + * Height in pixels. * * \param stride_bytes - * stride in bytes + * The number of bytes per horizontal line of the image. * * \param image_handle - * pointer to store image handle in. + * Pointer to store image handle in. * * \remarks - * Call this API for image formats that have consistent stride, aka no compression. Image size is calculated by - * height_pixels * stride_bytes. For advanced options use k4a_image_create_from_buffer(). + * 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 - * k4a_image_t is created with a reference of 1. + * The function will allocate an image buffer of size \p height_pixels * \p stride_bytes. * * \remarks - * Release the reference on this function with k4a_image_release + * 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 and error specific data can be - * found in the log. + * Returns #K4A_RESULT_SUCCEEDED on success. Errors are indicated with #K4A_RESULT_FAILED. * * \relates k4a_image_t * @@ -526,46 +538,50 @@ K4A_EXPORT k4a_result_t k4a_image_create(k4a_image_format_t format, int stride_bytes, k4a_image_t *image_handle); -/** Create an image from a pre-allocated buffer +/** Create an image from a pre-allocated buffer. * * \param format - * The format of the image that will be stored in this image container + * The format of the image that will be stored in this image container. * * \param width_pixels - * width in pixels + * Width in pixels. * * \param height_pixels - * height in pixels + * Height in pixels. * * \param stride_bytes - * stride in bytes + * The number of bytes per horizontal line of the image. * * \param buffer - * pointer to a pre-allocated image buffer + * Pointer to a pre-allocated image buffer. * * \param buffer_size - * size in bytes of the pre-allocated image buffer + * Size in bytes of the pre-allocated image buffer. * * \param buffer_release_cb - * buffer free function, called when all references to the buffer have been released + * 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 memory free function + * 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. + * Pointer to store image handle in. * * \remarks - * This function creates a k4a_image_t from a pre-allocated buffer. When all references to this object reach zero the - * provided buffer_release_cb callback function is called to release the memory. If this function fails, then the caller - * must free the pre-allocated memory, if this function succeeds, then the k4a_image_t is responsible for freeing the - * memory. k4a_image_t is created with a reference of 1. + * 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 - * Release the reference on this function with k4a_image_release. + * 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 + * 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 @@ -588,19 +604,18 @@ K4A_EXPORT k4a_result_t k4a_image_create_from_buffer(k4a_image_format_t format, void *buffer_release_cb_context, k4a_image_t *image_handle); -/** Get the image buffer +/** Get the image buffer. * * \param image_handle * Handle of the image for which the get operation is performed on. * * \remarks - * Returns the image buffer - * - * \remarks * Use this buffer to access the raw image data. * * \returns - * This function is not expected to return null, all k4a_image_t's are created with a buffer. + * 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 * @@ -614,19 +629,18 @@ K4A_EXPORT k4a_result_t k4a_image_create_from_buffer(k4a_image_format_t format, */ K4A_EXPORT uint8_t *k4a_image_get_buffer(k4a_image_t image_handle); -/** Get the image buffer size +/** Get the image buffer size. * * \param image_handle * Handle of the image for which the get operation is performed on. * * \remarks - * Returns the size of the image buffer in bytes - * - * \remarks - * Use this function to get the size of the image buffer returned by k4a_image_get_buffer() + * Use this function to know what the size of the image buffer is returned by k4a_image_get_buffer(). * * \returns - * This function is not expected to return 0, all k4a_image_t's are created with a buffer. + * 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 * @@ -640,19 +654,17 @@ K4A_EXPORT uint8_t *k4a_image_get_buffer(k4a_image_t image_handle); */ K4A_EXPORT size_t k4a_image_get_size(k4a_image_t image_handle); -/** Get the image format of the image +/** Get the format of the image. * * \param image_handle * Handle of the image for which the get operation is performed on. * * \remarks - * Returns the image format - * - * \remarks - * Use this function to know what the image format is. + * Use this function to determine the format of the image buffer. * * \returns - * This function is not expected to fail, all k4a_image_t's are created with a known format. + * 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 * @@ -666,16 +678,14 @@ K4A_EXPORT size_t k4a_image_get_size(k4a_image_t image_handle); */ K4A_EXPORT k4a_image_format_t k4a_image_get_format(k4a_image_t image_handle); -/** Get the image width in pixels +/** Get the image width in pixels. * * \param image_handle * Handle of the image for which the get operation is performed on. * - * \remarks - * Returns the image width in pixels - * * \returns - * This function is not expected to fail, all k4a_image_t's are created with a known width. + * 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 * @@ -689,16 +699,14 @@ K4A_EXPORT k4a_image_format_t k4a_image_get_format(k4a_image_t image_handle); */ K4A_EXPORT int k4a_image_get_width_pixels(k4a_image_t image_handle); -/** Get the image height in pixels +/** Get the image height in pixels. * * \param image_handle * Handle of the image for which the get operation is performed on. * - * \remarks - * Returns the image height in pixels - * * \returns - * This function is not expected to fail, all k4a_image_t's are created with a known height. + * 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 * @@ -712,16 +720,14 @@ K4A_EXPORT int k4a_image_get_width_pixels(k4a_image_t image_handle); */ K4A_EXPORT int k4a_image_get_height_pixels(k4a_image_t image_handle); -/** Get the image stride in bytes +/** Get the image stride in bytes. * * \param image_handle * Handle of the image for which the get operation is performed on. * - * \remarks - * Returns the image stride in bytes - * * \returns - * This function is not expected to fail, all k4a_image_t's are created with a known stride. + * 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 * @@ -745,7 +751,9 @@ K4A_EXPORT int k4a_image_get_stride_bytes(k4a_image_t image_handle); * They may be used for relative comparison, but their absolute value has no defined meaning. * * \returns - * Returning a timestamp of 0 is considered an error. + * 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 * @@ -759,7 +767,7 @@ K4A_EXPORT int k4a_image_get_stride_bytes(k4a_image_t image_handle); */ K4A_EXPORT uint64_t k4a_image_get_timestamp_usec(k4a_image_t image_handle); -/** Get the image exposure in microseconds +/** Get the image exposure in microseconds. * * \param image_handle * Handle of the image for which the get operation is performed on. @@ -768,7 +776,8 @@ K4A_EXPORT uint64_t k4a_image_get_timestamp_usec(k4a_image_t image_handle); * Returns an exposure time in microseconds. This is only supported on color image formats. * * \returns - * Returning an exposure of 0 is considered an error. + * 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 * @@ -782,16 +791,17 @@ K4A_EXPORT uint64_t k4a_image_get_timestamp_usec(k4a_image_t image_handle); */ K4A_EXPORT uint64_t k4a_image_get_exposure_usec(k4a_image_t image_handle); -/** Get the image white balance +/** 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 captures. + * Returns the image's white balance. This function is only valid for color captures, and not for depth or IR captures. * * \returns - * White balance in Kelvin, 0 if image format is not supported by the given capture. + * 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 * @@ -805,17 +815,16 @@ K4A_EXPORT uint64_t k4a_image_get_exposure_usec(k4a_image_t image_handle); */ K4A_EXPORT uint32_t k4a_image_get_white_balance(k4a_image_t image_handle); -/** Get the image's ISO speed +/** Get the image ISO speed. * * \param image_handle * Handle of the image for which the get operation is performed on. * * \remarks - * Returns the image's ISO speed - * This function is only valid for color captures, and not for depth captures. + * This function is only valid for color captures, and not for depth or IR captures. * * \returns - * 0 indicates the ISO speed was not available or an error occurred. + * Returns the ISO speed of the image. 0 indicates the ISO speed was not available or an error occurred. * * \relates k4a_image_t * @@ -839,7 +848,10 @@ K4A_EXPORT uint32_t k4a_image_get_iso_speed(k4a_image_t image_handle); * * \remarks * Use this function in conjunction with k4a_image_create() or k4a_image_create_from_buffer() to construct a - * k4a_image_t. A timestamp of 0 is not valid. + * \ref k4a_image_t. + * + * \remarks + * Set a timestamp of 0 to indicate that the timestamp is not valid. * * \relates k4a_image_t * @@ -859,11 +871,12 @@ K4A_EXPORT void k4a_image_set_timestamp_usec(k4a_image_t image_handle, uint64_t * Handle of the image to set the exposure time on. * * \param exposure_usec - * exposure time of the image in microseconds. + * 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 - * k4a_image_t. An exposure time of 0 is not valid. Only use this function with color image formats. + * \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 * @@ -883,11 +896,12 @@ K4A_EXPORT void k4a_image_set_exposure_time_usec(k4a_image_t image_handle, uint6 * Handle of the image to set the white balance on. * * \param white_balance - * White balance of the image. + * 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 - * k4a_image_t. A white balance of 0 is not valid. Only use this function with color image formats. + * \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 * @@ -911,7 +925,7 @@ K4A_EXPORT void k4a_image_set_white_balance(k4a_image_t image_handle, uint32_t w * * \remarks * Use this function in conjunction with k4a_image_create() or k4a_image_create_from_buffer() to construct a - * k4a_image_t. An ISO speed of 0 is not valid. Only use this function with color image formats. + * \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 * @@ -931,7 +945,8 @@ K4A_EXPORT void k4a_image_set_iso_speed(k4a_image_t image_handle, uint32_t iso_s * 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. + * 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 * @@ -951,8 +966,8 @@ K4A_EXPORT void k4a_image_reference(k4a_image_t 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. Caller should - * assume this function frees the object, as a result the object should not be accessed after this call completes. + * 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 * @@ -966,23 +981,24 @@ K4A_EXPORT void k4a_image_reference(k4a_image_t image_handle); */ K4A_EXPORT void k4a_image_release(k4a_image_t image_handle); -/** Starts the K4A device's cameras +/** Starts color and depth camera capture. * * \param device_handle - * Handle obtained by k4a_device_open() + * 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. + * 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 + * ::K4A_RESULT_SUCCEEDED is returned on success. * * \relates k4a_device_t * - * \remarks Individual sensors configured to run will now start stream capture data. + * \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 k4a_device_t until + * 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 @@ -995,10 +1011,10 @@ K4A_EXPORT void k4a_image_release(k4a_image_t image_handle); */ K4A_EXPORT k4a_result_t k4a_device_start_cameras(k4a_device_t device_handle, k4a_device_configuration_t *config); -/** Stops the K4A device's cameras +/** Stops the color and depth camera capture. * * \param device_handle - * Handle obtained by k4a_device_open() + * Handle obtained by k4a_device_open(). * * \relates k4a_device_t * @@ -1006,6 +1022,10 @@ K4A_EXPORT k4a_result_t k4a_device_start_cameras(k4a_device_t device_handle, k4a * 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) @@ -1016,21 +1036,24 @@ K4A_EXPORT k4a_result_t k4a_device_start_cameras(k4a_device_t device_handle, k4a */ K4A_EXPORT void k4a_device_stop_cameras(k4a_device_t device_handle); -/** Starts the K4A IMU +/** Starts the IMU sample stream. * * \param device_handle - * Handle obtained by k4a_device_open() + * 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 + * ::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 API a second time without calling stop after - * the first call. 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. + * 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 * @@ -1042,17 +1065,20 @@ K4A_EXPORT void k4a_device_stop_cameras(k4a_device_t device_handle); */ K4A_EXPORT k4a_result_t k4a_device_start_imu(k4a_device_t device_handle); -/** Stops the K4A IMU +/** Stops the IMU capture. * * \param device_handle - * Handle obtained by k4a_device_open() + * 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. It is ok to call the API twice, if the IMU is not running nothing will - * happen. + * 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 * @@ -1064,29 +1090,35 @@ K4A_EXPORT k4a_result_t k4a_device_start_imu(k4a_device_t device_handle); */ K4A_EXPORT void k4a_device_stop_imu(k4a_device_t device_handle); -/** Get the K4A device serial number +/** Get the K4A device serial number. * * \param device_handle - * Handle obtained by k4a_device_open() + * Handle obtained by k4a_device_open(). * * \param serial_number - * Location to write the serial number to. On output, this will be an ASCII null terminated string. This value may be - * NULL, so that \p serial_number_size may be used to return the size of the buffer needed to store the string. + * 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. On output, this value is set to the actual number of bytes in the - * serial number (including the null terminator) + * 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 needed size of the \p serial_number buffer is + * 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. Set serial_number to NULL to query for serial number size required by the - * API + * 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 * @@ -1100,13 +1132,13 @@ K4A_EXPORT k4a_buffer_result_t k4a_device_get_serialnum(k4a_device_t device_hand char *serial_number, size_t *serial_number_size); -/** Get the version numbers of the K4A subsystems' firmware +/** Get the version numbers of the device's subsystems. * * \param device_handle - * Handle obtained by k4a_device_open() + * Handle obtained by k4a_device_open(). * * \param version - * Location to write the version info to + * 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. @@ -1123,22 +1155,32 @@ K4A_EXPORT k4a_buffer_result_t k4a_device_get_serialnum(k4a_device_t device_hand */ K4A_EXPORT k4a_result_t k4a_device_get_version(k4a_device_t device_handle, k4a_hardware_version_t *version); -/** Get the K4A color sensor control value +/** Get the K4A color sensor control value. * * \param device_handle - * Handle obtained by k4a_device_open() + * Handle obtained by k4a_device_open(). * * \param command - * Color sensor control command + * Color sensor control command. * * \param mode - * Color sensor control mode (auto / manual) + * Location to store the color sensor's control mode. This mode represents whether the command is in automatic or manual + * mode. * * \param value - * Color sensor control value. Only valid when mode is manual + * 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 + * ::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. * * \relates k4a_device_t * @@ -1155,22 +1197,31 @@ K4A_EXPORT k4a_result_t k4a_device_get_color_control(k4a_device_t device_handle, k4a_color_control_mode_t *mode, int32_t *value); -/** Set the K4A color sensor control value +/** Set the K4A color sensor control value. * * \param device_handle - * Handle obtained by k4a_device_open() + * Handle obtained by k4a_device_open(). * * \param command - * Color sensor control command + * Color sensor control command. * * \param mode - * Color sensor control mode (auto / manual) + * Color sensor control mode to set. This mode represents whether the command is in automatic or manual mode. * * \param value - * Color sensor control value. Only valid when mode is manual + * 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 + * ::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. * * \relates k4a_device_t * @@ -1193,17 +1244,18 @@ K4A_EXPORT k4a_result_t k4a_device_set_color_control(k4a_device_t 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 if the caller wants to query for + * 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 to write the raw data to. On - * return this variable is updated with the amount of data actually written to the buffer. + * 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, ::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. + * 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 * @@ -1219,8 +1271,7 @@ K4A_EXPORT k4a_buffer_result_t k4a_device_get_raw_calibration(k4a_device_t devic uint8_t *data, size_t *data_size); -/** Get the camera calibration for the entire K4A device. The output struct is used as input to all transformation - * functions. +/** Get the camera calibration for the entire K4A device. * * \param device_handle * Handle obtained by k4a_device_open(). @@ -1229,7 +1280,7 @@ K4A_EXPORT k4a_buffer_result_t k4a_device_get_raw_calibration(k4a_device_t devic * Mode in which depth camera is operated. * * \param color_resolution - * Resolution in which color camera is operated + * Resolution in which color camera is operated. * * \param calibration * Location to write the calibration @@ -1237,6 +1288,18 @@ K4A_EXPORT k4a_buffer_result_t k4a_device_get_raw_calibration(k4a_device_t devic * \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 @@ -1269,11 +1332,13 @@ K4A_EXPORT k4a_result_t k4a_device_get_calibration(k4a_device_t device_handle, * \relates k4a_device_t * * \remarks - * If 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 sync_in_jack_connected is true then \ref + * 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) @@ -1289,7 +1354,7 @@ K4A_EXPORT k4a_result_t k4a_device_get_sync_jack(k4a_device_t device_handle, /** 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 + * 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. @@ -1298,14 +1363,26 @@ K4A_EXPORT k4a_result_t k4a_device_get_sync_jack(k4a_device_t device_handle, * Mode in which depth camera is operated. * * \param color_resolution - * Resolution in which color camera is operated + * Resolution in which color camera is operated. * * \param calibration - * Location to write the 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 @@ -1322,32 +1399,33 @@ K4A_EXPORT k4a_result_t k4a_calibration_get_from_raw(char *raw_calibration, 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 +/** 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 obtained by k4a_transformation_get_calibration(). + * Location to read the camera calibration data. * * \param source_point3d - * The 3d coordinates in millimeters representing a point in \p source_camera + * The 3D coordinates in millimeters representing a point in \p source_camera. * * \param source_camera - * The current camera + * The current camera. * * \param target_camera - * The target camera + * The target camera. * * \param target_point3d - * The new 3d coordinates of the input point in \p target_camera + * Pointer to the output where the new 3D coordinates of the input point in the coordinate space of \p target_camera is + * stored. * * \returns * ::K4A_RESULT_SUCCEEDED if \p target_point3d 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. The values \p source_camera and \p target_point3d can be identical in which case \p - * target_point3d will be identical to \p source_point3d. + * 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 will be + * identical to \p source_point3d. * * \relates k4a_calibration_t * @@ -1365,42 +1443,49 @@ K4A_EXPORT k4a_result_t k4a_calibration_3d_to_3d(const k4a_calibration_t *calibr const k4a_calibration_type_t target_camera, k4a_float3_t *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 +/** 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_transformation_get_calibration(). + * Location to read the camera calibration obtained by k4a_device_get_calibration(). * * \param source_point2d - * The 2d pixel coordinates in \p source_camera + * The 2D pixel in \p source_camera coordinates. * * \param source_depth - * The depth of \p source_point2d in millimeters + * The depth of \p source_point2d in millimeters. * * \param source_camera - * The current camera + * The current camera. * * \param target_camera - * The target camera + * The target camera. * * \param target_point3d - * The 3d coordinates of the input pixel in the coordinate system of \p target_camera + * Pointer to the output where the 3D coordinates of the input pixel in the coordinate system of \p target_camera is + * stored. * * \param valid - * Takes a value of 1 if the transformation was successful and 0, otherwise + * 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 was successfully written. ::K4A_RESULT_FAILED if \p calibration - * contained invalid transformation parameters. + * 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 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. If \p - * target_camera is different from \p source_camera, the 3d point is transformed to \p target_camera using - * k4a_transformation_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. If \p source_point2d is not considered as valid pixel coordinate - * according to the intrinsic camera model, \p valid is set to 0 and 1, otherwise. The user should not use the result - * of this transformation if \p valid was set to 0. + * 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. 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 if \p valid was set to 0. * * \relates k4a_calibration_t * @@ -1420,37 +1505,43 @@ K4A_EXPORT k4a_result_t k4a_calibration_2d_to_3d(const k4a_calibration_t *calibr k4a_float3_t *target_point3d, int *valid); -/** Transform a 3d point of a source coordinate system into a 2d pixel coordinate of the target camera +/** 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_transformation_get_calibration(). + * Location to read the camera calibration obtained by k4a_device_get_calibration(). * * \param source_point3d - * The 3d coordinates in millimeters representing a point in \p source_camera + * The 3D coordinates in millimeters representing a point in \p source_camera * * \param source_camera - * The current camera + * The current camera. * * \param target_camera - * The target camera + * The target camera. * * \param target_point2d - * The 2d pixel coordinates in \p target_camera + * Pointer to the output where the 2D pixel in \p target_camera coordinates is stored. * * \param valid - * Takes a value of 1 if the transformation was successful and 0, otherwise + * The output parameter returns a value of 1 if the \p source_point3d 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. + * 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 is transformed to \p target_camera using - * k4a_transformation_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. If the intrinsic camera model - * cannot handle this projection, \p valid is set to 0 and 1, otherwise. The user should not use the result of this - * transformation if \p valid was set to 0. + * 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 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 * @@ -1469,43 +1560,50 @@ K4A_EXPORT k4a_result_t k4a_calibration_3d_to_2d(const k4a_calibration_t *calibr 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 +/** 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_transformation_get_calibration(). + * Location to read the camera calibration obtained by k4a_device_get_calibration(). * * \param source_point2d - * The 2d pixel coordinates in \p source_camera + * The 2D pixel in \p source_camera coordinates. * * \param source_depth - * The depth of \p source_point2d in millimeters + * The depth of \p source_point2d in millimeters. * * \param source_camera - * The current camera + * The current camera. * * \param target_camera - * The target camera + * The target camera. * * \param target_point2d - * The 2d pixel coordinates in \p target_camera + * The 2D pixel in \p target_camera coordinates. * * \param valid - * Takes a value of 1 if the transformation was successful and 0, otherwise + * 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. + * 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 allows generating a mapping between pixel coordinates of depth and color cameras. Internally, the - * function calls k4a_transformation_2d_to_3d() to compute the 3d point corresponding to \p source_point2d and to - * transform the resulting 3d point into the camera coordinate system of \p target_camera. The function then calls - * k4a_transformation_3d_to_2d() to project this 3d point onto the image plane of \p target_camera. 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. The parameter valid is to 0 if k4a_transformation_2d_to_3d() or - * k4a_transformation_3d_to_2d() return an invalid transformation. The user should not use the result of this - * transformation if \p valid was set to 0. + * 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 * @@ -1525,13 +1623,21 @@ K4A_EXPORT k4a_result_t k4a_calibration_2d_to_2d(const k4a_calibration_t *calibr k4a_float2_t *target_point2d, int *valid); -/** Get handle to transformation context. +/** Get handle to transformation handle. * * \param calibration - * Location to read calibration obtained by k4a_device_get_calibration(). + * A calibration structure obtained by k4a_device_get_calibration(). * * \returns - * Location of handle to the transformation context. A null pointer is returned if creation fails. + * 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 * @@ -1545,10 +1651,10 @@ K4A_EXPORT k4a_result_t k4a_calibration_2d_to_2d(const k4a_calibration_t *calibr */ K4A_EXPORT k4a_transformation_t k4a_transformation_create(const k4a_calibration_t *calibration); -/** Destroy transformation context. +/** Destroy transformation handle. * * \param transformation_handle - * Location of handle to transformation context + * Transformation handle to destroy. * * \relates k4a_transformation_t * @@ -1565,13 +1671,31 @@ K4A_EXPORT void k4a_transformation_destroy(k4a_transformation_t transformation_h /** Transforms the depth map into the geometry of the color camera. * * \param transformation_handle - * Handle to transformation context + * Transformation handle. * * \param depth_image - * Handle to input depth image + * Handle to input depth image. * * \param transformed_depth_image - * Handle to output 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. @@ -1590,19 +1714,39 @@ K4A_EXPORT k4a_result_t k4a_transformation_depth_image_to_color_camera(k4a_trans const k4a_image_t depth_image, k4a_image_t transformed_depth_image); -/** Transforms the color image into the geometry of the depth camera. +/** Transforms a color image into the geometry of the depth camera. * * \param transformation_handle - * Handle to transformation context + * Transformation handle. * * \param depth_image - * Handle to input depth image + * Handle to input depth image. * * \param color_image - * Handle to input color image + * Handle to input color image. * * \param transformed_color_image - * Handle to output 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. @@ -1622,19 +1766,39 @@ K4A_EXPORT k4a_result_t k4a_transformation_color_image_to_depth_camera(k4a_trans 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. +/** Transforms the depth image into 3 planar images representing X, Y and Z-coordinates of corresponding 3D points. * * \param transformation_handle - * Handle to transformation context + * Transformation handle. * * \param depth_image - * Handle to input depth image + * Handle to input depth image. * * \param camera - * Geometry in which depth map was computed (depth or color camera) + * Geometry in which depth map was computed. * * \param xyz_image - * Handle to output 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. diff --git a/include/k4a/k4atypes.h b/include/k4a/k4atypes.h index 2fe653ab..a1ea6f94 100644 --- a/include/k4a/k4atypes.h +++ b/include/k4a/k4atypes.h @@ -69,7 +69,7 @@ K4A_DECLARE_HANDLE(k4a_capture_t); * Handle to a k4a image. * * Handles are created with k4a_capture_get_color_image(), k4a_capture_get_depth_image(), k4a_capture_get_ir_image(), - * k4a_image_create(), or k4a_image_create_with_buffer() and closed with k4a_image_release(). Invalid handles are set to + * k4a_image_create(), or k4a_image_create_from_buffer() and closed with k4a_image_release(). Invalid handles are set to * 0. * * \xmlonly @@ -83,8 +83,8 @@ K4A_DECLARE_HANDLE(k4a_image_t); /** \class k4a_transformation_t k4a.h * Handle to a k4a transformation context. * - * Handles are created with k4a_device_get_transformation_context() and closed with - * k4a_transformation_context_release(). Invalid handles are set to 0. + * Handles are created with k4a_transformation_create() and closed with + * k4a_transformation_destroy(). Invalid handles are set to 0. * * \xmlonly * diff --git a/include/k4ainternal/deloader.h b/include/k4ainternal/deloader.h index 5774215d..0ab51d13 100644 --- a/include/k4ainternal/deloader.h +++ b/include/k4ainternal/deloader.h @@ -8,7 +8,7 @@ #pragma once -#include +#include #ifdef __cplusplus extern "C" { diff --git a/include/k4a/k4aplugin.h b/include/k4ainternal/k4aplugin.h similarity index 88% rename from include/k4a/k4aplugin.h rename to include/k4ainternal/k4aplugin.h index eaf09121..107827ce 100644 --- a/include/k4a/k4aplugin.h +++ b/include/k4ainternal/k4aplugin.h @@ -18,6 +18,10 @@ #define __cdecl /**< __cdecl not defined in Linux */ #endif +#ifdef __cplusplus +extern "C" { +#endif + /** * Current Version of the k4A Depth Engine Plugin API * @@ -47,29 +51,19 @@ /** Supported Depth Engine modes * - * \xmlonly - * - * k4aplugin.h (include k4a/k4aplugin.h) - * - * \endxmlonly */ typedef enum { K4A_DEPTH_ENGINE_MODE_UNKNOWN = -1, /**< Unknown Depth Engine mode */ - K4A_DEPTH_ENGINE_MODE_LT_SW_BINNING = 2, /**< Translates to K4A_DEPTH_MODE_NFOV_2X2BINNED */ - K4A_DEPTH_ENGINE_MODE_PCM = 3, /**< Translates to K4A_DEPTH_MODE_PASSIVE_IR */ - K4A_DEPTH_ENGINE_MODE_LT_NATIVE = 4, /**< Translates to K4A_DEPTH_MODE_NFOV_UNBINNED */ - K4A_DEPTH_ENGINE_MODE_MEGA_PIXEL = 5, /**< Translates to K4A_DEPTH_MODE_WFOV_UNBINNED */ - K4A_DEPTH_ENGINE_MODE_QUARTER_MEGA_PIXEL = 7, /**< Translates to K4A_DEPTH_MODE_WFOV_2X2BINNED */ + K4A_DEPTH_ENGINE_MODE_LT_SW_BINNING = 2, /**< Translates to ::K4A_DEPTH_MODE_NFOV_2X2BINNED */ + K4A_DEPTH_ENGINE_MODE_PCM = 3, /**< Translates to ::K4A_DEPTH_MODE_PASSIVE_IR */ + K4A_DEPTH_ENGINE_MODE_LT_NATIVE = 4, /**< Translates to ::K4A_DEPTH_MODE_NFOV_UNBINNED */ + K4A_DEPTH_ENGINE_MODE_MEGA_PIXEL = 5, /**< Translates to ::K4A_DEPTH_MODE_WFOV_UNBINNED */ + K4A_DEPTH_ENGINE_MODE_QUARTER_MEGA_PIXEL = 7, /**< Translates to ::K4A_DEPTH_MODE_WFOV_2X2BINNED */ } k4a_depth_engine_mode_t; /** Depth Engine output types * - * \xmlonly - * - * k4aplugin.h (include k4a/k4aplugin.h) - * - * \endxmlonly */ typedef enum { @@ -80,11 +74,6 @@ typedef enum /** Depth Engine supported input formats * - * \xmlonly - * - * k4aplugin.h (include k4a/k4aplugin.h) - * - * \endxmlonly */ typedef enum { @@ -95,11 +84,6 @@ typedef enum /** Transform Engine types * - * \xmlonly - * - * k4aplugin.h (include k4a/k4aplugin.h) - * - * \endxmlonly */ typedef enum { @@ -110,11 +94,6 @@ typedef enum /** Depth Engine output frame information * - * \xmlonly - * - * k4aplugin.h (include k4a/k4aplugin.h) - * - * \endxmlonly */ typedef struct _k4a_depth_engine_output_frame_info_t { @@ -131,11 +110,6 @@ typedef struct _k4a_depth_engine_output_frame_info_t * /remarks At Runtime, please set to null, we parse these information from a * raw compressed input. Some internal testing may use this to pass in temperature info. * - * \xmlonly - * - * k4aplugin.h (include k4a/k4aplugin.h) - * - * \endxmlonly */ typedef struct _k4a_depth_engine_input_frame_info_t { @@ -147,15 +121,10 @@ typedef struct _k4a_depth_engine_input_frame_info_t /** Depth Engine return codes * - * \xmlonly - * - * k4aplugin.h (include k4a/k4aplugin.h) - * - * \endxmlonly */ typedef enum { - K4A_DEPTH_ENGINE_RESULT_SUCCEEDED = 0, + K4A_DEPTH_ENGINE_RESULT_SUCCEEDED = 0, /**< Result succeeded */ // Frame data error, require caller to retry with expected frame data K4A_DEPTH_ENGINE_RESULT_DATA_ERROR_INVALID_INPUT_BUFFER_SIZE = 1, /**< Invalid input buffer size */ @@ -188,11 +157,6 @@ typedef enum * /remarks On load, k4a will validate that major versions match between the SDK * and the plugin. * - * \xmlonly - * k4a_depth - * k4aplugin.h (include k4a/k4aplugin.h) - * - * \endxmlonly */ typedef struct { @@ -203,28 +167,14 @@ typedef struct /** Depth Engine context handle to be implemented by plugin * - * \xmlonly - * - * k4aplugin.h (include k4a/k4aplugin.h) - * - * \endxmlonly */ typedef struct k4a_depth_engine_context_t k4a_depth_engine_context_t; /** Transform Engine context handle to be implemented by plugin * - * \xmlonly - * - * k4aplugin.h (include k4a/k4aplugin.h) - * - * \endxmlonly */ typedef struct k4a_transform_engine_context_t k4a_transform_engine_context_t; -#ifdef __cplusplus -extern "C" { -#endif - /** Callback function for depth engine finishing processing. * * \param context @@ -265,7 +215,7 @@ typedef void(__stdcall k4a_processing_complete_cb_t)(void *context, int status, * An optional context to be passed back to the callback * * \returns - * K4A_DEPTH_ENGINE_RESULT_SUCCEEDED on success, or the proper failure code on + * ::K4A_DEPTH_ENGINE_RESULT_SUCCEEDED on success, or the proper failure code on * failure */ typedef k4a_depth_engine_result_code_t(__stdcall *k4a_de_create_and_initialize_fn_t)( @@ -305,7 +255,7 @@ typedef k4a_depth_engine_result_code_t(__stdcall *k4a_de_create_and_initialize_f * The input frame information (internal use only), should pass in null at runtime * * \returns - * K4A_DEPTH_ENGINE_RESULT_SUCCEEDED on success, or the proper failure code on + * ::K4A_DEPTH_ENGINE_RESULT_SUCCEEDED on success, or the proper failure code on * failure */ typedef k4a_depth_engine_result_code_t(__stdcall *k4a_de_process_frame_fn_t)( @@ -350,7 +300,7 @@ typedef void(__stdcall *k4a_de_destroy_fn_t)(k4a_depth_engine_context_t **contex * An optional context to be passed back to the callback * * \returns - * K4A_DEPTH_ENGINE_RESULT_SUCCEEDED on success, or the proper failure code on + * ::K4A_DEPTH_ENGINE_RESULT_SUCCEEDED on success, or the proper failure code on * failure */ typedef k4a_depth_engine_result_code_t(__stdcall *k4a_te_create_and_initialize_fn_t)( @@ -386,7 +336,7 @@ typedef k4a_depth_engine_result_code_t(__stdcall *k4a_te_create_and_initialize_f * Size of the output_frame buffer in bytes * * \returns - * K4A_DEPTH_ENGINE_RESULT_SUCCEEDED on success, or the proper failure code on + * ::K4A_DEPTH_ENGINE_RESULT_SUCCEEDED on success, or the proper failure code on * failure */ typedef k4a_depth_engine_result_code_t(__stdcall *k4a_te_process_frame_fn_t)(k4a_transform_engine_context_t *context, @@ -426,11 +376,6 @@ typedef void(__stdcall *k4a_te_destroy_fn_t)(k4a_transform_engine_context_t **co * k4a_plugin_t. The plugin must properly fill out all fields of the plugin for * the K4A SDK to accept the plugin. * - * \xmlonly - * - * k4aplugin.h (include k4a/k4aplugin.h) - * - * \endxmlonly */ typedef struct _k4a_plugin_t { diff --git a/include/k4arecord/playback.h b/include/k4arecord/playback.h index 6268f556..3e433f86 100644 --- a/include/k4arecord/playback.h +++ b/include/k4arecord/playback.h @@ -190,7 +190,8 @@ K4ARECORD_EXPORT k4a_buffer_result_t k4a_playback_get_tag(k4a_playback_t playbac * * \remarks * Capture objects will always contain at least 1 image, but may have images missing if frames were dropped in the - * original recording. When calling k4a_capture_get_*_image(), the image should be checked for NULL. + * 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 * @@ -229,7 +230,8 @@ K4ARECORD_EXPORT k4a_stream_result_t k4a_playback_get_next_capture(k4a_playback_ * * \remarks * Capture objects will always contain at least 1 image, but may have images missing if frames were dropped in the - * original recording. When calling k4a_capture_get_*_image(), the image should be checked for NULL. + * 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 * diff --git a/include/k4arecord/types.h b/include/k4arecord/types.h index 9e7e48ce..b2ab1137 100644 --- a/include/k4arecord/types.h +++ b/include/k4arecord/types.h @@ -117,7 +117,7 @@ typedef struct _k4a_record_configuration_t /** * 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 + * This value is 0 unless \p wired_sync_mode is set to ::K4A_WIRED_SYNC_MODE_SUBORDINATE */ uint32_t subordinate_delay_off_master_usec; diff --git a/src/deloader/deloader.c b/src/deloader/deloader.c index e8a01349..01d7e285 100644 --- a/src/deloader/deloader.c +++ b/src/deloader/deloader.c @@ -4,7 +4,6 @@ #include #include -#include #include #include diff --git a/tools/deversion/main.c b/tools/deversion/main.c index 6dbde4dc..a62d1588 100644 --- a/tools/deversion/main.c +++ b/tools/deversion/main.c @@ -3,7 +3,7 @@ #include -#include +#include #include static void print_usage() From f0ae2a57df2b34a0c729874ad92201383f95d3ee Mon Sep 17 00:00:00 2001 From: BrentA-Microsoft Date: Thu, 7 Mar 2019 12:39:22 -0800 Subject: [PATCH 3/9] Documentation review (#118) * Documentation review changes (cherry picked from commit b0c33e3d681fb5208e6b0e65ba3278b42129e097) --- include/k4a/k4a.h | 30 +- include/k4a/k4atypes.h | 636 ++++++++++++++++++++++++-------- include/k4ainternal/k4aplugin.h | 12 +- include/k4ainternal/logging.h | 4 +- include/k4arecord/playback.h | 103 +++--- include/k4arecord/record.h | 33 +- include/k4arecord/types.h | 35 +- 7 files changed, 615 insertions(+), 238 deletions(-) diff --git a/include/k4a/k4a.h b/include/k4a/k4a.h index 4cd5d46a..bdc9bb8e 100644 --- a/include/k4a/k4a.h +++ b/include/k4a/k4a.h @@ -25,7 +25,7 @@ extern "C" { * \returns Number of sensors connected to the PC. * * \remarks - * This API counts the number of K4A devices connected to the host PC. + * This API counts the number of Azure Kinect devices connected to the host PC. * * \xmlonly * @@ -37,7 +37,7 @@ extern "C" { */ K4A_EXPORT uint32_t k4a_device_get_installed_count(void); -/** Open a k4a device. +/** Open an Azure Kinect device. * * \param index * The index of the device to open, starting with 0. Optionally pass in #K4A_DEVICE_DEFAULT. @@ -49,7 +49,7 @@ K4A_EXPORT uint32_t k4a_device_get_installed_count(void); * * \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 k4a API calls. + * 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() @@ -64,7 +64,7 @@ K4A_EXPORT uint32_t k4a_device_get_installed_count(void); */ K4A_EXPORT k4a_result_t k4a_device_open(uint32_t index, k4a_device_t *device_handle); -/** Closes a k4a device. +/** Closes an Azure Kinect device. * * \param device_handle * Handle obtained by k4a_device_open(). @@ -192,8 +192,8 @@ K4A_EXPORT k4a_wait_result_t k4a_device_get_capture(k4a_device_t device_handle, * 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 a k4a API - * to free or release the sample. + * 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 * @@ -1090,7 +1090,7 @@ K4A_EXPORT k4a_result_t k4a_device_start_imu(k4a_device_t device_handle); */ K4A_EXPORT void k4a_device_stop_imu(k4a_device_t device_handle); -/** Get the K4A device serial number. +/** Get the Azure Kinect device serial number. * * \param device_handle * Handle obtained by k4a_device_open(). @@ -1155,7 +1155,7 @@ K4A_EXPORT k4a_buffer_result_t k4a_device_get_serialnum(k4a_device_t device_hand */ K4A_EXPORT k4a_result_t k4a_device_get_version(k4a_device_t device_handle, k4a_hardware_version_t *version); -/** Get the K4A color sensor control value. +/** Get the Azure Kinect color sensor control value. * * \param device_handle * Handle obtained by k4a_device_open(). @@ -1182,6 +1182,10 @@ K4A_EXPORT k4a_result_t k4a_device_get_version(k4a_device_t device_handle, k4a_h * 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 @@ -1197,7 +1201,7 @@ K4A_EXPORT k4a_result_t k4a_device_get_color_control(k4a_device_t device_handle, k4a_color_control_mode_t *mode, int32_t *value); -/** Set the K4A color sensor control value. +/** Set the Azure Kinect color sensor control value. * * \param device_handle * Handle obtained by k4a_device_open(). @@ -1223,6 +1227,10 @@ K4A_EXPORT k4a_result_t k4a_device_get_color_control(k4a_device_t device_handle, * 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 @@ -1238,7 +1246,7 @@ K4A_EXPORT k4a_result_t k4a_device_set_color_control(k4a_device_t device_handle, k4a_color_control_mode_t mode, int32_t value); -/** Get the raw calibration blob for the entire K4A device. +/** Get the raw calibration blob for the entire Azure Kinect device. * * \param device_handle * Handle obtained by k4a_device_open(). @@ -1271,7 +1279,7 @@ K4A_EXPORT k4a_buffer_result_t k4a_device_get_raw_calibration(k4a_device_t devic uint8_t *data, size_t *data_size); -/** Get the camera calibration for the entire K4A device. +/** Get the camera calibration for the entire Azure Kinect device. * * \param device_handle * Handle obtained by k4a_device_open(). diff --git a/include/k4a/k4atypes.h b/include/k4a/k4atypes.h index a1ea6f94..74177ede 100644 --- a/include/k4a/k4atypes.h +++ b/include/k4a/k4atypes.h @@ -23,12 +23,13 @@ extern "C" { #endif /** - * Internal use only. Declare an opaque handle type. + * 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 k4a APIs. - * The macro should not be used outside of the k4a headers. + * \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_ \ @@ -37,11 +38,10 @@ extern "C" { } * _handle_name_; /** \class k4a_device_t k4a.h - * Handle to a k4a device. + * Handle to an Azure Kinect device. * - * Handles are created with k4a_device_open() and closed - * with k4a_device_close(). - * Invalid handles are set to 0. + * \remarks + * Handles are created with k4a_device_open() and closed with k4a_device_close(). Invalid handles are set to 0. * * \xmlonly * @@ -52,10 +52,52 @@ extern "C" { K4A_DECLARE_HANDLE(k4a_device_t); /** \class k4a_capture_t k4a.h - * Handle to a k4a capture. + * Handle to an Azure Kinect capture. * - * Handles are created with k4a_device_get_capture() or k4a_capture_create() and closed with k4a_capture_release(). - * Invalid handles are set to 0. + * \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 it are 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 * @@ -66,11 +108,47 @@ K4A_DECLARE_HANDLE(k4a_device_t); K4A_DECLARE_HANDLE(k4a_capture_t); /** \class k4a_image_t k4a.h - * Handle to a k4a image. + * Handle to an Azure Kinect image. * - * Handles are created with k4a_capture_get_color_image(), k4a_capture_get_depth_image(), k4a_capture_get_ir_image(), - * k4a_image_create(), or k4a_image_create_from_buffer() and closed with k4a_image_release(). Invalid handles are set to - * 0. + * \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 * @@ -81,10 +159,18 @@ K4A_DECLARE_HANDLE(k4a_capture_t); K4A_DECLARE_HANDLE(k4a_image_t); /** \class k4a_transformation_t k4a.h - * Handle to a k4a transformation context. + * Handle to an Azure Kinect transformation context. * - * Handles are created with k4a_transformation_create() and closed with - * k4a_transformation_destroy(). Invalid handles are set to 0. + * \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 * @@ -115,7 +201,9 @@ K4A_DECLARE_HANDLE(k4a_transformation_t); * DEFAULT - log all message of level 'error' or higher criticality */ -/** Indicates the caller of \ref k4a_device_open wants to open the default sensor +/** Default device index. + * + * Passed as an argument to \ref k4a_device_open() to open the default sensor * * \xmlonly * @@ -123,9 +211,9 @@ K4A_DECLARE_HANDLE(k4a_transformation_t); * * \endxmlonly */ -#define K4A_DEVICE_DEFAULT (0) // Open the default K4A device +#define K4A_DEVICE_DEFAULT (0) -/** An infinite wait time for functions that take a timeout parameter +/** An infinite wait time for functions that take a timeout parameter. * * \xmlonly * @@ -135,32 +223,29 @@ K4A_DECLARE_HANDLE(k4a_transformation_t); */ #define K4A_WAIT_INFINITE (-1) -/** A timestamp value that should never be returned by the hardware. +/** 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 - */ -#define K4A_INVALID_TIMESTAMP ((uint64_t)0) - -/** callback function for a memory object being destroyed * - * \param buffer - * The buffer pointer that was supplied by the caller in k4a_memory_description_t. - * - * \param context - * The context for the memory object that needs to be destroyed. This was given to k4a in - * k4a_memory_description_t.buffer_release_cb_context. - * - * \remarks - * We all references for the memory object are released, this callback will be invoked as the final destroy for the - * given memory. */ typedef void(k4a_memory_destroy_cb_t)(void *buffer, void *context); -/** Return codes returned by k4a APIs +/** Result code returned by Azure Kinect APIs. * * \xmlonly * @@ -174,7 +259,7 @@ typedef enum K4A_RESULT_FAILED, /**< The result was a failure */ } k4a_result_t; -/** Return codes returned by k4a APIs +/** Result code returned by Azure Kinect APIs. * * \xmlonly * @@ -189,7 +274,7 @@ typedef enum K4A_BUFFER_RESULT_TOO_SMALL, /**< The input buffer was too small */ } k4a_buffer_result_t; -/** Return codes returned by k4a APIs +/** Result code returned by Azure Kinect APIs. * * \xmlonly * @@ -204,7 +289,7 @@ typedef enum K4A_WAIT_RESULT_TIMEOUT, /**< The operation timed out */ } k4a_wait_result_t; -/** Validate that a k4a_result_t is successful +/** Validate that a k4a_result_t is successful. * * \xmlonly * @@ -214,7 +299,7 @@ typedef enum */ #define K4A_SUCCEEDED(_result_) (_result_ == K4A_RESULT_SUCCEEDED) -/** Validate that a k4a_result_t is failed +/** Validate that a k4a_result_t is failed. * * \xmlonly * @@ -224,7 +309,17 @@ typedef enum */ #define K4A_FAILED(_result_) (!K4A_SUCCEEDED(_result_)) -/** Depth Sensor capture modes +/** 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 * @@ -234,15 +329,15 @@ typedef enum */ typedef enum { - K4A_DEPTH_MODE_OFF = 0, /**< Depth sensor will be turned off with this setting */ - K4A_DEPTH_MODE_NFOV_2X2BINNED, /**< RES: 320x288 */ - K4A_DEPTH_MODE_NFOV_UNBINNED, /**< RES: 640x576 */ - K4A_DEPTH_MODE_WFOV_2X2BINNED, /**< RES: 512x512 */ - K4A_DEPTH_MODE_WFOV_UNBINNED, /**< RES: 1024x1024 */ - K4A_DEPTH_MODE_PASSIVE_IR, /**< RES: 1024x1024 */ + 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 (RGB) sensor resolutions +/** Color sensor resolutions. * * \xmlonly * @@ -261,7 +356,10 @@ typedef enum K4A_COLOR_RESOLUTION_3072P, /**< 4096 * 3072 4:3 */ } k4a_color_resolution_t; -/** Image types +/** Image format type. + * + * \remarks + * The image format indicates how the \ref k4a_image_t buffer data is interpreted. * * \xmlonly * @@ -271,16 +369,98 @@ typedef enum */ typedef enum { - K4A_IMAGE_FORMAT_COLOR_MJPG = 0, /**< Color image type MJPG*/ - K4A_IMAGE_FORMAT_COLOR_NV12, /**< Color image type NV12*/ - K4A_IMAGE_FORMAT_COLOR_YUY2, /**< Color image type YUY2*/ - K4A_IMAGE_FORMAT_COLOR_BGRA32, /**< Color image type BGRA (8 bits per channel) */ - K4A_IMAGE_FORMAT_DEPTH16, /**< Depth image type Depth16*/ - K4A_IMAGE_FORMAT_IR16, /**< Depth image type IR16*/ - K4A_IMAGE_FORMAT_CUSTOM, /**< Used inconjuction with user created images */ + /** 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 color data such that all the luminance is at the + * beginning of the buffer, and the color information follows it. + * + * \details + * Stride is not relevant to this format. + */ + K4A_IMAGE_FORMAT_COLOR_NV12, + + /** Color image type YUY2. + * + * \details + * YUY2 stores chroma and luminance data in interleaved pixels. + * + * \details + * Stride should be used to determine the start location of each line of the image. + */ + 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 should be used to determine the start location of each line of the image. + * + * \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 should be used to determine the start location of each line of the image. + */ + 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 should be used to determine the start location of each line of the image. + */ + K4A_IMAGE_FORMAT_IR16, + + /** 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; -/** Color and Depth sensor frame rate +/** 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 * @@ -295,7 +475,17 @@ typedef enum K4A_FRAMES_PER_SECOND_30, /**< 30 FPS */ } k4a_fps_t; -/** Color (RGB) sensor control commands +/** 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 * @@ -305,21 +495,105 @@ typedef enum */ typedef enum { - K4A_COLOR_CONTROL_EXPOSURE_TIME_ABSOLUTE = 0, /**< Auto, Manual (in uSec unit) */ - K4A_COLOR_CONTROL_AUTO_EXPOSURE_PRIORITY, /**< Manual (0: framerate priority, 1: exposure priority) */ - K4A_COLOR_CONTROL_BRIGHTNESS, /**< Manual */ - K4A_COLOR_CONTROL_CONTRAST, /**< Manual */ - K4A_COLOR_CONTROL_SATURATION, /**< Manual */ - K4A_COLOR_CONTROL_SHARPNESS, /**< Manual */ - K4A_COLOR_CONTROL_WHITEBALANCE, /**< Auto, Manual (in degrees Kelvin) */ - K4A_COLOR_CONTROL_BACKLIGHT_COMPENSATION, /**< Manual (0: disable, 1: enable) */ - K4A_COLOR_CONTROL_GAIN, /**< Manual */ - K4A_COLOR_CONTROL_POWERLINE_FREQUENCY /**< Manual (1: 50Hz, 2:60Hz) */ + /** Exposure time setting. + * + * \details + * May be set to ::K4A_COLOR_CONTROL_MODE_AUTO or ::K4A_COLOR_CONTROL_MODE_MANUAL. + * + * \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. + */ + 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 (RGB) sensor control mode +/** Color sensor control mode * - * Used in conjunction with k4a_color_control_command_t + * \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 * @@ -333,8 +607,9 @@ typedef enum K4A_COLOR_CONTROL_MODE_MANUAL, /**< set the associated k4a_color_control_command_t to manual*/ } k4a_color_control_mode_t; -/** Calibration types - * Specifies the calibration type. +/** Calibration types. + * + * Specifies a type of calibration. * * \xmlonly * @@ -347,14 +622,17 @@ 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, /**< Gyro sensor */ - K4A_CALIBRATION_TYPE_ACCEL, /**< Accel 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 +/** Calibration model type. * - * The type of calibration performed on the sensor + * The model used interpret the calibration parameters. + * + * \remarks + * Azure Kinect devices are calibrated with Brown Conrady. * * \xmlonly * @@ -372,7 +650,7 @@ typedef enum */ } k4a_calibration_model_type_t; -/** Firmware built type +/** Firmware build type. * * \xmlonly * @@ -382,11 +660,11 @@ typedef enum */ typedef enum { - K4A_FIRMWARE_BUILD_RELEASE, /**< Production firmware */ - K4A_FIRMWARE_BUILD_DEBUG /**< Pre-production firmware */ + K4A_FIRMWARE_BUILD_RELEASE, /**< Production firmware. */ + K4A_FIRMWARE_BUILD_DEBUG /**< Pre-production firmware. */ } k4a_firmware_build_t; -/** Firmware signature +/** Firmware signature type. * * \xmlonly * @@ -396,12 +674,12 @@ typedef enum */ 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_MSFT, /**< Microsoft signed firmware. */ + K4A_FIRMWARE_SIGNATURE_TEST, /**< Test signed firmware. */ + K4A_FIRMWARE_SIGNATURE_UNSIGNED /**< Unsigned firmware. */ } k4a_firmware_signature_t; -/** Synchronization mode when connecting 2 or more devices together. +/** Synchronization mode when connecting two or more devices together. * * \xmlonly * @@ -411,15 +689,15 @@ typedef enum */ typedef enum { - K4A_WIRED_SYNC_MODE_STANDALONE, /**< Neither Sync In or Sync Out connections are used. */ + 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.*/ 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 just a mirror of 'Sync In' for this mode. + next device in the chain. 'Sync Out' is a mirror of 'Sync In' for this mode. */ } k4a_wired_sync_mode_t; -/** Version information +/** Version information. * * \xmlonly * @@ -429,13 +707,13 @@ typedef enum */ typedef struct _k4a_version_t { - uint32_t major; /**< Major version; represents a breaking change */ + 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 */ + major version. */ + uint32_t iteration; /**< Reserved. */ } k4a_version_t; -/** Structure to define hardware version +/** Structure to define hardware version. * * \xmlonly * @@ -445,16 +723,19 @@ typedef struct _k4a_version_t */ typedef struct _k4a_hardware_version_t { - k4a_version_t rgb; /**< RGB version*/ - k4a_version_t depth; /**< Depth version*/ - k4a_version_t audio; /**< Audio version*/ - k4a_version_t depth_sensor; /**< Depth Sensor*/ + 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; /**< Firmware reported hardware build */ - k4a_firmware_signature_t firmware_signature; /**< Firmware reported signature */ + 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; -/** Structure to define configuration for k4a sensor +/** Configuration parameters for an Azure Kinect device. + * + * \remarks + * Used by k4a_device_start_cameras() to specify the configuration of the data capture. * * \xmlonly * @@ -464,45 +745,79 @@ typedef struct _k4a_hardware_version_t */ typedef struct _k4a_device_configuration_t { - /** Image format to capture with the color camera. The color camera does not natively produce BGRA32 images. - * Setting BGRA32 for color_format will result in higher CPU utilization. */ + /** 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 */ + /** Image resolution to capture with the color camera. */ k4a_color_resolution_t color_resolution; - /** Capture mode for the depth camera */ + /** Capture mode for the depth camera. */ k4a_depth_mode_t depth_mode; - /** Frame rate for the color and depth camera */ + /** Desired frame rate for the color and depth camera. */ k4a_fps_t camera_fps; - /** Only report k4a_capture_t objects if they contain synchronized color and depth images. If set to false a - * capture may be reported that contains only a single image. NOTE: this can only be enabled if both color camera - * and depth camera's are configured to run*/ + /** 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; /** - * Delay after the capture of the color image and the capture of the depth image. Can be any - * value 1 period faster than the color capture (a negative value) upto 1 period after the color capture. + * 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*/ + /** The external synchronization mode. */ k4a_wired_sync_mode_t wired_sync_mode; /** - * If this camera is a subordinate, this sets the capture delay between the color camera capture and the input - * pulse. If this is not a subordinate, then this value is ignored. */ + * 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.*/ + * 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; -/** Initial configuration setting for disabling all sensors +/** Initial configuration setting for disabling all sensors. + * + * \remarks + * Use this setting to initialize a \ref k4a_device_configuration_t to a disabled state. * * \xmlonly * @@ -520,7 +835,7 @@ static const k4a_device_configuration_t K4A_DEVICE_CONFIG_INIT_DISABLE_ALL = { K 0, false }; -/** k4a_float2_t +/** Two dimensional floating point vector. * * \xmlonly * @@ -533,13 +848,13 @@ typedef union /** XY or array representation of vector */ struct _xy { - float x; /**< X representation of a vector */ - float y; /**< Y representation of a vector */ + 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; -/** k4a_float3_t +/** Three dimensional floating point vector. * * \xmlonly * @@ -549,17 +864,17 @@ typedef union */ typedef union { - /** XYZ or array representation of vector */ + /** XYZ or array representation of vector. */ struct _xyz { - float x; /**< X representation of a vector */ - float y; /**< Y representation of a vector */ - float z; /**< Z representation of a vector */ - } xyz; /**< X, Y, Z representation of a vector */ - float v[3]; /**< Array representation of a vector */ + 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 frame structure +/** IMU sample. * * \xmlonly * @@ -569,14 +884,17 @@ typedef union */ 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 in uSec */ - k4a_float3_t gyro_sample; /**< Gyro sample in radians per second */ - uint64_t gyro_timestamp_usec; /**< Timestamp in uSec */ + 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; -/** Camera sensor extrinsic calibration data +/** Extrinsic calibration data. + * + * \remarks + * Extrinsic calibration defines the physical relationship between two separate devices. * * \relates k4a_calibration_camera_t * @@ -592,10 +910,14 @@ typedef struct _k4a_calibration_extrinsics_t float translation[3]; /**< Translation vector*/ } k4a_calibration_extrinsics_t; -/** k4a_calibration_intrinsic_parameters_t +/** Camera intrinsic calibration data. * * \remarks - * Compatible with OpenCV. See OpenCV for documentation of individual parameters. + * 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 * @@ -629,7 +951,14 @@ typedef union float v[15]; /**< Array representation of intrinsic model parameters */ } k4a_calibration_intrinsic_parameters_t; -/** Camera sensor intrinsic calibration data +/** 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 * @@ -646,7 +975,7 @@ typedef struct _k4a_calibration_intrinsics_t k4a_calibration_intrinsic_parameters_t parameters; /**< Calibration parameters*/ } k4a_calibration_intrinsics_t; -/** Camera calibration contains intrinsic and extrinsic calibration information +/** Camera calibration contains intrinsic and extrinsic calibration information for a camera. * * \relates k4a_calibration_camera_t * @@ -658,18 +987,15 @@ typedef struct _k4a_calibration_intrinsics_t */ 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_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. It contains (1) the depth and color cameras' intrinsic - * calibrations, (2) extrinsic transformation parameters (3) depth and color modes. The extrinsic parameters allow 3d - * coordinate conversions between depth camera, color camera, the imu's gyro and the imu's accelerometer. For - * transforming from a source to a target 3d coordinate system, use the parameters stored under - * extrinsics[source][target]. * +/** Calibration type representing device calibration. + * * \xmlonly * * k4atypes.h (include k4a/k4a.h) @@ -678,12 +1004,20 @@ typedef struct _k4a_calibration_camera_t */ 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 */ - k4a_calibration_extrinsics_t extrinsics[K4A_CALIBRATION_TYPE_NUM][K4A_CALIBRATION_TYPE_NUM]; /**< Extrinsic - transformation */ - 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_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; #ifdef __cplusplus diff --git a/include/k4ainternal/k4aplugin.h b/include/k4ainternal/k4aplugin.h index 107827ce..ba0f07b3 100644 --- a/include/k4ainternal/k4aplugin.h +++ b/include/k4ainternal/k4aplugin.h @@ -3,7 +3,7 @@ * Licensed under the MIT License. * Kinect For Azure Depth Engine Plugin API. * Defines the API which must be defined by the depth engine plugin to be used - * by the K4A SDK. + * by the Azure Kinect SDK. */ #ifndef K4A_PLUGIN_H @@ -28,13 +28,13 @@ extern "C" { * \remarks The MAJOR version must be updated to denote any breaking change * that would cause an older SDK to not be able to use this plugin. */ -#define K4A_PLUGIN_MAJOR_VERSION 1 /**< K4A plugin major version */ -#define K4A_PLUGIN_MINOR_VERSION 0 /**< K4A plugin minor version */ +#define K4A_PLUGIN_MAJOR_VERSION 1 /**< Azure Kinect plugin major version */ +#define K4A_PLUGIN_MINOR_VERSION 0 /**< Azure Kinect plugin minor version */ /** * Expected name of plugin's dynamic library * - * \remarks When the K4A SDK tried to load the depth engine, it will attempt to + * \remarks When the Azure Kinect SDK tried to load the depth engine, it will attempt to * load a dynamic library with name contains "depthengine". The name contains a * version number to bind with the matching depth engine plugin interface. */ @@ -372,9 +372,9 @@ typedef void(__stdcall *k4a_te_destroy_fn_t)(k4a_transform_engine_context_t **co /** Plugin API which must be populated on plugin registration. * * \remarks - * The K4A SDK will call k4a_register_plugin, and pass in a pointer to a \ref + * The Azure Kinect SDK will call k4a_register_plugin, and pass in a pointer to a \ref * k4a_plugin_t. The plugin must properly fill out all fields of the plugin for - * the K4A SDK to accept the plugin. + * the Azure Kinect SDK to accept the plugin. * */ typedef struct _k4a_plugin_t diff --git a/include/k4ainternal/logging.h b/include/k4ainternal/logging.h index d433e568..b7c04ddb 100644 --- a/include/k4ainternal/logging.h +++ b/include/k4ainternal/logging.h @@ -60,7 +60,7 @@ K4A_DECLARE_HANDLE(logger_t); /** Logger configuration - allows logger to be used in seperate DLL's and provide different ENV vars for processes that need to load both instances. - For example K4A SDK and potentially K4A playback. + For example Azure Kinect SDK and potentially Azure Kinect playback. */ typedef struct { @@ -71,7 +71,7 @@ typedef struct size_t max_log_size; // max log size before rolling over to a new file. } logger_config_t; -/** Initialize logger_config_t to the default settings for K4A SDK +/** Initialize logger_config_t to the default settings for Azure Kinect SDK */ static inline void logger_config_init_default(logger_config_t *config) { diff --git a/include/k4arecord/playback.h b/include/k4arecord/playback.h index 3e433f86..6a31b7a5 100644 --- a/include/k4arecord/playback.h +++ b/include/k4arecord/playback.h @@ -20,7 +20,7 @@ extern "C" { * \param path * Filesystem path of the existing recording. * - * \param playback_handle [OUT] + * \param playback_handle * If successful, this contains a pointer to the recording handle. Caller must call k4a_playback_close() when * finished with the recording. * @@ -40,7 +40,7 @@ extern "C" { */ K4ARECORD_EXPORT k4a_result_t k4a_playback_open(const char *path, k4a_playback_t *playback_handle); -/** Get the raw calibration blob for the K4A device used during recording. +/** Get the raw calibration blob for the Azure Kinect device used during recording. * * \param playback_handle * Handle obtained by k4a_playback_open(). @@ -75,14 +75,14 @@ K4ARECORD_EXPORT k4a_buffer_result_t k4a_playback_get_raw_calibration(k4a_playba uint8_t *data, size_t *data_size); -/** Get the camera calibration for K4A device used during recording. The output struct is used as input to all +/** 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 [OUT] - * Location to write the calibration + * \param calibration + * Location to write the calibration. * * \returns * ::K4A_RESULT_SUCCEEDED if \p calibration was successfully written. ::K4A_RESULT_FAILED otherwise. @@ -108,7 +108,7 @@ K4ARECORD_EXPORT k4a_result_t k4a_playback_get_calibration(k4a_playback_t playba * \param playback_handle * Handle obtained by k4a_playback_open(). * - * \param config [OUT] + * \param config * Location to write the recording configuration. * * \returns @@ -133,7 +133,7 @@ K4ARECORD_EXPORT k4a_result_t k4a_playback_get_record_configuration(k4a_playback * Handle obtained by k4a_playback_open(). * * \param name - * The name of the tag to read + * 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 @@ -149,6 +149,10 @@ K4ARECORD_EXPORT k4a_result_t k4a_playback_get_record_configuration(k4a_playback * 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 @@ -180,18 +184,21 @@ K4ARECORD_EXPORT k4a_buffer_result_t k4a_playback_get_tag(k4a_playback_t playbac * \relates k4a_playback_t * * \remarks - * k4a_playback_get_next_capture() always returns the capture after the last returned capture. If the last call to - * k4a_playback_get_previous_capture() returned EOF, k4a_playback_get_next_capture() will return the first capture in - * the recording. + * 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 first capture - * with all timestamps >= the seek time. + * 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 all image timestamps greater than or equal to the seek time. * * \remarks - * Capture objects will always contain at least 1 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. + * 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 * @@ -211,7 +218,7 @@ K4ARECORD_EXPORT k4a_stream_result_t k4a_playback_get_next_capture(k4a_playback_ * * \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 + * this capture. * * \returns * ::K4A_STREAM_RESULT_SUCCEEDED if a capture is returned, or ::K4A_STREAM_RESULT_EOF if the start of the recording is @@ -220,17 +227,21 @@ K4ARECORD_EXPORT k4a_stream_result_t k4a_playback_get_next_capture(k4a_playback_ * \relates k4a_playback_t * * \remarks - * k4a_playback_get_previous_capture() always returns the capture before the last returned capture. If the last call to - * k4a_playback_get_next_capture() returned EOF, k4a_playback_get_previous_capture() will return the last capture in the - * recording. + * k4a_playback_get_previous_capture() always returns the previous capture in the sequence before the most + * recently returned capture. * * \remarks - * The first call to k4a_playback_get_previous_capture() after k4a_playback_seek_timestamp() will return the first - * capture with all timestamps < the seek time. + * 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 - * Capture objects will always contain at least 1 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 + * 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 @@ -244,13 +255,13 @@ K4ARECORD_EXPORT k4a_stream_result_t k4a_playback_get_next_capture(k4a_playback_ 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. +/** Read the next 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. + * \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 @@ -259,13 +270,16 @@ K4ARECORD_EXPORT k4a_stream_result_t k4a_playback_get_previous_capture(k4a_playb * \relates k4a_playback_t * * \remarks - * k4a_playback_get_next_imu_sample() always returns the imu sample after the last returned sample. If the last call to - * k4a_playback_get_previous_imu_sample() returned EOF, k4a_playback_get_next_imu_sample() will return the first imu - * sample in the recording. + * k4a_playback_get_next_imu_sample() always returns the IMU sample after the most recently returned sample. * * \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 >= the seek time. + * 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 * @@ -278,13 +292,13 @@ K4ARECORD_EXPORT k4a_stream_result_t k4a_playback_get_previous_capture(k4a_playb 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. +/** 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. + * 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 @@ -293,13 +307,16 @@ K4ARECORD_EXPORT k4a_stream_result_t k4a_playback_get_next_imu_sample(k4a_playba * \relates k4a_playback_t * * \remarks - * k4a_playback_get_previous_imu_sample() always returns the imu sample before the last returned sample. If the last - * call to k4a_playback_get_next_imu_sample() returned EOF, k4a_playback_get_previous_imu_sample() will return the last - * imu sample in the recording. + * k4a_playback_get_previous_imu_sample() always returns the IMU sample before the most recently returned sample. * * \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 < the seek time. + * 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 * @@ -331,19 +348,19 @@ K4ARECORD_EXPORT k4a_stream_result_t k4a_playback_get_previous_imu_sample(k4a_pl * * \remarks * The first call to k4a_playback_get_next_capture() after k4a_playback_seek_timestamp() will return the first capture - * with all timestamps >= the seek time. + * with all image timestamps 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 timestamps < the seek time. + * 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 >= the seek time. + * 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 < the seek time. + * imu sample with a timestamp less than the seek time. * * \xmlonly * @@ -363,7 +380,7 @@ K4ARECORD_EXPORT k4a_result_t k4a_playback_seek_timestamp(k4a_playback_t playbac * Handle obtained by k4a_playback_open(). * * \returns - * The timestamp of the last capture image or imu sample in microseconds. + * The timestamp of the last capture image or IMU sample in microseconds. * * \relates k4a_playback_t * diff --git a/include/k4arecord/record.h b/include/k4arecord/record.h index 58b0550c..12e0369b 100644 --- a/include/k4arecord/record.h +++ b/include/k4arecord/record.h @@ -15,23 +15,32 @@ extern "C" { #endif -/** Opens a new recording file for writing. The file will be created if it doesn't exist, or overwritten if an existing - * file is specified. +/** Opens a new recording file for writing. + * + * The file will be created if it doesn't exist, or overwritten if an existing file is specified. * * \param path * Filesystem path for the new recording. * * \param device - * The k4a 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. + * 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 k4a device was opened with. + * The configuration the Azure Kinect device was started with. * - * \param recording_handle [OUT] + * \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 + * 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 @@ -66,7 +75,7 @@ K4ARECORD_EXPORT k4a_result_t k4a_record_create(const char *path, * * \relates k4a_record_t * - * \returns ::K4A_RESULT_SUCCEEDED is returned on success + * \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 @@ -82,7 +91,9 @@ K4ARECORD_EXPORT k4a_result_t k4a_record_create(const char *path, */ 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. The track needs to be added before the recording header is written. +/** Adds the track header for recording IMU. + * + * The track needs to be added before the recording header is written. * * \param recording_handle * The handle of a new recording, obtained by k4a_record_create(). @@ -103,7 +114,9 @@ K4ARECORD_EXPORT k4a_result_t k4a_record_add_tag(k4a_record_t recording_handle, */ K4ARECORD_EXPORT k4a_result_t k4a_record_add_imu_track(k4a_record_t recording_handle); -/** Writes the recording header and metadata to file. This must be called before captures can be written. +/** Writes the recording header and metadata to file. + * + * This must be called before captures can be written. * * \param recording_handle * The handle of a new recording, obtained by k4a_record_create(). @@ -125,6 +138,7 @@ K4ARECORD_EXPORT k4a_result_t k4a_record_add_imu_track(k4a_record_t recording_ha K4ARECORD_EXPORT k4a_result_t k4a_record_write_header(k4a_record_t recording_handle); /** Writes a camera capture to file. + * * Captures must be written in increasing order of timestamp, and the file's header must already be written. * * \param recording_handle @@ -154,6 +168,7 @@ K4ARECORD_EXPORT k4a_result_t k4a_record_write_header(k4a_record_t recording_han 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. + * * Samples must be written in increasing order of timestamp, and the file's header must already be written. * When writing imu samples at the same time as captures, the samples should be within 1 second of the most recently * written capture. diff --git a/include/k4arecord/types.h b/include/k4arecord/types.h index b2ab1137..cc6512db 100644 --- a/include/k4arecord/types.h +++ b/include/k4arecord/types.h @@ -16,6 +16,7 @@ extern "C" { /** \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. * @@ -30,6 +31,7 @@ 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. * @@ -41,7 +43,7 @@ K4A_DECLARE_HANDLE(k4a_record_t); */ K4A_DECLARE_HANDLE(k4a_playback_t); -/** Return codes returned by k4a playback API +/** Return codes returned by Azure Kinect playback API. * * \xmlonly * @@ -51,12 +53,12 @@ K4A_DECLARE_HANDLE(k4a_playback_t); */ 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_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 +/** Playback seeking positions. * * \xmlonly * @@ -66,13 +68,14 @@ typedef enum */ 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_BEGIN, /**< Seek relative to the beginning of a recording. */ + K4A_PLAYBACK_SEEK_END /**< Seek relative to the end of a recording. */ } k4a_playback_seek_origin_t; /** Structure containing the device configuration used to record. * - * \relates k4a_device_configuration_t + * \see k4a_device_configuration_t + * \see k4a_playback_get_record_configuration() * * \xmlonly * @@ -82,28 +85,28 @@ typedef enum */ typedef struct _k4a_record_configuration_t { - /** Image format used to record the color camera */ + /** Image format used to record the color camera. */ k4a_image_format_t color_format; - /** Image resolution used to record the color camera */ + /** Image resolution used to record the color camera. */ k4a_color_resolution_t color_resolution; - /** Mode used to record the depth camera */ + /** Mode used to record the depth camera. */ k4a_depth_mode_t depth_mode; - /** Frame rate used to record the color and depth camera */ + /** Frame rate used to record the color and depth camera. */ k4a_fps_t camera_fps; - /** True if the recording contains Color camera frames */ + /** True if the recording contains Color camera frames. */ bool color_track_enabled; - /** True if the recording contains Depth camera frames */ + /** True if the recording contains Depth camera frames. */ bool depth_track_enabled; - /** True if the recording contains IR camera frames */ + /** True if the recording contains IR camera frames. */ bool ir_track_enabled; - /** True if the recording contains IMU sample data */ + /** True if the recording contains IMU sample data. */ bool imu_track_enabled; /** From c01f1e116c2fe33744ee1a20a5213c5853ecc240 Mon Sep 17 00:00:00 2001 From: wes-b Date: Sun, 10 Mar 2019 10:54:20 -0700 Subject: [PATCH 4/9] Min firmware version upgraded to 1.5.926614 (#120) * Min version upgraded to 1.5.926614 * fixing build error (cherry picked from commit ab77f814976b864e679d1040118aca4a26aa1fb4) --- src/depth/depth.c | 4 ++-- tools/updater/CMakeLists.txt | 7 ------- tools/updater/firmware/README.md | 9 --------- 3 files changed, 2 insertions(+), 18 deletions(-) delete mode 100644 tools/updater/firmware/README.md diff --git a/src/depth/depth.c b/src/depth/depth.c index 9bc6093f..27a6302d 100644 --- a/src/depth/depth.c +++ b/src/depth/depth.c @@ -22,8 +22,8 @@ extern "C" { #define DEPTH_CALIBRATION_DATA_SIZE 2000000 -static k4a_version_t g_min_fw_version_rgb = { 1, 5, 88 }; // 1.5.88 -static k4a_version_t g_min_fw_version_depth = { 1, 5, 63 }; // 1.5.63 +static k4a_version_t g_min_fw_version_rgb = { 1, 5, 92 }; // 1.5.92 +static k4a_version_t g_min_fw_version_depth = { 1, 5, 66 }; // 1.5.66 static k4a_version_t g_min_fw_version_audio = { 1, 5, 14 }; // 1.5.14 static k4a_version_t g_min_fw_version_depth_config = { 5006, 27, 0 }; // 5006.27 (interation is not used, set to zero) diff --git a/tools/updater/CMakeLists.txt b/tools/updater/CMakeLists.txt index d2d305fa..53167193 100644 --- a/tools/updater/CMakeLists.txt +++ b/tools/updater/CMakeLists.txt @@ -31,13 +31,6 @@ install( ${CMAKE_INSTALL_BINDIR} ) -install( - FILES - firmware/AzureKinectDK_Fw_1.5.886314.bin - DESTINATION - ${CMAKE_INSTALL_DATADIR}/k4a/firmware -) - if ("${CMAKE_SYSTEM_NAME}" STREQUAL "Windows") install( FILES diff --git a/tools/updater/firmware/README.md b/tools/updater/firmware/README.md deleted file mode 100644 index eb2626a3..00000000 --- a/tools/updater/firmware/README.md +++ /dev/null @@ -1,9 +0,0 @@ -# Firmware images - -## AzureKinectDK_Fw_1.5.886314.bin - -Intended for 1.0.0 release. - -## AzureKinectDK_Fw_1.5.786013.bin - -Intended for 0.8.x releases. From 92a77c03cd788e0ecb5da8a2fd9f8b60c2703851 Mon Sep 17 00:00:00 2001 From: BrentA-Microsoft Date: Mon, 11 Mar 2019 10:26:36 -0700 Subject: [PATCH 5/9] Fix documentation error in format descriptions (#119) * Fix format documentation (cherry picked from commit cac171d02230059818cc87e307a94a3effe124f7) --- include/k4a/k4atypes.h | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/include/k4a/k4atypes.h b/include/k4a/k4atypes.h index 74177ede..29f66aec 100644 --- a/include/k4a/k4atypes.h +++ b/include/k4a/k4atypes.h @@ -385,11 +385,13 @@ typedef enum /** Color image type NV12. * * \details - * NV12 images separate the luminance and color data such that all the luminance is at the - * beginning of the buffer, and the color information follows it. + * 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 is not relevant to this format. + * 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, @@ -399,7 +401,8 @@ typedef enum * YUY2 stores chroma and luminance data in interleaved pixels. * * \details - * Stride should be used to determine the start location of each line of the image. + * 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, @@ -410,7 +413,8 @@ typedef enum * and Red data. The fourth byte is the alpha channel and is unused in the Azure Kinect APIs. * * \details - * Stride should be used to determine the start location of each line of the image. + * 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 @@ -426,7 +430,8 @@ typedef enum * millimeters from the origin of the camera. * * \details - * Stride should be used to determine the start location of each line of the image. + * 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, @@ -440,7 +445,8 @@ typedef enum * This format represents infrared light and is captured by the depth camera. * * \details - * Stride should be used to determine the start location of each line of the image. + * 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, From 3d317db60cef5fdb1d10f7501d787de05af55c9a Mon Sep 17 00:00:00 2001 From: Matt Schulte Date: Wed, 17 Apr 2019 11:13:25 -0700 Subject: [PATCH 6/9] Do not recursively checkout submodules --- azure-pipelines.yml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/azure-pipelines.yml b/azure-pipelines.yml index 1b80a11f..43cf155d 100644 --- a/azure-pipelines.yml +++ b/azure-pipelines.yml @@ -61,7 +61,7 @@ jobs: fetchDepth: 20 lfs: false persistCredentials: true - submodules: 'recursive' + submodules: true # Use Python Version # Retrieves the specified version of Python from the tool cache. Optionally add it to PATH. @@ -199,7 +199,7 @@ jobs: fetchDepth: 20 lfs: false persistCredentials: true - submodules: 'recursive' + submodules: true - task: ShellScript@2 inputs: @@ -280,7 +280,7 @@ jobs: fetchDepth: 20 lfs: false persistCredentials: true - submodules: 'recursive' + submodules: true - task: BatchScript@1 displayName: 'Setup VS2017 Env' @@ -364,7 +364,7 @@ jobs: clean: true lfs: false persistCredentials: true - submodules: 'recursive' + submodules: true - task: DownloadBuildArtifacts@0 displayName: 'Download Build Artifacts' @@ -431,7 +431,7 @@ jobs: clean: true lfs: false persistCredentials: true - submodules: 'recursive' + submodules: true - task: DownloadBuildArtifacts@0 displayName: 'Download Build Artifacts' From 26f2e6d38d8f0ccbc574a4ba6df9cd1f248db980 Mon Sep 17 00:00:00 2001 From: Matt Schulte Date: Wed, 17 Apr 2019 12:52:54 -0700 Subject: [PATCH 7/9] Downloads findconnectedport for Universal Package --- azure-pipelines.yml | 25 +++++++++++++++++++------ 1 file changed, 19 insertions(+), 6 deletions(-) diff --git a/azure-pipelines.yml b/azure-pipelines.yml index 43cf155d..02388587 100644 --- a/azure-pipelines.yml +++ b/azure-pipelines.yml @@ -448,6 +448,19 @@ jobs: vstsPackageVersion: "1.0.1" downloadDirectory: "$(System.ArtifactsDirectory)/depthengineplugin" + - task: UniversalPackages@0 + displayName: 'Download findconnectedport' + inputs: + command: download + vstsFeed: 'analog.ai.depthcamera' + vstsFeedPackage: 'findconnectedport' + vstsPackageVersion: "0.1.1" + downloadDirectory: "$(System.ArtifactsDirectory)/findconnectedport" + + - script: 'chmod +x $(System.ArtifactsDirectory)/findconnectedport/linux/*' + workingDirectory: '$(System.ArtifactsDirectory)' + displayName: 'Add execution property to findconnectedport' + - task: CopyFiles@2 displayName: "Copy DepthEnginePlugin into LD_LIBRARY_PATH" inputs: @@ -478,10 +491,10 @@ jobs: workingDirectory: '$(System.ArtifactsDirectory)' displayName: 'Prevent the USB connector from accidentally being reset' - # The binary is built from https://microsoft.visualstudio.com/Analog/_git/systems.rustyhmdkit - # Wait a little bit so the device can enumerate, 3 seconds has seemed good. - - script: '$(Agent.HomeDirectory)/bin/findconnectedport-linux/findconnectedport && sleep 3' - workingDirectory: '$(Agent.HomeDirectory)/bin/findconnectedport-linux/' + # The binary is built from https://microsoft.visualstudio.com/Analog/_git/systems.rustyhmdkit + # Wait a little bit so the device can enumerate, 3 seconds has seemed good. + - script: '$(System.ArtifactsDirectory)/findconnectedport/linux/findconnectedport && sleep 3' + workingDirectory: '$(System.ArtifactsDirectory)/findconnectedport/linux/' displayName: 'Reset K4A Device' - script: './x86_64-linux-clang-relwithdebinfo/bin/enumerate_devices' @@ -500,6 +513,6 @@ jobs: continueOnError: true # The binary is built from https://microsoft.visualstudio.com/Analog/_git/systems.rustyhmdkit - - script: '$(Agent.HomeDirectory)/bin/findconnectedport-linux/findconnectedport' - workingDirectory: '$(Agent.HomeDirectory)/bin/findconnectedport-linux/' + - script: '$(System.ArtifactsDirectory)/findconnectedport/linux/findconnectedport' + workingDirectory: '$(System.ArtifactsDirectory)/findconnectedport/linux/' displayName: 'Reset K4A Device' From 619f203fe35710c4cc621df4a92569774700a5d2 Mon Sep 17 00:00:00 2001 From: Chris Edmonds <40211843+cdedmonds@users.noreply.github.com> Date: Fri, 19 Apr 2019 16:23:54 -0700 Subject: [PATCH 8/9] Cherry-pick #236 and #231 to 1.0.x (#249) * use isnan() * validating parameters for GPU code path * Linux build * Cherry-pick #236 and #231 * check for not equal instead of check against NaN * set x,y,z values to zero in point cloud function if pixel falls outside of lens radius * Bring up to date with latest develop * Clang format fixes * Re pick-up isnan change * Fix transformation.cpp --- include/k4ainternal/transformation.h | 18 ++ src/transformation/rgbz.c | 219 +++++++++++++++--- src/transformation/transformation.c | 31 ++- tests/Transformation/transformation.cpp | 293 ++++++++++++++---------- 4 files changed, 411 insertions(+), 150 deletions(-) diff --git a/include/k4ainternal/transformation.h b/include/k4ainternal/transformation.h index 9843f3d5..af2a8226 100644 --- a/include/k4ainternal/transformation.h +++ b/include/k4ainternal/transformation.h @@ -85,6 +85,14 @@ k4a_transformation_t transformation_create(const k4a_calibration_t *calibration, void transformation_destroy(k4a_transformation_t transformation_handle); +k4a_buffer_result_t transformation_depth_image_to_color_camera_validate_parameters( + const k4a_calibration_t *calibration, + const k4a_transformation_xy_tables_t *xy_tables_depth_camera, + const uint8_t *depth_image_data, + const k4a_transformation_image_descriptor_t *depth_image_descriptor, + uint8_t *transformed_depth_image_data, + k4a_transformation_image_descriptor_t *transformed_depth_image_descriptor); + k4a_buffer_result_t transformation_depth_image_to_color_camera_internal( const k4a_calibration_t *calibration, const k4a_transformation_xy_tables_t *xy_tables_depth_camera, @@ -100,6 +108,16 @@ transformation_depth_image_to_color_camera(k4a_transformation_t transformation_h uint8_t *transformed_depth_image_data, k4a_transformation_image_descriptor_t *transformed_depth_image_descriptor); +k4a_buffer_result_t transformation_color_image_to_depth_camera_validate_parameters( + const k4a_calibration_t *calibration, + const k4a_transformation_xy_tables_t *xy_tables_depth_camera, + const uint8_t *depth_image_data, + const k4a_transformation_image_descriptor_t *depth_image_descriptor, + const uint8_t *color_image_data, + const k4a_transformation_image_descriptor_t *color_image_descriptor, + uint8_t *transformed_color_image_data, + k4a_transformation_image_descriptor_t *transformed_color_image_descriptor); + k4a_buffer_result_t transformation_color_image_to_depth_camera_internal( const k4a_calibration_t *calibration, const k4a_transformation_xy_tables_t *xy_tables_depth_camera, diff --git a/src/transformation/rgbz.c b/src/transformation/rgbz.c index d37242fa..558fb6f2 100644 --- a/src/transformation/rgbz.c +++ b/src/transformation/rgbz.c @@ -8,6 +8,12 @@ #include #include +#ifdef _M_X64 +#include // SSE2 +#include // SSE3 +#include // SSE4.1 +#endif + typedef struct _k4a_transformation_input_image_t { const k4a_transformation_image_descriptor_t *descriptor; @@ -60,7 +66,7 @@ static bool transformation_compare_image_descriptors(const k4a_transformation_im descriptor1->height_pixels != descriptor2->height_pixels || descriptor1->stride_bytes != descriptor2->stride_bytes) { - LOG_ERROR("Unexpected image descriptor. Expect width_pixels: %d, height_pixels: %d, stride_bytes: %d. " + LOG_ERROR("Unexpected image descriptor. Expected width_pixels: %d, height_pixels: %d, stride_bytes: %d. " "Actual width_pixels: %d, height_pixels: %d, stride_bytes: %d.", descriptor1->width_pixels, descriptor1->height_pixels, @@ -98,7 +104,7 @@ static k4a_result_t transformation_compute_correspondence(const int depth_index, const k4a_transformation_rgbz_context_t *context, k4a_correspondence_t *correspondence) { - if (depth == 0) + if (depth == 0 || isnan(context->xy_tables->x_table[depth_index])) { memset(correspondence, 0, sizeof(k4a_correspondence_t)); return K4A_RESULT_SUCCEEDED; @@ -239,7 +245,32 @@ static bool transformation_check_valid_correspondences(const k4a_correspondence_ } // If two or more vertices are invalid then we can't create a valid triangle - return num_invalid < 2; + bool valid = num_invalid < 2; + + // Ignore interpolation at large depth discontinuity without disrupting slanted surface + // Skip interpolation threshold is estimated based on the following logic: + // - angle between two pixels is: theta = 0.234375 degree (120 degree / 512) in binning resolution mode + // - distance between two pixels at same depth approximately is: A ~= sin(theta) * depth + // - distance between two pixels at highly slanted surface (e.g. alpha = 85 degree) is: B = A / cos(alpha) + // - skip_interpolation_ratio ~= sin(theta) / cos(alpha) + // We use B as the threshold that to skip interpolation if the depth difference in the triangle is larger + // than B. This is a conservative threshold to estimate largest distance on a highly slanted surface at given depth, + // in reality, given distortion, distance, resolution difference, B can be smaller + const float skip_interpolation_ratio = 0.04693441759f; + float d1 = valid_top_left->depth; + float d2 = valid_top_right->depth; + float d3 = valid_bottom_right->depth; + float d4 = valid_bottom_left->depth; + float depth_min = transformation_min2f(transformation_min2f(d1, d2), transformation_min2f(d3, d4)); + float depth_max = transformation_max2f(transformation_max2f(d1, d2), transformation_max2f(d3, d4)); + float depth_delta = depth_max - depth_min; + float skip_interpolation_threshold = skip_interpolation_ratio * depth_min; + if (depth_delta > skip_interpolation_threshold) + { + valid = false; + } + + return valid; } static inline float transformation_area_function(const k4a_float2_t *a, const k4a_float2_t *b, const k4a_float2_t *c) @@ -428,7 +459,7 @@ static k4a_result_t transformation_depth_to_color(k4a_transformation_rgbz_contex return K4A_RESULT_SUCCEEDED; } -k4a_buffer_result_t transformation_depth_image_to_color_camera_internal( +k4a_buffer_result_t transformation_depth_image_to_color_camera_validate_parameters( const k4a_calibration_t *calibration, const k4a_transformation_xy_tables_t *xy_tables_depth_camera, const uint8_t *depth_image_data, @@ -455,10 +486,6 @@ k4a_buffer_result_t transformation_depth_image_to_color_camera_internal( transformation_compare_image_descriptors(transformed_depth_image_descriptor, &expected_transformed_depth_image_descriptor) == false) { - memcpy(transformed_depth_image_descriptor, - &expected_transformed_depth_image_descriptor, - sizeof(k4a_transformation_image_descriptor_t)); - if (transformed_depth_image_data == 0) { LOG_ERROR("Transformed depth image data is null.", 0); @@ -500,6 +527,29 @@ k4a_buffer_result_t transformation_depth_image_to_color_camera_internal( return K4A_BUFFER_RESULT_FAILED; } + return K4A_BUFFER_RESULT_SUCCEEDED; +} + +k4a_buffer_result_t transformation_depth_image_to_color_camera_internal( + const k4a_calibration_t *calibration, + const k4a_transformation_xy_tables_t *xy_tables_depth_camera, + const uint8_t *depth_image_data, + const k4a_transformation_image_descriptor_t *depth_image_descriptor, + uint8_t *transformed_depth_image_data, + k4a_transformation_image_descriptor_t *transformed_depth_image_descriptor) +{ + if (K4A_BUFFER_RESULT_SUCCEEDED != + TRACE_BUFFER_CALL( + transformation_depth_image_to_color_camera_validate_parameters(calibration, + xy_tables_depth_camera, + depth_image_data, + depth_image_descriptor, + transformed_depth_image_data, + transformed_depth_image_descriptor))) + { + return K4A_BUFFER_RESULT_FAILED; + } + k4a_transformation_rgbz_context_t context; memset(&context, 0, sizeof(k4a_transformation_rgbz_context_t)); @@ -610,7 +660,7 @@ static k4a_result_t transformation_color_to_depth(k4a_transformation_rgbz_contex return K4A_RESULT_SUCCEEDED; } -k4a_buffer_result_t transformation_color_image_to_depth_camera_internal( +k4a_buffer_result_t transformation_color_image_to_depth_camera_validate_parameters( const k4a_calibration_t *calibration, const k4a_transformation_xy_tables_t *xy_tables_depth_camera, const uint8_t *depth_image_data, @@ -639,10 +689,6 @@ k4a_buffer_result_t transformation_color_image_to_depth_camera_internal( transformation_compare_image_descriptors(transformed_color_image_descriptor, &expected_transformed_color_image_descriptor) == false) { - memcpy(transformed_color_image_descriptor, - &expected_transformed_color_image_descriptor, - sizeof(k4a_transformation_image_descriptor_t)); - if (transformed_color_image_data == 0) { LOG_ERROR("Transformed color image data is null.", 0); @@ -700,6 +746,33 @@ k4a_buffer_result_t transformation_color_image_to_depth_camera_internal( return K4A_BUFFER_RESULT_FAILED; } + return K4A_BUFFER_RESULT_SUCCEEDED; +} + +k4a_buffer_result_t transformation_color_image_to_depth_camera_internal( + const k4a_calibration_t *calibration, + const k4a_transformation_xy_tables_t *xy_tables_depth_camera, + const uint8_t *depth_image_data, + const k4a_transformation_image_descriptor_t *depth_image_descriptor, + const uint8_t *color_image_data, + const k4a_transformation_image_descriptor_t *color_image_descriptor, + uint8_t *transformed_color_image_data, + k4a_transformation_image_descriptor_t *transformed_color_image_descriptor) +{ + if (K4A_BUFFER_RESULT_SUCCEEDED != + TRACE_BUFFER_CALL( + transformation_color_image_to_depth_camera_validate_parameters(calibration, + xy_tables_depth_camera, + depth_image_data, + depth_image_descriptor, + color_image_data, + color_image_descriptor, + transformed_color_image_data, + transformed_color_image_descriptor))) + { + return K4A_BUFFER_RESULT_FAILED; + } + k4a_transformation_rgbz_context_t context; memset(&context, 0, sizeof(k4a_transformation_rgbz_context_t)); @@ -720,6 +793,104 @@ k4a_buffer_result_t transformation_color_image_to_depth_camera_internal( return K4A_BUFFER_RESULT_SUCCEEDED; } +#ifndef _M_X64 +static void transformation_depth_to_xyz(k4a_transformation_xy_tables_t *xy_tables, + const void *depth_image_data, + void *xyz_image_data) +{ + const uint16_t *depth_image_data_uint16 = (const uint16_t *)depth_image_data; + int16_t *xyz_data_int16 = (int16_t *)xyz_image_data; + int16_t x, y, z; + + for (int i = 0; i < xy_tables->width * xy_tables->height; i++) + { + float x_tab = xy_tables->x_table[i]; + + if (!isnan(x_tab)) + { + z = (int16_t)depth_image_data_uint16[i]; + x = (int16_t)(floorf(x_tab * (float)z + 0.5f)); + y = (int16_t)(floorf(xy_tables->y_table[i] * (float)z + 0.5f)); + } + else + { + x = 0; + y = 0; + z = 0; + } + + xyz_data_int16[3 * i + 0] = x; + xyz_data_int16[3 * i + 1] = y; + xyz_data_int16[3 * i + 2] = z; + } +} +#else +static void transformation_depth_to_xyz_sse(k4a_transformation_xy_tables_t *xy_tables, + const void *depth_image_data, + void *xyz_image_data) +{ + const __m128i *depth_image_data_m128i = (const __m128i *)depth_image_data; + __m128 *x_table_m128 = (__m128 *)xy_tables->x_table; + __m128 *y_table_m128 = (__m128 *)xy_tables->y_table; + __m128i *xyz_data_m128i = (__m128i *)xyz_image_data; + + const int16_t pos0 = 0x0100; + const int16_t pos1 = 0x0302; + const int16_t pos2 = 0x0504; + const int16_t pos3 = 0x0706; + const int16_t pos4 = 0x0908; + const int16_t pos5 = 0x0B0A; + const int16_t pos6 = 0x0D0C; + const int16_t pos7 = 0x0F0E; + + // x0, x3, x6, x1, x4, x7, x2, x5 + __m128i x_shuffle = _mm_setr_epi16(pos0, pos3, pos6, pos1, pos4, pos7, pos2, pos5); + // y5, y0, y3, y6, y1, y4, y7, y2 + __m128i y_shuffle = _mm_setr_epi16(pos5, pos0, pos3, pos6, pos1, pos4, pos7, pos2); + // z2, z5, z0, z3, z6, z1, z4, z7 + __m128i z_shuffle = _mm_setr_epi16(pos2, pos5, pos0, pos3, pos6, pos1, pos4, pos7); + + __m128i valid_shuffle = _mm_setr_epi16(pos0, pos2, pos4, pos6, pos0, pos2, pos4, pos6); + + for (int i = 0; i < xy_tables->width * xy_tables->height / 8; i++) + { + __m128i z = *depth_image_data_m128i++; + + __m128 x_tab_lo = *x_table_m128++; + __m128 x_tab_hi = *x_table_m128++; + __m128 valid_lo = _mm_cmpeq_ps(x_tab_lo, x_tab_lo); + __m128 valid_hi = _mm_cmpeq_ps(x_tab_hi, x_tab_hi); + __m128i valid_shuffle_lo = _mm_shuffle_epi8(*((__m128i *)&valid_lo), valid_shuffle); + __m128i valid_shuffle_hi = _mm_shuffle_epi8(*((__m128i *)&valid_hi), valid_shuffle); + __m128i valid = _mm_blend_epi16(valid_shuffle_lo, valid_shuffle_hi, 0xF0); + z = _mm_blendv_epi8(_mm_setzero_si128(), z, valid); + + __m128 depth_lo = _mm_cvtepi32_ps(_mm_unpacklo_epi16(z, _mm_setzero_si128())); + __m128 depth_hi = _mm_cvtepi32_ps(_mm_unpackhi_epi16(z, _mm_setzero_si128())); + + __m128i x_lo = _mm_cvtps_epi32(_mm_mul_ps(depth_lo, x_tab_lo)); + __m128i x_hi = _mm_cvtps_epi32(_mm_mul_ps(depth_hi, x_tab_hi)); + __m128i x = _mm_packs_epi32(x_lo, x_hi); + x = _mm_blendv_epi8(_mm_setzero_si128(), x, valid); + x = _mm_shuffle_epi8(x, x_shuffle); + + __m128i y_lo = _mm_cvtps_epi32(_mm_mul_ps(depth_lo, *y_table_m128++)); + __m128i y_hi = _mm_cvtps_epi32(_mm_mul_ps(depth_hi, *y_table_m128++)); + __m128i y = _mm_packs_epi32(y_lo, y_hi); + y = _mm_shuffle_epi8(y, y_shuffle); + + z = _mm_shuffle_epi8(z, z_shuffle); + + // x0, y0, z0, x1, y1, z1, x2, y2 + *xyz_data_m128i++ = _mm_blend_epi16(_mm_blend_epi16(x, y, 0x92), z, 0x24); + // z2, x3, y3, z3, x4, y4, z4, x5 + *xyz_data_m128i++ = _mm_blend_epi16(_mm_blend_epi16(x, y, 0x24), z, 0x49); + // y5, z5, x6, y6, z6, x7, y7, z7 + *xyz_data_m128i++ = _mm_blend_epi16(_mm_blend_epi16(x, y, 0x49), z, 0x92); + } +} +#endif + k4a_buffer_result_t transformation_depth_image_to_point_cloud_internal(k4a_transformation_xy_tables_t *xy_tables, const uint8_t *depth_image_data, @@ -740,8 +911,6 @@ transformation_depth_image_to_point_cloud_internal(k4a_transformation_xy_tables_ if (xyz_image_data == 0 || transformation_compare_image_descriptors(xyz_image_descriptor, &expected_xyz_image_descriptor) == false) { - memcpy(xyz_image_descriptor, &expected_xyz_image_descriptor, sizeof(k4a_transformation_image_descriptor_t)); - if (xyz_image_data == 0) { LOG_ERROR("XYZ image data is null.", 0); @@ -773,19 +942,11 @@ transformation_depth_image_to_point_cloud_internal(k4a_transformation_xy_tables_ return K4A_BUFFER_RESULT_FAILED; } - const uint16_t *depth_image_data_uint16 = (const uint16_t *)(const void *)depth_image_data; - int16_t *xyz_data_int16 = (int16_t *)(void *)xyz_image_data; - - for (int i = 0; i < xy_tables->width * xy_tables->height; i++) - { - int16_t z = (int16_t)depth_image_data_uint16[i]; - int16_t x = (int16_t)(floorf(xy_tables->x_table[i] * (float)z + 0.5f)); - int16_t y = (int16_t)(floorf(xy_tables->y_table[i] * (float)z + 0.5f)); - - xyz_data_int16[3 * i + 0] = x; - xyz_data_int16[3 * i + 1] = y; - xyz_data_int16[3 * i + 2] = z; - } +#ifdef _M_X64 + transformation_depth_to_xyz_sse(xy_tables, (const void *)depth_image_data, (void *)xyz_image_data); +#else + transformation_depth_to_xyz(xy_tables, (const void *)depth_image_data, (void *)xyz_image_data); +#endif return K4A_BUFFER_RESULT_SUCCEEDED; -} +} \ No newline at end of file diff --git a/src/transformation/transformation.c b/src/transformation/transformation.c index d00d9962..ee8a14e3 100644 --- a/src/transformation/transformation.c +++ b/src/transformation/transformation.c @@ -7,6 +7,7 @@ // System dependencies #include +#include k4a_result_t transformation_get_mode_specific_calibration(const k4a_calibration_camera_t *depth_camera_calibration, const k4a_calibration_camera_t *color_camera_calibration, @@ -316,7 +317,9 @@ static k4a_buffer_result_t transformation_init_xy_tables(const k4a_calibration_t if (valid == 0) { - xy_tables->x_table[idx] = 0.f; + // x table value of NAN marks invalid + xy_tables->x_table[idx] = NAN; + // set y table value to 0 to speed up SSE implementation xy_tables->y_table[idx] = 0.f; } else @@ -472,6 +475,18 @@ transformation_depth_image_to_color_camera(k4a_transformation_t transformation_h if (transformation_context->enable_gpu_optimization) { + if (K4A_BUFFER_RESULT_SUCCEEDED != + TRACE_BUFFER_CALL(transformation_depth_image_to_color_camera_validate_parameters( + &transformation_context->calibration, + &transformation_context->depth_camera_xy_tables, + depth_image_data, + depth_image_descriptor, + transformed_depth_image_data, + transformed_depth_image_descriptor))) + { + return K4A_RESULT_FAILED; + } + size_t depth_image_size = (size_t)(depth_image_descriptor->stride_bytes * depth_image_descriptor->height_pixels); size_t transformed_depth_image_size = (size_t)(transformed_depth_image_descriptor->stride_bytes * @@ -540,6 +555,20 @@ transformation_color_image_to_depth_camera(k4a_transformation_t transformation_h if (transformation_context->enable_gpu_optimization) { + if (K4A_BUFFER_RESULT_SUCCEEDED != + TRACE_BUFFER_CALL(transformation_color_image_to_depth_camera_validate_parameters( + &transformation_context->calibration, + &transformation_context->depth_camera_xy_tables, + depth_image_data, + depth_image_descriptor, + color_image_data, + color_image_descriptor, + transformed_color_image_data, + transformed_color_image_descriptor))) + { + return K4A_RESULT_FAILED; + } + size_t depth_image_size = (size_t)(depth_image_descriptor->stride_bytes * depth_image_descriptor->height_pixels); size_t color_image_size = (size_t)(color_image_descriptor->stride_bytes * diff --git a/tests/Transformation/transformation.cpp b/tests/Transformation/transformation.cpp index 06bad4c6..f0f4f6c8 100644 --- a/tests/Transformation/transformation.cpp +++ b/tests/Transformation/transformation.cpp @@ -310,19 +310,62 @@ TEST_F(transformation_ut, transformation_2d_to_2d) ASSERT_EQ_FLT2(point2d, m_depth_point2d_reference); } -TEST_F(transformation_ut, transformation_create_depth_only) +TEST_F(transformation_ut, transformation_depth_image_to_point_cloud) { - k4a_depth_mode_t depth_mode = K4A_DEPTH_MODE_NFOV_UNBINNED; - k4a_color_resolution_t color_resolution = K4A_COLOR_RESOLUTION_OFF; - - k4a_calibration_t calibration; - k4a_result_t result = - k4a_calibration_get_from_raw(g_test_json, sizeof(g_test_json), depth_mode, color_resolution, &calibration); - ASSERT_EQ(result, K4A_RESULT_SUCCEEDED); - - k4a_transformation_t transformation_handle = transformation_create(&calibration, true); + k4a_transformation_t transformation_handle = transformation_create(&m_calibration, false); ASSERT_NE(transformation_handle, (k4a_transformation_t)NULL); + int width = m_calibration.depth_camera_calibration.resolution_width; + int height = m_calibration.depth_camera_calibration.resolution_height; + k4a_image_t depth_image = NULL; + ASSERT_EQ(image_create(K4A_IMAGE_FORMAT_DEPTH16, width, height, width * (int)sizeof(uint16_t), &depth_image), + K4A_RESULT_SUCCEEDED); + ASSERT_NE(depth_image, (k4a_image_t)NULL); + k4a_transformation_image_descriptor_t depth_image_descriptor = image_get_descriptor(depth_image); + + uint16_t *depth_image_buffer = (uint16_t *)(void *)image_get_buffer(depth_image); + for (int i = 0; i < width * height; i++) + { + depth_image_buffer[i] = (uint16_t)1000; + } + + k4a_image_t xyz_image = NULL; + ASSERT_EQ(image_create(K4A_IMAGE_FORMAT_CUSTOM, width, height, width * 3 * (int)sizeof(int16_t), &xyz_image), + K4A_RESULT_SUCCEEDED); + ASSERT_NE(xyz_image, (k4a_image_t)NULL); + k4a_transformation_image_descriptor_t xyz_image_descriptor = image_get_descriptor(xyz_image); + + ASSERT_EQ(transformation_depth_image_to_point_cloud(transformation_handle, + image_get_buffer(depth_image), + &depth_image_descriptor, + K4A_CALIBRATION_TYPE_DEPTH, + image_get_buffer(xyz_image), + &xyz_image_descriptor), + K4A_RESULT_SUCCEEDED); + + int16_t *xyz_image_buffer = (int16_t *)(void *)image_get_buffer(xyz_image); + double check_sum = 0; + for (int i = 0; i < 3 * width * height; i++) + { + check_sum += (double)abs(xyz_image_buffer[i]); + } + check_sum /= (double)(3 * width * height); + + // Comparison against reference hash value computed over the entire image. If result image is changed (e.g., due to + // using a different calibration), the reference value needs to be updated. + const double reference_val = 562.20976003011071; + if (std::abs(check_sum - reference_val) > 0.001) + { + ASSERT_EQ(check_sum, reference_val); + } + + image_dec_ref(depth_image); + image_dec_ref(xyz_image); + transformation_destroy(transformation_handle); +} + +TEST_F(transformation_ut, transformation_all_image_functions_with_failure_cases) +{ int depth_image_width_pixels = 640; int depth_image_height_pixels = 576; k4a_image_t depth_image = NULL; @@ -333,8 +376,8 @@ TEST_F(transformation_ut, transformation_create_depth_only) &depth_image), K4A_WAIT_RESULT_SUCCEEDED); - int color_image_width_pixels = 1920; - int color_image_height_pixels = 1080; + int color_image_width_pixels = 1280; + int color_image_height_pixels = 720; k4a_image_t color_image = NULL; ASSERT_EQ(image_create(K4A_IMAGE_FORMAT_DEPTH16, color_image_width_pixels, @@ -359,132 +402,142 @@ TEST_F(transformation_ut, transformation_create_depth_only) &transformed_depth_image), K4A_WAIT_RESULT_SUCCEEDED); - k4a_transformation_image_descriptor_t depth_image_descriptor = image_get_descriptor(depth_image); - k4a_transformation_image_descriptor_t color_image_descriptor = image_get_descriptor(color_image); - k4a_transformation_image_descriptor_t transformed_color_image_descriptor = image_get_descriptor( - transformed_color_image); - uint8_t *depth_image_buffer = image_get_buffer(depth_image); - uint8_t *color_image_buffer = image_get_buffer(color_image); - uint8_t *transformed_color_image_buffer = image_get_buffer(transformed_color_image); - ASSERT_NE(transformation_color_image_to_depth_camera(transformation_handle, - depth_image_buffer, - &depth_image_descriptor, - color_image_buffer, - &color_image_descriptor, - transformed_color_image_buffer, - &transformed_color_image_descriptor), - K4A_RESULT_SUCCEEDED); - - k4a_transformation_image_descriptor_t transformed_depth_image_descriptor = image_get_descriptor( - transformed_depth_image); - uint8_t *transformed_depth_image_buffer = image_get_buffer(transformed_depth_image); - ASSERT_NE(transformation_depth_image_to_color_camera(transformation_handle, - depth_image_buffer, - &depth_image_descriptor, - transformed_depth_image_buffer, - &transformed_depth_image_descriptor), - K4A_RESULT_SUCCEEDED); - - k4a_image_t point_cloud_image = NULL; + k4a_image_t xyz_depth_image = NULL; ASSERT_EQ(image_create(K4A_IMAGE_FORMAT_CUSTOM, depth_image_width_pixels, depth_image_height_pixels, depth_image_width_pixels * 3 * (int)sizeof(int16_t), - &point_cloud_image), - K4A_WAIT_RESULT_SUCCEEDED); - - k4a_transformation_image_descriptor_t point_cloud_image_descriptor = image_get_descriptor(point_cloud_image); - uint8_t *point_cloud_image_buffer = image_get_buffer(point_cloud_image); - ASSERT_EQ(transformation_depth_image_to_point_cloud(transformation_handle, - depth_image_buffer, - &depth_image_descriptor, - K4A_CALIBRATION_TYPE_DEPTH, - point_cloud_image_buffer, - &point_cloud_image_descriptor), + &xyz_depth_image), K4A_RESULT_SUCCEEDED); - transformation_destroy(transformation_handle); -} - -TEST_F(transformation_ut, transformation_create_color_only) -{ - k4a_depth_mode_t depth_mode = K4A_DEPTH_MODE_OFF; - k4a_color_resolution_t color_resolution = K4A_COLOR_RESOLUTION_720P; - - k4a_calibration_t calibration; - k4a_result_t result = - k4a_calibration_get_from_raw(g_test_json, sizeof(g_test_json), depth_mode, color_resolution, &calibration); - ASSERT_EQ(result, K4A_RESULT_SUCCEEDED); - - k4a_transformation_t transformation_handle = transformation_create(&calibration, true); - ASSERT_NE(transformation_handle, (k4a_transformation_t)NULL); - - int depth_image_width_pixels = 640; - int depth_image_height_pixels = 576; - k4a_image_t depth_image = NULL; - ASSERT_EQ(image_create(K4A_IMAGE_FORMAT_DEPTH16, - depth_image_width_pixels, - depth_image_height_pixels, - depth_image_width_pixels * 1 * (int)sizeof(uint16_t), - &depth_image), - K4A_WAIT_RESULT_SUCCEEDED); - - int color_image_width_pixels = 1920; - int color_image_height_pixels = 1080; - k4a_image_t color_image = NULL; - ASSERT_EQ(image_create(K4A_IMAGE_FORMAT_DEPTH16, + k4a_image_t xyz_color_image = NULL; + ASSERT_EQ(image_create(K4A_IMAGE_FORMAT_CUSTOM, color_image_width_pixels, color_image_height_pixels, - color_image_width_pixels * 4 * (int)sizeof(uint8_t), - &color_image), - K4A_WAIT_RESULT_SUCCEEDED); - - k4a_image_t transformed_color_image = NULL; - ASSERT_EQ(image_create(K4A_IMAGE_FORMAT_COLOR_BGRA32, - depth_image_width_pixels, - depth_image_height_pixels, - depth_image_width_pixels * 4 * (int)sizeof(uint8_t), - &transformed_color_image), - K4A_WAIT_RESULT_SUCCEEDED); - - k4a_image_t transformed_depth_image = NULL; - ASSERT_EQ(image_create(K4A_IMAGE_FORMAT_DEPTH16, - color_image_width_pixels, - color_image_height_pixels, - color_image_width_pixels * 1 * (int)sizeof(uint16_t), - &transformed_depth_image), - K4A_WAIT_RESULT_SUCCEEDED); + color_image_width_pixels * 3 * (int)sizeof(int16_t), + &xyz_color_image), + K4A_RESULT_SUCCEEDED); k4a_transformation_image_descriptor_t depth_image_descriptor = image_get_descriptor(depth_image); k4a_transformation_image_descriptor_t color_image_descriptor = image_get_descriptor(color_image); k4a_transformation_image_descriptor_t transformed_color_image_descriptor = image_get_descriptor( transformed_color_image); - uint8_t *depth_image_buffer = image_get_buffer(depth_image); - uint8_t *color_image_buffer = image_get_buffer(color_image); - uint8_t *transformed_color_image_buffer = image_get_buffer(transformed_color_image); - ASSERT_NE(transformation_color_image_to_depth_camera(transformation_handle, - depth_image_buffer, - &depth_image_descriptor, - color_image_buffer, - &color_image_descriptor, - transformed_color_image_buffer, - &transformed_color_image_descriptor), - K4A_RESULT_SUCCEEDED); - k4a_transformation_image_descriptor_t transformed_depth_image_descriptor = image_get_descriptor( transformed_depth_image); + k4a_transformation_image_descriptor_t xyz_depth_image_descriptor = image_get_descriptor(xyz_depth_image); + k4a_transformation_image_descriptor_t xyz_color_image_descriptor = image_get_descriptor(xyz_color_image); + + uint8_t *depth_image_buffer = image_get_buffer(depth_image); + uint8_t *color_image_buffer = image_get_buffer(color_image); uint8_t *transformed_depth_image_buffer = image_get_buffer(transformed_depth_image); - ASSERT_NE(transformation_depth_image_to_color_camera(transformation_handle, - depth_image_buffer, - &depth_image_descriptor, - transformed_depth_image_buffer, - &transformed_depth_image_descriptor), - K4A_RESULT_SUCCEEDED); + uint8_t *transformed_color_image_buffer = image_get_buffer(transformed_color_image); + uint8_t *xyz_depth_image_buffer = image_get_buffer(xyz_depth_image); + uint8_t *xyz_color_image_buffer = image_get_buffer(xyz_color_image); - ASSERT_EQ(calibration.depth_camera_calibration.resolution_width, 0); - ASSERT_EQ(calibration.depth_camera_calibration.resolution_width, 0); + for (int i = 0; i < 5; i++) + { + k4a_depth_mode_t depth_mode = K4A_DEPTH_MODE_OFF; + k4a_color_resolution_t color_resolution = K4A_COLOR_RESOLUTION_OFF; - transformation_destroy(transformation_handle); + switch (i) + { + case 0: + depth_mode = K4A_DEPTH_MODE_NFOV_UNBINNED; + color_resolution = K4A_COLOR_RESOLUTION_OFF; + break; + case 1: + depth_mode = K4A_DEPTH_MODE_OFF; + color_resolution = K4A_COLOR_RESOLUTION_720P; + break; + case 2: + depth_mode = K4A_DEPTH_MODE_NFOV_2X2BINNED; + color_resolution = K4A_COLOR_RESOLUTION_720P; + break; + case 3: + depth_mode = K4A_DEPTH_MODE_NFOV_UNBINNED; + color_resolution = K4A_COLOR_RESOLUTION_2160P; + break; + default: + depth_mode = K4A_DEPTH_MODE_NFOV_UNBINNED; + color_resolution = K4A_COLOR_RESOLUTION_720P; + } + + k4a_calibration_t calibration; + k4a_result_t result = + k4a_calibration_get_from_raw(g_test_json, sizeof(g_test_json), depth_mode, color_resolution, &calibration); + ASSERT_EQ(result, K4A_RESULT_SUCCEEDED); + + k4a_transformation_t transformation_handle = transformation_create(&calibration, false); + ASSERT_NE(transformation_handle, (k4a_transformation_t)NULL); + + k4a_result_t result_color_to_depth = + transformation_color_image_to_depth_camera(transformation_handle, + depth_image_buffer, + &depth_image_descriptor, + color_image_buffer, + &color_image_descriptor, + transformed_color_image_buffer, + &transformed_color_image_descriptor); + + k4a_result_t result_depth_to_color = + transformation_depth_image_to_color_camera(transformation_handle, + depth_image_buffer, + &depth_image_descriptor, + transformed_depth_image_buffer, + &transformed_depth_image_descriptor); + + k4a_result_t result_xyz_depth = transformation_depth_image_to_point_cloud(transformation_handle, + depth_image_buffer, + &depth_image_descriptor, + K4A_CALIBRATION_TYPE_DEPTH, + xyz_depth_image_buffer, + &xyz_depth_image_descriptor); + + k4a_result_t result_xyz_color = transformation_depth_image_to_point_cloud(transformation_handle, + transformed_depth_image_buffer, + &transformed_depth_image_descriptor, + K4A_CALIBRATION_TYPE_COLOR, + xyz_color_image_buffer, + &xyz_color_image_descriptor); + + if (i != 4) + { + ASSERT_NE(result_color_to_depth, K4A_RESULT_SUCCEEDED); + ASSERT_NE(result_depth_to_color, K4A_RESULT_SUCCEEDED); + } + else + { + ASSERT_EQ(result_color_to_depth, K4A_RESULT_SUCCEEDED); + ASSERT_EQ(result_depth_to_color, K4A_RESULT_SUCCEEDED); + } + + if (i != 0 && i != 3 && i != 4) + { + ASSERT_NE(result_xyz_depth, K4A_RESULT_SUCCEEDED); + } + else + { + ASSERT_EQ(result_xyz_depth, K4A_RESULT_SUCCEEDED); + } + + if (i != 1 && i != 2 && i != 4) + { + ASSERT_NE(result_xyz_color, K4A_RESULT_SUCCEEDED); + } + else + { + ASSERT_EQ(result_xyz_color, K4A_RESULT_SUCCEEDED); + } + + transformation_destroy(transformation_handle); + } + + image_dec_ref(depth_image); + image_dec_ref(color_image); + image_dec_ref(transformed_color_image); + image_dec_ref(transformed_depth_image); + image_dec_ref(xyz_color_image); + image_dec_ref(xyz_depth_image); } int main(int argc, char **argv) From 67e7ba101a1fc4fa863ec2e59f77b84aad52c83f Mon Sep 17 00:00:00 2001 From: Matt Schulte Date: Tue, 23 Apr 2019 15:30:42 -0700 Subject: [PATCH 9/9] Build and statically link in LibUSB (#269) * Add libusb as submodule * Builds cmake from source * Fix zero-length-array errors from libusb --- .gitmodules | 3 + cmake/FindLibUSB.cmake | 119 ------------------------ extern/libusb/CMakeLists.txt | 53 +++++++++-- extern/libusb/config.h | 162 +++++++++++++++++++++++++++++++++ extern/libusb/src | 1 + extern/libuvc/CMakeLists.txt | 2 - scripts/bootstrap-ubuntu.sh | 1 + src/usbcommand/CMakeLists.txt | 6 +- tools/k4aviewer/CMakeLists.txt | 1 - 9 files changed, 212 insertions(+), 136 deletions(-) delete mode 100644 cmake/FindLibUSB.cmake create mode 100644 extern/libusb/config.h create mode 160000 extern/libusb/src diff --git a/.gitmodules b/.gitmodules index 54cea46c..5225c352 100644 --- a/.gitmodules +++ b/.gitmodules @@ -32,3 +32,6 @@ [submodule "extern/libjpeg-turbo/src"] path = extern/libjpeg-turbo/src url = https://github.com/libjpeg-turbo/libjpeg-turbo.git +[submodule "extern/libusb/src"] + path = extern/libusb/src + url = https://github.com/libusb/libusb diff --git a/cmake/FindLibUSB.cmake b/cmake/FindLibUSB.cmake deleted file mode 100644 index cceb6274..00000000 --- a/cmake/FindLibUSB.cmake +++ /dev/null @@ -1,119 +0,0 @@ -# Copyright (c) Microsoft Corporation. All rights reserved. -# Licensed under the MIT License. - -# FindLibUSB.cmake -# -# Cross platform module to find the libusb library -# -# This will define the following variables -# -# LibUSB_FOUND -# -# and the following imported targets -# -# LibUSB::LibUSB - -if (${CMAKE_SYSTEM_NAME} STREQUAL "Windows") - - set(LIBUSB_PREBUILT_WIN_LIB_URL https://github.com/libusb/libusb/releases/download/v1.0.22/libusb-1.0.22.7z) - get_filename_component(LIBUSB_7ZIP_FILENAME ${LIBUSB_PREBUILT_WIN_LIB_URL} NAME) - set(LIBUSB_7ZIP ${CMAKE_CURRENT_BINARY_DIR}/${LIBUSB_7ZIP_FILENAME}) - - # For Windows builds, download pre-built libusb libraries - include(FetchContent) - FetchContent_Declare( - libusb_prebuilt_win_lib - URL ${LIBUSB_PREBUILT_WIN_LIB_URL} - URL_HASH MD5=750E64B45ACA94FAFBDFF07171004D03 - ) - - FetchContent_GetProperties(libusb_prebuilt_win_lib) - if (NOT libusb_prebuilt_win_lib_POPULATED) - FetchContent_Populate( - libusb_prebuilt_win_lib - ) - endif() - - # Check for path to include directory - find_path(LIBUSB_INCLUDE_DIR - NAMES - libusb.h - PATHS - ${libusb_prebuilt_win_lib_SOURCE_DIR}/include - PATH_SUFFIXES - libusb-1.0 - ) - - if ("${CMAKE_SIZEOF_VOID_P}" STREQUAL "4") - set(LIBUSB_LIB_PATH "${libusb_prebuilt_win_lib_SOURCE_DIR}/MS32/dll") - elseif ("${CMAKE_SIZEOF_VOID_P}" STREQUAL "8") - set(LIBUSB_LIB_PATH "${libusb_prebuilt_win_lib_SOURCE_DIR}/MS64/dll") - else() - message(FATAL_ERROR "Unsupported size of void ptr: ${CMAKE_SIZEOF_VOID_P}") - endif() - - find_library(LIBUSB_LIB - NAMES - libusb-1.0 - PATHS - ${LIBUSB_LIB_PATH} - ) - - if ("${LIBUSB_LIB}" STREQUAL "LIBUSB_LIB-NOTFOUND") - message(FATAL_ERROR "LibUSB not found") - endif() - -else() - # For linux builds, find installed libusb libraries - find_package(PkgConfig REQUIRED) - pkg_check_modules(PC_LibUSB REQUIRED "libusb-1.0") - - find_path(LIBUSB_INCLUDE_DIR - NAMES - libusb.h - HINTS - ${PC_LibUSB_INCLUDE_DIRS} - PATH_SUFFIXES - libusb-1.0 - ) - - find_library(LIBUSB_LIB - NAMES - ${PC_LibUSB_LIBRARIES} - HINTS - ${PC_LibUSB_LIBDIR} - ${PC_LibUSB_LIBRARY_DIRS} - ) - -endif() - -mark_as_advanced(LIBUSB_INCLUDE_DIR) -mark_as_advanced(LIBUSB_LIB) - -include(FindPackageHandleStandardArgs) -find_package_handle_standard_args(LibUSB DEFAULT_MSG LIBUSB_INCLUDE_DIR LIBUSB_LIB) - -if (LibUSB_FOUND AND NOT TARGET LibUSB::LibUSB) - add_library(LibUSB::LibUSB SHARED IMPORTED) - - # On Windows copy the libUSB dll to the bin directory - if (${CMAKE_SYSTEM_NAME} STREQUAL "Windows") - # Use REGEX instead of NAME_WE since LibUsb-1.0.lib considers the extension "0.lib" - string(REGEX REPLACE "^.*/([^/]*)\\.lib$" "\\1" LibUSB_NAME ${LIBUSB_LIB}) - get_filename_component(LibUSB_DIRECTORY ${LIBUSB_LIB} DIRECTORY) - set(LibUSB_SHARED_PATH ${LibUSB_DIRECTORY}/${LibUSB_NAME}.dll) - else(${CMAKE_SYSTEM_NAME} STREQUAL "Windows") - set(LibUSB_SHARED_PATH ${LIBUSB_LIB}) - endif() - - - set_target_properties(LibUSB::LibUSB PROPERTIES - INTERFACE_INCLUDE_DIRECTORIES "${LIBUSB_INCLUDE_DIR}" - IMPORTED_IMPLIB "${LIBUSB_LIB}" - IMPORTED_LOCATION "${LibUSB_SHARED_PATH}") - - if (${CMAKE_SYSTEM_NAME} STREQUAL "Windows") - include(CopyImportedBinary) - copy_imported_binary(TARGET LibUSB::LibUSB) - endif() -endif() \ No newline at end of file diff --git a/extern/libusb/CMakeLists.txt b/extern/libusb/CMakeLists.txt index f08ff69b..fd568af3 100644 --- a/extern/libusb/CMakeLists.txt +++ b/extern/libusb/CMakeLists.txt @@ -1,12 +1,45 @@ -find_package(LibUSB REQUIRED) +add_library(LibUSB + STATIC + "${CMAKE_CURRENT_SOURCE_DIR}/src/libusb/core.c" + "${CMAKE_CURRENT_SOURCE_DIR}/src/libusb/descriptor.c" + "${CMAKE_CURRENT_SOURCE_DIR}/src/libusb/hotplug.c" + "${CMAKE_CURRENT_SOURCE_DIR}/src/libusb/io.c" + "${CMAKE_CURRENT_SOURCE_DIR}/src/libusb/strerror.c" + "${CMAKE_CURRENT_SOURCE_DIR}/src/libusb/sync.c") + +target_include_directories(LibUSB PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/src/libusb) +target_include_directories(LibUSB PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src/libusb/os) + +add_library(LibUSB::LibUSB ALIAS LibUSB) + +if ("${CMAKE_C_COMPILER_ID}" STREQUAL "Clang") + target_compile_options(LibUSB PUBLIC "-Wno-zero-length-array") +endif() + if ("${CMAKE_SYSTEM_NAME}" STREQUAL "Windows") - # Setup install - include(GNUInstallDirs) - install( - FILES - $ - DESTINATION - ${CMAKE_INSTALL_BINDIR} - ) -endif() \ No newline at end of file + target_sources(LibUSB PRIVATE + "${CMAKE_CURRENT_SOURCE_DIR}/src/libusb/os/poll_windows.c" + "${CMAKE_CURRENT_SOURCE_DIR}/src/libusb/os/threads_windows.c" + "${CMAKE_CURRENT_SOURCE_DIR}/src/libusb/os/windows_nt_common.c" + "${CMAKE_CURRENT_SOURCE_DIR}/src/libusb/os/windows_usbdk.c" + "${CMAKE_CURRENT_SOURCE_DIR}/src/libusb/os/windows_winusb.c") + + target_include_directories(LibUSB PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src/msvc) + + target_compile_definitions(LibUSB PRIVATE "_LIB" "_CRT_SECURE_NO_WARNINGS" "WINVER=0x0501" "_WIN32_WINNT=0x0501") + +elseif("${CMAKE_SYSTEM_NAME}" STREQUAL "Linux") + target_sources(LibUSB PRIVATE + "${CMAKE_CURRENT_SOURCE_DIR}/src/libusb/os/poll_posix.c" + "${CMAKE_CURRENT_SOURCE_DIR}/src/libusb/os/threads_posix.c" + "${CMAKE_CURRENT_SOURCE_DIR}/src/libusb/os/linux_usbfs.c" + "${CMAKE_CURRENT_SOURCE_DIR}/src/libusb/os/linux_udev.c") + + target_include_directories(LibUSB PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/) + + target_link_libraries(LibUSB PUBLIC "udev") + +else() + message(FATAL_ERROR "Unknown CMAKE_SYSTEM_NAME: ${CMAKE_SYSTEM_NAME}") +endif() diff --git a/extern/libusb/config.h b/extern/libusb/config.h new file mode 100644 index 00000000..fcef2d1d --- /dev/null +++ b/extern/libusb/config.h @@ -0,0 +1,162 @@ +/* config.h. THIS WAS GENERATED FROM configure and autoheader and modified to be used in Linux builds */ + +/* config.h. Generated from config.h.in by configure. */ +/* config.h.in. Generated from configure.ac by autoheader. */ + +/* Default visibility */ +#define DEFAULT_VISIBILITY __attribute__((visibility("default"))) + +/* Start with debug message logging enabled */ +/* #undef ENABLE_DEBUG_LOGGING */ + +/* Message logging */ +#define ENABLE_LOGGING 1 + +/* Define to 1 if you have the header file. */ +/* #undef HAVE_ASM_TYPES_H */ + +/* Define to 1 if you have the declaration of `TFD_CLOEXEC', and to 0 if you + don't. */ +#define HAVE_DECL_TFD_CLOEXEC 1 + +/* Define to 1 if you have the declaration of `TFD_NONBLOCK', and to 0 if you + don't. */ +#define HAVE_DECL_TFD_NONBLOCK 1 + +/* Define to 1 if you have the header file. */ +#define HAVE_DLFCN_H 1 + +/* Define to 1 if you have the header file. */ +#define HAVE_INTTYPES_H 1 + +/* Define to 1 if you have the `udev' library (-ludev). */ +#define HAVE_LIBUDEV 1 + +/* Define to 1 if you have the header file. */ +#define HAVE_LIBUDEV_H 1 + +/* Define to 1 if you have the header file. */ +/* #undef HAVE_LINUX_NETLINK_H */ + +/* Define to 1 if you have the header file. */ +#define HAVE_MEMORY_H 1 + +/* Define to 1 if you have the `pipe2' function. */ +#define HAVE_PIPE2 1 + +/* Define to 1 if you have the header file. */ +#define HAVE_POLL_H 1 + +/* Define to 1 if you have the header file. */ +#define HAVE_STDINT_H 1 + +/* Define to 1 if you have the header file. */ +#define HAVE_STDLIB_H 1 + +/* Define to 1 if you have the header file. */ +#define HAVE_STRINGS_H 1 + +/* Define to 1 if you have the header file. */ +#define HAVE_STRING_H 1 + +/* Define to 1 if the system has the type `struct timespec'. */ +#define HAVE_STRUCT_TIMESPEC 1 + +/* syslog() function available */ +/* #undef HAVE_SYSLOG_FUNC */ + +/* Define to 1 if you have the header file. */ +/* #undef HAVE_SYSLOG_H */ + +/* Define to 1 if you have the header file. */ +/* #undef HAVE_SYS_SOCKET_H */ + +/* Define to 1 if you have the header file. */ +#define HAVE_SYS_STAT_H 1 + +/* Define to 1 if you have the header file. */ +#define HAVE_SYS_TIME_H 1 + +/* Define to 1 if you have the header file. */ +#define HAVE_SYS_TYPES_H 1 + +/* Define to 1 if you have the header file. */ +#define HAVE_UNISTD_H 1 + +/* Define to the sub-directory where libtool stores uninstalled libraries. */ +#define LT_OBJDIR ".libs/" + +/* Darwin backend */ +/* #undef OS_DARWIN */ + +/* Haiku backend */ +/* #undef OS_HAIKU */ + +/* Linux backend */ +#define OS_LINUX 1 + +/* NetBSD backend */ +/* #undef OS_NETBSD */ + +/* OpenBSD backend */ +/* #undef OS_OPENBSD */ + +/* SunOS backend */ +/* #undef OS_SUNOS */ + +/* Windows backend */ +/* #undef OS_WINDOWS */ + +/* Name of package */ +#define PACKAGE "libusb" + +/* Define to the address where bug reports for this package should be sent. */ +#define PACKAGE_BUGREPORT "libusb-devel@lists.sourceforge.net" + +/* Define to the full name of this package. */ +#define PACKAGE_NAME "libusb" + +/* Define to the full name and version of this package. */ +#define PACKAGE_STRING "libusb 1.0.22" + +/* Define to the one symbol short name of this package. */ +#define PACKAGE_TARNAME "libusb" + +/* Define to the home page for this package. */ +#define PACKAGE_URL "http://libusb.info" + +/* Define to the version of this package. */ +#define PACKAGE_VERSION "1.0.22" + +/* type of second poll() argument */ +#define POLL_NFDS_TYPE nfds_t + +/* Define to 1 if you have the ANSI C header files. */ +#define STDC_HEADERS 1 + +/* Use POSIX Threads */ +#define THREADS_POSIX 1 + +/* timerfd headers available */ +#define USBI_TIMERFD_AVAILABLE 1 + +/* Enable output to system log */ +/* #undef USE_SYSTEM_LOGGING_FACILITY */ + +/* Use udev for device enumeration/hotplug */ +#define USE_UDEV 1 + +/* Version number of package */ +#define VERSION "1.0.22" + +/* Oldest Windows version supported */ +/* #undef WINVER */ + +/* Oldest Windows version supported */ +/* #undef _WIN32_WINNT */ + +/* Define to `__inline__' or `__inline' if that's what the C compiler + calls it, or to nothing if 'inline' is not supported under any name. */ +#ifndef __cplusplus +/* #undef inline */ +#endif diff --git a/extern/libusb/src b/extern/libusb/src new file mode 160000 index 00000000..0034b2af --- /dev/null +++ b/extern/libusb/src @@ -0,0 +1 @@ +Subproject commit 0034b2afdcdb1614e78edaa2a9e22d5936aeae5d diff --git a/extern/libuvc/CMakeLists.txt b/extern/libuvc/CMakeLists.txt index 52400648..4fe705c9 100644 --- a/extern/libuvc/CMakeLists.txt +++ b/extern/libuvc/CMakeLists.txt @@ -1,7 +1,5 @@ if ("${CMAKE_SYSTEM_NAME}" STREQUAL "Linux") if (NOT TARGET project_libuvc) - find_package(LibUSB REQUIRED) - set(CMAKE_BUILD_TARGET Static) include(ExternalProject) diff --git a/scripts/bootstrap-ubuntu.sh b/scripts/bootstrap-ubuntu.sh index 73dc3ec4..1f279398 100755 --- a/scripts/bootstrap-ubuntu.sh +++ b/scripts/bootstrap-ubuntu.sh @@ -31,5 +31,6 @@ sudo apt install -y \ libxrandr-dev \ libusb-1.0-0-dev \ libssl-dev \ + libudev-dev \ mesa-common-dev \ uuid-dev diff --git a/src/usbcommand/CMakeLists.txt b/src/usbcommand/CMakeLists.txt index fff89299..f75bd55c 100644 --- a/src/usbcommand/CMakeLists.txt +++ b/src/usbcommand/CMakeLists.txt @@ -7,13 +7,11 @@ add_library(k4a_usb_cmd STATIC ) # Consumers should #include -target_include_directories(k4a_usb_cmd PUBLIC +target_include_directories(k4a_usb_cmd PUBLIC ${K4A_PRIV_INCLUDE_DIR}) -find_package(LibUSB REQUIRED) - # Dependencies of this library -target_link_libraries(k4a_usb_cmd PUBLIC +target_link_libraries(k4a_usb_cmd PUBLIC azure::aziotsharedutil LibUSB::LibUSB k4ainternal::allocator diff --git a/tools/k4aviewer/CMakeLists.txt b/tools/k4aviewer/CMakeLists.txt index d40d2160..4791c336 100644 --- a/tools/k4aviewer/CMakeLists.txt +++ b/tools/k4aviewer/CMakeLists.txt @@ -49,7 +49,6 @@ configure_file( ) find_package(OpenGL REQUIRED) -find_package(LibUSB REQUIRED) include_directories( ${OPENGL_INCLUDE_DIRS} ${CMAKE_CURRENT_LIST_DIR}