Structure Scale Analyzer（结构尺度分析）

Structure Scale Analyzer - User Manual

Dragonfly Prototype Apps · Structure Scale Analyzer...

版本 Version 1.0 · 2026-08-01

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

本插件回答一个看似简单、实际很容易算错的问题：这个结构到底有多大？ 它对一个已分割的 ROI 或 MultiROI 逐步腐蚀（或膨胀），记录每一步还剩下多少个连通体。当一批尺寸相近的结构在同一步集体消失时，连通体数量会出现一次陡降——这一步就对应它们的特征尺度。

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

所报告的半径来自欧氏距离变换，不是数腐蚀步数得到的。 数步数最多只能精确到半个体素，而且偏差方向取决于真值落在两个整数之间的位置：用球体和平板做过验证，球体系统性偏大半个体素、平板系统性偏小半个体素。距离变换没有这个偏差，对任意体素长宽比都给出精确的物理长度。腐蚀步数估计仍然单独列为 Step estimate (±½ voxel)，供对照。

2. 适用场景

• 多孔材料：孔径分布与孔壁厚度。
• 纤维、血管、骨小梁：直径与相互间距。
• 涂层、膜层、器壁：厚度（用「厚度」模式）。
• 颗粒堆积体：颗粒的特征尺寸。
• 结构互相连通、无法逐个分割计数时，形态学尺度是少数仍然可用的测量方式。

3. 安装与启用

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

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

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

4. 从菜单打开：Prototype Apps ▸ Structure Scale Analyzer…（分组：Measurements & Analysis）。

4. 运行环境与首次配置

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

第 1 步会显示当前 Dragonfly 版本支持哪些能力：能否从数组发布 ROI、能否发布通道、能否读取 MultiROI。不可用的按钮会被禁用，而不是运行后才失败。

5. 界面说明

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

1. 环境

方法简介与能力探测结果。

2. 输入与分析模式

选择 ROI 掩膜或 MultiROI（只列出已发布对象）。选了 MultiROI 时优先使用 MultiROI，并可在第 6 步逐标签批量分析。三种模式：结构尺度与厚度都用腐蚀（前者关注整体特征尺度，后者关注局部半厚度）；对象间距改用膨胀，测的是背景一侧的尺度。连通性可选 6 连通（面）或 26 连通（面+棱+角）。

3. 参数与物理尺度

体素尺寸默认自动读自 Dragonfly 几何（单位毫米）；勾选 Override voxel size 可手动指定，用于几何信息缺失的对象。Resample anisotropic data to isotropic 在三轴间距不同时先重采样，否则腐蚀的「一步」在不同方向代表不同的物理距离。最大迭代次数限制曲线长度；平滑 sigma 与峰值偏移只影响腐蚀步数估计，不影响所报告的半径。

4. 预览与运行

Load mask 从 Dragonfly 读取数据并显示形状与前景体素数，Run analysis 运行主分析，Run per-label batch 对 MultiROI 的每个标签独立分析。

5. 曲线与结果

曲线图为连通体数随腐蚀步的变化（虚线为平滑结果，红色竖线为导数峰值位置）。结果表列出特征半径、全宽、测得对象数、最小/最大半径、峰值腐蚀步、步数估计、分布半高全宽、体素尺寸与终止原因。所有警告显示在表格下方。

6. 批量与导出

逐标签结果表；发布峰值状态 ROI（腐蚀到峰值步时的掩膜）与「局部半厚度」通道（每个体素到背景的距离，单位毫米）；导出 CSV 或 JSON。

6. 使用步骤

1. 第 2 步选择 ROI 或 MultiROI，选定分析模式与连通性。

2. 第 3 步确认体素尺寸（各向异性数据保持勾选重采样）。

3. 第 4 步点击 Load mask，确认形状与前景体素数合理。

4. 第 4 步点击 Run analysis。

5. 第 5 步读取特征半径，并核对警告与终止原因。

6. 需要逐标签结果时回到第 4 步运行批量分析；第 6 步发布或导出。

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

• 结果提示「峰值在第一个腐蚀步」：结构尺寸已接近或小于体素尺寸，报告值只是下界。需要更高分辨率的数据。
• 提示到达迭代上限：结构比 64 步还大，请在第 3 步提高最大迭代次数。
• 间距模式提示找不到对象之间的脊线：掩膜里只有一个连通体，或者对象彼此相连。间距至少需要两个分开的对象。
• Publish peak-state ROI 报错：该 Dragonfly 版本没有向 Python 暴露「从数组创建 ROI」的接口。改用导出，或发布局部半厚度通道。
• 结果与预期差一个量级：检查第 2 步显示的间距。若对象没有几何信息，请在第 3 步手动指定体素尺寸。

10. 注意事项与已知限制

• 间距按每一对对象的最近处计算。 早期实现沿整条背景脊线取值，结果被开放空间夸大；现在只取每一对对象之间脊线上的最小值。
• 间距模式忽略触及体积边界的背景区域，因为样品外的空白不是结构间距。
• 腐蚀曲线用 scipy.ndimage（BSD）标记连通体。更快的 connected-components-3d 是 LGPL，本插件以无源字节码形式随商业包分发，故不采用。
• 输入必须是已发布的 ROI 或 MultiROI；未发布对象不会出现在下拉列表中。
• 整卷读入内存。超大体积请先裁剪到感兴趣区域。

11. 参考资料

