画像オブジェクト
[FIE module]

説明

本ライブラリ群は、FIEライブラリにおける画像オブジェクトを扱うための物です。旧来、画像はメモリの先頭ポインタと必要な情報を生のまま渡すことによって扱われていましたが、 FIEでは、これらの画像に関する情報をまとめカプセル化した画像オブジェクトを使用します。画像オブジェクトは、ルート画像とチャイルド画像の２種からなり、これらの内部的な関係はおおよそ次図のようになります。

ルート画像は実際に画像メモリを保持するオブジェクトであり、幅、高さ、種別等の情報を保持します。チャイルド画像は実際には 画像メモリを保持しない オブジェクトで有り、ルート画像と関連づけて、そのルート画像の一部分のみを指定します。１個のルート画像に対して、複数のチャイルド画像が割り当て可能です。なお、ここで示している幅、高さ、等は全て内部的な情報であり、カプセル化されています。そのため、ユーザーがこれらの値を取得する際は、getter関数群を使用する必要があります。また、本画像オブジェクトはチャネル（レイヤ）の概念を持っており、１～１６チャネルの間で任意のチャネル数分の画像メモリを持つことができます。但し、各チャネルの画像メモリは全て同じ種別・サイズであるという制限があります。この制限はチャネルが主にカラー画像の処理に使用されることを想定しての設定であり、 UCHARの濃度値とDOUBLEの重みというような異なる型の情報を扱いたい場合は、複数の画像オブジェクトのインスタンスにて実現してください。

ルート画像とチャイルド画像: 先に述べた通り、ルート画像が実際に画像メモリを保持するオブジェクトであり、チャイルド画像はルート画像の一部分を指定するオブジェクトです。ここでは、これらの画像メモリがどのように確保されているかを示します。下図は21*16のルート画像の(6,7)-(15,13)の位置に10*7のチャイルド画像を割り当てた時の例です。

: 画像のメモリ構造は、座標(0,0)を基準にして、常にアドレスが増加するトップダウン形式です。本画像オブジェクトでは、画像の幅に４の倍数等の制限を設けていないため、自由なサイズの画像を作成することができます。しかし、そうすると２値画像ではパディングを設けなければ作成することができず、また濃淡画像の場合でも行先頭のアライメントがずれ、パフォーマンス上好ましくないため、パディングの挿入を行っています。そこで、このパディングを扱うために、幅と高さ以外に「ステップ」を設けています。ステップは「(x,y)から(x,y+1)に移動するために必要な移動量」であり、単位は画素です。（但し、画像形式が２値画像で有った場合は、単位は32bitブロックです。「２値画像について」を参照）単位を画素としているのは、利便性を考えての事ですが、このため画像メモリには下記の制限があります。当然 fnFIE_img_root_alloc() にて確保される画像メモリではこの条件を満たしていますが、インポートを利用する場合には注意が必要です。

: （幅 *（１画素のバイト数）+（パディングのバイト数））mod（１画素のバイト数）＝０

: ルート画像を確保すると、上記の形式にて適切なメモリ領域が確保され、利用可能な状態になります。一方、チャイルド画像を確保した場合は、メモリは確保されません。これは先に述べたとおり、チャイルド画像がルート画像の一部分を指定するためのものだからです。上図の例では、チャイルド画像は(0,0)のルート画像座標系での座標(6,7) と、チャイルド画像の幅と高さのみを保持します。ユーザーからチャイルド画像のメモリ領域への参照要請があった場合は、割り当てられているルート画像から必要な情報を取得して、オフセット分を計算してから回答します。より詳しく言えば、 fnFIE_img_get_ch_adrs() にてチャイルド画像のアドレスを取得すると、この関数の内部で割り当てられているルート画像の(0,0)のアドレスを取得し、それに6+step*7を加えてルート画像座標系で (6,7)のアドレス＝チャイルド画像の(0,0)のアドレスを返すと言うことです。

: ところで、チャイルド画像のステップはルート画像のステップと同じ値になります。これは、ステップが「(x,y)から(x,y+1)に移動するために必要な移動量」で有ると言うことを思い出せば容易に理解できます。このステップによって、Ｙ座標の移動量が抽象化しているため、チャイルド画像かルート画像かを意識することなく使用することができるのです。実際の例は次節の画像種別でサンプルを交えて説明しているので参照してください。

NULLチャイルド画像: NULLチャイルド画像とは、ルート画像に割り当てられていないが、画像オブジェクトのインスタンスだけは存在しているチャイルド画像の事です。例えば、ルート画像にチャイルド画像を割り当ててある状態で、割り当てられているルート画像を先に解放すると、割り当てているチャイルド画像は割り当て先が無くなってしまうため、NULLチャイルド画像になります。

: NULLチャイルド画像では、画像メモリがNULLの状態である画像であり、メモリアドレス、チャネル数、画像種別、幅、高さ、ステップ、の各パラメータは全て0(NULL)として処理されます。 NULLチャイルド画像かどうかの判定は、これらパラメータのgetter関数群にて、返ってきた値が0かどうかで判定できます。 NULLチャイルド画像は、 fnFIE_img_child_attach() / fnFIE_img_child_attach_single_ch() 関数にてルート画像への割り当てをし直すことで、NULLチャイルド画像ではなくなります。また、NULLチャイルド画像であっても、不要になったら fnFIE_free_object() 関数にて解放しなければいけない点には注意が必要です。

画素種別: 現在、本画像オブジェクトで定義される画素タイプは次の１１種類です。画素種別は enum f_imgtype にて定義されている値で指定します。

: ■ F_IMG_BIN : ２値画像(１画素1bit)
１画素１ビットで表されます。そのままでは扱えないため、４ＢＹＴＥ(UINT)３２画素をパッキングして保持しています。２値画像はパッキングされているため、取り扱いが特殊です。実際の取り扱いについては、２値画像についての章を参照してください。

