Skip to content

iolibrt#

The library iolibrt provides functions to load and store commonly used image formats. On Windows, the library also allows loading a sequence of images from, or saving to an .avi video file.

To use the library, the include file sisoIo.h should be added to the source code.

#include <sisoIo.h>

Additionally, iolibrt.lib should be added to your Microsoft Visual Studio Project, or libiolibrt.so to your Linux project. If you use CMake, the package name is SisoIoLib, the libraries are stored in the variable ${SISOIOLIB_LIBRARIES} and the the include directory is stored in the variable ${SISOIOLIB_INCLUDE_DIR}. See Prerequisites for more details on projects and how to use CMake.

Error Handling in iolibrt#

Most functions of the API return an int result code. If the function call was executed successfully, the return value will be 0 or for some functions a value equal or greater than zero. A negative value denotes an error condition in most cases. The error codes are defined in the header files sisoIoFileErrorCodes.h for general errors related to reading and writing files, and sisoIoBmpErrorCodes.h, sisoIoRawErrorCodes.h and sisoIoTiffErrorCodes.h for errors related to the specific file format.

The code examples in the rest of this part of the documentation will not include error handling as this is specific to the requirements of the application. As much as is feasible, return codes will be checked however for successful execution of the functions.

Working with Image Files#

The image input/output library supports two standard image file formats: Windows Bitmap (.bmp) and Tagged Image File Format (.tif or .tiff). In addition, a raw data file format (.raw) with a minimal header is supported for data which can't be represented by the standard file formats. The header of the .raw file contains the following information in this order:

  1. 4 bytes describing the image width
  2. 4 bytes describing the image height
  3. 4 bytes describing the bits per pixel. E.g. 8-bit grey = 8; 14-bit grey = 14; 10-bit rgb = 30
  4. 4 bytes describing the bytes per pixel; bytes per pixel are rounded up, e.g. 10 bits = 2 bytes
  5. The raw data

The functions in this chapter will determine the file format from the file extension of the file name.

Opening Image Files#

int IoImageOpen(
    const char * file,
    SisoIoImageEngine ** handle);

int IoImageOpenEx(
    const char * file,
    SisoIoImageEngine ** handle,
    int rgbSequence);

int IoFreeImage(
    SisoIoImageEngine * handle);

int IoGetWidth(
    const SisoIoImageEngine * handle);

int IoGetHeight(
    const SisoIoImageEngine * handle);

int IoGetBitsPerPixel(
    const SisoIoImageEngine * handle);

int IoGetBitsPerComponent(
    const SisoIoImageEngine * handle) ;

int IoGetNrOfComponents(
    const SisoIoImageEngine * handle);

const void * IoImageGetData(
    const SisoIoImageEngine * handle);

size_t IoCalculateBufferSize(
    int width,
    int height,
    int bitsPerPixel);

To open an image file, the functions IoImageOpen() or IoImageOpenEx() can be called. Both functions expect the file name in the first parameter and a pointer to a variable of type SisoIoImageEngine * which will be used in functions to access the image data. The function IoImageOpenEx() can be called for images with a reversed sequence of red, green and blue data with the parameter rgbSequence set to 1.

After an image is no longer needed, the function IoFreeImage() should be called to release the memory for the image data.

To get the dimensions and data format of the image data, the functions IoGetWidth(), IoGetHeight(), IoGetBitsPerPixel(), IoGetBitsPerComponent() and IoGetNrOfComponents() can be called.

The image data can be accessed by calling the function IoImageGetData() which will return a pointer to the buffer containing the image data. To get the size of the buffer, the function IoCalculateBufferSize() can be used.

The image data is usually divided into lines. The height of the image is the number of lines of which the image data is composed. Each line consists of pixels and the width of the image is the number of pixels in a line. Each pixel is represented by one or more color components. Grayscale images usually have a single component per pixel, the gray value. Color images usually contain three components, one value for red, green and blue each. An additional component might be a value for the opacity, or an infra-red or x-ray component. The components usually are encoded using the same number of bits. The number of components and the bits per pixel are referred to as pixel format. (Sometimes, the bits per component are used instead of bits per pixel.)

