Version: 16.3.1.167ea6ecff

3DExpress base package

3DExpress contains basic functionality for the 3D acquisition and processing.

Main Panel

The main panel displays the current state of 3DExpress. The top table presents all the configured inputs and the bottom table the configured outputs.

panel_main.png
3DExpress Main Panel

Information of the Inputs table

Information of the Outputs table

In addition to display the current status, both tables can be used to interact with 3DExpress. This is a list of main possible interactions:

The Keep Frames option allows the user to store to memory all incoming frames. After that, using the option Save Kept Frames (queue)), the user can save all these acquired frames to disk.

Warning
This operation store all the images to the RAM memory.

The option Flush removes one element (the first acquired) from the corresponding output queue.

Warning
The option Delete Input delete also all outputs from the selected input

Choosing the input source

3DExpress supports several simultaneous input channels. To add a new input, the user should select the menu option Configure > New Input on the main panel menu.

After that, a new window is presented to the user to configure the input settings. On the first step, the user must select the camera type.

Photonfocus 3D03

As this camera can work with multiple ROIs, after selecting this option, a new drop-box allows the user to select the number of peaks. This value should match with the current camera parameters.

These camera parameters can be modified after finishing the input settings.

After clicking to the Next button, user should introduce the driver to interface with the camera. In this particular case, the user should select the option Photonfocus PF3DCam.

To configure this driver, either the user can load some config. data or directly click the Next button. In this last case, a GEV Device Selection window allows the user to select the desired camera.

Automation Technology C4

3DExpress automatically reads the camera configuration to determine the camera parameters (working mode, ROI, outputs activated, etc.).

Despite that the camera already generates the rangemaps, setting the camera in 2D Mode allows the user to see the "live image" helping him to determine the correct COG threshold.

In case that the customer selects multiple outputs on the camera, these outputs are available as ExtraFrames output.

After clicking the Next button, the user should select the driver to interface with the camera. In this particular case, the user should select the option CVB GenICam driver.

Note
this GenICam driver is only available after installing the Common Vision Blox library.

LMI Gocator

After selecting the LMI Gocator input, the user should click the Next button to choose the driver. In this particular case, the user should select the option CVB GenICam driver.

Note
The CVB GenICam driver is only available after installing the Common Vision Blox library.

Driver configuration

According to the kind of camera chosen in the first panel, the user has to choose the driver to interface that camera.

Available options for Generic 2D cameras:

Available options for Generic 3D cameras:

Available options for Photonfocus 3D03

Available options for Automation Techonology C4 Cameras and LMI Gocator

Custom configuration (advanced)

The customer driver allows the user to add some driver parameters. The user can select between different driver types (generic, file, others).

The generic option allows the user to work with SAL3D driver files (*.fgd). In that case, the user must add the driver path on the "FGD path:" textcontrol and the different driver parameters on the "FGD config:" textcontrol.

For more information about the SAL3D drivers and the corresponding options, please check Frame Grabber & Camera Drivers.

Grab From File

This driver allows to work with saved image files. The user can select one (or more) image file or a full directory.

In addition, there are several parameters:

Silicon Software microEnable III/IV

The driver is specifically to work with Silicon Software framegrabbers (microEnable III/IV).

The customer can load a Silicon Software configuration file (*.mcf). In addition, the user can modify the different parameters by enabling the corresponding checkboxes.

Pleora

The driver is specifically to work with Pleora GigE driver. It requires a pleora license.

User should select the eBus version installed in her computer.

User can fix the camera by indicating the MAC or IP address, otherwise, a dialog appears asking to select the camera.

The driver allows to introduce a hardware time-stamp to control the end of the rangemap accumulation of profiles. This time out is expressed in number of clocks.

Common Vision Blox Genicam

This driver allows the user to work with GigE cameras using the Common Vision Blox GenICam driver.

For more information about the genicam driver, please check the Using the CVB GenICam to interface with 2D Cameras.

Grab From SAL3D RangeMap Files (.arm)

This driver allows to simulate a rangemap acquisition by loading one (or more) rangemap from file.

Note
In case the user wants to simulate the acquisition of a single camera with two ROIs, the user should separate the two rangemap paths using a semi-colon instead of a comma.

Grab From SAL3D COP Files (.cop)

This driver allows to simulate a rangemap acquisition by loading one (or more) COP from file.

Note
In case the user wants to simulate the acquisition of multiple COPs at the same time, the user should separate the two rangemap paths using a semi-colon instead of a comma.

Photonfocus PF3DCam

