apply

(削除予定) bigimage オブジェクトのブロックの処理

ページ内をすべて折りたたむ

bigimage オブジェクトの関数 apply は将来のリリースで削除される予定です。代わりに、blockedImage オブジェクトに関連付けられた関数 apply を使用してください。詳細については、バージョン履歴を参照してください。

構文

newbig = apply(bigimg,level,fun)
newbig = apply(bigimg,level,fun,extraImages)
newbig = apply(___,Name,Value)
[newbig,other1,other2,...] = apply(___)

説明

newbig = apply(bigimg,level,fun) は、関数 fun を使用して、指定された解像度レベルで大きなイメージ bigimg のすべてのブロックを処理し、処理したデータを含む新しい大きなイメージ newbig を返します。

例

newbig = apply(bigimg,level,fun,extraImages) は、大きなイメージ bigimg と 1 つ以上の追加の大きなイメージ extraImages のすべてのブロックを処理します。関数 fun がイメージとマスクなどの複数のイメージ入力を受け入れる場合は、この構文を使用します。

newbig = apply(___,Name,Value) は、名前と値の引数を使用して、データの並列処理やイメージのエッジでのブロックのパディングなど処理の諸側面を制御します。

[newbig,other1,other2,...] = apply(___) は、複数の出力を返します。関数 fun がイメージとイメージ以外の出力などの複数の出力を返す場合は、この構文を使用します。

例

すべて折りたたむ

ライブ スクリプトを開く

CAMELYON16 データセットのイメージ "tumor_091.tif" の変更したバージョンを使用して bigimage を作成します。元のイメージは、腫瘍組織が含まれるリンパ節の学習イメージです。元のイメージには 8 つの解像度レベルがあり、最も細かいレベルの解像度は 53760 x 61440 です。変更したイメージには、3 つの粗い解像度レベルのみが含まれています。変更したイメージの空間参照は、縦横比が一定に維持され、各レベルで特徴がレジストレーションされるように調整されています。

bim = bigimage('tumor_091R.tif');

最も細かい解像度レベル 1 でエッジ保存型非局所平均フィルターを各ブロックに適用して、イメージ内の構造を強調します。この例では、関数 apply は、入力 bigimage の各ブロックに対して以下の操作を実行します。

  • ブロックを L*a*b* 色空間に変換します。

  • imnlmfilt を使用してブロックをフィルター処理します。

  • ブロックを RGB 色空間に変換し直します。

関数 apply は出力ブロックを再結合し、新しい bigimage を作成します。

bim_enhanced = apply(bim,1, ...
    @(block)lab2rgb(imnlmfilt(rgb2lab(block),'DegreeOfSmoothing',15)));

関数 bigimageshow を使用して、Figure ウィンドウの左側に元のイメージを表示します。

figure
ha1 = subplot(1,2,1);
bigimageshow(bim,'ResolutionLevel',1);
title("Original Image")

Figure ウィンドウの右側に強調されたイメージを表示します。

ha2 = subplot(1,2,2);
bigimageshow(bim_enhanced);
title("Enhanced Image")

両方の表示の範囲が同じであることを確認し、特徴を拡大します。

linkaxes([ha1,ha2]);
xlim([1600,2300])
ylim([1900,2600])

入力引数

すべて折りたたむ

大きなイメージ。bigimage オブジェクトとして指定します。

解像度レベル。bigimg の解像度レベル値以下の正の整数として指定します。

関数ハンドル。ハンドルとして指定します。詳細については、関数ハンドルの作成を参照してください。

関数入力

関数 fun は入力として少なくとも 1 つのブロックを受け入れなければなりません。

オプションで、この関数はブロック以外の追加入力を受け入れることができます。ブロック以外の入力を指定して処理を実行するには、関数 apply を呼び出し、無名関数として fun を指定しなければなりません。詳細については、無名関数を参照してください。

fun へのさまざまな種類の入力に対するサンプル関数シグネチャを次の表に示します。また、この表は apply を呼び出すときに使用するサンプル構文も示しています。

入力タイプ関数シグネチャapply を呼び出す例
単一のブロック 
function outblock = myfun(inblock)
  ...
end
 
newbig = apply(bigimg,level,@myfun);
2 つのブロック 
function outblock = myfun(inblock1,inblock2)
  ...
