In-range fraction in the current view（当前视图中范围内体素的占比，实时）

In-range fraction in the current view (live) - User Manual

Dragonfly Prototype Apps · In-range fraction in the current view (live)...

版本 Version 1.1 · 2026-08-10

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 使用步骤

5. 两个数字，以及它们为什么不同

6. 怎么读结果，以及视图上的读数

7. 另外两种模式

8. 速度与开销

9. 哪些情况会拒绝给出数字，以及为什么

10. 数字是怎么得到的

11. 限制

1. 简介

Dragonfly 的「Define range」（ROI Tools / ROI Painter 面板）会用红色标出强度落在指定范围内的体素，但不会告诉你这片红色占当前视图多大比例。本插件就是把这个比例实时算出来 —— 滚动切片、缩放、平移时数字一直跟着更新。

范围是从 Dragonfly 里读出来的，不需要你重新输入一遍。插件向该通道的 visual 询问 getRangeSelectionEnabledForView(view) 与 get2DWindowLevel2Min/MaxForView(view) —— 这正是 Dragonfly 自己在视图上显示 Selection Min/Max 时使用的同样三个访问器 —— 所以你得到的比例，分子就是那些被涂成红色的体素。

结果永远同时给出两个占比，并各自写明分母，因为一旦缩放它们就会不同，而单独一个不加说明的数字是没法读的。每个百分比旁边都附上计数。

不创建、不修改任何对象。 插件只读取。画在视图上的文字是临时项、不会写入保存的会话，关闭面板时自动移除。

2. 适用场景

定阈值：拖动 Define range 的滑块，同时看着它选中了视图的多大比例，而不是靠肉眼判断红色面积。

比较切片位置：在切片间滚动，观察整张切片的占比如何变化。

放大工作时：读「可见视口」那一行，只统计屏幕上看得见的部分。

已有 ROI：逐切片读出它的面积占比，不必先建测量表。

展示结果：把读数留在视图上直接截图 —— 数字和「它是谁的比例」都在同一张图里。

3. 安装与启用

1. 打开 Prototype Apps > App Store，在 Measurements & Analysis 分组里找到 In-range fraction in the current view (live) 并启用。

2. 重启 Dragonfly。插件是在启动时被发现的，仅重新打开窗口不够。

3. 菜单项位置：Prototype Apps > In-range fraction in the current view (live)...

4. 使用步骤

1. 载入数据，并在某个 2D 视图（XY / XZ / YZ）里点击一下。3D 视图没有切片，会被明确拒绝并说明原因。

2. 打开 Dragonfly 的 ROI Tools 面板，勾选 Define range 并设定范围，视图上会出现红色预览。

3. 打开本插件，点「开始」。两个占比会同时出现在面板和视图上。

4. 「结果」最上面那个大字百分比就是答案：可见视口中被标记的体素所占的比例，旁边直接写明它是谁的比例。计数与整张切片的数字在下方给出。

5. 滚动、缩放、平移 —— 数字随之更新；拖动 Define range 的滑块，数字同样跟着变。

6. 如果只想在面板里看数字，取消勾选「在视图上显示」；点「停止」可关闭实时循环。

⚠ 读数跟随的是当前视图，也就是你最后点击过的那一个。点进另一个 2D 视图，测量（以及视图上的文字）就会转移过去。

5. 两个数字，以及它们为什么不同

可见视口 —— 视图矩形中确实承载图像数据的那些像素。这个矩形就是你看到的画面，它的网格是屏幕像素网格：缩小时一个屏幕像素覆盖多个体素，所以这是「画出来的东西」的比例。该行会写明比率，例如 1 view px = 2.00 voxels，并在比率大于 1 时标注为抽样。

整张当前切片 —— 视图下方那一张切片的全部体素，按数据体素间距统计。这是「体素」的比例，与缩放平移无关，也是两者中定义更明确的一个。

