跳转到内容

iolibrt#

iolibrt 库提供了加载和存储常用图像格式的功能。在 Windows 上，该库还允许从以下对象加载图像序列或将其保存到 .avi 视频文件中。

要使用该库，应将包含文件 sisoIo.h 添加到源代码中。

#include <sisoIo.h>

此外， iolibrt.lib 应添加到您的 Microsoft Visual Studio 项目中，或者 libiolibrt.so 添加到您的 Linux 项目中。如果使用 CMake，包名称为 SisoIoLib，库存储在变量 ${SISOIOLIB_LIBRARIES} 中，包含目录存储在变量 ${SISOIOLIB_INCLUDE_DIR}。请参阅 前提条件 了解有关项目以及如何使用 CMake 的更多详细信息。

iolibrt 中的错误处理#

API 的大多数函数都会返回一个 int 结果代码。如果函数调用执行成功，返回值为 0，或者某些函数的返回值大于或等于零。在大多数情况下，负值表示出现错误条件。Error Codes 定义在头文件中 sisoIoFileErrorCodes.h 用于与读取和写入文件相关的通用错误，以及 sisoIoBmpErrorCodes.h, sisoIoRawErrorCodes.h 和 sisoIoTiffErrorCodes.h 用于与特定文件格式相关的错误。

本文档其余部分的代码示例将不包含错误处理，因为这是针对应用程序特定需求的。不过，在可行的情况下，将对返回代码进行检查，以确保函数成功执行。

处理图像文件#

图像输入/输出库支持两种标准图像文件格式：Windows 位图 (.bmp) 和标记图像文件格式 (.tif 或 .tiff)。此外，对于无法用标准文件格式表示的数据，支持带最小文件头的原始数据文件格式 (.raw)。.raw 文件的文件头按此顺序包含以下信息：

  1. 4 个字节，用于描述图像宽度
  2. 4 个字节，用于描述图像高度
  3. 4 个字节，用于描述每个像素的位数。例如：8 位灰度 = 8；14 位灰度 = 14；10 位 RGB = 30
  4. 4 个字节，用于描述每个像素的字节数；每个像素的字节数向上取整，例如 10 位 = 2 个字节
  5. 原始数据

本章中的函数将根据文件名中的文件扩展名来确定文件格式。

打开图像文件#

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);

若要打开图像文件，可以调用 IoImageOpen() 或 IoImageOpenEx() 函数。这两个函数都期望在第一个参数中传入文件名，并在第二个参数中传入指向 SisoIoImageEngine * 类型变量的指针，该变量将在后续函数中用于访问图像数据。对于红、绿色和蓝色数据顺序相反的图像，可以调用 IoImageOpenEx() 函数并将 rgbSequence 参数设为 1。

当不再需要某幅图像后，应调用 IoFreeImage() 函数以释放该图像数据的 Memory。

若要获取图像数据的尺寸和数据格式，可以调用 IoGetWidth(), IoGetHeight(), IoGetBitsPerPixel(), IoGetBitsPerComponent() 和 IoGetNrOfComponents() 中获取字节数组，可以调用

可以通过调用函数来访问图像数据， IoImageGetData() 该函数将返回一个指向包含图像数据的缓冲区的指针。若要获取缓冲区的大小，可以调用 IoCalculateBufferSize() 可以使用。

图像数据通常分为多行。图像的高度即构成图像数据的行数。每行由多个像素组成，图像的宽度即一行中的像素数。每个像素由一个或多个颜色分量表示。灰度图像通常每个像素只有一个分量，即灰度值。彩色图像通常包含三个分量，分别对应红、绿、蓝三个值。附加分量可能是用于不透明度的值，或者是红外或 X 射线分量。这些分量通常使用相同数量的位数进行编码。分量数和每像素位数统称为 Pixel Format。（有时，会使用每分量位数代替每像素位数。）

根据 Pixel Format 的不同，每行末尾可能包含一些填充字节，以确保每行的第一个像素从规定的对齐方式开始。函数 IoCalculateBufferSize() 假定各行始终从字节边界开始，因此对于每个像素的位数不是 8 的倍数的 Pixel Format，行尾可能包含填充位，下一行将从缓冲区中的下一个字节开始。

保存图像文件#

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

若要将图像数据保存到文件，可以调用 IoSaveImageExt() 函数。该函数期望在第一个参数中传入文件名，并在第二个参数中传入指向包含图像数据的缓冲区的指针。其余三个参数用于向函数传递图像尺寸和每像素位数。

您可以保存以下文件格式： .tif,.tiff, .bmp, .raw。文件格式将自动根据以下内容进行检测： const char * file.

处理图像序列文件#

图像输入/输出库提供了对简单图像序列文件格式的支持。图像序列文件包含数量众多的、具有相同尺寸和 Pixel Format 的图像。每幅图像均被分配了一个序列索引和一个帧号。序列索引对应于图像在文件中的位置，序列索引 0 是序列文件中的第一幅图像，1 是第二幅图像，依此类推。帧号是在采集过程中获得的，通常从 1 开始，并且当并非所有连续图像都被写入序列时，序列中的帧号可能会出现间隙。

图像序列文件没有定义标准的文件扩展名，推荐的选择是 .isq 或 .imageseq.

打开图像序列文件#

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);

