Triclops SDK
4.0.3.0
Functions
Depth map validation functions

Functions

enum TriclopsError triclopsGetBackForthValidation (const TriclopsContext context, TriclopsBool *on)
 Gets the current back-forth validation setting. More...
 
enum TriclopsError triclopsGetBackForthValidationMapping (const TriclopsContext context, unsigned char *value)
 Gets the value that appears in the disparity image for pixels that fail back-forth validation. More...
 
enum TriclopsError triclopsGetSubpixelValidationMapping (const TriclopsContext context, unsigned char *value)
 Retrieves the value that appears in the disparity image for pixels that fail subpixel validation. More...
 
enum TriclopsError triclopsGetSurfaceValidation (const TriclopsContext context, TriclopsBool *on)
 Gets the current surface validation setting. More...
 
enum TriclopsError triclopsGetSurfaceValidationDifference (const TriclopsContext context, float *diff)
 Returns maximum disparity difference. More...
 
enum TriclopsError triclopsGetSurfaceValidationMapping (const TriclopsContext context, unsigned char *value)
 Retrieves the current surface validation mapping. More...
 
enum TriclopsError triclopsGetSurfaceValidationSize (const TriclopsContext context, int *size)
 Retrieves the current validation size. More...
 
enum TriclopsError triclopsGetTextureValidation (const TriclopsContext context, TriclopsBool *on)
 Retrieves the state of the texture validation flag. More...
 
enum TriclopsError triclopsGetTextureValidationMapping (const TriclopsContext context, unsigned char *value)
 Gets the value that appears in the disparity image for pixels that fail texture validation. More...
 
enum TriclopsError triclopsGetTextureValidationThreshold (const TriclopsContext context, float *value)
 Retrieves the texture validation threshold. More...
 
enum TriclopsError triclopsSetBackForthValidation (TriclopsContext context, TriclopsBool on)
 Enables or disables back-forth validation. More...
 
enum TriclopsError triclopsSetBackForthValidationMapping (TriclopsContext context, unsigned char value)
 Sets the value that appears in the disparity image for pixels that fail back-forth validation. More...
 
enum TriclopsError triclopsSetSubpixelValidationMapping (TriclopsContext context, unsigned char value)
 Sets the value that appears in the disparity image for pixels that fail subpixel validation. More...
 
enum TriclopsError triclopsSetSurfaceValidation (TriclopsContext context, TriclopsBool on)
 Enables or disables surface validation. More...
 
enum TriclopsError triclopsSetSurfaceValidationDifference (TriclopsContext context, float diff)
 Set the maximum disparity difference. More...
 
enum TriclopsError triclopsSetSurfaceValidationMapping (TriclopsContext context, unsigned char value)
 Sets the current surface validation mapping. More...
 
enum TriclopsError triclopsSetSurfaceValidationSize (TriclopsContext context, int size)
 Sets the minimum number of pixels a surface can cover and still be considered valid. More...
 
enum TriclopsError triclopsSetTextureValidation (const TriclopsContext context, TriclopsBool on)
 Turns texture validation on or off. More...
 
enum TriclopsError triclopsSetTextureValidationMapping (TriclopsContext context, unsigned char value)
 Sets the value that appears in the disparity image for pixels that fail texture validation. More...
 
enum TriclopsError triclopsSetTextureValidationThreshold (TriclopsContext context, float value)
 Sets the texture validation threshold. More...
 

Detailed Description

Validations

In some cases, such as occlusions and lack of texture, it is not possible to establish correspondence between images. If the correspondence is not correct, the obtained measurements can not be correct. In order to avoid incorrect measurements, three validation methods are introduced:

Texture Validation

Texture validation determines whether disparity values are valid based on levels of texture in the correlation mask. If the amount of texture is not sufficient to produce correct matches, the pixel will be declared invalid.

Surface Validation

Surface validation is a filtering process designed to remove noise from the disparity image. The kind of noise removed with this process is spikes. Spikes are characteristic of mismatches in correlation-based stereo vision. The spikes can often cover a connected region of many pixels. This noise is not zero-mean, random, evenly distributed or Gaussian. The result is that this noise is difficult to remove with standard filtering techniques, as it appears to be a valid signal, instead of noise. Surface validation is a method to validate regions of a disparity image based on an assumption that they must belong to a likely physical surface in the image. The method segments the disparity image into connected regions. Any region that is less than a given size, is suspect and removed from the disparity image.

Back-forth validation

Back-forth validation performs depth computation using both frames as references and then compares the results. If the computed disparity differs by more than 1.0 pixels the disparity is marked as invalid.

Function Documentation

enum TriclopsError triclopsGetBackForthValidation ( const TriclopsContext  context,
TriclopsBool on 
)

Gets the current back-forth validation setting.