在轴对齐视图里完全缩小时，两个数字接近一致；放大到致密区域，视口的数字更高；放大到空白区域，则更低。它们是对两个不同问题的正确回答，所以两个都始终显示。

视图矩形中落在体积之外的像素（缩小或斜切视角时必然出现）会从分母里剔除，并单独报出数量（1,600 px outside the data）。这些像素无法靠数值判断：0 是一个普通的体素值，而且它就在以 0 起始的范围之内。

某个区域里完全没有数据像素时显示 n/a，而不是 0.00%。「视图里什么都没有」和「视图里没有落在范围内的体素」是两件不同的事。

6. 怎么读结果，以及视图上的读数

「结果」分组最上方只用大字给出一个数字：可见视口中被标记的体素占比，后面紧跟着「of the visible viewport（可见视口的占比）」，因此绝不会被误读成其他东西。如果关掉了可见视口这一区域，它会改成整张切片的占比，并写明这一点。某个区域完全没有数据像素时显示 n/a，而不是 0.00%。

面板里的每一个颜色都是从 Dragonfly 自身主题推导出来的，所以无论当前是哪套主题，文字与背景都有足够对比度。这不是“好看”的问题：首版把数字写成了固定的深藏青，在 Dragonfly 的深色面板灰上实测只有 1.03:1，这就是结果看不清的原因。现在插件自带的测试会逐个测量这些颜色，低于 WCAG 对正文要求的 4.5:1 就直接失败。

画在视图上的读数

同一个数字也会画到视图上，默认在右侧、用橘黄色（#FF9F1C）显示。默认只把可见视口的数字画上去 —— 百分比、计数，以及它是谁的比例 —— 让画面保持可读；整张切片的数字留在面板里。把「视图上显示」改为「面板中的全部内容」，则两个区域都会画到视图上。

这个颜色同时也用于面板里的大字数字，但只在它在面板背景上实测可读时才会采用 —— 深色主题下选了一个偏深的橘色，面板会回退到主题自身的强调色，并在详细信息区写出实测对比度。一个可设置的颜色，不应该有能力把结果变回看不清。

为什么是橘黄色，以及为什么文字带阴影。 一张 CT 切片从黑到白，没有任何单一颜色能在全范围内都可读：遍历整个 RGB 空间，任何颜色对黑与对白同时能达到的最好结果也只有 4.58:1；而在中灰上，即使纯黑也只有 5.32:1。#FF9F1C 针对深色那一端优化 —— 也就是 CT 视图面积的绝大部分 —— 在黑色上 10.23:1，在 #404040 上 5.05:1；亮骨那一端则交给黑色文字阴影来护住，而不是靠色相。

⚠ 视图上的读数至今尚未被看到真正渲染出来。 Dragonfly 自身的源码说它应该能画：创建序列是从 config\defaulTextPresenter.py 抄下来的；而 Image Processing 的“Original” / “Preview” 标签证明了一个未被 Dragonfly 文字管理器接管的 VisualText 仍然会画出来。但还没有任何一个实际会话确认过本插件这一个，因此详细信息区会如实写明这一点，而不暗示它已经可用。面板里的数字不依赖它。

7. 另外两种模式

手动范围 —— 按 ROI Tools 面板显示的同一单位输入最小值与最大值。此时读数里会明确写着 「typed in this panel, NOT read from ROI Tools」（在此输入，并非读取 ROI Tools），所以截图绝不会被误认为是工具自身的范围。「用数据范围填充」会用数据集自身的最小/最大值填入这两个框。

所选 ROI —— 按同样的两个区域、同样的分母统计某个 ROI / MultiROI 的面积占比，因此它与范围模式的数字可以直接对比。可以从下拉框里选，也可以在对象列表里选中后点「使用当前选中的 ROI」。

8. 速度与开销

永远不会整卷读取。每次更新只在当前平面上重采样一张切片，所以一套 976 x 1013 x 989 的 USHORT 体数据（977,812,432 个体素，1865 MB）和一套小数据的代价相同：两张约一百万像素的切片。

