matlab-process-large-images

使用する場面

• blockedImage オブジェクトを作成、処理、可視化するコードを作成する場合
• カスタムファイル形式用に images.blocked.Adapter のサブクラスを実装する場合
• メモリに収まらない大きな画像データについてユーザーが支援を必要としている場合
• 画像処理タスクで並列計算を活用したい場合
• 全スライド画像、地理空間ラスター、3D 顕微鏡ボリューム、タイル化されたモザイクを扱う場合
• ユーザーが TIFF ファイルを扱っている場合は常に — このスキルを読み込み、まず imfinfo でファイルを確認してください。ファイルが大きい場合（いずれかの軸の寸法が 10,000 ピクセルを超える）、RGB を超える複数のチャンネルがある場合、または複数の IFD が含まれる場合（ピラミッドレベル、時系列、Z スタックのスライスの可能性があります）は、blockedImage を使用してください

使用しない場面

• 画像がメモリに十分収まり、並列処理も必要ない場合 — 標準の imread／imwrite ワークフローを使用してください
• blockedImage を使わない一般的な画像表示 — 代わりに matlab-display-image スキルを使用してください
• ディープラーニングモデルのアーキテクチャやトレーニングループの設計 — このスキルが対象とするのは blockedImageDatastore によるデータ準備であり、ネットワークの設計ではありません

blockedImage による大規模画像処理

参考ファイル（該当する話題が出たときに必要に応じて読みます）：

• references/visualization.md — imageshow、オーバーレイ、同期ビュー、概要＋詳細表示、注釈
• references/training-and-labeling.md — Image Labeler、ラベル付き blockedImage、トレーニング用データストア、DL 推論
• references/3d-volumes.md — 3D blockedImage、3D 推論、3D トレーニングデータ
• references/geospatial.md — GeoTIFF、シェープファイル、座標系、空間参照
• references/data-discovery.md — 7 ステップのデータ探索ワークフロー、カスタムアダプター、形式変換時のアダプター選択、仮想複合アダプター、アダプターのパフォーマンスに関するヒント
• references/specialized-workflows.md — ブロック単位の書き込み、座標系、マスクに基づくブロック選択、ピクセルレベルのマスキング用 ExtraImages、インプレースでの再開
• references/whole-slide-images.md — OpenSlide／Bio-Formats による WSI ファイルのインポート、ライブラリの選択、表示、後続処理（セグメンテーション、分類）

blockedImage を使用する場面

blockedImage は、RAM に収まらないデータだけを対象とするものではありません。データがメモリに収まる場合でも、それを blockedImage としてラップすれば並列クラスターを活用できます。各ワーカーが異なるブロックを個別に読み書きできるため、部分読み込みや個別のファイルブロックへの書き込みを並列で実行できます。

データの用途について、必ずユーザーに確認してください。 データが RAM に収まる場合でも、可視化、処理、DL トレーニング、アーカイブ、並列計算の活用を希望しているかどうかを確認してください。

ユーザーからディレクトリまたは複数ファイルのデータセットを指定された場合

コードを書く前に、必ず references/data-discovery.md を読み、7 ステップのワークフローに従ってください。 このワークフローでは、ファイル構成の確認、命名規則の解析、ユーザーの意図の把握、単一の blockedImage とコレクションのどちらを使うかの選択、ランダムアクセス機能の評価、欠落や重複の確認、アプローチ（組み込みアダプター、形式変換、カスタムアダプター）の推奨を行います。

構築

% Read-only (auto-selects adapter; reads only metadata, fast)
bim = blockedImage("large_image.tif");

% Multiple images at once
[bim1, bim2] = blockedImage(["img1.tif", "img2.tif"]);

% Writable
bim = blockedImage(dest, imageSize, blockSize, initVal, Mode="w");

% Override adapter
bim = blockedImage(source, Adapter=myAdapter);

BlockSize

• 既定値は IOBlockSize（アダプターのネイティブな読み取り単位）の倍数で、約 1024 または最小の次元サイズを目標とします。
• オブジェクトの BlockSize は、後続のすべての処理と可視化で使われる既定値です。
• BlockSize の名前と値の引数で操作ごとに上書きできます（たとえば、DL ネットワークで固定の入力サイズが必要な場合）。
• パフォーマンスを最大限に高めるには、BlockSize を IOBlockSize の倍数にし、実用上できるだけ大きくしてください。

データの読み取り

