---
title: 图形分析
source: https://vjmap.com/guide/service/api/04-analysis.html
---

# 图形分析

> 分类代号：C.4  本章共 **6 个接口**

这一组接口都是 vjmap 的"增值分析"能力，参数差异大、且对输入的 DWG/图像质量要求很高，因此 SDK 采用 **pass-through** 风格：你按下面文档组参数，SDK 负责 POST 与错误处理，**不做参数字段级强校验**。

全部走 `POST /api/v1/map/cmd/{cmd}/_null/v1`（`_null` 表示不绑定具体 mapid，参数里自带）。

---

## 快速索引

| 序号 | SDK 方法 | cmd |
|----:|---------|------|
| 30 | `cmd_map_diff` / `cmdMapDiff` | `mapDiff` |
| 31 | `cmd_map_compare` / `cmdMapCompare` | `mapCompare` |
| 32 | `cmd_extract_table` / `cmdExtractTable` | `extractTable` |
| 33 | `cmd_extract_center_lines` / `cmdExtractCenterLines` | `extractCenterLines` |
| 34 | `cmd_match_object` / `cmdMatchObject` | `objectMatch` |
| 35 | `cmd_image_svg_to_dwg` / `cmdImageSvgToDwg` | `imageSvgToDwg` |

---

## 30 · 像素差异 `mapDiff`

比较两张 DWG **渲染成图片后的像素差异**，返回增删改的像素块外包矩形中心点。

### 请求参数

| 字段 | 类型 | 说明 |
|------|------|------|
| `mapid1` / `version1` | string | 旧图 |
| `mapid2` / `version2` | string | 新图 |
| `darkMode` | bool | 是否使用暗色底渲染 |
| `bufferSize` | int | 像素容差，相同像素在此距离内不判为"改" |
| `mergeClose` | bool | 合并靠得很近的差异块 |

### 响应（实采：同图 vs 同图）

```json
{
  "del": "",
  "modify": "",
  "new": "",
  "status": true
}
```

有差异时 `del` / `modify` / `new` 是 `x1,y1,x2,y2;x3,y3,x4,y4` 格式的字符串；`svc.cmd_map_diff()` 不做 parse，调用方按需切分。

### Python

```python
res = svc.cmd_map_diff(
    mapid1="sys_zp", version1="v1",
    mapid2="sys_zp", version2="v2",
    bufferSize=5,
)
```

---

## 31 · 实体对比 `mapCompare`

和 `mapDiff` 不同：`mapCompare` 比较的是 **DWG 实体**，不是渲染像素。

### 请求参数

| 字段 | 类型 | 说明 |
|------|------|------|
| `mapid1` / `version1`, `mapid2` / `version2` | string | 两张图 |
| `tolerancePos` | number | 坐标容差 |
| `toleranceAngle` | number | 角度容差（度） |



后端会先做一次快速 hash 去重。真实对比时返回：

```json
{
  "status": true,
  "add": [...],       // 仅在新图存在的实体 id
  "del": [...],       // 仅在旧图存在
  "modify": [...]     // 两边都有但有差异
}
```

### Python

```python
svc.cmd_map_compare(mapid1="a", version1="v1", mapid2="a", version2="v2")
```

---

## 32 · 表格提取 `extractTable`

自动从 DWG 里识别"线条围出来的表格"，返回单元格网格与每格文本。**最常用**于检图、清单导出。

### 请求参数

| 字段 | 说明 |
|------|------|
| `mapid` / `version` | 要识别的图 |
| `layer` | 可选，只在某 style / layer 上跑 |
| `bbox` | 可选，限定在地图坐标系下的 bbox |
| `minCellWidth` / `minCellHeight` | 最小单元格尺寸阈值 |

### 响应（实采：sys_zp/v1，无额外参数）

```json
{
  "tables": [{
    "attr": {
      "cellEmptyRatio": 45,
      "tableCellMaxCount": 70,
      "tableTextCount": 39,
      "unLinkLineRatio": 0
    },
    "colCount": 4,
    "cols": ["587693680.21", "587698180.22", "587717259.64", "..."],
    "datas": [["类目", "数量", "价格", "说明"], [...]],
    "rows": ["...", "..."]
  }]
}
```

