Triclops SDK
4.0.3.0
Functions
Disparities to 3D coordinates transformation functions

Functions

enum TriclopsError triclopsCreateImage3d (TriclopsContext context, TriclopsImage3d **ppimage)
 Initialises a 3D image structure. More...
 
void triclopsDestroyImage3d (TriclopsImage3d **ppimage)
 Destroys a 3D image structure. More...
 
enum TriclopsError triclopsExtractImage3d (TriclopsContext context, TriclopsImage3d *pimage)
 Generates a 3D point cloud in camera space from the provided context. More...
 
enum TriclopsError triclopsExtractWorldImage3d (TriclopsContext context, TriclopsImage3d *pimage)
 Generates a 3D point in world space cloud from the provided context. More...
 
enum TriclopsError triclopsGetTransformFromFile (const char *fileName, TriclopsTransform *transform)
 Loads a 3D world coordinates rototranslation matrix from memory. More...
 
enum TriclopsError triclopsGetTriclopsToWorldTransform (TriclopsContext context, TriclopsTransform *transform)
 Gets the 3D world coordinates rototranslation matrix to a TriclopsContext. More...
 
enum TriclopsError triclopsRCD16ToWorldXYZ (TriclopsContext context, int row, int col, unsigned short disp, float *x, float *y, float *z)
 Converts a 2D pixel coordinate in disparity space to a 3D point in world coordinate system. More...
 
enum TriclopsError triclopsRCD16ToXYZ (TriclopsContext context, int row, int col, unsigned short disp, float *x, float *y, float *z)
 Converts a 2D pixel coordinate in disparity space to a 3D point in camera coordinate system. More...
 
enum TriclopsError triclopsRCDFloatToWorldXYZ (TriclopsContext context, float row, float col, float disp, float *x, float *y, float *z)
 Converts a 2D pixel coordinate in disparity space to a 3D point in world coordinate system. More...
 
enum TriclopsError triclopsRCDFloatToXYZ (TriclopsContext context, float row, float col, float disp, float *x, float *y, float *z)
 Converts a 2D pixel coordinate in disparity space to a 3D point in camera coordinate system. More...
 
enum TriclopsError triclopsRCDToWorldXYZ (TriclopsContext context, float row, float col, float disp, float *x, float *y, float *z)
 Converts a 2D pixel coordinate in disparity space to a 3D point in world coordinate system. More...
 
enum TriclopsError triclopsRCDToXYZ (TriclopsContext context, float row, float col, float disp, float *x, float *y, float *z)
 Converts a 2D pixel coordinate in disparity space to a 3D point in camera coordinate system. More...
 
enum TriclopsError triclopsSetTriclopsToWorldTransform (TriclopsContext context, const TriclopsTransform *transform)
 Sets the 3D world coordinates rototranslation matrix to a TriclopsContext. More...
 
enum TriclopsError triclopsWorldXYZToRCD (TriclopsContext context, float x, float y, float z, float *row, float *col, float *disp)
 Converts a 3D point in world coordinate system to a 2D pixel coordinate in disparity space. More...
 
enum TriclopsError triclopsWriteTransformToFile (const char *fileName, const TriclopsTransform *transform)
 Saves a 3D world coordinates rototranslation matrix to memory. More...
 
enum TriclopsError triclopsXYZToRCD (TriclopsContext context, float x, float y, float z, float *row, float *col, float *disp)
 Converts a 3D point in camera coordinate system to a 2D pixel coordinate in disparity space. More...
 

Detailed Description

2D Disparity space, 3D Camera space and 3D World space

The disparity values computed by the stereo computation functions provided by Triclops, together with their xy position inside the depth map, generate an imaginary space (disparity space) where distances from the camera are represented by how many pixels is one pixel in the reference (i.e. right) frame distant from itself in the slave (i.e. left) frame. The 3D representation used by Triclops is the one shown in the figure below:

stereo_3D_01.png
Image and world coordinate systems in the Triclops library

