Measure distances between shapes（测量形状之间的距离）
Measure distances between shapes - User Manual
Dragonfly Prototype Apps · Measure distances between shapes...
版本 Version 1.0 · 2026-08-06
第一部分 中文手册
目录
1. 简介
2. 适用场景
3. 安装与启用
4. 使用方法
5. 两种距离的含义，以及各形状的支持情况
6. 数据是怎么得来的
7. 限制
1. 简介
测量本会话中两个已发布的标注/形状对象之间的距离。只有一个标签页：选择对象 A、选择对象 B，选「中心到中心」或「边缘到边缘」，点「测量」。
结果同时以米和微米给出。Dragonfly 的几何数据按 SI 存储，CT 尺度的长度用米表示约为 1e-5 —— 正确但不可读；而只给微米又会隐藏数据本来的单位来源。
不创建、不修改任何对象。 本插件只读取你选择的那两个对象。
2. 适用场景
两个圆形标注中心之间的间距 —— 例如孔位、标记点、参考圆。
两个已画区域之间的最小间隙 —— 按边缘而不是按中心测量。
4D 数据里按时间步分别测量：读取几何所用的时间步可在面板上指定。
需要把测量结果连同「用的是哪种算法」一并记录的场合 —— 详细信息区会为每个结果写明所用公式。
3. 安装与启用
1. 打开 Prototype Apps ▸ App Store，在 Measurements & Analysis 分组里找到 Measure distances between shapes 并启用。
2. 重启 Dragonfly。插件在启动时被发现，因此必须重启。
3. 菜单项为 Prototype Apps ▸ Measure distances between shapes...
4. 无需其它准备：不需要虚拟环境、不需要下载、不需要联网、不需要 GPU。
4. 使用方法
1. 先创建或打开要测量的两个标注，使它们已发布到会话中（在数据属性树里可见）。
2. 打开插件。两个下拉框会列出找到的全部标注，标签包含标题、类名与形状类型，例如 Circle A [VisualRegion, circle]。
3. 如果面板已打开后才新建标注，点「刷新列表」。
4. 选择对象 A 与对象 B，选择距离类型，若为 4D 数据则设置「时间步」，然后点「测量」。
5. 在「结果」框顶部读取距离，下面一行是本次使用的计算方式；「详细信息」框内是两个对象的完整几何信息。
⚠ 两个下拉框不能选同一个对象。选中同一对象两次会被提示拒绝，而不是返回 0。
5. 两种距离的含义，以及各形状的支持情况
自 2026-08-06 起，两个选择器同时列出标注和视觉形状（VisualSphere、VisualBox、VisualCylinder、VisualRectangle、VisualPlane），并在标签里标出几何类型，例如 Sphere1 [VisualSphere, sphere]。因为 Shape3D.getCenter() 在基类上，中心到中心对任意组合都有效，包括「一个标注对一个球」。
「中心到中心」—— 两个质心之间的直线距离。它支持全部标注类型：VisualRegion、VisualPath、VisualPoints、VisualRuler、VisualArrow、VisualAngle、VisualLabel。之所以不需要按类型分别处理，是因为质心由 Annotation 基类本身提供。
「边缘到边缘，圆–圆」—— 两个圆心之间的距离减去两个半径。两圆重叠时结果为负数，且该负号被保留而不是夹到 0，因为重叠的深度本身就是有用信息。
「边缘到边缘，轮廓类形状」—— 对矩形、多边形、自由形区域、路径、点集与标尺，按各自控制点构成的轮廓逐段求最近距离。矩形、多边形与自由形轮廓按闭合处理，因此最后一个控制点回到第一个控制点的那条边也参与计算。
⚠ 暂不支持、且会明确拒绝而不给近似值的组合：椭圆（其边缘距离需要在标注平面内对轮廓采样），以及圆与轮廓类形状配对。这两种情况下窗口不显示任何数字，并写明原因。对本插件而言，给出一个看似合理但错误的测量值是最糟的结果，所以这些组合会明确失败。对同样这些对象，「中心到中心」仍然可用。
配对 | 中心到中心 | 边缘到边缘（最小距离） |
球 ↔ 球 | 支持 | 精确解析式：中心距减去两个半径，重叠时保留负号 |
球 ↔ 盒（有向） | 支持 | 精确解析式：变换进盒坐标系后逐轴 clamp |
球 ↔ 圆柱（有限带盖） | 支持 | 精确解析式：径向/轴向分解，含盖沿情形 |
球 ↔ 矩形 | 支持 | 精确解析式：在矩形平面内 clamp |
盒 ↔ 盒、盒 ↔ 圆柱、圆柱 ↔ 圆柱、矩形 ↔ 任意 | 支持 | GJK（支撑函数）。凸体的最小距离会收敛到真值；括号无法收紧时按可显示精度判定，达不到就拒绝出数 |
标注 ↔ 视觉形状 | 支持 | 拒绝：标注没有平面朝向，无法在三维中与实体对置 |
任意 ↔ VisualPlane | 拒绝 | 拒绝：无界裁剪平面没有中心也没有可测边界 |
⚠ 本插件的原则是：给出一个看起来合理但错误的距离，是最坏的结果。凡是无法精确回答的配对都会被拒绝并说明原因，而不是给一个近似值；结果区还会写出所用的计算路线，便于核对。
6. 数据是怎么得来的
全部数据来自 Dragonfly 自己的对象模型，且只使用安装目录自带类型声明中写明的方法签名 —— 标注上的 getCentroid、getControlPointCount、getControlPointPositionAtIndex，以及区域对象上的 getShape、getArea、getPerimeter、getDirection0Size、getDirection1Size。
圆的半径由其报告的面积反解：r = √(A / π)。这里故意不取 getDirection0Size —— 因为 Dragonfly 的类型声明并未说明方向尺寸是半径还是直径，猜错会让每一个边缘距离都差 2 倍。方向尺寸仍会被读取，并与面积反解出的半径比对，插件把实测判定出的约定（直径还是半径）打印在「详细信息」框里，让这个前提可见而不是隐藏。
对象模型里没有「圆」这个类：圆形标注是一个形状类型为 circle 的区域对象。面板标签之所以显示形状类型，正是为此 —— 让你在测量之前就看清测的是什么。
如果某个属性无法从对象读出，只会损失那一个属性 —— 插件随后判断还能诚实测出什么，而不是用默认值顶上。
7. 限制
列表中只包含标注对象。ROI、MultiROI、网格与图像通道不在其列，因为它们之间的距离属于另一类计算。
轮廓类的边缘距离以控制点作为轮廓。对于自由形轮廓，这就是 Dragonfly 存储的轮廓；但如果某种形状的控制点只是操作手柄而不是边界，结果就没有意义 —— 这正是圆永远不走这条路径的原因。
距离在三维世界坐标下测量。因此画在不同切片上的两个标注，其距离还包含切片间距 —— 这是正确的，但如果你按二维思考可能会觉得意外。
Part II English Manual
Contents
1. Introduction
2. Use cases
3. Installation & enabling
4. Using it
5. What each distance means, and which shapes support it
6. How the numbers are obtained
7. Limitations
1. Introduction
Measures the distance between two annotation or shape objects that are published in the current session. One tab: pick Object A, pick Object B, choose Center to center or Edge to edge, press Measure.
The answer is shown in both metres and micrometres, because Dragonfly stores geometry in SI and a CT-scale length in metres is around 1e-5 — correct but unreadable — while micrometres alone hide the provenance.
Nothing is created or modified. The plugin only reads the two objects you select.
2. Use cases
The spacing between the centres of two circle annotations — hole positions, fiducial marks, reference circles.
The smallest gap between two drawn regions, measured edge to edge rather than centre to centre.
Per-time-step measurement in 4D data: the time step used to read the geometry is set in the panel.
Any case where the measurement has to be recorded together with the method that produced it — the details pane names the formula for every result.
3. Installation & enabling
1. Open Prototype Apps ▸ App Store, find Measure distances between shapes in the Measurements & Analysis group, and enable it.
2. Restart Dragonfly. Plugins are discovered at startup, so a restart is required.
3. The item appears as Prototype Apps ▸ Measure distances between shapes...
4. No further setup: no venv, no download, no internet, no GPU.
4. Using it
1. Create or open the two annotations you want to measure, so that they are PUBLISHED in the session and visible in the data properties tree.
2. Open the plugin. Both drop-downs list every annotation found, labelled with its title, its class and its shape type — for example Circle A [VisualRegion, circle].
3. If you create an annotation while the panel is open, press Refresh the list.
4. Pick Object A and Object B, choose the distance type, set the Time step if the data is 4D, and press Measure.
5. Read the result at the top of the Result box and the method used underneath it; the Details box holds the full geometry of both objects.
⚠ The two drop-downs must not be on the same object. Selecting one object twice is rejected with a message rather than returning zero.
5. What each distance means, and which shapes support it
Since 2026-08-06 both pickers list annotations and visual shapes in one flat list (VisualSphere, VisualBox, VisualCylinder, VisualRectangle, VisualPlane), labelled with the geometry kind, e.g. Sphere1 [VisualSphere, sphere]. Because Shape3D.getCenter() is on the base class, centre-to-centre works for ANY combination, including an annotation measured against a sphere.
Center to center — the straight-line distance between the two centroids. This works for every annotation type: VisualRegion, VisualPath, VisualPoints, VisualRuler, VisualArrow, VisualAngle and VisualLabel. It needs no per-type special casing because the centroid is provided by the Annotation base class itself.
Edge to edge, circle to circle — the distance between the two centres minus the two radii. When the circles overlap the result is negative, and the sign is kept rather than clamped to zero, because the depth of the overlap is useful information.
Edge to edge, outline shapes — for rectangles, polygons, freeform regions, paths, point sets and rulers, the closest approach between the two outlines, computed segment against segment over their control points. A rectangle, polygon or freeform outline is treated as CLOSED, so the edge joining the last control point back to the first is included.
⚠ Not yet supported, and refused rather than approximated: an ellipse (its edge distance needs the outline sampled in the annotation plane), and a circle paired with an outline shape. In both cases the window shows no number and states the reason. A plausible but wrong measurement would be the worst thing this plugin could produce, so these combinations fail loudly. Center to center still works for those same pairs.
Pair | Centre to centre | Edge to edge (minimum) |
sphere ↔ sphere | yes | exact: centre distance minus both radii, signed on overlap |
sphere ↔ box (oriented) | yes | exact: into the box frame, clamped per axis |
sphere ↔ cylinder (finite, capped) | yes | exact: axial/radial split, cap rim included |
sphere ↔ rectangle | yes | exact: clamped in the patch plane |
box ↔ box, box ↔ cylinder, cylinder ↔ cylinder, rectangle ↔ anything | yes | GJK over support functions. Converges to the true minimum for convex bodies; when the bracket cannot be closed the answer is kept only if its resolution beats what is displayed, otherwise refused |
annotation ↔ visual shape | yes | refused: an annotation has no plane orientation, so its outline cannot be placed against a solid in 3-D |
anything ↔ VisualPlane | refused | refused: an unbounded clipping plane has neither a centre nor a measurable edge |
⚠ The rule this plugin follows: a plausible wrong distance is the worst possible outcome. A pair that cannot be answered exactly is refused with the reason stated rather than approximated, and the window always names the route it took so the number can be checked.
6. How the numbers are obtained
Everything comes from Dragonfly's own object model, using only the method signatures declared in the installation's own type stub — getCentroid, getControlPointCount, getControlPointPositionAtIndex on the annotation, and getShape, getArea, getPerimeter, getDirection0Size, getDirection1Size on a region.
A circle's radius is derived from its reported area: r = sqrt(A / pi). It is deliberately NOT taken from getDirection0Size, because Dragonfly's type declarations do not state whether a direction size is a radius or a diameter, and guessing would put a factor of two into every edge distance. The direction size is still read and compared against the area-derived radius, and the convention the plugin measures — diameter or radius — is printed in the Details box, so the assumption is visible instead of hidden.
There is no circle class in the object model: a circle annotation is a region whose shape type is circle. The panel's labels show the shape type for exactly this reason, so you can see what you are about to measure.
If one property cannot be read from an object, only that property is lost — the plugin then decides what can still be measured honestly, rather than substituting a default.
7. Limitations
Only annotations are listed. ROIs, MultiROIs, meshes and channels are not offered, because their distances are a different computation.
Edge to edge over an outline uses the control points as the outline. For a smooth freeform contour that is the contour Dragonfly stores, but for a shape whose control points are handles rather than a boundary the result would be meaningless — which is why a circle never takes that route.
Distances are measured in 3-D world coordinates. Two annotations drawn on different slices are therefore separated by the slice distance as well, which is correct but may be unexpected if you were thinking in 2-D.