- `cols` / `rows`：单元格网格线的坐标；
- `datas[i][j]`：每格文本（可能含编码乱码，视 DWG 字体而定）。

### Python

```python
res = svc.cmd_extract_table(mapid="sys_zp", version="v1")
for t in res.get("tables", []):
    print(t["colCount"], "x", len(t["rows"]))
```

### Node.js

```javascript
const res = await svc.cmdExtractTable({ mapid: 'sys_zp', version: 'v1' });
console.log(res.tables?.length);
```

---

## 33 · 中心线提取 `extractCenterLines`

对闭合多边形（如道路、管线）抽取中心线。

### 请求参数

| 字段 | 说明 |
|------|------|
| `mapid` / `version` | 源图 |
| `layer` | 可选，限定 layer |
| `expr` | 可选，按属性过滤实体（与 queryFeatures 的 expr 同义） |

### 响应（实采：sys_zp/v1）

```json
{
  "centerlines": [
    [[587562497.79, 3103857885.77], [587556239.69, 3103860401.38]],
    [[587603886.22, 3103921932.46], [587602627.19, 3103925333.77]]
  ]
}
```

`centerlines` 是"多段折线数组"；每条线由若干 `[x, y]` 顶点构成。

### Python

```python
res = svc.cmd_extract_center_lines(mapid="sys_zp", version="v1")
for line in res["centerlines"]:
    print("line with", len(line), "verts")
```

---

## 34 · 目标匹配 `objectMatch`

在底图中找与模板图形相似的子图（样式 + 尺寸）。常用于批量识别图章、标注块、设备。

### 请求参数

| 字段 | 类型 | 默认值 | 说明 |
|------|------|-------|------|
| `mapid` / `version` | string | — | 底图 |
| `templateMapid` / `templateVersion` | string | — | 模板图 |
| `objectBounds` | string / number[] | — | **必填**：模板所在的 bbox（地图坐标） `[x1,y1,x2,y2]` |
| `score` | number | 0.6 | 相似度阈值 |
| `canOverlap` | bool | false | 命中框是否允许重叠 |
| `maxOverlap` | number | 0.3 | 允许的最大重叠比例 |
| `toleranceAngle` | number | 180 | 角度容差（度），180 = 任意旋转 |
| `minReduceArea` | number | 256 | 小于此面积的命中框被忽略 |

### 响应


成功时返回：

```json
{
  "status": true,
  "matches": [
    { "bounds":"[x1,y1,x2,y2]", "angle": 0.0, "score": 0.92 },
    ...
  ]
}
```

### Python

```python
res = svc.cmd_match_object(
    mapid="sys_zp", version="v1",
    templateMapid="sys_zp", templateVersion="v1",
    objectBounds="[587661000,3103886000,587661200,3103886200]",
    score=0.7, toleranceAngle=90,
)
```

---

## 35 · SVG / 图像转 DWG `imageSvgToDwg`

把 SVG 字符串或位图转换成 DWG 实体。对位图会先做线条检测 + 矢量化。

### 请求参数

| 字段 | 说明 |
|------|------|
| `svgData` | SVG 文本 |
| `imageUrl` | 远程图片 URL（与 svgData 二选一） |
| `threshold` | 位图二值化阈值（0–255） |
| `mapid` / `version` | 可选：把结果直接写入该地图；为空则只返回 DWG JSON |

### 响应（实采：svgData="`<svg></svg>`"，空内容）

```json
{
  "error": "image or svg content is empty",
  "status": false
}
```

合法输入时返回：

```json
{
  "status": true,
  "mapdata": "<DWG JSON 字符串>"
}
```

可以把 `mapdata` 传给 `create_entity_geo_data`（见 [03-query.md](./03-query.md)）渲染。

---

## 通用注意

1. 这组接口都可能 **耗时 >10s**，SDK 默认 timeout=60s，建议在业务层再做重试与超时兜底。
2. 后端遇到参数非法时常返回 `{"error": "...", "status": false}`——不是 HTTP 4xx/5xx。SDK 会把它当成 2xx 正常响应返回给调用方。
3. 返回 `"status": false` 时 `error` 字段的语言**依系统 locale 而定**（我们这里抓到了中/英混合的错误串）。

---