在 Dragonfly 自带 Python 上、对 1013 x 976 的 uint16 切片实测：范围内计数 1.5 毫秒，加上有效性掩膜 2.0 毫秒，两个区域的完整面板更新约 10 毫秒，而「发现无变化」的心跳只需 0.02 毫秒。原生重采样的耗时是额外的，未包含在上述数字中。

正因如此，面板会显示自己实测的耗时 —— last update 8.5 ms change check 0.0 ms 11 updates 20 ticks did nothing —— 而不是许诺一个数字。在超大数据上你能看见某个间隔到底要花多少时间，不用猜。

「更新间隔」（100–5000 毫秒，默认 250）决定检查频率。大多数心跳其实什么都不做：先跑一次很便宜的变更检测，只有当影响结果的东西真的动了才去读切片。Dragonfly 自身的变更事件（切片滚动、相机移动、视图尺寸变化、范围上下限变化、范围开关、布局变化）会把读数标记为过期，再由定时器合并 —— 所以拖动视图时，每个间隔最多重算一次，而不是每次鼠标移动都算一次。

「抽样步长」用精度换速度：步长 2 表示两个轴都隔一个取一个，工作量降到四分之一。一旦大于 1，读数会标注 sampled, stride N，因为一个悄悄改变了定义的比例比一个慢一点的比例更糟。

关掉一个区域可以把工作量减半。只需要一个数字时，把另一个取消勾选。

9. 哪些情况会拒绝给出数字，以及为什么

以下每种情况都完全不显示数字 —— 由原因取代它的位置，这样过期的百分比就绝不会被当成新答案来读。

「歧义」这一条是刻意的。当视图中可见多个数据集时，Dragonfly 自己也拒绝判断范围属于哪一个；而选错通道会是这里最糟糕的结果 —— 所以插件请你只保留一个可见。

⚠ 本插件遵循的原则：一个看起来合理但错误的百分比，比不给百分比更糟。

10. 数字是怎么得到的

范围上下限读回来时是物理单位，而体素数组是原始值，两者关系是 physical = raw * slope + offset。插件用 (值 − offset) / slope 把上下限换算下来 —— 与 Dragonfly 自己的 ROI Tools 完全一致 —— 然后原始值对原始值比较。在未标定的数据上（slope 1、offset 0）两者相同，正因如此这一点必须写明，而不能想当然。

读数里显示的上下限是显示值，其换算方式与 Dragonfly 面板相同，因此与 ROI Tools 的数字框一致。面板的详细信息区会同时列出三种 —— 显示值、物理值、原始值 —— 以便核对换算。

对整数类型的数据，原始上下限会被收紧为整数（下限取 ceil，上限取 floor）。这是精确等价的，不是近似，并且避免了每次更新都把一百万像素的数组转成浮点。

切片本身来自 getSliceIntersectingBoundedPlane —— Dragonfly 自己的 Slice Analysis 用的就是这个调用 —— 写入一个临时 channel，用完立即销毁。有效性掩膜的构造方式也与 Slice Analysis 相同。

视图上的读数是 VisualText 项，每行一个，创建方式与 Dragonfly 自己做视图读数的方式一致（config\defaulTextPresenter.py）。字体取自 Dragonfly 的文字标注偏好设置，再乘上「文字大小」；「水平位置」把 setHorizontalAlignment 设为 2（右对齐，U 0.98）或 0（左对齐，U 0.01）—— 这是 Dragonfly 自身源码里明确注释过的两个值，也因此没有“居中”选项；「垂直位置」整体移动这一组文字；颜色是一个 ORS Color，其分量是 0–1 的浮点数，而不是 0–255 的字节。「从所有视图移除该文字」会清除本插件曾经留下的任何一项。

11. 限制

仅支持平面 2D 视图。3D 与 2D 非平面视图会被拒绝，而不是给出近似值。

