med-viewer-sdk 0.1.0

package/README.md

@@ -0,0 +1,253 @@
+# MedViewer SDK
+
+MedViewer SDK 是一个强大且灵活的医学图像查看 SDK，它基于 OpenSeadragon 构建，旨在为医学图像分析和注释提供丰富的交互功能。
+
+## 功能特性
+
+- **高性能图像查看：** 利用 OpenSeadragon 实现高分辨率医学图像的无缝查看，支持深度缩放和平移功能。
+- **可定制工具栏：**
+    - 动态且可配置的工具栏，可集成各种工具和插件。
+    - 支持文本和图标按钮。
+    - 按钮可以触发设置下拉菜单或直接执行操作。
+    - 用户定义的按钮配置可以覆盖默认设置（图标、标签、功能）。
+    - 响应式布局，侧边工具栏（MIDDLE_LEFT, MIDDLE_RIGHT）支持垂直方向。
+- **选择插件：**
+    - 提供交互式选择功能（例如，绘制矩形）。
+    - 可配置的选择外观和行为。
+    - 与工具栏集成，方便访问和控制。
+- **比例尺插件：**
+    - 在查看器上显示动态比例尺。
+    - 支持不同类型的比例尺（例如，显微镜、地图）。
+    - 可配置位置、颜色、字体和大小。
+    - 自动初始化并与查看器的缩放级别同步。
+- **标注工具：**
+    - **Annotorious 集成 (AnnoAnnotator)：**
+        - 集成 Annotorious 库以提供高级标注功能。
+        - 支持各种标注工具（例如，徒手绘制、多边形）。
+        - 提供启用/禁用、设置工具、获取/设置标注和清除标注的方法。
+        - 动态注入自定义标注样式。
+    - **Konva.js 集成 (KonvaAnnotator)：**
+        - 利用 Konva.js 实现自定义绘图覆盖。
+        - 当前支持绘制矩形和可能的箭头（注释掉的同步逻辑表明可能计划了更复杂的交互）。
+        - 允许拖动形状。
+        - 无论缩放级别如何，都保持恒定的描边宽度 (`strokeScaleEnabled: false`)。
+        - 提供启用/禁用、设置工具、获取/设置标注和清除标注的方法。
+- **颜色调整插件：**
+    - 启用对图像属性（如亮度、对比度、饱和度、伽马、锐化、边缘增强、伪彩色和反色）的实时调整。
+    - **利用 WebGL 着色器：** 直接在 GPU 上实现调整以提高性能。
+    - 尝试强制 OpenSeadragon 使用其 WebGL 渲染器以获得最佳功能。
+    - 提供自定义 WebGL 着色器用于高级颜色操作。
+- **基于插件的架构：**
+    - SDK 采用模块化、基于插件的架构设计，以 `MedViewerEngine` 作为核心协调器。
+    - 易于扩展以添加新功能。
+    - 管理各种插件的生命周期（初始化、销毁）。
+
+## 安装
+
+```bash
+# 假设使用 npm 或 yarn 进行包管理
+npm install openseadragon konva # 根据需要添加其他依赖
+# 或
+yarn add openseadragon konva
+```
+
+然后，在您的项目中引入 SDK：
+
+```typescript
+import { MedViewerEngine } from 'med-viewer-sdk'; // 根据需要调整路径
+// 如果有任何 CSS，请导入
+```
+
+## 用法
+
+### 基本初始化
+
+```typescript
+import { MedViewerEngine } from './core/Engine'; // 以本地路径为例
+import OpenSeadragon from 'openseadragon';
+
+const viewerElement = document.getElementById('med-viewer-container');
+
+if (viewerElement) {
+  const engine = new MedViewerEngine({
+    element: viewerElement,
+    viewerOptions: {
+      // OpenSeadragon 选项
+      id: 'openseadragon-viewer',
+      prefixUrl: 'https://openseadragon.github.io/openseadragon/images/',
+      tileSources: {
+        type: 'image',
+        url: 'https://openseadragon.github.io/example-images/duomo/duomo.dzi'
+      },
+      // ... 其他 OSD 选项
+    },
+    plugins: {
+      toolbar: true, // 启用默认工具栏
+      selection: true, // 启用选择插件
+      scalebar: { // 启用比例尺插件并带自定义选项
+        type: 'MICROSCOPY',
+        location: 'BOTTOM_LEFT',
+        color: 'rgb(255, 255, 255)',
+        fontColor: 'rgb(255, 255, 255)',
+        backgroundColor: 'rgba(0, 0, 0, 0.5)',
+      },
+      anno: true, // 启用 Annotorious
+      konva: true, // 启用 Konva.js 绘图
+      colorAdjust: { // 启用颜色调整并带初始设置
+        initial: {
+          brightness: 1.2,
+          contrast: 0.8,
+          invert: true,
+        }
+      }
+    }
+  });
+
+  // 访问插件
+  if (engine.toolbar) {
+    console.log('工具栏已激活');
+  }
+  if (engine.selection) {
+    engine.selection.enable();
+    engine.selection.setSelectionMode('RECTANGLE');
+  }
+  if (engine.anno) {
+    engine.anno.setEnabled(true);
+    engine.anno.setTool('rect');
+  }
+  if (engine.konva) {
+    engine.konva.setEnabled(true);
+    engine.konva.setTool('rect');
+  }
+  if (engine.colorAdjust) {
+    engine.colorAdjust.setAdjustments({ brightness: 1.5 });
+  }
+
+  // 不再需要时进行清理
+  // engine.destroy();
+}
+```
+
+### 自定义工具栏
+
+您可以通过将 `ToolbarButton` 配置数组传递给 `toolbar` 插件选项来定制工具栏。可以通过匹配其 `id` 来覆盖现有默认按钮。
+
+```typescript
+import { MedViewerEngine, ToolbarButton } from './core/Engine'; // 以本地路径为例
+import myCustomIcon from './assets/my-icon.png';
+
+const customToolbarButtons: ToolbarButton[] = [
+  {
+    id: 'anno', // 覆盖默认的 'anno' 按钮
+    label: '我的标注',
+    icon: myCustomIcon, // 使用自定义图标
+    // 保留原始的 dropdownContent 或定义新的
+  },
+  {
+    id: 'customTool', // 添加新的自定义按钮
+    label: '新工具',
+    onClick: (engine) => {
+      alert('自定义工具已点击！');
+      // 在此处实现自定义逻辑
+    }
+  }
+];
+
+const engine = new MedViewerEngine({
+  // ...
+  plugins: {
+    toolbar: {
+      buttons: customToolbarButtons,
+      // ... 其他工具栏选项
+    },
+    // ... 其他插件
+  }
+});
+```
+
+
+## 引用方式
+
+构建完成后，您可以通过以下方式在其他项目中使用 `med-viewer-sdk`：
+
+### 1. 本地开发（使用 `npm link`）
+
+如果您在本地同时开发 `med-viewer-sdk` 和另一个项目，`npm link` 是一个便捷的选择。
+
+-   **在 `med-viewer-sdk` 项目目录中执行：**
+    ```bash
+    npm link
+    ```
+-   **在您的其他项目目录中执行：**
+    ```bash
+    npm link med-viewer-sdk
+    ```
+    现在，您就可以像从 npm 安装一样导入 `med-viewer-sdk` 了。
+
+### 2. 从本地路径安装
+
+您可以直接从文件系统的本地路径安装打包后的 SDK。
+
+-   **在您的其他项目的 `package.json` 中添加：**
+    ```json
+    "dependencies": {
+      "med-viewer-sdk": "file:../path/to/your/med-viewer-sdk", // 根据实际路径调整
+      // ... 其他依赖
+    }
+    ```
+-   **然后在您的其他项目目录中运行 `npm install`。**
+
+### 3. 发布到包注册表 (例如 npm)
+
+如果这是一个可重用的库，您通常会将其发布到包注册表。
+
+-   **确保您的 `package.json` 已准备好发布：**
+    -   `name`、`version`、`main`、`module`、`types`、`files` 字段应正确配置。
+    -   `files` 数组应包含 `dist` 目录和任何其他必要文件。
+-   **登录 npm (如果尚未登录)：**
+    ```bash
+    npm login
+    ```
+-   **发布：**
+    ```bash
+    npm publish --access public // 如果是私有包，则无需 --access public
+    ```
+
+### 4. 在您的代码中导入
+
+安装/链接后，您可以在应用程序中导入它：
+
+-   **对于 ES 模块 (推荐用于现代 JS/TS 项目)：**
+    ```typescript
+    import { MedViewerEngine } from 'med-viewer-sdk';
+    // 或者如果您在脚本标签中需要全局名称：
+    // const MedViewerSDK = window.MedViewerSDK;
+    ```
+-   **对于 CommonJS (如果使用 Node.js 或旧版打包工具)：**
+    ```javascript
+    const { MedViewerEngine } = require('med-viewer-sdk');
+    ```
+-   **直接在 HTML 中 (UMD 构建)：**
+    ```html
+    <script src="path/to/your/node_modules/med-viewer-sdk/dist/med-viewer-sdk.umd.js"></script>
+    <script>
+      const MedViewerSDK = window.MedViewerSDK;
+      // 使用 MedViewerSDK.MedViewerEngine 等
+    </script>
+    ```
+
+## API 参考
+
+（此处将提供 `MedViewerEngine`、`Toolbar`、`SelectionPlugin`、`ScalebarPlugin`、`AnnoAnnotator`、`KonvaAnnotator`、`ColorAdjustPlugin` 及其选项的详细 API 参考。这通常从 JSDoc 或单独的文档生成。）
+
+## 开发
+
+（有关设置开发环境、运行测试、构建等的说明。）
+
+## 贡献
+
+（贡献项目的指南。）
+
+## 许可证
+
+（许可证信息。）

