OHIF Viewer 报告保存对话框深度解析:目标序列选择、序列命名与版本化机制

原创2026-09-18 11:30:231,333 阅读
文章标签:医疗健康前端图像处理PWA

OHIF Viewer 报告保存对话框深度解析:目标序列选择、序列命名与版本化机制

本文以 OHIF Viewer 行为文档 report-dialog-save-destinations.md 为主线,结合 extensions/default 与 extensions/cornerstone-dicom-seg 的实际源码与测试,完整剖析保存对话框(Report Dialog)的工作原理。你将掌握:Save to current / Save as new / Replace existing 三种保存目标的判定逻辑、predecessorImageId 与 PredecessorSequence 的底层机制、新序列的四种命名候选及其记忆历史、新序列编号的计算规则,以及如何通过 ohif.createReportDialog 自定义替换整个对话框。

一、概述:保存对话框解决什么问题

当用户需要把一次编辑的成果写回 DICOM 存储时,OHIF Viewer 会弹出一个报告保存对话框(Report Dialog)。它可以存储三类对象:

  • 分割(Segmentation,SEG)
  • 轮廓集(Contour Set / RTSTRUCT)
  • 测量报告(Measurement Report / SR)

对话框向用户提出两个核心问题:对象写入哪个序列(Series),以及这个序列叫什么名字。两者看似简单,背后却牵涉到版本化语义、前驱引用链与记忆历史三个设计维度。

该功能横跨多个模块,实现位置如下:

此外,配套的迁移指南 report-dialog.md 记录了 3.13 → 3.14 版本中该对话框从"单一下拉框"演进为"三种明确目标"的完整过程,可作为行为文档的延伸阅读。

二、核心语义:一次保存只存一个对象

在深入三个目标之前,必须先理解保存对话框的基础语义:

每次保存都把当前的全部数据作为一个对象写入目标序列,对话框不做任何合并。

这意味着:

  1. 保存进一个已有数据的序列时,不会先读取该序列的旧数据——旧对象不会与新对象融合;
  2. 当前数据也不会被遗漏任何一部分——保存的是服务中选定的全量数据(测量服务中的全部测量、分割服务中的全部分段);
  3. 目标序列决定了新对象取代哪一个旧实例——predecessorImageId 指向的实例被"继承"(supersede),旧实例仍然保留在序列中,但新实例成为该序列被默认加载的对象。

从源码看,reportDialogCustomization.tsx 中的 Destination 类型注释明确写道:三种目标存储的是同一个对象,对话框不合并任何内容("All three store the same object, and the dialog merges nothing")。

三、三种保存目标:Save to current / Save as new / Replace existing

3.1 三种目标一览

目标 对象去向 对话框何时提供该目标
Save to current 视口加载数据来源的那个序列 数据的 predecessorImageId 指向一个已加载的序列
Save as new 新建一个序列,编号与描述均可编辑 始终可用
Replace existing 用户选择的、同模态(modality)的其他已加载序列 视口还持有至少一个此类序列

默认选择规则:

  • 当 Save to current 可用时,它是默认选择;
  • 否则默认选择 Save as new;
  • Save to current 与 Replace existing 都保留目标序列原有的编号与描述,因此对话框对这两项只读展示、不允许用户编辑。

在 UI 上,这三个目标以分段控件(Segmented Control)的形式呈现在 Series 行上,控件下方有一行帮助文字,保存按钮上也重复了所选目标的措辞。源码中这三个目标的文案定义在 reportDialogCustomization.tsx 的 DESTINATIONS 数组中:

  • Save to current:帮助文字为 "Adds a new version to this series as the new default. Earlier versions are kept."(向该序列添加一个新版本作为新的默认对象,旧版本保留);不可用时提示 "This data has not been saved to a series yet"(这些数据尚未保存到任何序列)。
  • Save as new:帮助文字为 "Creates a separate series."(创建独立序列)。
  • Replace existing:帮助文字为 "Choose a series to replace. The current data becomes the default and earlier versions are kept."(选择一个要替换的序列,当前数据成为默认,旧版本保留);不可用时提示 "No other series of this type is loaded"(没有加载其他同类序列)。

