Triclops SDK
4.0.3.0
Functions
Image functions

Functions

enum TriclopsError triclopsBuildColorStereoPairFromBuffers (const TriclopsContext context, TriclopsColorImage *right, TriclopsColorImage *left, TriclopsColorStereoPair *triclopsInput)
 Joins two color images in a single side-by-side structure. More...
 
enum TriclopsError triclopsBuildColorStereoPairFromFile (const TriclopsContext context, const char *filename, TriclopsColorPixelFormat pixelFormat, TriclopsColorStereoPair *triclopsInput)
 Loads a color picture from file in a side-by-side structure. More...
 
enum TriclopsError triclopsBuildMonoStereoPairFromBuffers (const TriclopsContext context, TriclopsImage *right, TriclopsImage *left, TriclopsMonoStereoPair *triclopsInput)
 Joins two greyscale images in a single side-by-side structure. More...
 
enum TriclopsError triclopsBuildMonoStereoPairFromFile (const TriclopsContext context, const char *filename, TriclopsMonoStereoPair *triclopsInput)
 Loads a greyscale picture from file in a side-by-side structure. More...
 
enum TriclopsError triclopsFreeColorStereoPair (TriclopsColorStereoPair *stereoPair, bool isSingleBuffer)
 Releases a color side-by-side image structure. More...
 
enum TriclopsError triclopsFreeMonoStereoPair (TriclopsMonoStereoPair *stereoPair, bool isSingleBuffer)
 Releases a greyscale side-by-side image structure. More...
 
enum TriclopsError triclopsGetColorImage (const TriclopsContext context, TriclopsColorImageType imageType, TriclopsCamera camera, TriclopsColorImage *image)
 Retrieves a 32-bit color image form a context. More...
 
enum TriclopsError triclopsGetImage (const TriclopsContext context, TriclopsImageType imageType, TriclopsCamera camera, TriclopsImage *image)
 Retrieves an 8-bit greyscale image form a context. More...
 
enum TriclopsError triclopsGetImage16 (const TriclopsContext context, TriclopsImage16Type imageType, TriclopsCamera camera, TriclopsImage16 *image)
 Retrieves a 16-bit greyscale image form a context. More...
 
enum TriclopsError triclopsLoadColorImageFromBuffer (TriclopsColorPixel *buffer, unsigned int nrows, unsigned int ncols, unsigned int rowinc, TriclopsColorImage *image)
 Load a color image from a buffer. More...
 
enum TriclopsError triclopsLoadColorImageFromFile (const char *filename, TriclopsColorPixelFormat pixelFormat, TriclopsColorImage *image)
 Load a color image from a file. More...
 
enum TriclopsError triclopsLoadImage16FromBuffer (unsigned short *buffer, unsigned int nrows, unsigned int ncols, unsigned int rowinc, TriclopsImage16 *image)
 Load a 16-bit image from a buffer. More...
 
enum TriclopsError triclopsLoadImage16FromFile (const char *filename, TriclopsImage16 *image)
 Load a 16-bit image from a file. More...
 
enum TriclopsError triclopsLoadImageFromBuffer (unsigned char *buffer, unsigned int nrows, unsigned int ncols, unsigned int rowinc, TriclopsImage *image)
 Load a 8-bit image from a buffer. More...
 
enum TriclopsError triclopsLoadImageFromFile (const char *filename, TriclopsImage *image)
 Load a 8bit image from a file. More...
 
enum TriclopsError triclopsSaveColorImage (TriclopsColorImage *image, const char *filename, TriclopsColorPixelFormat pixelFormat)
 Saves a color image to memory. More...
 
enum TriclopsError triclopsSaveImage (TriclopsImage *image, const char *filename)
 Saves a greyscale image to memory. More...
 
enum TriclopsError triclopsSaveImage16 (TriclopsImage16 *image, const char *filename)
 Saves a 16-bit image to memory. More...
 

Detailed Description