Depending on the pixel format, each line can contain some padding at the end to make sure that the first pixel of each line starts with a defined alignment. The function IoCalculateBufferSize() assumes that lines always start at a byte boundary, so for pixel formats which don't use a multiple of 8 bits per pixel, the end of a line might contain padding bits, and the next line starts at the next byte in the buffer.

Saving Image Files#

int IoSaveImageExt(
    const char * file,
    void * data,
    int width,
    int height,
    int bitsPerPixel);

To save image data to a file, the function IoSaveImageExt() can be called. The function expects the file name in the first parameter and a pointer to the buffer which contains the image data in the second. The three remaining parameters pass the image dimensions and the bits per pixel to the function.

You can save the following file formats: .tif,.tiff, .bmp, .raw. The file formats are detected automatically from the const char * file.

Working with Image Sequence Files#

The image input/output library provides support for a simple image sequence file format. Image sequence files contain a number of images of the same dimensions and pixel format. Each image is assigned a a sequence index and a frame number. The sequence index corresponds to the position of the image within the file, sequence index 0 is the first image in the sequence file, 1 the second, and so on. The frame number is obtained during acquisition, usually starts with 1 and the sequence can contain gaps in the frame numbers when not all consecutive images were written to the sequence.

There is no standard file extension defined for image sequence files, recommended choices are .isq or .imageseq.

Opening Image Sequence Files#

int IoOpenSeq(
    void ** handle,
    const char * file,
    int * width,
    int * height,
    int * bitsPerPixel,
    int flags);

int IoCloseSeq(
    void * handle);

int IoGetSeqInfo(
    void * handle,
    int * nrOfFrames,
    int * nrOfLostFrames);

int IoReadNextSeqPicture(
    void * handle,
    int * frame,
    void * buffer);

To open an existing image sequence file for reading images from, the function IoOpenSeq() can be called. The function expects a pointer to a variable of type void * in the parameter handle which will be used in functions to access the data in the image sequence file, the file name in the parameter file and three pointers to variables for the image dimensions in the parameters width and height and the number of bits per pixel in the parameter bitsPerPixel. The parameter flags is reserved for future extensions and should always be set to 0.

When the application is finished accessing the data in an image sequence file, the function IoCloseSeq() should be called.

To read the next image from the image sequence file, the function IoReadNextSeqPicture() can be called. The function expects a handle from a previous call to IoOpenSeq() in the parameter handle, a pointer to a variable of type int to store the frame number of the image in the paramater frame and a pointer to the buffer to store the image data in the parameter buffer. The buffer must be large enough to store the image data according to the image diemnsions and pixel format and can be calculated for example by a call to IoCalculateBufferSize().

The function IoGetSeqInfo() can be called to request information about the number of images stored in the image sequence files and the sum of gaps between frame numbers in the sequence.

Writing Image Sequence Files#

int IoCreateSeq(
    void ** handle,
    const char * file,
    int width,
    int height,
    int bitsPerPixel,
    int flags);

int IoCloseSeq(
    void * handle);

int IoWriteNextSeqPicture(
    void * handle,
    int frame,
    const void * buffer);

To create a new image sequence file for writing images to, the function IoCreateSeq() can be called. The function expects a pointer to a variable of type void * in the parameter handle which will be used in functions to access the data in the image sequence file, the file name in the parameter file, the image dimensions in the parameters width and height and the number of bits per pixel in the parameter bitsPerPixel. The parameter flags is reserved for future extensions and should always be set to 0.

When the application is finished accessing the data in an image sequence file, the function IoCloseSeq() should be called.