3.2 三个目标的源码实现

reportDialogCustomization.tsx 中:

  • existingSeries:从 displaySetService.getDisplaySetCache() 中筛选出同模态的显示集,映射为 ExistingSeries 结构(value 即 predecessorImageId,作为写入目标;seriesNumber 用于计算下一个可用编号),并过滤掉没有 predecessorImageId 的条目与重复值;
  • currentSeries:existingSeries 中 value === predecessorImageId 的那一个,即 Save to current 的写入目标;数据从未被存储过时它为 null;
  • replaceableSeries:existingSeries 中排除 currentSeries 的其余部分,即 Replace existing 的可选项。

对话框打开时,useState<Destination>(currentSeries ? 'current' : 'new') 决定默认选中的标签页。只有当 Replace existing 目标被选中但尚未选择具体序列时,保存与下载按钮才会被禁用(isIncomplete 判断)。

四、哪些序列会被对话框提供为目标

4.1 两个硬性条件

对话框把某个已加载序列作为目标,必须同时满足两个条件:

  1. 序列持有同类型的对象——即与本次保存的模态(modality)一致(保存 SEG 时只考虑 SEG 序列);
  2. 序列具有 predecessorImageId 值。

predecessorImageId 命名的是"上次有人保存进该序列的那个直接前驱实例(immediate prior object)"。本次保存将取代(supersede)这一个实例。adapter 通过 PredecessorSequence provider,借助这个值解析出对应的序列与实例编号。

4.2 为什么不回退到 SeriesInstanceUID

对话框不会回退到显示集的 SeriesInstanceUID 值。原因在于类型语义:

  • UID 命名的是序列而不是实例,因此它不指向任何前驱对象;
  • UID 也不是 image id,PredecessorSequence provider 无法为 UID 找到任何实例;
  • 结果就是:若以 UID 作为"前驱",provider 找不到实例,保存会新建一个序列,而不是扩展所选的序列。

迁移文档 report-dialog.md 补充说明:旧版本的行为正是把 SeriesInstanceUID 当作序列值塞给 provider,导致 provider 抛出 TypeError——这正是行为文档中"provider 对 UID 找不到实例"这一规则的由来。

4.3 本地 id 是合法值

一个本地 id(local id),例如 dicomfile:3,是完全合法的 predecessorImageId。机制如下:

  • 用户上传的实例(uploaded instance)在注册时被赋予一个本地 id;
  • provider 能够解析本地 id;
  • 因此用户可以多次针对同一个上传实例执行保存(例如先存 Save as new,之后再次保存时通过本地 id 定位到它)。

4.4 下载但未存储的序列

一个被下载(download)却从未写回存储的显示集,没有 predecessorImageId 值,因此对话框不会提供该显示集作为保存目标。

但要注意:新建序列的编号计算仍然会计入这类序列。因为编号来自该模态的全部已加载序列,而不仅仅是"被提供的那些"。源码见 reportDialogCustomization.tsx:defaultNewSeriesNumber 遍历 modalityDisplaySets(同模态全部显示集)取最大 SeriesNumber 再加一,而非基于 existingSeries 或 replaceableSeries。

五、新序列叫什么:四种命名候选

5.1 四名候选的优先级

Save as new 提供四种候选名称,描述字段从第一个非空名称开始填充:

优先级 名称来源 说明
1 itemName 用户为该项目选择的名称。保存前的重命名会反映到该字段
2 加载来源序列的描述 即该数据上一次保存时使用的序列名
3 该类型项目以前用过的描述 最近使用的最靠前(详见"记住的描述")
4 defaultSeriesDescription 没有任何其他名称时的兜底名称

仓库内三个内置调用方传入的 defaultSeriesDescription 分别为:Segmentation(SEG)、Contours(RTSTRUCT)与 Measurements(测量报告)。

5.2 itemName 与 labelIsGenerated 的微妙关系

itemName 必须是"用户选择过的名称"。以 storeSegmentation 为例,commandsModule.ts 中:

const { label, predecessorImageId, labelIsGenerated } = segmentation;
// 只有用户选择的名称才进入 itemName,对话框将其放在第一位;
// 生成的名称则进入 defaultSeriesDescription,放在最后。
const chosenLabel = labelIsGenerated ? '' : label || '';
const defaultSeriesDescription =
  (labelIsGenerated && label) || (modality === 'RTSTRUCT' ? 'Contours' : 'Segmentation');

这里的关键在于 labelIsGenerated 标记:

  • 分割服务(Segmentation Service)为新分割自动生成一个名称(例如 Segmentation 3),并给分割打上 labelIsGenerated 标记;
  • 一个仍带着该标记的标签,会被归入 defaultSeriesDescription 而非 itemName——因为生成的名称不能压过(outrank)用户记住的描述;
  • 重命名会清除该标记。此后即使用户手动输入一个与自动生成名一模一样的字符串(例如真的输入了 Segmentation 3),保存时也不会做字符串比对,该名称仍会以 itemName 的身份进入候选第一位。

迁移文档还补充了 labelIsGenerated 的完整生命周期:Segmentation.labelIsGenerated 是 @cornerstonejs/tools 中的新字段,由 SegmentationPublicInput.config 携带;创建者发明标签时传入 labelIsGenerated: true;不带标签的创建者同样会得到该标记;而携带 label 但未带 labelIsGenerated 的更新操作会清除标记(即重命名)。

5.3 下拉列表的去重与回退规则

四种名称按上述顺序放入下拉列表(pull-down),并遵循以下规则:

  • 空白名称与纯空格名称会被剔除,防止其"藏住"后面的名称;
  • 对话框忽略大小写比较名称,列表中每个名称只出现一次;
  • 字段被清空时,回退到列表的第一个名称。

源码实现见 reportDialogCustomization.tsx:descriptionOptions 先对 [itemName, currentSeries?.description, ...remembered, defaultSeriesDescription] 逐一 trim() 并过滤空值,再用 toLowerCase() 去重。

5.4 没有 itemName 的调用方

没有可编辑名称的调用方不传 itemName。例如测量报告(measurement report)没有此类名称,因此其描述字段直接从"加载来源序列的描述"或"最近使用的名称"开始。

5.5 键盘交互

用户可以通过三种方式使用该列表(源码见 reportDialogCustomization.tsx):

  • 点击下拉按钮:展示全部候选名称;
  • 键入文字:列表被过滤为"当前输入可以补全(complete)"的名称子集;
  • Tab:补全为过滤后列表的第一个名称(若与当前输入不同则阻止默认 Tab 行为);
  • 方向键 + Enter:在列表中上下移动并选中一项;
  • Escape:关闭列表。

六、记住的描述(Remembered Descriptions)

6.1 什么时候被记住

  • 用户创建新序列并使用该描述时,此描述被记住;下载(download)也算一次保存,同样触发记忆;
  • 保存进一个已存在的序列时,不记住任何东西——因为该序列保留自己的描述;
  • 使用 defaultSeriesDescription 的保存不进入历史:调用方每次保存都会提供该名称,对话框无论如何都会提供它,记住它只会污染历史。

由此产生一个重要推论:自动生成的分割标签(如 Segmentation 1)落在 defaultSeriesDescription 上,因此不会进入历史,对话框也就不会把 Segmentation 1 当作后来某个无关分割的名称来推荐。

6.2 两个配置项

配置项 含义 默认值
itemType 描述被记住时使用的键(key) 模态(modality),即 SEG / RTSTRUCT / SR 各自独立
rememberedDescriptionCount 每种类型记住多少条描述 5

特别地,rememberedDescriptionCount: 0 会完全关闭该功能:不记忆、不提供,列表只剩一个名称,对话框也不渲染下拉按钮,退化为普通文本输入框。对于不允许向 localStorage 持久化任何内容的部署,应显式传入 rememberedDescriptionCount: 0。

6.3 存储实现

历史数据存放在浏览器 localStorage 中,键名为 ohif.seriesDescriptionHistory,结构为 Record<string, string[]>(按 itemType 分组、最近使用在前)。核心实现在 seriesDescriptionHistory.ts:

  • getSeriesDescriptionHistory(itemType, maxCount):读取并返回该类型最近使用的描述,最多 maxCount 条(第 39-52 行);
  • rememberSeriesDescription(itemType, description, maxCount):把描述记为最近使用,移除更早的同名条目(大小写不敏感,isSameDescription 用 toLowerCase() 比较),并截断到 maxCount 条(第 58-82 行);
  • readHistory():由于 localStorage 在某些浏览器配置下不可用、内容也可能被污染,所有读取都是防御性的,失败仅意味着"没有历史"(第 20-29 行)。