General image functions using to manipulate image structures used in Triclops. Triclops uses 8-bit greyscale images as inputs for Edge filtering and disparity computations and accepts both 8-bit greyscale and 32-bit color images for frame rectification. The images have to be packed in specific structures (i.e. TriclopsMonoStereoPair and TriclopsColorStereoPair) in order to be accepted as valid stereo inputs.

Depth maps are stored as 16-bit images, with every pixel representing a depth in fixed point format (12 integer bits, 4 decimal bits).

Triclops' Image management

All of the functions that retrieve frames from contexts perform only shallow copies of the frames, effectively pointing at internal data locations. This means that it is necessary to perform a hard copy of the image data every time the frame data is needed after destroying the context or after refreshing a context's internal buffers.

The file formats currently supported are PGM, PPM, PNG and TIFF formats.

Function Documentation

enum TriclopsError triclopsBuildColorStereoPairFromBuffers ( const TriclopsContext  context,
TriclopsColorImage right,
TriclopsColorImage left,
TriclopsColorStereoPair triclopsInput 
)

Joins two color images in a single side-by-side structure.

This function performs the same operation than triclopsBuildMonoStereoPairFromBuffers() but it is intended for color images

Parameters
contextAny context
rightThe right image of the pair
leftThe left image of the pair
triclopsInputThe stereo pair to populate using the images
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidBuffersEither one or both input images pointers are NULL
TriclopsErrorInvalidSourceResolutionThe resolutions of the input images are different
TriclopsErrorInvalidContextThe provided context is invalid
See also
triclopsBuildColorStereoPairFromFile()
triclopsBuildMonoStereoPairFromBuffers()
triclopsFreeColorStereoPair()
enum TriclopsError triclopsBuildColorStereoPairFromFile ( const TriclopsContext  context,
const char *  filename,
TriclopsColorPixelFormat  pixelFormat,
TriclopsColorStereoPair triclopsInput 
)

Loads a color picture from file in a side-by-side structure.

This function performs the same operation than triclopsBuildMonoStereoPairFromFile() but it is intended for color images.

Parameters
contextAny context
filenamePath to the side-by-side picture
pixelFormatPixel color encoding of the picture to load
triclopsInputThe stereo pair to populate using the image from memory
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidBuffersThe image load function returned a NULL pointer [This should never happen]
TriclopsErrorInvalidSourceResolutionOne of the two dimensions of the input image is invalid (e.g. too large)
TriclopsErrorNotSupportedImageFileFormatThe format of the provided image is not supported
TriclopsErrorInvalidContextThe provided context is invalid
TriclopsErrorInvalidBitdepthImageThe size of one pixel in terms of number of bits is invalid.
See also
triclopsBuildColorStereoPairFromBuffers()
triclopsBuildMonoStereoPairFromFile()
triclopsFreeColorStereoPair()
enum TriclopsError triclopsBuildMonoStereoPairFromBuffers ( const TriclopsContext  context,
TriclopsImage right,
TriclopsImage left,
TriclopsMonoStereoPair triclopsInput 
)

Joins two greyscale images in a single side-by-side structure.

This function performs only a shallow copy of the two images provided, meaning that both images should be valid for the whole life of the stereo pair structure. The two images need to have the same resolution for this function to correctly execute.

Parameters
contextAny context
rightThe right image of the pair
leftThe left image of the pair
triclopsInputThe stereo pair to populate using the images
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidBuffersEither one or both input images pointers are NULL
TriclopsErrorInvalidSourceResolutionThe resolutions of the input images are different
TriclopsErrorInvalidContextThe provided context is invalid
See also
triclopsBuildMonoStereoPairFromFile()
triclopsBuildColorStereoPairFromBuffers()
triclopsFreeMonoStereoPair()
enum TriclopsError triclopsBuildMonoStereoPairFromFile ( const TriclopsContext  context,
const char *  filename,
TriclopsMonoStereoPair triclopsInput 
)

Loads a greyscale picture from file in a side-by-side structure.