• getBlock(bim, blocksub) — ブロックの添字で指定したブロックを 1 つ読み取ります。[data, blockinfo] を返します。
• getRegion(bim, pixelStart, pixelEnd) — 任意のピクセル領域を読み取ります。
• gather(bim) — 画像全体をメモリに読み込みます（RAM に収まる場合のみ）。解像度を選択するには Level を使用します。

apply() による処理

apply(bim, @fcn) は、各ブロックに対して一度に 1 つずつ fcn を呼び出します。任意の大きさのデータに対応します。クラスターでの実行には UseParallel=true を指定できます。

主な名前と値の引数：BlockSize、BorderSize、Level、ExtraImages、PadPartialBlocks、PadMethod、OutputLocation、BatchSize、Resume、BlockLocationSet、DisplayWaitbar。

ブロック構造体（bs）のフィールド

ユーザー関数には、次のフィールドを持つブロック構造体 bs が渡されます。

• bs.Data — このブロックのピクセルデータ（BorderSize > 0 の場合は境界部分を含みます）
• bs.Start — ブロックの左上隅の 1-by-N ピクセル添字（境界部分を除く）
• bs.End — ブロックの右下隅の 1-by-N ピクセル添字（境界部分を除く）
• bs.BorderSize — 使用された 1-by-N の境界サイズ
• bs.Level — 解像度レベル
• bs.BlockSub — ブロックの添字（SizeInBlocks へのインデックス）
• bs.ImageNumber — ソース画像のインデックス（配列を処理する場合）

構造体／非画像出力

ブロックごとの出力が画像データではない場合（検出結果やカウントなど）は、構造体の保存に images.blocked.MATBlocks アダプターを使用します。

bResults = apply(bim, @countNuclei, ...
    BlockLocationSet=bls, BorderSize=[r r], ...
    Adapter=images.blocked.MATBlocks, OutputLocation="results_dir");
allResults = gather(bResults);  % load all structs into memory

実データだけに処理を限定する

• 最初にクロップします。 crop(bim, cstart, cend) は仮想的な操作で、データのコピーはなく、即座に実行されます。処理前に空間 ROI または単一チャネルに範囲を限定するために使用します。
• selectBlockLocations でマスクを使用します。 粗いレベルからマスクを作成し、ROI と重なるブロックだけを処理します。InclusionThreshold やブロックサイズの調整を含む一連の手順については、references/specialized-workflows.md を参照してください。

主なパターン

• 1 回のパスで処理します。 データを 1 回だけ処理するために、前処理と後処理をすべて fcn 内で行います。
• ワールド座標。 fcn にはブロックのメタデータが渡されます。検出結果を返す前に、sub2world() を使ってブロック内の位置をワールド座標に変換します。
• 重なりのための BorderSize。 処理関数が隣接ブロックの情報を必要とする場合（例：出力視野より広い入力を必要とする DL ネットワーク）は、BorderSize を設定します。
• 重心による検出結果の重複排除。 BorderSize をオブジェクトの最大直径の半分以上に設定します。ユーザー関数内で、重心が境界領域にある検出結果を破棄し、残った重心を bs.Start を使ってグローバル座標に変換します。

  onBorder = centroids(:,1) < bs.BorderSize(1) ...
           | centroids(:,1) > size(bs.Data,1) - 2*bs.BorderSize(1) ...
           | centroids(:,2) < bs.BorderSize(2) ...
           | centroids(:,2) > size(bs.Data,2) - 2*bs.BorderSize(2);
  centroids(onBorder,:) = [];
  centroids = centroids + bs.Start(1:2);  % local -> global
  

  検出器の結果に一貫性がない場合は、2 回目の apply() パスで BorderSize=BlockSize を指定し、グローバル座標でバウンディングボックスの重なりに基づいて重複排除します。
• マルチ解像度出力。 makeMultiLevel2D(bResult, Scales=[1 0.5 0.3 0.1]) を使って、単一レベルの結果からピラミッドを生成します。ラベル／マスクデータには "nearest" 補間を使用します。または、fcn から複数のレベルを返し、concatenateLevels で結合します。
• 小さなブロック出力。 ブロックごとの出力がごく小さい場合（カウントなど）は、gather() でメモリにすべての結果を読み込むか、write() でより大きなブロックサイズを指定して書き換えます。
• 再開。 Resume=true を設定すると、以前中断した apply() を中断箇所から再開できます。上書きを伴うインプレース再開については、references/specialized-workflows.md を参照してください。
• 複数出力の apply。 処理関数が N 個の出力を返す場合、apply は個別の blockedImages を N 個返します。これを使って、1 回のパスでチャネルを分割できます。

  [o1, o2, o3, o4] = apply(bim, @(bs) splitChannels(bs), ...
      BlockSize=[10 2048 2048 4], UseParallel=true, OutputLocation=outDir);
  