6.4 测试用例佐证

reportDialogCustomization.test.ts 中对记忆历史的断言非常直观,例如:

  • remembers the description that was used, per type of item:输入 Right kidney 保存后,storedHistory() 等于 { SEG: ['Right kidney'] };
  • remembers nothing for the name that the caller provides:直接用生成的 Segmentation 1 保存后,storedHistory() 等于 {};
  • remembers nothing when the typed name is the provided one:即使输入带空格变体的 contours,也不会被记住;
  • remembers nothing when an existing series is stored into:存入已有序列不触发记忆。

七、新序列的序列号(Series Number)

7.1 计算规则

Save as new 提供的序列号 = 该模态全部已加载序列的最高序列号 + 1,且至少为 minSeriesNumber。用户可以直接编辑该数字;若数字为空或非法,则回退到对话框最初提供的数字。

源码见 reportDialogCustomization.tsx 与 parsedSeriesNumber 的解析逻辑(第 279-282 行)。

7.2 minSeriesNumber 的模态默认值

minSeriesNumber 由 createReportDialogPrompt.tsx 按模态计算,仅当调用方未显式传入时生效:

minSeriesNumber ||=
  (modality === 'SR' && 3000) ||
  (modality === 'SEG' && 3100) ||
  (modality === 'RTSTRUCT' && 3200) ||
  4000;

即:SR 为 3000、SEG 为 3100、RTSTRUCT 为 3200,其他模态一律 4000。同时在 reportDialogCustomization.tsx 中,对话框组件自身的 minSeriesNumber 默认值为 3000。

7.3 返回值:seriesNumber 与 priorSeriesNumber

createReportDialogPrompt 返回 seriesNumber,同时返回 priorSeriesNumber(比 seriesNumber 小 1)。这是为了兼容旧调用方:凡是按 1 + priorSeriesNumber 计算编号的调用方,都能得到对话框当前显示(可能被用户编辑过)的数字。

迁移文档给出了明确的版本差异:

  • 3.13(旧):调用方自己算 SeriesNumber: 1 + priorSeriesNumber,无法感知用户的编辑;
  • 3.14(新):直接使用 SeriesNumber: seriesNumber(对话框已返回最终值),priorSeriesNumber 从"该模态最高现有编号"变为"seriesNumber - 1",旧式 1 + priorSeriesNumber 依然可用。

7.4 存储端的优先级

一个容易被忽略的细节:当设置了 predecessorImageId 时,SeriesDescription 和 SeriesNumber 会被忽略,因为生成的实例会应用前驱实例的序列数据——这正是对话框在扩展已有序列时把编号与描述显示为只读的原因。这在 commandsModule.ts 的 storeSegmentation 中有直接体现:

const args = {
  segmentationId,
  options: {
    dataSource: dataSourceName,
    SeriesDescription: series ? undefined : reportName || label || defaultSeriesDescription,
    SeriesNumber: series ? undefined : seriesNumber,
    predecessorImageId: series,
  },
};

当 series(即 predecessorImageId)存在时,SeriesDescription 与 SeriesNumber 均为 undefined。

八、保存之后:被存储的对象成为新前驱

要让"第二次保存默认 Save to current"成立,保存动作本身必须把本次写入的实例登记为新的前驱。核心机制是 registerStoredInstanceImageId:从 viewer 存储的实例,会像从数据源加载的实例一样被识别——它获得一个"重新加载该实例时会用到的 imageId",并在加入元数据存储前把这个 imageId 映射到它的 UIDs。因此,由存储实例生成的显示集自带 predecessorImageId。

