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、または一部の関数では0以上の値になります。ほとんどの場合、負の値はエラー状態を示します。Error Codesは次のヘッダーファイルで定義されています。 sisoIoFileErrorCodes.h ファイルの読み書きに関連する一般的なエラー、および sisoIoBmpErrorCodes.h, sisoIoRawErrorCodes.h および sisoIoTiffErrorCodes.h 特定のファイル形式に関連するエラーに対して使用します。

このマニュアルの残りの部分にあるコード例には、アプリケーションの要件に固有のものであるためエラー処理は含まれていません。ただし、関数の正常終了を確認するため、可能な限りリターンコードがチェックされます。

画像ファイルの操作#

画像入出力ライブラリは、Windows Bitmap (.bmp) および Tagged Image File Format (.tif または .tiff) の2つの標準画像ファイルフォーマットをサポートしています。さらに、標準フォーマットで表現できないデータを扱うために、最小限のヘッダーを持つ RAW データファイルフォーマット (.raw) もサポートされています。.raw ファイルのヘッダーには、この順序で次の情報が含まれています。

画像幅を表す4バイト
画像高さを表す4バイト
1画素あたりのビット数を表す4バイト（例：8ビットグレースケール = 8、14ビットグレースケール = 14、10ビットRGB = 30）
1画素あたりのバイト数を表す4バイト。1画素あたりのバイト数は切り上げられます（例：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() を呼び出すことができます。両方の関数とも、最初のパラメーターにファイル名、2番目のパラメーターに画像データへのアクセスに使用される SisoIoImageEngine * 型の変数へのポインタを指定します。関数 IoImageOpenEx() は、赤、緑、青のデータの順序が反転している画像に対して、パラメーター rgbSequence を1に設定して呼び出すことができます。

画像が不要になった後には、画像データのMemoryを解放するために関数 IoFreeImage() を呼び出す必要があります。

画像データの寸法とデータフォーマットを取得するには、関数 IoGetWidth(), IoGetHeight(), IoGetBitsPerPixel(), IoGetBitsPerComponent() および IoGetNrOfComponents() を呼び出すことができます。

画像データには、関数 IoImageGetData() を呼び出すことでアクセスできます。この関数は、画像データを含むバッファへのポインタを返します。バッファのサイズを取得するには、関数 IoCalculateBufferSize() を使用できます。

画像データは通常、複数のラインに分割されます。画像の高さは、画像データを構成するラインの数です。各ラインはピクセルで構成され、画像の幅は1ラインあたりのピクセル数です。各ピクセルは1つ以上のカラーコンポーネントで表現されます。グレースケール画像は通常、ピクセルごとに単一のコンポーネント（グレースケール値）を持ちます。カラー画像は通常、赤、緑、青のそれぞれに1つの値を持つ3つのコンポーネントを含みます。追加のコンポーネントとして、不透明度の値や、赤外線またはX線のコンポーネントが含まれる場合があります。コンポーネントは通常、同じビット数を使用してエンコードされます。コンポーネントの数と1ピクセルあたりのビット数は、Pixel Formatと呼ばれます（ピクセルあたりのビット数の代わりに、コンポーネントあたりのビット数が使用されることもあります）。

Pixel Formatによっては、各ラインの最初のピクセルが定義されたアライメントで開始されるように、各ラインの末尾にパディングが含まれる場合があります。関数 IoCalculateBufferSize() は、ラインが常にバイト境界で始まると仮定するため、1ピクセルあたり8ビットの倍数を使用しないPixel Formatの場合、ラインの末尾にパディングビットが含まれる可能性があり、次のラインはバッファ内の次のバイトから始まります。

画像ファイルの保存#

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

画像データをファイルに保存するには、関数 IoSaveImageExt() を呼び出すことができます。この関数は、最初のパラメーターにファイル名、2番目のパラメーターに画像データを含むバッファへのポインタを受け取ります。残りの3つのパラメーターは、画像の寸法と1ピクセルあたりのビット数を関数に渡します。

次のファイルフォーマットを保存できます。 .tif,.tiff, .bmp, .raw。ファイルフォーマットは以下から自動的に検出されます。 const char * file.

画像シーケンスファイルの操作#

画像入出力ライブラリは、シンプルな画像シーケンスファイル形式をサポートしています。画像シーケンスファイルには、同じ寸法と Pixel Format を持つ複数の画像が格納されます。各画像には、シーケンスインデックスとフレーム番号が割り当てられます。シーケンスインデックスはファイル内での画像の位置に対応し、シーケンスインデックス 0 はシーケンスファイルの最初の画像、1 は2番目の画像を示します。フレーム番号は取り込み時に取得され、通常は 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 、およびパラメータとしての画像寸法に関する3つの変数へのポインタ 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 、およびパラメータとしての画像寸法に関する3つの変数へのポインタ 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 型の変数へのポインタと、パラメータ内の1秒あたりのフレーム数を期待します fps。ピクセルフォーマットは関数のバリエーションによって決定されます。 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 で始まる画像シーケンスファイル内のすべての画像がビデオファイルに含まれます。