関数

PyFIE 関数は FIE(C 言語) に含まれる各関数に対応した Python 関数であり、 Python から FIE(C 言語) 関数を呼び出すためのバインディングです。

各 PyFIE 関数のインターフェースは、 対応する FIE(C 言語) 関数に互換となっています。 すなわち "関数名" および "引数の並び" は同じであり、 要求される引数（および戻り値）の型は FIE(C 言語) 関数で要求される引数（および戻り値）の型に相当した PyFIE データ型となります。

下記に FIE(C 言語) 関数と、 対応する PyFIE 関数の例を示します。

FIE(C 言語) 関数

INT FVALGAPI fnFIE_kernel_filter(

    FHANDLE hsrc,
    FHANDLE hdst,
    F_FILTER_KERNEL_T *kernel,
    INT border_mode,
    DOUBLE border_value

);

PyFIE 関数

pyfie.fnFIE_kernel_filter(

    hsrc,
    hdst,
    kernel,
    border_mode,
    border_value

)

引数
    hsrc
        pyfie.FHANDLE 型
    hdst
        pyfie.FHANDLE 型
    kernel
        pyfie.F_FILTER_KERNEL_T.PTR 型
    border_mode
        pyfie.DOUBLE 型
    border_value
        pyfie.DOUBLE 型

戻り値
    pyfie.INT 型

注釈

上記 PyFIE 関数の戻り値は pyfie.INT 型となっていますが、 初期状態では pyfie.f_err 型として返されます。

詳しくは PyFIE 関数の戻り値 を参照して下さい。

このように PyFIE 関数のインターフェースにおいて 全ての引数は PyFIE データ型となりますが、 実際の関数呼び出し時には PyFIE データ型の他に そのデータ型へ変換可能なオブジェクトを指定することができます。

注釈

インターフェース上で要求されている PyFIE データ型そのものを引数として指定することは当然可能ですが、 大抵の場合 変換可能な別種類のオブジェクトを指定することがプログラミングを簡潔にします。

---

PyFIE 関数の引数変換規則

PyFIE 関数の引数における各 PyFIE データ型への変換規則を示します。

引数の PyFIE データ型	変換可能なオブジェクト
PyFIE 算術型	異なる数値種別の PyFIE 算術型 Python 組み込みの数値型 Python 組み込みの文字列型 (str) Python 組み込みのブール型 (bool)
PyFIE 構造体	Python 組み込みのリスト型 (list) Python 組み込みのタプル型 (tuple) Python 組み込みのマッピング型 (dict)
PyFIE 共用体	Python 組み込みのリスト型 (list) Python 組み込みのタプル型 (tuple) Python 組み込みのマッピング型 (dict)
PyFIE ポインタ	(参照先となる) PyFIE データ型インスタンス PyFIE 配列 参照先要素型のデータサイズが同じ PyFIE ポインタ型 Python 組み込みのリスト型 (list) [1] Python 組み込みのタプル型 (tuple) [1] numpy.ndarray [1] [2] None
PyFIE 配列	（ PyFIE ポインタと同様 ）
文字列 (CHAR.PTR)	Python 組み込みの文字列型 (str) None
FHANDLE	numpy.ndarray [2]

[1] (1,2,3)

ポインタの参照先が算術型である場合にのみ使用することができます。

[2] (1,2)

NumPy が使用可能な環境でのみ NumPy の numpy.ndarray を使用することができます。 詳しくは NumPy との連携 を参照してください。

PyFIE 算術型

PyFIE 算術型の引数には Python 組み込み型である 数値型、 文字列型、 ブール型などを 渡すことができます。

数値を表現した文字列を渡した場合、 文字列から数値へ変換されます。 (この変換は Python により行われますので、 その変換仕様も Python に準じます)

また PyFIE 定数の名前を文字列として渡した場合、 対応する定数値へ変換されます。

C 言語

INT ch = 3;

FHANDLE img = fnFIE_img_root_alloc(
    F_IMG_UC8,
    ch,
    512,
    480
);

Python

ch = 3

img = pyfie.fnFIE_img_root_alloc(
    "F_IMG_UC8",  # INT 型引数 type に文字列型(定数名)を指定.
    ch,   # INT 型引数 channels に数値型変数を指定.
    512,  # INT 型引数 width に数値型リテラルを指定.
    "480" # INT 型引数 height に文字列型(数値表現)を指定
)

PyFIE 構造体 / 共用体

注釈

以下では PyFIE 構造体についての説明を行っていますが、 PyFIE 共用体についても同様の内容となります。

PyFIE 構造体の引数として Python 組み込み型である リスト型(list) 及び タプル型(tuple) を渡すことが可能です。 この場合リスト型/タプル型の要素には、 構造体のメンバに対する値を構造体定義におけるメンバの順序となるように (つまり PyFIE 構造体コンストラクタの引数で指定するように) 値を指定します。

また PyFIE 構造体の引数として Python 組み込み型である マッピング型(dict) も渡すことが可能です。 この場合マッピング型の要素には、 構造体のメンバ名がキーとなるように (つまり PyFIE 構造体コンストラクタのキーワード引数で指定するように) 値を指定します。

