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 中的 Error Handling#

API 的大多數函式皆會傳回一個 int 結果代碼。如果函式呼叫成功執行，傳回值將為 0，或者對於某些函式而言，為大於或等於零的值。在大多數情況下，負值表示發生錯誤狀況。Error Codes 定義於標頭檔中 sisoIoFileErrorCodes.h 用於與讀取和寫入檔案相關的一般錯誤，以及 sisoIoBmpErrorCodes.h, sisoIoRawErrorCodes.h 進行明確的生命週期管理即呼叫 sisoIoTiffErrorCodes.h 用於與特定檔案格式相關的錯誤。

本說明文件其餘部分的程式碼範例將不包含 error handling，因為這取決於應用程式的特定需求。不過，在可行範圍內，仍會檢查傳回代碼以確保函式成功執行。

處理影像檔案#

影像輸入/輸出程式庫支援兩種標準影像檔案格式：Windows Bitmap (.bmp) 和 Tagged Image File Format (.tif 或 .tiff)。此外，對於無法以標準檔案格式表示的資料，支援具備最小標頭的 raw 資料檔案格式 (.raw)。.raw 檔案的標頭依序包含以下資訊：

4 個位元組，描述影像寬度
4 個位元組，描述影像高度
4 個位元組，描述每個像素的位元數。例如：8 位元灰階 = 8；14 位元灰階 = 14；10 位元 rgb = 30
4 個位元組，描述每個像素的位元組數；每個像素的位元組數會向上進位，例如 10 位元 = 2 個位元組
raw 資料

本章中的函式將透過檔名的副檔名來判斷檔案格式。

開啟影像檔案#

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() 以釋放該影像資料的記憶體。

若要取得影像資料的尺寸與資料格式，可呼叫函式 IoGetWidth(), IoGetHeight(), IoGetBitsPerPixel(), IoGetBitsPerComponent() 進行明確的生命週期管理即呼叫 IoGetNrOfComponents() 。

透過呼叫函式即可存取影像資料， IoImageGetData() 該函式會傳回一個指向包含影像資料之緩衝區的指標。若要取得緩衝區的大小，可使用函式 IoCalculateBufferSize() 。

影像資料通常分為多行。影像的高度是指組成影像資料的行數。每一行由像素組成，影像的寬度則是指單行中的像素數量。每個像素由一個或多個色彩分量表示。灰階影像通常每個像素有一個分量，即灰階值。彩色影像通常包含三個分量，分別代表紅色、綠色和藍色值。額外的分量可能是透明度值、紅外線或 X 光分量。這些分量通常使用相同的位元數進行編碼。分量數量與每個像素的位元數稱為 Pixel Format。（有時會使用每個分量的位元數來代替每個像素的位元數。）

根據 Pixel Format 的不同，每一行結尾可能包含一些填補資料（padding），以確保每一行的第一個像素從規定的對齊位置開始。函式 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 時，影像輸入/輸出庫對 Audio Video Interleave (.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。像素格式取決於該函式的變體： IoCreateAVIGray() 進行明確的生命週期管理即呼叫 IoCreateAVIGrayW() 建立用於 8-bit 灰階影像資料的視訊檔案，而 IoCreateAVIColor() 進行明確的生命週期管理即呼叫 IoCreateAVIColorW() 建立用於 24-bit 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 開始的所有影像都將包含在視訊檔案中。