package/dist/adapters/vue/MedViewer.d.ts

@@ -0,0 +1,17 @@
+import type { MedEngineOptions } from '../../core/Engine';
+declare const _default: import("vue-demi").DefineComponent<import("vue-demi").ExtractPropTypes<{
+    options: {
+        type: () => Omit<MedEngineOptions, "element">;
+        required: true;
+    };
+}>, () => import("vue-demi").VNode<import("vue-demi").RendererNode, import("vue-demi").RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import("vue-demi").ComponentOptionsMixin, import("vue-demi").ComponentOptionsMixin, "ready"[], "ready", import("vue-demi").PublicProps, Readonly<import("vue-demi").ExtractPropTypes<{
+    options: {
+        type: () => Omit<MedEngineOptions, "element">;
+        required: true;
+    };
+}>> & Readonly<{
+    onReady?: ((...args: any[]) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue-demi").ComponentProvideOptions, true, {}, any>;
+export default _default;

package/dist/adapters/vue/index.d.ts

@@ -0,0 +1,2 @@
+import MedViewer from './MedViewer';
+export default MedViewer;

package/dist/core/AnnoAnnotator.d.ts

@@ -0,0 +1,15 @@
+import "annotorious-openseadragon-ld/dist/annotorious.min.css";
+import { MedViewerEngine } from "./Engine";
+import { BaseAnnotator } from "./BaseAnnotator";
+export declare class AnnoAnnotator extends BaseAnnotator {
+    anno: any;
+    constructor(engine: MedViewerEngine, config?: any);
+    setEnabled(enabled: boolean): void;
+    setTool(tool: "rect" | "polygon" | "line" | "point" | "circle" | "ellipse" | "freehand" | null, color?: string): void;
+    getAnnotations(): any[];
+    setAnnotations(data: any[]): void;
+    clear(): void;
+    destroy(): void;
+    private initEvents;
+    private injectStyles;
+}

package/dist/core/BaseAnnotator.d.ts

@@ -0,0 +1,33 @@
+import { MedViewerEngine } from './Engine';
+/**
+ * 标注插件的基类
+ */
+export declare abstract class BaseAnnotator {
+    protected engine: MedViewerEngine;
+    protected isEnabled: boolean;
+    constructor(engine: MedViewerEngine);
+    /**
+     * 启用/禁用标注功能
+     */
+    abstract setEnabled(enabled: boolean): void;
+    /**
+     * 设置当前的工具模式 (例如：矩形、箭头、多边形)
+     */
+    abstract setTool(tool: string | null): void;
+    /**
+     * 获取所有标注数据 (建议在此处进行格式标准化)
+     */
+    abstract getAnnotations(): any[];
+    /**
+     * 加载标注数据
+     */
+    abstract setAnnotations(data: any[]): void;
+    /**
+     * 清除所有标注
+     */
+    abstract clear(): void;
+    /**
+     * 销毁插件，移除事件监听
+     */
+    abstract destroy(): void;
+}

package/dist/core/ColorAdjustPlugin.d.ts

@@ -0,0 +1,29 @@
+import type { MedViewerEngine } from "./Engine";
+export interface ColorAdjustments {
+    brightness?: number;
+    contrast?: number;
+    saturation?: number;
+    gamma?: number;
+    sharpen?: number;
+    edgeEnhance?: number;
+    pseudoColor?: boolean;
+    invert?: boolean;
+}
+export interface ColorAdjustOptions {
+    initial?: ColorAdjustments;
+}
+export declare class ColorAdjustPlugin {
+    private engine;
+    private adjustments;
+    private options;
+    constructor(engine: MedViewerEngine, options?: ColorAdjustOptions);
+    setAdjustments(adjustments: ColorAdjustments): void;
+    getAdjustments(): ColorAdjustments;
+    destroy(): void;
+    private apply;
+    private isWebGLRenderer;
+    private forceWebGLRenderer;
+    private applyWebGLFilters;
+    private setupCustomShader;
+    private createShader;
+}

package/dist/core/Coords.d.ts

@@ -0,0 +1,6 @@
+export declare class Coords {
+    static imageToScreen(imageX: number, imageY: number, scale: number): {
+        x: number;
+        y: number;
+    };
+}

package/dist/core/Engine.d.ts

@@ -0,0 +1,57 @@
+import OpenSeadragon from "openseadragon";
+import { KonvaAnnotator } from "./KonvaAnnotator";
+import { AnnoAnnotator } from "./AnnoAnnotator";
+import { MedToolbar, type ToolbarOptions } from "./Toolbar";
+import { ColorAdjustPlugin, type ColorAdjustOptions } from "./ColorAdjustPlugin";
+import { SelectionPlugin, type SelectionOptions } from './SelectionPlugin';
+import { ScalebarPlugin, type ScalebarOptions } from './Scalebar';
+/**
+ * 引擎配置接口
+ */
+export interface MedEngineOptions {
+    element: HTMLElement;
+    tileSource: string | any;
+    navigatorBorderRadius?: number;
+    prefixUrl?: string;
+    plugins?: {
+        konva?: boolean | any;
+        annotorious?: boolean | any;
+        toolbar?: boolean | ToolbarOptions;
+        colorAdjust?: boolean | ColorAdjustOptions;
+        selection?: boolean | SelectionOptions;
+        scalebar?: boolean | ScalebarOptions;
+    };
+}
+/**
+ * 医学影像核心引擎
+ * 职责：初始化 OpenSeadragon，管理插件生命周期
+ */
+export declare class MedViewerEngine {
+    viewer: OpenSeadragon.Viewer;
+    konva: KonvaAnnotator | null;
+    anno: AnnoAnnotator | null;
+    toolbar: MedToolbar | null;
+    colorAdjust: ColorAdjustPlugin | null;
+    selection: SelectionPlugin | null;
+    scalebar: ScalebarPlugin | null;
+    private options;
+    constructor(options: MedEngineOptions);
+    /**
+     * 内部插件初始化逻辑
+     * 解决异步 DOM 挂载问题，防止 Annotorious 初始化时找不到 Canvas
+     */
+    private initPlugins;
+    /**
+     * 真正挂载 Annotorious 的私有方法
+     */
+    private mountAnnotorious;
+    /**
+     * 统一切换交互模式
+     * @param mode 'browse' | 'konva' | 'anno'
+     */
+    setInteractionEffect(mode: "browse" | "konva" | "anno"): void;
+    /**
+     * 销毁引擎与所有插件
+     */
+    destroy(): void;
+}

package/dist/core/KonvaAnnotator.d.ts

@@ -0,0 +1,36 @@
+import Konva from 'konva';
+import { MedViewerEngine } from './Engine';
+import { BaseAnnotator } from './BaseAnnotator';
+export declare class KonvaAnnotator extends BaseAnnotator {
+    stage: Konva.Stage;
+    layer: Konva.Layer;
+    private overlay;
+    private isDrawing;
+    private currentShape;
+    private currentTool;
+    private startPoint;
+    constructor(engine: MedViewerEngine);
+    /**
+     * 实现基类方法：启用/禁用标注层
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * 实现基类方法：设置工具
+     */
+    setTool(tool: 'rect' | 'arrow' | null): void;
+    /**
+     * 核心同步逻辑：保持 Canvas 与 OSD 图片位置重合
+     */
+    /**
+     * 监听绘图相关的鼠标事件
+     */
+    private initDrawingEvents;
+    /**
+     * 工具方法：获取相对于图像(0~1)空间的鼠标位置
+     */
+    private getRelativePointerPosition;
+    getAnnotations(): any[];
+    setAnnotations(data: any[]): void;
+    clear(): void;
+    destroy(): void;
+}

package/dist/core/Scalebar.d.ts

@@ -0,0 +1,42 @@
+import OpenSeadragon from "openseadragon";
+import "../plugins/openseadragon-scalebar.js";
+export declare enum ScalebarType {
+    NONE = 0,
+    MICROSCOPY = 1,
+    MAP = 2
+}
+export declare enum ScalebarLocation {
+    NONE = 0,
+    TOP_LEFT = 1,
+    TOP_RIGHT = 2,
+    BOTTOM_RIGHT = 3,
+    BOTTOM_LEFT = 4
+}
+export interface ScalebarOptions {
+    type?: ScalebarType;
+    pixelsPerMeter?: number;
+    xOffset?: number;
+    yOffset?: number;
+    stayInsideImage?: boolean;
+    color?: string;
+    fontColor?: string;
+    backgroundColor?: string;
+    fontSize?: string;
+    fontFamily?: string;
+    barThickness?: number;
+    minWidth?: string;
+    location?: ScalebarLocation;
+    referenceItemIdx?: number;
+    sizeAndTextRenderer?: (ppm: number, minSize: number) => {
+        size: number;
+        text: string;
+    };
+}
+export declare class ScalebarPlugin {
+    private viewer;
+    private options;
+    private scalebar;
+    constructor(viewer: OpenSeadragon.Viewer, options?: ScalebarOptions);
+    private init;
+    destroy(): void;
+}

package/dist/core/SelectionPlugin.d.ts

@@ -0,0 +1,102 @@
+import OpenSeadragon from "openseadragon";
+import "../plugins/openseadragon-selection.js";
+export interface SelectionOptions {
+    element?: HTMLElement | null;
+    showSelectionControl?: boolean;
+    toggleButton?: HTMLElement | null;
+    showConfirmDenyButtons?: boolean;
+    styleConfirmDenyButtons?: boolean;
+    returnPixelCoordinates?: boolean;
+    keyboardShortcut?: string;
+    rect?: OpenSeadragon.Rect | null;
+    allowRotation?: boolean;
+    startRotated?: boolean;
+    startRotatedHeight?: number;
+    restrictToImage?: boolean;
+    onSelection?: (rect: OpenSeadragon.Rect) => void;
+    onSelectionCanceled?: () => void;
+    onSelectionChange?: (rect: OpenSeadragon.Rect) => void;
+    onSelectionToggled?: (state: {
+        enabled: boolean;
+    }) => void;
+    prefixUrl?: string | null;
+    navImages?: {
+        selection: {
+            REST: string;
+            GROUP: string;
+            HOVER: string;
+            DOWN: string;
+        };
+        selectionConfirm: {
+            REST: string;
+            GROUP: string;
+            HOVER: string;
+            DOWN: string;
+        };
+        selectionCancel: {
+            REST: string;
+            GROUP: string;
+            HOVER: string;
+            DOWN: string;
+        };
+    };
+    borderStyle?: {
+        width: string;
+        color: string;
+    };
+    handleStyle?: {
+        top: string;
+        left: string;
+        width: string;
+        height: string;
+        margin: string;
+        background: string;
+        border: string;
+    };
+    cornersStyle?: {
+        width: string;
+        height: string;
+        background: string;
+        border: string;
+    };
+}
+export declare class SelectionPlugin {
+    private viewer;
+    private selection;
+    private options;
+    constructor(viewer: OpenSeadragon.Viewer, options?: SelectionOptions);
+    private init;
+    private setupSelection;
+    /**
+     * 启用选择模式
+     */
+    enable(): void;
+    /**
+     * 禁用选择模式
+     */
+    disable(): void;
+    /**
+     * 切换选择模式状态
+     */
+    toggleState(): void;
+    /**
+     * 获取当前选择区域
+     */
+    getSelection(): OpenSeadragon.Rect | null;
+    /**
+     * 设置选择区域
+     */
+    setSelection(rect: OpenSeadragon.Rect): void;
+    /**
+     * 清除选择
+     */
+    clearSelection(): void;
+    /**
+     * 检查是否启用选择模式
+     */
+    isEnabled(): boolean;
+    /**
+     * 销毁插件
+     */
+    destroy(): void;
+}

package/dist/core/Toolbar.d.ts

@@ -0,0 +1,32 @@
+import type { MedViewerEngine } from "./Engine";
+export type ToolbarPosition = "TOP_LEFT" | "TOP_CENTER" | "TOP_RIGHT" | "BOTTOM_LEFT" | "BOTTOM_CENTER" | "BOTTOM_RIGHT" | "MIDDLE_LEFT" | "MIDDLE_RIGHT";
+export interface ToolbarButton {
+    id: string;
+    label?: string;
+    icon?: string;
+    dropdownContent?: (engine: MedViewerEngine, hide: () => void) => HTMLElement;
+    onClick?: (engine: MedViewerEngine, hide: () => void) => void;
+}
+export interface ToolbarOptions {
+    position?: ToolbarPosition;
+    buttons?: ToolbarButton[];
+}
+/**
+ * MedToolbar 主类
+ */
+export declare class MedToolbar {
+    private engine;
+    private options;
+    private element;
+    private dropdownElement;
+    private outsideClickHandler;
+    constructor(engine: MedViewerEngine, options?: ToolbarOptions);
+    destroy(): void;
+    private render;
+    private showDropdown;
+    private adjustDropdownPosition;
+    private closeDropdown;
+    private mount;
+    private getClassName;
+    private injectStyles;
+}

package/dist/med-viewer-sdk.d.ts

@@ -0,0 +1,6 @@
+import { MedViewerEngine } from './core/Engine';
+import { KonvaAnnotator } from './core/KonvaAnnotator';
+import { AnnoAnnotator } from './core/AnnoAnnotator';
+import { MedToolbar } from './core/Toolbar';
+import { SelectionPlugin } from './core/SelectionPlugin';
+export { MedViewerEngine, KonvaAnnotator, AnnoAnnotator, MedToolbar, SelectionPlugin };