|
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...
|
|
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:
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.
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
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
-
context | The context the 3D image is initialized for |
ppimage | The 3D image to initialize |
- Returns
- An error code representing the outcome of the function
- Return values
-
TriclopsErrorOk | The function completed successfully |
- See also
- triclopsDestroyImage3d()
-
triclopsExtractImage3d()
Destroys a 3D image structure.
- Parameters
-
ppimage | The 3D image to destroy |
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
-
context | The context where to retrieve the disparity map to convert |
pimage | The 3D image to fill with the generated point cloud |
- Returns
- An error code representing the outcome of the function
- Return values
-
TriclopsErrorOk | The function completed successfully |
TriclopsError3dImageSizeAndOutputResolutionMismatch | The output resolution and the resolution of the 3D image are not the same |
TriclopsErrorDisparityMapAndOutputResolutionMismatch | The output resolution and the resolution of teh disparity map are not the same |
TriclopsErrorInvalidContext | The provided context is invalid |
- See also
- triclopsCreateImage3d()
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
-
context | The context where to retrieve the disparity map to convert |
pimage | The 3D image to fill with the generated point cloud |
- Returns
- An error code representing the outcome of the function
- Return values
-
TriclopsErrorOk | The function completed successfully |
TriclopsError3dImageSizeAndOutputResolutionMismatch | The output resolution and the resolution of the 3D image are not the same |
TriclopsErrorDisparityMapAndOutputResolutionMismatch | The output resolution and the resolution of teh disparity map are not the same |
TriclopsErrorInvalidContext | The provided context is invalid |
- See also
- triclopsCreateImage3d()
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
-
fileName | The path, either relative or absolute, to the matrix file |
transform | The 4x4 matrix to fill with the data contained in the file |
- Returns
- An error code representing the outcome of the function
- Return values
-
TriclopsErrorOk | The function completed successfully |
TriclopsErrorCorruptTransformFile | The provided file path points to either an invalid transform file or to a file with the wrong extension. |
- See also
- triclopsSetTriclopsToWorldTransform()
Gets the 3D world coordinates rototranslation matrix to a TriclopsContext.
- Parameters
-
context | The Triclops context that contains the matrix |
transform | The destination 4x4 rototranslation |
- Returns
- An error code representing the outcome of the function
- Return values
-
TriclopsErrorOk | The function completed successfully |
TriclopsErrorInvalidContext | The 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.
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
-
context | The Triclops context used to compute disparities |
row | The y location of the input pixel |
col | The x location of the input pixel |
disp | The disparity value computed for the input pixel |
x | The resulting x coordinate of the pixel in world coordinate system |
y | The resulting y coordinate of the pixel in world coordinate system |
z | The resulting z coordinate of the pixel in world coordinate system |
- Returns
- An error code representing the outcome of the function
- Return values
-
TriclopsErrorOk | The function completed successfully |
TriclopsErrorInvalidCoordinates | The provided 2D coordinates are invalid |
TriclopsErrorInvalidDisparityValue | The provided disparity value is invalid (i.e. less or equal than 0 or plain invalid) |
TriclopsErrorInvalidContext | The provided context is invalid |
- See also
- triclopsSetTriclopsToWorldTransform()
-
triclopsRCD16ToWorldXYZ()
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
-
context | The Triclops context used to compute disparities |
row | The y location of the input pixel |
col | The x location of the input pixel |
disp | The disparity value computed for the input pixel |
x | The resulting x coordinate of the pixel in camera coordinate system |
y | The resulting y coordinate of the pixel in camera coordinate system |
z | The resulting z coordinate of the pixel in camera coordinate system |
- Returns
- An error code representing the outcome of the function
- Return values
-
TriclopsErrorOk | The function completed successfully |
TriclopsErrorInvalidCoordinates | The provided 2D coordinates are invalid (i.e. less that zero or larger that the current outut resolution) |
TriclopsErrorInvalidDisparityValue | The provided disparity is invalid (i.e. less or equal than 0 or plain invalid) |
TriclopsErrorInvalidContext | The provided context is invalid |
- See also
- triclopsRCD16ToXYZ()
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()
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().
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
-
context | The Triclops context to which set the matrix |
transform | The homogeneous 4x4 rototranslation matrix to set |
- Returns
- An error code representing the outcome of the function
- Return values
-
TriclopsErrorOk | The function completed successfully |
TriclopsErrorSingularRotationMatrix | The provided rototranslation matrix is singular |
TriclopsErrorInvalidContext | The provided context is invalid |
- See also
- triclopsRCDFloatToWorldXYZ()
-
triclopsWorldXYZToRCD()
-
triclopsGetTriclopsToWorldTransform()
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
-
context | The Triclops context used to compute disparities |
x | The x coordinate of the input pixel in camera coordinate system |
y | The y coordinate of the input pixel in camera coordinate system |
z | The z coordinate of the input pixel in camera coordinate system |
row | The resulting y coordinate of the input pixel in 2D space |
col | The resulting x coordinate of the input pixel in 2D space |
disp | The resulting disparity value computed for the input pixel |
- Returns
- An error code representing the outcome of the function
- Return values
-
TriclopsErrorOk | The function completed successfully |
TriclopsErrorInvalidDistanceValue | The provided z coordinate is invalid (i.e. less or equal than 0) |
TriclopsErrorInvalidContext | The provided context is invalid |
- See also
- triclopsRCDFloatToXYZ()
-
triclopsWorldXYZToRCD()
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
-
fileName | The path, either relative or absolute, to the matrix file |
transform | The 4x4 matrix to save to memory |
- Returns
- An error code representing the outcome of the function
- Return values
-
TriclopsErrorOk | The function completed successfully |
TriclopsErrorCorruptTransformFile | An error occurred while writing the matrix to memory |
- See also
- triclopsSetTriclopsToWorldTransform()
Converts a 3D point in camera coordinate system to a 2D pixel coordinate in disparity space.
- Parameters
-
context | The Triclops context used to compute disparities |
x | The x coordinate of the input pixel in camera coordinate system |
y | The y coordinate of the input pixel in camera coordinate system |
z | The z coordinate of the input pixel in camera coordinate system |
row | The resulting y coordinate of the input pixel in 2D space |
col | The resulting x coordinate of the input pixel in 2D space |
disp | The 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
-
TriclopsErrorOk | The function completed successfully |
TriclopsErrorInvalidDistanceValue | The provided z coordinate is invalid (i.e. less or equal than 0) |
TriclopsErrorInvalidContext | The provided context is invalid |
- See also
- triclopsRCDFloatToXYZ()
-
triclopsWorldXYZToRCD()