Triclops SDK
4.0.3.0
Functions
Image rectification functions

Functions

enum TriclopsError triclopsColorRectify (TriclopsContext context, TriclopsColorStereoPair *input)
 Prepares the internal color image buffers for depth computation. More...
 
enum TriclopsError triclopsGetEdgeCorrelation (const TriclopsContext context, TriclopsBool *on)
 Retrieves the current edge pre-processing status for a context. More...
 
enum TriclopsError triclopsGetEdgeMask (const TriclopsContext context, int *masksize)
 Retrieves the current edge pre-processing mask size. More...
 
enum TriclopsError triclopsGetRectify (const TriclopsContext context, TriclopsBool *on)
 Retrieves the state of the rectification feature. More...
 
enum TriclopsError triclopsRectify (TriclopsContext context, TriclopsMonoStereoPair *input)
 Prepares the internal image buffers for depth computation. More...
 
enum TriclopsError triclopsRectifyColorImage (TriclopsContext context, TriclopsCamera camera, TriclopsColorStereoPair *input, TriclopsColorImage *output)
 Rectifies a raw color image. More...
 
enum TriclopsError triclopsRectifyPixel (const TriclopsContext context, TriclopsCamera camera, float rowIn, float colIn, float *rowOut, float *colOut)
 Converts a pixel location from the unrectified image to that of the rectified image. More...
 
enum TriclopsError triclopsSetEdgeCorrelation (TriclopsContext context, TriclopsBool on)
 Switches edge pre-processing on or off. More...
 
enum TriclopsError triclopsSetEdgeMask (TriclopsContext context, int masksize)
 Sets a new edge pre-processing mask size. More...
 
enum TriclopsError triclopsSetRectify (TriclopsContext context, TriclopsBool on)
 Turns rectification on or off. More...
 
enum TriclopsError triclopsUnrectifyPixel (const TriclopsContext context, TriclopsCamera camera, float rowIn, float colIn, float *rowOut, float *colOut)
 Converts a pixel location from the rectified image to that of the unrectified image. More...
 

Detailed Description

The functions in this group perform various image processing techniques on side-by-side buffers as specified by rectification settings. Depending on the settings the processing techniques used can be:

Rectification

Rectification is the process of correcting input images for the distortions of the lenses. Lenses often cause distortions in raw images. For example, straight lines in the scene will often appear curved in the raw images. This effect will be particularly evident in the corners of the images. Rectified images will be corrected for these kinds of distortions.

Further, rectified images will be corrected so that the rows of images digitized from horizontally displaced cameras are aligned, and similarly that the columns of images obtained from vertically displaced cameras are aligned. Without this feature, searching along the rows and columns will not produce the correct results.

Edge detection

Edge detection is an optional feature that allows matching on the changes in the brightness rather than the absolute values of the pixels in the images. This feature is useful because the cameras in the Triclops camera module have auto gain control. If the auto gains in the cameras do not change identically, the absolute brightness between images may not be the same. While absolute brightness are not the same, the change in the intensity stays constant. Therefore, using edge detection will help in environments where the lighting conditions change significantly.

While edge detection may improve results, there is an additional processing cost that is associated with it. Therefore the user needs to evaluate the result improvement when choosing to turn edge detection on.

Function Documentation

enum TriclopsError triclopsColorRectify ( TriclopsContext  context,
TriclopsColorStereoPair input 
)

Prepares the internal color image buffers for depth computation.

This function performs the same operations as triclopsRectify(), but processes colored images. Rectified color buffers are internally converted to monochrome before depth computation.

Parameters
contextThe context where to retrieve the processing settings and where to store the results
inputThe side-by-side color structure to process
See also
TriclopsMonoStereoPair
triclopsColorRectify()
triclopsBuildColorStereoPairFromBuffers()
triclopsBuildColorStereoPairFromFile()
triclopsGetImage()
triclopsGetColorImage()
triclopsSetEdgeCorrelation()
triclopsSetEdgeMask()
triclopsSetRoi()
triclopsSetRectify()
triclopsStereo()
enum TriclopsError triclopsGetEdgeCorrelation ( const TriclopsContext  context,
TriclopsBool on 
)

Retrieves the current edge pre-processing status for a context.

Parameters
contextThe context from which to get the status of edge pre-processing
onThe retrieved status
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidContextThe provided context is invalid
See also
triclopsSetEdgeCorrelation()
enum TriclopsError triclopsGetEdgeMask ( const TriclopsContext  context,
int *  masksize 
)

Retrieves the current edge pre-processing mask size.

