3D Measurement & Acquisition QA（三维测量与采集质量检查）

3D Measurement & Acquisition QA - User Manual

Dragonfly Prototype Apps · 3D Measurement & Acquisition QA...

版本 Version 1.0 · 2026-08-01

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

在做任何测量之前，本插件先回答一个更基础的问题：这份采集数据能不能用来测量？ 它检查聚焦、饱和、噪声与频谱，给出主导结构尺度，并考察每个对象内部的强度分布。

面板分为 6 个编号步骤。任何上游输入或参数变化都会使下游结果失效，导出的数字永远对应当前设置；长任务在工作线程中运行，取消或失败都不会发布任何东西。

体素间距自动读自 Dragonfly 几何。各向异性数据在需要各向同性的步骤会真正重采样，而不是把三轴间距平均后当作物理长度——那样得到的「尺寸」不是长度。

2. 适用场景

• 批量扫描进入分析流程前的自动质检：先挑出失焦、过曝、信噪比不足的数据。
• 多通道成像：检查通道之间是否串扰或错位（通道相关性）。
• 确定主导颗粒或孔隙尺度（三维粒度分析）。
• 考察对象内部强度是均匀还是集中在边缘：壳层结构、镀层、染色渗透深度。

3. 安装与启用

1. 安装 Prototype Apps 完整包（或在 App Store 中勾选本插件）。

2. 本插件默认未启用，请在 App Store 或菜单项管理器中启用。

3. 完全重启 Dragonfly（插件只在启动时被发现）。

4. 从菜单打开：Prototype Apps ▸ 3D Measurement & Acquisition QA…（分组：Measurements & Analysis）。

4. 运行环境与首次配置

无需任何安装或配置。 完全运行在 Dragonfly 自带的 Python 中，使用其已附带的 NumPy 与 SciPy。不联网、不下载、不需要 GPU、不创建虚拟环境。

面板顶部的 Environment 一行显示当前可用能力（是否可发布通道、是否可读取 MultiROI）。不可用的功能会被禁用并说明原因。

5. 界面说明

顶部固定显示运行环境、当前输入、当前任务、进度条与 Cancel。

1. 数据与环境

选择通道（只列出已发布对象），可选 ROI 掩膜与 MultiROI 对象，以及时间步。选定后会显示形状、三轴间距、是否各向异性和时间步数，并据此自动设定粒度分析的半径量程。

2. 图像质量

输出聚焦度（整体与分块的最小值/中位数/5 分位）、饱和比例（分别统计触底与触顶）、强度统计、噪声（MAD×1.4826）与信噪比、功率谱斜率。

3. 粒度分析

以一系列物理半径做开运算，得到保留曲线与尺寸谱，并给出峰值半径。半径量程根据体素尺寸自动设定；超出上限的半径会被跳过并明确提示，而不是耗尽内存。

4. 径向分布

对 MultiROI 的每个标签，按等体积同心壳层统计强度占比与均值，并给出径向变异系数。等体积而非等厚度，否则最外层仅因为体积大就总是占优。

5. 批量质检规则

对第 2 步测得的指标套用阈值规则，给出 pass / warn / fail 与触发原因。规则引用了但测量未提供的指标会被标为 missing，绝不当作通过。

6. 结果与导出

发布聚焦度或噪声通道（新对象，继承源几何），或导出 CSV / JSON / 自包含 HTML 报告。

6. 使用步骤

1. 第 1 步选择通道（需要时加 ROI 掩膜与 MultiROI）。

2. 第 2 步运行图像质量，先看饱和比例与信噪比。

3. 第 3 步运行粒度分析，读取峰值半径。

4. 第 4 步（需选 MultiROI）运行径向分布。

5. 第 5 步设定阈值并运行批量质检。

6. 第 6 步发布通道或导出报告。

7. 参数说明

8. 输出结果

• 聚焦度通道 / 噪声通道：新发布的通道，继承源通道的间距与几何，原通道不被修改。
• CSV：图像质量指标、粒度曲线、逐标签逐壳层的径向分布。
• JSON：全部结果的结构化输出。
• HTML：自包含报告，只包含实际运行过的步骤。

9. 常见问题与故障排除

列表里没有我的通道。 只显示已发布对象；先发布，再点第 1 步的「刷新」。

粒度分析提示跳过了若干半径。 该半径换算成体素后超过了上限（默认 32 体素，且不超过体积最短边的一半）。请先降采样，或减小最大半径。

第 4 步按钮是灰的。 径向分布需要一个 MultiROI，请在第 1 步选择。

信噪比显示为空。 噪声估计为 0（例如完全平坦的合成数据），此时信噪比没有意义。

质检结果里有 missing。 规则引用的指标本次没有测到，插件不会把它当作通过。

10. 注意事项与已知限制

• 本插件不做 Radiomics 纹理特征（GLCM/GLRLM 等）——那是 MultiROI Label Classifier 的职责，重复实现会让同一个量有两个数字。
• 不做空间关系分析（CPC 插件）与分割结果比较（MiC 插件）。
• 结构元半径上限为 32 体素且不超过体积最短边的一半；更大的结构请先降采样。
• 功率谱斜率对视场大小和窗函数敏感，适合同一批数据横向比较，不适合跨设备绝对比较。
• 饱和判定基于存储数据类型的取值范围；浮点数据没有固有范围，此时使用观测到的最小/最大值。

11. 参考资料

• CellProfiler 的 MeasureImageQuality / MeasureGranularity / MeasureObjectIntensityDistribution 模块文档（仅作为需要测什么的参考，本插件未使用其源码）：https://cellprofiler-manual.s3.amazonaws.com/CellProfiler-4.2.8/modules/measurement.html
• Matheron, G.：粒度分析（granulometry）的数学形态学基础
• SciPy ndimage 形态学与滤波器文档

