Inkvec

Inkvec 是一款将 PNG、JPEG、WebP、GIF、BMP 或 TIFF 转换为 SVG 的命令行工具。与多数依赖容差滑块的描摹器不同，它的几何输出由像素中的实际证据决定：边界位置依据抗锯齿信号解析（在合成测试圆上误差约 0.05 像素），圆形直接写为 <circle> 标签而非贝塞尔曲线近似，平滑渐变还原为真正的 SVG 渐变而非色带，坐标数量通过最小描述长度（MDL）自动选择，无需人工猜测参数。

这种设计使 Inkvec 的输出更接近艺术家手动绘制的矢量文件。每个区域对应一条路径，圆形保持原生图元，相邻形状共享的边缘不会因独立拟合而漂移分离。其目标不是追求速度或通用性，而是在标志、图标、图表等图形艺术场景中提供高保真、低冗余的矢量结果。

性能对比：质量优先于速度

在包含 21 个案例的基准测试中（14 个真实图标、4 个合成探针、3 个品牌标志），Inkvec 与 VTracer、Trazor 进行了横向比较。评估指标包括 CIEDE2000 颜色误差（DE00）、DISTS 感知相似度、DINOv3 语义一致性及坐标数量：

• Inkvec：平均 DE00 0.132，中位 DE00 0.054，坐标数 446，耗时 1.17 秒。
• VTracer（默认）：平均 DE00 1.303，坐标数 1,943（约为 Inkvec 的 4.4 倍），耗时 0.04–0.05 秒。
• VTracer（调优）：平均 DE00 1.264，坐标数 1,239（2.8 倍），耗时 0.06 秒。
• Trazor：平均 DE00 0.518，坐标数 1,172（2.6 倍），耗时 2.19 秒。

VTracer 显著更快，但这是以几何精度和输出简洁性为代价的权衡。Inkvec 的坐标数最少，颜色误差最低，且生成的 SVG 结构更干净。值得注意的是，color-trace（potrace-color）被排除在主表之外，因其本质是逐像素重绘而非几何描摹，在同一测试集中坐标数高达 25,018，约为 Inkvec 的 124 倍。

在 246 个图标的回归语料库上，Inkvec 的中位 DE00 为 0.125，p90 为 0.612，仅 13 个案例高于 1.0。均值 0.299 受少数离群值拉高，典型图标表现稳定。所有基准数据均可通过仓库脚本复现，CI 门控会在颜色误差或参数比劣化超过阈值时自动失败。

安装与基础用法

Inkvec 提供预构建二进制文件，也可从源码编译（需 Rust 1.88+）：

# 从 Releases 下载预构建版本，或从源码安装
cargo install --path crates/inkvec-cli

# 基本转换
inkvec logo.png -o logo.svg

执行后会输出详细处理日志，包括调色板分析、平面图构建、边界求解迭代次数、线段压缩比等。退出代码 0 表示成功，1 为用法错误，2 为 --strict 模式下检测到扁平输入，3 为调试转储失败。

常用选项包括：

• --restore <auto|on|off>：启用训练恢复器清理 JPEG/WebP/AI 解码损伤，默认关闭。
• --sr <auto|on|off>：超分辨率预处理（2-4× 放大），与恢复器互补。
• --lossy <auto|on|off>：控制是否信任输入为干净源，或以噪声感知方式描摹。
• --max-dim <px>：长边上限，默认 2048，SVG 仍以原始尺寸写入。
• --minify：移除 id、组、尾随零，体积减小约 10%，几何不变。
• --no-background：丢弃覆盖整个画布的背景面。

完整参数列表可通过 inkvec --help 查看。

可选功能与多平台支持

Inkvec 的核心几何管线完全确定性，不依赖神经网络。但针对受损输入，提供了可选的训练恢复器模块：

• restore-model：通过 ONNX Runtime 运行，CPU 执行，构建时自动下载预编译运行时。
• restore-burn：纯 Rust 实现，无原生依赖，速度慢约 4 倍。
• restore-wgpu：通过 Burn 在 GPU 上运行，支持 Vulkan/DX12/Metal，无需 CUDA。

去噪器权重托管于 Hugging Face（Logolabs/inkvec-denoiser-001，Apache-2.0 许可），首次使用 --restore 时自动拉取，也可手动执行 python tools/pull_model.py。

此外，crates/inkvec-wasm 将完整管线编译为 WebAssembly，可在浏览器中直接使用，无需上传文件。在线演示地址为 huggingface.co/spaces/logolabs/inkvec。库 API 也对外暴露，Rust 项目可直接调用 trace_image 函数集成相同管线。

技术边界与适用场景

Inkvec 专为图形艺术设计，对以下场景存在明确限制：

• 照片：自然颜色过渡违反离散墨水模型，会导致严重色带和高坐标数。建议保留为 AVIF/WebP 或使用扩散曲线。
• 文本与排版：仅作为几何轮廓描摹，无 OCR 或 <text> 标签生成。语义文本处理应使用 Tesseract 等专用引擎。
• 可变宽度素描：中轴笔画恢复要求均匀线宽，粗糙素描会退化为填充轮廓。
• 亚像素间隙（<1px）：抗锯齿斜坡可能合并细小间隙，可尝试 --sr on 先上采样。
• 复杂渐变：仅支持线性与径向渐变，网格渐变、角度扫描等会被量化为色带。
• 实时视频：单帧处理约需 1.2 秒，不适合 60 FPS 场景。交互级速度应选用 Potrace 或 VTracer。

这些限制源于其核心算法对精确平面分区和描述长度模型的依赖，并非工程缺陷。开发者在 docs/LIMITATIONS.md 中提供了完整的架构边界披露。