neroued-vectorizer 0.2.0

High-quality raster-to-SVG vectorization

neroued_vectorizer

高质量栅格到矢量（raster-to-SVG）C++ 库，将位图自动转换为平滑的多色 SVG。

效果展示

特性

• 双管线架构：V1（边界图 + 剪切模型）和 V2（层叠模型 + 深度排序）
• V2 管线：OKLab MMCQ 感知量化、深度排序画家算法、形状延伸消除缝隙、路径优化、同色合并、覆盖率修补
• V1 管线：SLIC 超像素 + K-Means、Schneider 曲线拟合、Potrace + Clipper2 拓扑修复
• 亚像素边界细化
• 薄线增强、抗锯齿边缘检测
• 可选 ICC 色彩管理（lcms2）
• 质量评估模块（PSNR / SSIM / Delta E / Chamfer 距离）
• CLI 工具：raster_to_svg、evaluate_svg
• Python 绑定：pip install neroued-vectorizer

依赖

依赖	版本	说明
OpenCV	>= 4.5	core, imgproc, imgcodecs
Potrace	-	系统库 libpotrace-dev
spdlog	>= 1.14	自动通过 FetchContent 获取
Clipper2	>= 2.0	自动通过 FetchContent 获取
nanosvg	-	vendored，SVG 解析（eval/tests 使用）
lcms2	-	可选，ICC 色彩管理
libjpeg	-	可选，配合 lcms2
OpenMP	-	可选，并行加速

系统依赖安装

Ubuntu / Debian:

sudo apt install libopencv-dev libpotrace-dev liblcms2-dev libjpeg-dev

macOS (Homebrew):

brew install opencv potrace little-cms2 jpeg

构建

mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . -j$(nproc)

构建选项

选项	默认值	说明
NV_BUILD_EVAL	ON	构建质量评估库
NV_BUILD_APPS	ON	构建 CLI 工具
NV_BUILD_TESTS	ON	构建单元测试
NV_BUILD_PYTHON	OFF	构建 Python 绑定（需要 pybind11）

仅构建核心库：

cmake .. -DNV_BUILD_EVAL=OFF -DNV_BUILD_APPS=OFF -DNV_BUILD_TESTS=OFF

安装

cmake --install build --prefix /usr/local

安装内容包括：头文件、静态库（libneroued_vectorizer.a、libneroued_vectorizer_eval.a）、CLI 工具。

CLI 工具

raster_to_svg

将栅格图像转换为 SVG：

./build/apps/raster_to_svg --image input.png --out output.svg

常用参数：

参数	默认值	说明
--image	必需	输入图像路径
--out	同目录 .svg	输出 SVG 路径
--colors	0	量化颜色数（0 = 自动）
--smoothness	0.5	轮廓平滑度 [0,1]
--detail-level	-1	统一细节控制 [0,1]（-1 = 禁用）
--curve-fit-error	0.8	曲线拟合误差阈值
--min-region	50	最小区域面积（像素²）
--upscale-short-edge	600	短边自动放大阈值
--log-level	info	日志级别
--pipeline	v1	管线模式：v1 或 v2

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

evaluate_svg

评估矢量化质量：

# 单图评估
./build/apps/evaluate_svg --image input.png --json report.json

# 批量评估
./build/apps/evaluate_svg --manifest manifest.json --baseline-dir baselines/

常用参数：

参数	说明
--image FILE	单图模式，输入图像路径
--manifest FILE	批量模式，Manifest JSON 路径
--svg-dir DIR	SVG 输出目录
--json FILE	指标/报告输出 JSON 路径
--baseline-dir DIR	基线目录，用于回归对比
--set-baseline	保存当前结果为新基线
--history FILE	CSV 历史文件，追加运行摘要
--category CAT	仅运行指定类别的图像（批量模式）
--note TEXT	注释，存入历史/报告
--log-level LEVEL	日志级别（默认 info）

矢量化参数覆盖（与 raster_to_svg 相同）可通过 --help 查看。

Python 绑定

安装

pip install neroued-vectorizer

从源码构建（需要系统已安装 OpenCV 和 Potrace）：

pip install .

Python 用法

import neroued_vectorizer as nv

