Version: 16.3.1.167ea6ecff

How to evaluate the library

This section will guide you through evaluation of the library's algorithms using the distributed precompiled example programs.

Evaluation of SAL3D Core

This GUI example will guide you through the evaluation of SAL3D main objects and related functionalities. Main objects are Range Maps (accumulation of profiles on laser triangulation applications), COPs, and ZMaps.

The user can open Range Map data (from SAL3D arm files or from image files). This data can be converted to COP by assuming linear relation or by using a metric configuration file (obtained from Metric Calibration Tool). Linear factors relate rows, columns, and greyvalues to X, Y, and Z coordinates according the user input values.

COP objects can alternatively be loaded from files. COP data can be displayed as points, wireframe or as solid. This data can be also exported to PLY File Format (as binary or ASCII).

ZMap objects can be obtained from COPs together with a set of ZMapFactors. Although the user can use the default factors which can be get from a COP, it is preferred to select the most appropiate for each application according to the ZMap size and the COP ROI. Thus, modifying the ZMap factors, users can obtain a smaller ZMap (increasing the processing speed) or a ZMap of a specific COP ROI. In addition, users can force the ZMapFactors to get the same pixel/metric ratio on both axis (X and Y). In that case, the width or height are automatically modified to satisfy the constraint.

ZMaps can be saved in several formats, however, in order not to loose any float information ZMap images should be saved as zmap files or 32-bits tiff image. Otherwise, there is a normalization on Z to adjust the 8-bits representation.

Evaluation of the Horizontal Peak Finder Tool using wxPeakFinderHExample

This GUI example will allow you to evaluate the sub-pixel accuracy of the SAL3D Peak Finder Tool. Pictures can be loaded (from files or cameras) and the detected points of the laser profile stored in a plain text file.

The Peak Finder Tool works analysing frames column by column, returning a laser stripe point for each picture column. Vertical laser stripes can not be detected using this tool (only using the obsolete Vertical peak finder).

peakFinder_Orientation.png
Laser stripe orientation: Peak finder tool analyzes pictures column by column, so, only horizontal stripe orientations.

A Profile can be extracted from a Frame, first converting the image file to a Frame with Open Image... under File menu. Once it has computed the Profile from the Frame, the result it is shown as an overlapping of the Profile over the image.

A RangeMap can be created with Grab... under Grabber menu. The GUI application displays a Grab Parameters dialog where user defines frame grabber driver, time out, the laser detector threshold, and maximum number of profiles.

The frame grabbers drivers, which are not the same as the vendor's drivers, instruct the application how to initialize a particular frame grabber and how to talk to the frame grabber in order to receive the image from the camera. The default installation path for these drivers is C:\Program Files\AQSENSE\SAL3D\bin\, and they have the file extension FGD.

In addition, this demo works using a virtual frame grabber too (fileframegrabber). Several files can be loaded to simulate the acquisition.

The timeout, in milliseconds, is the maximum time that the frame grabber will wait for images from the camera (not used in case of fileframegrabber)

The number of profiles defines the maximum size of the Range Map. When the Range Map reaches the number of profiles previously defined, the application stops grabbing. As both conditions (timeout and number of profiles) are always used, the grabbing stops when any of both conditions is true.

Note
In case of fileframegrabber, the number of profiles should correspond to the number of frames (files) used during the "virtual" acquisition. When acquiring from a real frame grabber, the number of profiles will depend on the camera trigger mode (free running, external trigger, the encoder, etc).

User can stop the Grabbing with Freeze under Grabber menu. In that case, the RangeMap acquisition stops without returning the acquired profiles.

Once a RangeMap is created, it can be viewed with Range Map... under View menu. Although this application only displays a color bidimensional representation of the RangeMap, it can be saved and use the Core Example for the next Range Map representations.


Evaluation of the Metric Calibration Tool using wxMetricExample and wxMetricStaticExample

These GUI examples will allow you to evaluate the metric accuracy in the 3D reconstruction from a RangeMap. wxMetricExample needs a RangeMap (as arm file or image file) originated from the acquisition of a calibration pattern. The difference between the wxMetric and the wxMetricStatic is the calibration pattern. The first one requires the linear scanning of the Linear Metric Calibration Pattern, while the wxMetricStatic only requires a single profile of the Static Metric Calibration Pattern (or a central profile of the Linear Pattern).

