IMG2SVG | Michaell Alavedra

本文档旨在对 IMG2SVG 进行详尽的解剖，这是一个用于将栅格图像高级转换为可缩放 SVG 矢量的系统。下面详细介绍了支持应用运行的动机、结构设计和技术决策。

1. 业务实用性与通用工作流

问题

图形数字化通常涉及处理存在像素化和噪声的栅格图像（位图），这限制了它们在高分辨率介质或纯图形设计中的实用性。传统的矢量化需要庞大的桌面工具或可能损害隐私或即时性的云服务。此外，源图像通常带有噪点，导致矢量化结果带有数千条不必要的路径，从而降低渲染性能。

业务解决方案

我将 IMG2SVG 设计为一个本地优先 (Local-First) 的工具，专注于在 Web 浏览器中即时、私密地解决从栅格到矢量的转换。

核心工作流非常直观：

加载与选择： 用户通过上传面板或选择以前保存在本地的文件来提供栅格图像。
预处理： 在尝试绘制矢量之前，系统应用可配置的滤镜（Box Blur、中值滤波或 K-Means 聚类量化）。这稳定了噪声并简化了原始图像的结构。
矢量化： 图像被跟踪并转换为数学指令 (SVG)。所有密集的计算过程都从主界面中抽象出来，以避免操作卡顿。
视觉迭代： 用户调整配置并应用更改。工具在本地持久化保存结果和所使用的配置，允许在以后的会话中恢复确切的工作。

2. 整体架构与结构模式

为了确保最佳性能并保持计算核心与视图之间的解耦，我将项目结构建立在职责清晰分离的基础上，重点关注面向密集型处理的渐进式 Web 应用 (PWA)。

“Local-First” 模型与计算下放

业务逻辑需要在客户端进行密集型处理 (CPU-bound)。因此，我将像素预处理层和矢量化完全委托给了 Web Workers。

graph TD
    UI[界面与状态层] -->|发送数据与参数| Worker[Web Worker: imageTracerJS + 预处理]
    Worker -->|返回 SVG 字符串| UI
    UI <-->|读取 / 持久化| IDB[(IndexedDB)]

该设计防止了高昂的操作（如 K-Means 质心计算或矢量路径跟踪）阻塞主线程 (Main Thread)，从而保持用户界面的流畅。

3. 数据建模与状态逻辑

应用的状态分为两个主要维度：用于实时交互的易失性内存和用于长期存储的持久性内存。

持久化存储

我使用 IndexedDB 来存储本地实体，而不依赖于外部后端。我定义了一个主要实体 ImageRecord，它不仅存储原始二进制文件和生成的 SVG，还存储所使用的精确配置。

erDiagram
    ImageRecord {
        number id PK
        string name
        Blob originalBlob
        string previewUrl
        string svgContent
        number createdAt
        number updatedAt
        Object settings
    }

响应式状态管理

用户界面的短暂与全局状态通过单个不可变状态树（使用 Zustand 实现）进行管理。

classDiagram
    class AppState {
        +number currentImageId
        +boolean processing
        +number progress
        +VectorizerSettings settings
        +String[] detectedColors
        +String[] hiddenColors
        +setCurrentImageId(id)
        +setProcessing(bool)
        +updateSettings(settings)
    }
    class VectorizerSettings {
        +number ltres
        +number qtres
        +number preprocessBlur
        +number preprocessQuantize
        +...
    }
    AppState *-- VectorizerSettings

这种分离使我能够轻松地通过从数据库加载 ImageRecord 并将其 settings 直接应用于 AppState 来再水化应用，从而精确恢复用户的会话。

4. 技术栈

技术的选择回应了在高级性能与可维护、强类型的架构之间取得平衡的需求。

技术	架构角色	技术考量
Astro	路由框架与核心结构。	利用群岛架构促进静态站点的生成，减少主线程上的 JavaScript 负担并启用原生 PWA (`@vite-pwa/astro`)。
React	构建交互式 UI（组件）。	作为 Islands 架构应用 (`client:only="react"`)，仅用于掌控复杂的矢量化和视觉迭代动态逻辑。
Zustand	短暂全局状态管理。	提供轻量级的发布/订阅机制，避免与 Context API 相关的无用重新渲染循环。
Dexie.js	持久化层 (IndexedDB Wrapper)。	简化异步事务，并为浏览器中 Blob 的强壮存储提供复合索引。
Web Workers	计算子进程隔离。	偏转图像预处理（中值滤镜、K-Means）和 `imagetracerjs` 的调用，以释放主线程。
Tailwind CSS	基于实用程序的样式系统。	允许保持 CSS 在视觉上与组件紧密耦合，而无需增加外部文件中的认知负担，确保对 Dark Mode 的适应。
Biome.js	统一的 Linter 和 Formatter。	替代传统的 ESLint/Prettier 流水线，为 TypeScript 代码提供更快的（基于 Rust）语法分析。

总结

IMG2SVG 中实现的架构表明，现代 Web 生态系统完全有能力支持传统上与桌面资源或重型客户端-服务器架构绑定的应用。通过利用 Web Workers 下放计算负担并利用 IndexedDB 构建强韧的本地优先体验，系统保证了隐私、性能与确定性。通过 Zustand 进行的状态封装和过程的异步分段，将一系列密集的数学任务转化为用于矢量操作的流畅且可靠的交互式工作流。