Centerline and Length (v2)（中心线与长度）

Centerline and Length (v2) - User Manual

Dragonfly Prototype Apps · Centerline and Length (v2)...

版本 Version 1.0 · 2026-09-22

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

从一个已发布的 Multi-ROI 出发，对每个非零 label 分别提取中心线、测量其实际长度，并把长度作为一个新的逐标签 scalar slot 写回该 Multi-ROI。五个标签页就是完整流程：Input → Centerline → Smooth → Length measurement → Report。

与直接对骨架折线求和不同，本插件在测量之前先判定每个标签的形状：开放曲线和带分枝的骨架沿加权测地距离最长的路径测量；闭合环按环测量周长；壳体或薄片没有中心线，直接拒绝并说明原因。

数字骨架是阶梯状的，直接求和会使长度偏大。实测：缓斜直线 +9.0%，三维斜线 +10.5%，5:1 各向异性数据 +21.7%。Smooth 页就是用来消除这一偏差的；使用默认参数时，同样的模型误差都在约 1% 以内。

2. 适用场景

• 血管、纤维、通道、裂缝等细长弯曲对象的逐标签长度统计。
• 原始体素骨架存在明显锯齿，或数据在 Z 方向间距明显更大（各向异性）的情况。
• 需要把长度写回 Multi-ROI 以便后续按长度着色、筛选或导出的场合。
• 需要一次性处理成百上千个标签：实测 120×300×300 体积、300 个标签共 0.32 秒（每标签约 1.1 毫秒），读取 Multi-ROI 本身才是耗时大头。

不适用于实心块体、壳体或薄片。这类标签没有有意义的“长度”，插件会分别以 not elongated 提示或直接拒绝，而不会给出一个看起来合理的错误数字。

3. 安装与启用

1. 运行 Prototype Apps 安装程序（Full Package / App Store 安装包）。

2. 在插件列表中勾选 Centerline and Length (v2)。

3. 完成安装后完全重启 Dragonfly（菜单在启动时构建，不重启看不到新条目）。

4. 在菜单 Prototype Apps ▸ Measurements & Analysis ▸ Centerline and Length (v2)... 中打开。

如需临时隐藏该条目，可使用 Menu Item Manager；禁用只是不显示菜单，不会删除已安装的代码目录。

4. 运行环境与首次配置

本插件为 in_process 类型：没有任何首次配置步骤，不需要创建虚拟环境、不需要下载模型、不需要联网、不需要 GPU，也不需要管理员权限。

它只使用 Dragonfly 自带的 PyQt6、NumPy、SciPy 与 scikit-image。已在 Dragonfly 2025.1（Python 3.10.13 / scikit-image 0.19.3）与 2027.1（Python 3.14.3 / scikit-image 0.25.2）上验证，结果逐位一致。

生成的 HTML 报告是本地自包含文件，不会上传到任何服务器。

5. 界面说明

1 Input（输入）

选择一个已发布的 MultiROI 与 Time step，点击 Read input 读取。Optional steps 组用于配置一键执行：Include smoothing、Include report 默认勾选，Publish extracted centerlines、Publish smoothed centerlines 默认不勾选。Execute all steps with current settings 按当前设置依次执行全部步骤。

2 Centerline（中心线）

设置 Minimum label size (voxels) 后点击 Extract centerlines。可用 Publish centerlines 把结果发布为带 Label ID 标量的 Dragonfly Graph。

3 Smooth（平滑，可选）

Iterations、Smoothing factor、Resampling step (voxels) 三个参数控制平滑强度，点击 Smooth centerlines 执行。此步骤可以完全跳过。

4 Length measurement（长度测量）

Measure from 选择测量来源（原始或平滑中心线），Scalar slot name 指定写回的槽名。Measure lengths 填表，Write as new MultiROI scalar slot 写回 Multi-ROI。表格除长度外还给出 Shape、Discarded、Length / diameter、Warnings 四列，把鼠标停在某一行上会显示针对该标签的具体说明。

5 Report（报告，可选）

选择输出路径后点击 Generate report，生成一个自包含的本地 HTML 文件。

6. 使用步骤

1. 在 1 Input 页选择 Multi-ROI 与时间点，点击 Read input。

2. 在 2 Centerline 页设置最小标签体素数，点击 Extract centerlines；查看日志中被跳过的标签及原因。

3. （可选）在 3 Smooth 页点击 Smooth centerlines，消除骨架的阶梯偏差。

4. 在 4 Length measurement 页选择测量来源，点击 Measure lengths，检查表格中的 Shape 与 Warnings 两列。

5. 点击 Write as new MultiROI scalar slot 把长度写回 Multi-ROI。

6. （可选）在 5 Report 页生成 HTML 报告。

上述全部步骤也可以在 1 Input 页用 Execute all steps with current settings 一次完成；Smooth 与 Report 是否参与由该页的两个复选框决定。

7. 参数说明

迭代次数或系数过大会继续缩短路径，超出“仅消除阶梯效应”的范围。建议对比表格中的 Raw length 与 Measured length 两列以及 Reduction 百分比：合理的平滑通常使长度下降 1%–10%，而不是几十个百分点。