Although the example RangeMaps installed with SAL3D (Distribution Files) can be used, the results for a certain acquisition system can be calculated by acquiring a RangeMap of a calibration pattern (Linear calibration pattern and Static calibration pattern) with it. Consider the details of the pattern acquisition, described in the previous link. For example, the metric tool expects the calibration pattern parallel to the motion, although it doesn't need to be very accurately parallel.

wxMetricExample

After importing the pattern picture (File > Load Pattern Range Map or File > Import Image as RangeMap.. ), the range map viewer shows the pattern, whose orientation should be like in the following figure (a). The occlusion can be either in the top or bottom depending on the camera orientation

patternOrientation.png
Expected orientation of the Linear Metric Calibration Pattern.

Then the acquisition system can be calibrated ( Calibrate > Calibrate ...). The metric calibration time depends on the RangeMap's size, (up to some minutes for large RangeMaps)

After calibration a metric report is obtained, containing 4 parameters:

Consider also that the Metric Calibration Tool alone does not correct lens distortion; you can use sal3d::LensDistortion::calibrate for that, in the lens calibration tool.

In addition, this example lets the user modify the pattern points according to user pattern dimensions (Calibrate > Import Pattern Points). Points can be loaded from a plain text file listed in the following format:

Example
x1 y1 z1
x2 y2 z2
...
x12 y12 z12
height

Please, refer to Linear calibration pattern section for a full description of pattern points. In addition, there are two text pattern points files on the installed files C:\Program Files\AQSENSE\SAL3D\examples\rangeMaps, one for the each metric calibration technique.

WxStaticMetricExample

As this example only news a single profile for calibration, when loading RangeMaps with more than one profile, user should introduce the number of the profile. This profile is displayed on the top window.

After the calibration, the metric reconstruction profile is represented on the bottom window. User can visualize the metric coordinates by pointing the metric profile. In addition, the metric report is obtained, containing 3 parameters:

For getting accurate results, be sure that the pattern misorientation is as small as possible. However, as a single profile is analysed, it is not possible to compute the pattern misorientation. Consider also that the Metric Calibration Tool does not correct lens distortion.

In addition, this example lets the user modify the pattern points according to user pattern dimensions (Calibrate > Import Pattern Points). Points can be loaded from a plain text file listed in the following format:

Example
y1 z1
y2 z2
y3 z3
y4 z4
height

Reader is referred to Static calibration pattern section for a full description of pattern points.

In addition, there are two text pattern points files on the installed files C:\Program Files\AQSENSE\SAL3D\examples\rangeMaps, one for the each metric calibration technique.

After calibration, user can open a new RangeMap, in that case, the previous metric calibration is used to reconstruct the current profile.

Moreover, this example can also be used to get a metric config for linear scanning, in that case, user must introduce the encoder step before calibration.


Evaluation of the Match3D Tool using wxMatch3DExample

This GUI example lets you evaluate the alignment of two surfaces. A COP should be loaded as a reference model (File > Open Model), and a second COP related to the inspected part (File > Open Part). After the alignment (Match > Align) the right window displays both aligned surfaces. The bottom window displays the disparity map between both surfaces, and can be saved as a ZMap.

In addition to the Match3D alignment, this example also permits the evaluation of the Match3DCoarse for aligning objects located one far from the other or big misoriented. Another option to align far objects is using an initial pre-alignment (Match>Set Initial Movement).

After the alignment, the status bar displays the quality of the alignment. However, when pointing the mouse over the disparity map, the status bar displays the x and y coordinates of the object and also the metric disparity between model and part.

User can change the color scale of the disparity map using the Set Tolerance under Disparity menu. Disparity map values higher than the tolerance are displayed in blue/red depending on their sign. Values between [-tolerance, tolerance] are scaled from blue to red.

Although you can use model and part COPs from the Distributed examples, you can also evaluate the Match3D Tool for your acquisitions. You can use the CORE example to obtain COPs with your acquisition system.

Wrong Normal Orientation