# 从文件路径
result = nv.vectorize("photo.png")

# 从内存字节
with open("photo.png", "rb") as f:
    result = nv.vectorize(f.read())

# 从 numpy 数组（BGR/BGRA/GRAY uint8）
import numpy as np
img = np.zeros((100, 100, 3), dtype=np.uint8)
result = nv.vectorize(img)

# 自定义配置
config = nv.VectorizerConfig()
config.num_colors = 8
config.curve_fit_error = 1.0
result = nv.vectorize("photo.png", config)

# 使用 V2 层叠管线
config = nv.VectorizerConfig()
config.pipeline_mode = nv.PipelineMode.V2
result = nv.vectorize("photo.png", config)

# 使用结果
print(result.svg_content)       # SVG 文档字符串
print(result.width, result.height)
print(result.num_shapes)
print(result.palette)           # list[nv.Rgb]

# 保存
result.save("output.svg")

VectorizerConfig 的所有参数与 C++ 版本一致，参见下方参数表。

库集成

CMake add_subdirectory

add_subdirectory(path/to/neroued_vectorizer EXCLUDE_FROM_ALL)
target_link_libraries(your_target PRIVATE neroued::vectorizer)

CMake FetchContent

include(FetchContent)
FetchContent_Declare(neroued_vectorizer
    GIT_REPOSITORY https://github.com/neroued/neroued_vectorizer.git
    GIT_TAG master)
FetchContent_MakeAvailable(neroued_vectorizer)
target_link_libraries(your_target PRIVATE neroued::vectorizer)

API

#include <neroued/vectorizer/vectorizer.h>

using namespace neroued::vectorizer;

// 从文件路径
VectorizerConfig config;
config.num_colors = 8;
auto result = Vectorize("input.png", config);

// 从内存缓冲区（ICC 感知）
auto result = Vectorize(data_ptr, data_size, config);

// 从 cv::Mat
cv::Mat image = cv::imread("input.png");
auto result = Vectorize(image, config);

// 使用结果
std::cout << "SVG shapes: " << result.num_shapes << "\n";
std::cout << "Palette: " << result.palette.size() << " colors\n";
std::ofstream("output.svg") << result.svg_content;

VectorizerConfig 完整参数

适用范围：V1+V2 = 两条管线共用，V1 = 仅 V1 边界图管线，V2 = 仅 V2 层叠管线。

参数	类型	默认值	适用	说明
管线选择
pipeline_mode	PipelineMode	V1	V1+V2	管线实现：V1（经典边界图）或 V2（层叠模型）
颜色分割
num_colors	int	0	V1+V2	调色板颜色数，0 = 自动检测
min_region_area	int	50	V1+V2	最小区域面积（像素²）
曲线拟合
curve_fit_error	float	0.8	V1+V2	曲线拟合误差阈值（V1: Schneider 拟合, V2: 路径合并）
corner_angle_threshold	float	135.0	V1	角点检测角度阈值（度）
smoothness	float	0.5	V1	轮廓平滑度 [0,1]
预处理
smoothing_spatial	float	15.0	V1+V2	Mean Shift 空间窗口半径
smoothing_color	float	25.0	V1+V2	Mean Shift 颜色窗口半径
upscale_short_edge	int	600	V1+V2	短边自动放大阈值（0 = 禁用）
max_working_pixels	int	3000000	V1+V2	自动缩小像素阈值（0 = 禁用）
SLIC 分割
slic_region_size	int	20	V1	SLIC 目标区域大小
slic_compactness	float	6.0	V1	SLIC 紧致度
edge_sensitivity	float	0.8	V1	边缘感知空间权重衰减 [0,1]
refine_passes	int	6	V1	边界标签细化迭代次数
max_merge_color_dist	float	200.0	V1+V2	小区域合并最大 LAB ΔE²
亚像素边界
enable_subpixel_refine	bool	true	V1	启用梯度引导亚像素细化
subpixel_max_displacement	float	0.7	V1	亚像素最大法向位移
抗锯齿检测
enable_antialias_detect	bool	false	V1	启用 AA 混合边缘检测
aa_tolerance	float	10.0	V1	AA 混合像素最大 LAB ΔE
薄线增强
thin_line_max_radius	float	2.5	V1	距离变换半径阈值
SVG 输出
svg_enable_stroke	bool	true	V1+V2	启用描边输出
svg_stroke_width	float	0.5	V1+V2	描边宽度
细节控制
detail_level	float	-1.0	V1	统一细节控制 [0,1]（-1 = 禁用）
merge_segment_tolerance	float	0.05	V1+V2	近线性贝塞尔段合并容差
Potrace 管线
min_contour_area	float	10.0	V1+V2	最小轮廓面积
min_hole_area	float	4.0	V1+V2	最小孔洞面积
contour_simplify	float	0.45	V1+V2	轮廓简化强度
enable_coverage_fix	bool	true	V1+V2	启用覆盖率修补
min_coverage_ratio	float	0.998	V1+V2	全局覆盖率触发阈值；值越低越容忍少量缺失像素
max_unpatched_gap_area	float	0.0	V1+V2	局部缺口面积触发阈值；超过该面积即使全局覆盖率达标也会修补，负数表示禁用局部触发
诊断
enable_depth_validation	bool	false	V2	启用深度排序诊断验证