Parameters
contextThe context from which to set the edge mask size
masksizeThe retrieved mask size
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidContextThe provided context is invalid
See also
triclopsSetEdgeMask()
enum TriclopsError triclopsGetRectify ( const TriclopsContext  context,
TriclopsBool on 
)

Retrieves the state of the rectification feature.

Parameters
contextThe context.
onA pointer to a Boolean that will store the current setting..
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully.
TriclopsInvalidContextThe input context is invalid.
See also
triclopsSetRectify()
enum TriclopsError triclopsRectify ( TriclopsContext  context,
TriclopsMonoStereoPair input 
)

Prepares the internal image buffers for depth computation.

All the resulting processed frames are stored in the provided context. The processed frames can be retrieved using triclopsGetImage().

This function has to be called before triclopsStereo otherwise that function will return an error code.

Parameters
contextThe context where to retrieve the processing settings and where to store the results
inputThe side-by-side structure to process
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidStereoInputThe provided side-by-side structure has one or more invalid internal values
TriclopsErrorSizeStereoInputImagesMismatchThe two images contained in the provided side-by-side structure have different resolutions
TriclopsErrorSensorCalibratedAreaOutsideInputThe sensor calibrated area is not completely overlapped with the source image
TriclopsErrorInvalidSourceResolutionThe resolution of the provided source is invalid (i.e. either dimension is smaller than 1)
TriclopsErrorInvalidResolutionThe requested output resolution is invalid (i.e. either dimension is smaller than 1)
TriclopsErrorInvalidROIThe ROI requested is either invalid or is not completely overlapped with the source image
TriclopsErrorRoiAndOutputAspectRatioMismatchThe aspect ratio of the requested ROI and the requested output are different
TriclopsErrorStereoInputAndOutputResolutionMismatchThe resolution of the frames forming the side-by-side image and the output resolution are different. This error is returned only when rectification has been deactivated.
TriclopsErrorRoiAndOutputResolutionMismatchThe resolution of the frames forming the side-by-side image and the selected ROI are different. This error is returned only when rectification has been deactivated.
TriclopsErrorBadMemoryAllocationThe system returned an allocation error while creating one of the internal buffers (i.e. Edge or Rectified buffers) or while requesting more memory for rectification warpers
TriclopsErrorInvalidInternalSettingOne of the internal settings used for the generation of the rectification warpers is not valid.
TriclopsErrorGenerationRectifyDataThe library was not able to generate one or more rectification warpers.
TriclopsErrorInvalidContextThe provided context is either invalid or contains one or more invalid rectification warpers.
See also
TriclopsMonoStereoPair
triclopsColorRectify()
triclopsBuildMonoStereoPairFromBuffers()
triclopsBuildMonoStereoPairFromFile()
triclopsGetImage()
triclopsSetEdgeCorrelation()
triclopsSetRectify()
triclopsSetRoi()
triclopsStereo()
enum TriclopsError triclopsRectifyColorImage ( TriclopsContext  context,
TriclopsCamera  camera,
TriclopsColorStereoPair input,
TriclopsColorImage output 
)

Rectifies a raw color image.

This function will rectify a 32-bit color image corresponding to a raw image composing the color side-by-side structure of the stereo input. It is useful for creating rectified color images for display.

Parameters
contextThe context where to retrieve the processing settings and to rectify the requested raw color image
cameraThe camera from which the raw image originated
inputA pointer to the side-by-side color stereo input to process
outputA pointer to the rectified color image
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully.
TriclopsInvalidContextThe provided context is either invalid or contains one or more invalid rectification warpers
TriclopsErrorInvalidCameraThe chosen camera is invalid
TriclopsErrorInvalidStereoInputThe provided side-by-side structure has one or more invalid internal values
TriclopsErrorSensorCalibratedAreaOutsideInputThe sensor calibrated area is not completely overlapped with the source image
TriclopsErrorSizeStereoInputImagesMismatchThe two images contained in the provided side-by-side structure have different resolutions
TriclopsErrorInvalidSourceResolutionThe resolution of the provided source is invalid (i.e. either dimension is smaller than 1)
TriclopsErrorInvalidResolutionThe requested output resolution is invalid (i.e. either dimension is smaller than 1)
TriclopsErrorInvalidROIThe ROI requested has one or more invalid internal values or is not completely overlapped with the source image
TriclopsErrorRoiAndOutputAspectRatioMismatchThe aspect ratio of the requested ROI and the requested output are different
TriclopsErrorInvalidInternalSettingAn internal invalid setting occurred
TriclopsErrorNeitherSingleNorSideBySideImageThe raw image relative to the selected camera is neither a single nor a side-by-side image
See also
TriclopsColorStereoPair
TriclopsColorImage
triclopsColorRectify()
enum TriclopsError triclopsRectifyPixel ( const TriclopsContext  context,
TriclopsCamera  camera,
float  rowIn,
float  colIn,
float *  rowOut,
float *  colOut 
)