This function is used to obtain the current setting of back-forth validation.

Parameters
contextThe context to get the back-forth validation flag from
onA pointer for the returned value of the current setting of the back-forth validation flag.
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidContextThe provided context is invalid
See also
triclopsSetBackForthValidation()
enum TriclopsError triclopsGetBackForthValidationMapping ( const TriclopsContext  context,
unsigned char *  value 
)

Gets the value that appears in the disparity image for pixels that fail back-forth validation.

Parameters
contextThe context to retrieve the back-forth validation mapping value from
valueA pointer to the location for the retrieved mapping value
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidContextThe provided context is invalid
See also
triclopsGetBackForthValidationMapping()
enum TriclopsError triclopsGetSubpixelValidationMapping ( const TriclopsContext  context,
unsigned char *  value 
)

Retrieves the value that appears in the disparity image for pixels that fail subpixel validation.

Parameters
contextThe context to retrieve the subpixel validation mapping value from
valueA pointer to the location for the retrieved mapping value
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidContextThe provided context is invalid
See also
triclopsSetSubpixelValidationMapping()
enum TriclopsError triclopsGetSurfaceValidation ( const TriclopsContext  context,
TriclopsBool on 
)

Gets the current surface validation setting.

This function is used to obtain the current setting of surface validation.

Parameters
contextThe context to get the surface validation flag from
onA pointer for the returned value of the current setting of the surface validation flag.
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidContextThe provided context is invalid
See also
triclopsSetSurfaceValidation()
enum TriclopsError triclopsGetSurfaceValidationDifference ( const TriclopsContext  context,
float *  diff 
)

Returns maximum disparity difference.

This function returns the maximum disparity difference between two adjacent pixels that will still allow the two pixels to be considered part of the same surface.

Parameters
contextThe context to get the surface validation difference from
diffA pointer to the location for the retrieved surface validation difference
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidContextThe provided context is invalid
See also
triclopsSetSurfaceValidationSize()
enum TriclopsError triclopsGetSurfaceValidationMapping ( const TriclopsContext  context,
unsigned char *  value 
)

Retrieves the current surface validation mapping.

This function returns the current setting for the surface validation parameter.

Parameters
contextThe context to retrieve the surface validation mapping value from
valueA pointer to the location for the retrieved mapping value
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidContextThe provided context is invalid
See also
triclopsSetSurfaceValidationMapping()
enum TriclopsError triclopsGetSurfaceValidationSize ( const TriclopsContext  context,
int *  size 
)

Retrieves the current validation size.

This function is used to extract the surface size parameter for surface validation.

Parameters
contextThe context to get the surface validation size from
sizeA pointer to the location for the retrieved surface validation size
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidContextThe provided context is invalid
See also
triclopsSetSurfaceValidationSize()
enum TriclopsError triclopsGetTextureValidation ( const TriclopsContext  context,
TriclopsBool on 
)

Retrieves the state of the texture validation flag.

Parameters
contextThe input context.
onA pointer to the location for the retrieved texture validation flag.
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidContextThe provided context is invalid
See also
triclopsSetTextureValidation()
enum TriclopsError triclopsGetTextureValidationMapping ( const TriclopsContext  context,
unsigned char *  value 
)

Gets the value that appears in the disparity image for pixels that fail texture validation.

Parameters
contextThe context to retrieve the texture validation mapping value from
valueA pointer to the location for the retrieved mapping value
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidContextThe provided context is invalid
See also
triclopsSetTextureValidationThreshold()
enum TriclopsError triclopsGetTextureValidationThreshold ( const TriclopsContext  context,
float *  value 
)

Retrieves the texture validation threshold.

Parameters
contextThe context to retrieve the texture threshold value from
valueA pointer to the location for the retrieved texture threshold
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidContextThe provided context is invalid
See also
triclopsSetTextureValidationThreshold()
enum TriclopsError triclopsSetBackForthValidation ( TriclopsContext  context,
TriclopsBool  on 
)

Enables or disables back-forth validation.

This function is used to enable or disable back-forth validation.

Parameters
contextThe input context to set the back-forth validation flag for
onA Boolean flag indicating if back-forth validation is enabled or disabled.
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidContextThe provided context is invalid
See also
triclopsGetBackForthValidation()
enum TriclopsError triclopsSetBackForthValidationMapping ( TriclopsContext  context,
unsigned char  value 
)

Sets the value that appears in the disparity image for pixels that fail back-forth validation.

Sets the back-forth validation mapping value. This is the value that is assigned to pixels in the disparity image that fail the back-forth validation test. The range is between 0 and 255.