Parameters
contextAny context
filenamePath to the side-by-side picture
triclopsInputThe stereo pair to populate using the image from memory
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidBuffersThe image load function returned a NULL pointer [This should never happen]
TriclopsErrorInvalidSourceResolutionOne of the two dimensions of the input image is invalid (e.g. too large)
TriclopsErrorNotSupportedImageFileFormatThe format of the provided image is not supported
TriclopsErrorInvalidContextThe provided context is invalid
TriclopsErrorInvalidBitdepthImageThe size of one pixel in terms of number of bits is invalid.
See also
triclopsBuildMonoStereoPairFromBuffers()
triclopsBuildColorStereoPairFromFile()
triclopsFreeMonoStereoPair()
enum TriclopsError triclopsFreeColorStereoPair ( TriclopsColorStereoPair stereoPair,
bool  isSingleBuffer 
)

Releases a color side-by-side image structure.

This function performs the same operation as triclopsFreeMonoStereoPair().

Parameters
stereoPairThe color side-by-side structure to free
isSingleBufferSet to true if the structure has only the right buffer set
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
See also
triclopsBuildColorStereoPairFromBuffers()
triclopsBuildColorStereoPairFromFile()
enum TriclopsError triclopsFreeMonoStereoPair ( TriclopsMonoStereoPair stereoPair,
bool  isSingleBuffer 
)

Releases a greyscale side-by-side image structure.

This function is useful when a side-by-side image loaded using triclopsBuildMonoStereoPairFromFile() is not needed anymore (e.g. at exit). This function will have side effects when called on a TriclopsMonoStereoPair created using triclopsBuildMonoStereoPairFromBuffers() as in this case the structure uses two shallow copies of the images provided at construction, resulting in the destruction of the two original images.

Parameters
stereoPairThe greyscale side-by-side structure to free
isSingleBufferSet to true if the structure has only the right buffer set
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
See also
triclopsBuildMonoStereoPairFromBuffers()
triclopsBuildMonoStereoPairFromFile()
enum TriclopsError triclopsGetColorImage ( const TriclopsContext  context,
TriclopsColorImageType  imageType,
TriclopsCamera  camera,
TriclopsColorImage image 
)

Retrieves a 32-bit color image form a context.

The function performs the same operation as triclopsGetImage(), but retrieves color frames (i.e. colored unrectified and rectified images)

Parameters
contextThe context where to retrieve the frame
imageTypeThe frame to retrieve
cameraThe sensor relative to the frame
imageThe image to fill with the data retrieved
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidCameraThe chosen sensor is non-existent (e.g. int casted to TriclopsCamera)
TriclopsErrorInvalidParameterThe chosen frame is non-existent (e.g. int casted to TriclopsCamera)
TriclopsErrorInvalidContextThe provided context is invalid
See also
TriclopsColorImage
triclopsSaveColorImage()
triclopsGetImage()
enum TriclopsError triclopsGetImage ( const TriclopsContext  context,
TriclopsImageType  imageType,
TriclopsCamera  camera,
TriclopsImage image 
)

Retrieves an 8-bit greyscale image form a context.

The function retrieves an image from the internal frame buffers of the provided context. The frame can be relative to either sensor of the camera.

Parameters
contextThe context where to retrieve the frame
imageTypeThe frame to retrieve
cameraThe sensor relative to the frame
imageThe image to fill with the data retrieved
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidCameraThe chosen sensor is non-existent (e.g. int casted to TriclopsCamera)
TriclopsErrorInvalidRequestThe chosen frame is TriImg_EDGE even though Edge filtering is deactivated
TriclopsErrorInvalidParameterThe chosen frame is non-existent (e.g. int casted to TriclopsCamera)
TriclopsErrorInvalidContextThe provided context is invalid
See also
TriclopsImage
triclopsSaveImage()
triclopsGetImage16()
enum TriclopsError triclopsGetImage16 ( const TriclopsContext  context,
TriclopsImage16Type  imageType,
TriclopsCamera  camera,
TriclopsImage16 image 
)