Specific driver to work with Photonfocus 3D03 cameras. In case neither the IP or the MAC address is specified, after clicking on the next button, 3DExpress displays in a new window all the available cameras.

panel_fg_configuration.png
Driver Configuration Panel

Detection of the laser line

Note
This panel only appears in case of using the Generic 2D kind of cameras

The peak finder configuration panel displays the current camera image with the overlay of the laser detected profile in red. The two yellow lines represent the width of each detected peak. User can decrease/increase the threshold for a good tuning of the laser detection.

panel_peak_configuration.png
Peak Finder Configuration Panel

In addition, the user can select how many threads of the application will be used for the laser detection; it can be a heavy work to detect the laser position in many pictures per second.

The method used by default is the standard center of gravity (COG), however, in case of having the license of the more accurate Aqsense Peak Detector, user can choose between both algorithms.

Detection of two laser lines

3DExpress supports the detection of two lines only when for all the frames, all laser lines can be split by fixed ROIs.

Our each of the two line extractions, the user should select the beginning and ending of each ROI. By default, the ROI of the first peak (peak0) is set to the size of the Frame, and the ROI of the second peak (peak1) is set to start and end to the row zero (this is the way to define that this second peak is disabled).

In case of multiple lines, the user should select the number of laser lines, and for each one, it should define the start and end rows for that laser extraction.

two_laserlines_settings.png
Setting the ROIs for each laser line
Note
Note: The ROI limit lines only appear when the corresponding input is grabbing.

After defining the two laser lines ROIs, the following panels allows the user to select from each peak get the data. For example, the following image shows how to select the peak that the user want to calibrate. In case the user wants to calibrate the two peaks, the user needs to apply two calibrations, one for each source.

two_peaks_selecting_source.png
Setting the desired peak during the calibration

Accumulation of the profile data into RangeMaps

The profile data obtained after the laser line extraction (either using 3D cameras of a software laser detector) can be accumulated into RangeMaps.

panel_rm_configuration.png
RangeMap Configuration Panel

3DExpress allows to define different methods to end the rangemap accumulation

Warning
In case of using the CVB GenICam driver, the Time-out value must be configured inside the CVB Management console (see Section CVB GenICam Driver for more details).

Accumulating profiles in case of AT cameras

In case of AT cameras, despite in general it is not need to accumate profiles, as the camera internally accumulates them, there are some cases where we could need to control the size of the rangemap:

In these two cases, after activating the option Enable presence detector, the Min. profiles and Max. profiles options are used, independent on the number of profiles sent by the camera.

Determining the presence/absence of the scanning object by using the laser line.

In addition to the end conditions, 3DExpress allows the user to define a object presence/absence detection using the laser profile information, in case of Generic 2D or Photonfocus 3D03 cameras.

In case the user defines a Laserdetector minpoints greater than 0, 3DExpress analizes, profile by profile, the number of detected peaks on the defined ROI. User can define a ROI smaller to the camera ROI to discard points always present on the image.

This laser detection is used either to start and to stop the rangemap accumulation. So, 3DExpress starts to accumulate a rangemap when it finds the first profile with more than "minpoints" detected. Similarly, 3DExpress stops the accumulation of a RangeMap when it finds the first profile with less than "minpoints" detected.

This stop condition works together with the other ones (time-out or maximum number of profiles), so, in case the user is interested to only use the presence/absence detection, the user should assure that the other two values are big enough.

The COP viewer (see Laser Detector Limits for more information) contains tools to help the user to check if the limits are corrected set.

Rangemaps processing plug-in

3DExpress allows to run external code to postprocess the rangemap inside 3DExpress.

To do that, user can select an external dll (RangeMap filter tab) that process the input rangemap and returns a new rangemap. User can also add some configuration parameters on the corresponding text control.

As an example, the 3DExpress installation package includes a dll and source code of the rangemap median filter.

As this filter is for rangemaps, it must take into account that rangemap can contain missing data. This median filter only computes the median filter if the operating window has more than "minelements" valid points. Otherwise, the result of the processing point is "zero". So, this filter also remove isolated data.

These parameters can be modified by adding them on the config text control:

"winsize=3|minelems=5"

COPs processing plug-in

3DExpress allows to run external code to postprocess the COP inside 3DExpress.

To do that, user can select an external dll (COP filter tab) that process the input COP and returns a new COP. User can also add some configuration parameters on the corresponding text control.

As an example, the 3DExpress installation package includes a dll and source code of the COP crop filter (copcrop.dll). This crop filter is based on the definiton of a bounding box aligned to X/Y/Z axes.

The available parameters for this filter are:

Example to remove points out of a given Z range:

"zmin=-3.5|zmax=10.5"

Rangemaps queues

User can determine how many rangemaps must be stored in a circular queue until they are call from the external applications. There are three possible ways to run when the queue is full.

Calibration of the rangemap data

Possible calibration solutions included in the base package:

Alternatevely, it is possible to use the Metric Linear Calibration Add-on

Static Metric calibration of the rangemap data

The static metric calibration allows the user to get the metric configuration parameters that allows to convert rangemap data (pixel units) to COP data (in metric units). So, after calibration, user is able to perform metric measurements over the scan data.

This static metric calibration requires the use of a pattern (reference calibration object) for the extraction of the calibration parameters (for more information, please, read the Section Static calibration pattern).

panel_static_metric_configuration.png
Static Metric Configuration Panel

In order to calibrate the system, the user should introduce the dimensions of the static pattern. These dimensions can be introduced either in the top table (and the additional height textbox) or by loading the points from file. This file is a txt-plain file containing the following data:

y1 z1
y2 z2
y3 z3
y4 z4
height

In order to visualize the calibration profile, user can use the "Grab one" button to get a profile from the camera, or it can load a RangeMap from file. In that case, user should introduce the index of the profile to use to calibrate the system.

User can observe this profile on the bottom left window. The bottom right window displayed the metric profile after calibration. A resize of the dialog can enlarge these bottom windows.

In case the user is intereted on reconstructing not only profiles, but also cloud of points (COP), the user has to introduce in the corresponding textbox the encoder step (the metric distance between two consecutive profiles) before clicking the "Calibrate" button.

In case that after a valid calibration, the user needs to change only the encoder, after setting the new value on the "Encoder step:" textbox, user can update the new value by clicking on "Set encstep" button.

If the working ROI is bigger than the calibration pattern, and other objects appear to the scene, the user can set a calibration ROI (using the ROIleft and ROIRight controls) to discard points out of this area.

Note
If possible, it is recommended that the pattern calibration covers all the working area.

After calibration, the user can save this metric configuration to a file if desired, for a possible combination with sal3d, or then using the Metric Config File kind of metric configuration.

Note
If the system had been previously calibrated by means of the Lens distortion Add-on, 3DExpress will pop-up the following message:
You have done a lens calibration. It will be used at this metric calibration. If you don't want to use the lens calibration, please answer Cancel.
In case you want to use the lens calibration parameters together with the metric, you should click on Ok, otherwise, clicking on Cancel, you will calibrate without using the lens distortion parameters.

Static Metric calibration using patternZZ

In order to calibrate the system, the user should introduce the dimensions of the static pattern. These dimensions can be introduced either in the top table (and the additional height textbox) or by loading the points from file. This file is a txt-plain file containing the inside points of the different segments of the pattern.

3dexpress_patternZZ.png
Static Metric patternZZ Configuration Panel

User can also automatically creates the pattern points by introducing the coordinates of the first point, and the offset between points.

First, you should need to set the number of pattern points you have in your pattern.

Note
Extreme points of the pattern are not considered as calibration points

In order to introduce the offset between points, you should set the corresponding "Y dist" and "Z dist" values. The sign of the "Z dist" is quite important. In case that the second calibration point has a Z higher than the first one, "Z dist" must be positive, negative in other case.

This static metric calibration requires the use of a pattern (reference calibration object) for the extraction of the calibration parameters (for more information, please, read the Section Static calibration pattern).

Rough calibration by using 3 linear factors

In some applications it is not required to have a metric calibration data, and an approximation can be used. In this case, the user do not need any calibration pattern to get COPs from RangeMap data.

By setting the metric algorithm to "3 factors", a simple panel appears, where the user have to introduce the 3 linear factors that convert rangemap to COPs

3DExpress outputs

3DExpress can generate different types of outputs (RangeMaps, COPs, ZMaps and Extra Frame). In order to add a new output on 3DExpress, user must click on the Add output ... icon, and then choose on the top drop-down list the desired output.

Defining the parameters of the RangeMap output

Once defined the output type (RangeMap in this case), the user must select on the second drop-box list the input channel (this is important in case of multiple inputs).

The RangeMap object is a 32 floating-point image, so, in case the user is interested in processing the rangemap as an 8 bit image in the client, a normalization is required. For that, the user must select the option 8-bit unsigned on the Frame settings section. If the user does not enable the frame output, this output will be usable only from inside 3DExpress, and with a SAL3D client. The user can also select a 16 bits normalization.

