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、带标签的 blockedImages、训练数据存储、深度学习推理
• references/3d-volumes.md — 3D blockedImage、3D 推理、3D 训练数据
• references/geospatial.md — GeoTIFF、shapefile、坐标系、空间参照
• references/data-discovery.md — 7 步数据发现工作流、自定义适配器、格式转换适配器选择、虚拟复合适配器、适配器性能提示
• references/specialized-workflows.md — 按块写入、坐标系、基于掩膜的块选择、用于像素级掩膜的 ExtraImages、原位续传
• references/whole-slide-images.md — 通过 OpenSlide/Bio-Formats 导入 WSI 文件、在不同库之间进行选择、显示、下游处理（分割、分类）

何时使用 blockedImage

blockedImage 不仅适用于数据超出 RAM 容量的情况。即使数据可装入内存，将其包装为 blockedImage 也能让你利用并行集群：每个工作进程都可以独立读写不同的数据块，从而并行读取部分数据，并并行写入不同的文件块。

**务必询问用户对数据的意图。**询问他们是否需要可视化、处理、深度学习训练或归档，以及是否希望利用并行计算——即使数据可装入 RAM 也要询问。

用户提供目录或多文件数据集时

始终先阅读 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 名称-值参数覆盖（例如，深度学习网络要求固定输入尺寸时）。
• 为获得最佳性能，请使 BlockSize 为 IOBlockSize 的倍数，并尽可能取较大值。

读取数据

• getBlock(bim, blocksub) — 按块下标读取一个块。返回 [data, blockinfo]。
• getRegion(bim, pixelStart, pixelEnd) — 读取任意像素区域。
• gather(bim) — 将整幅图像加载到内存中（仅当图像可装入 RAM 时）。使用 Level 选择分辨率。

使用 apply() 处理

apply(bim, @fcn) 会逐个对每个块调用 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。

重要模式

• 单次处理。 在 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
  

  对于结果不一致的检测器，可添加第二次 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 会返回 N 个独立的 blockedImages。可用此方式在单次处理中拆分通道：

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

• 使用 ExtraImages 进行像素级掩码处理。 通过 ExtraImages 传入第二个 blockedImage，以便在块函数中与主图像一同访问。完整模式（包括分辨率不匹配的处理）请参见 references/specialized-workflows.md。
• 一次处理生成金字塔 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 中的“格式转换的适配器选择”。

---

版权所有 2026 The MathWorks, Inc.