# 图片转矢量

> 示例：
> - `vjcad/example/insert/vectorize/01insertimage.js` — INSERTIMAGE 命令
> - `vjcad/example/insert/vectorize/02vectorizeapi.js` — VectroizeConfig + parseSvgToWebcad
> 文档：`vjcad/doc/insert/index.md`

把 PNG / JPG / GIF / WebP 转成矢量实体（基本流程：栅格 → SVG → vjcad 实体）。

## 1. 命令方式

```js
// 前提：已加载 insert-plugin（PluginManager.loadByName('vcad-plugin-insert') 或宿主应用自带）
await Engine.editor.executerWithOp('INSERTIMAGE');
Engine.zoomExtents();
```

`INSERTIMAGE` 弹出对话框：

- **导入方式**：选择文件 / 拖放 / `Ctrl+V` 粘贴
- **聚类**：`黑白` / `彩色`，彩色又分 `切除` / `堆叠`
- **斑点过滤** `0~128`，**颜色精度** `1~8`，**渐变步长** `0~128`
- **曲线模式**：`像素` / `多边形` / `样条`，样条还有 `拐角阈值` / `线段长度` / `连接阈值`
- **导入选项**：`启用填充` / `允许缩放` / `允许旋转`
- 实时预览 SVG 与 WebCAD 转换结果

## 2. API 方式

`VectroizeService` 由 `insert-plugin` 插件提供（独立装载），返回 SVG 字符串再走 `parseSvgToWebcad` 即可。`vjcad/example/insert/vectorize/02vectorizeapi.js` 演示完整流程：

```js
// 1. 准备 RGBA 像素数据（Canvas 或 ImageData）
const ctx = canvas.getContext('2d');
const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
const pixelData = new Uint8Array(imageData.data.buffer);

// 2. 配置矢量化参数
const config = {
    colorMode:      'color',   // 'color' | 'binary'
    hierarchical:   'stacked', // 'stacked' | 'cutout'，仅彩色生效
    pathMode:       'spline',  // 'pixel' | 'polygon' | 'spline'
    filterSpeckle:   4,         // 0~128，斑点过滤
    colorPrecision:  6,         // 1~8，颜色精度
    layerDifference: 16,        // 0~128，渐变步长
    cornerThreshold: 60,        // 0~180°，仅样条
    lengthThreshold: 4,         // 3.5~10
    spliceThreshold: 45,        // 0~180°
    pathPrecision:   8,         // 0~8，SVG 数字精度
};

// 3. 调用插件转 SVG（伪代码，需 insert-plugin）
// const { getVectroizeService } = await import('insert-plugin');
// const svgContent = await getVectroizeService()
//     .convertToSvg(pixelData, canvas.width, canvas.height, config);

// 4. SVG → vjcad 实体（同 svg-import）
const wasmService = getWebCadCoreService();
await wasmService.initWasm();
const webcadData = await wasmService.parseSvgToWebcad(svgContent, 0, 0, 1, 1, 1.0);
// ... 装临时 CadDocument，clone 实体后 Engine.addEntities
```

> 完整代码（含构造测试图、临时 CadDocument 装载、move 到插入点）：`vjcad/example/insert/vectorize/02vectorizeapi.js`

## 3. VectroizeConfig 字段

| 字段 | 类型 / 取值 | 说明 |
|---|---|---|
| `colorMode` | `'color' \| 'binary'` | 彩色 / 黑白 |
| `hierarchical` | `'stacked' \| 'cutout'` | 颜色层级（仅彩色） |
| `pathMode` | `'pixel' \| 'polygon' \| 'spline'` | 曲线拟合方式 |
| `filterSpeckle` | 0~128 | 过滤面积小于此值的斑点 |
| `colorPrecision` | 1~8 | 颜色种类数（仅彩色） |
| `layerDifference` | 0~128 | 渐变层差（仅彩色） |
| `cornerThreshold` | 0~180° | 拐角识别（仅样条） |
| `lengthThreshold` | 3.5~10 | 曲线段长度（仅样条） |
| `spliceThreshold` | 0~180° | 拼接连接阈值（仅样条） |
| `pathPrecision` | 0~8 | 输出 SVG 数字精度 |

## 4. 模式选择经验

| 输入 | 推荐 |
|---|---|
| 工程线稿 / 黑白图 | `colorMode: binary` + `pathMode: spline` + `filterSpeckle: 4` |
| 截图带文字 | `colorMode: color` + `pathMode: polygon` + 高 `colorPrecision` |
| Logo / 图标 | `colorMode: color` + `pathMode: spline` + `filterSpeckle: 8` |
| 手绘扫描 | 提高 `cornerThreshold` 减少锯齿 |

## 红旗

- `INSERTIMAGE` 命令默认会把白色当作背景，**导入后看似"少了线"** 时，先确认源图是不是白底（`whiteColorProcessing` 设成 `2 过滤` 反而会丢失白色线条）
- 大图（>4MP）建议先压缩，避免聚类阶段内存峰值过高
- `pixel` 模式生成的实体数量爆炸（一像素一段），仅供调试，不建议直接保存
- 实体颜色不是 `CECOLOR`：`parseSvgToWebcad` 把 SVG 里的颜色写成真彩色 `0x1000000 | 0xRRGGBB`（`binary` 模式的 SVG 只有单色，导入后也是该 RGB 真彩色）；深色背景下黑线看不清时用 `blackColorProcessing: 1`（反色）

## 参考（官方文档 MCP）

- 示例：
- `vjcad/example/insert/vectorize/01insertimage.js` — INSERTIMAGE 命令
- `vjcad/example/insert/vectorize/02vectorizeapi.js` — VectroizeConfig + parseSvgToWebcad
- 文档：`vjcad/doc/insert/index.md`