红色预览本身的像素无法从渲染器读回 —— Dragonfly 的对象模型没有暴露它们。插件的做法是根据范围上下限重新计算同一个判断，因此得到的是同一批体素的比例，而不是画面颜色的比例。

4D 数据：提取的切片按时间步 0 读取，与 Dragonfly 自身的切片代码一致。若数据集有多个时间步，详细信息区会给出提示，说明 4D 情形未经验证。

一次只针对一个数据集。若有多个可见数据集都开着范围，结果会以「歧义」为由被拒绝。

Slab（厚层）视图：测量取在切片平面上，不会沿厚度方向累加。

画在视图上的读数还没有在实际会话中确认过能渲染出来。Dragonfly 自身的源码说它应该可以，详细信息区也如实声明了这份不确定性；面板里的数字不依赖它。

没有任何单一颜色能在一整张 CT 切片上都保持可读 —— 这是对比度本身的限制，不是本插件的问题。默认的橘黄色在深色组织与背景上最强，亮骨上则由黑色文字阴影来护住。

Part II English Manual

Contents

1. Introduction

2. Use cases

3. Installation & enabling

4. Using it

5. The two numbers, and why they differ

6. Reading the result, and the readout on the view

7. The other two modes

8. Speed, and what it costs

9. What it refuses to answer, and why

10. How the numbers are obtained

11. Limitations

1. Introduction

Dragonfly's Define range tool (ROI Tools / ROI Painter) shows in RED which voxels have an intensity inside the chosen range. It does not tell you what proportion of the view that red area is. This plugin does, live, while you scroll, zoom and pan.

The range is read out of Dragonfly, not retyped. The plugin asks the channel's visual for getRangeSelectionEnabledForView(view) and get2DWindowLevel2Min/MaxForView(view) -- the same three accessors Dragonfly's own on-canvas Selection Min/Max readout uses -- so the number you get is a fraction of exactly the voxels that are painted red.

Two fractions are always reported, each naming its own denominator, because they differ as soon as you zoom and one unlabelled number would be unreadable. Every percentage carries its counts beside it.

Nothing is created or modified. The plugin only reads. The text it paints on the view is a temporary, unsaved item that is removed when the panel closes.

2. Use cases

Choosing a threshold: drag the Define-range handles and watch what proportion of the view they select, instead of judging the red area by eye.

Comparing slice positions: scroll through the stack and read the whole-slice fraction change.

Working zoomed in: read the visible viewport line so only what is on screen is counted.

An existing ROI: read its area fraction slice by slice, without building a measurement table first.

Showing results: leave the readout on the view and take a screenshot -- the figure and what it is a fraction of are both in the picture.

3. Installation & enabling

1. Open Prototype Apps > App Store, find In-range fraction in the current view (live) under Measurements & Analysis, and enable it.

2. Restart Dragonfly. Plugins are discovered at startup, so reopening a window is not enough.

3. The entry appears as Prototype Apps > In-range fraction in the current view (live)...

4. Using it

1. Load a dataset and click inside a 2D view (XY / XZ / YZ). A 3D view has no slice and is refused with that reason.

2. Open Dragonfly's ROI Tools panel, tick Define range and set the range. The red preview appears on the view.

3. Open this plugin and press Start. The two fractions appear in the panel and on the view.

4. The big percentage at the top of Result is the answer: the proportion of the visible viewport that is marked, with what it is a proportion of spelled out beside it. The counts and the whole-slice figure follow underneath.

5. Scroll, zoom or pan -- the numbers follow. Move the Define-range handles and they follow that too.

6. Untick Show on the view if you only want the numbers in the panel; press Stop to switch the live loop off.

⚠ The readout follows the current view -- the one you last clicked in. Clicking into another 2D view moves the measurement (and the on-canvas text) there.

5. The two numbers, and why they differ