8. 输出结果

• Multi-ROI 上的新 scalar slot：逐标签长度，单位为米，带长度量纲，可直接用于按长度着色或筛选。
• 长度表格：Label、Name、Voxels、Points、Raw length、Measured length、Reduction、Shape、Discarded、Length / diameter、Warnings。
• Dragonfly Graph（可选）：原始与平滑中心线各一条，携带 Label ID 标量，可在三维视图中直接查看。
• HTML 报告（可选）：自包含单文件，含完整表格、运行参数、被跳过的标签以及本次实际出现的提示的含义说明。

9. 常见问题与故障排除

某个标签被跳过了。 打开日志：跳过原因会按类别列出（体素数过少、空标签、没有可测量的路径、属于壳体或薄片）。报告的 Skipped 一节也会重复这些信息。

长度明显偏大。 说明没有执行平滑，或平滑强度不足。请执行 3 Smooth 页，并观察 Reduction 百分比。

长度明显偏小。 查看 blunt ends 提示与 End radius：在平齐端面处骨架会比实体短约一个局部半径（实测半径 2 时短 1 个体素，半径 6 时短 7 个）。该值不会被自动加到长度上，因为端面形状无法从掩模判断。

结果被标为 not elongated。 该标签的长度与等效球直径之比小于 1，说明它不是细长物体，对它测量中心线长度没有意义。

出现 symmetry fallback 提示。 该标签关于体素边界完全对称（例如截面恰为 4×4 的方柱，或圆心落在体素边界上的圆柱），细化算法会把它整体删除。插件对其做一次单体素膨胀后重新测量，因此结果可能有约一个体素的偏差。

菜单里找不到该插件。 Dragonfly 在启动时构建菜单，安装或启用之后必须完全重启。

10. 注意事项与已知限制

• 只测量第 0 个时间点。含多个时间点的 Multi-ROI 会在日志与报告中明确报出被忽略的时间点数量。
• 带分枝的标签只报告主干长度，侧枝被排除，排除比例见 Discarded 列——这是定义，不是误差。
• 含环路的网络无法用单一长度描述。插件仍会给出最长路径，但同时标出 contains a loop。
• 端部缺失不会被自动补偿（见常见问题）。
• 平滑是可选的，但对弯曲对象强烈建议开启；轴向或恰好 45° 的直线本身没有偏差，平滑对其完全没有影响。
• 本插件不会修改原 Multi-ROI 的标签本身，只追加一个 scalar slot。

11. 参考资料

• T. C. Lee, R. L. Kashyap, C. N. Chu, Building skeleton models via 3-D medial surface/axis thinning algorithms, CVGIP: Graphical Models and Image Processing, 56(6):462–478, 1994 —— skimage.morphology.skeletonize(method="lee") 所实现的算法。
• scikit-image、SciPy（scipy.ndimage、scipy.sparse.csgraph）官方文档。
• 插件仓库内的 DESIGN.md：记录了本文所引用的全部实测数据与设计取舍。

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

Starting from one published Multi-ROI, extracts a centerline for every non-zero label, measures its real length, and appends that length to the same Multi-ROI as a new per-label scalar slot. The five tabs are the workflow: Input → Centerline → Smooth → Length measurement → Report.

Unlike simply summing a skeleton polyline, this plugin classifies the shape of each label before measuring it: an open curve and a branched skeleton are measured along the longest weighted geodesic path; a closed ring is measured as a ring; a shell or plate has no centerline and is refused with a stated reason.

A digital skeleton staircases, so summing it directly reports a length that is too large. Measured: +9.0% on a shallow line, +10.5% on a 3-D diagonal, +21.7% at 5:1 anisotropy. The Smooth tab removes exactly that; at the default settings the same phantoms all measure to within roughly 1%.

2. Use cases

• Per-label length of slender, curved objects: vessels, fibres, channels, cracks.
• Data whose voxel skeleton is visibly jagged, or whose Z spacing is much larger than X and Y (anisotropic).
• Workflows that need the length written back onto the Multi-ROI so labels can be coloured, filtered or exported by length.
• Hundreds of labels at once: measured 0.32 s in total for 300 labels in a 120×300×300 volume (about 1.1 ms per label). Reading the Multi-ROI out of Dragonfly dominates the run.

Not suitable for solid blobs, shells or plates. Such labels have no meaningful length, and the plugin flags them not elongated or refuses them outright rather than printing a plausible wrong number.

3. Installation & enabling

1. Run the Prototype Apps installer (Full Package / App Store package).

2. Tick Centerline and Length (v2) in the plugin list.

3. Restart Dragonfly completely — menus are built at startup, so a new entry does not appear until then.

4. Open it from Prototype Apps ▸ Measurements & Analysis ▸ Centerline and Length (v2)...

Use the Menu Item Manager to hide the entry temporarily. Disabling only hides the menu; it does not remove the installed code directory.

4. Runtime environment & first-run setup

This is an in_process plugin: there is no first-run setup at all. No virtual environment, no model download, no internet, no GPU and no administrator access.

