 |
Sensor API v2.5.0
|
|
Sensor API v2.5.0
|
This page clarifies usage of sensor parameters in the SDK.
The sensor works either in peak or raw data mode. Changing of mode during grabbing is a slow operation (typically about 1 second).
Typically peak mode is used. In this mode the sensor processes a raw image and provides points to the application. Each point output contains x coordinate, height and intensity values.
Example of received 3D points when two grooves are measured:
In a raw mode gray scale image from the sensor is captured. This mode is useful when sensor capabilities are studied.
Example of raw image where two grooves are measured:
C++:
C#:
Maximum size of the raw image equals sensor size. Sensor size for LCI401, LCI1200, LCI1201 and LCI1600 sensors is 1088 (vertical) x 2048 (horizontal) pixels. For LCI2020 and LCI1620 sensors size is 1400 (vertical) x 1728 (horizontal) pixels.
Maximum frequency of raw image is limited by the Ethernet interface. Required throughput can be calculated by formula image_height x 2048 x imaging_frequency.
Disable peak mode:
C++:
C#:
The sensor is calibrated in the FocalSpec's production to produce exact micrometer coordinates. Calibration files are stored in the sensors for those which are manufactured after 02/2019. If files are not in the sensor those must be set before image grabbing.
The sensor must be in the peak mode when calibration files are used. After files are set sensor unit must be set to use micrometers. If unit is not changed pixel units without calibration are used.
Following examples check whether calibration files exist in the sensor or not. If files exist only peak unit change is needed.
C#:
C++:
C#:
Camera works either in internal (free run) or external pulsing mode. In free run mode user can set imaging frequency. In external pulsing mode frequency is set to 0 and the frequency is defined by an external triggering to the camera I/O. Maximum imaging frequency is limited by
Maximum camera frequency is increased when depth of field is decreased. Following formulas can be used to calculate maximum window height in pixels when a frequency is known.
Recommended way to calculate maximum frequency is to use _AdjustRoiAndFps() function.
For LCI401, LCI1200, LCI1201 and LCI1600 sensors maximum frequency is 5000 Hz and height can be calculate with the following equation: int height = (int)(47.5 / 129 * (1e6 / frequency - 1548 / 47.5)); Safety margin. height -= (int)(0.2 * height);
See Depth of Field chapter to map height into micrometers.
For LCI401, LCI1200, LCI1201 and LCI1600 sensors LED pulse duration must be at least 100 us less than minimum interval between two image captures. For example, if maximum imaging frequency is 500 Hz maximum LED pulse duration is (1/500 Hz) * 1000 * 1000-100 us = 1900 us.
For LCI1220 and LCI1620 sensors LED pulse duration must be at least 31 us less than minimum interval between two image captures.
Recommended way to calculate maximum led pulse duration is to use _AdjustRoiAndFps() function.
In peak mode required ethernet throughput can be calculated by following formula: imaging_frequency * 64 bits/points * points_per_frame
For example, if we have two surfaces and imaging frequency is 500 Hz resulting Ethernet throughput is
In raw mode required throughput is:
Sensor's maximum imaging frequency can be increased by decreasing the image height.
Recommended way to adjust PARAM_IMAGE_HEIGHT and PARAM_IMAGE_OFFSETY parameters is to use _AdjustRoiAndFps() function with SetRoiForFps or RoiOperation.SetFpsForRoi attribute.
Example to adjust imaging height and offset when maximum imaging frequency is known:
Example to adjust imaging height and offset when needed depth of field is known. The maximum imaging frequency is returned.
Amount of light in the sensor can adjusted in three ways
Usually exposure is controlled by setting proper value for the LED pulse width. Width is given as microseconds typically varying between 1 us (high gloss, such as a mirror surface) and 100 us, but it can be also higher in low gloss surfaces.
C++:
C#:
AGC is a camera function to adjust LED pulse width automatically to a proper value. This functionality can be used if the surface is continuous and no rapid changed are expected. The controller continuously calculates average intensity value of measured 3D points and compares this value to predefined value. LED pulse width is adjusted to minimize the error between measured and predefined value. Adjusted LED pulse width can be read from Header.PulseWidth of each received profile.
C++:
C#:
Used current for the LED lighting can be tuned. There are separate values for edge and center areas of the illuminator which can be used to smooth the illumination profile. Typically 1 ampere current is used.
C++:
C#:
The gain controls the amplification of the signal from the camera sensor. When the gain is increased also background noise is increased. Typically there is no need to change default gain value.
For LCI401, LCI1200, LCI1201 and LCI1600 sensors the default gain value is 1 and the range is 1.0 - 3.2. For LCI1220 and LCI1620 sensors the default gain value is 2 and the range is 2.0 - 8.0.
C++:
C#:
3D points detection starts with applying Signal Detection Filter to the signal. If the averaged value is greater than a specified threshold a peak is detected. After that exact location of the peak is calculated with FIR. Finally, an average peak intensity is calculated with Average Intensity Filter. Length of filters and threshold are user configurable. Usually filter length 16 gives the best results if material type is opaque. A shorter value may be needed if highly glossy surface (like mirror) is measured. Also, transparent surfaces may need lower values since layers needs to be separated from each other.
User has a possibility to select which intensity value is returned per layer. This is useful in multilayer surfaces where some layers might be thinner.
Parameters:
Recommended way to set all peak detection parameters is to use _SetPeakDetectionParameters() function.
C++:
C#:
After _SetPeakDetectionParameters() function threshold and filter parameters can be tuned.
By default intensity is calculated with Average Intensity Filter. If transparent material has a thin layer the filter might be too large. In order to reduce crosstalk user can select filter for each layer separately.
This chapter applies only for LCI401, LCI1200, LCI1201 and LCI1600 sensors. In LCI1220 and LCI1620 sensors reordering is not needed.
Received profiles are not guaranteed to arrive in order without reordering. All profiles have a header where order is in header->index attribute. Normally index increases linearly but sometimes there are out of order profiles caused by the Ethernet buffering.
You have two options to do reordering. One is to check the index in the application and do necessary processing, or you can enable reordering in the FS SDK.
FS SDK's reordering functionality buffers profiles until all are in order. Downside of reordering is that if packets are out of order jitter of the profiles will be increase.
Reordering uses 500 ms timeout for waiting pending packets. All received profiles are delivered to the application even though the timeout is expired. This is very unlikely but may happen if the PC is stalled longer than the timeout.
Reordering could be useful to activate on the cased when higher reception frequency ~5000Hz are used and frames are constantly being delivered not in order.
C++:
C#:
The trigger inputs can be used to synchronize the sensor with an external device. Application examples include: synchronizing the profile measurement into a certain signal of a production process or combining profiles into 3D point clouds based on the trigger index.
To measure the profile at each trigger event, input A should be used (input B is unconnected and is pulled down internally). This way every rising edge of the A signal triggers a measurement. The figure below shows the timing diagram of A and B signals when connected to a quadrature encoder. Only the B forwards triggers the measurement, because the B channel is on low state at the moment of a rising edge of the A channel.
Timing diagram of a quadrature encoder:
External logic B enables trigger A at edges 5-7: Another way of configuring the encoder inputs is shown in the figure below. B input of the encoder can be used as a disable signal. On every rising edge of the encoder input signal A, the edge is accepted as a trigger if the encoder input signal B is simultaneously at a low state. An external logic can be used to generate B signal. B signal can be used, for example, to disable measurement during a relocation of the sensor.
Any of inputs 1-4 can be configured as A, B and Zero input. Input state is also transferred to PC embedded in each peak frame and can be used as general-purpose input that way. The sensor keeps count of the trigger location internally and embeds this information for each frame. Every rising edge of the A input, while the B input is in low state, increases location count. Every rising edge of the A input, while the B input is in high state, decreases location count. A rising edge of the Zero input.
FS API default input source definitions:
PARAM_TRIGGER_SOURCE default is 1.
PARAM_TRIGGER_DISABLE_SOURCE default is 2.
PARAM_TRIGGER_ZERO_SOURCE default is 3.
PARAM_REG_PULSE_DIVIDER default is 1.
C++:
C#:
Points in transparent surfaces are sorted to different layers according to z-coordinate. Problem is that if the first layer point is missing second layer point is detected as a first layer point. This feature improves classification by using prior information about the surface.
Missing first layer is detected by setting following parameters:
FSSDK provides possibility to use a priori information to enhance missing layer detection.
Maximum layer thickness (PARAM_LAYER_MAX_THICKNESS) can be set for each layer
HDR imaging is supported by the sensor and it might be useful in situations where the target has high level of contrast.
If HDR is not used in high contrast cases, exposuring dark areas with a proper LED length saturates bright areas. This might cause reduced accuracy of detected peaks.
If HDR is used, no bright pixels are saturating and the relative order of brightness is maintained between all pixels. This improves accuracy of detected peaks.
Pixel intensity without HDR:
If HDR is enabled sensor sensitivity is dropped approximately 20%. Only values below are supported. Behavior of other values is not tested.
This functionality fills areas which are not measured with interpolated points.
PARAM_FILL_GAP_X_MAX Defines maximum gap of missing measurement points filled by interpolation. If 0, interpolation feature is disabled.
Additionally a user can configure z difference of the gap area:
PARAM_LAYER_MIN_THICKNESS parameter defines maximum Z difference for interpolated points. For opaque materials, a user can set parameter for the first layer.
If PARAM_LAYER_MIN_THICKNESS is 0 (default behavior), the missing area is interpolated except areas where the gap is less than 4 pixels wide. In those cases interpolation is not used when the Z difference is big.
Trim Edges filter is indented to remove artificial points detected at the end of the surfaces. The filter can be disabled/enabled at runtime in the line callback function and it takes effect on the next processed profiles
The filter works optimally for those edges which are clearly visible. It may remove real points if edges are gradually disappearing. Therefore, it is recommended to use the filter only for profiles which have clear edges. Additionally, it might be useful to use PARAM_FILL_GAP_X_MAX parameter to fill not measured areas on the edge.
Filtering is done for each profile separately which means that only horizontal edges are trimmed.
Following issues are handled with the filter:
Loading a recipe is the recommended way to configure the sensor at application startup and during the parameter set change. For online changes, user shall use the SetParameter/GetParameter functions.
A typical use case for the recipe is following (this is how FSSDK GuiExample works):
In another use case the application only uses the recipe (this is how FSSDK ConsoleExample works):
Following steps are needed for the sensor initialization with a recipe.
1) Open()-function to discover sensors and Connect()-function to set IP addresses
2) Check is the calibration available in the sensor.
3) Load a recipe
4) Set image acquisition parameters which are not defined in the recipe. For example:
A strong surface texture may cause edge artifacts in Z values. In order to reduce edge artifacts the sensor can be calibrated for Z-Compensation.
An example of calibration procedure is implemented in FieldCalibrationTool. The tool can be used as is or it can be customized by using provided source codes.
Z-Compensation can be enabled separately for X or Y direction. Y direction means moving direction acquisition with external triggering. Typically, both X and Y direction are needed for compensation calculation.
Note that Z-Compensation in Y direction is available only for BatchCallback data and there is no effect on LineCallback data. Additionally PARAM_MOVING_DIRECTION and PARAM_ENCODER_PULSE_WIDTH parameters need to be set properly when Y direction compensation is used.
A calibration file is read when the user enables either compensation direction. By default, calibration file location is the same as other calibration files (C:\FocalSpec\Calibration). If calibration used this path there is no need to set the file manually. Optionally users can set full path with paramter PARAM_SENSOR_Z_COMPENSATION_FILE .
In console example application X and Y compensations are enabled for batch call back function:
For some materials it might be beneficial to adjust Z-compensation algorithm. User can increase or decrease Z-compensation effect by following multipliers: PARAM_Z_COMPENSATION_X_BRIGHT_TO_DARK_MUL, PARAM_Z_COMPENSATION_X_DARK_TO_BRIGHT_MUL, PARAM_Z_COMPENSATION_Y_BRIGHT_TO_DARK_MUL, PARAM_Z_COMPENSATION_Y_DARK_TO_BRIGHT_MUL.
User has an option remove points where calculated Z-Compensation is big. This is useful feature if the material has a strong texture and compensation is suboptimal for those points. The feature can be used with parameter PARAM_Z_COMPENSATION_THRESHOLD.
If points are removed by PARAM_Z_COMPENSATION_THRESHOLD feature, empty areas can be interpolated by using neighboring points. Interpolation can be enabled with parameter PARAM_Z_COMPENSATION_INTERPOLATE.
1.8.13