Converts a pixel location from the unrectified image to that of the rectified image.

This function converts coordinates of a pixel location from the unrectified image to those of the rectified image. The source and output image dimensions must have been previously set either via a call to triclopsPrepareRectificationData() or via a call to triclopsSetSourceResolution followed by triclopsSetResolution. Note that if ROI processing is enabled, both input and output pixel locations refer to the ROI coordinate system

Parameters
contextThe context where to retrieve the processing settings and to convert pixel coordinayes
cameraThe camera for which the pixel should be rectified
rowInThe row coordinate of the location of the pixel to rectify.
colInThe column coordinate of the location of the pixel to rectify.
rowOutA pointer to the row coordinate of the location of the rectified pixel.
colOutA pointer to the column coordinate of the location of the rectified pixel.
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully.
TriclopsInvalidContextThe provided context is either invalid or contains one or more invalid rectification warpers
TriclopsErrorInvalidCameraThe chosen camera is invalid
TriclopsErrorInvalidSourceResolutionThe resolution of the provided source is invalid (i.e. either dimension is smaller than 1)
TriclopsErrorBadMemoryAllocationThe system returned an allocation error while requesting memory for rectification warp functions or warpers
TriclopsErrorInvalidCoordinatesThe input pixel coordinates are invalid.
See also
triclopsRectify()
triclopsUnrectifyPixel()
triclopsSetSourceResolution()
triclopsSetResolution()
triclopsPrepareRectificationData()
enum TriclopsError triclopsSetEdgeCorrelation ( TriclopsContext  context,
TriclopsBool  on 
)

Switches edge pre-processing on or off.

Edge pre-processing is required for texture validation.

Parameters
contextThe context for which to enable/disable edge pre-processing
onWhether edge-preprocessing should be on or off
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidContextThe provided context is invalid
See also
triclopsGetEdgeCorrelation()
triclopsSetTextureValidation()
enum TriclopsError triclopsSetEdgeMask ( TriclopsContext  context,
int  masksize 
)

Sets a new edge pre-processing mask size.

Parameters
contextThe context for which to set the edge mask size
masksizeThe new mask size, which needs to be an odd number between 3 and 11
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidContextThe provided context is invalid
TriclopsErrorInvalidSettingThe provided mask size is invalid
See also
triclopsGetEdgeMask()
enum TriclopsError triclopsSetRectify ( TriclopsContext  context,
TriclopsBool  on 
)

Turns rectification on or off.

Parameters
contextThe input context.
onA Boolean indicating whether rectification should be turned on or off.
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully.
TriclopsInvalidContextThe input context is invalid.
See also
triclopsGetRectify()
enum TriclopsError triclopsUnrectifyPixel ( const TriclopsContext  context,
TriclopsCamera  camera,
float  rowIn,
float  colIn,
float *  rowOut,
float *  colOut 
)

Converts a pixel location from the rectified image to that of the unrectified image.

This function converts coordinates of a pixel location from the rectified image to those of the unrectified image coordinates.

This version will accommodate input rectified pixel locations that are outside of the normal rectified image bounds, as long as the corresponding unrectified location is within its own image bounds. The source and output image dimensions must have been previously set either via a call to triclopsPrepareRectificationData() or via a call to triclopsSetSourceResolution followed by triclopsSetResolution. Note that if ROI processing is enabled, both input and output pixel locations refer to the ROI coordinate system

Parameters
contextThe context where to retrieve the processing settings and to convert pixel coordinayes
cameraThe camera for which the pixel should be unrectified
rowInThe row coordinate of the location of the pixel to unrectify.
colInThe column coordinate of the location of the pixel to unrectify.
rowOutA pointer to the row coordinate of the location of the unrectified pixel.
colOutA pointer to the column coordinate of the location of the unrectified pixel.
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully.
TriclopsInvalidContextThe provided context is either invalid or contains one or more invalid rectification warpers
TriclopsErrorInvalidCameraThe chosen camera is invalid
TriclopsErrorInvalidSourceResolutionThe resolution of the provided source is invalid (i.e. either dimension is smaller than 1)
TriclopsErrorBadMemoryAllocationThe system returned an allocation error while requesting memory for rectification warp functions or warpers
TriclopsErrorInvalidCoordinatesThe input pixel coordinates are invalid.
See also
triclopsRectifyPixel()
triclopsSetSourceResolution()
triclopsSetResolution()
triclopsPrepareRectificationData()
Contact Support Triclops SDK Programmer's Guide and API Reference