It uses only the PyQt6, NumPy, SciPy and scikit-image bundled with Dragonfly. It is verified on Dragonfly 2025.1 (Python 3.10.13 / scikit-image 0.19.3) and 2027.1 (Python 3.14.3 / scikit-image 0.25.2), with bit-identical results.

The HTML report is a self-contained local file. Nothing is uploaded anywhere.

5. Interface

1 Input

Pick a published MultiROI and a Time step, then Read input. The Optional steps group configures the one-button run: Include smoothing and Include report are ticked by default, Publish extracted centerlines and Publish smoothed centerlines are not. Execute all steps with current settings runs the whole pipeline.

2 Centerline

Set Minimum label size (voxels) and press Extract centerlines. Publish centerlines publishes the result as a Dragonfly Graph carrying a Label ID scalar.

3 Smooth (optional)

Iterations, Smoothing factor and Resampling step (voxels) control the strength; press Smooth centerlines. This step can be skipped entirely.

4 Length measurement

Measure from selects raw or smoothed centerlines and Scalar slot name names the slot. Measure lengths fills the table and Write as new MultiROI scalar slot writes it back. Beside the lengths the table gives Shape, Discarded, Length / diameter and Warnings; hovering a row explains what each warning costs for that label.

5 Report (optional)

Choose an output path and press Generate report to write a self-contained local HTML file.

6. How to use

1. On 1 Input, choose the Multi-ROI and time step, then Read input.

2. On 2 Centerline, set the minimum label size and press Extract centerlines; read the log for labels that were skipped and why.

3. (Optional) On 3 Smooth, press Smooth centerlines to remove the staircase bias.

4. On 4 Length measurement, choose the source and press Measure lengths; check the Shape and Warnings columns.

5. Press Write as new MultiROI scalar slot to store the lengths on the Multi-ROI.

6. (Optional) On 5 Report, generate the HTML report.

All of the above can be done in one click with Execute all steps with current settings on 1 Input; the two checkboxes there decide whether Smooth and Report take part.

7. Parameters

Too many iterations, or too large a factor, keep shortening the path past the point where only the staircase is being removed. Compare Raw length with Measured length and read Reduction: sensible smoothing takes 1%–10% off, not tens of percent.

8. Output

• A new scalar slot on the Multi-ROI: per-label length in metres, carrying a length dimension, usable directly for colouring or filtering by length.
• The lengths table: Label, Name, Voxels, Points, Raw length, Measured length, Reduction, Shape, Discarded, Length / diameter, Warnings.
• Dragonfly Graphs (optional): raw and smoothed centerlines, each carrying a Label ID scalar, viewable in the 3-D scene.
• An HTML report (optional): one self-contained file with the full table, the run settings, the skipped labels, and a legend for exactly those warnings that actually occurred.

9. FAQ & troubleshooting

A label was skipped. Read the log: the reasons are grouped (too few voxels, empty label, no measurable path, shell or plate). The Skipped section of the report repeats them.

The length looks too large. Smoothing was not run, or was too weak. Run the 3 Smooth tab and watch the Reduction percentage.

The length looks too small. Look for the blunt ends warning and the End radius column: at a flat end the skeleton stops short by roughly the local radius (measured: 1 voxel at r=2, 7 voxels at r=6). It is not added to the length, because the cap shape that would decide the true figure cannot be known from the mask.

A result is flagged not elongated. That label's length divided by its equivalent sphere diameter is below 1, so it is not a slender object and a centerline length is not meaningful for it.

A result is flagged symmetry fallback. That label is perfectly symmetric about a voxel boundary (for example a prism of exactly 4×4 cross-section, or a cylinder centred on a voxel boundary), and thinning deletes such a body entirely. The plugin re-measures it after a one-voxel dilation, so expect about one voxel of deviation.

The plugin is not in the menu. Dragonfly builds its menus at startup; restart it completely after installing or enabling.

10. Notes & known limitations

• Only time step 0 is measured. A Multi-ROI with more time steps reports how many were ignored, in the log and in the report.
• A branched label reports its trunk only. Side branches are excluded and the excluded fraction is in the Discarded column — that is the definition, not an error.
• A network with loops cannot be described by one length. The longest path is still given, flagged contains a loop.
• End shortening is never compensated automatically (see the FAQ).
• Smoothing is optional but strongly recommended for curved objects. An axis-aligned or exactly-45° line is unbiased to begin with, and smoothing leaves it completely unchanged.
• The plugin never modifies the labels of the source Multi-ROI; it only appends a scalar slot.

11. References

• T. C. Lee, R. L. Kashyap, C. N. Chu, Building skeleton models via 3-D medial surface/axis thinning algorithms, CVGIP: Graphical Models and Image Processing, 56(6):462–478, 1994 — the algorithm behind skimage.morphology.skeletonize(method="lee").
• scikit-image and SciPy documentation (scipy.ndimage, scipy.sparse.csgraph).
• DESIGN.md in the plugin repository: every measurement quoted in this manual, with the phantom it was taken from.