🗺️ Map Geometry API

服务健康状态检查接口

响应示例

{
  "status": "ok"
}

在地图图像上规划从起点（绿色）到终点（红色）的避障路径，返回路径坐标和可视化图像。

请求头

请求体 (JSON)

注意：表格中的“字段默认值”是底层字段在没有模式预设时的默认值。实际调用会先应用 path_mode / passage_mode 的模式预设， 再用请求中显式传入的同名字段覆盖。因此在默认 path_mode=safe 下，部分字段的实际生效值会不同，例如 hard_clearance=0.09、center_danger_corridors=true、soft_clearance=0.16。

路径模式与兼容规则

推荐新调用只传 path_mode / passage_mode 表达意图；一周前的旧调用形式仍然兼容。 服务端执行顺序为：path_mode 预设 → passage_mode 预设 → 请求中显式传入的底层参数覆盖。 因此旧字段如 planner、force_s_bend、hard_clearance、soft_clearance 仍然有效。

响应状态码

200 成功（业务错误通过响应体 ok=false 表示） 400 请求参数错误 404 Artifact 不存在或已过期

响应体 (点击展开)

{
  "ok": true,
  "error_message": "",

	  // --- 模式信息 ---
	  "mode": "deterministic",
	  "path_mode": "safe",
	  "passage_mode": "auto",
	  "planner": "grid_astar",
  "planner_mode_requested": "auto",
  "force_s_bend": false,
  "tight_mode": false,
  "simplify_target": "auto",
  "show_waypoints": false,

  // --- 图像信息 (Object) ---
  "image": {
    "width": 800,      // 图像宽度（像素）
    "height": 600     // 图像高度（像素）
  },

  // --- 坐标角点 (Object) ---
  "corners": {
    "top_left": [-16.1, 20.71],      // 左上角世界坐标 [X, Y]
    "bottom_right": [36.45, -12.24]  // 右下角世界坐标 [X, Y]
  },

  // --- 起点终点坐标 (Object) ---
  "start_world": {
    "X": ...,
    "Y": ...
  },
  "end_world": {
    "X": ...,
    "Y": ...
  },

  // --- 路径轨迹 (Array of Object) ---
  "trajectory": [
    { "X": -10.5, "Y": 15.2 },
    { "X": -8.3, "Y": 14.8 },
    // ... 更多路径点
  ],
  "waypoints": [...],    // 与 trajectory 相同
  "original_path": [...],  // 原始直线路径（参考用）

  "waypoint_count": 25,

  // --- 规划参数 ---
  "obstacle_extraction": {
    "supersample": 2.0,
    "dilate": 0
  },
  "interpretation_applied": null | Object,
  "grid_max_dim": 320,
  "planning_upscale": 1,
  "planning_upscale_applied": 1,
  "chord_bias": 0.42,
  "slalom_corridor": true,

  // --- 文件下载链接 ---
  "artifact_id": "abc123xyz",
  "overlay_preview_url": "http://host/v1/artifacts/abc123xyz/overlay.png",
  "path_csv_url": "http://host/v1/artifacts/abc123xyz/path.csv",
  "overlay_image_url": "...",   // overlay_preview_url 的别名
  "csv_online_url": "...",         // path_csv_url 的别名
  "visualization_png": "/path/to/overlay.png"
}

错误响应示例

{
  "ok": false,
  "error_message": "download image failed: ..." | "invalid numeric parameter: ...",
  "mode": "deterministic",
  "planner": "",
  "waypoints": [],
  "trajectory": []
}

获取路径规划可视化叠加图的 PNG 图像文件。使用 Content-Disposition: inline 可直接在浏览器预览。

路径参数

响应头

响应状态码

200 PNG 图像文件 404 Artifact 不存在或已过期

获取路径坐标的 CSV 文件。每行包含一个路径点的 X, Y 世界坐标。使用 Content-Disposition: attachment 触发下载。

路径参数

响应头

CSV 格式

X1,Y1
X2,Y2
X3,Y3
...

响应状态码

200 CSV 文件 404 Artifact 不存在或已过期

interpretation_json 用来告诉服务端“哪些像素是障碍物、哪个像素区域是起点、哪个像素区域是终点”。 它是一个 JSON 字符串，不是 JSON 对象；如果不传，服务端使用默认解释规则：黑色/深色为障碍物，绿色为起点，红色为终点。

该配置支持“局部覆盖”：只传其中一段时，其他段会继续使用默认值。例如只想指定起终点像素，可以只传 start 和 end。 像素坐标使用 PIL/图像坐标系：左上角为 (0,0)，向右为 X 正方向，向下为 Y 正方向。

默认解释规则

{
  "version": 1,
  "obstacle": {
    "mode": "rgb_dark",
    "max_channel": 54,
    "min_alpha": 16
  },
  "start": {
    "mode": "green_dominant",
    "g_min": 80,
    "delta": 20
  },
  "end": {
    "mode": "red_dominant",
    "r_min": 100,
    "delta": 20
  }
}

默认分类顺序为：透明像素忽略 → 障碍物 → 起点 → 终点 → 其他。也就是说，如果某个像素同时满足障碍物和起点规则，会先被当作障碍物。

JSON Schema (点击展开)