: なお、windowsのDIBでの２値画像とはパッキング形式が違う事に注意してください。 DIBは、１ＢＹＴＥ(UCHAR)８画素パッキングであるため、４ＢＹＴＥ(UINT)３２画素パッキングの本形式とは並びが異なるためです。（リトルエンディアン⊃IA-32プロセッサの場合）下図：メモリ上での２値画素の並び順

: ■ F_IMG_UC8 ：8bit濃淡画像
１画素が符号無し８ビット(UCHAR)で表されます。つまり、濃度値は0～255の範囲となります。

: ■ F_IMG_S16 ：符号付き16bit濃淡画像
１画素が符号付き１６ビット(SHORT)で表されます。つまり、濃度値は-32768～+32767の範囲となります。

: ■ F_IMG_US16 ：16bit濃淡画像
１画素が符号無し１６ビット(USHORT)で表されます。つまり、濃度値は0～65535の範囲となります。

: ■ F_IMG_DOUBLE ：倍精度浮動小数点画像
１画素が倍精度浮動小数点(DOUBLE)で表されます。

: ■ F_IMG_RGBQUAD ：32bitパッキングカラー
１画素が32bitで、８ビットの値が４つパッキングされた形式です。通常、RGBQUAD構造体の配列として使用します。なお、この形式は当社の従来ライブラリ(FVL, FVX 等)との互換性を意識して設けられた物であり、 FIEライブラリでの新規開発で使用することは推奨しません。 F_IMG_UC8形式でチャネルを使用してカラーを扱う事を推奨します。

: ■ F_IMG_I32 ：符号付き32bit濃淡画像
１画素が符号付き３２ビット(INT)で表されます。つまり、濃度値は $[-2^{31}, 2^{31}-1]$ の範囲となります。

: ■ F_IMG_UI32 ：32bit濃淡画像
１画素が符号無し３２ビット(UINT)で表されます。つまり、濃度値は $[0, 2^{32}-1]$ の範囲となります。

: ■ F_IMG_I64 ：符号付き64bit濃淡画像
１画素が符号付き６４ビット(DLONG)で表されます。つまり、濃度値は $[-2^{63}, 2^{63}-1]$ の範囲となります。

: ■ F_IMG_FLOAT ：単精度浮動小数点画像
１画素が単精度浮動小数点(FLOAT)で表されます。

: ■ F_IMG_RGBTRIPLE ：24bitパッキングカラー
１画素が24bitで、８ビットの値が３つパッキングされた形式です。UCHAR型にて扱います。

画像メモリへのアクセス

２値画像形式(F_IMG_BIN)を除いて、特定の画素へアクセスするには、次の手順で行います。

fnFIE_img_get_ch_adrs() にてアドレスを取得し、目的の型のポインタにキャスト＆代入
fnFIE_img_get_step() or fnFIE_img_get_params() にてステップを取得
*( ポインタ + (Ｘ座標値) + ((ステップ)*(Ｙ座標値)) ) が目的の画素値です。

: 上記の手順から分かる通り、このオブジェクトを使って処理を作る場合、 ルート画像とチャイルド画像を区別する必要がありません。 つまり、処理座標範囲の指定をわざわざ設けなくとも、このチャイルド画像を使えば同等の処理が可能になるわけです。

以下は画像型が符号付き16bit濃淡(F_IMG_S16)の画像を作成し、ルート画像、チャイルド画像それぞれの座標(3,5)の画素値を100にする例です。ステップの取り扱い方、アドレスの計算法と共に、ルート画像でもチャイルド画像でも処理ルーチンが同じ点に注意してください。

// エラー処理は省略しているので注意して下さい。
#include "fie.h"

void set_x3y5( FHANDLE himg )
{
    SHORT *adrs;
    INT_PTR step;

    // 画像の(0,0)のアドレスを取得
    adrs = (SHORT*)fnFIE_img_get_ch_adrs( himg, 0 );

    // ｙ座標を+1するために必要な移動量を取得
    step = fnFIE_img_get_step( himg );

    // 座標(3,5) の画素値を100に
    *(adrs + step*5 + 3) = 100;
}


INT main()
{
    FHANDLE himg, himg_child;

    // FIEライブラリの使用前に必ずコールする必要があります。
    fnFIE_setup();

    // 100x100 のルート画像を確保
    himg = fnFIE_img_root_alloc( F_IMG_S16, 1, 100, 100 );

    // ルート画像の(10,10)-(49,49)をチャイルド画像として割り当て
    himg_child = fnFIE_img_child_alloc( himg, 10, 10, 40, 40 );

    // ルート画像の座標(3,5)を100にセット
    set_x3y5( himg );

    // チャイルド画像の座標(3,5) (==ルート画像の座標系で(13,15)) を100にセット
    set_x3y5( himg_child );

    fnFIE_free_object( himg_child );
    fnFIE_free_object( himg );

    // 終了処理
    fnFIE_teardown();

    return 0;
}

２値画像について: F_IMG_BIN で示される２値画像は、UINTに３２画素がパッキングされているという特殊性から、他の形式と比べてアドレスの扱い方が特殊です。他の画像形式では、メモリアドレスが確定すると、画素が一意に決定されますが、２値画像では３２画素分パッキングされているため、アドレスが確定しても画素が一意に決まりません。このため、２値画像のアドレス取得関数 fnFIE_img_get_ch_binadrs() , fnFIE_img_get_binadrs() では、そのアドレスにおける画素のビット位置を取得するための変数が追加されています。

    VOID fnFIE_img_get_binadrs( FHANDLE himg, UINT** adrs, INT *bitpos )