Retrieves a 16-bit greyscale image form a context.

The function performs the same operation as triclopsGetImage(), but only retrieves 16-bit frames (i.e. depth maps).

Parameters
contextThe context where to retrieve the frame
imageTypeThe frame to retrieve
cameraThe sensor relative to the frame
imageThe image to fill with the data retrieved
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidCameraThe chosen sensor is non-existent (e.g. int casted to TriclopsCamera)
TriclopsErrorInvalidParameterThe chosen frame is non-existent (e.g. int casted to TriclopsCamera)
TriclopsErrorInvalidContextThe provided context is invalid
See also
TriclopsImage16
triclopsSaveImage16()
triclopsGetImage()
enum TriclopsError triclopsLoadColorImageFromBuffer ( TriclopsColorPixel buffer,
unsigned int  nrows,
unsigned int  ncols,
unsigned int  rowinc,
TriclopsColorImage image 
)

Load a color image from a buffer.

The function performs the same operation as triclopsLoadColorImageFromFile(), but only retrieves a color frames from a buffer rather than a file. It carries out a shallow copy of the buffer.

Parameters
bufferThe pointer to the buffer containing image values
nrowsThe number of rows of the buffer
ncolsThe number of columns of the buffer
rowincThe pitch, or row increment for the image. rowinc must be a multiple of cols
imageThe pointer to the structure describing the image
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidBufferThe buffer is null
TriclopsErrorInvalidRowIncThe row increment is invalid.
See also
triclopsLoadImageFromBuffer()
triclopsLoadImage16FromBuffer()
triclopsLoadColorImageFromFile()
enum TriclopsError triclopsLoadColorImageFromFile ( const char *  filename,
TriclopsColorPixelFormat  pixelFormat,
TriclopsColorImage image 
)

Load a color image from a file.

The function performs the same operation as triclopsLoadImageFromFile(), triclopsLoadImage16FromFile(), but only retrieves color frames (i.e. raw and rectified images).

The path should contain a full filename, including the extension, in order for the function to understand which

Parameters
filenameThe path to the image filename
pixelFormatThe format of the color pixel
imageThe pointer to the structure describing the loaded image
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorFileReadThe image has not been successfully from file
TriclopsErrorNotSupportedImageFileFormatThe image format is not supported or unknown
TriclopsErrorInvalidBitdepthImageThe size of one pixel in bits is invalid. Supported pixel size values are 24 and 32.
TriclopsErrorNotSupportedColorPixelFormatThe format of pixels is not supported
See also
triclopsLoadImageFromFile()
triclopsLoadImage16FromFile()
enum TriclopsError triclopsLoadImage16FromBuffer ( unsigned short *  buffer,
unsigned int  nrows,
unsigned int  ncols,
unsigned int  rowinc,
TriclopsImage16 image 
)

Load a 16-bit image from a buffer.

The function performs the same operation as triclopsLoadImage16FromFile(), but only retrieves 16-bit frames from a buffer rather than a file. It carries out a shallow copy of the buffer.

Parameters
bufferThe pointer to the buffer containing image values
nrowsThe number of rows of the buffer
ncolsThe number of columns of the buffer
rowincThe pitch, or row increment for the image. rowinc must be a multiple of cols
imageThe pointer to the structure describing the image
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidBufferThe buffer is null
TriclopsErrorInvalidRowIncThe row increment is invalid.
See also
triclopsLoadImageFromBuffer()
triclopsLoadColorImageFromBuffer()
triclopsLoadImage16FromFile()
enum TriclopsError triclopsLoadImage16FromFile ( const char *  filename,
TriclopsImage16 image 
)

Load a 16-bit image from a file.

The function performs the same operation as triclopsLoadImageFromFile(), triclopsLoadColorImageFromFile(), but only retrieves 16-bit frames (i.e. disparity maps).

The path should contain a full filename, including the extension, in order for the function to understand which

