# MapEditor

**Repository Path**: rogers34/map-editor

## Basic Information

- **Project Name**: MapEditor
- **Description**: 轻量地图编辑工具，兼容ROS2格式
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-22
- **Last Updated**: 2026-06-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="center">
  <img src="map-editor-preview.jpg" alt="MapEditor 界面预览" width="800">
</p>

<h1 align="center">MapEditor</h1>

<p align="center">
  <strong>ROS2 栅格地图编辑器 — 纯前端 · 免部署 · 仿 Windows 画图</strong>
</p>

<p align="center">
  <img alt="License" src="https://img.shields.io/badge/license-MIT-blue.svg">
  <img alt="Platform" src="https://img.shields.io/badge/platform-web-brightgreen">
  <img alt="ROS2" src="https://img.shields.io/badge/ROS2-nav2-orange">
</p>

<p align="center">
  <a href="#特性">特性</a> •
  <a href="#快速开始">快速开始</a> •
  <a href="#使用指南">使用指南</a> •
  <a href="#ros2-地图格式">格式说明</a> •
  <a href="#项目结构">项目结构</a>
</p>

---

MapEditor 是一个纯前端、零依赖的 ROS2 栅格地图编辑工具，支持 PGM/YAML 格式地图的导入、像素级编辑、路径点（Waypoint）与电子围栏（Fence）的绘制管理。采用 Windows 画图风格的 Ribbon 工具栏布局，浏览器直接运行，无需任何后端或部署。

## 特性

- **ROS2 地图导入** — 一键导入 `.pgm` + `.yaml` 格式地图，自动解析 resolution、origin、negate 等参数
- **像素编辑** — 铅笔、直线、橡皮、填充，支持画笔大小和颜色选择
- **路径点 (Waypoint)** — 放置、拖拽移动、拖拽调整方向、重命名，方向箭头实时可视化
- **电子围栏 (Fence)** — 多边形绘制、顶点拖拽、整体平移、区域填充色，支持闭合/开放
- **版本管理** — 版本号与编辑备注，自动写入 YAML 注释和 JSON 元数据
- **工程目录** — 导入时设置工程目录，所有导出默认定位到该目录
- **撤销/重做** — 复合快照，像素与矢量数据同时恢复
- **矢量导入导出** — JSON 格式，完整保留路径点/围栏的 ID、名称、角度、颜色等属性
- **属性面板** — 选中元素后右侧显示，支持 ID/名称/坐标/角度/颜色等字段在线编辑
- **高亮选中** — 选中路径点发光外圈、围栏发光外框、方向手柄提示

## 快速开始

直接在浏览器中打开 `index.html` 即可。由于 Canvas API 在 `file://` 协议下受限，需要使用 HTTP 服务器：

```bash
# Python
python -m http.server 3000

# Node.js
npx http-server -p 3000

# PowerShell (Windows 内置)
powershell -Command "Start-Process 'http://localhost:3000'"
Start-Process powershell -ArgumentList '-NoExit -Command
  $l=New-Object System.Net.HttpListener;
  $l.Prefixes.Add('http://localhost:3000/'); $l.Start();
  while($l.IsListening){$c=$l.GetContext();
  $p=if($c.Request.Url.LocalPath -eq '/'){'/index.html'}else{$c.Request.Url.LocalPath};
  $f='.'+$p; if(Test-Path $f){$b=[IO.File]::ReadAllBytes((Resolve-Path $f));
  $c.Response.ContentType='text/html'; $c.Response.OutputStream.Write($b,0,$b.Length)}
  $c.Response.Close()}"
```

然后浏览器打开 `http://localhost:3000`。

## 使用指南

### 菜单栏

| 菜单 | 功能 |
|------|------|
| **文件** | 导入/导出地图工程、导入/导出矢量 JSON、新建地图、设置工程目录 |
| **编辑** | 撤销、重做、清空地图 |
| **视图** | 缩放、适应窗口、显示栅格 |
| **矢量** | 导入/导出 JSON |
| **帮助** | 关于 |

### 工具栏

工具栏分为工具区、颜色区、尺寸区和版本备注区：

| 工具 | 快捷键 | 用途 |
|------|--------|------|
| 编辑 | `S` | 选择、拖拽、移动路径点和围栏；空白处拖拽平移 |
| 平移 | `H` | 拖拽画布 |
| 铅笔 | `P` | 像素级绘制 |
| 直线 | `L` | 拖动绘制直线 |
| 橡皮 | `E` | 擦除像素（涂白） |
| 填充 | `F` | 洪水填充 |
| 路径点 | `W` | 创建和编辑路径点 |
| 围栏 | `G` | 创建电子围栏 |

### 路径点操作

**创建**：路径点模式下点击画布空白 → 放置 → 拖拽调整方向 → 松手确定。

**编辑**（路径点模式或编辑模式均可）：

