map-grabber

获取地址的 OpenStreetMap 矢量数据（街道、建筑物）并导出到 SVG、GeoPackage 或 CAD/Rhino 的 DXF。

# Map Grabber

Get site base maps from OpenStreetMap: provide an address, receive street network and optional building footprints as vector data (SVG, GeoPackage, or DXF) for use in CAD or Rhino.

## Dependencies

- `osmnx` (OSM data and graph; requires `geopandas`, `networkx`)
- `ezdxf` (optional; for DXF export)

**Setup:** OpenClaw does not install Python packages automatically. After installing this skill, run once: `pip install -r requirements.txt` (from the skill folder). If a script fails with `ModuleNotFoundError`, install the missing package (osmnx pulls geopandas; for DXF add ezdxf).

## Usage

### Grab map by address

**Parameters:**

- `address`: Address or place name (e.g. "SoHo, New York" or "123 Main St, Los Angeles").
- `--dist`: Radius in meters around the point (default 500).
- `--buildings`: Also download building footprints.
- `--svg`: Output path for SVG (street network plot).
- `--png`: Output path for PNG (same map as image; use for Telegram or preview).
- `--gpkg`: Output path for GeoPackage (streets and optionally buildings as layers).
- `--dxf`: Output path for DXF (requires ezdxf; for CAD/Rhino).

At least one of `--svg`, `--png`, `--gpkg`, or `--dxf` is required.

```bash
# PNG for Telegram + GeoPackage
python3 scripts/grab_map.py "Times Square, New York" --dist 400 --png site.png --gpkg site.gpkg

# With buildings and DXF
python3 scripts/grab_map.py "Shanghai Tower, Shanghai" --dist 500 --buildings --png site.png --gpkg site.gpkg --dxf site.dxf
```

Output: street network (and optionally buildings) in the requested formats.

## Sending images to Telegram

Used from the OpenClaw Telegram conversation. To show the user the map: run the script with **`--png <path>.png`** (e.g. `--png site.png`), then **send that PNG** to the conversation via the OpenClaw message/media tool. Use `--png` (not only `--svg`) when the user expects an image in chat.

**OpenClaw allowed paths:** The message tool only sends files from allowed dirs (`~/.openclaw/media/`, `~/.openclaw/agents/`, or `/tmp`). Use e.g. `--png ~/.openclaw/media/site.png` or `--png /tmp/site.png`; do not use the skill install directory or sending will fail.

**Agent behavior:** When the user asks for a site map, base map, or OSM map (by address or place name), **run the script directly** using `exec`: call `grab_map.py` with the given address, `--png <path>.png` with `<path>` under an allowed dir (and optional `--dist`, `--buildings`), then send the generated PNG to the user. Do not ask for confirmation; execute and return the image and a short confirmation.

## Examples

**User:** "Get me a site base map for 123 Main St" or "抓一张这个地址的场地底图."  
**Action:** Run `grab_map.py "123 Main St" --png /tmp/site.png` (or similar path), then send the PNG to the user and confirm.

**User:** "Get me a site base map for 123 Main St as SVG and DXF."  
**Action:** Run `grab_map.py` with that address, `--svg`, `--dxf`, and optionally `--png` for chat; return the file paths and confirmation.

**User:** "I need OSM data for this address with building footprints for Rhino."  
**Action:** Run with `--buildings`, `--gpkg` and optionally `--dxf`; if they want an image in chat, also use `--png` and send it.

---

## 中文说明

# Map Grabber

从 OpenStreetMap 获取场地底图：提供一个地址，即可得到以矢量数据（SVG、GeoPackage 或 DXF）形式呈现的街道网络和可选的建筑物轮廓，供 CAD 或 Rhino 使用。

## 依赖项

- `osmnx`（OSM 数据和图；需要 `geopandas`、`networkx`）
- `ezdxf`（可选；用于 DXF 导出）

**安装设置：** OpenClaw 不会自动安装 Python 包。安装本技能后，运行一次：`pip install -r requirements.txt`（在技能文件夹中执行）。如果脚本因 `ModuleNotFoundError` 失败，请安装缺失的包（osmnx 会带入 geopandas；如需 DXF 则额外安装 ezdxf）。

## 用法

### 按地址抓取地图

**参数：**

- `address`：地址或地名（例如 "SoHo, New York" 或 "123 Main St, Los Angeles"）。
- `--dist`：以该点为中心的半径（米，默认 500）。
- `--buildings`：同时下载建筑物轮廓。
- `--svg`：SVG 的输出路径（街道网络绘图）。
- `--png`：PNG 的输出路径（同一地图的图像形式；用于 Telegram 或预览）。
- `--gpkg`：GeoPackage 的输出路径（街道，可选地将建筑物作为图层）。
- `--dxf`：DXF 的输出路径（需要 ezdxf；用于 CAD/Rhino）。

`--svg`、`--png`、`--gpkg` 或 `--dxf` 中至少需要提供一个。

```bash
# PNG for Telegram + GeoPackage
python3 scripts/grab_map.py "Times Square, New York" --dist 400 --png site.png --gpkg site.gpkg

# With buildings and DXF
python3 scripts/grab_map.py "Shanghai Tower, Shanghai" --dist 500 --buildings --png site.png --gpkg site.gpkg --dxf site.dxf
```

输出：以请求的格式呈现的街道网络（以及可选的建筑物）。

## 向 Telegram 发送图像

在 OpenClaw 的 Telegram 对话中使用。要向用户展示地图：运行脚本时带上 **`--png <path>.png`**（例如 `--png site.png`），然后通过 OpenClaw 的消息/媒体工具将该 PNG **发送**到对话中。当用户期望在聊天中看到图像时，请使用 `--png`（不要只用 `--svg`）。

**OpenClaw 允许的路径：** 消息工具只发送允许目录中的文件（`~/.openclaw/media/`、`~/.openclaw/agents/` 或 `/tmp`）。请使用例如 `--png ~/.openclaw/media/site.png` 或 `--png /tmp/site.png`；不要使用技能安装目录，否则发送会失败。

**代理行为：** 当用户请求场地图、底图或 OSM 地图（通过地址或地名）时，使用 `exec` **直接运行脚本**：以给定地址调用 `grab_map.py`，使用 `--png <path>.png`，其中 `<path>` 位于允许目录下（并可选地带上 `--dist`、`--buildings`），然后将生成的 PNG 发送给用户。无需请求确认；直接执行并返回图像和简短的确认信息。

## 示例

**用户：** "Get me a site base map for 123 Main St" 或 "抓一张这个地址的场地底图."  
**操作：** 运行 `grab_map.py "123 Main St" --png /tmp/site.png`（或类似路径），然后将 PNG 发送给用户并确认。

**用户：** "Get me a site base map for 123 Main St as SVG and DXF."  
**操作：** 以该地址运行 `grab_map.py`，带上 `--svg`、`--dxf`，并可选地为聊天加上 `--png`；返回文件路径和确认信息。

**用户：** "I need OSM data for this address with building footprints for Rhino."  
**操作：** 带上 `--buildings`、`--gpkg`，并可选地带上 `--dxf` 运行；如果他们想在聊天中看到图像，也使用 `--png` 并发送。