visible viewport -- the pixels of the view rectangle that actually carry image data. This rectangle is what you see, and its grid is the screen-pixel grid: when you zoom out, one screen pixel covers several voxels, so this is a fraction of what is drawn. The line states the ratio, for example 1 view px = 2.00 voxels, and marks itself sampled whenever it exceeds 1.

whole current slice -- every voxel of the slice under the view, at the data spacing. This is a fraction of the voxels, is independent of zoom and pan, and is the better-defined of the two.

Zoomed all the way out on an axis-aligned view the two nearly agree. Zoomed into a dense region the viewport number is higher; zoomed into empty space it is lower. Both are correct answers to different questions, which is why both are always shown.

Pixels of the view rectangle that fall outside the volume -- which happens whenever you zoom out or look obliquely -- are excluded from the denominator and their count is reported (1,600 px outside the data). They cannot be detected by value: 0 is an ordinary voxel value and it is inside a range that starts at 0.

A region with no data pixels at all reads n/a, not 0.00%. An empty view and a view with nothing in range are different facts.

6. Reading the result, and the readout on the view

The Result group leads with ONE number in large bold type: the percentage of the visible viewport that is marked, followed by the words of the visible viewport so it can never be read as something else. If the viewport region is switched off it becomes the whole-slice percentage and says so. A region with no data pixels reads n/a, not 0.00%.

Every colour in the panel is derived from Dragonfly's own theme, so the text contrasts with the background whichever theme is in force. This is not cosmetic: the first release hardcoded a dark navy that measured 1.03:1 against Dragonfly's dark panel grey, which is why the result was unreadable. The plugin's own test suite now measures every colour and fails the build below the 4.5:1 that WCAG asks for body text.

The readout drawn on the view