VectorizerResult

字段 / 方法	类型	说明
svg_content	string	完整 SVG 文档
width	int	图像宽度（像素）
height	int	图像高度（像素）
num_shapes	int	SVG 中的形状数
resolved_num_colors	int	实际使用的颜色数
palette	vector<Rgb> / list[Rgb]	使用的调色板
save(path)	Python only	将 SVG 内容保存到文件

目录结构

neroued_vectorizer/
├── include/neroued/vectorizer/   # 公共头文件
│   ├── vectorizer.h              # 主 API
│   ├── config.h                  # VectorizerConfig
│   ├── result.h                  # VectorizerResult
│   ├── color.h                   # 颜色类型（Rgb, Lab）
│   ├── vec2.h / vec3.h           # 向量类型
│   ├── error.h                   # 错误类型
│   └── logging.h                 # 日志初始化
├── src/                          # 内部实现（按管线阶段组织）
│   ├── preprocess/               # 预处理（缩放、Mean Shift）
│   ├── segment/                  # 颜色分割（SLIC、K-Means、形态学）
│   ├── boundary/                 # 边界提取（图构建、亚像素、AA检测）
│   ├── contour/                  # 轮廓装配（链式装配、薄线）
│   ├── curve/                    # 曲线拟合（贝塞尔、Schneider、路径优化）
│   ├── trace/                    # 追踪（Potrace、覆盖率、拓扑修复）
│   ├── stacking/                 # V2 层叠模型（深度排序、形状延伸）
│   ├── quantize/                 # V2 OKLab MMCQ 颜色量化
│   ├── output/                   # 输出（SVG 写入、形状合并）
│   └── detail/                   # 内部工具（cv_utils、icc_utils）
├── python/                       # Python 绑定
│   ├── neroued_vectorizer/       # Python 包（__init__.py、类型桩）
│   ├── bindings.cpp              # pybind11 绑定代码
│   └── tests/                    # Python 测试
├── eval/                         # 质量评估库
├── apps/                         # CLI 工具
├── ci/                           # CI 依赖安装脚本
└── tests/                        # 单元测试

版本管理与发布

版本号由 git tag 自动派生（基于 setuptools-scm）：

• v0.2.0 tag → PyPI 版本 0.2.0
• tag 后的开发提交 → 0.2.1.dev3+gabcdef

发布流程

# 1. 预发布验证（自动发到 TestPyPI）
git tag v0.2.0rc1
git push origin v0.2.0rc1

# 2. 验证 TestPyPI 上的包
pip install --index-url https://test.pypi.org/simple/ \
            --extra-index-url https://pypi.org/simple/ \
            neroued-vectorizer==0.2.0rc1

# 3. 正式发布（自动发到 PyPI）
git tag v0.2.0
git push origin v0.2.0

支持平台

平台	架构	Python
Linux	x86_64	3.10 – 3.14
macOS	arm64	3.10 – 3.14
Windows	x86_64	3.10 – 3.14

许可证

本项目使用 GPL-3.0-or-later 许可证。