DAVID4 SDK  1.8.7
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
IStructuredLightScanner.h
1 //=============================================================================
2 // See License in Related Pages
3 //=============================================================================
4 
5 #pragma once
6 
7 #ifndef DAVID_SDK_I_STRUCTURED_LIGHT_SCANNER_H
8 #define DAVID_SDK_I_STRUCTURED_LIGHT_SCANNER_H
9 
10 #include "davidSDK/Common.h"
11 #include <vector>
12 
13 namespace david {
14 
15 //*****************************************************************************
16 /// @addtogroup InterfaceGroup
17 /// @{
18 /// @defgroup StructuredLightScannerGroup Structured Light Scanning
19 /// Functions and types related to 'Structured Light Scanning'.
20 /// @{
21 //*****************************************************************************
22 
23 //=============================================================================
24 // ImageFormat
25 //=============================================================================
26 
27 /// Describes the image format.
29 {
30  int width; ///< Width of the image.
31  int height; ///< Height of the image.
32  PixelFormat pixelFormat; ///< Pixel format.
33  double fps; ///< Frames per second.
34 
35  /// Constructor.
36  ///
37  /// @param[in] width Sets the image width.
38  /// @param[in] height Sets the image height.
39  /// @param[in] fps Sets the frames per second.
40  /// @param[in] pixelFormat Sets the pixel format.
42 };
43 
44 
45 //=============================================================================
46 // CameraPropertyTarget
47 //=============================================================================
48 
49 /// Defines different types of usage for camera properties.
50 /// Camera properties are distinguished by their name and their usage (e.g. usage in scanning or texturing).
52 {
53  CamPropsForAll, ///< Camera property should be used for all algorithms.
54  CamPropsForScanning, ///< Camera property should be used for scanning only.
55  CamPropsForTexturing, ///< Camera property should be used for texturing only.
56 };
57 
58 
59 //=============================================================================
60 // Orientation
61 //=============================================================================
62 
63 /// Defines orientations for hardware setup.
65 {
66  HorizontalOrientation, ///< Horizontal setup. Projector and camera are next to each other.
67  VerticalOrientation, ///< Vertical setup. Projector and camera are above each other.
68  BothOrientations, ///< Diagonal setup. Projector and camera are located diagonally.
69 };
70 
71 
72 //=============================================================================
73 // PatternColor
74 //=============================================================================
75 
76 /// Defines pattern colors for SL.
78 {
79  White,
80  Red,
81  Green,
82  Blue,
83 };
84 
85 
86 //=============================================================================
87 // PatternPixelFormat
88 //=============================================================================
89 
90 /// Describes available pixel formats for pattern images.
91 /// Can be converted to #PixelFormat.
93 {
94  PPF_Y800 = Y800, ///< Standard 8bit grayscale format.
95  PPF_RGB24 = RGB24, ///< Red, green, and blue 8bit color components for each pixel. Byte 0=8bit blue; Byte 1=8bit green; Byte 2=8bit red.
96 };
97 
98 
99 //=============================================================================
100 // CapturedPixelFormat
101 //=============================================================================
102 
103 /// Describes available pixel formats for captured images that are processed by SLS module.
104 /// Can be converted to #PixelFormat.
106 {
107  CPF_Y800 = Y800, ///< Standard 8bit grayscale format.
108 };
109 
110 
111 //=============================================================================
112 // CodedLightPhaseShiftParams
113 //=============================================================================
114 
115 /// Defines parameters used in structured light mode 'coded light + phase shift' ('cl+ps').
117 {
118  Optional<int> frequencies; ///< Number of frequencies. 0==auto (but not available in DLL mode).
119  Optional<bool> inverse; ///< Use inverse Coded Light patterns. Doubles the amount of Coded Light patterns.
120  Optional<int> shifts; ///< Number of sine patterns (Phase Shift shifts).
121  Optional<Orientation> orientation; ///< Defines orientation of hardware setup.
122  Optional<PatternColor> color; ///< Color of the projected patterns.
123  Optional<int> brightness; ///< Brightness of the projected patterns [0-255]. Default is 255.
124  Optional<int> noiseReduction; ///< Amount of noise reduction.
125 };
126 
127 
128 //=============================================================================
129 // ResultFilteringParams
130 //=============================================================================
131 
132 /// Defines parameters used for result filtering.
134 {
135  Optional<double> qualityCheck; ///< Quality threshold for 3D data [0,1].
136  Optional<bool> backgroundRemovalEnabled; ///< Background Removal enabled (true/false).
137  Optional<double> backgroundRemovalEpsilon; ///< Epsilon for Background Removal.
138  Optional<double> outlierRemoval; ///< Outlier filter [0,1]
139 };
140 
141 
142 //=============================================================================
143 // CalibPoint
144 //=============================================================================
145 
146 /// Point correspondence used for calibration.
147 /// 'worldRefPos3d' is projected into camera image at 'projectedPos2d'.
148 /// The error between 'projectedPos2d' and measured marker point 'measuredPos2d' should be minimal.
150 {
151  double worldRefPos3d[3]; ///< Reference 3d point (x,y,z) with respect to world coordinates.
152  double measuredPos2d[2]; ///< Measured 2d image point with respect to image coordinates.
153  double projectedPos2d[2]; ///< Image coordinates of 'worldRefPos3d' projected into image using calibrated model parameters.
154 };
155 
156 
157 /// Defines a plane in 3D.
158 struct Plane
159 {
160  double pos[3]; ///< One point on the plane (X,Y,Z)
161  double normal[3]; ///< Normal vector of the plane (X,Y,Z)
162 };
163 
164 //=============================================================================
165 // IStructuredLightScanner
166 //=============================================================================
167 
168 /// Interface class for 'Structured Light Scanning'.
169 ///
170 /// Example:
171 /// @include SimpleStructuredLightScanner.cpp
173 {
174 public:
175  /// Destructor.
177 
178  //-------------------------------------------------------------------------
179  /// @name Internal camera and projector interface
180  /// @{
181  //-------------------------------------------------------------------------
182 
183  /// Set the new screen ID. The value 0 switches the projection off.
184  /// @param[in] screenID ID of the screen used for displaying structured light patterns, or 0 for OFF.
185  virtual void SetScreenID(int screenID) = 0;
186 
187  /// Returns a list of available cameras.
188  /// @return The list of names.
189  virtual std::vector<std::string> GetAvailableCameraNames() = 0;
190 
191  /// Select a new camera.
192  ///
193  /// Example:
194  /// @code
195  /// SelectCamera("DAVID-CAM-3-M (8F6DEE1E)");
196  /// @endcode
197  ///
198  /// @param[in] cameraName Name of the camera.
199  /// @param[in] imageFormat Format of the camera image.
200  /// @exception david::Error_DeviceNotAvailable (david::FunctionException) Selected camera is not available.
201  /// @exception david::Error_FormatNotAvailable (david::FunctionException) Selected camera image format is invalid.
202  virtual void SelectCamera(const std::string& cameraName, const ImageFormat& imageFormat = ImageFormat()) = 0;
203 
204  /// Check state of camera.
205  /// @return False, if camera is not working correctly or camera is not connected.
206  /// @return True, if camera is connected and is working correctly.
207  virtual bool CheckCamera() = 0;
208 
209  /// Set the camera property 'propertyName'.
210  ///
211  /// Here are some important property names:
212  /// - exposure (should be 1/60 s, 1/30 s, or 1/15 s for most cases)
213  /// - gain (should be as low as possible)
214  /// - brightness
215  /// - sharpness
216  /// - gamma
217  /// - ....
218  ///
219  /// @note Not all cameras support all properties. See also #GetCameraPropertyNames.
220  ///
221  /// @param[in] propertyName Name of property.
222  /// @param[in] value New value of the property.
223  /// @param[in] camPropsUsage For which algorithm should the camera property be set? See david::CamPropsSelect.
224  /// @exception david::Error_DeviceNotAvailable (david::FunctionException) Selected camera is not available.
225  /// @exception david::Error_InvalidArgument (david::FunctionException) Invalid property or property is not available.
226  virtual void SetCameraProperty(const std::string& propertyName, double value, enum CamPropsUsage camPropsUsage = CamPropsForAll) = 0;
227 
228  /// Get the camera property 'propertyName'.
229  /// @param[in] propertyName Name of property.
230  /// @param[in] camPropsUsage For which algorithm should the camera property be queried? See david::CamPropsSelect. CamPropsForAll is not allowed here.
231  /// @return Value of the camera property.
232  /// @exception david::Error_DeviceNotAvailable (david::FunctionException) Selected camera is not available.
233  /// @exception david::Error_InvalidArgument (david::FunctionException) Invalid property or property is not available.
234  virtual double GetCameraProperty(const std::string& propertyName, enum CamPropsUsage camPropsUsage = CamPropsForScanning) = 0;
235 
236  /// Get a list of camera property names.
237  /// @param[in] onlyAvailable List only available camera properties?
238  /// @return Array of camera property names.
239  virtual std::vector<std::string> GetCameraPropertyNames(bool onlyAvailable) = 0;
240 
241  /// Get the current grayscale live image from the camera.
242  /// @param[out] pixelValues 8bit gray scale pixel values are writting into this buffer.
243  /// @param[out] width Width of the image.
244  /// @param[out] height Height of the image.
245  /// @exception david::Error_NoLiveImage (david::FunctionException) Live image is not available.
246  virtual void GetLiveImage(std::vector<uint8_t>& pixelValues, int& width, int& height) = 0;
247 
248  /// @}
249  //-------------------------------------------------------------------------
250  /// @name External camera and projector interface
251  /// @{
252  //-------------------------------------------------------------------------
253 
254  /// Selects a sequence of image files as "virtual camera". All images must be located in the same directory.
255  /// The image file names are chosen automatically:
256  /// <table borders="0">
257  /// <tr> <td>Image for camera calibration</td> <td>File name must contain "cam_calib"</td> </tr>
258  /// <tr> <td>Pattern images</td> <td>File names must contain "image" and be sorted alphabetically.</td> </tr>
259  /// <tr> <td>Texture image</td> <td>File name must contain "texture"</td> </tr>
260  /// </table>
261  ///
262  /// @param[in] directory Path to the image files.
263  /// @exception david::Error_InvalidPath (david::FunctionException) Path invalid.
264  /// @exception david::Error_DirectoryNotFound (david::FunctionException) Directory does not exist.
265  virtual void SelectImageSequence(const std::string& directory) = 0;
266 
267  /// Get the current number of pattern for the complete sequence.
268  /// @return Number of pattern to be projected.
269  virtual int GetPatternCount() = 0;
270 
271  /// Get the pattern image with the zero based index 'patternIndex'.
272  /// @param[out] data Pixel values are written to this buffer.
273  /// - #PPF_Y800: Size has to be width*height bytes.
274  /// - #PPF_RGB24: Size has to be width*height*3 bytes.
275  /// @param[in] width Requested width of pattern image.
276  /// @param[in] height Requested height of pattern image.
277  /// @param[in] pixelFormat Supported pixel formats for pattern images.
278  /// @param[in] patternIndex Zero based index of pattern image. See also #GetPatternCount.
279  virtual void GetPatternImage(uint8_t* data, int width, int height, PatternPixelFormat pixelFormat, int patternIndex) = 0;
280 
281  /// Set the captured image for given pattern with zero based index 'patternIndex'.
282  /// @param[in] data Valid pointer to buffer with pixel values.
283  /// - CPF_Y800: Size of 'data' has to be width*height.
284  /// @param[in] width Width of captured image.
285  /// @param[in] height Height of captured image.
286  /// @param[in] pixelFormat Pixel format of captured image.
287  /// @param[in] patternIndex Zero based index of pattern image. See also #GetPatternCount.
288  virtual void SetCapturedImage(const uint8_t* data, int width, int height, CapturedPixelFormat pixelFormat, int patternIndex) = 0;
289 
290  /// Set the texture image analog to #SetCapturedImage.
291  /// @param[in] data Valid pointer to buffer with pixel values. Size of 'data' has to be equal to GetImageSize(width, height, pixelFormat).
292  /// @param[in] width Width of texture image.
293  /// @param[in] height Height of texture image.
294  /// @param[in] pixelFormat Pixel format of captured image.
295  virtual void SetTextureImage(const uint8_t* data, int width, int height, PixelFormat pixelFormat) = 0;
296 
297  /// @}
298  //-------------------------------------------------------------------------
299  /// @name Calibration
300  /// @{
301  //-------------------------------------------------------------------------
302 
303  /// Import camera and projector calibration from XML files.
304  /// @param[in] camCalibFilename Filename of the camera calibration to be imported from.
305  /// @param[in] projectorCalibFilename Filename of the projector calibration to be imported from.
306  /// @exception david::Error_CameraCalibration (david::FunctionException) Could not read camera calibration file.
307  /// @exception david::Error_ProjectorCalibration (david::FunctionException) Could not read projector calibration file.
308  virtual void ImportCalibration(const std::string& camCalibFilename, const std::string& projectorCalibFilename) = 0;
309 
310  /// Export camera and projector calibration to XML files.
311  /// @param[in] camCalibFilename Filename of the camera calibration to be exported to.
312  /// @param[in] projectorCalibFilename Filename of the projector calibration to be exported to.
313  /// @exception david::Error_NotCalibrated (david::FunctionException) Scanner is not calibrated.
314  virtual void ExportCalibration(const std::string& camCalibFilename, const std::string& projectorCalibFilename) = 0;
315 
316  /// Change resolution of image format used camera calibration.
317  /// @warning The aspect ratio is not allowed to change.
318  /// @param[in] newWidth New camera image width.
319  /// @param[in] newHeight New camera image height.
320  /// @exception david::Error_NotCalibrated (david::FunctionException) Camera is not calibrated.
321  /// @exception david::Error_InvalidFormat (david::FunctionException) Requested image resolution not supported.
322  virtual void ChangeCameraCalibrationResolution(int newWidth, int newHeight) = 0;
323 
324  /// Trigger automatic calibration of the Structured Light Scanner.
325  /// The function returns when calibration is finished or an error occurred.
326  /// @param[in] scale Scale of the calibration patterns. Typically in mm.
327  /// @return If calibration is successful: Array of correspondences used for calibration. Empty array otherwise.
328  /// @exception david::Error_CameraCalibration (david::FunctionException) Camera calibration failed.
329  /// @exception david::Error_ProjectorCalibration (david::FunctionException) Projector calibration failed.
330  virtual std::vector<CalibPoint> Calibrate(double scale) = 0;
331 
332  /// @}
333  //-------------------------------------------------------------------------
334  /// @name Calibration (static functions)
335  /// @{
336  //-------------------------------------------------------------------------
337 
338  /// Helper function for computing the calibration error given an array of calibration correspondences.
339  /// @param[out] maxDelta Maximum Euclidean distance [pixel] between any corresponding 'measuredPos2d' and 'projectedPos2d'.
340  /// @param[out] rmsError Total root mean square error.
341  /// @param[in] calibPoints Array of calibration points. See david::CalibPoint.
342  static void GetCalibrationError(double& maxDelta, double& rmsError, const std::vector<CalibPoint>& calibPoints);
343 
344 
345  /// @}
346  //-------------------------------------------------------------------------
347  /// @name Scanning
348  /// @{
349  //-------------------------------------------------------------------------
350 
351  /// Select scan mode Coded Light + Phase Shift (standard DAVID4 mode) and sets the parameters.
352  /// Missing parameters will remain unchanged.
353  /// @param[in] params Parameters for this structured light mode.
354  virtual void SetCodedLightPhaseShiftMode(const CodedLightPhaseShiftParams& params) = 0;
355 
356  /// Get current SLS params for Coded Light and Phase Shift.
357  /// @return Parameters for this structured light mode. See david::CodedLightPhaseShiftParams.
359 
360  /// Set the result filtering parameters for SL scans.
361  /// @param[in] params Parameters for result filtering.
362  virtual void SetResultFiltering(const ResultFilteringParams& params) = 0;
363 
364  /// Get the result filtering parameters for SL scans.
365  /// @return Current parameters for result filtering.
367 
368  /// Trigger a Structured Light Scan.
369  /// The function computes a 3D scan from a sequence of captured pattern images.
370  /// The captured images can be provided in two ways:
371  /// 1. Camera and projector are selected (#SelectCamera and #SetScreenID): Selected camera and projector are used to capture a new sequence.
372  /// 2. Captured images have been provided via #SelectImageSequence or #SetCapturedImage + #SetTextureImage.
373  ///
374  /// The function returns when scanning is finished or an error occurred.
375  /// @param[in] grabTexture Also grab a texture with the scan (default: false)
376  /// @param[in] setAsBackground Define this scan as background (for Background Removal in ResultFiltering) (default: false)
377  /// @return Number of triangulated 3D points.
378  /// @exception david::Error_NotCalibrated (david::FunctionException) Cannot scan because scanner is not calibrated.
379  virtual int Scan(bool grabTexture=false, bool setAsBackground=false) = 0;
380 
381  /// Grab a new texture.
382  virtual void GrabTexture() = 0;
383 
384  /// Execute an auto white balancing procedure.
385  virtual void AutoWhiteBalance() = 0;
386 
387  /// Add the current scan to 'Shape Fusion' module.
388  /// @return ID of the mesh.
389  /// @exception david::Error_MissingObject (david::FunctionException) No scan data at hand.
390  virtual int AddScanToShapeFusion() = 0;
391 
392  /// Export the current scan as a triangular mesh.
393  /// See documentation of DAVID software for supported file formats.
394  ///
395  /// @warning File paths like "c:\\meshes\\myobject.obj" are interpreted as files located on the server.
396  /// For files located on the client you have to use a shared network path like "\\\\mycomputer\\meshes\\myobject.obj".
397  ///
398  /// @param[in] filename Filename of the mesh to be exported.
399  /// @exception david::Error_NoAccess (david::FunctionException) No access to path.</td> </tr>
400  /// @exception david::Error_InvalidPath (david::FunctionException) Export path invalid.</td> </tr>
401  /// @exception david::Error_DirectoryNotFound (david::FunctionException) Export target directory does not exist.</td> </tr>
402  /// @exception david::Error_MissingFilename (david::FunctionException) Export path misses file name.</td> </tr>
403  /// @exception david::Error_InvalidMeshId (david::FunctionException) Specified meshID does not exist.</td> </tr>
404  virtual void ExportMesh(const std::string& filename) = 0;
405 
406  /// @}
407  //-------------------------------------------------------------------------
408  /// @name Background removal
409  /// @{
410  //-------------------------------------------------------------------------
411 
412  /// Export the current background as a depth map file (.PFM).
413  ///
414  /// @param[in] filename Filename of the depth map to be exported.
415  virtual void ExportBackgroundDepthmap(const std::string& filename) = 0;
416 
417  /// Import background from a depth map file (.PFM).
418  ///
419  /// @param[in] filename Filename of the depth map to be imported.
420  virtual void ImportBackgroundDepthmap(const std::string& filename) = 0;
421 
422  /// Gets the currently used background scan as depth map.
423  ///
424  /// @param[out] depthValues The depth values, row by row, from top to bottom, each row left to right.
425  /// @param[out] width Number of columns
426  /// @param[out] height Number of rows
427  virtual void GetBackgroundDepthmap(std::vector<float>& depthValues, int &width, int &height) = 0;
428 
429  /// Sets the background scan, giving a depth map. The resolution should be identical to the camera resolution.
430  ///
431  /// @param[in] depthValues The depth values, row by row, from top to bottom, each row left to right.
432  /// @param[in] width Number of columns
433  /// @param[in] height Number of rows
434  virtual void SetBackgroundDepthmap(const std::vector<float>& depthValues, int width, int height) = 0;
435 
436  /// Sets the "background scan" from a given list of planes. Camera must be calibrated first!
437  ///
438  /// @param[in] planes The list of planes that define the background.
439  virtual void SetBackgroundPlanes(const std::vector<Plane>& planes) = 0;
440 
441  /// @}
442 };
443 
444 /// @} StructuredLightScannerGroup
445 /// @} InterfaceGroup
446 
447 } // namespace
448 
449 #endif // DAVID_SDK_I_STRUCTURED_LIGHT_SCANNER_H