两类对象的登记路径不同:

  • 分割与轮廓(SEG / RTSTRUCT):保存会移除内存中的分割并展示存储下来的那个,因此重新加载的分割通过正常加载路径从显示集取得前驱;
  • 测量(Measurements):测量不会从存储的报告重新加载,因此新增的 recordMeasurementsPredecessor 命令(在 CORNERSTONE 命令模块中)直接把前驱记录在测量及其派生的标注上,确保之后编辑测量不会丢失该引用。

在 promptSaveReport.tsx 中可以看到测量路径的完整闭环:storeMeasurements 执行后,从新显示集取 predecessorImageId,再调用 recordMeasurementsPredecessor 写回测量数据。

实际效果:同一份数据第二次保存时,默认选中 Save to current 并指向第一次保存所创建的序列。

九、如何自定义或替换对话框

ohif.createReportDialog 是正式的定制点(customization)。任何自定义组件只要注册到该键名下即可整体替换内置对话框。替换时需遵循的输入输出契约如下:

9.1 输入 props

内置 ReportDialog 组件接收(见 reportDialogCustomization.tsx):

  • dataSources:可写入的数据源列表(多数据源导出开启时显示选择器);
  • modality:本次保存的模态,用于筛选可写序列;
  • predecessorImageId:数据加载来源的 image id,决定 Save to current 是否可用;
  • minSeriesNumber:新序列编号的下限;
  • itemName:用户为该对象选择的名称(如分割名),新序列首选它;生成的名称应放入 defaultSeriesDescription;
  • defaultSeriesDescription:无其他名称时的兜底名;
  • itemType:记忆历史的键,默认取模态;
  • rememberedDescriptionCount:记忆条数,0 关闭;
  • enableDownload:是否显示 Download 按钮。

9.2 输出 onSave

onSave 负载包含:reportName(序列描述)、dataSource、series(以 predecessorImageId 值引用目标序列,新建序列时为 null)、seriesNumber(对话框显示并可能被编辑过的最终编号)以及 priorSeriesNumber。3.14 起新增 seriesNumber 字段;一个只创建新序列的自定义对话框可以直接传 series: null 与自定义的 seriesNumber。

9.3 复用记忆历史

描述记忆是对话框自身的职责。自定义对话框若想复用该行为,应直接调用 seriesDescriptionHistory.ts 导出的 getSeriesDescriptionHistory 与 rememberSeriesDescription;不想使用的对话框忽略 itemType 与 rememberedDescriptionCount 即可。

9.4 配套的样式与行为细节

  • 对话框标题为 Save Segmentation、Save Contours、Save Measurements(3.14 前为 Store/Create Report 措辞),调用方可通过 title 或模式的 defaultSaveTitle 覆盖;
  • 底部操作区为 FooterAction:左侧 Download、右侧 Cancel 与主保存按钮;
  • 对话框打开时默认焦点会落在"系列目标"分段控件上,但当目标是 Save as new 时,代码通过 useEffect 把光标移到描述输入框,便于用户直接键入命名(第 436-442 行)。

十、测试验证与行为契约

reportDialogCustomization.test.ts 用 701 行测试完整锁定了本文描述的全部行为,是理解行为契约的最佳入口。测试通过模拟多个显示集验证:

  • 目标可用性:无前驱时 current 禁用并提示;无其他同模态序列时 replace 禁用;默认选中标签页随数据是否被保存过而切换(第 186-215 行);
  • Save to current:展示目标序列只读的编号与描述,onSave 携带该序列的 predecessorImageId 与序列号(第 217-235 行);
  • Save as new:编号为最高现有编号 + 1;没有同模态序列时用 minSeriesNumber;不提供的序列(无前驱的下载序列)仍然计入编号计算;空字段回退到提供的值(第 237-301 行);
  • Replace existing:选择前禁用保存按钮;不重复提供当前序列;无描述的序列以 Series 3103 形式命名;带本地 id(dicomfile:3)的上传序列可被选中并可重复保存(第 303-384 行)。

十一、相关阅读

掌握这套"目标判定 + 命名候选 + 前驱链"的机制后,无论是排查保存行为、扩展新的保存对象类型,还是整体替换保存对话框,都能准确对齐 OHIF Viewer 既有的数据版本化语义,避免在自定义过程中破坏"旧版本保留、新版本成为默认"的核心契约。

登录后查看全文
Viewers