# SlicetoDeepZoomImage **Repository Path**: peakb_admin/SlicetoDeepZoomImage ## Basic Information - **Project Name**: SlicetoDeepZoomImage - **Description**: https://github.com/niu-peng/SlicetoDeepZoomImage - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-06-28 - **Last Updated**: 2026-06-28 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Slice to DeepZoom 基于 `Electron + Vite + Vue 3` 的桌面切片工具，用来把超大图像或病理切片文件转换为 DeepZoom `DZI` 结构，并在应用内立即预览。 --- ## 一、项目概述 **Slice to DeepZoom** 是一款面向数字病理学领域的桌面应用工具，核心目标是将超大尺寸的病理切片图像文件（如 SVS、KFB、NDPI、TIFF 等专业格式）转换为 DeepZoom（DZI）瓦片结构，以便在 Web 端或应用内实现流畅的高倍率缩放浏览。项目基于 **Electron + Vite + Vue 3** 技术栈构建，采用全中文界面，定位为专业病理工作流中的图像预处理环节。 --- ## 二、核心功能 ### 1. 病理切片格式转换 应用的核心能力是调用系统级 **libvips** 图像处理库，通过 `vips thumbnail` 和 `vips dzsave` 两个 CLI 命令完成图像的缩略图生成与 DZI 瓦片切分。支持的输入格式涵盖病理学领域的主流文件类型：SVS（Aperio）、KFB（江丰生物）、NDPI（Hamamatsu）、TIFF/TIF，以及通用的 PNG、JPG/JPEG。转换参数硬编码为：瓦片大小 512px、重叠像素 1px、输出格式 DZI、后缀 JPG Q75 压缩，这些参数针对病理切片的典型使用场景进行了优化。 ### 2. 单任务线性工作流 应用采用单任务互斥设计，同一时间仅允许一个转换任务运行。这一设计避免了多个 vips 进程并发竞争磁盘 I/O 和内存资源的问题，确保在处理动辄数 GB 的病理切片文件时系统稳定性。模块级 `activeConversion` 变量充当互斥锁，新的转换请求必须等待当前任务完成后才能启动。 ### 3. 双模式文件输入 用户可通过两种方式选择待转换的病理切片文件：一是点击按钮调用操作系统原生文件选择对话框（已预设病理格式过滤器），二是直接将文件拖拽至应用界面的放置区域（Dropzone）。拖拽交互包含完整的视觉反馈——拖入时高亮、拖离时恢复、处理中锁定。 ### 4. 实时进度反馈 转换过程中，应用通过 IPC 通道从主进程向渲染进程推送细粒度的进度更新。进度划分为六个阶段：预检（4%）→ 输出目录准备（12%）→ 缩略图生成（24-38%）→ DZI 瓦片切分（44-88%）→ 元数据写入与验证（92%）→ 完成（100%）。由于 `vips dzsave` 本身不提供进度回调，应用实现了"脉冲进度"机制——每 1.2 秒自动递增 1 个百分点，为用户提供平滑的视觉反馈。界面顶部有一条 4px 高的绿色渐变进度条，同时配合四步工作流指示器（文件输入 → 任务锁定 → 瓦片写入 → 输出验证）以彩色圆点展示当前所处阶段。 ### 5. 任务取消支持 用户可在转换进行中随时取消任务。取消操作通过向活跃的 vips 子进程发送 `SIGTERM` 信号实现，同时在转换流程的多个关键检查点调用 `ensureNotCanceled()` 进行状态检测，确保取消指令能被及时响应。自定义的 `ConversionCanceledError` 错误类用于区分正常错误和用户主动取消。 ### 6. 产物管理与历史记录 每次转换在输出目录下自动创建独立的任务文件夹，内含 DZI 文件、瓦片目录、400px 宽的缩略图以及 `manifest.json` 元数据文件。manifest 记录了 UUID、任务名称、源文件信息、所有输出路径、VIPS 参数和时间戳。应用维护最近 5 条任务的历史记录，按 DZI 路径去重，支持持久化到 `localStorage`，重启后自动恢复。界面提供"打开任务目录"、"定位 DZI 文件"、"打开源文件目录"等操作系统集成按钮，可直接唤起系统文件管理器。 ### 7. 任务名称智能处理 转换前会对输入文件名进行清洗处理：通过 Unicode NFKC 规范化消除全角/半角差异，剥离特殊字符，将空白字符替换为下划线。若输出目录中已存在同名任务文件夹，自动追加数字后缀（如 `Case_001`、`Case_001-2`）避免覆盖。 --- ## 三、技术架构特点 ### 1. Electron 三层架构 项目严格遵循 Electron 的标准三层架构：**主进程**（`src/main/`）负责窗口管理、系统对话框、vips 进程调度；**预加载脚本**（`src/preload/`）通过 `contextBridge.exposeInMainWorld` 安全地暴露 6 个 API 方法；**渲染进程**（`src/renderer/`）承载完整的 Vue 3 单页应用。IPC 通信采用 5 个请求-响应通道（renderer → main）加 1 个事件推送通道（main → renderer）的模式，职责划分清晰。 ### 2. 极简依赖设计 运行时仅依赖 3 个包：`@electron-toolkit/preload`（预加载桥接工具）、`@electron-toolkit/utils`（Electron 辅助函数）、`electron-updater`（自动更新支持，当前为占位配置）。前端无 Vue Router、无 Pinia/Vuex，整个渲染进程为单组件架构（`App.vue` 约 1156 行），所有状态通过 Vue 3 Composition API 的 `ref()` 和 `computed()` 管理。这种极简依赖策略降低了包体积和维护复杂度。 ### 3. Vite 驱动的构建体系 使用 `electron-vite` 作为统一构建工具，分别为主进程、预加载脚本和渲染进程提供独立的 Vite 配置。渲染进程启用 `@vitejs/plugin-vue` 插件，支持 Vue 单文件组件的热更新。构建产物通过 `electron-builder` 打包为平台安装程序：macOS 使用 zip 格式并配置了 JIT 和 dyld 环境变量的 entitlements；Windows 使用 NSIS 安装程序（中文语言包 2052）；Linux 支持 AppImage、Snap 和 Deb 三种格式。 ### 4. Mintlify 风格设计系统 界面视觉设计参照 Mintlify 网站风格，建立了一套完整的设计令牌系统：品牌色 `#18E299`（薄荷绿）、近黑色 `#0d0d0d` 作为主文字色、极浅绿灰 `#f7faf8` 作为页面背景。所有按钮和标签采用 999px 圆角（药丸形状），卡片统一 24px 圆角，使用 Inter 字体和等宽字体 SFMono-Regular/Consolas。页面背景采用从左上角绿白渐变过渡到主背景色的径向渐变效果。响应式设计在 1120px 断点处将双栏布局折叠为单栏，720px 断点进一步优化移动端适配。 ### 5. 安全与代码质量 渲染进程 HTML 配置了严格的内容安全策略（CSP），限制脚本、样式和图片仅可加载同源资源。ESLint 使用 Flat 配置格式，集成了 Vue 推荐规则和 Prettier 格式化规则，启用了缓存加速重复检查。Prettier 配置为单引号、无分号、100 字符行宽、无尾逗号。编辑器配置强制 UTF-8 编码、2 空格缩进、LF 换行符。 ### 6. 进程管理与错误处理 vips 命令通过 `child_process.spawn`（非 execFile）执行，设置 `windowsHide: true` 隐藏 Windows 控制台窗口。对 `ENOENT` 错误（vips 未安装）提供友好的中文提示信息。对 `SIGTERM` 和 `SIGINT` 信号正确识别为用户取消而非异常错误。转换完成后对所有预期输出文件进行存在性验证，确保产物完整性。 ### 7. 跨平台发布准备 项目已配置完整的跨平台构建流程：`npm run build:mac`、`npm run build:win`、`npm run build:linux` 三个脚本分别处理各平台的打包。`.npmrc` 配置了中国区 npm 镜像源（npmmirror.com）以及 Electron 和 electron-builder 的二进制下载镜像，显著提升国内开发环境的安装速度。`.nvmrc` 固定 Node.js 版本为 24.14，确保团队成员使用一致的运行时环境。 --- ## 四、转换产物结构 每次转换都会在输出目录下生成一个独立任务文件夹： ```text library/ Case_001/ Case_001.dzi Case_001_files/ Case_001_thumbnail.jpg manifest.json ``` --- ## 五、环境要求 - Node.js：`24.14.x` 或更高 - npm：建议跟随 Node 24 一起使用 - libvips：系统需要可直接执行 `vips` 项目根目录已经包含 `.nvmrc`，建议直接执行： ```bash nvm use npm install npm run dev ``` 如果当前 shell 没有切到正确的 Node 版本，`vite`/`eslint` 会因为版本过旧而无法正常工作。 --- ## 六、常用命令 ```bash npm run dev # 启动开发服务器 npm run build # 构建应用 npm run build:mac # 打包 macOS 安装程序 npm run build:win # 打包 Windows 安装程序 npm run build:linux # 打包 Linux 安装程序 npm run format # 代码格式化 npm run lint # 代码检查 ``` --- ## 七、当前验证情况 - 使用 `Node v24.14.1` 显式执行本地 CLI 后，`eslint` 通过 - 使用 `Node v24.14.1` 执行 `electron-vite build` 通过 --- ## 八、待完善功能 当前版本已预留但尚未实现的功能包括： - **OpenSeadragon 预览**：基于 OpenSeadragon 的应用内 DZI 即时预览（"预览"按钮当前为占位状态） - **自动更新**：基于 electron-updater 的应用自动更新（发布地址当前为占位 URL） --- ## 九、说明 当前工作区默认 `node -v` 仍然可能指向旧版本 Node；如果你直接在终端里运行命令，请先 `nvm use`，否则会看到和业务代码无关的环境兼容报错。