: アドレス値 adrs には画像 himg の座標(0,0)の画素が含まれるUINTブロックのアドレスが代入され、そのブロック内のビット位置が bitpos に代入されます。ビット位置変数 bitpos はブロック内一番左側、つまりＸ座標の一番小さい画素を０とする０～３１の値です。

また、 fnFIE_img_get_step() 関数にて取得するステップ値も他の形式とは性質が異なります。２値画像でのステップは単位が画素ではなく、「UINTブロック(32bitブロック)の数」にて表されます。つまり、「(x,y)の画素がパッキングされているUINTブロック」から、「(x,y+1)の画素がパッキングされているUINTブロック」へ移動するのに必要な移動量になっています。以下は100x100の２値画像の(10,10)-(49,49)にチャイルド画像を割り当て、そのチャイルド画像の(0,5)の画素値を１にするサンプルです。

// エラー処理は省略しているので注意して下さい。
#include "fie.h"

INT main()
{
    FHANDLE himg, himg_child;
    UINT *adrs;
    INT bpos;
    INT_PTR step;

    // FIEライブラリの使用前に必ずコールする必要があります。
    fnFIE_setup();

    // 100x100 のルート画像を確保します
    himg = fnFIE_img_root_alloc( F_IMG_BIN, 1, 100, 100 );

    // ルート画像の(10,10)-(49,49)をチャイルド画像として割り当て
    himg_child = fnFIE_img_child_alloc( himg, 10, 10, 40, 40 );

    // チャイルド画像の(0,0)が有る32bitブロックのアドレスを取得
    fnFIE_img_get_ch_binadrs( himg_child, 0, &adrs, &bpos );
    // ｙ座標を+1するために必要な移動量を取得
    step = fnFIE_img_get_step( himg_child );

    // 座標(0,5) の画素値を1に
    *(adrs+step*5) |= 0x80000000 >> bpos;

    // 座標(7,8) の画素値を0に
    *(adrs+step*8 + (bpos + 7) / 32) &= ~(0x80000000 >> (bpos + 7) % 32);

    fnFIE_free_object( himg_child );
    fnFIE_free_object( himg );

    // 終了処理
    fnFIE_teardown();

    return 0;
}


マクロ定義
#define	F_IMG_MAX_CHANNELS 16
列挙型
enum	f_imgtype { F_IMG_BIN = 1, F_IMG_UC8 = 2, F_IMG_S16 = 3, F_IMG_US16 = 4, F_IMG_DOUBLE = 5, F_IMG_RGBQUAD = 6, F_IMG_I32 = 7, F_IMG_UI32 = 8, F_IMG_I64 = 9, F_IMG_FLOAT = 11, F_IMG_RGBTRIPLE = 12 }
	画像種別 [詳細]
関数
INT FVALGAPI	fnFIE_img_set_padding_size (INT exp)
	パディングサイズの設定
FHANDLE FVALGAPI	fnFIE_img_root_alloc (INT type, INT channels, INT width, INT height)
	ルート画像の確保
FHANDLE FVALGAPI	fnFIE_img_root_import_alloc (VOID **adrss, INT channels, INT type, INT_PTR step, INT width, INT height)
	ルート画像の確保(import版)
INT FVALGAPI	fnFIE_img_root_realloc (FHANDLE himg, INT type, INT channels, INT width, INT height)
	ルート画像の変更
INT FVALGAPI	fnFIE_img_root_copy (FHANDLE hsrc, FHANDLE *hdst)
	ルート画像のコピー
FHANDLE FVALGAPI	fnFIE_img_child_alloc (FHANDLE hroot, INT offset_x, INT offset_y, INT width, INT height)
	チャイルド画像の確保
FHANDLE FVALGAPI	fnFIE_img_child_alloc_single_ch (FHANDLE hroot, INT ch, INT offset_x, INT offset_y, INT width, INT height)
	チャイルド画像の確保(単一チャネル割り当て版)
INT FVALGAPI	fnFIE_img_child_detach (FHANDLE hchild)
	チャイルド画像のルート画像への割り当てを解除(NULLチャイルド画像にする)
INT FVALGAPI	fnFIE_img_child_attach (FHANDLE hchild, FHANDLE hroot, INT x, INT y, INT width, INT height)
	チャイルド画像をルート画像へ割り当てる
INT FVALGAPI	fnFIE_img_child_attach_single_ch (FHANDLE hchild, FHANDLE hroot, INT ch, INT x, INT y, INT width, INT height)
	チャイルド画像をルート画像へ割り当てる
VOID FVALGAPI	fnFIE_img_get_ch_binadrs (FHANDLE himg, INT channel, UINT *adrs, INT bitpos)
	２値画像の画像アドレス取得
VOID FVALGAPI	fnFIE_img_get_binadrs (FHANDLE himg, UINT *adrs, INT bitpos)
	２値画像の画像アドレス取得(チャネル０固定)
VOID *FVALGAPI	fnFIE_img_get_ch_adrs (FHANDLE himg, INT channel)
	画像アドレス取得
VOID *FVALGAPI	fnFIE_img_get_adrs (FHANDLE himg)
	画像アドレス取得(チャネル０固定)
INT FVALGAPI	fnFIE_img_get_params (FHANDLE himg, INT channels, INT type, INT_PTR step, INT width, INT *height)
	画像情報取得
INT FVALGAPI	fnFIE_img_get_channels (FHANDLE himg)
	画像情報取得(チャネル数)
INT FVALGAPI	fnFIE_img_get_type (FHANDLE himg)
	画像情報取得(画像タイプ)
INT_PTR FVALGAPI	fnFIE_img_get_step (FHANDLE himg)
	画像情報取得(ステップ)