| 操作 | 方式 |
|------|------|
| 调整方向 | 点击箭头尖端橙色手柄 → 拖拽 |
| 移动 | 编辑模式下点击主体圆点 → 拖拽 |
| 删除 | 选中后按 `Delete` / 右键菜单删除 |
| 重命名 | 右键菜单重命名 / 双击主体 |
| 属性 | 选中后右侧面板编辑坐标、角度、名称、类型 |

### 围栏操作

**创建**：围栏模式下依次点击 → 点击首点闭合 / 右键闭合 / 双击闭合。

**编辑**（编辑模式）：

| 操作 | 方式 |
|------|------|
| 移动顶点 | 点击顶点拖拽 |
| 删除顶点 | 双击顶点 |
| 整体拖拽 | 点击围栏内部区域 → 拖拽 |
| 选中/属性 | 点击内部区域 → 侧边栏编辑名称、颜色 |
| 删除 | 选中后 `Delete` / 右键菜单 |
| 重命名 | 右键菜单 |

### 快捷键

| 键 | 功能 |
|----|------|
| `P` `L` `E` `F` | 铅笔 / 直线 / 橡皮 / 填充 |
| `W` `G` `S` `H` | 路径点 / 围栏 / 编辑 / 平移 |
| `Delete` / `Backspace` | 删除选中元素 |
| `Ctrl+Z` / `Ctrl+Y` | 撤销 / 重做 |
| `Ctrl++` / `Ctrl+-` | 放大 / 缩小 |
| `Ctrl+0` | 重置缩放 |

### 右键菜单

选中路径点或围栏后右键，弹出浮动菜单，提供重命名和删除操作。

### 属性侧边栏

选中元素后右侧自动展开属性面板，支持在线编辑字段，修改即时生效。

| 路径点 | 围栏 |
|--------|------|
| ID（只读）、名称、X、Y、角度、类型 | ID（只读）、名称、颜色、顶点数、状态 |

## ROS2 地图格式

### 导入转换

按 [nav2 map_server](https://github.com/ros-navigation/navigation2) 标准公式逐像素转换：

```
negate=0:  occ = (255 - pixel_val) / 255.0
negate=1:  occ = pixel_val / 255.0

occ ≥ occupied_thresh → 占用 → 黑色 RGB(0,0,0)
occ ≤ free_thresh     → 空闲 → 白色 RGB(254,254,254)
其余                  → 未知 → 灰色 RGB(178,178,178)
```

从 YAML 中读取 `negate`、`occupied_thresh`、`free_thresh` 参数。

### 导出 YAML

```yaml
image: map.pgm
resolution: 0.05
origin: [-10.0, -10.0, 0.0]
negate: 0
occupied_thresh: 0.65
free_thresh: 0.196
# MapEditor 版本: 3
# 备注: 仓库A区 - 增加了北侧通道围栏
```

### 导出 JSON (nav_elements.json)

```json
{
  "type": "MapEditor Vector Data",
  "edition_version": 3,
  "edition_notes": "仓库A区 - 增加了北侧通道围栏",
  "waypoints": [
    { "id": "wp_1", "x": 100, "y": 200, "angle": 1.57, "name": "充电点", "type": "normal" }
  ],
  "fences": [
    { "id": "fence_1", "name": "禁区", "points": [...], "closed": true, "color": "#ff4444" }
  ]
}
```

## 交互优先级

点击检测顺序保证操作预期：

1. 路径点箭头尖端 → 调方向
2. 路径点主体圆点 → 拖拽移动
3. 围栏顶点 → 拖拽顶点
4. 围栏内部区域 → 选中 + 整体拖拽

各模式下检测范围不同：路径点模式不检测围栏内部，围栏模式不检测其他围栏。

## 技术栈

- **纯 HTML5 + CSS3 + JavaScript**（ES2020）
- **Canvas API** — 像素渲染与叠加图层
- **File System Access API** — 系统文件保存对话框
- **showSaveFilePicker / showDirectoryPicker** — 导出路径选择

## 项目结构

```
Map-Editor/
├── index.html                  # 主页面
├── map-editor-preview.jpg      # 效果预览图
├── README.md
├── css/
│   └── style.css               # 全部样式
└── js/
    ├── app.js                  # 主控制器、菜单、快捷键、矢量交互
    ├── canvasManager.js        # 画布引擎、缩放、平移、渲染、撤销
    ├── mapParser.js            # ROS2 PGM/YAML 解析与生成
    ├── tools.js                # 铅笔、直线、橡皮、填充工具
    ├── waypoints.js            # 路径点管理与渲染
    ├── fences.js               # 电子围栏管理与渲染
    └── vectorIO.js             # 矢量 JSON 导入导出
```

## 浏览器兼容

| 特性 | Chrome / Edge 86+ | 其他浏览器 |
|------|:-----------------:|:----------:|
| 画布编辑 | ✓ | ✓ |
| 文件保存对话框 | ✓ | 降级为 `<a download>` |
| 目录选择 | ✓ | 不支持 |
| 目录批量写入 | ✓ | 降级为逐文件保存 |

## License

MIT