Parameters
filenameThe path to the image filename.
imageThe pointer to the structure describing the loaded image
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorFileReadThe image has not been successfully from file
TriclopsErrorNotSupportedImageFileFormatThe image format is not supported or unknown
TriclopsErrorInvalidBitdepthImageThe size of one pixel in bits is not 16, as expected
See also
triclopsLoadImageFromFile()
triclopsLoadColorImageFromFile()
enum TriclopsError triclopsLoadImageFromBuffer ( unsigned char *  buffer,
unsigned int  nrows,
unsigned int  ncols,
unsigned int  rowinc,
TriclopsImage image 
)

Load a 8-bit image from a buffer.

The function performs the same operation as triclopsLoadImageFromFile(), but only retrieves 8-bit frames from a buffer rather than a file. It carries out a shallow copy of the buffer.

Parameters
bufferThe pointer to the buffer containing image values
nrowsThe number of rows of the buffer
ncolsThe number of columns of the buffer
rowincThe pitch, or row increment for the image. rowinc must be a multiple of cols
imageThe pointer to the structure describing the image
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidBufferThe buffer is null
TriclopsErrorInvalidRowIncThe row increment is invalid.
See also
triclopsLoadImage16FromBuffer()
triclopsLoadColorImageFromBuffer()
triclopsLoadImageFromFile()
enum TriclopsError triclopsLoadImageFromFile ( const char *  filename,
TriclopsImage image 
)

Load a 8bit image from a file.

The function performs the same operation as triclopsLoadImage16FromFile(), triclopsLoadColorImageFromFile(), but only retrieves 8-bit frames (i.e. raw, rectified and edge images).

The path should contain a full filename, including the extension, in order for the function to understand which file format to use when loading the image.

Parameters
filenameThe path to the image filename.
imageThe pointer to the structure describing the loaded image
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorFileReadThe image has not been successfully from file
TriclopsErrorNotSupportedImageFileFormatThe image format is not supported or unknown
TriclopsErrorInvalidBitdepthImageThe size of one pixel in bits is not 8, as expected
See also
triclopsLoadImage16FromFile()
triclopsLoadColorImageFromFile()
enum TriclopsError triclopsSaveColorImage ( TriclopsColorImage image,
const char *  filename,
TriclopsColorPixelFormat  pixelFormat 
)

Saves a color image to memory.

This function saves color frames (i.e. colored unrectified and rectified images)

The path should contain a full filename, including the extension, in order for the function to understand which file format to use when saving the image.

Parameters
imageThe image to save to memory
filenameThe path where to save the image
pixelFormatThe format of the color pixel
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidFilenameThe provided file path is invalid
TriclopsErrorNotSupportedImageFileFormatThe chosen image format is not supported
TriclopsErrorNotSupportedColorPixelFormatThe format of pixels is not supported
See also
triclopsSaveImage()
triclopsSaveImage16()
enum TriclopsError triclopsSaveImage ( TriclopsImage image,
const char *  filename 
)

Saves a greyscale image to memory.

The path should contain a full filename, including the extension, in order for the function to understand which file format to use when saving the image.

Parameters
imageThe image to save to memory
filenameThe path where to save the image
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidParameterThe provided path is an empty string
TriclopsErrorNotSupportedImageFileFormatThe chosen image format is not supported
See also
triclopsSaveImage16()
triclopsSaveColorImage()
enum TriclopsError triclopsSaveImage16 ( TriclopsImage16 image,
const char *  filename 
)

Saves a 16-bit image to memory.

The path should contain a full filename, including the extension, in order for the function to understand which file format to use when saving the image.

Parameters
imageThe image to save to memory
filenameThe path where to save the image
Returns
An error code representing the outcome of the function
Return values
TriclopsErrorOkThe function completed successfully
TriclopsErrorInvalidParameterThe provided path is an empty string
TriclopsErrorNotSupportedImageFileFormatThe chosen image format is not supported
See also
triclopsSaveImage()
triclopsSaveColorImage()
Contact Support Triclops SDK Programmer's Guide and API Reference