end

関数 myfun のハンドルの後に 2 番目の bigimage を指定します。

newbig = apply(bigimg,level,@myfun,otherbig);

1 つのブロックと 1 つの非ブロック 
function outblock = myfun(inblock,nonblock)
  ...
end

この例では、スカラー値 37 を関数 myfun に渡します。

c = 37;
mynewbig = apply(mybigimg,level,@(x) myfun(x,c));

関数出力

通常、関数 fun は、入力ブロックと同じサイズのイメージ ブロックを 1 つ以上返します。この場合、apply はブロックを再結合し、bigimage を返します。apply の BorderSize 引数を指定し、bigimage の出力が必要な場合、apply は出力ブロックから境界をトリミングします。fun の中でブロックを直接トリミングすることもできます。

上の表の例はすべて、単一のブロックを返す関数シグネチャを示しています。ただし、関数 fun は、struct または他のイメージ以外の出力を返すこともできます。

fun のさまざまな種類の出力に対するサンプル関数シグネチャを次の表に示します。また、この表は apply を呼び出すときに使用するサンプル構文も示しています。

出力タイプサンプル処理関数apply を呼び出す例
入力ブロックと同じサイズのブロック 
function sameSizedBlock = myfun(inblock)
  sameSizedBlock = imgaussfilt(inblock);
end
bigimageOutput = apply(bigimg,level,@myfun);

bigimageOutput は単一解像度の bigimage です。この例では、bigimageOutput のチャネル数とデータ型は入力 bigimg と同じです。

入力ブロックと同じサイズの複数のブロック 
function [sameSizedBlock,maskBlock] = myfun(inblock)
  sameSizedBlock = rgb2lightness(inblock);
  maskBlock = imbinarize(sameSizedBlock);
end
[bigimageOutput1,bigimageOutput2] = apply(bigimgRGB,level,@myfun);

bigimageOutput1 は単一解像度の bigimage です。この例では、bigimgRGB にカラー イメージが含まれる場合、bigimageOutput1 のチャネル数は入力 bigimgRGB と異なります。

bigimageOutput2 は、チャネル数とデータ型が bigimgRGB と異なる単一解像度の bigimage です。

イメージ以外 
function nonimageOutput = myfun(inblock)
  nonimageOutput = mean(inblock(:))
end

cellArrayOutput = apply(bigimg,level,@myfun);

cellArrayOutput は、要素が各ブロックのイメージ以外の出力である cell 配列です。cellArrayOutput には、各ブロックの (x,y) 原点を 1 行 2 列のベクトルとして指定する追加列が 1 つあります。

Struct 
function structOutput = myfun(inblock)
  structOutput.num = numel(inblock);
  structOutput.mean = mean(inblock(:));
  structOutput.max = max(inblock(:));
end

tableOutput = apply(mybigimg,level,@myfun);
tableOutput は、4 つの変数 num、mean、max、および BlockOrigin を持つ table です。BlockOrigin 変数は、各ブロックの (x,y) 原点を 1 行 2 列のベクトルとして指定します。

複数出力 
function [out1,out2,out3,out4,out5] = myfun(inblock)
  % non-image output
  out1 = min(inblock(:));
  % image output of same size as input block
  out2 = imgaussfilt(out2);
  out3 = imbinarize(inblock);
  % struct output
  out4.originalMean = mean(inblock(:));
  out4.filteredMean = mean(out2(:));
  out4.fractionTrue = sum(out3(:))/numel(out3);
  % non-image output
  out5 = out4.fractionTrue;
end

[c1,b2,b3,t4] = apply(mybigimg,level,@myfun);

myfun の最初の出力がイメージではないため、c1 は cell 配列です。myfun の 2 番目と 3 番目の出力が入力ブロックと同じサイズのイメージ ブロックであるため、b2 と b3 は bigimage です。myfun の 4 番目の出力が struct であるため、t4 は table です。

apply の呼び出しに 4 つの出力引数のみが指定されているため、関数 apply は myfcn の 5 番目の出力引数を無視します。

大きな追加入力イメージ。bigimage オブジェクトのベクトルとして指定します。それぞれの大きなイメージの空間範囲は bigimg と同じでなければなりませんが、ブロックのサイズは同じである必要はありません。それぞれの大きなイメージで ClassUnderlying および Channels プロパティの値が異なる可能性があります。