To append the next image to the image sequence file, the function IoWriteNextSeqPicture() can be called. The function expects a handle from a previous call to IoCreateSeq() in the parameter handle, the frame number of the image in the paramater frame and a pointer to the buffer which contains the image data in to in the parameter buffer. The buffer must be large enough to provide the image data according to the image diemnsions and pixel format and can be calculated for example by a call to IoCalculateBufferSize().

Working with Video Files (Windows Only)#

When using the Framegrabber API for the Microsoft Windows Operating System, the image input/output library provides limited support for the Audio Video Interleave (.avi) file format.

Opening Video Files#

int IoOpenAVI(
    void ** handle,
    const char * file,
    int * width,
    int * height,
    int * bitDepth);

int IoCloseAVI(
    void * handle);

int IoReadAVIPicture(
    void * handle,
    int index,
    void * buffer);

To open an existing video file for reading images from, the function IoOpenAVI() can be called. The function expects a pointer to a variable of type void * in the parameter handle which will be used in functions to access the data in the video file, the file name in the parameter file and three pointers to variables for the image dimensions in the parameters width and height and the number of bits per pixel in the parameter bitsPerPixel.

When the application is finished accessing the data in a video file, the function IoCloseAVI() should be called.

To read an image from the video file, the function IoReadAVIPicture() can be called. The function expects a handle from a previous call to IoOpenSeq() in the parameter handle, the index of the image to read and a pointer to the buffer to store the image data in the parameter buffer. The buffer must be large enough to store the image data according to the image diemnsions and pixel format and can be calculated for example by a call to IoCalculateBufferSize().

Writing Video Files#

int IoCreateAVIGray(
    void ** handle,
    const char * file,
    int width,
    int height,
    double fps);

int IoCreateAVIGrayW(
    void ** handle,
    const LPCWSTR file,
    int width,
    int height,
    double fps);

int IoCreateAVIColor(
    void ** handle,
    const char * file,
    int width,
    int height,
    double fps);

int IoCreateAVIColorW(
    void ** handle,
    const LPCWSTR file,
    int width,
    int height,
    double fps);

int IoCloseAVI(
    void * handle);

int IoWriteAVIPicture(
    void * handle,
    int index,
    const void * buffer);

To create a new video file for writing images to, one of the functions IoCreateAVIGray(), IoCreateAVIGrayW(), IoCreateAVIColor() or IoCreateAVIColorW() can be called. The functions expects a pointer to a variable of type void * in the parameter handle which will be used in functions to access the data in the video file, the file name in the parameter file, the image dimensions in the parameters width and height and the number of frames per second in the parameter fps. The pixel format is determined by the variant of the function: IoCreateAVIGray() and IoCreateAVIGrayW() create a video file for 8-bit grayscale image data, and IoCreateAVIColor() and IoCreateAVIColorW() create a file for 24-bit RGB image data. The variants ending in W allow file names using a wide-character string.

When the application is finished accessing the data in a video file, the function IoCloseAVI() should be called.

To write an image to the video file, the function IoWriteAVIPicture() can be called. The function expects a handle from a previous call to one of the functions for creating a video file in the parameter handle, the index of the image in the video sequence in the paramater index and a pointer to the buffer which contains the image data in to in the parameter buffer. The buffer must be large enough to provide the image data according to the image diemnsions and pixel format and can be calculated for example by a call to IoCalculateBufferSize().

Creating Video Files from Image Sequence Files#

int IoSeqCreateAvi(
    void * handle,
    const char * file,
    int fromSeqIndex,
    int toSeqIndex);

The function IoSeqCreateAvi() can be called to create a video file from an existing image sequence file. The function expects a handle from a previous call to IoOpenSeq() in the parameter handle, the file name of the video file to be created in the parameter file and the first and the last sequence index from the image sequence file to include in the video file in the parameters fromSeqIndex and toSeqIndex. If the value -1 is passed to the parameter toSeqIndex, all images in the image sequence file starting with fromSeqIndex are included in the video file.