基本的な使い方¶

ここでは PyFIE の基本的な使い方について説明します。

PyFIE 関数

FIE ライブラリの関数を Python から呼び出すために用意されている PyFIE の関数（PyFIE 関数）は、 FIE(C 言語) の関数と同じインターフェースをもちます。

下記は PyFIE 関数の呼び出し例です。

C 言語

// サイズ 256 x 256 の濃淡画像 src と 2 値画像 dst を確保.
FHANDLE src = fnFIE_img_root_alloc(F_IMG_UC8, 1, 256, 256);
FHANDLE dst = fnFIE_img_root_alloc(F_IMG_BIN, 1, 256, 256);

// 濃淡画像 src に対し閾値 128 で 2 値化を行い,
// 結果を 2 値画像 dst へ出力.
fnFIE_binarize(src, dst, 128);

Python

# サイズ 256 x 256 の濃淡画像 src と 2 値画像 dst を確保.
src = pyfie.fnFIE_img_root_alloc(pyfie.F_IMG_UC8, 1, 256, 256)
dst = pyfie.fnFIE_img_root_alloc(pyfie.F_IMG_BIN, 1, 256, 256)

# 濃淡画像 src に対し閾値 128 で 2 値化を行い,
# 結果を 2 値画像 dst へ出力.
pyfie.fnFIE_binarize(src, dst, 128)

注釈

PyFIE ではガベージコレクションにより FIE オブジェクト(FHANDLE)の解放が自動的に行われるため、 fnFIE_free_object() による FIE オブジェクトの解放処理を省略することができます（詳細は FHANDLE を参照ください）。

関数引数には、上記のようにリテラルを渡す以外に Python 組み込みの数値型などを渡すことができます。また定数の代わりに文字列を指定することも可能です。下に例を示します。

C 言語

INT ch = 1, w = 256, h = 256;

FHANDLE src = fnFIE_img_root_alloc(F_IMG_UC8, ch, w, h);

Python

ch, w, h, = 1, 256, 256

src = pyfie.fnFIE_img_root_alloc("F_IMG_UC8", ch, w, h)

注釈

この他にも PyFIE 関数の引数には、様々なオブジェクトを指定することが可能です。詳細は PyFIE 関数の引数変換規則を参照ください。

上記のような例では、 FIE(C 言語) と PyFIE の関数呼び出しはほぼ同じ記述となります。

これに対し C 言語と Python の言語の違いから、 PyFIE 特有の記述を要求されるものがいくつかあります。ポインタ、構造体、配列等がそれに該当します。

そのために PyFIE では "PyFIE データ型" という C 言語互換データのためのクラスが用意されています。 PyFIE データ型には PyFIE 算術型、 PyFIE 構造体、 PyFIE 共用体、 PyFIE ポインタ、 PyFIE 配列といったものが含まれます。

以下では、これらの PyFIE データ型について説明していきます。

PyFIE 算術型

PyFIE 算術型は FIE(C 言語) における INT や DOUBLE などの算術型に相当する PyFIE データ型です。 pyfie.INT や pyfie.DOUBLE などのように FIE(C 言語) で使われてるものと同じ名前が付けられています。

PyFIE 算術型はコンストラクタによりインスタンス化します。これは C 言語における変数の宣言に相当します。

C 言語

INT i;

INT j = 3;

i = 1;

Python

# PyFIE 算術型のインスタンス化
i = pyfie.INT()

# コンストラクタに引数を与えることで初期値の設定ができます
j = pyfie.INT(3)

# PyFIE 算術型の値を設定
i.value = 1

PyFIE 算術型は、数値演算や数値リテラルとしての使用といったことも可能ですが、基本的に PyFIE 関数から返される値を受け取るための "ポインタ型引数" として使用することが主となります（詳細は PyFIE 算術型が必要となる背景を参照してください）。ポインタ型引数についての説明は後述します。

この他の PyFIE 算術型の使用方法については、算術型を参照してください。

PyFIE 構造体/共用体

PyFIE 構造体は FIE(C 言語) で使用される構造体に相当する PyFIE データ型です。 PyFIE 構造体とそのメンバには FIE(C 言語) で使われているものと同じ名前が付けられています。