INT_PTR FVALGAPI	fnFIE_img_get_pixel_size (FHANDLE himg)
	画像情報取得(画素サイズ)
INT_PTR FVALGAPI	fnFIE_img_get_step_as_bytes (FHANDLE himg)
	画像情報取得(メモリステップ)
INT FVALGAPI	fnFIE_img_get_width (FHANDLE himg)
	画像情報取得(画像幅)
INT FVALGAPI	fnFIE_img_get_height (FHANDLE himg)
	画像情報取得(画像高さ)
INT FVALGAPI	fnFIE_img_get_root_params (FHANDLE himg, FHANDLE hroot, INT channel, INT offset_x, INT offset_y)
	画像のルート情報取得
INT FVALGAPI	fnFIE_img_is_overlaped (FHANDLE himg1, FHANDLE himg2)
	画像オーバーラップ判定

マクロ定義

#define F_IMG_MAX_CHANNELS 16

FIE画像オブジェクトのチャネル数の最大値

列挙型

enum f_imgtype

画像種別

列挙型の値:

F_IMG_BIN	２値画像(1bit/1画素)
F_IMG_UC8	8bit濃淡画像
F_IMG_S16	符号付き16bit濃淡画像
F_IMG_US16	16bit濃淡画像
F_IMG_DOUBLE	倍精度浮動小数点画像
F_IMG_RGBQUAD	32bitパッキングカラー画像
F_IMG_I32	符号付き32bit濃淡画像
F_IMG_UI32	32bit濃淡画像
F_IMG_I64	符号付き64bit濃淡画像
F_IMG_FLOAT	単精度浮動小数点画像
F_IMG_RGBTRIPLE	24bitパッキングカラー画像

関数

INT FVALGAPI fnFIE_img_set_padding_size ( INT exp )

パディングサイズの設定

fnFIE_img_root_alloc() 又は fnFIE_img_root_realloc() 時に、ステップ（画像メモリ幅）を何バイト単位にするかを 2^n の指数nで設定します。画像幅がこの倍数で無い場合は、適切なパディングが挿入され、ステップは 2^n の倍数バイトになります。但し、１画素のバイト数が 2^n よりも大きい場合、ステップは１画素のバイト数の倍数になります。

本関数を１度も呼ばなかった場合のデフォルト値は n=3 です。特別な理由が無い限りデフォルトの n=3 のまま使用することを推奨します。

example

画像型 F_IMG_UC8 で n=0 の場合 → ステップは1byteの倍数
画像型 F_IMG_UC8 で n=4 の場合 → ステップは16byteの倍数
画像型 F_IMG_DOUBLE で n=0 の場合 → ステップは8byteの倍数
画像型 F_IMG_DOUBLE で n=4 の場合 → ステップは16byteの倍数

引数:

[in] exp ステップサイズ 2^n の乗数n (0≦n≦10)
デフォルト==3

注意:: この関数で設定された値は、グローバル変数にて保持され、以降の全ての fnFIE_img_root_alloc() , fnFIE_img_root_realloc() の動作に影響を及ぼすため注意してください。

FHANDLE FVALGAPI fnFIE_img_root_alloc	(	INT	type,
		INT	channels,
		INT	width,
		INT	height
	)

ルート画像の確保

ルート画像を確保します。

生成された画像ハンドルが不要になったら fnFIE_free_object() にて解放してください。

引数:

`[in]`	type	確保する画像種別。下記のいずれかを指定。 F_IMG_BIN F_IMG_UC8 F_IMG_S16 F_IMG_US16 F_IMG_DOUBLE F_IMG_RGBQUAD F_IMG_I32 F_IMG_UI32 F_IMG_I64 F_IMG_FLOAT F_IMG_RGBTRIPLE
`[in]`	channels	チャネル数(1～16)
`[in]`	width	画像幅(1以上)
`[in]`	height	画像高さ(1以上)

戻り値:: 確保された画像のハンドルライセンスエラー、未初期化エラー、またはメモリ不足で確保に失敗した場合はNULLを返します。

FHANDLE FVALGAPI fnFIE_img_root_import_alloc	(	VOID **	adrss,
		INT	channels,
		INT	type,
		INT_PTR	step,
		INT	width,
		INT	height
	)

ルート画像の確保(import版)

外部で確保された画像メモリ空間を使用して、ルート画像を作成します。本関数で作成したルート画像はリサイズすることができません。また、本関数で作成されたルート画像では fnFIE_free_object() 関数によってオブジェクトを解放しても、登録された画像メモリは解放しません。このため、登録したメモリは登録したユーザー側で解放処理を行う必要が有ります。

引数:

`[in]`	adrss	画像メモリのポインタ列。 (チャネル0から順番になった配列で channels パラメータ個分の要素が必要)
`[in]`	channels	チャネル数(1～16)
`[in]`	type	画像種別 F_IMG_BIN F_IMG_UC8 F_IMG_S16 F_IMG_US16 F_IMG_DOUBLE F_IMG_RGBQUAD F_IMG_I32 F_IMG_UI32 F_IMG_I64 F_IMG_FLOAT F_IMG_RGBTRIPLE
`[in]`	step	画像ステップ(メモリ横幅：画素サイズ単位) 但し、下記の画像型の場合は単位が変わります。 F_IMG_BIN型の場合：UINTブロック数 F_IMG_RGBTRIPLE型の場合：バイト単位
`[in]`	width	画像幅(1以上)
`[in]`	height	画像高さ(1以上)

戻り値:: 確保された画像のハンドルライセンスエラー、未初期化エラー、またはメモリ不足で確保に失敗した場合はNULLを返します。

INT FVALGAPI fnFIE_img_root_realloc	(	FHANDLE	himg,
		INT	type,
		INT	channels,
		INT	width,
		INT	height
	)

ルート画像の変更