Part II English Manual

Contents

1. Introduction

2. Use cases

3. Installation & enabling

4. Runtime environment & first-run setup

5. Interface

6. How to use

7. Parameters

8. Output

9. FAQ & troubleshooting

10. Notes & known limitations

11. References

1. Introduction

Before anything is measured, this plugin answers a more basic question: is this acquisition good enough to measure? It checks focus, saturation, noise and spectrum, reports the dominant structure scale, and examines how intensity is distributed inside each object.

The panel is six numbered steps. Changing anything upstream invalidates the results below it, so an exported number always matches the settings on screen; long analyses run on a worker thread, and cancel or failure publishes nothing.

Voxel spacing is read from Dragonfly's geometry. Anisotropic data is genuinely resampled where a metric needs isotropy, instead of averaging the three spacings and calling the result a physical length — that number would not be a length.

2. Use cases

• Screen a batch of scans before analysis: catch out-of-focus, clipped or noisy data early.
• Multi-channel imaging: check for bleed-through or misalignment via channel correlation.
• Find the dominant particle or pore scale with 3D granulometry.
• See whether intensity inside an object is uniform or edge-loaded: shells, coatings, stain penetration depth.

3. Installation & enabling

1. Install the Prototype Apps package (or tick this plugin in the App Store).

2. The plugin is disabled by default — enable it in the App Store or the Menu Item Manager.

3. Restart Dragonfly completely (plugins are discovered at startup only).

4. Open it from Prototype Apps ▸ 3D Measurement & Acquisition QA… (group: Measurements & Analysis).

4. Runtime environment & first-run setup

Nothing to install or configure. It runs entirely in Dragonfly's own Python using the NumPy and SciPy it already ships. No internet, no download, no GPU, no virtual environment.

The Environment line reports what is available (channel publishing, MultiROI reading). Anything unavailable disables the matching feature and says why.

5. Interface

A fixed header shows the environment, the current input, the current task, a progress bar and Cancel.

1. Setup & Data

Pick a Channel (published objects only), optionally an ROI mask and a MultiROI, and a timestep. The shape, the three spacings, whether the data is anisotropic and the timestep count are shown, and the granulometry radius range is derived from the voxel size.

2. Image Quality

Focus (global plus the minimum, median and 5th percentile over blocks), saturation (low and high counted separately), intensity statistics, noise (MAD x 1.4826) and SNR, and the power-spectrum slope.

3. Granularity

Grey openings over a series of physical radii give the retained curve, the size spectrum and the peak radius. The radius range follows the voxel size, and a radius too large for the data is skipped with an explicit message rather than exhausting memory.

4. Radial Distribution

For each MultiROI label, intensity fraction and mean over equal-volume concentric shells, plus the radial CV. Equal volume rather than equal thickness, otherwise the outermost shell always dominates simply by being bigger.

5. Batch QC Rules

Threshold rules applied to the step-2 metrics give pass / warn / fail with the triggering reason. A metric a rule names but the measurement does not provide is reported as missing, never as a pass.

6. Results & Export

Publish a focus or noise Channel (a new object inheriting the source geometry), or export CSV, JSON and a self-contained HTML report.

6. How to use

1. Step 1: choose the Channel (and an ROI mask / MultiROI if needed).

2. Step 2: run image quality; read saturation and SNR first.

3. Step 3: run granularity and read the peak radius.

4. Step 4 (needs a MultiROI): run the radial distribution.

5. Step 5: set thresholds and run the batch QC.

6. Step 6: publish a map or export a report.

7. Parameters

8. Output

• Focus / noise Channel: a newly published Channel inheriting the source spacing and geometry. The source is never modified.
• CSV: image-quality metrics, the granulometry curve, and per-label per-shell radial values.
• JSON: the full structured result set.
• HTML: a self-contained report containing only the steps that actually ran.

9. FAQ & troubleshooting

My channel is not listed. Only published objects appear; publish it, then press Refresh in step 1.

Granularity says radii were skipped. In voxels those radii exceed the cap (32 voxels, and never more than half the shortest volume axis). Downsample first, or lower the maximum radius.

The step-4 button is greyed out. The radial distribution needs a MultiROI; select one in step 1.

SNR is blank. The noise estimate was zero (perfectly flat synthetic data, for instance), which makes SNR meaningless.

The QC table shows 'missing'. A rule names a metric this run did not measure; the plugin will not treat that as a pass.

10. Notes & known limitations

• This plugin does not compute Radiomics texture features (GLCM/GLRLM and friends) — the MultiROI Label Classifier owns those, and duplicating them would give one quantity two numbers.
• It does not do spatial-relationship analysis (the CPC plugin) or segmentation comparison (the MiC plugin).
• The structuring element is capped at 32 voxels and at half the shortest volume axis; for larger structures, downsample first.
• The power-spectrum slope depends on field of view and windowing. It is meant for comparing scans within one batch, not as an absolute number across instruments.
• Saturation is judged against the storage dtype's range; float data has no intrinsic range, so the observed minimum and maximum are used.

11. References

• CellProfiler's MeasureImageQuality / MeasureGranularity / MeasureObjectIntensityDistribution module documentation, used only as a reference for which quantities matter — no source was used: https://cellprofiler-manual.s3.amazonaws.com/CellProfiler-4.2.8/modules/measurement.html
• Matheron, G. — the mathematical-morphology basis of granulometry
• SciPy ndimage morphology and filter documentation