PyFIE 構造体は先ほどの PyFIE 算術型と同様、コンストラクタによりインスタンス化して使用します。

C 言語

PNT_T pnt;

pnt.x = 1;
pnt.y = 2;

Python

# PyFIE 構造体のインスタンス化
pnt = pyfie.PNT_T()

# 構造体のメンバに値を設定
pnt.x = 1
pnt.y = 2

関数呼び出し時の構造体型引数には、このインスタンスを指定します。

C 言語

FCOMPLEX c1 = {1.0, 2.0};
FCOMPLEX c2 = {0.1, 0.2};

FCOMPLEX c;

c = fnFIE_cadd(c1, c2);

Python

# PyFIE 構造体のインスタンス化
# コンストラクタの引数によりメンバの初期値を設定することができます
c1 = pyfie.FCOMPLEX(1.0, 2.0)

# キーワード引数による指定も可能です
c2 = pyfie.FCOMPLEX(real=0.1, image=0.2)

# 構造体型引数の指定
c = pyfie.fnFIE_cadd(c1, c2)

注釈

ここで説明した PyFIE 構造体についての内容は、 PyFIE 共用体においても同様となります。

この他の PyFIE 構造体/共用体の使用方法については、構造体/共用体を参照してください。

ポインタ

PyFIE 関数のポインタ型引数に対しては、 PyFIE データ型のポインタを使用します。

PyFIE データ型のインスタンスは属性 ref をもっており、これによりポインタを取得することができます。これは C 言語における "& 演算子" に相当するものと考えてください。

ポインタ型の引数には、この属性 ref により取得したポインタを渡します。下記の例では PyFIE 算術型インスタンス w 、 h のポインタを引数に渡しています。

C 言語

INT w;
INT h;

fnFIE_img_get_params(img, NULL, NULL, NULL, &w, &h);

Python

w = pyfie.INT()
h = pyfie.INT()

# PyFIE 算術型インスタンスのポインタを引数に指定
pyfie.fnFIE_img_get_params(img, None, None, None, w.ref, h.ref)

変数 img は確保済の画像オブジェクト(FHANDLE) であるものとします
NULL ポインタを指定する箇所には None を使用することができます

構造体ポインタ型の引数に関しても同様に、 PyFIE 構造体の属性 ref を使用してポインタを渡します。

C 言語

DPNT_T pnt1 = {1.5, 2.7};
DPNT_T pnt2 = {3.7, 7.3};
DPNT_T cent;

fnFIE_cg_calc_center_2pointA(pnt1, pnt2, &cent);

Python

pnt1 = pyfie.DPNT_T(1.5, 2.7)
pnt2 = pyfie.DPNT_T(3.7, 7.3)
cent = pyfie.DPNT_T()

# PyFIE 構造体のポインタを引数に指定 (cent.ref)
pyfie.fnFIE_cg_calc_center_2pointA(pnt1, pnt2, cent.ref)

ちなみに、ポインタ型の引数に対しては上記例のように属性 ref を使用せず、 PyFIE データ型インスタンスそのものを渡すことも可能です。つまり上記 2 つの関数呼び出し例は、下記のように記述しても同じ結果となります。

Python

# w, h は参照渡しとなる
pyfie.fnFIE_img_get_params(img, None, None, None, w, h)

Python

# 構造体 pnt1, pnt2 は値渡し, cent は参照渡しとなる
pyfie.fnFIE_cg_calc_center_2pointA(pnt1, pnt2, cent)

続いてポインタ型の "変数" について説明します。

前述の属性 ref により得られる "ポインタ" は厳密には、 PyFIE データ型インスタンスへの参照を保持する PyFIE ポインタ型のインスタンスとなります。

各 PyFIE データ型それぞれに対して PyFIE ポインタ型が用意されており、各 PyFIE データ型（クラス）の後ろに .PTR を付けたものが "その PyFIE データ型に対する PyFIE ポインタ型（クラス）" となります。

つまり C 言語における "INT *" のようなポインタ型の記述が、 PyFIE では "INT.PTR" のように対応していると考えてください。

これをコンストラクタとして、 PyFIE ポインタ型のインスタンス化を行うことができます。これは C 言語における "ポインタ型変数" の宣言に相当します。

