MATLAB TIFF 工具集

面向显微/成像数据的 TIFF 读写与处理小工具集合，包含：

• 快速读取多帧/多通道 TIFF（支持按帧范围读取）
• 保存 2D/3D 堆栈为标准或 BigTIFF，并自定义/合并 Tag
• 多通道拆分、可选去涟漪噪声、自动生成平均图
• 常用投影（平均/标准差/帧子集最大阈值）
• 读取/精简元数据、分辨率读取、批量编号范围探测

适合批处理 TIFF 体数据与显微成像数据预处理流程。

依赖与环境

• MATLAB R2019b 及以上（使用了 arguments 块与 Tiff 类）
• Image Processing Toolbox（用于 imadjust，可选）
• 可选：Fast_Tiff_Write / Fast_BigTiff_Write（用于更快地写多帧 TIFF，tiff_split 依赖）。如未安装，可将其替换为内置 Tiff 写入逻辑，或使用本仓库的 tiff_save 改写。

提示（命名空间）：部分示例或代码中出现 utils.xxx 的调用（比如 utils.tiff_save）。如果你直接将本目录加入 MATLAB 路径，请将调用中的 utils. 前缀移除，或把本目录重命名为包目录 +utils/ 后再使用带前缀的方式。

安装

将本文件夹加入 MATLAB 路径（建议递归）：

addpath(genpath('path/to/tiff'));
savepath; % 可选：持久化

如需使用 tiff_split 的高速写入，请确保已在路径中提供 Fast_Tiff_Write 与 Fast_BigTiff_Write 类实现。

快速上手

读取整卷/按帧范围读取/多通道拆分：

% 读取所有帧（单通道）
img = tiff_read('stack.tif');

% 读取第 5 帧（单通道）
img5 = tiff_read('stack.tif', 5);

% 读取帧范围 1 到 10（单通道）
img1to10 = tiff_read('stack.tif', '1:10');

% 读取所有帧（双通道交织：ch1, ch2, ch1, ch2, ...）
[ch1, ch2] = tiff_read('stack_multi.tif', 'none', 2);

保存到 TIFF（自动选择 BigTIFF，如果超过 ~3.76GB）：

% 直接保存 3D 堆栈
tiff_save(img, 'out.tif');

% 复用原文件 Tag 再保存
tags = tiff_read_tag('stack.tif');
tiff_save(img, 'out_with_tags.tif', tags);

简单投影：

avg2d = tiff_projection_avg(img);     % 平均投影（uint16）
std2d = tiff_projection_std(img);     % 标准差投影（uint8，归一化后）

% 选取“最大阈值比例”的帧子集（非常规“max投影”，返回子集堆栈，而非 2D）
topFrames = tiff_projection_max(img, 0.1); % 返回按像素值降序排序后的前 10% 帧堆栈

读取分辨率、精简 Tag：

res = tiff_get_resolution('stack.tif');   % XResolution (像素/厘米)
tags = tiff_read_tag('stack.tif');
tags_simple = tiff_tag_simple(tags);      % 去除 Software/Artist 字段

拆分多通道并可选保存平均图：

tiff_split('stack_multi.tif', 2, ...
		'FolderProcessed', 'Processed', ...
		'AvgOutput', true, ...
		'rippleNoiseEnable', true, ...
		'rippleNoise', 700);
% 说明：依赖 Fast_Tiff_Write / Fast_BigTiff_Write；平均图将以 *_AVG.tif 形式输出

探测按规则命名的帧编号范围：

[startNum, endNum] = get_tiff_num_range('path/to/folder');
% 扫描模式 file_00001.tif, file_00002.tif, ...，并尝试避开“仍在生成”的文件

按倍数扩充帧数（重复写出）：

tiff_expand('input.tif', 'expanded.tif', 50); % 每帧重复 50 次

API 概览

• img = tiff_read(filepath, frame_range, nChannel)

  • 按需读取 TIFF：
    • frame_range 可为：'none'（默认/全量）、标量帧索引、'start:end' 字符串
    • nChannel>1 时，返回按通道拆分的多个输出，每个为该通道的 3D 堆栈

• tiff_save(input_img, filepath, tags)

  • 保存 2D/3D 图像为多页 TIFF；自动判断是否使用 BigTIFF（>~3.76GB）
  • tags 为空则按 input_img 自动生成；否则与默认标签合并（保留自定义字段）

• tags = tiff_read_tag(input)

  • 读取常用 TIFF Tag（支持传入文件路径或已打开的 Tiff 对象）

• res = tiff_get_resolution(filepath)

  • 读取 XResolution（像素/厘米）

• tags2 = tiff_generate_tagstruct(input_img, inputTags)

  • 基于图像尺寸/类型生成合规 Tag，并与 inputTags 合并（保留未覆盖字段）

• tags_simple = tiff_tag_simple(tags)

  • 去掉 Software 与 Artist 字段的精简标签

• avg2d = tiff_projection_avg(imgStack)

  • 第三维求均值后转 uint16

• std2d = tiff_projection_std(imgStack)

  • 第三维求标准差后归一化并转 uint8

• topFrames = tiff_projection_max(imgStack, thresholdMax)

  • 将第三维按像素值降序排序，取前 ceil(nFrames*thresholdMax) 帧的子堆栈（注意：不是传统意义的“最大投影”）

• averageImage = avg_big_tiff(filePath)

  • 适用于大体积文件：逐帧累加求平均，返回 uint16

• tiff_split(inputFilePath, numChannels, options)

  • 将交织的多通道堆栈按通道拆分输出；可选：去涟漪噪声、输出平均图、进度显示
  • 需第三方写入器 Fast_Tiff_Write/Fast_BigTiff_Write

• [startNum, endNum] = get_tiff_num_range(folder)

  • 在 folder 下匹配 file_00001.tif 这类规则文件名，返回最小和最大编号

• tiff_expand(inputFilePath, outputFilePath, expansionFactor)

  • 将每帧重复写出 expansionFactor 次，自动选择标准 TIFF 或 BigTIFF

注意事项与最佳实践

• 大文件与 BigTIFF：

  • tiff_save 在估算文件体积 > ~3.76 GB 时会启用 BigTIFF（'w8'）。
  • tiff_expand 会按 4 GB 阈值预判并使用 BigTIFF。

• 数据类型：

  • 标签中的 BitsPerSample 与 SampleFormat 会依据 input_img 类型自动设置。
  • tiff_projection_std 返回 uint8，如需保留位深，请自行调整。

• 多通道交织：

  • tiff_read(..., nChannel>1) 假设帧顺序按 ch1,ch2,ch3,... 重复交织。

• 依赖组件：

  • 若没有 Fast_Tiff_Write/Fast_BigTiff_Write，请改写 tiff_split 中写入部分为 Tiff/tiff_save。