跳至內容

iolibrt#

libiolibrt 程式庫提供了用於載入與儲存常見影像格式的功能。在 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 Bitmap (.bmp) 和 Tagged Image File Format (.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() 可用於此目的。

影像資料通常分為多個行（Line）。影像的高度構成影像資料的行數。每行由像素組成，影像的寬度為一行中的像素數。每個像素由一個或多個色彩分量表示。灰階影像通常每個像素包含一個分量，即灰階值。彩色影像通常包含三個分量，分別代表紅色、綠色和藍色各一個值。額外分量可能是透明度值，或是紅外線或 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。Pixel Format由函數的變體決定： 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 開始的所有影像都會包含在影片檔案中。