When a COP is not correctly populated, and the coordinate axis does not follow the expect one, the COP normals are defined in the wrong direction, so, instead of pointing outside the object, they are pointing inside the object.

By default, the wxMatch3DExample only displays the points whose normal is pointing to the camera, so, in case no points (or few) appear after loading a COP, the reason could be the Wrong COP distribution.

In this case, as Match3D does not consider the points whose normal is pointing in, the Match3D fails or it give an error saying "not enough valid points". To solve this error, user can repair the COP by using the option Repair->Flip Model normals or Repair->Flip Parts normals.

Possible reasons of Match3D misalignments

This section describes some typical cases of misalignments.

Match3D

Match3D-Coarse Extension




Evaluation of the Merger Tool using wxMergerExample

This GUI example lets you evaluate the accuracy of merging two Profiles acquired simultaneously from different cameras. For a better understanding in the example Profiles are taken one by one from existing Range Maps. Merger tool requires its own parameters to combine information from both cameras. In order to compute them, user could load two calibration pattern range maps; one corresponding to the base camera and the other one to the auxiliary camera. After that, parameters can be computed clicking Merger > Calibrate.

You can find example ARM files acquired from both cameras distributed with SAL3D (Distribution Files).

The Merger Tool calibration expects the calibration pattern parallel to the motion (see Linear calibration pattern for more details).

Note
This tool requires the same number of profiles in both range maps (base and auxiliary). Because it is assumed that both cameras are simultaneously acquiring.
The computation time depends on the Range Map's size. Please wait until merger calibration finishes.

In case of wrong input, a message box appears indicating one of both calibration range maps is not valid. If this message appears, make sure that:

After loading both RangeMaps, and obtained the Merger Configuration, the application displays an accuracy report.

The bottom window displays the merged RangeMap. User can visualize each profile of this RangeMap using the slider.

Once the wxMergerExample has a Merger Configuration loaded, either loading from a file or calibrating, you can load new ARM files for the base and auxiliary cameras, acquired as the calibration target, and you will get their merged result.

Evaluation of the Mesh Import Tool

The Mesh Import Tool allows the user to get COP from mesh files. In order to import mesh files to SAL3D, this application generates a virtual scanning of the full object to get a cloud of points. As the main use of the Mesh Import is to generate a reference model for the Match3D Tool, user should orientate the Mesh object to view the surface to inspect.

After that, user must select the COP resolution according to the project requirements. Then, this GUI generates a COP that can be used on the Match3D as a reference model. User only needs to save to disk and load it from the final application. Alternatevely, user can also generate a ZMap from the mesh data.

Evaluation of the CAD Import Tool

The CAD Import tool allows the user to get COP from IGES data. In order to import CAD data to SAL3D, this application generates a virtual scanning of the full object to get a cloud of points. As the main use of the CAD Import is to generate a reference model for the Match3D Tool, user should orientate the CAD model to view the surface to inspect. After that, user must select the COP resolution according to the project requirements. Then, the CAD Import tool generates a COP that can be used on the Match3D as a reference model. User only needs to save to disk and load it from the final application.

Evaluation of the Angular Metric Tool

This GUI example will allow you to evaluate the metric accuracy in the 3D reconstruction from a RangeMap in case of angular scanning. wxAngularMetricExample needs a RangeMap originated from the acquisition of a calibration pattern. This example automatically loads a pattern range map distributed in the library.

Although the example RangeMap installed with SAL3D (Distribution Files) can be used, the results for a certain acquisition system can be calculated by acquiring a RangeMap of a calibration pattern (Description of the angular calibration pattern) with it. Consider the details of the pattern acquisition, described in the previous link.

In addition to the pattern, the example asks for the initial scanning axis and the delta angle. The first value is an aproximation of the angle with respects the position where the laser is perpendicular to the calibration pattern. The delta angle is the angle increment between two consecutive profiles. The default values corresponds to the parameters of the distributed range map. In case of testing a different range map, the appropiate values must be used.

Then the acquisition system can be calibrated ( Calibrate > Calibrate ...). The metric calibration time depends on the RangeMap's size, (up to some minutes for large RangeMaps)

After calibration a metric report is obtained, containing 3 parameters:

This tool, opposite to Metric Calibration tool, does not required an accurate pattern orientation.

Although the library allows to combine the Angular Metric Calibration with the Lens Distortion Tool, this example does not use it.

In addition, this example lets the user modify the pattern points according to user pattern dimensions (Calibrate > Import Pattern Points). Points can be loaded from a plain text file listed in the following format:

Example
y1 z1
y2 z2
...
y4 z4
height

Please, refer to Description of the angular calibration pattern section for a full description of pattern points. In addition, there are one text pattern point file on the installed files C:\Program Files\AQSENSE\SAL3D\examples\rangeMaps.

Evaluation of the wxIntegratorExample

This GUI example shows the triangulation of one or several COPs to get a continuous surface representation of a Cloud of Points. User can open several COPs using the option File > Open COP and selecting all COPs before clicking on Open button. In addition, user can add more COPs using the menu File > Add COP. In case of usign the Open option, instead of Add, previous COPs are removed. To generate a mesh, user must select the Reconstruct > Reconstruct Surface ... . After some processing time, a new window will appear displaying the generated mesh.

In addition, before starting the reconstruction, user can change the Integrator parameters (Edit > Settings). The reconstruction depth is related to the resolution of the final reconstruction, a valid range is [1, 10]. The samples per node parameter determines the smoothness of the reconstruction in the presence of noise in the cloud of points. This parameter should be set to 1 in case of no presence of noise and to a range between 10-20 in case of important noise.

Warning
Integration time highly increases together with the resolution, it could take several minutes in case of depth 10

Evaluation of the wxGeometricExample

This GUI example shows part of the functionality of the geometric tool. This example uses some of the plane functions present on this library.

After loading a COP file (File > Open COP) user can tilt the COP to orientate it parallel to Z axis (Tilt > Tilt). The example fits a plane to the data, and then computes the rotation to align this plane to Z axis. The top windows displayes in green the COP before tilting and in yellow the COP after tilting. The bottom left and right windows display the generated ZMap before and after tilting.

If user loades the example present in C:\Program Files\AQSENSE\SAL3D\examples\COPs\geometric.cop, user will see that measuring on the tilted image is much more easy than without tilting.

The Geometric tool section give more information about these advantages.

This example also allows the user to define a plane by selecting 3 points. After selecting the optionTilt > Tilt by 3 points), user must define 3 points on the bottom left image. As black pixels corresponds to non valid points, the status bar indicates which point should be selected.

Evaluation of wxAreaExample

This GUI example shows how to compute areas on COP rows. This example contains two modes (Mode > Area to Reference Line and Mode > Enclosed Area). The first one computes the area for each loaded COP to a reference line defined by the 5 first and last valid points on the profile. This number is fixed on the example, but the SAL3D functions allow the user to define it.

The second mode computes the area enclosed by all the loaded COPs.

The top window displayes the loaded COPs, the middle window represents the area value for each COP row. In case of loading several COPs, several graphics appears. User can observe the area of each profile by pointing the mouse over the graphic. The bottom window display the profile (or profiles) according the profile selected on the middle window.

The status bar displayes the accumuated area of each profile. To get the volume, user should multiply these values for the encoder step.

Evaluation of the wxLensDistortionExample

This GUI example shows the benefics of removing the lens aberrations introduces by the radial distortion. The user could choose between using an image from file (File > Open Image) or acquiring this from the camera (Grabber > Grab). In the first case, only one image could be load. In the second case, more images can be used to determined the parameters by clicking on Capture button. User could click on Reset button to remove previous acquired views.

In both cases, before calibration, user must introduce the number of pattern rows and columns and choose the calibration mode (Mode > Chessboard Pattern, Mode > Dots Pattern, or Mode > Inverted Dots Pattern). After that, user must click on Calibrate button to get the parameters, that are displayed on the status bar. In addition, the control points (red) and the points after correction (green) are displayed over the last acquired image.

Some pattern images are present in C:\Program Files\AQSENSE\SAL3D\examples\Frames.

Althought GUI examples distributed together with the library, the Lens Distortion parameters can be used in the Metric Calibration tool to get a better metric config in the presence of lens distortion. After calibration, Metric Config contains both Metric and Distortion parameters.