名前と値の引数

すべて折りたたむ

オプションの引数のペアを Name1=Value1,...,NameN=ValueN として指定します。ここで、Name は引数名で、Value は対応する値です。名前と値の引数は他の引数の後に指定しなければなりませんが、ペアの順序は重要ではありません。

例: newbig = apply(bigimg,level,@myfun,UseParallel=true);

R2021a より前では、コンマを使用して名前と値をそれぞれ区切り、Name を引用符で囲みます。

例: newbig = apply(bigimg,level,@myfun,"UseParallel",true);

各バッチで処理関数 fun に指定されたブロック数。正の整数として指定します。BatchSize が 1 より大きい場合、PadPartialBlocks は true でなければなりません。

BatchSize が 1 より大きい場合、apply はブロックを numrows x numcols x channels x BatchSize の配列として指定します。apply が bigimage を返すようにするには、fun は同じサイズの配列を返さなければなりません。apply が cell 配列またはテーブルを返すようにするには、fun は長さが BatchSize でブロックごとに要素が 1 つある cell 配列を返さなければなりません。

ブロック サイズ。[numrows numcols] 形式の正の整数の 1 行 2 列ベクトルとして指定します。BlockSize を指定した場合、apply は、サイズが [numrows numcols] のブロックを処理関数 fun に渡します。apply はブロックのすべてのチャネルを fun に渡します。

境界サイズ。[numrows numcols] 形式の非負の整数の 1 行 2 列ベクトルとして指定します。関数は、numrows 行を各ブロックの上下に追加し、numcols 列を近傍ブロックからのデータと共に各ブロックの左右に追加します。イメージのエッジにあるブロックでは、データは PadMethod に従ってパディングされます。既定では、ブロックに境界は追加されません。

ウェイト バーの表示。true または false として指定します。true の場合、関数 apply は長時間かかる処理のウェイト バーを表示します。ウェイト バーを閉じた場合、apply は、利用可能であれば部分出力を返します。

データ型: logical

ブロック情報を含める。false または true として指定します。true の場合、apply は処理関数 fun への最後の入力として struct を含めます。この struct には、ブロックに関する空間参照情報を記述する、次のフィールドがあります。

フィールド説明
BlockStartWorld 境界やパディングを除く、ブロックの左上ピクセルの中心のワールド座標。
BlockEndWorld境界やパディングを除く、ブロックの右下ピクセルの中心のワールド座標。
DataStartWorld境界やパディングを含む、ブロックの左上ピクセルの中心のワールド座標。
DataEndWorld境界やパディングを含む、ブロックの右下ピクセルの中心のワールド座標。

BatchSize が 1 より大きい場合、struct の値は長さが BatchSize の配列です。

データ型: logical

マスク ブロックの包含しきい値。[0, 1] の範囲の数値として指定します。包含しきい値は、イメージ ブロックを処理するために必要な、マスク ブロック内の非ゼロ ピクセルの最小割合を示します。

  • 包含しきい値が 0 の場合、対応するマスク ブロック内の少なくとも 1 つのピクセルが非ゼロのときに apply はブロックを処理します。

  • 包含しきい値が 1 の場合、マスク ブロック内のすべてのピクセルが非ゼロのときにのみ apply はブロックを処理します。

マスク。サイズが bigimg と同じで ClassUnderlying プロパティ値が logical である bigimage オブジェクトとして指定します。

関数 apply は、マスクの非ゼロ ブロックと重なるブロックのみを処理します。InclusionThreshold も指定した場合、処理するブロックは、マスク ブロック内で最小限の割合の非ゼロ ピクセルと重なっていなければなりません。イメージ ブロックがマスク ブロックと十分に重なっている場合、apply は、イメージ ブロック全体を処理関数 fun に送信し、fun はブロック内のすべてのピクセルを処理します。fun はマスクに直接アクセスすることはできません。

イメージがマスクより粗い場合またはブロックのエッジがマスク ブロックと一致していない場合、入力ブロックは複数のマスク ブロックと重なる可能性があります。入力ブロックが複数のマスク ブロックと重なる場合、apply は、入力ブロックの中心と重なるマスクを選択します。

