NumPy との連携

NumPy が使用可能な環境では、 PyFIE のデータ型と NumPy の numpy.ndarray を連携して使用することが可能となります。

NumPy は Python で多次元配列を扱うために広く用いられている Python パッケージです。 Scipy や OpenCV など様々なサードパーティライブラリが NumPy を使用しています。 NumPy との連携により、それらのライブラリと PyFIE との相互運用が容易に行えるようになります。

注釈

NumPy 1.13.0 以上のバージョンに対応しています。



画像オブジェクト と ndarray の相互変換

FHANDLE 型インスタンスとして扱われる PyFIE の画像オブジェクト（以下単に 画像オブジェクト と記す）は、 NumPy の numpy.ndarray と相互に変換することが可能です。



画像オブジェクト から ndarray へのアタッチ

画像オブジェクト のインスタンスメソッド attach_to_ndarray() または インスタンスプロパティ ndarray により、 画像オブジェクト の画像メモリを共有する numpy.ndarray を取得することができます。

注釈

これにより numpy.ndarray を要求する他のパッケージにおいて PyFIE の 画像オブジェクト を使用することが可能となります。


FHANDLE.attach_to_ndarray()

画像オブジェクト の画像メモリを共有する numpy.ndarray を返します。

このとき、返される numpy.ndarray は以下のようなものとなります。


1 チャネル画像オブジェクトの場合

画像オブジェクト のチャネル数が 1 であった場合、 numpy.ndarray は同形状の 2 次元配列となります。

ただし画像型が F_IMG_RGBTRIPLE または F_IMG_RGBQUAD の場合は、 3 または 4 のコンポーネント（RGB）から構成される各画素の次元が追加されるため、 numpy.ndarray は 3 次元配列となります。

下記に画像サイズが w × h である 1 チャネル 画像オブジェクト に対する、 numpy.ndarray の dtype （データ型） 及び shape （形状）の対応を示します。

1 チャネル画像オブジェクト (画像サイズ w × h )

画像型

dtype

shape

F_IMG_BIN [1]

N/A

N/A

F_IMG_UC8

numpy.uint8

(h, w)

F_IMG_S16

numpy.int16

(h, w)

F_IMG_US16

numpy.uint16

(h, w)

F_IMG_I32

numpy.int32

(h, w)

F_IMG_UI32

numpy.uint32

(h, w)

F_IMG_I64

numpy.int64

(h, w)

F_IMG_FLOAT

numpy.float32

(h, w)

F_IMG_DOUBLE

numpy.float64

(h, w)

F_IMG_RGBQUAD

numpy.uint8

(h, w, 4)

F_IMG_RGBTRIPLE

numpy.uint8

(h, w, 3)

複数チャネル画像オブジェクトの場合

画像オブジェクト のチャネル数が複数であった場合の numpy.ndarray は、 各チャネルに対する numpy.ndarray を要素にもつ 1 次元配列となります。

つまりチャネル数が n の 画像オブジェクト に対する numpy.ndarray は、 shape が (n, ) 、 dtype が numpy.object （つまり Python オブジェクトを要素にもつ）の 1 次元配列となり、 その要素として n 個の "1 チャネル画像オブジェクトに対する numpy.ndarray" が格納されていることになります。

注釈

この仕様は、 FIE の 画像オブジェクト が複数チャネル分の画像メモリを連続したメモリ領域ではなく、 （チャネル毎に）個別に管理していることに由来しています。


戻り値:

画像オブジェクト の画像メモリを共有する numpy.ndarray を返します。


FHANDLE.ndarray

画像オブジェクト ではインスタンスプロパティ ndarray により、 アタッチされた numpy.ndarray にアクセスすることができます。

注釈

このプロパティでは 内部で attach_to_ndarray() の呼び出しが行われます。



画像オブジェクト から ndarray へのクローン

画像オブジェクト のインスタンスメソッド clone_to_ndarray() により、 画像オブジェクト の画像データがコピーされた numpy.ndarray を生成することができます。


FHANDLE.clone_to_ndarray(layered=False)

画像オブジェクト の画像データがコピーされた numpy.ndarray を返します。

このとき、返される numpy.ndarray は以下のようなものとなります。


1 チャネル画像オブジェクトの場合

画像オブジェクト のチャネル数が 1 であった場合、 numpy.ndarray は同形状の 2 次元配列となります。

ただし画像型が F_IMG_RGBTRIPLE または F_IMG_RGBQUAD の場合は、 3 または 4 のコンポーネント（RGB）から構成される各画素の次元が追加されるため、 numpy.ndarray は 3 次元配列となります。