C 言語

INT * p1 = NULL;
INT ** p2 = NULL;

PNT_T * p3 = NULL;

Python

# INT 型へのポインタ型
p1 = pyfie.INT.PTR()

# INT 型へのポインタ型へのポインタ型
p2 = pyfie.INT.PTR.PTR()

# 構造体へのポインタ型
p3 = pyfie.PNT_T.PTR()

また PyFIE ポインタ型自身も "PyFIE データ型" に含まれますので、属性 ref によりポインタを取得することができます。これを使用して "ポインタのポインタ" である引数の指定を行います。

下記は "UINT 型ポインタ型へのポインタ" である引数(adrs) への指定を行う例です。

C 言語

UINT * adrs = NULL;
INT bpos;

fnFIE_img_get_binadrs(img, &adrs, &bpos)

Python

adrs = pyfie.UINT.PTR() # 算術型のポインタ型
bpos = pyfie.INT()

# adrs.ref はポインタのポインタ型引数の指定
# bpos.ref はポインタ型引数の指定となる
pyfie.fnFIE_img_get_binadrs(img, adrs.ref, bpos.ref)

変数 img は確保済の 2 値画像オブジェクト(FHANDLE) であるものとします

同様に下記は "構造体 F_EDGE 型ポインタ型へのポインタ" である引数(edges) への指定を行う例です。

C 言語

F_EDGE * edges = NULL;
INT edge_num;

fnFIE_edge_sobel(img, ..., &edges, &edge_num);

Python

edges = pyfie.F_EDGE.PTR() # 構造体のポインタ型
edge_num = pyfie.INT()

# edges.ref は構造体のポインタ型引数指定となる
pyfie.fnFIE_edge_sobel(img, ..., edges.ref, edge_num.ref)

変数 img は確保済の画像オブジェクト(FHANDLE) であるものとします

この他の PyFIE ポインタの使用方法については、ポインタを参照してください。

配列

PyFIE 配列は、各 PyFIE データ型を要素とする配列です。 Python 組み込み型である list 等とは異なり、 PyFIE 配列は "要素を格納するための C 言語互換メモリブロック" を内部に保持します。

PyFIE 配列は、各 PyFIE データ型クラスがもつ ARRAY() メソッドによりインスタンス化します。これは C 言語における配列変数の宣言に相当します。配列の要素数はメソッドの引数で指定します。

インスタンス化された PyFIE 配列の各要素には添字を使ってアクセスします。

C 言語

INT a[3];
a[0] = -1;

INT b[3][10];
b[2][9] = -1;

PNT_T c[5];
c[0].x = -1;
c[0].y = -1;

Python

# PyFIE 配列のインスタンス化
a = pyfie.INT.ARRAY(3)

# 配列要素へのアクセス例.
a[0] = -1

# 2 次元配列の例
b = pyfie.INT.ARRAY(3, 10)
b[2][9] = -1

# 構造体の配列の例
c = pyfie.PNT_T.ARRAY(5)
c[0].x = -1
c[0].y = -1

PyFIE 配列は、関数呼び出し時のポインタ型引数として直接渡すことができます。下記に例を示します。

C 言語

INT ch = fnFIE_img_get_channels(img);

{
    DOUBLE vals[ch];
    INT i;

    for(i = 0; i < ch; i ++){
        vals[i] = 255;
    }

    fnFIE_draw_point(img, vals, ...);
}

Python

ch = pyfie.fnFIE_img_get_channels(img)

# PyFIE 配列のインスタンス化
vals = pyfie.DOUBLE.ARRAY(ch)

for i in range(ch):
    vals[i] = 255

# ポインタ型引数の指定に PyFIE 配列を使用する例
pyfie.fnFIE_draw_point(img, vals, ...)

変数 img は確保済の画像オブジェクト(FHANDLE) であるものとします

この他の PyFIE 配列型の使用方法については、配列を参照してください。

以上が PyFIE の基本的な使い方です。ここで説明されている記述方法により、一通りの PyFIE 関数呼び出しが可能となります。

この他に PyFIE では、さらに簡単な記述により FIE ライブラリを使用するための機能が用意されています。他のチュートリアルでは、そのような使い方について説明しています。