Triclops provides a set of functions to transform 2D coordinates in disparity space into 3D coordinates, either in camera coordinates (i.e. with the axes origin set [0,0,0] set at the optical center of the right sensor) or in world coordinates. The world coordinates are computed by applying a homogeneous 3D rototranslation to the 3D coordinates in camera space. If the rototranslation matrix is not set both camera and world coordinates computation functions, given the same 2D pixel with the same disparity value, return the same 3D point.

Rototranslation.png
Homogeneous 4x4 rototranslation matrix

The rototranslation matrix is a 4x4 homogeneous matrix as the one shown above, where 'alpha' is the yaw (y-axis rotation), 'beta' is the pitch (x-axis rotation), 'gamma' is the roll (z-axis rotation); while xt, yt and zt are the translations along the three axes.

See also
TriclopsTransform

3D Images

Often it is useful to convert an entire disparity map to a 3D point cloud, where all the validated disparities are represented as a point in space. To help in this task Triclops provides the TriclopsImage3d structure, which is a two-dimensional matrix containing 3D points.

See also
TriclopsImage3d

Function Documentation

enum TriclopsError triclopsCreateImage3d ( TriclopsContext  context,
TriclopsImage3d **  ppimage 
)

Initialises a 3D image structure.

The function initialises a TriclopsImage3d based on the output resolution set in the provided TriclopsContext. This function is useful when trying to generate a full 3D point cloud based on the output of a depth map generated using the provided context.

Parameters
contextThe context the 3D image is initialized for
ppimageThe 3D image to initialize
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
See also
triclopsDestroyImage3d()
triclopsExtractImage3d()
void triclopsDestroyImage3d ( TriclopsImage3d **  ppimage)

Destroys a 3D image structure.

Parameters
ppimageThe 3D image to destroy
enum TriclopsError triclopsExtractImage3d ( TriclopsContext  context,
TriclopsImage3d pimage 
)

Generates a 3D point cloud in camera space from the provided context.

The function generates a 3D point cloud in camera space using all the valid disparities contained in the disparity buffer in the provided TriclopsContext. This function requires triclopsStereo() to be called at least once before generating a 3D point cloud.

Every invalid disparity will be given a 3D coordinate of [0, 0, 0].

Parameters
contextThe context where to retrieve the disparity map to convert
pimageThe 3D image to fill with the generated point cloud
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsError3dImageSizeAndOutputResolutionMismatchThe output resolution and the resolution of the 3D image are not the same
TriclopsErrorDisparityMapAndOutputResolutionMismatchThe output resolution and the resolution of teh disparity map are not the same
TriclopsErrorInvalidContextThe provided context is invalid
See also
triclopsCreateImage3d()
enum TriclopsError triclopsExtractWorldImage3d ( TriclopsContext  context,
TriclopsImage3d pimage 
)

Generates a 3D point in world space cloud from the provided context.

This function computes the 3D point cloud in camera coordinate system using triclopsExtractImage3d() and then applies the rototranslation matrix (set using triclopsSetTriclopsToWorldTransform()) contained in the provided context to the point cloud.

Parameters
contextThe context where to retrieve the disparity map to convert
pimageThe 3D image to fill with the generated point cloud
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsError3dImageSizeAndOutputResolutionMismatchThe output resolution and the resolution of the 3D image are not the same
TriclopsErrorDisparityMapAndOutputResolutionMismatchThe output resolution and the resolution of teh disparity map are not the same
TriclopsErrorInvalidContextThe provided context is invalid
See also
triclopsCreateImage3d()
enum TriclopsError triclopsGetTransformFromFile ( const char *  fileName,
TriclopsTransform transform 
)

Loads a 3D world coordinates rototranslation matrix from memory.

The file containing the rototranslation matrix needs to have the ".trans" extension, otherwise the function will not recognise the file as valid.