ルート画像のサイズ等を変更します。

注意: ルート画像をreallocすると、それまでattachされていたチャイルド画像はすべてNULLチャイルド画像になります。また fnFIE_img_root_import_alloc() にて確保されたルート画像が指定された場合は、 F_ERR_INVALID_IMAGE エラーとなります。

引数:

`[in]`	himg	サイズを変更する画像のハンドル
`[in]`	type	確保する画像種別 F_IMG_BIN F_IMG_UC8 F_IMG_S16 F_IMG_US16 F_IMG_DOUBLE F_IMG_RGBQUAD F_IMG_I32 F_IMG_UI32 F_IMG_I64 F_IMG_FLOAT F_IMG_RGBTRIPLE
`[in]`	channels	チャネル数(1～16)
`[in]`	width	画像幅(1以上)
`[in]`	height	画像高さ(1以上)

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_NOMEMORY	メモリ不足で確保に失敗した
	F_ERR_INVALID_IMAGE	不正な画像が渡された(ハンドルが不正orインポートされていてリサイズ不可)
	F_ERR_INVALID_PARAM	パラメータ不正
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

INT FVALGAPI fnFIE_img_root_copy	(	FHANDLE	hsrc,
		FHANDLE *	hdst
	)

ルート画像のコピー

hsrc に指定された画像と同じサイズのルート画像を新たに生成し、内容を複製して *hdst に返します。
hsrc に指定する画像は、ルート画像でもチャイルド画像でもかまいません。大きなルート画像の小さな一部分を指し示すチャイルド画像を当関数でコピーした場合、元のルート画像の小さな一部分と同サイズの新たなルート画像が生成して返されます。

生成された画像ハンドル(*hdst)が不要になったら fnFIE_free_object() にて解放してください。

引数:

`[in]`	hsrc	コピー元の画像のハンドル( type: all )
`[out]`	hdst	コピーされたルート画像のハンドル関数エントリー時 *hdst == NULL でなければなりません。

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_PARAM	パラメータエラー( hdst がNULL または *hdst != NULL )
	F_ERR_INVALID_IMAGE	不正画像エラー( hsrc が不正 )
	F_ERR_NOMEMORY	メモリ不足エラー
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

FHANDLE FVALGAPI fnFIE_img_child_alloc	(	FHANDLE	hroot,
		INT	offset_x,
		INT	offset_y,
		INT	width,
		INT	height
	)

チャイルド画像の確保

指定のルート画像の部分矩形領域をチャイルド画像に割り当てます。割り当て先の画像( hroot パラメータ)には、ルート画像でもチャイルド画像でもどちらでも指定することができます。 hroot にルート画像が渡された場合は、本関数で作成されたチャイルド画像は、そのルート画像のチャイルドになります。 hroot にチャイルド画像が渡された場合は、「 hroot に渡されたチャイルド画像が割り当てているルート画像」のチャイルドになります。

ルート画像が２以上のチャネルを持っていた場合は、作成されたチャイルド画像も同じチャネル数を持ちます。（下図参照）

ルート画像の領域をはみ出すチャイルド画像を作成することはできません。はみ出る領域を指定した場合には NULL を返します。また、全パラメータに0を指定した場合は、ルート画像が割り当てられていない NULLチャイルド画像を生成します。

生成された画像ハンドルが不要になったら fnFIE_free_object() にて解放してください。

引数:

`[in]`	hroot	ルート画像のハンドル(チャイルド画像でも可)
`[in]`	offset_x	ルート座標系における、チャイルド領域左上x座標 (0≦ offset_x ≦ (ルート画像の幅 -1 - width ))
`[in]`	offset_y	ルート座標系における、チャイルド領域左上y座標 (0≦ offset_y ≦ (ルート画像の高さ -1 - height ))
`[in]`	width	チャイルド領域幅 (1≦ width ≦(ルート画像の幅 - offset_x ))
`[in]`	height	チャイルド領域高さ(1≦ height ≦(ルート画像の高さ - offset_y ))

戻り値:: 正常終了した場合は、確保されたチャイルド画像のハンドルを返す。ライセンスエラー、未初期化エラー、パラメータ不正やメモリ確保失敗により異常終了した場合は、NULLを返す

参照:: fnFIE_img_child_alloc_single_ch()

FHANDLE FVALGAPI fnFIE_img_child_alloc_single_ch	(	FHANDLE	hroot,
		INT	ch,
		INT	offset_x,
		INT	offset_y,
		INT	width,
		INT	height
	)

チャイルド画像の確保(単一チャネル割り当て版)

指定のルート画像の部分矩形領域をチャイルド画像に割り当てます。割り当て先の画像( hroot パラメータ)には、ルート画像でもチャイルド画像でもどちらでも指定することができます。 hroot にルート画像が渡された場合は、本関数で作成されたチャイルド画像は、そのルート画像のチャイルドになります。 hroot にチャイルド画像が渡された場合は、「 hroot に渡されたチャイルド画像が割り当てているルート画像」のチャイルドになります。

作成されるチャイルド画像は、ルート画像の指定の単一チャネルのみに割り当てられます。（下図参照）

ルート画像の領域をはみ出すチャイルド画像を作成することはできません。はみ出る領域を指定した場合には NULL を返します。全パラメータに0を指定した場合は、ルート画像が割り当てられていない NULLチャイルド画像を生成します。

生成された画像ハンドルが不要になったら fnFIE_free_object() にて解放してください。

引数:

`[in]`	hroot	ルート画像のハンドル(チャイルド画像でも可)
`[in]`	ch	チャイルド画像を割り当てる、ルート画像のチャネル(0≦ ch ≦(ルート画像のch数-1))
`[in]`	offset_x	ルート座標系における、チャイルド領域左上x座標(0≦ offset_x ≦(ルート画像の幅 -1 - width ))
`[in]`	offset_y	ルート座標系における、チャイルド領域左上y座標(0≦ offset_y ≦(ルート画像の高さ -1 - height ))
`[in]`	width	チャイルド領域幅 (1≦ width ≦(ルート画像の幅 - offset_x ))
`[in]`	height	チャイルド領域高さ(1≦ height ≦(ルート画像の高さ - offset_y ))

戻り値:: 正常終了した場合は、確保されたチャイルド画像のハンドルを返します。ライセンスエラー、未初期化エラー、パラメータ不正やメモリ確保失敗により異常終了した場合は、NULLを返します。

参照:: fnFIE_img_child_alloc()

INT FVALGAPI fnFIE_img_child_detach ( FHANDLE hchild )

チャイルド画像のルート画像への割り当てを解除(NULLチャイルド画像にする)

チャイルド画像のルート画像への割り当てを解除します。割り当てを解除されたチャイルド画像は画像を保持しない(NULLポインタを持つ) 画像ハンドラになります。

引数:

[in] hchild 解除するチャイルド画像のハンドル

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_IMAGE	異常終了(ハンドルにNULLが渡された or ルート画像が渡された)
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

INT FVALGAPI fnFIE_img_child_attach	(	FHANDLE	hchild,
		FHANDLE	hroot,
		INT	x,
		INT	y,
		INT	width,
		INT	height
	)

チャイルド画像をルート画像へ割り当てる

既存のチャイルド画像を、指定のルート画像に割り当て直します。割り当て先の画像( hroot パラメータ)には、ルート画像でもチャイルド画像でもどちらでも指定することができます。 hroot にルート画像が渡された場合は、本関数で作成されたチャイルド画像は、そのルート画像のチャイルドになります。 hroot にチャイルド画像が渡された場合は、「 hroot に渡されたチャイルド画像が割り当てているルート画像」のチャイルドになります。

ルート画像が２以上のチャネルを持っていた場合は、作成されたチャイルド画像も同じチャネル数を持ちます。（下図参照）

ルート画像の領域をはみ出すチャイルド画像を作成することはできません。はみ出る領域を指定した場合には F_ERR_INVALID_PARAM を返します。

引数:

`[in]`	hchild	割り当てるチャイルド画像
`[in]`	hroot	割り当てられるれるルート画像(チャイルド画像でも可)
`[in]`	x	領域左上x座標 (0≦ x ≦(ルート画像の幅 -1 - width ))
`[in]`	y	領域左上y座標 (0≦ y ≦(ルート画像の高さ -1 - height ))
`[in]`	width	領域幅 (1≦ width ≦(ルート画像の幅 - x ))
`[in]`	height	領域高さ (1≦ height ≦(ルート画像の高さ- y ))

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_PARAM	パラメータエラー
	F_ERR_INVALID_IMAGE	不正な画像が渡されました
	F_ERR_NOMEMORY	メモリ不足により異常終了
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

INT FVALGAPI fnFIE_img_child_attach_single_ch	(	FHANDLE	hchild,
		FHANDLE	hroot,
		INT	ch,
		INT	x,
		INT	y,
		INT	width,
		INT	height
	)

チャイルド画像をルート画像へ割り当てる

既存のチャイルド画像を、指定のルート画像に割り当て直します。割り当て先の画像( hroot パラメータ)には、ルート画像でもチャイルド画像でもどちらでも指定することができます。 hroot にルート画像が渡された場合は、本関数で作成されたチャイルド画像は、そのルート画像のチャイルドになります。 hroot にチャイルド画像が渡された場合は、「 hroot に渡されたチャイルド画像が割り当てているルート画像」のチャイルドになります。

作成されるチャイルド画像は、ルート画像の指定の単一チャネルのみに割り当てられます。（下図参照）

ルート画像の領域をはみ出すチャイルド画像を作成することはできません。はみ出る領域を指定した場合には F_ERR_INVALID_PARAM を返します。

引数:

`[in]`	hchild	割り当てるチャイルド画像
`[in]`	hroot	割り当てられるルート画像(チャイルド画像でも可)
`[in]`	ch	チャイルド画像を割り当てる、ルート画像のチャネル(0≦ ch ≦(ルート画像のch数-1))
`[in]`	x	領域左上x座標 (0≦ x ≦(ルート画像の幅 -1 - width ))
`[in]`	y	領域左上y座標 (0≦ y ≦(ルート画像の高さ -1 - height ))
`[in]`	width	領域幅 (1≦ width ≦(ルート画像の幅- x ))
`[in]`	height	領域高さ (1≦ height ≦(ルート画像の高さ- y ))

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_PARAM	パラメータエラー
	F_ERR_INVALID_IMAGE	不正な画像が渡されました
	F_ERR_NOMEMORY	メモリ不足により異常終了
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

VOID FVALGAPI fnFIE_img_get_ch_binadrs	(	FHANDLE	himg,
		INT	channel,
		UINT **	adrs,
		INT *	bitpos
	)

２値画像の画像アドレス取得

himg パラメータで指定された２値画像の左上アドレスを返します。画像が２値画像(typeがF_IMG_BIN)で無かった場合には adrs, bitpos 共に0を返します。

２値画像はUINTに32画素がパッキングされた特殊形式のため、本関数を使用してアドレスを取得します。本関数では、adrsパラメータにて画像左上の画素がパッキングされているブロックのアドレスを adrs に、同画素のパッキングされているブロック内のビット位置を bitpos にて返します。 bitpos はブロック内一番左側 (X座標が小さい方)を0とする0～31の値になります。

２値画像以外の画像に対しては fnFIE_img_get_adrs() を使用して下さい。

引数:

`[in]`	himg	アドレスを取得する画像のハンドル
`[in]`	channel	アドレスを取得するチャネルの番号
`[out]`	adrs	左上画素が含まれるブロックのアドレス
`[out]`	bitpos	ブロック内の左上画素のビット位置。ブロック内一番左側(X座標が小さい方)を0とする0～31の値。

参照:: fnFIE_img_get_binadrs(), fnFIE_img_get_ch_adrs()

VOID FVALGAPI fnFIE_img_get_binadrs	(	FHANDLE	himg,
		UINT **	adrs,
		INT *	bitpos
	)

２値画像の画像アドレス取得(チャネル０固定)

himg パラメータで指定された２値画像の「チャネル０番の」左上アドレスを返します。 0番以外のチャネルのアドレスが取得したい場合は fnFIE_img_get_ch_binadrs() を使用して下さい。画像が２値画像(F_IMG_BIN)で無かった場合には adrs, bitpos 共に0を返します。

２値画像はUINTに32画素がパッキングされた特殊形式のため、本関数を使用してアドレスを取得します。本関数では adrs パラメータにて画像左上の画素がパッキングされているブロックのアドレスを adrs に、同画素のパッキングされているブロック内のビット位置を bitpos にて返します。 bitpos はブロック内一番左側 (X座標が小さい方)を0とする0～31の値になります。

２値画像以外の画像に対しては fnFIE_img_get_adrs() を使用して下さい。

引数:

`[in]`	himg	アドレスを取得する画像のハンドル
`[out]`	adrs	左上画素が含まれるブロックのアドレス
`[out]`	bitpos	ブロック内の左上画素のビット位置。ブロック内一番左側(X座標が小さい方)を0とする0～31の値。

参照:: fnFIE_img_get_ch_binadrs(), fnFIE_img_get_adrs()

VOID* FVALGAPI fnFIE_img_get_ch_adrs	(	FHANDLE	himg,
		INT	channel
	)

画像アドレス取得

imgパラメータで指定された画像の左上アドレスを返します。但し、画像が２値画像(F_IMG_BIN)の場合は、本関数では取得できません。この場合は、本関数ではNULLを返しますので、 fnFIE_img_get_binadrs() を代わりに使用して下さい。

引数:

`[in]`	himg	アドレスを取得する画像のハンドル
`[in]`	channel	アドレスを取得するチャネル番号

戻り値:: 正常終了した場合は、左上画素のアドレスを返します。異常終了した場合は、NULLを返します。(パラメータエラー、画像形式エラー、ライセンスエラー、または未初期化エラー)

参照:: fnFIE_img_get_binadrs(), fnFIE_img_get_adrs()

VOID* FVALGAPI fnFIE_img_get_adrs ( FHANDLE himg )

画像アドレス取得(チャネル０固定)

himg パラメータで指定された画像の「チャネル０番の」左上アドレスを返します。 0番以外のチャネルのアドレスが取得したい場合は fnFIE_img_get_ch_adrs() を使用して下さい。但し、画像が２値画像(F_IMG_BIN)の場合は、本関数では取得できません。この場合は、本関数ではNULLを返しますので、 fnFIE_img_get_binadrs() を代わりに使用して下さい。

引数:

[in] himg アドレスを取得する画像のハンドル

戻り値:: 正常終了した場合は、左上画素のアドレスを返します。異常終了した場合は、NULLを返します。(パラメータエラー、画像形式エラー、ライセンスエラー、または未初期化エラー)

参照:: fnFIE_img_get_ch_adrs(), fnFIE_img_get_binadrs()

INT FVALGAPI fnFIE_img_get_params	(	FHANDLE	himg,
		INT *	channels,
		INT *	type,
		INT_PTR *	step,
		INT *	width,
		INT *	height
	)

画像情報取得

himg パラメータで指定された画像の情報を取得します。取得できる情報は、チャネル数、種別、幅、高さ、ステップです。指定された画像がNULLチャイルド画像だった場合は、各パラメータには0を返し、正常終了します。

出力先の引数( channels, type, step, width, height )はすべてNULLポインタチェックがされるため、必要の無いものにはNULLが指定可能です。このとき himg 以外のパラメータはNULLであっても、エラーにはならず正常終了となります。例えば、チャネル数とステップだけを取得したければ、 channels と step に有効なポインタを渡し、他の type, width, hegiht にはNULLを指定すれば良いです。

引数:

`[in]`	himg	情報を取得する画像のハンドル
`[out]`	channels	画像メモリのチャネル数
`[out]`	type	画像メモリの種別
`[out]`	step	画像メモリの行ステップ(画素単位)
`[out]`	width	領域幅
`[out]`	height	領域高さ

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_IMAGE	不正な画像ハンドルが渡されたため異常終了
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

INT FVALGAPI fnFIE_img_get_channels ( FHANDLE himg )

画像情報取得(チャネル数)

himg パラメータで指定された画像のチャネル数を取得します。指定された画像がNULLチャイルド画像だった場合は、0が返ります。

引数:

[in] himg 情報を取得する画像のハンドル

戻り値:: 正常終了した場合は、画像のチャネル数を返します。異常終了した場合は、-1を返します。

INT FVALGAPI fnFIE_img_get_type ( FHANDLE himg )

画像情報取得(画像タイプ)

himg パラメータで指定された画像のタイプを取得します。指定された画像がNULLチャイルド画像だった場合は、0が返ります。

引数:

[in] himg 情報を取得する画像のハンドル

戻り値:: 正常終了した場合は、画像のタイプを返します。異常終了した場合は、-1を返します。

INT_PTR FVALGAPI fnFIE_img_get_step ( FHANDLE himg )

画像情報取得(ステップ)