下記に画像サイズが w × h である 1 チャネル 画像オブジェクト に対する、 numpy.ndarray の dtype （データ型） 及び shape （形状）を示します。

1 チャネル画像オブジェクト (画像サイズ w × h)

画像型

dtype

shape

F_IMG_BIN

numpy.bool_

(h, w)

F_IMG_UC8

numpy.uint8

(h, w)

F_IMG_S16

numpy.int16

(h, w)

F_IMG_US16

numpy.uint16

(h, w)

F_IMG_I32

numpy.int32

(h, w)

F_IMG_UI32

numpy.uint32

(h, w)

F_IMG_I64

numpy.int64

(h, w)

F_IMG_FLOAT

numpy.float32

(h, w)

F_IMG_DOUBLE

numpy.float64

(h, w)

F_IMG_RGBQUAD

numpy.uint8

(h, w, 4)

F_IMG_RGBTRIPLE

numpy.uint8

(h, w, 3)

複数チャネル画像オブジェクトの場合

画像オブジェクト が複数チャネルの場合、 パラメータ layered によりチャネルを階層化するか否かを指定することができます。

layered に True を指定した場合、 チャネルは階層化され、 同じチャネルにおける各画素が画像メモリ上で連続に配置された状態となります。 この場合、画像サイズ w × h 、 チャネル数 n の 画像オブジェクト に対する numpy.ndarray の shape は (n, h, w) となります。

layered に False を指定した場合、 チャネルは階層化されず、 各チャネルにおける同座標の画素が画像メモリ上で連続に配置された状態（すなわちチャネルをインタリーブした状態）となります。 この場合、画像サイズ w × h 、 チャネル数 n の 画像オブジェクト に対する numpy.ndarray の shape は (h, w, n) となります。

ただし画像型が F_IMG_RGBTRIPLE または F_IMG_RGBQUAD である場合、 layered の指定に関わらず常にチャネルは階層化されます。

下記に画像サイズが w × h である n チャネル 画像オブジェクト に対する、 numpy.ndarray の shape を示します。

n チャネル画像オブジェクト (画像サイズ w × h)

画像型
shape
layered = True
shape
layered = False

F_IMG_RGBQUAD

(n, h, w, 4)

(n, h, w, 4)

F_IMG_RGBTRIPLE

(n, h, w, 3)

(n, h, w, 3)

others

(n, h, w)

(h, w, n)

パラメータ:

layered -- 複数チャネル 画像オブジェクト の場合にチャネルの階層化を行うか否かを指定します。

戻り値:

コピーされた numpy.ndarray を返します。



ndarray から 画像オブジェクト へのアタッチ

FHANDLE のクラスメソッド attach_from_ndarray() により、 numpy.ndarray と画像メモリを共有する 画像オブジェクト を取得することができます。


classmethod FHANDLE.attach_from_ndarray(ndarray)

パラメータ ndarray に渡された numpy.ndarray と 画像メモリを共有する 画像オブジェクト を返します。

返される 画像オブジェクト は ndarray が保持するデータメモリ空間に対して、 fnFIE_img_root_import_alloc() [2] により生成されたインポート版ルート画像となります。

返される 画像オブジェクト の画像型、 画像サイズ、 チャネル数は、 ndarray の dtype （データ型） 及び shape （形状） によって下記のように決定されます。


ndarray が 1 次元配列の場合

ndarray の shape が (w, ) の場合、 生成される 画像オブジェクト の幅は w 、 高さは 1 、 チャネル数は 1 となります。 このとき画像型は下記表 "dtype から画像型への対応" により決定されます。


ndarray が 2 次元配列の場合

ndarray の shape が (h, w) の場合、 生成される 画像オブジェクト の幅は w 、 高さは h 、 チャネル数は 1 となります。 このとき画像型は下記表 "dtype から画像型への対応" により決定されます。


ndarray が 3 次元配列の場合

ndarray の shape が (c, h, w) の場合、 生成される 画像オブジェクト の幅は w 、 高さは h 、 チャネル数は c となります。 このとき画像型は下記表 "dtype から画像型への対応" により決定されます。

