DAVID4 SDK  1.8.7
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
d4lib.h
1 //=============================================================================
2 // See License in Related Pages
3 //=============================================================================
4 
5 #ifndef DAVID_SDK_D4LIB_H
6 #define DAVID_SDK_D4LIB_H
7 
8 #include <stddef.h>
9 
10 #ifdef __cplusplus
11  #ifndef NULL
12  #define NULL 0
13  #endif
14 #else
15  #ifndef NULL
16  #define NULL (void *)0
17  #endif
18 #endif
19 
20 #ifdef __cplusplus
21 extern "C" {
22 #endif
23 
24 #ifdef _WIN32
25  #ifdef BUILD_D4LIB
26  #ifndef D4LIB_API
27  #define D4LIB_API __declspec( dllexport )
28  #endif
29  #else
30  #ifndef D4LIB_API
31  #define D4LIB_API __declspec( dllimport )
32  #endif
33  #endif
34 #else
35  #ifndef D4LIB_API
36  #define D4LIB_API __attribute__((visibility("default")))
37  #endif
38 #endif
39 
40 //*****************************************************************************
41 /// @addtogroup LowLevelGroup
42 /// @{
43 /// @defgroup d4lib DAVID Low Level Library (d4lib)
44 /// Provides a low level C interface to 'Scanning' and 'Shape Fusion' functions.
45 /// @{
46 //*****************************************************************************
47 
48 //=============================================================================
49 /// @name Library initialization and basic types
50 /// @note The DAVID Low Level Library has to be initialized once. Licensing is usually done by license files / USB key.
51 /// The License key parameter is only required for special/future versions. Normally, please use nullptr.
52 ///
53 /// @code
54 /// int result = d4lib_init(nullptr);
55 /// @endcode
56 ///
57 /// When you are done, call #d4lib_release.
58 /// @{
59 //=============================================================================
60 
61 /// Basic size type.
62 typedef size_t d4size;
63 
64 /// Image pointer.
65 typedef struct d4img* d4img_ptr;
66 
67 /// Float image pointer.
68 typedef struct d4fimg* d4fimg_ptr;
69 
70 /// Camera pointer.
71 typedef struct d4cam* d4cam_ptr;
72 
73 /// Projector pointer.
74 typedef struct d4projector* d4projector_ptr;
75 
76 /// Calibration pointer.
77 typedef struct d4calib* d4calib_ptr;
78 
79 /// Structured light scanning pointer.
80 typedef struct d4sls* d4sls_ptr;
81 
82 /// Mesh pointer.
83 typedef struct d4mesh* d4mesh_ptr;
84 
85 /// Initialize DAVID Low Level Library.
86 /// @param[in] licenseKey License key. Only required for special/future versions - normally please use nullptr
87 /// @return d4ok, d4error_NotLicensed
88 D4LIB_API int d4lib_init(const char* licenseKey);
89 
90 /// Release DAVID Low Level Library.
91 /// @return d4ok
92 D4LIB_API int d4lib_release();
93 
94 /// Get version of library.
95 /// @param[out] version Valid pointer to string that gets the version.
96 /// @param[in] maxLength Maximum string length inlucing null terminator that fits into 'version'.
97 D4LIB_API int d4lib_getVersion(char* version, d4size maxLength);
98 
99 // BEGIN_D4LIB_ERROR_CODES
100 
101 /// All DAVID Low Level Library functions return an error code.
103 {
104  d4ok = 0, ///< All ok.
105  d4error_InvalidArgument = -100, ///< One or more arguments of function call are not valid.
106  d4error_FormatNotAvailable = -101, ///< Format is not available.
107  d4error_InvalidFormat = -102, ///< Invalid format.
108  d4error_NoAccess = -103, ///< General access denied error.
109  d4error_MissingObject = -104, ///< Important object is missing.
110  d4error_OutOfMemory = -105, ///< Failed to allocate necessary memory.
111  d4error_Abort = -106, ///< Operation aborted.
112  d4error_Fail = -107, ///< Unspecified failure.
113  d4error_NotLicensed = -108, ///< Software license does not support this request.
114  d4error_NotImplemented = -109, ///< The requested function is not implemented.
115  d4error_InvalidPath = -200, ///< Invalid path syntax.
116  d4error_FileNotFound = -201, ///< Could not find the specified file.
117  d4error_DirectoryNotFound = -202, ///< Could not find the specified directory.
118  d4error_MissingFilename = -203, ///< The specified path does not contain a file name.
119  d4error_InconsistentBuffer = -204, ///< Buffer size differs from expected buffer size.
120  d4error_InvalidVersion = -205, ///< Invalid or unsupported version.
121  d4error_DeviceNotAvailable = -300, ///< Device is not available / not found.
122  d4error_NoLiveImage = -301, ///< Can not get live image from camera.
123  d4error_ActuatorStalled = -302, ///< Actuator stalled. Required torque might be too high.
124  d4error_CameraCalibration = -400, ///< Camera calibration failed.
125  d4error_ProjectorCalibration = -401, ///< Projector calibration failed.
126  d4error_ScanFailed = -500, ///< Scan failed.
127  d4error_NotCalibrated = -501, ///< Scanner is not calibrated.
128  d4error_AlignFailed = -600, ///< Alignment failed.
129  d4error_InvalidMeshId = -601, ///< One or more mesh IDs are invalid.
130 };
131 
132 // END_D4LIB_ERROR_CODES
133 
134 /// @}
135 
136 
137 //=============================================================================
138 /// @name Memory management
139 /// Objects are created and deleted by the library. In order to create new objects
140 /// use the d4xxx_newXxx functions. Life time of an object is managed by reference counting:
141 /// Use #d4mem_decRefCount to release an object.
142 /// @{
143 //=============================================================================
144 
145 /// Decrement the reference count for the object identified by 'ptr'.
146 /// @param[in,out] ptr Valid pointer to the object.
147 /// @return #d4ok, #d4error_InvalidArgument
148 D4LIB_API int d4mem_decRefCount(void* ptr);
149 
150 /// Increment the reference count for the object identified by 'ptr'.
151 /// The object is deleted when the reference count reaches zero.
152 /// @param[in,out] ptr Valid pointer to the object.
153 /// @return #d4ok, #d4error_InvalidArgument
154 D4LIB_API int d4mem_incRefCount(void* ptr);
155 
156 /// @}
157 
158 
159 //=============================================================================
160 /// @name Images
161 /// Functions and types related to images.
162 /// Notes:
163 /// - Image pointer is #d4img_ptr
164 /// - New images are created via #d4img_newImage
165 /// - Different pixel formats are supported. See #d4img_PixelFormat
166 /// - Access to image format is via #d4img_setImageFormat and #d4img_getImageFormat
167 /// - Access to image data is via #d4img_setImageData and #d4img_getImageData
168 /// @{
169 //=============================================================================
170 
171 /// Supported pixel formats.
173 {
174  d4img_UnknownPixelFormat = 0, ///< Pixel format is unknown.
175  d4img_Y800, ///< 8bit grayscale images.
176  d4img_RGB24, ///< 24bit RGB images. Byte 0=8bit blue; Byte 1=8bit green; Byte 2=8bit red.
177  d4img_YUY2, ///< 16bit color format. Byte 0=8bit Y'0; Byte 1=8bit Cb; Byte 2=8bit Y'1; Byte 3=8bit Cr.
178  d4img_BY8, ///< 8bit bayer color format.
179 };
180 
181 /// Describes the format of an image.
183 {
184  int width; ///< Width of the image.
185  int height; ///< Height of the image.
186  int pixelFormat; ///< Pixel format of the image. See #d4img_PixelFormat.
187 };
188 
189 /// Creates a new image.
190 /// @return Pointer to an image or NULL in case of an error.
191 D4LIB_API d4img_ptr d4img_newImage();
192 
193 /// Get format of the image.
194 /// @param[in] img Valid pointer to an image.
195 /// @param[out] width Pointer to int for width of image. May be NULL.
196 /// @param[out] height Pointer to int for height of image. May be NULL.
197 /// @param[out] pixelFormat Pointer to int for #d4img_PixelFormat. May be NULL.
198 /// @return #d4ok, #d4error_InvalidArgument
199 D4LIB_API int d4img_getImageFormat(d4img_ptr img, int* width, int* height, int* pixelFormat);
200 
201 /// Set format of the image.
202 /// @param[out] img Valid pointer to an image.
203 /// @param[in] width Width of the image or zero.
204 /// @param[in] height Height of the image or zero.
205 /// @param[in] pixelFormat See #d4img_PixelFormat. #d4img_UnknownPixelFormat is allowed.
206 /// @return #d4ok, #d4error_InvalidArgument
207 D4LIB_API int d4img_setImageFormat(d4img_ptr img, int width, int height, int pixelFormat);
208 
209 /// Get image data. Image data is converted, if 'pixelFormat' does not fit.
210 /// @param[in] img Valid pointer to an image.
211 /// @param[out] data Destination buffer for image data.
212 /// @param[in] size Size of destination buffer in bytes.
213 /// @param[in] pixelFormat Desired pixel format. See #d4img_PixelFormat.
214 /// When set to #d4img_UnknownPixelFormat, pixel format of 'img' is used.
215 /// @return #d4ok, #d4error_InvalidArgument
216 D4LIB_API int d4img_getImageData(d4img_ptr img, void* data, d4size size, int pixelFormat);
217 
218 /// Set the image data. Image data is converted, if 'pixelFormat' does not fit.
219 /// @param[out] img Valid pointer to an image.
220 /// @param[in] data Valid pointer it image data array.
221 /// @param[in] size Size of image data array in bytes.
222 /// @param[in] pixelFormat Pixel format of data array. See #d4img_PixelFormat.
223 /// When set to #d4img_UnknownPixelFormat, pixel format of 'img' is used.
224 /// @return #d4ok, #d4error_InvalidArgument
225 D4LIB_API int d4img_setImageData(d4img_ptr img, const void* data, d4size size, int pixelFormat);
226 
227 /// Set the image data. Image data is converted, if 'pixelFormat' does not fit.
228 /// @param[out] destImg Valid pointer to destination image.
229 /// @param[in] pixelFormat Pixel format of data array. See #d4img_PixelFormat.
230 /// When set to #d4img_UnknownPixelFormat, image data is just copied.
231 /// @param[in] srcImg Valid pointer to source image.
232 /// @return #d4ok, #d4error_InvalidArgument
233 D4LIB_API int d4img_convert(d4img_ptr destImg, int pixelFormat, d4img_ptr srcImg);
234 
235 /// Import image from file.
236 /// @note Supported file formats: .bmp
237 /// @note Supported image formats: #d4img_RGB24
238 /// @param[out] img Valid pointer to destination image.
239 /// @param[in] filename Filename of image.
240 /// @return #d4ok, #d4error_InvalidArgument, #d4error_InvalidPath, #d4error_FileNotFound, #d4error_NoAccess, #d4error_FormatNotAvailable, #d4error_Fail
241 D4LIB_API int d4img_import(d4img_ptr img, const char* filename);
242 
243 /// Export image to file.
244 /// @note Supported file formats: .bmp, .png
245 /// @note Supported image formats: #d4img_RGB24
246 /// @param[in] img Valid pointer to destination image.
247 /// @param[in] filename Filename of image.
248 /// @return #d4ok, #d4error_InvalidArgument, #d4error_InvalidPath, #d4error_NoAccess, #d4error_FormatNotAvailable, #d4error_Fail
249 D4LIB_API int d4img_export(d4img_ptr img, const char* filename);
250 
251 /// Compute a color image from 3 or 4 grayscale images that were capture under specific lighting conditions.
252 /// @param[out] outputColorImage Valid pointer to output image. Output pixel format will be set #d4img_RGB24.
253 /// Width and height will be set to width and height of input images.
254 /// @param[in] inputGrayImages Valid pointer to an array of 3 or 4 image pointers. The following conditions have to be met:
255 /// - All input images have to be of the same width and height.
256 /// - All input images have to be of pixel format #d4img_Y800.
257 /// - Ordering has to be red, green, blue, and optional black image.
258 /// @param[in] inputImageCount Number of input images. Has to be 3 or 4.
259 /// @return #d4ok, #d4error_InvalidArgument, #d4error_FormatNotAvailable
260 D4LIB_API int d4img_computeColorImage(d4img_ptr outputColorImage, d4img_ptr* inputGrayImages, int inputImageCount);
261 
262 /// Compute white balance parameters. The color image has to be captured with a white background.
263 /// @note See #d4img_convert for supported image formats.
264 /// @param[in] img Valid pointer to input to a color image.
265 /// @param[out] redFactor Valid pointer to double that gets the scaling factor for red color component.
266 /// @param[out] greenFactor Valid pointer to double that gets the scaling factor for green color component.
267 /// @param[out] blueFactor Valid pointer to double that gets the scaling factor for blue color component.
268 /// @return #d4ok, #d4error_InvalidArgument, #d4error_FormatNotAvailable
269 D4LIB_API int d4img_computeWhiteBalance(d4img_ptr img, double* redFactor, double* greenFactor, double* blueFactor);
270 
271 /// Apply white balance correction to 'img'.
272 /// @note Supported image formats: d4img_RGB24
273 /// @param[in,out] img Valid pointer to image that should be corrected.
274 /// @param[in] redFactor Red correction factor > 0.
275 /// @param[in] greenFactor Green correction factor > 0.
276 /// @param[in] blueFactor Blue correction factor > 0.
277 /// @return #d4ok, #d4error_InvalidArgument, #d4error_FormatNotAvailable
278 D4LIB_API int d4img_applyWhiteBalance(d4img_ptr img, double redFactor, double greenFactor, double blueFactor);
279 
280 
281 /// @}
282 
283 
284 //=============================================================================
285 /// @name Float images
286 /// Special functions and types related to scalar float images.
287 /// Each pixel has a 32bit scalar float value with no special bounds on ranges.
288 /// Notes:
289 /// - Image pointer is #d4fimg_ptr
290 /// - New images are created via #d4fimg_newImage
291 /// - Access to image format si via #d4fimg_setImageFormat and #d4fimg_getImageFormat
292 /// - Access to image data is via #d4fimg_setImageData and #d4fimg_getImageData
293 /// @{
294 //=============================================================================
295 
296 /// Creates a new 32bit float image.
297 /// @return Pointer to an image or d4null in case of an error.
298 D4LIB_API d4fimg_ptr d4fimg_newImage();
299 
300 /// Get format of the float image.
301 /// @param[in] img Valid pointer to a float image.
302 /// @param[out] width Pointer to an int that gets the width of the image. May be NULL.
303 /// @param[out] height Pointer to an int that gets the height of the image. May be NULL.
304 /// @return #d4ok, #d4error_InvalidArgument
305 D4LIB_API int d4fimg_getImageFormat(d4fimg_ptr img, int* width, int* height);
306 
307 /// Set format of the float image.
308 /// @param[in] img Valid pointer to a float image.
309 /// @param[out] width Width of the image or zero.
310 /// @param[out] height Height of the image or zero.
311 /// @return #d4ok, #d4error_InvalidArgument
312 D4LIB_API int d4fimg_setImageFormat(d4fimg_ptr img, int width, int height);
313 
314 /// Get image data.
315 /// @param[in] img Valid pointer to an image.
316 /// @param[out] data Destination buffer for image data.
317 /// @param[in] size Size of 'data' in bytes.
318 /// @return #d4ok, #d4error_InvalidArgument
319 D4LIB_API int d4fimg_getImageData(d4fimg_ptr img, float* data, d4size size);
320 
321 /// Set image data.
322 /// @param[out] img Valid pointer to an image.
323 /// @param[in] data Source buffer for image data.
324 /// @param[in] size Size of 'data' in bytes.
325 /// @return #d4ok, #d4error_InvalidArgument
326 D4LIB_API int d4fimg_setImageData(d4fimg_ptr img, const float* data, d4size size);
327 
328 /// Supported replace operations.
330 {
331  d4fimg_ReplaceIfLess, ///< Replace value if it less than a comparison value.
332  d4fimg_ReplaceIfGreater ///< Replace value if it greater than a comparison value.
333 };
334 
335 /// Replace pixel value by 'replaceValue', if condition is valid. Otherwise source value is used.
336 /// @code
337 /// d4fimg_ReplaceIfLess: img[i] = compare[i] < threshold ? replaceValue : img[i];
338 /// d4fimg_ReplaceIfGreater: img[i] = compare[i] > threshold ? replaceValue : img[i];
339 /// @endcode
340 ///
341 /// @param[in,out] img Valid source and target image.
342 /// @param[in] replaceValue Value for replacement.
343 /// @param[in] compare Valid image that stores mask values for each pixel.
344 /// @param[in] threshold Threshold value that is used for comparison.
345 /// @param[in] replaceOp Desired replace operation.
346 /// @return #d4ok, #d4error_InvalidArgument
347 D4LIB_API int d4fimg_replace(d4fimg_ptr img, float replaceValue, d4fimg_ptr compare, float threshold, int replaceOp);
348 
349 /// Sets all pixel values to given float value.
350 /// @param[in,out] img Valid image.
351 /// @param[in] value Value to be set.
352 /// @return #d4ok, #d4error_InvalidArgument
353 D4LIB_API int d4fimg_setFloat(d4fimg_ptr img, float value);
354 
355 /// Export float image to file.
356 /// @note Supported file formats: .pfm
357 /// @param[in] img Valid pointer to float image.
358 /// @param[in] filename Filename of image.
359 /// @return #d4ok, #d4error_InvalidArgument, #d4error_InvalidPath, #d4error_NoAccess, #d4error_FormatNotAvailable, #d4error_Fail
360 D4LIB_API int d4fimg_export(d4fimg_ptr img, const char* filename);
361 
362 /// Import float image from file.
363 /// @note Supported file formats: .pfm
364 /// @param[out] img Valid pointer to destination float image.
365 /// @param[in] filename Filename of image.
366 /// @return #d4ok, #d4error_InvalidArgument, #d4error_InvalidPath, #d4error_FileNotFound, #d4error_NoAccess, #d4error_FormatNotAvailable, #d4error_Fail
367 D4LIB_API int d4fimg_import(d4fimg_ptr img, const char* filename);
368 
369 
370 /// @}
371 
372 //=============================================================================
373 /// @name Camera
374 /// Functions and types related to camera interface.
375 /// @note At the moment, only DirectShow cameras are supported.
376 /// @{
377 //=============================================================================
378 
379 /*
380 // Definition of supported camera modes.
381 enum d4cam_Mode
382 {
383  d4cam_StandardMode = 0, ///< Standard camera mode. Primary use: Preview and scanning.
384  d4cam_HighresMode = 1, ///< Some cameras might support a highres mode. Primary use: Texturing and highres scanning.
385 };
386 */
387 
388 /// Creates a new DirectShow camera instance.
389 /// @return Pointer to camera object.
390 D4LIB_API d4cam_ptr d4cam_newDirectShowCamera();
391 
392 /// Get the number of available cameras.
393 /// Can be used in combination with #d4cam_getAvailableCamerasName.
394 /// @param[in] cam Valid pointer to camera interface.
395 /// @param[out] count Valid pointer to int that gets the number of available cameras.
396 /// @return #d4ok, #d4error_InvalidArgument, #d4error_DeviceNotAvailable
397 D4LIB_API int d4cam_getAvailableCamerasCount(d4cam_ptr cam, int* count);
398 
399 /// Get the name of an available camera.
400 /// Can be used in combination with #d4cam_getAvailableCamerasCount.
401 /// @param[in] cam Valid pointer to camera interface.
402 /// @param[out] name Valid pointer to string that gets the camera name.
403 /// @param[in] maxLength Maximum length of 'name'.
404 /// @param[in] index Zero based index of available index.
405 /// @return #d4ok, #d4error_InvalidArgument, #d4error_DeviceNotAvailable
406 D4LIB_API int d4cam_getAvailableCamerasName(d4cam_ptr cam, char* name, d4size maxLength, int index);
407 
408 /// Open camera.
409 ///
410 /// Example:
411 /// @code
412 /// d4cam_open(cam, "DAVID-CAM-3-M (8F6DEE1E)", 0, 0, d4cam_Y800, 0.0);
413 /// d4cam_captureImageAsync(cam, img, 0.0, 1.0, 0);
414 /// d4cam_waitForCapture(cam, img);
415 /// @endcode
416 ///
417 /// @param[in,out] cam Valid pointer to camera.
418 /// @param[in] name Name of the camera.
419 /// @param[in] width Desired with of the camera forat. Set zero to ignore.
420 /// @param[in] height Desired height of the camera format. Set zero to ignore.
421 /// @param[in] pixelFormat Desired pixel format. Set to d4cam_UnknownPixelFormat to ignore.
422 /// @param[in] fps Desired frames per second of the camera format. Set zero to ignore.
423 /// @return #d4ok All ok.
424 /// @return #d4error_InvalidArgument One of the arguments is invalid.
425 /// @return #d4error_DeviceNotAvailable Selected camera is not available.
426 /// @return #d4error_FormatNotAvailable Selected camera image format is invalid.
427 D4LIB_API int d4cam_open(d4cam_ptr cam, const char* name, int width, int height, int pixelFormat, double fps);
428 
429 /// Check if camera is open and ok.
430 /// @param[in] cam Pointer to camera.
431 /// @return #d4ok, #d4error_InvalidArgument, #d4error_DeviceNotAvailable
432 D4LIB_API int d4cam_check(d4cam_ptr cam);
433 
434 /// Close camera.
435 /// @param[in,out] cam Valid pointer to camera.
436 /// @return #d4ok, #d4error_InvalidArgument
437 D4LIB_API int d4cam_close(d4cam_ptr cam);
438 
439 /// Set running camera into a paused state.
440 /// Camera is automatically resumed when calling any capture function.
441 /// Resuming a camera from paused state takes some time depeding on the camera driver.
442 /// @param[in,out] cam Valid pointer to a camera.
443 /// @return #d4ok, #d4error_InvalidArgument, #d4error_DeviceNotAvailable
444 D4LIB_API int d4cam_pause(d4cam_ptr cam);
445 
446 /*
447 // Set the camera mode.
448 // @param[in,out] Valid pointer to a camera.
449 // @param[in] mode Desired mode. See #d4cam_Mode.
450 // @return #d4ok, #d4error_InvalidArgument, #d4error_DeviceNotAvailable
451 D4LIB_API int d4cam_setMode(d4cam_ptr cam, int mode);
452 
453 // Get current camera mode.
454 // @param[in] Valid pointer to a camera.
455 // @param[out] Valid pointer to an int that gets the camera mode (see #d4cam_Mode).
456 // @return #d4ok, #d4error_InvalidArgument, #d4error_DeviceNotAvailable
457 D4LIB_API int d4cam_getMode(d4cam_ptr cam, int* mode);
458 */
459 
460 /// Start a new asynchronous image capture. The function returns immediately.
461 /// Use #d4cam_getCapturedImage to wait for the capturing to be finished.
462 /// Example:
463 /// @code
464 /// d4img_ptr img = d4img_newImage();
465 /// d4cam_captureImageAsync(cam, 0, 1.0, 0);
466 /// d4cam_getCapturedImage(cam, img, d4img_Y800);
467 /// // ...
468 /// d4mem_decRefCount(img);
469 /// img = NULL;
470 /// @endcode
471 /// @param[in,out] cam Valid pointer to a camera.
472 /// @param[in] minContentChange How much has the content of the new image to be different from the previous image? Range: [0,100]%.
473 /// @param[in] maxWaitTime Maximum wait time [seconds] until an image has to be captured.
474 /// 'minContentChange' will be ignored when 'maxWaitTime' has been exceeded.
475 /// @param[in] temporalSmoothCount Temporal smoothing: Final image is average of '1+temporalSmoothCount' camera images.
476 /// @return #d4ok, #d4error_InvalidArgument, #d4error_DeviceNotAvailable
477 D4LIB_API int d4cam_captureImageAsync(d4cam_ptr cam, int minContentChange, double maxWaitTime, int temporalSmoothCount);
478 
479 /// Set the number of images that are skipped after a content change was detected.
480 /// This value will be used when #d4cam_captureImageAsync is called with 'minContentChange' > 0.
481 /// Only set this value when there are problems (e.g. when using rolling shutter camera or image tearing).
482 /// @param[in,out] cam Valid pointer to a camera.
483 /// @param[in] skipCount Number of images to be skipped. Default value is 1.
484 /// @return #d4ok, #d4error_InvalidArgument, #d4error_DeviceNotAvailable
485 D4LIB_API int d4cam_setSkipCount(d4cam_ptr cam, int skipCount);
486 
487 /// Get the captured image. If a capturing is still in progress (started via #d4cam_captureImageAsync), the function will wait until capturing is finished.
488 /// @param[in,out] cam Valid pointer to a camera.
489 /// @param[out] img Valid pointer to an image that gets the captured image.
490 /// @param[in] pixelFormat Desired pixel format (see #d4img_PixelFormat). In case of #d4img_UnknownPixelFormat, camera pixel format will be used.
491 /// @return #d4ok, #d4error_InvalidArgument
492 /// @return #d4error_DeviceNotAvailable Camera is not open or does not deliver any images.
493 /// @return #d4error_Fail #d4cam_captureImageAsync was not called before.
494 D4LIB_API int d4cam_getCapturedImage(d4cam_ptr cam, d4img_ptr img, int pixelFormat);
495 
496 /// Get the image format of the camera.
497 /// @param[in] cam Valid pointer to camera.
498 /// @param[out] width Optional pointer to int for width of image. May be NULL.
499 /// @param[out] height Optioal pointer to int for height of image. May be NULL.
500 /// @param[out] pixelFormat Optional pointer to int for #d4img_PixelFormat. May be NULL.
501 /// @param[out] fps Optional pointer to double for frames per second. May be NULL.
502 /// @return #d4ok, #d4error_InvalidArgument, #d4error_DeviceNotAvailable
503 D4LIB_API int d4cam_getImageFormat(d4cam_ptr cam, int* width, int* height, int* pixelFormat, double* fps);
504 
505 /// Get the timestamp of the last captured image.
506 /// @param[in,out] cam Valid pointer to a camera.
507 /// @param[out] timestamp Valid pointer to a double that gets the timestamp [seconds].
508 /// @return #d4ok, #d4error_InvalidArgument, #d4error_DeviceNotAvailable
509 D4LIB_API int d4cam_getTimestamp(d4cam_ptr cam, double* timestamp);
510 
511 /// Set a camera property.
512 /// @param[in,out] cam Valid pointer to an open camera.
513 /// @param[in] value Value to be set.
514 /// @param[in] name Null terminated string of camera name.
515 /// @return #d4ok, #d4error_InvalidArgument, #d4error_DeviceNotAvailable
516 D4LIB_API int d4cam_setProperty(d4cam_ptr cam, double value, const char* name);
517 
518 /// Get a camera property.
519 /// @param[in,out] cam Valid pointer to an open camera.
520 /// @param[out] value Valid pointer to double that gets the value.
521 /// @param[in] name Valid string to name of property.
522 /// @return #d4ok, #d4error_InvalidArgument, #d4error_DeviceNotAvailable, #d4error_Fail
523 D4LIB_API int d4cam_getProperty(d4cam_ptr cam, double* value, const char* name);
524 
525 /// Get a camera property range.
526 /// @note Not all values (like 'deltaValue') might be available by every camera.
527 /// @param[in,out] cam Valid pointer to an open camera.
528 /// @param[out] minValue Valid pointer to double that gets the minimum value.
529 /// @param[out] maxValue Valid pointer to double that gets the maximum value.
530 /// @param[out] defValue Valid pointer to double that gets the default value.
531 /// @param[out] deltaValue Valid pointer to double that gets the delta value.
532 /// @param[in] name Valid string to name of property.
533 /// @return #d4ok, #d4error_InvalidArgument, #d4error_DeviceNotAvailable, #d4error_Fail
534 D4LIB_API int d4cam_getPropertyRange(d4cam_ptr cam, double* minValue, double* maxValue, double* defValue, double* deltaValue, const char* name);
535 
536 /// Get number of all camera property names or 'onlyAvailable' camera property names.
537 /// @param[in,out] cam Valid pointer to open camera.
538 /// @param[out] count Valid pointer to int that gets the count of camera property names.
539 /// @param[in] onlyAvailable List only available camera properties?
540 /// @return #d4ok, #d4error_InvalidArgument, #d4error_DeviceNotAvailable
541 D4LIB_API int d4cam_getPropertyCount(d4cam_ptr cam, int* count, bool onlyAvailable);
542 
543 /// Get a camera property name.
544 /// @warning Function has be used in combination with #d4cam_getPropertyCount and 'onlyAvailable' identical.
545 /// @param[in,out] cam Valid pointer to open camera.
546 /// @param[out] name Valid pointer to string that gets the property name.
547 /// @param[in] maxLength Maximum length of 'name'.
548 /// @param[in] propertyNameIndex Zero based index of a property name. Has to be in range [0, #d4cam_getPropertyCount).
549 /// @param[in] onlyAvailable List only available camera properties?
550 /// @return #d4ok, #d4error_InvalidArgument, #d4error_DeviceNotAvailable
551 D4LIB_API int d4cam_getPropertyName(d4cam_ptr cam, char* name, d4size maxLength, int propertyNameIndex, bool onlyAvailable);
552 
553 /// @}
554 
555 
556 //=============================================================================
557 /// @name Projector
558 /// Interface functions for controlling projectors.
559 /// Notes:
560 /// - Projector connected as extended display is created via #d4projector_newExtendedDisplayProjector
561 /// - Establish connection via #d4projector_openByScreenID, #d4projector_getScreenCount, and #d4projector_getScreenFormat
562 /// - Necessary image format for displaying images is available via #d4projector_getImageFormat
563 /// - Show images: #d4projector_displayImage and #d4projector_displayUniformColor
564 /// - Call #d4projector_close or release object when done
565 /// @{
566 //=============================================================================
567 
568 /// Creates a new projector using extended display.
569 /// @return Pointer to projector object or NULL in case of an error.
570 D4LIB_API d4projector_ptr d4projector_newExtendedDisplayProjector();
571 
572 /// Closes the connection to the projector.
573 /// @param[in,out] projector Valid pointer to the projector.
574 /// @return #d4ok, #d4error_InvalidArgument
575 D4LIB_API int d4projector_close(d4projector_ptr projector);
576 
577 /// Get image format for displaying images.
578 /// @param[in,out] projector Valid pointer to the projector.
579 /// @param[out] width Optional pointer to int that gets width of image [px].
580 /// @param[out] height Optional pointer to int that gets height of image [px].
581 /// @param[out] pixelFormat Optional pointer to int that gets pixel format of image (see #d4img_PixelFormat).
582 /// @return #d4ok, #d4error_InvalidArgument, #d4error_DeviceNotAvailable
583 D4LIB_API int d4projector_getImageFormat(d4projector_ptr projector, int* width, int* height, int* pixelFormat);
584 
585 /// Display an image.
586 /// @warning 'img' has to be of the format given by #d4projector_getImageFormat.
587 /// @param[in,out] projector Valid pointer to the projector.
588 /// @param[in] img Image to be displayed. Must have same format as #d4projector_getImageFormat.
589 /// @return #d4ok, #d4error_InvalidArgument, #d4error_DeviceNotAvailable
590 D4LIB_API int d4projector_displayImage(d4projector_ptr projector, d4img_ptr img);
591 
592 /// Display an image with a uniform color.
593 /// @param[in,out] projector Valid pointer to the projector.
594 /// @param[in] red Red color component [0,255].
595 /// @param[in] green Green color component [0,255].
596 /// @param[in] blue Blue color component [0,255].
597 /// @return #d4ok, #d4error_InvalidArgument, #d4error_DeviceNotAvailable
598 D4LIB_API int d4projector_displayUniformColor(d4projector_ptr projector, unsigned char red, unsigned char green, unsigned char blue);
599 
600 /// Establish the connection to a projector by given 'screenID'.
601 /// @param[in,out] projector Valid pointer to the projector.
602 /// @param[in] screenID ID of the desired screen. First screen has ID 1. Use in combination with #d4projector_getScreenCount.
603 /// @return #d4ok, #d4error_InvalidArgument
604 D4LIB_API int d4projector_openByScreenID(d4projector_ptr projector, int screenID);
605 
606 /// Check if projector is open and ok.
607 /// @param[in] projector Pointer to projector.
608 /// @return #d4ok, #d4error_InvalidArgument, #d4error_DeviceNotAvailable
609 D4LIB_API int d4projector_check(d4projector_ptr projector);
610 
611 /// Get the number of available screens.
612 /// Should be used in combination with #d4projector_getScreenFormat.
613 /// @param[in,out] projector Valid pointer to the projector.
614 /// @param[out] screenCount Valid pointer to int that gets the number of available screens.
615 /// @return #d4ok, #d4error_InvalidArgument
616 D4LIB_API int d4projector_getScreenCount(d4projector_ptr projector, int* screenCount);
617 
618 /// Get screen dimensions and position for requested screen.
619 /// Should be used in combination with #d4projector_getScreenCount.
620 /// @param[in,out] projector Valid pointer to the projector.
621 /// @param[out] x Optional pointer to int that gets x position of screen [px].
622 /// @param[out] y Optional pointer to int that gets x position of screen [px].
623 /// @param[out] width Optional pointer to int that gets width of screen [px].
624 /// @param[out] height Optional pointer to int that gets height of screen [px].
625 /// @param[in] screenID ID of the desired screen. First screen has ID 1. Use in combination with #d4projector_getScreenCount.
626 /// @return #d4ok, #d4error_InvalidArgument, #d4error_DeviceNotAvailable
627 D4LIB_API int d4projector_getScreenFormat(d4projector_ptr projector, int* x, int* y, int* width, int* height, int screenID);
628 
629 /// @}
630 
631 
632 //=============================================================================
633 /// @name Calibration
634 /// Interface functions related to camera and projector calibration.
635 /// Notes:
636 /// - New calibration objects are created via #d4calib_newCameraCalibration or #d4calib_newProjectorCalibration.
637 /// - Calibration state is checked via #d4calib_isCalibrated.
638 /// - Import and export of calibration data: #d4calib_importCalibration and #d4calib_exportCalibration.
639 /// - Calibration: #d4calib_calibrate
640 /// @{
641 //=============================================================================
642 
643 /// Point correspondence used for calibration.
644 /// 'worldRefPos3d' is projected into camera image at 'projectedPos2d'.
645 /// The error between 'projectedPos2d' and measured marker point 'measuredPos2d' should be minimal.
647 {
648  double worldRefPos3d[3]; ///< Reference 3d point (x,y,z) with respect to world coordinates.
649  double measuredPos2d[2]; ///< Measured 2d image point with respect to image coordinates.
650  double projectedPos2d[2]; ///< Image coordinates of 'worldRefPos3d' projected into image using calibrated model parameters.
651 };
652 
653 /// More detailed camera calibration error.
655 {
656  d4calib_CamCalibError_ok = 0, ///< No error.
657  d4calib_CamCalibError_MarkerDetection = -100, ///< Marker detection failed.
658  d4calib_CamCalibError_MarkerMapping = -101, ///< Left and right calibration planes do not intersect.
659  d4calib_CamCalibError_PlaneIntersection = -102, ///< Left and right calibration planes do not intersect.
660  d4calib_CamCalibError_LeftPlane = -103, ///< Calibration of left plane failed.
661  d4calib_CamCalibError_RightPlane = -104, ///< Calibration of right plane failed.
662  d4calib_CamCalibError_ModelFitting = -105, ///< Could not find valid mapping between measured points and model parameters.
663  d4calib_CamCalibError_ErrorValuesTooHigh = -106, ///< The resulting calibration error values are too high.
664  d4calib_CamCalibError_Unknown = -107, ///< Unknown calibration error.
665 };
666 
667 /// More detailed projector calibration error.
669 {
670  d4calib_ProjectorCalibError_ok = 0, ///< No error.
671  d4calib_ProjectorCalibError_PhaseImage = -200, ///< Could not compute phase image from input sequence.
672  d4calib_ProjectorCalibError_ModelFitting = -201, ///< Could not find valid mapping between measured points and model parameters.
673  d4calib_ProjectorCalibError_Unknown = -202, ///< Unknown calibration error.
674 };
675 
676 /// Create a new calibration object for cameras.
677 /// @return Pointer to camera calibration object or NULL in case of an error.
678 D4LIB_API d4calib_ptr d4calib_newCameraCalibration();
679 
680 /// Create a new calibration object for projectors.
681 /// @return Pointer to projector calibration object or NULL in case of an error.
682 D4LIB_API d4calib_ptr d4calib_newProjectorCalibration();
683 
684 /// Is calibration valid?
685 /// @param[in,out] calib Valid pointer to calibration object.
686 /// @param[out] calibrated Valid pointer to bool that gets calibration state: True, if calibrated.
687 /// @return #d4ok, #d4error_InvalidArgument
688 D4LIB_API int d4calib_isCalibrated(d4calib_ptr calib, bool* calibrated);
689 
690 /// Import calibration data from file.
691 /// @param[in,out] calib Valid pointer to calibration object.
692 /// @param[in] filename Valid pointer to filename string.
693 /// @return #d4ok, #d4error_InvalidArgument, #d4error_FileNotFound, #d4error_InvalidFormat
694 D4LIB_API int d4calib_importCalibration(d4calib_ptr calib, const char* filename);
695 
696 /// Export calibration data to file.
697 /// @param[in,out] calib Valid pointer to calibration object.
698 /// @param[in] filename Valid pointer to filename string.
699 /// @return #d4ok, #d4error_InvalidArgument
700 D4LIB_API int d4calib_exportCalibration(d4calib_ptr calib, const char* filename);
701 
702 /// Change resolution of image format used for calibration. Intrinsics are adapted to this new resolution.
703 /// @note Only available for camera calibration. Projector model uses normalized coordinates.
704 /// @warning The aspect ratio is not allowed to change.
705 /// @param[in,out] calib Valid pointer to calibration object.
706 /// @param[in] newWidth New camera image width.
707 /// @param[in] newHeight New camera image height.
708 /// @return #d4ok, #d4error_InvalidArgument, #d4error_NotCalibrated, #d4error_InvalidFormat
709 D4LIB_API int d4calib_changeCalibrationResolution(d4calib_ptr calib, int newWidth, int newHeight);
710 
711 /// Get the resolution of a calibration.
712 /// @note Only available for camera calibration. Projector model uses normalized coordinates.
713 /// @param[in] calib Valid pointer to calibration object.
714 /// @param[out] width The image width.
715 /// @param[out] height The image height.
716 /// @return #d4ok, #d4error_InvalidArgument, #d4error_NotCalibrated
717 D4LIB_API int d4calib_getCalibrationResolution(d4calib_ptr calib, int *width, int *height);
718 
719 /// Standard calibration procedure for one camera and one projector using the corner calibration panels.
720 /// @warning Only #d4img_Y800 pixel format is supported for 'imgCamCalib' and 'capturedImages'.
721 /// @param[out] camCalib Valid pointer to camera calibration object.
722 /// @param[in] imgCamCalib Valid pointer to camera image of calibration corner.
723 /// @param[out] projectorCalib Valid pointer to projector calibration object.
724 /// @param[in,out] sls Valid pointer to structured light scanning object.
725 /// @param[in] capturedImages Valid pointer to an array of image pointers. Every pointer has to be valid and of pixel format #d4img_Y800.
726 /// @param[in] imageCount Number of image pointers in 'capturedImages'.
727 /// @param[in] scale Calibration scale from panel.
728 /// @param[in] compensatePatternOffsets Use bundle adjustment to determine offsets of left and right patterns within their respective planes. Set to false, if calibration corner is perfect.
729 /// @param[out] calibError Optional pointer to int that gets additional information about calibration error (#d4calib_CamCalibError, #d4calib_ProjectorCalibError, or #d4ok).
730 /// @param[out] calibPoints Optional pointer to array of calibration points that is filled with correspondences used for calibration. See #d4calib_CalibPoint.
731 /// @param[in,out] calibPointCount Optional pointer to int. Input: Maximum number of calibration points that fit into 'calibPoints'. Output: Number of calibration points written to 'calibPoints'.
732 /// @return #d4ok, #d4error_InvalidArgument, #d4error_FormatNotAvailable, #d4error_CameraCalibration, #d4error_ProjectorCalibration
733 D4LIB_API int d4calib_calibrate(d4calib_ptr camCalib, d4img_ptr imgCamCalib,
734  d4calib_ptr projectorCalib, d4sls_ptr sls, d4img_ptr* capturedImages, int imageCount,
735  double scale, bool compensatePatternOffsets, int* calibError,
736  d4calib_CalibPoint* calibPoints, int* calibPointCount);
737 
738 /// @}
739 
740 
741 //=============================================================================
742 /// @name Structured Light Scanner
743 /// Types and functions related to Structured Light Scanning (SLS).
744 /// Notes:
745 /// - Create new SLS object: #d4sls_newStructuredLightScanner
746 /// - Access to parameters: #d4sls_getCodedLightPhaseShiftParams and #d4sls_setCodedLightPhaseShiftParams
747 /// - Project pattern images: #d4sls_getPatternCount, #d4sls_getPatternImage
748 /// - Compute scan result as depth image: #d4sls_computeDepthImage
749 /// @{
750 //=============================================================================
751 
752 /// Selects the color used for all generated patterns.
754 {
755  d4sls_White, ///< All color channels are used by same magnitude.
756  d4sls_Red, ///< Only red color channel is used.
757  d4sls_Green, ///< Only green color channel is used.
758  d4sls_Blue ///< Only blue color channel is used.
759 };
760 
761 /// Defines orientations for hardware setup.
763 {
764  d4sls_HorizontalOrientation, ///< Horizontal setup. Projector and camera are next to each other.
765  d4sls_VerticalOrientation, ///< Vertical setup. Projector and camera are above each other.
766  d4sls_BothOrientations ///< Diagonal setup. Projector and camera are located diagonally.
767 };
768 
769 /// Defines parameters used in structured light mode 'coded light + phase shift' ('cl+ps').
771 {
772  int colorSelect; ///< Select color to channel for projection. See d4sls_ColorSelect.
773  int orientation; ///< Orientation of setup. See d4sls_Orientation.
774  int brightness; ///< Maximum brightness of pattern colors in range [0,255].
775  int shifts; ///< Number of phase shifts.
776  int frequencies; ///< Number of frequencies (affects number of patterns). Optimal setting depends on camera/projector resolution and setup.
777  bool inverse; ///< Use inverted patterns for coded light?
778  bool randomizeSequence; ///< Randomize pattern sequence? Changes the order of pattern in sequence. Can improve pattern change detection based on image content.
779 };
780 
781 /// Defines a plane in 3D. Used for d4sls_planesToDepthImage.
783 {
784  double pos[3]; ///< One point on the plane (X,Y,Z)
785  double normal[3]; ///< Normal vector of the plane (X,Y,Z)
786 };
787 
788 /// Create new SLS object.
789 /// @return Pointer to SLS object or NULL.
790 D4LIB_API d4sls_ptr d4sls_newStructuredLightScanner();
791 
792 /// Get parameters for 'cl+ps' mode.
793 /// @param[in,out] sls Valid pointer to a SLS instance.
794 /// @param[out] params Valid pointer to parameters.
795 /// @return #d4ok, #d4error_InvalidArgument
796 D4LIB_API int d4sls_getCodedLightPhaseShiftParams(d4sls_ptr sls, d4sls_CodedLightPhaseShiftParams* params);
797 
798 /// Set parameters for 'cl+ps' mode.
799 /// @note By setting parameters the 'cl+ps' will be activated automatically. 'cl+ps' is active by default.
800 /// @param[in,out] sls Valid pointer to a SLS instance.
801 /// @param[out] params Valid pointer to parameters.
802 /// @return #d4ok, #d4error_InvalidArgument
803 D4LIB_API int d4sls_setCodedLightPhaseShiftParams(d4sls_ptr sls, const d4sls_CodedLightPhaseShiftParams* params);
804 
805 /// Get number of pattern in a scanning sequence.
806 /// @param[in,out] sls Valid pointer to a SLS instance.
807 /// @param[out] patternCount Valid pointer to int that gets the pattern count.
808 /// @return #d4ok, #d4error_InvalidArgument
809 D4LIB_API int d4sls_getPatternCount(d4sls_ptr sls, int* patternCount);
810 
811 /// Get pattern image at 'patternIndex'.
812 /// @param[in,out] sls Valid pointer to Structured Light Scanning instance.
813 /// @param[out] img Valid pointer to image for pattern.
814 /// @param[in] width Desired image width [px].
815 /// @param[in] height Desired image height [px].
816 /// @param[in] pixelFormat Desired pixel format, see #d4img_PixelFormat. Supported formats are:
817 /// - d4img_RGB24
818 /// @param[in] patternIndex Valid zero based index of pattern. @see #d4sls_getPatternCount.
819 /// @return #d4ok, #d4error_InvalidArgument
820 /// @return #d4error_InvalidFormat Selected pixel format is not supported.
821 D4LIB_API int d4sls_getPatternImage(d4sls_ptr sls, d4img_ptr img, int width, int height, int pixelFormat, int patternIndex);
822 
823 /// Get special image for setup.
824 /// @param[in,out] sls Valid pointer to Structured Light Scanning instance.
825 /// @param[out] img Valid pointer to image for pattern.
826 /// @param[in] width Desired image width [px].
827 /// @param[in] height Desired image height [px].
828 /// @param[in] pixelFormat Desired pixel format, see #d4img_PixelFormat. Supported formats are:
829 /// - d4img_RGB24
830 /// @return #d4ok, #d4error_InvalidArgument
831 /// @return #d4error_InvalidFormat Selected pixel format is not supported.
832 D4LIB_API int d4sls_getSetupImage(d4sls_ptr sls, d4img_ptr img, int width, int height, int pixelFormat);
833 
834 /// Get special chessboard image that can be used to validate a calibration performed by #d4calib_calibrate.
835 /// @param[in,out] sls Valid pointer to Structured Light Scanning instance.
836 /// @param[out] img Valid pointer to image for pattern.
837 /// @param[in] width Desired image width [px].
838 /// @param[in] height Desired image height [px].
839 /// @param[in] pixelFormat Desired pixel format, see #d4img_PixelFormat. Supported formats are:
840 /// - d4img_RGB24
841 /// @param[in] projectorCalib Valid pointer to projector calibration.
842 /// @param[in] scale Scale used for calibration.
843 /// @return #d4ok, #d4error_InvalidArgument, #d4error_NotCalibrated
844 /// @return #d4error_InvalidFormat Selected pixel format is not supported.
845 D4LIB_API int d4sls_getChessboardImage(d4sls_ptr sls, d4img_ptr img, int width, int height, int pixelFormat, d4calib_ptr projectorCalib, double scale);
846 
847 /// Compute depth image that represents the current scan.
848 /// @warning At the moment, only #d4img_Y800 is supported for captured images.
849 /// @param[in,out] sls Valid pointer to Structured Light Scanning instance.
850 /// @param[out] depthImage Valid pointer to float image that gets depth values for each pixel of the camera.
851 /// @param[out] qualityImage Optional pointer to float image that gets quality values for each depth value.
852 /// @param[in] capturedImages Valid pointer to an array of image pointers. Every pointer has to be valid and of pixel format #d4img_Y800.
853 /// @param[in] imageCount Number of image pointers in 'capturedImages'.
854 /// @param[in] camCalib Valid pointer to camera calibration object.
855 /// @param[in] projectorCalib Valid pointer to projector calibration object.
856 /// @param[in] minContrast Minimum required contrast (magnitude of amplitude signal). Set to <= 0 in order to use default value (10).
857 /// @return #d4ok, #d4error_InvalidArgument, #d4error_NotCalibrated
858 D4LIB_API int d4sls_computeDepthImage(d4sls_ptr sls, d4fimg_ptr depthImage, d4fimg_ptr qualityImage,
859  d4img_ptr* capturedImages, int imageCount, d4calib_ptr camCalib, d4calib_ptr projectorCalib,
860  int minContrast);
861 
862 /// Computes a depth image from a list of planes.
863 /// @param[in] sls Valid pointer to Structured Light Scanning instance.
864 /// @param[out] depthImage Valid pointer to float image that gets depth values for each pixel of the camera.
865 /// @param[in] camCalib Valid pointer to camera calibration object.
866 /// @param[in] numPlanes Number of planes given by parameter "planes".
867 /// @param[in] planes Array of d4sls_Plane structs.
868 /// @return #d4ok, #d4error_InvalidArgument, #d4error_NotCalibrated
869 D4LIB_API int d4sls_planesToDepthImage(d4sls_ptr sls, d4fimg_ptr depthImage, d4calib_ptr camCalib, int numPlanes, const d4sls_Plane* planes);
870 
871 /// @}
872 
873 
874 //=============================================================================
875 /// @name Scanning
876 /// Generic scanning functions.
877 /// Notes:
878 /// - Triangulation of depth images: #d4scan_convertDepthImageToMesh
879 /// - Background removal: #d4scan_removeBackground
880 /// @{
881 //=============================================================================
882 
883 /// Compute mesh from a depth image.
884 /// For every pixel of the depth image with a depth value in range [minDepth, maxDepth] a vertex is generated.
885 /// Neighbouring vertices are triangulated. Vertices that are not referenced by any triangle are removed.
886 /// @param[out] mesh Valid pointer to a mesh.
887 /// @param[in] depthImage Valid pointer to a depth image.
888 /// @param[in] qualityImage Optional pointer to a quality image with values in range [0,1]=[bad,good].
889 /// @param[in] calib Valid (camera) calibration.
890 /// @param[in] minDepth Minimum depth value in [mm]. Has to be > 0.
891 /// @param[in] maxDepth Maximum depth value in [mm]. Has to be > 'minDepth'.
892 /// @param[in] depthThres Neighbor pixels to a triangle will not be connected, if their difference in depth is larger than this value [mm].
893 /// @param[in] minQuality Minimum quality value. Only used if 'qualityImage' is a valid pointer.
894 /// @param[in] outlierRemoval Outlier filter, removing smallest fragments. 0=off. 1=remove all except the largest fragment. e.g. 0.1=remove all fragments that are smaller than 10% of the largest fragment.
895 /// @return #d4ok, #d4error_InvalidArgument
896 D4LIB_API int d4scan_convertDepthImageToMesh(d4mesh_ptr mesh, d4fimg_ptr depthImage, d4fimg_ptr qualityImage, d4calib_ptr calib, float minDepth, float maxDepth, float depthThres, float minQuality, double outlierRemoval);
897 
898 /// Remove background scan from current scan.
899 /// All depth values that are farther away the the background, are set to -1:
900 /// @code
901 /// depthImage[i] = (depthImage[i] < backgroundImage[i] - epsilon) ? depthImage[i] : -1.f;
902 /// @endcode
903 ///
904 /// @param[in,out] depthImage Valid pointer to depth image that represents the current scan.
905 /// @param[in] backgroundImage Valid pointer to depth image that represents the background scan.
906 /// @param[in] epsilon Expand background scan by this amount into the direction of the cameras origin.
907 D4LIB_API int d4scan_removeBackground(d4fimg_ptr depthImage, d4fimg_ptr backgroundImage, float epsilon);
908 
909 /// @}
910 
911 
912 //=============================================================================
913 /// @name Mesh
914 /// A triangulated mesh represents the surface of a 3D object.
915 /// More information about triangulated meshes:
916 /// - http://en.wikipedia.org/wiki/Triangle_mesh
917 /// - http://en.wikipedia.org/wiki/Polygon_mesh#Face-vertex_meshes
918 ///
919 /// Notes:
920 /// - Create new mesh: #d4mesh_newMesh
921 /// - Number of vertices and triangles: #d4mesh_getVertexCount, #d4mesh_getTriangleCount
922 /// - Access to buffers: #d4mesh_getBuffer, #d4mesh_setBuffer, #d4mesh_BufferType
923 /// - Access to texture: #d4mesh_getTexture, #d4mesh_setTexture
924 /// - Position and orientation of mesh: #d4mesh_getPose, #d4mesh_setPose
925 /// - Grouping / submeshes: #d4mesh_getSubmeshCount, #d4mesh_combine, #d4mesh_uncombine
926 ///
927 /// @{
928 //=============================================================================
929 
930 /// Buffer selection.
932 {
933  /// The vertex position buffer stores the vertex positions as an array of tuples.
934  /// Each vertex position is described by a tuple (x,y,z) of three 32bit floats .
935  /// This buffer is always present.
936  /// @note Coordinates are always with respect to the local coordinate system of the mesh.
938 
939  /// The vertex normal buffer stores the vertex normals as an array of tuples.
940  /// Each vertex normal is described by a tuple (nx,ny,nz) of three 32bit floats.
941  /// This buffer is always present.
942  /// @note Coordinates are always with respect to the local coordinate system of the mesh.
944 
945  /// The texture coordinates buffer stores texture coordinates as an array of tuples.
946  /// Each vertex texture coordinate is described a tuple (u,v) of two 32bit floats.
947  /// This buffer is only optional.
948  /// @note Coordinates should be in range [0,1].
950 
951  /// The texture color buffer stores vertex colors as an array of tuples.
952  /// Each vertex texture coordinate is described a RGBA tuple (red, green, blue, alpha) of four 8bit unsigned chars.
953  /// This buffer is only optional.
954  /// @note Coordinates should be in range [0,1].
956 
957  /// The triangle index buffer stores triangles as an array of vertex indices.
958  /// Each triangle is described by tuple (v0, v1, v2) of three 32bit integer vertex indices that are zero based.
959  /// This buffer is always present.
961 
962  /// The vertex quality buffer stores a quality value for each vertex.
963  /// This buffer is only optional.
964  /// @note Quality values should be in range [0,1].
966 };
967 
968 
969 /// Create new mesh object.
970 /// @return Pointer to mesh object or NULL.
971 D4LIB_API d4mesh_ptr d4mesh_newMesh();
972 
973 /// Clear all data of mesh object.
974 /// @param[in,out] mesh Valid pointer to mesh object.
975 /// @return #d4ok, #d4error_InvalidArgument
976 D4LIB_API int d4mesh_clear(d4mesh_ptr mesh);
977 
978 /// Copy mesh data from 'sourceMesh' to 'targetMesh'.
979 /// Old content of 'targetMesh' is deleted.
980 /// @param[out] targetMesh Valid pointer to target mesh object.
981 /// @param[in] sourceMesh Valid pointer to source mesh object.
982 /// @return #d4ok, #d4error_InvalidArgument
983 D4LIB_API int d4mesh_copy(d4mesh_ptr targetMesh, d4mesh_ptr sourceMesh);
984 
985 /// Combine multiple meshes into submeshes of a single mesh.
986 /// @param[out] meshGroup Valid pointer to a mesh object. Must not be part of 'meshesToCombine'.
987 /// @param[in] meshesToCombine Pointer to array of valid pointers to mesh objects that have to be combined.
988 /// @param[in] meshCount Number of meshes referenced by 'meshesToCombine'.
989 /// @return #d4ok, #d4error_InvalidArgument
990 D4LIB_API int d4mesh_combine(d4mesh_ptr meshGroup, d4mesh_ptr* meshesToCombine, int meshCount);
991 
992 /// Uncombine submeshes of 'meshGroup' into independent meshes.
993 /// 'meshCount' has to be equal to the submesh count of 'mesh' (see #d4mesh_getSubmeshCount).
994 /// @param[in] meshGroup Valid pointer to a mesh object that contains combined meshes. Must not be part of 'uncombinedMeshes'.
995 /// @param[out] uncombinedMeshes Pointer to array of valid pointers to mesh objects that get the uncombined meshes.
996 /// @param[in] meshCount Number of meshes referenced by 'uncombinedMeshes'.
997 /// @return #d4ok, #d4error_InvalidArgument
998 D4LIB_API int d4mesh_uncombine(d4mesh_ptr meshGroup, d4mesh_ptr* uncombinedMeshes, int meshCount);
999 
1000 /// Get the number of submeshes (combined meshes) in 'mesh'.
1001 /// A mesh has at least one submesh. This is also the standard case unless #d4mesh_combine or #d4mesh_setSubmeshCount was used.
1002 /// @param[in] mesh Valid pointer to a mesh object.
1003 /// @param[out] count Valid pointer to int that gets number of combined meshes in 'mesh'.
1004 /// @return #d4ok, #d4error_InvalidArgument
1005 D4LIB_API int d4mesh_getSubmeshCount(d4mesh_ptr mesh, int* count);
1006 
1007 /// Set the number of submeshes (combined meshes) in 'mesh'.
1008 /// @param[in] mesh Valid pointer to a mesh object.
1009 /// @param[in] count New number of submeshes (>0).
1010 /// @return #d4ok, #d4error_InvalidArgument
1011 D4LIB_API int d4mesh_setSubmeshCount(d4mesh_ptr mesh, int count);
1012 
1013 /// Copy requested buffer ('bufferType') content into 'data'.
1014 /// You can use #d4mesh_getVertexCount, #d4mesh_getTriangleCount, and #d4mesh_getBufferSize to
1015 /// compute the correct size of 'data'.
1016 /// @param[in] mesh Valid pointer to a mesh object.
1017 /// @param[out] data Valid pointer to data buffer.
1018 /// @param[in] size Size of 'data' buffer in bytes.
1019 /// @param[in] bufferType Desired data buffer, see #d4mesh_BufferType.
1020 /// @param[in] submeshIndex Zero based index to a submesh of 'mesh'. Also see #d4mesh_getSubmeshCount.
1021 /// @return #d4ok, #d4error_InvalidArgument
1022 D4LIB_API int d4mesh_getBuffer(d4mesh_ptr mesh, void* data, d4size size, int bufferType, int submeshIndex);
1023 
1024 /// Copy 'data' into the desired buffer ('bufferType').
1025 /// You can use #d4mesh_getVertexCount, #d4mesh_getTriangleCount, and #d4mesh_getBufferSize to
1026 /// compute the correct size of 'data'.
1027 /// @param[out] mesh Valid pointer to a mesh object.
1028 /// @param[in] data Valid pointer to data buffer.
1029 /// @param[in] size Size of 'data' buffer in bytes.
1030 /// @param[in] bufferType Desired data buffer, see #d4mesh_BufferType.
1031 /// @param[in] submeshIndex Zero based index to a submesh of 'mesh'. Also see #d4mesh_getSubmeshCount.
1032 /// @return #d4ok, #d4error_InvalidArgument
1033 D4LIB_API int d4mesh_setBuffer(d4mesh_ptr mesh, const void* data, d4size size, int bufferType, int submeshIndex);
1034 
1035 /// Is the buffer 'bufferType' available?
1036 /// See #d4mesh_BufferType for information about which buffers are optional.
1037 /// @param[in] mesh Valid pointer to a mesh object.
1038 /// @param[out] hasBuffer Valid pointer to bool that gets answer.
1039 /// @param[in] bufferType Desired data buffer, see #d4mesh_BufferType.
1040 /// @param[in] submeshIndex Zero based index to a submesh of 'mesh'. Also see #d4mesh_getSubmeshCount.
1041 /// @return #d4ok, #d4error_InvalidArgument
1042 D4LIB_API int d4mesh_hasBuffer(d4mesh_ptr mesh, bool* hasBuffer, int bufferType, int submeshIndex);
1043 
1044 /// Get size of buffer 'bufferType' in bytes (for all submeshes).
1045 /// @param[in] mesh Valid pointer to a mesh object.
1046 /// @param[out] size Valid pointer to value that gets the size of the buffer in bytes.
1047 /// Size will be set to zero if buffer is not available.
1048 /// @param[in] bufferType Desired data buffer, see #d4mesh_BufferType.
1049 /// @param[in] submeshIndex Zero based index to a submesh of 'mesh'. Also see #d4mesh_getSubmeshCount.
1050 /// @return #d4ok, #d4error_InvalidArgument
1051 D4LIB_API int d4mesh_getBufferSize(d4mesh_ptr mesh, d4size* size, int bufferType, int submeshIndex);
1052 
1053 /// Get the number of vertices for a given submesh of a mesh.
1054 /// @param[in] mesh Valid pointer to a mesh object.
1055 /// @param[out] vertexCount Valid pointer to int that gets the number of vertices.
1056 /// @param[in] submeshIndex Zero based index to a submesh of 'mesh'. Also see #d4mesh_getSubmeshCount.
1057 /// @return #d4ok, #d4error_InvalidArgument
1058 D4LIB_API int d4mesh_getVertexCount(d4mesh_ptr mesh, int* vertexCount, int submeshIndex);
1059 
1060 /// Set the number of vertices for a given submesh of a mesh.
1061 /// @param[in] mesh Valid pointer to a mesh object.
1062 /// @param[in] vertexCount New vertex count.
1063 /// @param[in] submeshIndex Zero based index to a submesh of 'mesh'. Also see #d4mesh_getSubmeshCount.
1064 /// @return #d4ok, #d4error_InvalidArgument
1065 D4LIB_API int d4mesh_setVertexCount(d4mesh_ptr mesh, int vertexCount, int submeshIndex);
1066 
1067 /// Get the number of triangles (total count for all submeshes).
1068 /// @param[in] mesh Valid pointer to a mesh object.
1069 /// @param[out] triangleCount Valid pointer to int that gets the number of triangles.
1070 /// @param[in] submeshIndex Zero based index to a submesh of 'mesh'. Also see #d4mesh_getSubmeshCount.
1071 /// @return #d4ok, #d4error_InvalidArgument
1072 D4LIB_API int d4mesh_getTriangleCount(d4mesh_ptr mesh, int* triangleCount, int submeshIndex);
1073 
1074 /// Set the number of triangles for a given submesh of a mesh.
1075 /// @param[in] mesh Valid pointer to a mesh object.
1076 /// @param[in] triangleCount New triangle count.
1077 /// @param[in] submeshIndex Zero based index to a submesh of 'mesh'. Also see #d4mesh_getSubmeshCount.
1078 /// @return #d4ok, #d4error_InvalidArgument
1079 D4LIB_API int d4mesh_setTriangleCount(d4mesh_ptr mesh, int triangleCount, int submeshIndex);
1080 
1081 /// Get the name of a mesh.
1082 /// @param[in] mesh Valid pointer to a mesh object.
1083 /// @param[out] name Valid pointer to string that gets the name.
1084 /// @param[in] maxLength Maximum length of a string that fits into 'name'.
1085 /// @return #d4ok, #d4error_InvalidArgument
1086 D4LIB_API int d4mesh_getName(d4mesh_ptr mesh, char* name, d4size maxLength);
1087 
1088 /// Set the name of a mesh.
1089 /// @param[in] mesh Valid pointer to a mesh object.
1090 /// @param[out] name Valid pointer to a string.
1091 /// @return #d4ok, #d4error_InvalidArgument
1092 D4LIB_API int d4mesh_setName(d4mesh_ptr mesh, const char* name);
1093 
1094 /// Get the texture of a mesh.
1095 /// Textures are optional.
1096 /// @param[in] mesh Valid pointer to a mesh object.
1097 /// @param[in] submeshIndex Zero based index to a submesh of 'mesh'. Also see #d4mesh_getSubmeshCount.
1098 /// @return Pointer to an image or NULL. Reference count is incremented.
1099 D4LIB_API d4img_ptr d4mesh_getTexture(d4mesh_ptr mesh, int submeshIndex);
1100 
1101 /// Set the texture of a mesh.
1102 /// Textures are optional.
1103 /// @param[in,out] mesh Valid pointer to a mesh object.
1104 /// @param[in,out] image Valid pointer to an image. Reference count is incremented, no copy is made.
1105 /// @param[in] submeshIndex Zero based index to a submesh of 'mesh'. Also see #d4mesh_getSubmeshCount.
1106 /// @return #d4ok, #d4error_InvalidArgument
1107 D4LIB_API int d4mesh_setTexture(d4mesh_ptr mesh, d4img_ptr image, int submeshIndex);
1108 
1109 /// Has 'mesh' a texture?
1110 /// @param[in] mesh Valid pointer to a mesh.
1111 /// @param[out] hasTexture Valid pointer to a bool that gets the answer.
1112 /// @param[in] submeshIndex Zero based index to a submesh of 'mesh'. Also see #d4mesh_getSubmeshCount.
1113 /// @return #d4ok, #d4error_InvalidArgument
1114 D4LIB_API int d4mesh_hasTexture(d4mesh_ptr mesh, bool* hasTexture, int submeshIndex);
1115 
1116 /// Get the position and orientation (pose) of a mesh.
1117 /// The pose is represented as a homogenenous transformation matrix:
1118 /// @code
1119 /// | nx ox ax px | = | d0 d4 d8 d12 |
1120 /// | ny oy ay py | = | d1 d5 d9 d13 |
1121 /// | nz oz az pz | = | d2 d6 d10 d14 |
1122 /// | 0 0 0 1 | = | d3 d7 d11 d15 |
1123 ///
1124 /// world_T_local = (d0, d1, d2, d3, d4, d5, d6, d7, d8, d9, d10, d11, d12, d13, d14, d15)
1125 /// @endcode
1126 ///
1127 /// Some notes:
1128 /// - The 3D vector (nx, ny, nz) is the x axis of the local coordinate system with respect to world coordinates.
1129 /// - The 3D vector (ox, oy, oz) is the y axis of the local coordinate system with respect to world coordinates.
1130 /// - The 3D vector (ax, ay, az) is the z axis of the local coordinate system with respect to world coordinates.
1131 /// - The 3D vector (px, py, pz) is the position of the mesh with respect to world coordinates.
1132 ///
1133 /// This matrix transforms local coordinates into world coordinates:
1134 /// @code
1135 /// (wPx, wPy, wPz, 1)^T = world_T_local * (lPx, lPy, lPz, 1)^T
1136 /// @endcode
1137 ///
1138 /// @param[in] mesh Valid pointer to a mesh.
1139 /// @param[out] world_T_local Valid pointer to an array of 16 double values.
1140 /// @return #d4ok, #d4error_InvalidArgument
1141 D4LIB_API int d4mesh_getPose(d4mesh_ptr mesh, double world_T_local[16]);
1142 
1143 /// Set the position and orientation (pose) of a mesh.
1144 /// The pose is represented as a homogenenous transformation matrix.
1145 /// @see #d4mesh_getPose for a more detailed description.
1146 /// @param[in,out] mesh Valid pointer to a mesh.
1147 /// @param[in] world_T_local Valid pointer to an array of 16 double values describing the transformation matrix.
1148 /// @return #d4ok, #d4error_InvalidArgument
1149 D4LIB_API int d4mesh_setPose(d4mesh_ptr mesh, const double world_T_local[16]);
1150 
1151 /// @}
1152 
1153 
1154 //=============================================================================
1155 /// @name Mesh: Filtering
1156 /// Filtering of meshes.
1157 ///
1158 /// Notes:
1159 /// - Smoothing: #d4mesh_smoothAverage
1160 /// - Mesh simplification: #d4mesh_reduceMeshDensity
1161 ///
1162 /// @{
1163 //=============================================================================
1164 
1165 /// Index to define a vertex in a submesh
1167 {
1168  int submeshIndex; ///< which submesh contains the vertex
1169  int vertexIndex; ///< vertex index in that submesh
1170 };
1171 
1172 /// Smooth mesh using an average filter.
1173 /// @param[in,out] mesh Valid pointer to a mesh.
1174 /// @param[in] smoothing Number of smoothing steps.
1175 /// @return #d4ok, #d4error_InvalidArgument
1176 D4LIB_API int d4mesh_smoothAverage(d4mesh_ptr mesh, int smoothing);
1177 
1178 /// Reduce the vertex/triangle density of mesh (simplification).
1179 /// @param[in,out] mesh Valid pointer to a mesh.
1180 /// @param[in] factor 0.5f for retaining 50% of all triangles, 0.1f for 10% triangles...
1181 /// @return #d4ok, #d4error_InvalidArgument
1182 D4LIB_API int d4mesh_reduceMeshDensity(d4mesh_ptr mesh, float factor);
1183 
1184 /// Remove selected vertices. Referenced triangles are also removed.
1185 /// A vertex i is selected if selected[i]==true.
1186 /// @param[in,out] mesh Valid pointer to a mesh.
1187 /// @param[in] selectedVertices Valid pointer to an array of indices to vertices which should be removed.
1188 /// @param[in] selectedVerticesCount Number of indices in 'selectedVertices'.
1189 /// @return #d4ok, #d4error_InvalidArgument
1190 D4LIB_API int d4mesh_removeSelectedVertices(d4mesh_ptr mesh, const d4mesh_SubmeshVertexIndex* selectedVertices, int selectedVerticesCount);
1191 
1192 /// Invert orientation of all triangles in given mesh.
1193 /// @param[in,out] mesh Valid pointer to a mesh.
1194 /// @return #d4ok, #d4error_InvalidArgument
1195 D4LIB_API int d4mesh_invertTriangleOrientation(d4mesh_ptr mesh);
1196 
1197 /// Remove any vertex i that when projected into a virtual camera view has a mask value of 'mask[i]==true'.
1198 /// Vertices outside view or with a mask value fo 'mask[i]==false' are not removed.
1199 /// If a vertex is removed, its referenced triangles are also removed.
1200 /// The virtual camera is described by a perspective camera model:
1201 /// - Central z axis goes through center of image --> Center is at (width/2, height/2).
1202 /// - Image plane has a size in x-direction of 'width and a size of 'height' in y-direction.
1203 /// - x-axis is from left to right and y-axis from top to down (with respect to image).
1204 /// - Camera looks along the positive z-axis.
1205 /// - Visible points are on positive side of z-axis.
1206 /// - Focal length is given by 'f'.
1207 /// - Pose of the camera with respect to world coordinates is given by 'world_T_cam'.
1208 ///
1209 /// @param[in,out] meshes Valid pointer to an array of valid mesh pointers.
1210 /// @param[in] meshCount Number of meshes referenced by 'meshes'.
1211 /// @param[in] mask Valid pointer to an boolean array of size 'width*height'. True: Vertex should be removed. False: Keep vertex.
1212 /// @param[in] width Width of the mask image [pixel]. Has to be > 0.
1213 /// @param[in] height Height of the mask image [pixel]. Has to be > 0.
1214 /// @param[in] f Focal length (distance of image plane to origin camera coordinate system).
1215 /// @param[in] world_T_cam Position and orientation (pose) of the camera with respect to world coordinates.
1216 /// The pose is represented as a homogenenous transformation matrix.
1217 /// See #d4mesh_getPose for more information.
1218 /// @param[in] onlyVisible Remove only visible vertices? WARNING: At the moment, only 'onlyVisible==false' is supported.
1219 /// @return #d4ok, #d4error_InvalidArgument
1220 D4LIB_API int d4mesh_removeVerticesByVirtualCamMask(d4mesh_ptr* meshes, int meshCount, const unsigned char* mask, int width, int height, double f, const double world_T_cam[16], bool onlyVisible);
1221 
1222 // Selects all vertices that are on the negative half space defined by a plane.
1223 // The plane is given by a 3D point on the plane 'pointOnPlane' and 3D vector 'planeNormal' orthogonal to the plane.
1224 // @param[in] mesh Valid pointer to a mesh.
1225 // @param[in,out] selected Valid pointer to an array of bools with minimum size equal to
1226 // @param[in] clearSelection Clear previous selection?
1227 // @param[in] pointOnPlane 3D point (x,y,z) w.r.t. to local coordinate system.
1228 // @param[in] planeNormal 3D vector (x,y,z) orthgonal to the plane w.r.t. to local coordinate system.
1229 //D4LIB_API int d4mesh_selectVerticesNegativeHalfSpace(d4mesh_ptr mesh, bool* selected, bool clearSelection, const float pointOnPlane[3], const float planeNormal[3]);
1230 
1231 /// @}
1232 
1233 
1234 //=============================================================================
1235 /// @name Mesh: Alignment
1236 /// Alignment (registration) of meshes.
1237 ///
1238 /// - Pairwise alignment: #d4mesh_alignPairCoarse and #d4mesh_alignPairFine
1239 /// - Global alignment: #d4mesh_alignGlobalFine
1240 ///
1241 /// @{
1242 //=============================================================================
1243 
1244 /// Provides user knowledge about the motion between two scans.
1245 /// In most cases the motion can be described by a simple rotation around an axis,
1246 /// where the pitch along the (motion=rotation) axis is zero.
1248 {
1249  bool angleKnown; ///< Is rotation 'angle' around motion axis known?.
1250  bool axisDirKnown; ///< Is direction vector 'axisDir' of motion axis is known?
1251  double angleDeg; ///< Angle of rotation in degrees.
1252  double angleToleranceDeg; ///< Tolerance of angleDeg in degrees.
1253  double axisDir[3]; ///< 3D direction vector (x,y,z) of motion axis w.r.t. world coordinates.
1254 };
1255 
1256 
1257 /// A list of poses (4*4 matrices) plus tolerances for translation and rotation.
1259 {
1260  int numPoses; ///< Number of poses (each 4*4 doubles) specified in poses
1261  double *poses; ///< List of poses (each 4*4 doubles) (nullptr for none)
1262  double toleranceTrans; ///< Translational tolerance [mm] of the poses (0 to deactivate).
1263  double toleranceDeg; ///< Rotational tolerance [degree] of the poses (0 to deactivate).
1264 };
1265 
1266 
1267 /// Parameter set for Coarse Alignment, see #d4mesh_alignPairCoarse.
1269 {
1270  int texturePercentage; ///< Percentage of texture influence on alignment (0-99). Only used if value is higher than 0.
1271  d4mesh_MotionInfo motionInfo; ///< Additional information about motion between the two meshes. See #d4mesh_MotionInfo for more details.
1272  float qualityFactor; ///< 1 is recommended. Larger values like 5 or 10 may create better results for symmetric objects, but increase computation time. Lower values like 0.01 to 0.1 decrease computation time, but may result in wrong alignment results.
1273 
1274  // Contact Pairs:
1275  d4size numContactVertices1; ///< Number of contact vertices on mesh1, specified in 'contactVertices1'
1276  int *contactVertices1; ///< Array of contact vertex indices on mesh1, or NULL
1277  d4size numContactVertices2; ///< Number of contact vertices on mesh2, specified in 'contactVertices2'
1278  int *contactVertices2; ///< Array of contact vertex indices on mesh2, or NULL
1279 
1280  // Blacklisting/Whitelisting:
1281  d4mesh_PosesWithTolerances blacklist1; ///< Blacklist of (rough) poses that mesh1 may not be moved to (can be empty)
1282  d4mesh_PosesWithTolerances whitelist1; ///< Whitelist of (rough) poses that mesh1 must be moved to (can be empty)
1283 };
1284 
1285 
1286 /// Parameter set for Fine Alignment, see #d4mesh_alignPairFine.
1288 {
1289  int texturePercentage; ///< Percentage of texture influence on alignment. Only used, if value is higher than 0.
1290  int maxNumIterations; ///< Number of iterations to run maximally (recommended: 100)
1291  double maxTranslation; ///< Maximum allowed drift[mm] of mesh center (0 = no limit). Alignment will stop when this limit is reached.
1292  double maxRot_deg; ///< Maximum allowed rotation[deg] of mesh in degree (0 = no limit). Alignment will stop when this limit is reached.
1293 };
1294 
1295 
1296 /// Parameter set for Global Fine Alignment, see #d4mesh_alignGlobalFine.
1298 {
1299  int texturePercentage; ///< Percentage of texture influence on alignment. Only used if value is higher than 0.
1300  int numIterations; ///< Number of iterations to run (recommended: 20)
1301  double maxTranslation; ///< Maximum allowed drift[mm] of any mesh center (0 = no limit). Global Fine Alignment will not move any scan more than this.
1302  double maxRot_deg; ///< Maximum allowed rotation[deg] of any mesh in degree (0 = no limit). Global Fine Alignment will not rotate any scan more than this.
1303 };
1304 
1305 /// Align 'mesh1' to 'mesh2' coarsely.
1306 /// @param[in,out] mesh1 Valid pointer to mesh that is moved (aligned).
1307 /// @param[in] mesh2 Valid pointer to mesh.
1308 /// @param[out] quality Optional pointer to double that gets quality value in range [-1,1]=[bad,good].
1309 /// @param[in] params Valid pointer to alignment parameter set. See #d4mesh_CoarseAlignParams.
1310 /// @return #d4ok, #d4error_InvalidArgument, #d4error_Fail
1311 D4LIB_API int d4mesh_alignPairCoarse(d4mesh_ptr mesh1, d4mesh_ptr mesh2, double* quality, const d4mesh_CoarseAlignParams* params);
1312 
1313 /// Align 'mesh1' to 'mesh2' fine.
1314 /// @param[in,out] mesh1 Valid pointer to mesh that is moved (aligned).
1315 /// @param[in] mesh2 Valid pointer to mesh.
1316 /// @param[out] quality Optional pointer to double that gets quality value in range [-1,1]=[bad,good].
1317 /// @param[in] params Valid pointer to alignment parameter set. See #d4mesh_FineAlignParams.
1318 /// @return #d4ok, #d4error_InvalidArgument,# d4error_Fail
1319 D4LIB_API int d4mesh_alignPairFine(d4mesh_ptr mesh1, d4mesh_ptr mesh2, double* quality, const d4mesh_FineAlignParams* params);
1320 
1321 /// Align meshes globally fine.
1322 /// @param[in,out] meshes Valid pointer to an array of valid mesh pointers.
1323 /// @param[in] meshCount Number of meshes referenced by 'meshes'.
1324 /// @param[in] params Valid pointer to alignment parameter set. See #d4mesh_GlobalFineAlignParams.
1325 /// @return #d4ok, #d4error_InvalidArgument, #d4error_Fail
1326 D4LIB_API int d4mesh_alignGlobalFine(d4mesh_ptr* meshes, int meshCount, const d4mesh_GlobalFineAlignParams* params);
1327 
1328 /// @}
1329 
1330 
1331 //=============================================================================
1332 /// @name Mesh: Fusion
1333 /// Fusion of meshes and textures into one mesh and one texture.
1334 ///
1335 /// Notes:
1336 /// - Geometric data is fused with #d4mesh_fuseGeometry
1337 /// - Texture data is fused with #d4mesh_fuseTexture
1338 ///
1339 /// @{
1340 //=============================================================================
1341 
1342 /// Fuse multiple meshes into one triangular mesh.
1343 /// @param[out] fusedGeo Valid pointer to fusion result.
1344 /// @param[in] meshes Valid pointer to an array of valid mesh pointers.
1345 /// @param[in] meshCount Number of meshes referenced by 'meshes'.
1346 /// @param[in] resolution Limits the maximum resolution and thus the required memory usage.
1347 /// @param[in] holeSizeThresRel Holes, which have a smaller area than holeSizeThresRel * size of original data surface, will be closed. 0 = open all holes. 1 = close all holes.
1348 /// @param[in] sharpness Fusion sharpness in [-3,+5]. Negative values for smoothing. Default is 1.
1349 /// @return #d4ok, #d4error_InvalidArgument, #d4error_Fail
1350 D4LIB_API int d4mesh_fuseGeometry(d4mesh_ptr fusedGeo, d4mesh_ptr* meshes, int meshCount, int resolution, float holeSizeThresRel, int sharpness);
1351 
1352 /// Converts a metric resolution value into a resolution value required by #d4mesh_fuseGeometry.
1353 /// It uses the maximum bounding box length of all 'meshes'.
1354 /// @param[in] meshes Valid pointer to an array of valid mesh pointers.
1355 /// @param[in] meshCount Number of meshes referenced by 'meshes'.
1356 /// @param[out] resolution Valid pointer to resolution value that can be used in #d4mesh_fuseGeometry.
1357 /// @param[in] metricResolution Smallest possible element size in units (e.g. 0.1 [mm]).
1358 /// @return #d4ok, #d4error_InvalidArgument, #d4error_Fail
1359 D4LIB_API int d4mesh_getFuseGeometryResolution(d4mesh_ptr* meshes, int meshCount, int* resolution, double metricResolution);
1360 
1361 /// Fuse textures referenced by 'meshes' into one texture of 'fusedGeo'.
1362 /// @param[in,out] fusedGeo Valid pointer to a mesh.
1363 /// @param[in] meshes Valid pointer to an array of valid mesh pointers.
1364 /// @param[in] meshCount Number of meshes referenced by 'meshes'.
1365 /// @return #d4ok, #d4error_InvalidArgument, #d4error_Fail
1366 D4LIB_API int d4mesh_fuseTexture(d4mesh_ptr fusedGeo, d4mesh_ptr* meshes, int meshCount);
1367 
1368 /// @}
1369 
1370 
1371 //=============================================================================
1372 /// @name Mesh: Import / Export
1373 /// Import and export of meshes. See functions for supported formats.
1374 ///
1375 /// Notes:
1376 /// - Import: #d4mesh_import
1377 /// - Export: #d4mesh_export
1378 ///
1379 /// @{
1380 //=============================================================================
1381 
1382 /// Export 'mesh' to file.
1383 /// Supported formats: OBJ, STL, PLY
1384 /// @warning Texture is only exported, if there is only one submesh (see #d4mesh_getSubmeshCount).
1385 /// @param[in] mesh Valid pointer to mesh.
1386 /// @param[in] filename Valid pointer to string with filename.
1387 /// @return #d4ok, #d4error_InvalidArgument, #d4error_InvalidPath, #d4error_FileNotFound, #d4error_NoAccess
1388 D4LIB_API int d4mesh_export(d4mesh_ptr mesh, const char* filename);
1389 
1390 /// Import 'mesh' from file.
1391 /// Supported formats: OBJ
1392 /// @param[out] mesh Valid pointer to mesh.
1393 /// @param[in] filename Valid pointer to string with filename.
1394 /// @return #d4ok, #d4error_InvalidArgument, #d4error_InvalidPath, #d4error_FileNotFound, #d4error_NoAccess
1395 D4LIB_API int d4mesh_import(d4mesh_ptr mesh, const char* filename);
1396 
1397 /// @}
1398 
1399 /// @} d4lib
1400 /// @} LowLevelGroup
1401 
1402 
1403 #ifdef __cplusplus
1404 } // extern "C"
1405 #endif
1406 
1407 
1408 #endif // DAVID_SDK_D4LIB_H