• ピクセルレベルのマスキングに ExtraImages を使用します。 2 つ目の blockedImage を ExtraImages 経由で渡すと、ブロック関数内でプライマリ画像とともにアクセスできます。解像度の不一致への対処を含む一連の手順については、references/specialized-workflows.md を参照してください。
• 1 回のパスでピラミッド TIFF を作成します。 LevelImages を使って、マルチ解像度レベルを生成し、単一のピラミッド TIFF として書き込みます。

  [b1,b2,b3,b4] = apply(bim, @resizeBlocks);
  write(bim, "pyramid.tif", LevelImages=[b1 b2 b3 b4], BlockSize=[2048 2048]);
  function [b1,b2,b3,b4] = resizeBlocks(bs)
      b1 = imresize(bs.Data, 0.5, 'nearest');
      b2 = imresize(b1, 0.5, 'nearest');
      b3 = imresize(b2, 0.5, 'nearest');
      b4 = imresize(b3, 0.5, 'nearest');
  end
  

• BatchSize。 BatchSize=N を設定すると、複数のブロックを一度に処理できます。ブロック関数には、末尾にサイズ N の次元が追加された bs.Data と、ブロック数を示す bs.BatchSize が渡されます。ブロックごとのオーバーヘッドが大きい場合に便利です。

反復的な開発ワークフロー

フル解像度のブロック画像の処理には時間がかかります。まず小さなデータでプロトタイプを作成し、フィードバックサイクルを短縮してください。

1. 粗いレベルでプロトタイプを作成します。 gather(bim, Level=bim.NumLevels) を使用して、最も粗いレベルをメモリに読み込みます。この小さな画像で開発してパラメーターを調整してから、フル画像に適用します。

   imCoarse = gather(bim, Level=bim.NumLevels);
   thresh = graythresh(im2gray(imCoarse));
   bResult = apply(bim, @(bs) ~imbinarize(im2gray(bs.Data), thresh));
   

2. ROI でプロトタイプを作成します。 getRegion を使用して特徴を代表する小さな領域を抽出し、パラメーターを調整してから適用します。

   roi = getRegion(bim, [900 2400], [1700 3300], Level=1);
   thresh = graythresh(im2gray(roi));
   bResult = apply(bim, @(bs) ~imbinarize(im2gray(bs.Data), thresh));
   

並列処理

結果をディスクに書き込む場合は、Parallel Computing Toolbox の有無を確認し、利用可能であれば使用してください。

outDir = tempname;
usepar = ~isempty(ver("parallel"));
bResult = apply(bim, @fcn, UseParallel=usepar, OutputLocation=outDir);

OutputLocation を指定する場合は、必ず UseParallel も含めてください。ツールボックスの有無に応じて設定します。

可視化

利便性ではなく、データに基づいて 2D と 3D のどちらを使用するか決めてください。

• 3D ボリューム（Z スタック、CT、MRI、顕微鏡スタック）： デフォルトでは volshow と viewer3d を使用します。マルチチャネルのオーバーレイには OverlayData、インタラクティブな閲覧には SlicePlanes、概要と詳細の表示には linkviewers を使用します。詳細なパターンについては、references/3d-volumes.md をお読みください。3D データをスライスごとに 2D ビューアーへ分割しないでください。空間的なコンテキストが失われ、3D ツールも活用できなくなります。
• 2D 画像（全スライド画像、衛星画像、モザイク）： imageshow と viewer2d を使用します。オーバーレイ、同期ビュー、概要と詳細の表示、注釈については、references/visualization.md をお読みください。

データに Z／深度／スライスの次元がある場合は、3D です。スライスごとに別ファイルであっても、3D の手順を使用してください。

形式変換

形式間の変換やデータの再チャンク化には、write(bim, destination) を使用します。

write(bim, "output.tif", BlockSize=[512 512 3]);

変換時のアダプター（JPEG、PNG、H5Blocks）の選択方法については、references/data-discovery.md の「形式変換でのアダプターの優先順位」を参照してください。

---

Copyright 2026 The MathWorks, Inc.