# Calibration Calibration is used to apply the transformation between a depth map and a point cloud or a mesh. There are 3 ways to set up this conversion: * Apply a simple scale on the pixel coordinates of the depth map ([`EScaleCalibrationModel`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1EScaleCalibrationModel.html) [_.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1EScaleCalibrationModel.html) [_Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1EScaleCalibrationModel.html) class) * Use the explicit geometric model ([`EExplicitGeometricCalibrationModel`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1EExplicitGeometricCalibrationModel.html) [_.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1EExplicitGeometricCalibrationModel.html) [_Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1EExplicitGeometricCalibrationModel.html) class) * Use the object-based calibration approach ([`EObjectBasedCalibrationModel`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1EObjectBasedCalibrationModel.html) [_.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1EObjectBasedCalibrationModel.html) [_Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1EObjectBasedCalibrationModel.html) class) These models share the same base class [`ECalibrationModel`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1ECalibrationModel.html) [_.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1ECalibrationModel.html) [_Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1ECalibrationModel.html) and expose the method [`ECalibrationModel::Apply`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1ECalibrationModel.html#a148a345d9f0244fa71623288ded66b45) [_.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1ECalibrationModel.html#a79dbef377a3b3914e4eb8de43bafea8d) [_Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1ECalibrationModel.html#ac4dace2c2ffa277832ff32b14631939e), which is used to apply the conversion between a depth map pixel and a 3D point. It takes as input the coordinates of one point in a depth map and it returns the coordinates of the corresponding point in the 3D space. The method [`ECalibrationModel::Apply`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1ECalibrationModel.html#a148a345d9f0244fa71623288ded66b45) [_.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1ECalibrationModel.html#a79dbef377a3b3914e4eb8de43bafea8d) [_Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1ECalibrationModel.html#ac4dace2c2ffa277832ff32b14631939e) is not aware of the possible mirroring of the corresponding depth map and cannot make use of [`EDepthMap::SetAxisSystemType`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1EDepthMap.html#ad91ea22505b82c695b0f80fa9cf0116e) [_.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1EDepthMap.html#a871ab138ae0e08e31cb11840c0d23788) [_Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1EDepthMap.html#a379ae9a2aed95e051eb4cb48d916548e) (see below). If necessary (when the corresponding depth map is vertically mirrored) the $y$ coordinates should be flipped before calling the `Apply` method. * The class [`EDepthMapToPointCloudConverter`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1EDepthMapToPointCloudConverter.html) [_.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1EDepthMapToPointCloudConverter.html) [_Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1EDepthMapToPointCloudConverter.html) generates a point cloud from a depth map, using one of the calibration models. * The class [`EDepthMapToMeshConverter`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1EDepthMapToMeshConverter.html) [_.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1EDepthMapToMeshConverter.html) [_Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1EDepthMapToMeshConverter.html) generates a mesh from a depth map, using one of the calibration models. By convention: * The origin of the referential is the lower-left corner of the depth map. * The center of the first pixel at the lower-left corner is at $x = 0.5$ and $y = 0.5$. * The center of the pixel at the upper-right corner is at $x = \text{width} - 0.5$ and $y = \text{height} - 0.5$, where $\text{width}$ is the width of the depth map and $\text{height}$ is its height. ## Mirrored Depth Maps By default, **Easy3D** considers that the origin of the 3D axis of the depth map is the bottom left of the internal image buffer, and the Y axis is pointing up. This means that the depth map image is not seen as vertically mirrored compared to the real world image of the scanned object. Nevertheless, depending on your acquisition setup this mirroring can happen (for example if the direction of the scan is inverted). If this is your case, you can set [`EDepthMap::SetAxisSystemType`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1EDepthMap.html#ad91ea22505b82c695b0f80fa9cf0116e) [_.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1EDepthMap.html#a871ab138ae0e08e31cb11840c0d23788) [_Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1EDepthMap.html#a379ae9a2aed95e051eb4cb48d916548e) to [`EAxisSystemType_CornerUpperLeft`](../../../doxygen_cpp/namespaceeVision_1_1Easy3D.html#a91b8d60f0cd4555c7933e5b1ba9f9146) [_.NET](../../../doxygen_cs/namespaceeVision_1_1Easy3D.html#a5fa31f0d73e508b8cd7e4a9b0ce3542c) [_Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1EAxisSystemType.html), meaning that the origin of the 3D axis is on the upper left corner and the Y axis is pointing down. This value changes the behavior of the methods : * [`EObjectBasedCalibrationGenerator::Compute`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1EObjectBasedCalibrationGenerator.html#ab6eaa5f47687d0952d1904d34f497b3c) [_.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1EObjectBasedCalibrationGenerator.html#a0b33629b3ef56a3a0f001933501e869f) [_Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1EObjectBasedCalibrationGenerator.html#aa2a9e13561abbfd3a0f1e86baec51f5b) * [`EDepthMapToPointCloudConverter::Convert`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1EDepthMapToPointCloudConverter.html#a957190194612df7ed201c54019b6e8fd) [_.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1EDepthMapToPointCloudConverter.html#a5b60408cefbbd5dd9c1e1d2b5b41cd21) [_Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1EDepthMapToPointCloudConverter.html#a2fc9a5891bd54f222011a86034b2a1ea) * [`EDepthMapToMeshConverter::Convert`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1EDepthMapToMeshConverter.html#a5b1f452102fb244a02f7063f676a61fc) [_.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1EDepthMapToMeshConverter.html#a99edaa29324268ff34b9e719c7863e9f) [_Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1EDepthMapToMeshConverter.html#a11bdf54a2f05f0fe913e9ae1f5b4a2ee) ## Scale Calibration The scale model ([`EScaleCalibrationModel`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1EScaleCalibrationModel.html) [_.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1EScaleCalibrationModel.html) [_Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1EScaleCalibrationModel.html)) only applies a simple factor on the X, Y and Z axis. These factors are the only parameters of [`EScaleCalibrationModel`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1EScaleCalibrationModel.html) [_.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1EScaleCalibrationModel.html) [_Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1EScaleCalibrationModel.html). For depth maps coming from laser triangulation setup, this transformation does not produce corrected, metric points. It’s main use is to display depth maps as 3D data with the [`E3DViewer`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1E3DViewer.html) [_.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1E3DViewer.html) [_Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1E3DViewer.html) class. ## Explicit Geometric Calibration The explicit geometric model ([`EExplicitGeometricCalibrationModel`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1EExplicitGeometricCalibrationModel.html) [_.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1EExplicitGeometricCalibrationModel.html) [_Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1EExplicitGeometricCalibrationModel.html)) defines a simple and ideal laser triangulation setup. The explicit calibration makes some strong assumptions on the setup geometry and can only be used when a minimum set of parameters are known: * The angles of the camera and the laser plane, in the counter clockwise direction. The camera angle must be positive. * The height of the camera above the scanned object. * The field of view of the camera defined by the sensor size (mm) and the optical focal length (mm). * The physical distance between two line scans of the depth map (depends on acquisition rate and motion speed). * The size of the image and the ROI origin used in laser line extraction (between the top (0) and the bottom (height) of the image). #### HINT Use the [“Easy3D_Setup_Configuration.xlsx](_downloads/3ebd852e0776ceef717ebee69d751026/easy3d_setup_configuration.xlsx)” spreadsheet to compute and check your setup configuration and parameters.  The setup of an explicit geometric calibration uses the constructor of the [`EExplicitGeometricCalibrationModel`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1EExplicitGeometricCalibrationModel.html) [_.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1EExplicitGeometricCalibrationModel.html) [_Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1EExplicitGeometricCalibrationModel.html) class.  ## Object-Based Calibration Object-based calibration gives real world, metric, coordinates from an arbitrary laser triangulation setup. From the scan of a reference object, the calibration process tries to calculate all the parameters required for the transformation to the world space (position and attributes of the camera, position of the laser plane, relative motion of the object, optical distortion…). 1. The calibration process generates a calibration model. 2. **Easy3DLaserLine** uses this calibration model to transform the laser profile scans (or depth maps) into metric, distortion free point clouds. * The calibration model includes all the geometric parameters required for this transformation: * The relative position of the laser and the camera. * The projection and the distortion model of the camera. * The relative motion of the object. ### The Calibration Object The general principle of **Easy3DLaserLine** calibration is to match a scan of a known calibration object to its true geometric dimensions. #### The Truncated Double Pyramid * The dimensions of the “double truncated pyramid” calibration object the X-, Y- and Z-axes are named A, B and C respectively. * The design of the double truncated pyramid must follow the ratios given in the illustration below.  * For example, the provided CAD files of the calibration object use A = 4 cm, B = 6 cm and C = 1 cm. The Calibration Object Size, required for the calibration process, are the values A, B and C.  ### Building a Calibration Object #### Overall Dimensions * Manufacture a calibration object that fits the working area of the project. * For example, if the project targets the inspection of a PCB (a printed circuit board as illustrated), design your calibration object with: 1. The dimension A or B (it does not matter) similar to the width of the PCB. 2. The height (C) of only several millimeters. #### HINT This is not a strict requirement, if the scanned object is slightly larger or smaller than the calibration object, the calibration process is still valid.  #### HINT There is no constraint on the orientation of the calibration object during the scan: - The X-axis can be aligned with the motion direction or with the laser line. - After the calibration process, the origin and axes of the 3D calibrated point cloud follow the conventions of the reference design.  ### Precision and Tolerance The relevant dimensions of the calibration object are the width, the length and the height of the pyramids (called A, B and C in the illustrations). * The relative dimensions to A, B and C (B/2, A/4…) are important and you must execute them with the same precision. * The dimensional tolerances are related to the overall expected precision. If you want to achieve measurements on the point cloud with a precision of 0.01 mm, the manufacturing of the calibration object must have the same precision. * These tolerances only apply to the pyramids geometry, the calibration process does not use the dimensions of the support. * The planar surfaces must be flat between 2 parallel planes separated by the target tolerance, as illustrated.  #### Material and Surface Finishing #### HINT The goal is to obtain the laser profile as thinnest as possible over the whole object surface with the largest reflected energy. The build material and the surface finishing are also important and must have: * A good reflectance, with diffuse reflection (no specular reflections). * No transmission and limited diffusion inside the material. #### HINT You can obtain a good surface finishing using aluminum material and blasting. Blasting gives the surfaces a satin gray finish.  #### 3D CAD Models The calibration object models are available in various 3D CAD formats like STEP, OBJ and STL. Download these files from the download area in the `Additional Resources` section ([www.euresys.com/Support](https://www.euresys.com/Support/Software,-drivers-and-documentation?Series=f97da39d-3c25-404c-aee7-73de1d1867fc)).  ### Scanning the Calibration Object * The scan of the calibration object produces a depth map. * To ensure a correct detection of the calibration object and a precise calibration model, you must fulfill the following criteria: * All faces of the calibration object must be visible on the depth map (this affects the orientation of both the camera and the laser). * No other object can be higher than the calibration object in the depth map. * The depth map must have at least 200 $\times$ 200 pixels. * The calibration object must cover at least 50% of the defined pixels of the depth map. * Examples of bad scans:  ### Using the Calibration with **eVision** * The class [`EObjectBasedCalibrationModel`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1EObjectBasedCalibrationModel.html) [_.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1EObjectBasedCalibrationModel.html) [_Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1EObjectBasedCalibrationModel.html) is the container for the object based calibration model. * The class [`EObjectBasedCalibrationGenerator`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1EObjectBasedCalibrationGenerator.html) [_.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1EObjectBasedCalibrationGenerator.html) [_Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1EObjectBasedCalibrationGenerator.html) performs the computation of such a model using an [`EDepthMap8`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1EDepthMap8.html) [_.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1EDepthMap8.html) [_Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1EDepthMap8.html)/[`EDepthMap16`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1EDepthMap16.html) [_.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1EDepthMap16.html) [_Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1EDepthMap16.html)/[`EDepthMap32f`](../../../doxygen_cpp/classeVision_1_1Easy3D_1_1EDepthMap32f.html) [_.NET](../../../doxygen_cs/classeVision_1_1Easy3D_1_1EDepthMap32f.html) [_Python](../../../doxygen_python/classeVision_1_1Easy3D_1_1EDepthMap32f.html) as input. #### SEE ALSO * [Code snippets](../../../resources/code_snippets/3d_processing/easy3dlaserline/index.html.md) * [C++ sample](../../../resources/sample_programs/3d_processing/easy3dlaserlinecalibration.html.md)