{
  "version": 1,

  // --- 障碍物配置 ---
  "obstacle": {
    "mode": "rgb_dark" | "luminance_below" | "luminance_above",
    "max_channel": 54,        // rgb_dark 模式: R,G,B 都 <= 此值为障碍物
    "threshold": 30,          // luminance 模式: 亮度阈值
    "min_alpha": 16            // 最小透明度，低于此值被忽略
  },

  // --- 起点配置 ---
  "start": {
    "mode": "green_dominant" | "pixel",
    "g_min": 80,                // green_dominant: G >= 此值
    "delta": 20,              // green_dominant: G > R+delta 且 G > B+delta
    "x": 100,                 // pixel 模式: 像素 X 坐标
    "y": 200                  // pixel 模式: 像素 Y 坐标
  },

  // --- 终点配置 ---
  "end": {
    "mode": "red_dominant" | "pixel",
    "r_min": 100,               // red_dominant: R >= 此值
    "delta": 20,               // red_dominant: R > G+delta 且 R > B+delta
    "x": 500,                  // pixel 模式: 像素 X 坐标
    "y": 300                   // pixel 模式: 像素 Y 坐标
  }
}

API 中如何传 interpretation_json

因为请求体本身已经是 JSON，所以 interpretation_json 的值需要是转义后的字符串。

{
  "image_url": "https://example.com/map.png",
  "top_left_x": "-16.1",
  "top_left_y": "20.71",
  "bottom_right_x": "36.45",
  "bottom_right_y": "-12.24",
  "interpretation_json": "{\"start\":{\"mode\":\"pixel\",\"x\":306,\"y\":268},\"end\":{\"mode\":\"pixel\",\"x\":352,\"y\":420}}"
}

常见用法

障碍物模式说明

示例：自定义深蓝色障碍物

{
  "version": 1,
  "obstacle": {
    "mode": "luminance_below",
    "threshold": 30,
    "min_alpha": 16
  },
  "start": {
    "mode": "green_dominant",
    "g_min": 80,
    "delta": 20
  },
  "end": {
    "mode": "red_dominant",
    "r_min": 100,
    "delta": 20
  }
}

新模式：最小安全优先调用

curl -X POST http://localhost:8788/v1/plan/deterministic \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/map.png",
    "top_left_x": "-16.1",
    "top_left_y": "20.71",
    "bottom_right_x": "36.45",
    "bottom_right_y": "-12.24"
  }'

不传 path_mode 时默认使用 safe，会自动启用硬安全距离、危险通道居中和软安全距离预设。

新模式：末段外扩 + 右侧通过

curl -X POST http://localhost:8788/v1/plan/deterministic \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/map.png",
    "top_left_x": "-16.1",
    "top_left_y": "20.71",
    "bottom_right_x": "36.45",
    "bottom_right_y": "-12.24",
    "path_mode": "terminal_wide",
    "passage_mode": "prefer_right"
  }'

新模式：强制 S 弯紧贴

curl -X POST http://localhost:8788/v1/plan/deterministic \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/map.png",
    "top_left_x": "-16.1",
    "top_left_y": "20.71",
    "bottom_right_x": "36.45",
    "bottom_right_y": "-12.24",
    "path_mode": "s_bend_tight"
  }'

旧模式兼容：保持旧版普通默认

curl -X POST http://localhost:8788/v1/plan/deterministic \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/map.png",
    "top_left_x": "-16.1",
    "top_left_y": "20.71",
    "bottom_right_x": "36.45",
    "bottom_right_y": "-12.24",
    "path_mode": "legacy",
    "safety": "0.09",
    "planner": "auto",
    "segments": "10",
    "lateral": "0.35"
  }'

legacy 不主动启用新的安全预设，适合需要复现旧接口默认行为的调用方。

旧模式兼容：一周前的强制 S 弯紧贴写法

curl -X POST http://localhost:8788/v1/plan/deterministic \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/map.png",
    "top_left_x": "-16.1",
    "top_left_y": "20.71",
    "bottom_right_x": "36.45",
    "bottom_right_y": "-12.24",
    "planner": "auto",
    "force_s_bend": "true",
    "tight_mode": "true"
  }'

旧字段仍然生效。服务端会识别 force_s_bend=true 并按旧版 S 弯语义处理。

新模式 + 参数覆盖

curl -X POST http://localhost:8788/v1/plan/deterministic \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/map.png",
    "top_left_x": "-16.1",
    "top_left_y": "20.71",
    "bottom_right_x": "36.45",
    "bottom_right_y": "-12.24",
    "path_mode": "safe",
    "passage_mode": "prefer_right",
    "hard_clearance": "0.12",
    "soft_clearance": "0.24",
    "show_waypoints": "true"
  }'

模式先提供预设，显式传入的 hard_clearance、soft_clearance、show_waypoints 会覆盖模式默认值。

带 interpretation_json：指定像素起终点

curl -X POST http://localhost:8788/v1/plan/deterministic \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/map.png",
    "top_left_x": "-16.1",
    "top_left_y": "20.71",
    "bottom_right_x": "36.45",
    "bottom_right_y": "-12.24",
    "path_mode": "safe",
    "interpretation_json": "{\"start\":{\"mode\":\"pixel\",\"x\":306,\"y\":268},\"end\":{\"mode\":\"pixel\",\"x\":352,\"y\":420}}"
  }'

Python Requests 调用

import requests

response = requests.post(
    "http://localhost:8788/v1/plan/deterministic",
    json={
        "image_url": "https://example.com/map.png",
        "top_left_x": "-16.1",
        "top_left_y": "20.71",
        "bottom_right_x": "36.45",
        "bottom_right_y": "-12.24",
        "path_mode": "safe",
        "passage_mode": "auto"
    }
)
result = response.json()
print(result["overlay_preview_url"])  # 获取可视化图
print(result["path_csv_url"])          # 获取CSV下载链接