Parameters
contextThe context to set the back-forth validation mapping for.
valueThe new value to map invalid pixels to. The range is from 0 to 255.
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidContextThe provided context is invalid
TriclopsErrorInvalidSettingThe requested threshold is out of range [0-255]
See also
triclopsGetBackForthValidationMapping()
enum TriclopsError triclopsSetSubpixelValidationMapping ( TriclopsContext  context,
unsigned char  value 
)

Sets the value that appears in the disparity image for pixels that fail subpixel validation.

Strict subpixel validation verifies that the disparity values contribute to the subpixel interpolation make sense. By setting the mapping value to 0x??, an invalid pixel that failed this validation step will be marked 0xFF??.

Parameters
contextThe context to set the subpixel validation mapping for.
valueThe new subpixel validation mapping value. The range is from 0 to 255.
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidContextThe provided context is invalid
TriclopsErrorInvalidSettingThe requested threshold is out of range [0-255]
See also
triclopsGetSubpixelValidationMapping()
enum TriclopsError triclopsSetSurfaceValidation ( TriclopsContext  context,
TriclopsBool  on 
)

Enables or disables surface validation.

This function is used to enable or disable surface validation.

Parameters
contextThe input context to set the surface validation flag for
onA Boolean flag indicating if surface validation is enabled or disabled.
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidContextThe provided context is invalid
See also
triclopsGetSurfaceValidation()
enum TriclopsError triclopsSetSurfaceValidationDifference ( TriclopsContext  context,
float  diff 
)

Set the maximum disparity difference.

Set the maximum disparity difference between two adjacent pixels that will still allow the two pixels to be considered part of the same surface.

Parameters
contextThe context to set the surface validation size parameter for
diffThe maximum disparity difference between two adjacent pixels that will still allow the two pixels to be considered part of the same surface.
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidContextThe provided context is invalid
TriclopsErrorInvalidSettingA negative difference was given.
See also
triclopsGetSurfaceValidationDifference()
enum TriclopsError triclopsSetSurfaceValidationMapping ( TriclopsContext  context,
unsigned char  value 
)

Sets the current surface validation mapping.

Surface validation is a noise rejection method. By setting the mapping value to 0x??, an invalid pixel that failed this validation step will be marked 0xFF??.

Parameters
contextThe context to set the surface validation mapping for.
valueThe new value to map invalid pixels to. The range is from 0 to 255.
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidContextThe provided context is invalid
TriclopsErrorInvalidSettingThe requested threshold is out of range [0-255]
See also
triclopsGetSurfaceValidationMapping()
enum TriclopsError triclopsSetSurfaceValidationSize ( TriclopsContext  context,
int  size 
)

Sets the minimum number of pixels a surface can cover and still be considered valid.

This function is used to set the minimum number of pixels a surface can cover and still be considered valid. The larger the number is, the fewer surfaces will be accepted. The lower the number is, the more surfaces will be accepted. Common parameter values range from 100 to 500, depending on image resolution.

Parameters
contextThe context to set the surface validation size parameter for
sizeThe minimum number of pixels a surface can cover and still be considered valid
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidContextThe provided context is invalid
TriclopsErrorInvalidSettingA negative size was given.
See also
triclopsGetSurfaceValidationSize()
enum TriclopsError triclopsSetTextureValidation ( const TriclopsContext  context,
TriclopsBool  on 
)

Turns texture validation on or off.

Sets the context texture validation flag. When set to true, texture-based validation is enabled. Pixels that do not pass the validation test will be marked with the texture validation mapping value in the disparity image.

Parameters
contextThe input context to set the texture validation flag for
onA Texture validation flag to set, indicating if texture validation is enabled or disabled.
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidContextThe provided context is invalid
See also
triclopsGetTextureValidation()
enum TriclopsError triclopsSetTextureValidationMapping ( TriclopsContext  context,
unsigned char  value 
)

Sets the value that appears in the disparity image for pixels that fail texture validation.

Parameters
contextThe context to set the texture validation mapping for.
valueThe new value to map invalid pixels to. The range is from 0 to 255.
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidContextThe provided context is invalid
TriclopsErrorInvalidSettingThe requested threshold is out of range [0-255]
See also
triclopsGetTextureValidationThreshold()
enum TriclopsError triclopsSetTextureValidationThreshold ( TriclopsContext  context,
float  value 
)

Sets the texture validation threshold.

Sets the texture validation threshold. This threshold allows one to tune the texture-based rejection of pixels. Values range from 0.0 (no rejection) to 128.0 (complete rejection) but good operating range is between 0.0 and 2.0.

Parameters
contextThe context to set the texture validation threshold for
valueThe new texture validation threshold.
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidContextThe provided context is invalid
TriclopsErrorInvalidSettingThe requested threshold is out of range [0.0-128.0]
See also
triclopsGetTextureValidationThreshold()
Contact Support Triclops SDK Programmer's Guide and API Reference