ただし dtype が numpy.uint8 であり、 かつ shape の最も内側の次元の要素数が 3 または 4 であった場合、 下記のように F_IMG_RGBTRIPLE または F_IMG_RGBQUAD 型の 画像オブジェクト が生成されます。

  • ndarray の shape が (h, w, 3) の場合、 幅 w 、 高さ h 、 チャネル数 1 、 画像型が F_IMG_RGBTRIPLE の 画像オブジェクト が生成されます。

  • ndarray の shape が (h, w, 4) の場合、 幅 w 、 高さ h 、 チャネル数 1 、 画像型が F_IMG_RGBQUAD の 画像オブジェクト が生成されます。


dtype から画像型への対応

dtype

画像型

numpy.uint8

F_IMG_UC8

numpy.bool_

F_IMG_UC8

numpy.int16

F_IMG_S16

numpy.uint16

F_IMG_US16

numpy.int32

F_IMG_I32

numpy.uint32

F_IMG_UI32

numpy.int64

F_IMG_I64

numpy.float32

F_IMG_FLOAT

numpy.float64

F_IMG_DOUBLE

パラメータ:

ndarray -- numpy.ndarray を指定します。

戻り値:

numpy.ndarray と画像メモリを共有する 画像オブジェクト を返します。

注釈

ndarray の幅方向の画素がメモリ空間上で一続きに並んでいない場合 （F_IMG_RGBTRIPLE と F_IMG_RGBQUAD 以外の型においては numpy.ndarray.strides の最後の要素が numpy.ndarray.itemsize と異なる場合）はアタッチできません。

処理に失敗した場合は例外が発生します。



ndarray から 画像オブジェクト へのクローン

FHANDLE のクラスメソッド clone_from_array() により、 numpy.ndarray のデータがコピーされた 画像オブジェクト を生成することができます。


classmethod FHANDLE.clone_from_array(array_like, img_type=None)

パラメータ array_like に渡された配列のデータがコピーされた 画像オブジェクト を返します。

返される 画像オブジェクト は fnFIE_img_root_alloc() [3] により （または array_like を numpy.ndarray にコピーした後に fnFIE_img_root_import_alloc() により） 生成され、 array_like から画像データをコピーされたルート画像となります。

array_like には numpy.ndarray の他に、 Python 組み込み型である list や tuple 等 "array like なオブジェクト" を渡すことが可能です。

パラメータ img_type には生成される 画像オブジェクト の画像型を指定します。 img_type に None を指定した場合は attach_from_ndarray() と同じ変換規則にて 画像型が決定されます。


パラメータ:

  • array_like -- "array like なオブジェクト" を指定します。

  • img_type -- 生成される 画像オブジェクト の画像型を指定します。

戻り値:

コピーされた 画像オブジェクト を返します。



画像オブジェクトのプロパティ (dtype)

FHANDLE 型インスタンスでは下記読み出し専用プロパティを使用することができます。


FHANDLE.dtype

インスタンスが 画像オブジェクト である場合、 下記のように画像型に対応した numpy.ndarray の dtype （データ型） を返します。

画像型

dtype

F_IMG_UC8

numpy.uint8

F_IMG_S16

numpy.int16

F_IMG_US16

numpy.uint16

F_IMG_I32

numpy.int32

F_IMG_UI32

numpy.uint32

F_IMG_I64

numpy.int64

F_IMG_FLOAT

numpy.float32

F_IMG_DOUBLE

numpy.float64

F_IMG_RGBQUAD

numpy.uint8

F_IMG_RGBTRIPLE

numpy.uint8

注釈

インスタンスが 画像オブジェクト ではない場合、 及び 画像オブジェクト であっても対応する numpy.ndarray の dtype がない場合には例外が発生します。



構造体と ndarray の相互変換

行列を表す PyFIE 構造体である FMATRIX を numpy.ndarray と相互に変換することが可能です。

FMATRIX.clone_to_ndarray(dtype=None)

FMATRIX 構造体インスタンスの行列データがコピーされた numpy.ndarray を返します。

パラメータ:

dtype -- numpy.ndarray のデータ型を指定します。 None を指定した場合は numpy.float64 が使用されます。

戻り値:

コピーされた numpy.ndarray を返します。

classmethod FMATRIX.clone_from_array(array_like)

パラメータ array_like に渡された配列のデータがコピーされた FMATRIX 構造体インスタンスを返します。

array_like には numpy.ndarray の他に、 Python 組み込み型である list や tuple 等 "array like なオブジェクト" を渡すことが可能です。

array_like の次元数は1または2である必要があります。 次元数が1の場合は、出力される FMATRIX 構造体インスタンスの行数は1になります。