This normalization scaled the rangemap values to transform the rangemap range to the range [0, 255]. The user can change this normalization by defining the rangemap range to be scaled. RangeMap values lower than the defined minimum value will be set to zero, and RangeMap values higher the defined maximum will be set to 255.

The Width and Height parameters allow the user to fix the size of the output RangeMap. Setting these value to zero means that the final size is undefined, so the output rangemap size will be the same as acquired. For other values, the output is cropped in case the dimension is smaller than the rangemap size, or the output contains empty (0 pixel values) extra lines to adjust the dimensions.

After setting all the normalization parameters, 3DExpress indicates the ratio between rangemaps units, and normalized image units.

Clicking the Apply button makes the settings effective without closing the dialog page.

The button Files... allows to automatically saves all acquired rangemaps to a selected destination. This option is allow both for the rangemap and the normalized rangemap output image file.

After creating a new output, the main panel shows a new icon representing this ouput. The user can view the last elenemt in the output by double-clicking the output icon, or can modify its settings using the right-mouse button.

panel_output_rm.png
Panel to configure the RangeMap output

Defining the parameters of the COP output

The output COP (3D Cloud-Of-Points) does not require any specific parameter, but it can only be used with a client written using SAL3D, as the SAL3D library includes the COP data type.

The button Files... allows to automatically saves all acquired COPs to a selected destination. The user can choose between COP or PLY formats.

Defining the parameters of the ZMap output

Once defined the output type (ZMap in this caset), the user must select on the second drop-box list the input channel (this is important in case of multiple inputs).

panel_output_zmap.png
Panel to configure the ZMap output

The ZMap factors section allows the user the define the conversion factors from the COP (3D Cloud-Of-Points) to the ZMap (please, see the section Zmap for more information about these parameters).

By enabling the Xmin and/or Ymin checkboxs, the user can manually introduce these values, otherwise, for each COP, 3DExpress will determine the minimum coordinate on each axis.

The first list box allows the user to choose between undefined, Xunits/pixel or Xmax. In case it is not defined, 3DExpress will determine for each COP the maximum coordinate. Alternatively, the user can fix the Maximum value, or it can define the conversion ratio units/pixels. This last option is easily ensures that each output has always the same ratio between pixels and metric units.

This is similar for the Y axis. If the user is interested to have proportional outputs, the user must introduce the same value in the Xunits/pixels and Yunits/pixels.

The customer can also select the size of the output. This is quite important, for example working with Sherlock (from Teledyne Dalsa), as this program requires all the input images to have the same size.

The Frame settings parameters allows the user to normalize the ZMap into 8 bits (or 16 bits) images. It is required to enable this, if you use the client APIs distributed with 3DExpress. The ZMap data types in the client side are supported only with SAL3D.

