病理切片标注‑组件库

背景

前端需要展示病理切片图像。并在上面查看 AI 标注结果，还要支持医生手动修改标注、对比不同版本的差异。

经过调研发现这方面。

• 病理切片通常是几十亿像素级别的超大图，必须采用瓦片金字塔方案；领域标准是 OpenSeadragon + DZI与谷歌地图加载卫星图原理相同。
• 标注绘制层选用了轻量的开源插件 @wtsml/doodle基于 SVG overlay。支持多边形、矩形、圆、椭圆等常用形状，并具备撤销/重做功能。

使用者痛点

• 数据格式不匹配：后端返回的 JSON 与 doodle 所需的内部结构差异大，需要手动转换。
• 图像信息解析繁琐：尺寸、缩放级别、瓦片大小等元信息必须自行读取并传递。
• 缺少统一 UI 面板：缩放控制、工具切换、标注统计、区域列表等必须重复开发。
• 精修模式状态管理混乱：医生在 AI 标注上细微调整时状态同步和撤销/提交逻辑往往出错。
• 版本对比缺乏差异算法：仅叠加多个版本无法直观看出新增、删除或修改区域。
• 跨项目复用成本高：每个新项目都要重新实现上述功能，导致研发效率低下。

方法——完整组件库

将 OpenSeadragon 与 @wtsml/doodle 的能力进行深度封装。并提供一套可直接使用的 Vue 组件 + Core 引擎，实现“一次实现，多项目复用”。

成品概览

• DZI 深度缩放图像浏览：缩放、平移、全屏、导航器。
• 多种标注工具：移动、直线、矩形、多边形、圆、椭圆、方法、闭合方法。
• 标注统计面板：区域数量、类型分布实时展示。
• 画笔 + 撤销/重做/删除/提交，一键完成人工校正。
• 多版本差异可视化，自动分配颜分。
• 信息面板 + 查看器 + 工具面板，一体化页面结构。
• useAnnotationViewer 一把梭管理所有状态，业务方只需关注数据交互。

安装教程

Vue 项目一键安装

# Vue 项目直接装这个
npm install @pathology/dzi-viewer-vue
pnpm add @pathology/dzi-viewer-vue
# 同时确保以下 peer 依赖已在项目中
npm install vue element-plus @element-plus/icons-vue openseadragon
pnpm add vue element-plus @element-plus/icons-vue openseadragon

If you don’t use Vue

npm install @pathology/dzi-viewer-core
pnpm add @pathology/dzi-viewer-core

设计架构 & 为什么拆分？

@pathology/dzi-viewer-vue ← Vue 层
│ Vue 组件 + Composable
│ 基于 Element Plus 实现 UI
│ └── @pathology/dzi-viewer-core ← 主要层
创建查看器 / 标注管理 / 几何计算
版本对比 / 坐标转换 / 图像加载
零 UI 框架依赖
└── OpenSeadragon + @wtsml/doodle

*拆分意义*

• No UI lock‑in：The core 包可以在 React、Angular 或纯 JS 项目中直接使用，无需额外适配 Vue。
• Easier maintenance & testing：The core 层专注业务逻辑与算法。 Vue 层只负责视图渲染和交互，使得单元测试更聚焦、更可靠。
• Simplified CI/CD：Pnpm workspace monorepo 管理，两套打包方式：Core 用 tsup 输出 ESM & CJS 双格式；Vue 用 Vite library mode 打包并自动生成类型声明。

三种工作模式 & 状态流转图

The actual pathology workflow is not just “open image and look”. It can be divided into three mutually exclusive modes:

• 预览模式: 打开切片。仅查看 AI 标注结果，是最常用场景。
• 精修模式: 医生发现 AI 标注错误后用画笔工具手动微调边界并提交修正。
• 对比模式: 把 AI 原始标注与人工精修后的结果进行差异可视化。最多支持 N 个版本同时对比，每个版本自动配色。不过，

view → refine → view ↓                      ↑ compare ────────────────┘

The whole state is encapsulated by composable useAnnotationViewer. Business code only needs to pass a { mode }。and library handles all internal transitions.

快速上手示例

If you need a full three‑column layout,just drop in 。feed it required props and you get a production‑ready page instantly.

If you prefer fine‑grained control,use composable directly:

import { useAnnotationViewer } from "@pathology/dzi-viewer-vue";话说回来，const { viewer,tools,stats } = useAnnotationViewer({
imageUrl: dziUrl。annotationData: annotations,mode: "refine",// 必须实现的数据提供者接口见下文
});

统一的标注数据格式

The previous approach tried to expose doodle’s raw { pos },which varied wildly 娱乐ween shapes. To simplify backend integration we defined a canonical JSON schema:

interface AnnotationPoint {
x: number;y: number，}
interface AnnotationRegion {
external: AnnotationPoint;// 外边界点数组
至于holes?不过，，AnnotationPoint;// 可选内部空洞集合
再看shape?，"line" | "rect" | "polygon" |
"circle" | "ellipse" | "path" | "closed_path";}
interface AnnotationData {
regions: AnnotationRegion;}

The component internally converts this schema into doodle’s { pos }. Conversion logic lives in @pathology/dzi-viewer-core/src/utils/convertPointsToPos.ts,~50 行代码就可以完成全部映射。

版本对比差异算法

The algorithm works in two passes:

1.  If two regions have identical coordinate sets → marked as "unchanged".
2. If not exact,compute similarity based on:
   • Areal ratio 
   • Barycenter distance 
   .
   . If similarity ≥ threshold → marked as "modified". Remaining unmatched regions are classified as "added"/"removed".

This heuristic covers>九十五成上下 of real‑world cases while staying lightweight. Implementation resides in @pathology/dzi-viewer-core/src/utils/annotationDifference.ts.

后端对接 – 完全解耦

The library exposes a simple contract that any backend can implement:

interface AnnotationDataProvider {
/** 获取指定切片及可选版本的标注 */
getAnnotation: Promise;/** 获取该切片所有可用版本列表，用于对比 */
getVersions?: Promise;/** 提交精修后的标注 */
submitRefine?: Promise;}

• If you omit getVersions。version‑compare panel disappears.
• If you omit submitRefine,“提交”按钮会被隐藏，从而可以仅用于只读展示场景。老实说，Li st> The component never hard‑codes any API endpoint – you just pass an object that conforms to this interface. Ul>

项目信息 & License

• GitHub ：
• npm 包 ： @pathology/dzi-viewer-core。@pathology/dzi‑viewer‑vue
• License ： MIT

。

---