Parameters
fileNameThe path, either relative or absolute, to the matrix file
transformThe 4x4 matrix to fill with the data contained in the file
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorCorruptTransformFileThe provided file path points to either an invalid transform file or to a file with the wrong extension.
See also
triclopsSetTriclopsToWorldTransform()
enum TriclopsError triclopsGetTriclopsToWorldTransform ( TriclopsContext  context,
TriclopsTransform transform 
)

Gets the 3D world coordinates rototranslation matrix to a TriclopsContext.

Parameters
contextThe Triclops context that contains the matrix
transformThe destination 4x4 rototranslation
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidContextThe provided context is invalid
See also
triclopsSetTriclopsToWorldTransform()
enum TriclopsError triclopsRCD16ToWorldXYZ ( TriclopsContext  context,
int  row,
int  col,
unsigned short  disp,
float *  x,
float *  y,
float *  z 
)

Converts a 2D pixel coordinate in disparity space to a 3D point in world coordinate system.

This function acts exactly like triclopsRCDFloatToXYZ() but takes a fixed point (i.e. 12.4 short integer) as disparity value.

enum TriclopsError triclopsRCD16ToXYZ ( TriclopsContext  context,
int  row,
int  col,
unsigned short  disp,
float *  x,
float *  y,
float *  z 
)

Converts a 2D pixel coordinate in disparity space to a 3D point in camera coordinate system.

This function acts exactly like triclopsRCDFloatToXYZ() but takes a fixed point (i.e. 12.4 short integer) as disparity value.

enum TriclopsError triclopsRCDFloatToWorldXYZ ( TriclopsContext  context,
float  row,
float  col,
float  disp,
float *  x,
float *  y,
float *  z 
)

Converts a 2D pixel coordinate in disparity space to a 3D point in world coordinate system.

This function computes the 3D point in camera coordinate system using triclopsRCDFloatToXYZ() and then applies the rototranslation matrix (set using triclopsSetTriclopsToWorldTransform()) contained in the provided context to the point.

Parameters
contextThe Triclops context used to compute disparities
rowThe y location of the input pixel
colThe x location of the input pixel
dispThe disparity value computed for the input pixel
xThe resulting x coordinate of the pixel in world coordinate system
yThe resulting y coordinate of the pixel in world coordinate system
zThe resulting z coordinate of the pixel in world coordinate system
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidCoordinatesThe provided 2D coordinates are invalid
TriclopsErrorInvalidDisparityValueThe provided disparity value is invalid (i.e. less or equal than 0 or plain invalid)
TriclopsErrorInvalidContextThe provided context is invalid
See also
triclopsSetTriclopsToWorldTransform()
triclopsRCD16ToWorldXYZ()
enum TriclopsError triclopsRCDFloatToXYZ ( TriclopsContext  context,
float  row,
float  col,
float  disp,
float *  x,
float *  y,
float *  z 
)

Converts a 2D pixel coordinate in disparity space to a 3D point in camera coordinate system.

This function uses a disparity value in floating point (i.e. already converted from the 12.4 fixed-point format to its decimal value) and returns the coordinate of a point in 3D space.

Parameters
contextThe Triclops context used to compute disparities
rowThe y location of the input pixel
colThe x location of the input pixel
dispThe disparity value computed for the input pixel
xThe resulting x coordinate of the pixel in camera coordinate system
yThe resulting y coordinate of the pixel in camera coordinate system
zThe resulting z coordinate of the pixel in camera coordinate system
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidCoordinatesThe provided 2D coordinates are invalid (i.e. less that zero or larger that the current outut resolution)
TriclopsErrorInvalidDisparityValueThe provided disparity is invalid (i.e. less or equal than 0 or plain invalid)
TriclopsErrorInvalidContextThe provided context is invalid
See also
triclopsRCD16ToXYZ()
enum TriclopsError triclopsRCDToWorldXYZ ( TriclopsContext  context,
float  row,
float  col,
float  disp,
float *  x,
float *  y,
float *  z 
)

Converts a 2D pixel coordinate in disparity space to a 3D point in world coordinate system.

This function has been kept for retro-compatibility and is an alias for triclopsRCDFloatToWorldXYZ()