In case both values (Value 3 and Value 255 are set to zero, the Zmap is automatically normalized from [Zmin, Zmax] to [3, 255].

The reason we use the range [3, 255], instead of [0, 255] is because we have some special conversion values.

Special normalization values
ZMap ValueNormalized Image Value
NaN0
-Inf1
+Inf2
Note
NaN values are used for non defined points, and -Inf and +Inf are only used in case of disparity maps, not available in 3DExpress still.

Below the Frame settings, 3DExpress indicates the 3 factors that relates pixels with 3D coordinates.

Interpolated ZMap

User can choose between two types of zmap, either Interpolated, or without interpolation. In case of interpolation, COP triangles are used during the ZMap generation. In case of non-interpolation, only the COP points are using to generate the ZMap.

Combined ZMap

In case of using two lasers and one camera (with two ROIs), it is possible to combine both COPs in a single ZMap.

For more information, please, see section Combined zmaps (one camera and two lasers).

ZMap-aligned output

This option allows the user to define the projection plane. In general, when creating a ZMap from a COP, all 3D points are orthogonally projected to the plane Z=0. However, sometimes it can be interesting to project to another plane (for example in case the user is interested to make 2D measures over a tilted plane).

To define the projection plane (after activating the corresponding checkbox), the user should click the Set ROI button, that will open a new window, that includes the rangemap of the last acquired part. Using the mouse, the user can define (by "painting in while") a ROI (Region-Of-Interest) where he knows to always include a flat part of the scanned object. The points inside this ROI will be use to determine the projection plane. After clicking the Apply button, user can see in red the 3D points inside te ROI.

After that, for each acquired rangemap, 3DExpress will use the points in the ROI to determine the equation of the corresponding 3D plane. Then, 3DExpress will determine the Movement that aligns this plane with the plane Z=0, before the ZMap projection.

The user can also modify the selected ROI using the button Clear ROI or by setting the Paint mode: to Subtract from ROI.

In case the user is interested to reduce the ROI span in the Z axis, the user can introduce the Z values on the Upper Z limit and Lower Z limit.

Note
Both the ROI and the crop on the Z axis will not remove any COP point, they are only used to determine which points will be used to define the 3D plane
panel_planeAligned.png
Panel to configure the ZMap-aligned output

The button Files... allows to automatically saves all acquired ZMaps to a selected destination.

Defining the parameters of the ZMap output with texture

In cases where the texture (either in grayscale or color) is important, it is possible to create an additional ZMap that contains the texture of the COP.

This textured ZMap must be related to an existing ZMap. This way, we ensure that both outputs have a correspondence pixel to pixel. Combining both outputs, it is possible to know the Z coordinate and the texture information of each point in the ZMap.

In order to relate with the corresponding ZMap output, the user should select the output index on the Related ZMap Output.

The user should select the input source of the texture information. In general, the user can select between the light and width information provided by the peak detector (or the camera in case of 3D cameras).

Note
This output does not require ZMap factors because 3DExpress automatically uses the factors of the related ZMap.

The button Files... allows to automatically saves all acquired ZMaps to a selected destination.

Defining the parameters of the ExtraFrame

The extra Frame output contains additional information extracted during the laser line detection. The extra frame information depends on the laser stripe detection; both software laser line detection (COG and Aqsense Peak detector) additionally determine the width of the laser line. This width information can be used in some cases to solve surface inspection problems.

In case of using 3D cameras, the Extra Frame information depends on each camera model.

panel_output_extraFrame.png
Panel to configure the Extra Frame output

Depending on the extra Frame information, the data can be a 32 floating-point image, so, in case the user is interested to process the rangemap with 8 bits (or 16bits) image operators, a normalization is required. This is the case for the client API distributed with SAL3D, and can be chosen in the dialog.

This normalization scales the grey values to transform the image range to the range [0, 255] (or [0,65535] in case of 16 bits). The user can change this normalization by defining the grey normalization range. Grey values lower than the defined minimum value will be set to zero, and grey values higher the defined maximum will be set to 255.

The Width and Height parameters allows the user to fix the size of the output RangeMap. Setting these value to zero, it means that the dimension is not defined, so, the output size will be the same as the extra Frame. For other values, the output is cropped in case the dimension is smaller than the extra Frame size, or the output contains empty (0 pixel values) extra lines to adjust the dimensions

The button Files... allows to automatically saves all acquired ExtraFrames to a selected destination. Ther user can choose between different file formats.

Visualization of input/output data

3DExpress allows the user to visualize all input and output data either during the set-up or while the application is running.

The user only needs to double-click on the corresponding input (or output) source to open a new window displaying the data.

In general, all these windows allows the user to save the data to a file. In addition, each window contains some specific functionality depending the data type.

COP Viewer

viewer_cop.png
COP Viewer

This viewer displays the COP of the corresponding output.

The COP viewer allows the user to see the first element on the queue and the last element in the queue by selecting the corresponding button (Current element or Last Received).

This viewer also allows the user to simulateously display more than one COP. User can add to the viewer COPs from other outputs (using the Menu Extra and selecting the desired source) or it can add COPs from file (File > Add..< >).

Laser Detector Limits

In case the user is acquiring using the "Laser Detector Configuration" (see Determining the presence/absence of the scanning object by using the laser line. for more information), the user should enter some limits (LaserDetector top and LaserDetector bottom. Sometimes it is not easy to know where to place these values or to check if they are correctly configurated.

To help the user to check these limits, 3DExpress allows the user to display them on the 3D Viewer (View > Laser Detector Limits. After enabling this option, the viewer displays two planes (in cyan color).

Full Frame pixels

When observing a COP, sometimes the user has no references about the relation between the 3D data and the camera pixels. As a reference, the user can display on the COP viever, the reconstruction of all the sensor pixels (only the ones included inside the camera ROI) on the plane X = 0 (View > Full Frame Pixels. For example, users can check if the current acquisition is covering all the camera ROI.

Moving COPs

The user can control the position and orientation of the COP using the mouse buttons.

  • Pan: Mouse Left button (+ Mouse movement)
  • Rotate: Mouse Right button (+ Mouse movement)
  • Zoom: Mouse wheel or Ctrl + Mouse Right button (+ Mouse movement)

Displaying texture

The COP viewer also supports the projection of the texture data over the 3D data.

The user should activate this option select the texture source on the corresponding output panel. User can select between light or width.

After that, user can go to the 3D viewer and actiave the menu option View > Texture.