形态学粒度分析：G. Matheron, Random Sets and Integral Geometry, Wiley, 1975。局部厚度与距离变换：T. Hildebrand & P. Rüegsegger, "A new method for the model-independent assessment of thickness in three-dimensional images", Journal of Microscopy 185(1), 1997。

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

This plugin answers a question that sounds simple and is easy to get wrong: how big is this structure, really? It erodes (or dilates) a segmented ROI or MultiROI step by step and records how many connected components survive each step. When a population of similarly sized structures disappears together, the component count drops sharply — and that step corresponds to their characteristic scale.

The panel has 6 numbered steps. Changing anything upstream invalidates every downstream result, so an exported number always matches what is on screen; the analysis runs on a worker thread, and cancel or failure publishes nothing.

The reported radius comes from the Euclidean distance transform, not from counting erosion steps. A step count can only resolve the scale to half a voxel, and the sign of that error depends on where the true radius falls between two integers: measured against phantoms, spheres came out systematically half a voxel too large and slabs half a voxel too small. The distance transform has no such bias and gives an exact physical length for any voxel aspect ratio. The erosion-step estimate is still reported separately as Step estimate (±½ voxel) for comparison.

2. Use cases

• Porous materials: pore size and pore-wall thickness.
• Fibres, vessels, trabeculae: diameter and the spacing between them.
• Coatings, membranes, vessel walls: thickness (use the thickness mode).
• Grain packings: the characteristic grain size.
• When the structure is interconnected and cannot be split into countable objects, a morphological scale is one of the few measurements still available.

3. Installation & enabling

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

2. This 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 ▸ Structure Scale Analyzer… (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.

Step 1 shows what this Dragonfly build supports: whether an ROI can be created from an array, whether a Channel can be published, whether MultiROI labels are readable. Unavailable actions are disabled up front rather than failing after a long run.

5. Interface

The header always shows the environment, the current input, the running task, a progress bar and Cancel.

1. Setup

A short description of the method plus the capability probe.

2. Input & Analysis Mode

Pick an ROI mask or a MultiROI (published objects only). A MultiROI takes precedence and unlocks the per-label batch in step 6. Three modes: structure scale and thickness both erode (the first looks at the overall characteristic scale, the second at local half-thickness); spacing between objects dilates instead, measuring the scale on the background side. Connectivity is 6-connected (faces) or 26-connected (faces + edges + corners).

3. Parameters & Physical Scale

The voxel size is read from Dragonfly's geometry (in millimetres); tick Override voxel size to set it by hand for objects without geometry. Resample anisotropic data to isotropic matters because otherwise one erosion step means a different physical distance along each axis. The iteration limit bounds the curve; smoothing sigma and the peak offset only affect the erosion-step estimate and not the reported radius.

4. Preview & Run

Load mask reads the data from Dragonfly and reports its shape and foreground voxel count, Run analysis runs the main measurement, and Run per-label batch analyses every label of a MultiROI independently.

5. Curve & Results

The plot shows component count against erosion step (dashed = smoothed, red line = the derivative peak). The table lists the characteristic radius, full width, number of objects measured, min/max radius, the peak erosion step, the step estimate, the distribution FWHM, the voxel size and why the curve stopped. Warnings appear underneath.

6. Batch & Export

The per-label table; publishing the peak-state ROI (the mask eroded to the peak step) and a local half-thickness Channel (each voxel's distance to background, in mm); and export to CSV or JSON.

6. How to use

1. In step 2 pick an ROI or MultiROI and choose the mode and connectivity.

2. In step 3 confirm the voxel size (leave resampling on for anisotropic data).

3. In step 4 click Load mask and sanity-check the shape and foreground count.

4. In step 4 click Run analysis.

5. In step 5 read the characteristic radius and check the warnings and stop reason.

6. For per-label numbers run the batch from step 4; publish or export in step 6.

7. Parameters

8. Output

9. FAQ & troubleshooting

• "the peak is at the first erosion step" — the structure is at or below the voxel size, so the number is a lower bound. Acquire at a higher resolution.
• "the iteration limit was reached" — the structure is larger than 64 steps. Raise Max iterations in step 3.
• Spacing mode says no ridge was found between objects — the mask has a single component, or the objects touch. Spacing needs at least two separate objects.
• Publish peak-state ROI fails — this Dragonfly build does not expose an ROI-from-array factory to Python. Export instead, or publish the half-thickness Channel.
• The result is off by an order of magnitude — check the spacing shown in step 2. If the object carries no geometry, set the voxel size by hand in step 3.

10. Notes & known limitations

• Spacing is measured at each object pair's closest approach. An earlier implementation took values along the whole background ridge, which open space inflated; only the minimum along each pair's ridge is used now.
• Spacing mode ignores background regions that touch the volume border, because empty space outside the sample is not a spacing between structures.
• Components are labelled with scipy.ndimage (BSD). The faster connected-components-3d is LGPL and this plugin ships as sourceless bytecode inside a commercial package, so it is deliberately not used.
• The input must be a published ROI or MultiROI; unpublished objects do not appear in the pickers.
• The whole volume is read into memory. Crop very large volumes to the region of interest first.

11. References

Morphological granulometry: G. Matheron, Random Sets and Integral Geometry, Wiley, 1975. Local thickness and the distance transform: T. Hildebrand & P. Rüegsegger, "A new method for the model-independent assessment of thickness in three-dimensional images", Journal of Microscopy 185(1), 1997.