若要打开现有的图像序列文件以读取其中的图像，可以调用函数 IoOpenSeq() 该函数需要一个指向特定类型变量的指针 void * 在参数 handle 这将在用于访问图像序列文件中数据的函数、参数中的文件名 file 以及三个用于图像尺寸的变量指针作为参数 width 和 height 以及参数中的每像素位数中使用 bitsPerPixel。参数 flags 保留用于未来的扩展，并且应始终设置为 0。

当应用程序完成对图像序列文件中数据的访问时，该函数 IoCloseSeq() 应当被调用。

要从图像序列文件中读取下一幅图像，该函数 IoReadNextSeqPicture() 可以调用。该函数需要来自先前调用的句柄 IoOpenSeq() 在参数 handle，一个指向类型为 int 将图像的帧号存储在参数中 frame 以及一个指向缓冲区的指针，用于在参数中存储图像数据 buffer。缓冲区的大小必须足以根据图像尺寸和 Pixel Format 存储图像数据，例如可以通过调用以下内容来计算 IoCalculateBufferSize().

函数 IoGetSeqInfo() 可以调用该函数以请求有关存储在图像序列文件中的图像数量以及序列中帧号之间间隙总和的信息。

写入图像序列文件#

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);

要创建一个用于写入图像的新图像序列文件，该函数 IoCreateSeq() 该函数需要一个指向特定类型变量的指针 void * 在参数 handle 这将在用于访问图像序列文件中数据的函数、参数中的文件名 file，参数中的图像尺寸 width 和 height 以及参数中的每像素位数中使用 bitsPerPixel。参数 flags 保留用于未来的扩展，并且应始终设置为 0。

当应用程序完成对图像序列文件中数据的访问时，该函数 IoCloseSeq() 应当被调用。

要将下一幅图像追加到图像序列文件中，该函数 IoWriteNextSeqPicture() 可以调用。该函数需要来自先前调用的句柄 IoCreateSeq() 在参数 handle，参数中的图像帧号 frame 以及一个指向包含图像数据的缓冲区的指针作为参数 buffer。缓冲区的大小必须足以根据图像尺寸和 Pixel Format 提供图像数据，例如可以通过调用以下内容来计算 IoCalculateBufferSize().

处理视频文件（仅限 Windows）#

在使用适用于 Microsoft Windows 操作系统的 Framegrabber API 时，图像输入/输出库对音频视频交错（.avi）文件格式提供了有限的支持。

打开视频文件#

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);

要打开现有的视频文件以从中读取图像，该函数 IoOpenAVI() 该函数需要一个指向特定类型变量的指针 void * 在参数 handle 它将在访问视频文件中数据的函数中使用，文件名在参数中 file 以及三个用于图像尺寸的变量指针作为参数 width 和 height 以及参数中的每像素位数中使用 bitsPerPixel.

当应用程序完成对视频文件中数据的访问时，该函数 IoCloseAVI() 应当被调用。

若要从视频文件中读取图像，可以调用函数 IoReadAVIPicture() 可以调用。该函数需要来自先前调用的句柄 IoOpenSeq() 在参数 handle，要读取的图像索引以及指向用于存储图像数据的缓冲区的指针在参数中 buffer。缓冲区的大小必须足以根据图像尺寸和 Pixel Format 存储图像数据，例如可以通过调用以下内容来计算 IoCalculateBufferSize().

写入视频文件#

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);

若要创建一个用于写入图像的新视频文件，可以调用以下函数之一 IoCreateAVIGray(), IoCreateAVIGrayW(), IoCreateAVIColor() 或 IoCreateAVIColorW() 可以被调用。该函数期望接收一个指向类型的变量的指针 void * 在参数 handle 它将在访问视频文件中数据的函数中使用，文件名在参数中 file，参数中的图像尺寸 width 和 height 以及参数中的每秒帧数 fps。Pixel Format 由函数的变体决定： IoCreateAVIGray() 和 IoCreateAVIGrayW() 创建一个用于 8 位灰度图像数据的视频文件，以及 IoCreateAVIColor() 和 IoCreateAVIColorW() 创建一个用于 24 位 RGB 图像数据的文件。以……结尾的变体 W 允许使用宽字符字符串的文件名。

当应用程序完成对视频文件中数据的访问时，该函数 IoCloseAVI() 应当被调用。

若要将图像写入视频文件，可以调用函数 IoWriteAVIPicture() 可以被调用。该函数期望在参数中接收来自先前对创建视频文件的函数之一的调用的句柄 handle，参数中的视频序列中的图像索引 index 以及一个指向包含图像数据的缓冲区的指针作为参数 buffer。缓冲区的大小必须足以根据图像尺寸和 Pixel Format 提供图像数据，例如可以通过调用以下内容来计算 IoCalculateBufferSize().

从图像序列文件创建视频文件#

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

函数 IoSeqCreateAvi() 可以调用该函数从现有的图像序列文件创建视频文件。该函数需要来自先前调用的句柄 IoOpenSeq() 在参数 handle，参数中要创建的视频文件的文件名 file 以及要在视频文件中包含的来自图像序列文件的第一个和最后一个序列索引作为参数 fromSeqIndex 和 toSeqIndex。如果将值 -1 传递给参数 toSeqIndex，图像序列文件中自……起的所有图像 fromSeqIndex 包含在视频文件中。