himg パラメータで指定された画像のステップ(メモリ横幅)を取得します。指定された画像がNULLチャイルド画像だった場合は、0が返ります。

ステップは「(x,y)から(x,y+1)に移動するために必要な移動量」であり、単位は画素です。但し、F_IMG_BIN型とF_IMG_RGBTRIPLE型の場合は単位が異なり、それぞれ下記のようになります。

F_IMG_BIN型の場合：32bitブロック単位。「２値画像について」を参照
F_IMG_RGBTRIPLE型の場合：バイト単位

引数:

[in] himg 情報を取得する画像のハンドル

戻り値:: 正常終了した場合は、画像のステップを返します。異常終了した場合は、-1を返します。

INT_PTR FVALGAPI fnFIE_img_get_pixel_size ( FHANDLE himg )

画像情報取得(画素サイズ)

himg パラメータで指定された画像の画素サイズを取得します。指定された画像がNULLチャイルド画像だった場合は、0が返ります。

画素サイズは「(x,y)から(x+1,y)に移動するために必要な移動量」であり、単位はバイトです。但し、 F_IMG_BIN 型の場合は「(x,y)画素の所属しているブロックの先頭から次のブロックの先頭に移動するために必要なバイト数」になります。詳しくは画像オブジェクトの説明文書内「２値画像について」を参照してください。

引数:

[in] himg 情報を取得する画像のハンドル

戻り値:: 正常終了した場合は、画像の画素サイズを返します。異常終了した場合は、-1を返します。

INT_PTR FVALGAPI fnFIE_img_get_step_as_bytes ( FHANDLE himg )

画像情報取得(メモリステップ)

himg パラメータで指定された画像のメモリステップ(バイト単位メモリ横幅)を取得します。指定された画像がNULLチャイルド画像だった場合は、0が返ります。

メモリステップは「(x,y)から(x,y+1)に移動するために必要な移動量」であり、単位はバイトです。但し、 F_IMG_BIN 型の場合は「(x,y)画素の所属している32bitブロックの先頭から(x,y+1)画素の所属している32bitブロックの先頭に移動するために必要なバイト数」になります。詳しくは画像オブジェクトの説明文書内「２値画像について」を参照してください。

引数:

[in] himg 情報を取得する画像のハンドル

戻り値:: 正常終了した場合は、画像のステップを返します。異常終了した場合は、-1を返します。

参照:: fnFIE_img_get_step()

INT FVALGAPI fnFIE_img_get_width ( FHANDLE himg )

画像情報取得(画像幅)

himg パラメータで指定された画像の幅を取得します。指定された画像がNULLチャイルド画像だった場合は、0が返ります。

引数:

[in] himg 情報を取得する画像のハンドル

戻り値:: 正常終了した場合は、画像の幅を返します。異常終了した場合は、-1を返します。

INT FVALGAPI fnFIE_img_get_height ( FHANDLE himg )

画像情報取得(画像高さ)

himg パラメータで指定された画像の高さを取得します。指定された画像がNULLチャイルド画像だった場合は、0が返ります。

引数:

[in] himg 情報を取得する画像のハンドル

戻り値:: 正常終了した場合は、画像の高さを返します。異常終了した場合は、-1を返します。

INT FVALGAPI fnFIE_img_get_root_params	(	FHANDLE	himg,
		FHANDLE *	hroot,
		INT *	channel,
		INT *	offset_x,
		INT *	offset_y
	)

画像のルート情報取得

画像 himg の割り当てられているルート画像の情報を取得します。 himg はルート画像でもチャイルド画像でも構いません。

引数:

`[in]`	himg	情報を取得する画像
`[out]`	hroot	himg の割り当てられているルート画像のハンドル himg がルート画像のときは himg を返す(つまり hroot = himg* ) 関数エントリー時 *hroot == NULL でなければなりません。
`[out]`	channel	hroot のうち himg* の割り当てられているチャネル番号 himg がルート画像の場合、または himg が hroot の全チャネルに割り当てられている場合は -1 を返す
`[out]`	offset_x	himg の左上Ｘ座標（ルート画像の左上画素を(0,0)としたときの座標）
`[out]`	offset_y	himg の左上Ｙ座標（ルート画像の左上画素を(0,0)としたときの座標）

注意:: hroot にて返されるルート画像のハンドルはコピーではありません。そのため取得された hroot を解放すると himg に割り当てられているルート画像が解放されてしまうことに注意してください。

戻り値:

	F_ERR_NONE	正常終了
	F_ERR_INVALID_IMAGE	himg に無効な画像ハンドルが指定された
	F_ERR_INVALID_PARAM	無効なパラメータが入力された。出力パラメータの何れかがNULL *hroot がNULLでない
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

INT FVALGAPI fnFIE_img_is_overlaped	(	FHANDLE	himg1,
		FHANDLE	himg2
	)

画像オーバーラップ判定

２枚の画像 himg1, himg2 が指し示している画像メモリ空間が、オーバーラップして（重なって）いるかいないかを判定します。

「オーバーラップしている」とは himg1, himg2 のどちらか、又は両方がチャイルド画像である場合に、両方の関連づけられているルート画像が同じ物であり、尚かつその領域が重なっている状態を言います。(下図）

引数:

`[in]`	himg1	判定する画像１
`[in]`	himg2	判定する画像２

戻り値:

	0	２枚の画像はオーバーラップしていない
	1	２枚の画像の一部分がオーバーラップしている
	2	２枚の画像は完全に同じ部分を指している
	F_ERR_INVALID_IMAGE	無効な画像が指定された
	F_ERR_NO_LICENCE	ライセンスエラー、または未初期化エラー

画像オブジェクト [FIE module]

説明

マクロ定義

列挙型

関数

マクロ定義

列挙型

関数

画像オブジェクト
[FIE module]