出力 bigimage を保存する場所。false または true として指定します。並列処理には Parallel Computing Toolbox™ が必要です。

不完全なエッジ ブロックのパディング方法。次のいずれかの値を指定します。既定では、apply は数値ブロックを 0 によってパディングし、categorical ブロックを missing によってパディングします。

値

意味

数値スカラー

定数値の要素によって数値配列をパディングします。

string スカラー

bigimage の Classes プロパティにある指定されたクラスによって categorical 配列をパディングします。

'replicate'

配列の境界の要素を繰り返すことによってパディングします。

'symmetric'

配列自体の鏡像で配列をパディングします。

部分ブロックのパディング。false または true として指定します。部分ブロックは、イメージのサイズが BlockSize で完全に割り切れない場合に生じます。それらが存在する場合、部分ブロックはイメージの右下端に沿った場所にあります。

  • false の場合、処理関数 fun はパディングをせずに部分ブロックを処理し、BlockSize よりも小さいブロックを返すことができます。

  • true の場合、関数 apply は指定された PadMethod を使用して部分ブロックをパディングします。処理関数 fun はフルサイズのブロックを処理して返します。

BatchSize が 1 より大きい場合は、PadPartialBlocks を true に設定してください。

データ型: logical

並列処理の使用。false または true として指定します。並列処理には Parallel Computing Toolbox が必要です。

UseParallel を true に指定すると、MATLAB® は既定の並列設定に基づいて自動的に並列プールを開きます。apply は、使用可能なワーカー全体で bigimage ブロックを処理します。すべての入力 bigimage の DataSource プロパティは、それぞれの並列ワーカーに対して有効なパスでなければなりません。相対パスを使用する場合、ワーカーとクライアント処理が同じ作業ディレクトリ上にあることを確認してください。ワーカーがクライアント処理と同じファイル システムを共有していない場合、OutputFolder を指定します。

データ型: logical

出力引数

すべて折りたたむ

処理された大きなイメージ。単一解像度レベルの bigimage オブジェクトとして返されます。newbig の行と列の数は、指定された解像度 level での大きな入力イメージ bigimg の行と列の数に等しくなります。ただし、newbig のチャネル数と基になるクラスは異なる可能性があります。

処理関数 fun の追加出力。次のいずれかとして返されます。fun が複数の出力引数を返す場合、apply は、それと同じ数またはそれより少ない数の出力引数を返す可能性があります。

値

発生

bigimage オブジェクト

対応する fun の出力引数が、入力ブロックと同じサイズ (または、BorderSize 引数を指定したとき、入力ブロックのパディングされたサイズ) の数値配列または logical 配列としてデータを返す場合、apply は bigimage を返します。

返される bigimage の解像度レベルは 1 つですが、チャネル数と基になるクラスは異なる可能性があります。

table

対応する fun の出力引数がデータを struct として返す場合、apply は table を返します。table には、各ブロックの (x,y) 原点をワールド座標の 1 行 2 列のベクトルとして指定する追加の BlockOrigin 変数があります。

cell 配列

対応する fun の出力引数がデータを非イメージとして返す場合、apply は cell 配列を返します。cell 配列には、各ブロックの (x,y) 原点をワールド座標の 1 行 2 列のベクトルとして指定する追加列があります。

ヒント

  • 推論の深層学習ネットワークを処理関数 fun 内で実行するときに GPU を最適に読み込むには、BatchSize の設定を 1 より大きくすると便利です。

アルゴリズム

apply は、最も効率的な順序で一度に 1 つのブロックのデータを処理関数 fun に渡して、すべてのデータを処理します (通常は行優先のブロック順序)。apply は各ブロックを 1 回だけ処理します。

多数の処理操作を実行するために apply を複数回呼び出すのは、すべてのデータを複数回処理しなければならないため、非効率的です。処理時間を最適化するには、複数の処理操作を実行するように fun を定義します。これにより、読み取りと書き込みのオーバーヘッドが最小化され、データ局所性が保証されます。粗い解像度レベルで作成したマスクを使用して、イメージの領域を処理から除外することにより、特定のレベルで処理時間をさらに短縮できます。

バージョン履歴

R2019b で導入

すべて展開する

参考

|