下記は構造体 DPNT_T 型の引数にリスト型とマッピング型を指定する例です。

C 言語

DPNT_T pnt1 = {  1,  2 };
DPNT_T pnt2 = { 30, 40 };
DPNT_T center;

fnFIE_cg_calc_center_2pointA(
    pnt1,
    pnt2,
    &center
);

Python

center = pyfie.DPNT_T()

pyfie.fnFIE_cg_calc_center_2pointA(
    [1, 2],           # DPNT_T 型引数 pnt1 にリスト型を指定.
    {"x":30, "y":40}, # DPNT_T 型引数 pnt2 にマッピング型を指定.
    cent.ref
)

下記は構造体 BOX_T 型の引数にタプル型を指定する例と、マッピング型を指定する例です。

C 言語

BOX_T search_window;

search_window.st.x = 1;
search_window.st.y = 2;
search_window.ed.x = 100;
search_window.ed.y = 200;

fnFIE_gs2_search( ..., search_window, ... );

Python

# BOX_T 型引数 search_window にタプル型を指定.
pyfie.fnFIE_gs2_search( ..., ((1, 2), (100, 200)), ... );

Python

# BOX_T 型引数 search_window にマッピング型を指定.
pyfie.fnFIE_gs2_search( ..., {"st":(1, 2), "ed":(100, 200)}, ... );

PyFIE ポインタ

PyFIE ポインタを要求する引数に PyFIE データ型インスタンスの ref 属性を渡す場合、 代わりに PyFIE データ型インスタンスそのものを渡しても同じ結果となります。 （インスタンスそのものを渡した場合は関数の入り口で ref 属性が自動的にとり出されます。）

つまり下記 2 つの Python サンプルコードは等価となります。

C 言語

INT ch;

fnFIE_img_get_params( ..., &ch, ... );

Python

ch = pyfie.INT()

# INT.PTR 型引数 channels にインスタンスの ref 属性を指定.
pyfie.fnFIE_img_get_params( ..., ch.ref, ... )

Python

ch = pyfie.INT()

# ref を省略し、 INT.PTR 型引数にインスタンスそのものを指定.
pyfie.fnFIE_img_get_params( ..., ch, ... )

また PyFIE ポインタ型引数として None を指定した場合、 C 言語における NULL ポインタ指定と等価となります。

この他、 ここで紹介していない PyFIE ポインタ型へ変換可能なオブジェクトに関しては、 PyFIE ポインタ型のオブジェクト変換 を参照してください。

PyFIE 配列

PyFIE 配列型の引数は、 同じ要素型の PyFIE ポインタ型引数に等価となります。 これは C 言語の仕様と同様です。

文字列 (CHAR.PTR)

CHAR.PTR 型として文字列を要求する引数には Python 組み込みの文字列型を渡すことができます。

C 言語

fnFIE_load_bmp( "filename.bmp", ... );

Python

pyfie.fnFIE_load_bmp("filename.bmp", ... )

---

PyFIE 関数の戻り値

PyFIE 関数の戻り値に関して、 下記の場合に特殊な扱いとなります。

エラーコード （INT）

FIE(C 言語) に含まれる多くの関数は戻り値として INT 型のエラーコードを返す仕様となっています。 このような関数に対応する PyFIE 関数では、 戻り値（エラーコード）を pyfie.INT 型ではなく pyfie.f_err 型の PyFIE 定数インスタンスとして返します。

PyFIE 定数インスタンスの文字列表現は定数名となっており、 対話的な環境でエラーコードの確認をすることが容易となります。

この挙動が好ましくない場合には、 pyfie.ctrl.enable_f_err_return() により 戻り値として pyfie.INT 型が返されるように切り替えることが可能です。

NULL ポインタ

PyFIE ポインタ型及び FHANDLE 型の戻り値として "NULL ポインタ" に相当するものが返される場合、 "NULL ポインタ" に相当するインスタンスの代わりに None が返されます。

VOID

戻り値が VOID である PyFIE 関数（つまり C 言語においては戻り値が無い関数）は、 常に None を返します。

---

PyFIE 関数の接頭辞の省略

PyFIE 関数のうち接頭辞が fnFIE_ である関数は、接頭辞の省略が可能です。 通常の PyFIE 関数と異なり、接頭辞を省略した PyFIE 関数ではキーワード引数が使用可能であり、一部の引数についてはデフォルト値が付与されます。

下記に接頭辞が省略された PyFIE 関数の例を示します。

PyFIE 関数

pyfie.fnFIE_sobel(
    hsrc,
    hdst,
    calc_mode,
    border_mode,
    border_value,
)

接頭辞が省略された PyFIE 関数

pyfie.sobel(
    hsrc,
    hdst,
    calc_mode=pyfie.F_SOBEL_SQRT_MODE,
    border_mode=pyfie.F_BORDER_CONTINUOUS,
    border_value=0,
)

注釈

デフォルト引数は FIE(C 言語) には存在しません。 具体的なデフォルト引数値については接頭辞が省略された各 PyFIE 関数のシグネチャを参照してください。