本関数で確保された FMATRIX 構造体インスタンスは、 Python のガベージコレクション対象となるため fnFIE_mat_afree() により解放する必要はありません。 解放後はメンバ変数 FMATRIX.m の参照先アドレスは無効となります。

パラメータ:

array_like -- "array like なオブジェクト" を指定します。

戻り値:

コピーされた FMATRIX 構造体インスタンスを返します。

注釈

本関数で確保された FMATRIX インスタンスは、下記の操作を行うことができません。

  • 他の FMATRIX 構造体インスタンスの属性 value に対する代入

  • 他の FMATRIX 構造体インスタンスポインタの属性 deref に対する代入

  • FMATRIX 構造体配列の各要素に対する代入

  • PyFIE 構造体の FMATRIX 構造体メンバに対する代入



PyFIE 算術型ポインタから ndarray へのアタッチ

PyFIE 算術型ポインタ（参照先が算術型である PyFIE ポインタ）は、 インスタンスメソッド ndarray() により ポインタの参照先メモリ領域を共有する numpy.ndarray を取得することができます。 このときポインタインスタンスは自分が参照するメモリ領域の範囲を知らないので、 メソッドの引数により範囲を指定することになります。


PTR.ndarray(num)

PyFIE 算術型ポインタインスタンスの参照先メモリ領域を共有する numpy.ndarray を返します。

パラメータ num では参照先メモリ領域の範囲を要素個数で指定します。

注釈

パラメータ num で 実際に確保されているメモリ領域の範囲を超えるような指定を行った場合、 不正なメモリアクセスの要因となります。

返される numpy.ndarray の dtype （データ型） は参照先算術型に対応したものとなり、 shape （形状） は (num, ) の 1 次元配列となります。

パラメータ:

num -- 参照先メモリ領域の要素個数を指定します。

戻り値:

ポインタのメモリ領域を共有する numpy.ndarray を返します。



PyFIE データ型としての ndarray 使用

PyFIE では以下のような場面で numpy.ndarray を PyFIE データ型のように使用することができます。


PyFIE 関数に ndarray を使用する

PyFIE 関数を呼び出す際、 下記 PyFIE データ型が要求される引数に対して numpy.ndarray を直接渡すことができます。

FHANDLE 型 （ 画像オブジェクト ）

PyFIE 関数の FHANDLE 型 引数に対して numpy.ndarray を渡すことができます。 この場合 numpy.ndarray は 画像オブジェクト と見なされ、 内部で attach_from_ndarray() による変換が行われます。

PyFIE 構造体/共用体

PyFIE 関数の 構造体/共用体 引数に対して numpy.ndarray を渡すことができます。 詳しくは PyFIE 構造体のオブジェクト変換 を参照してください。

ポインタ型

PyFIE 関数の ポインタ型 引数に対して numpy.ndarray を渡すことができます。 この場合 numpy.ndarray が保持するメモリ領域のトップアドレスが、 内部でポインタ型に変換されます。

ポインタへの変換は単純キャストにて行われます。 そのため、 引数のデータ型と numpy.ndarray のデータ型（dtype）が対応している必要はありません。

注釈

あらゆる numpy.ndarray を任意データ型へのポインタとして指定することが可能となります。 使い方によって numpy.ndarray のメモリ領域範囲を超えるアクセスを可能となりますので ご注意ください。


PyFIE 構造体/共用体のメンバに ndarray を使用する

PyFIE 構造体/共用体のメンバを設定する際、 下記のように numpy.ndarray を使用することができます。

ポインタ型 メンバ

PyFIE 構造体/共用体のポインタ型メンバに対して numpy.ndarray を直接設定することができます。 この場合、 ポインタ型メンバは numpy.ndarray が保持するメモリ領域（トップアドレス）を参照することになります。

ポインタへの変換は単純キャストにて行われます。 そのためメンバのデータ型と numpy.ndarray のデータ型（dtype）が対応している必要はありません。

注釈

あらゆる numpy.ndarray を任意データ型へのポインタとして指定することが可能となります。 使い方によって numpy.ndarray のメモリ領域範囲を超えるアクセスを可能となりますので ご注意ください。

配列型 メンバ

PyFIE 構造体/共用体の配列型メンバに対して numpy.ndarray を設定することができます。 この場合、 numpy.ndarray から配列型メンバの各要素へ値のコピーが行われます。

ただし配列型の要素型は PyFIE 算術型でなければなりません。 要素の数値型と numpy.ndarray のデータ型（dtype）が対応している必要はなく、 異なる数値型の場合には値のコピーの際に Python による数値変換が行われます。