enum TriclopsError triclopsRCDToXYZ ( TriclopsContext  context,
float  row,
float  col,
float  disp,
float *  x,
float *  y,
float *  z 
)

Converts a 2D pixel coordinate in disparity space to a 3D point in camera coordinate system.

This function has been kept for retro-compatibility and is an alias for triclopsRCDFloatToXYZ().

enum TriclopsError triclopsSetTriclopsToWorldTransform ( TriclopsContext  context,
const TriclopsTransform transform 
)

Sets the 3D world coordinates rototranslation matrix to a TriclopsContext.

This function sets the provided homogeneous 4x4 rototranslation matrix (as the one presented in the detailed description) as the world translation matrix for the provided triclops context. If the last row of the matrix is not normalized (i.e. [0 0 0 1]) the function will try to normalize it. When providing such a matrix it is advised to check the resulting matrix by calling triclopsGetTriclopsToWorldTransform().

Parameters
contextThe Triclops context to which set the matrix
transformThe homogeneous 4x4 rototranslation matrix to set
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorSingularRotationMatrixThe provided rototranslation matrix is singular
TriclopsErrorInvalidContextThe provided context is invalid
See also
triclopsRCDFloatToWorldXYZ()
triclopsWorldXYZToRCD()
triclopsGetTriclopsToWorldTransform()
enum TriclopsError triclopsWorldXYZToRCD ( TriclopsContext  context,
float  x,
float  y,
float  z,
float *  row,
float *  col,
float *  disp 
)

Converts a 3D point in world coordinate system to a 2D pixel coordinate in disparity space.

This function first applies an inverse rototranslation matrix (based on the one set in the provided context) and then uses triclopsRCDToXYZ() to compute the 2D coordinate in disparity space.

Parameters
contextThe Triclops context used to compute disparities
xThe x coordinate of the input pixel in camera coordinate system
yThe y coordinate of the input pixel in camera coordinate system
zThe z coordinate of the input pixel in camera coordinate system
rowThe resulting y coordinate of the input pixel in 2D space
colThe resulting x coordinate of the input pixel in 2D space
dispThe resulting disparity value computed for the input pixel
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidDistanceValueThe provided z coordinate is invalid (i.e. less or equal than 0)
TriclopsErrorInvalidContextThe provided context is invalid
See also
triclopsRCDFloatToXYZ()
triclopsWorldXYZToRCD()
enum TriclopsError triclopsWriteTransformToFile ( const char *  fileName,
const TriclopsTransform transform 
)

Saves a 3D world coordinates rototranslation matrix to memory.

The file containing the rototranslation matrix needs to have the ".trans" extension, otherwise the function will not recognise the file as valid.

Parameters
fileNameThe path, either relative or absolute, to the matrix file
transformThe 4x4 matrix to save to memory
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorCorruptTransformFileAn error occurred while writing the matrix to memory
See also
triclopsSetTriclopsToWorldTransform()
enum TriclopsError triclopsXYZToRCD ( TriclopsContext  context,
float  x,
float  y,
float  z,
float *  row,
float *  col,
float *  disp 
)

Converts a 3D point in camera coordinate system to a 2D pixel coordinate in disparity space.

Parameters
contextThe Triclops context used to compute disparities
xThe x coordinate of the input pixel in camera coordinate system
yThe y coordinate of the input pixel in camera coordinate system
zThe z coordinate of the input pixel in camera coordinate system
rowThe resulting y coordinate of the input pixel in 2D space
colThe resulting x coordinate of the input pixel in 2D space
dispThe resulting disparity value computed for the input pixel

Note: According to the input x and y coordinates, the corresponding col and row values could be negative or larger than the current output resolution, without generating any code error.

Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidDistanceValueThe provided z coordinate is invalid (i.e. less or equal than 0)
TriclopsErrorInvalidContextThe provided context is invalid
See also
triclopsRCDFloatToXYZ()
triclopsWorldXYZToRCD()
Contact Support Triclops SDK Programmer's Guide and API Reference