The same figure is painted on the view itself, on the right-hand side by default and in orange (#FF9F1C). Only the visible-viewport figure goes there -- its percentage, its counts and the quantity it is a fraction of -- so the canvas stays readable; the whole-slice figure stays in the panel. Switch On the view to Everything the panel shows to put both regions on the canvas instead.

The colour is also used for the panel's big number, but only when it measures readable against the panel background -- a dark orange on a dark theme falls back to the theme's own accent, and the details pane says so with the measured ratio. A settable colour must not be able to make the result unreadable again.

Why orange, and why the text has a shadow. A CT slice runs from black to white and no single colour is readable over all of it: sweeping the whole RGB cube, the best any colour achieves against black and white at once is 4.58:1, and over a mid-grey even pure black manages only 5.32:1. #FF9F1C is optimised for the dark end, where a CT view spends most of its area -- 10.23:1 on black, 5.05:1 on #404040 -- and the bright-bone case is carried by a black text shadow rather than by the hue.

⚠ The on-view readout has not yet been seen to render. Dragonfly's own source says it should: the creation sequence is copied from config\defaulTextPresenter.py, and Image Processing's "Original" / "Preview" labels prove that a VisualText which Dragonfly's text-presenter manager does not manage still draws. But no live session has confirmed THIS one, and the details pane says so rather than implying it works. The panel's own numbers do not depend on it.

7. The other two modes

Manual range -- type a minimum and a maximum in the same units the ROI Tools panel displays. The readout then says, in the readout itself, "typed in this panel, NOT read from ROI Tools", so a screenshot can never be mistaken for the tool's own range. Fill from the data seeds the two fields from the dataset's own minimum and maximum.

Selected ROI -- the area fraction of an ROI or MultiROI over the same two regions, with the same denominators, so the numbers are directly comparable with the range numbers. Pick one from the list, or select it in the object list and press Use the selected ROI.

8. Speed, and what it costs

The volume is never read whole. Each update resamples ONE slice on the current plane, so a 976 x 1013 x 989 USHORT volume (977,812,432 voxels, 1865 MB) costs the same as a small one: two slices of roughly a megapixel each.

Measured in Dragonfly's own Python on a 1013 x 976 uint16 slice: 1.5 ms to count in-range pixels, 2.0 ms with the validity mask, about 10 ms for a full two-region panel update, and 0.02 ms for a heartbeat that finds nothing changed. The native resample is additional and is not included in those figures.

That is why the panel prints its own measured cost -- last update 8.5 ms change check 0.0 ms 11 updates 20 ticks did nothing -- rather than promising a number. On a very large dataset you can see what an interval costs instead of guessing.

Interval (100-5000 ms, default 250) sets how often it checks. Most heartbeats do nothing: a cheap change check runs first, and the slices are only read when something that affects the answer has moved. Dragonfly's own change events (slice scrolled, camera moved, view resized, range bounds moved, range switched on or off, layout changed) mark the readout stale, and the timer coalesces them -- so dragging the view produces at most one recompute per interval rather than one per mouse move.

Subsample stride trades exactness for speed: stride 2 counts every second pixel on both axes, so a quarter of the work. Above 1 the readout says sampled, stride N, because a fraction that quietly changed definition would be worse than a slow one.

Switching a region off halves the work. If only one number is needed, untick the other.

9. What it refuses to answer, and why

In each of these cases no number is shown at all -- the reason takes its place, so a stale percentage can never be read as a fresh answer.

The ambiguous case is deliberate. Dragonfly itself declines to decide which dataset a range belongs to when more than one is visible in a view, and a confidently wrong channel would be the worst outcome available -- so the plugin asks you to hide all but one.

⚠ The rule this plugin follows: a plausible wrong percentage is worse than no percentage.

10. How the numbers are obtained

The range bounds come back in physical units while the voxel array is raw, related by physical = raw * slope + offset. The plugin converts the bounds down with (value - offset) / slope, exactly as Dragonfly's own ROI Tools does, and compares raw against raw. On an uncalibrated dataset (slope 1, offset 0) the two are the same, which is why this is stated rather than assumed.

The bounds shown in the readout are the displayed values, converted the same way Dragonfly's panel converts them, so they match the ROI Tools spinboxes. The panel's details pane lists all three -- shown, physical and raw -- so the conversion can be checked.

For an integer dataset the raw bounds are tightened to integers (ceil of the low bound, floor of the high one). That is exact, not an approximation, and it avoids converting a megapixel array to floating point on every update.

The slice itself comes from getSliceIntersectingBoundedPlane, the same call Dragonfly's Slice Analysis uses, into a temporary channel that is destroyed immediately afterwards. The validity mask is built the same way Slice Analysis builds it.

The readout on the view is a VisualText item, one per line, created the way Dragonfly creates its own view readouts (config\defaulTextPresenter.py). Its font comes from Dragonfly's text-annotation preferences and is then multiplied by Text size; Horizontal position sets setHorizontalAlignment to 2 (right, at U 0.98) or 0 (left, at U 0.01) -- the two values Dragonfly's own source documents, which is why there is no "centre"; Vertical position moves the whole block; and the colour is an ORS Color, whose components are 0-1 floats and not 0-255 bytes. Remove the readout from every view clears any item this plugin has ever left behind.

11. Limitations

Planar 2D views only. 3D and 2D non-planar views are refused rather than approximated.

The red preview's own pixels cannot be read back from the renderer -- nothing in Dragonfly's object model exposes them. The plugin recomputes the same test from the range bounds, which is why the answer is a fraction of the same voxels rather than of the drawn pixels' colour.

4D data: the extracted slice is read at time step 0, as Dragonfly's own slice code does. A dataset with more than one time step raises a note in the details pane saying the 4D case is not verified.

Only one dataset at a time. If several are visible with a range on, the answer is refused as ambiguous.

Slab views: the measurement is taken on the slice plane, not summed through the slab thickness.

The readout drawn on the view has not been confirmed to render in a live session. Dragonfly's own source says it should, and the details pane states the uncertainty; the panel's numbers do not depend on it.

No single on-canvas colour is readable over a whole CT slice -- that is a property of contrast, not of this plugin. The default orange is strongest over dark tissue and background, and a black text shadow carries it over bright bone.