# tools

**Repository Path**: idcu/tools

## Basic Information

- **Project Name**: tools
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-16
- **Last Updated**: 2026-04-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 设备标注工具

在图纸上标注设备（摄像头、路灯、网桥等）的位置和朝向角度，支持 Excel 导入导出和标注图片生成。

## 功能特性

- **设备标注**：在图纸上点击放置设备，拖拽调整位置，旋转调整朝向
- **多种设备类型**：预置枪机、球机、路灯、网桥等，支持自定义颜色、图标、旋转基点
- **显示设置**：十字线、方向线（可调起点/长度）、视野扇形（角度/半径）、原点标记、网格
- **标注内容**：可配置显示编号、类型、坐标、角度等标签
- **Excel 导入导出**：批量导入设备坐标，导出标注数据
- **标注图片生成**：将标注结果渲染到图纸上导出 PNG
- **多端同步**：支持轮询和 WebSocket 两种实时同步模式
- **多图纸管理**：上传和切换多张图纸

## 技术栈

| 层 | 技术 |
|---|------|
| 后端 | Python 3.8+ 标准库 HTTP 服务器 |
| 前端 | 原生 HTML/CSS/JavaScript（无框架依赖） |
| 图片处理 | Pillow |
| Excel | pandas + openpyxl |
| 实时同步 | websockets（可选） |

## 项目结构

```
device_marker/
├── server.py                # 主入口，启动 HTTP 服务
├── config.py                # 配置管理（路径、设备类型、设置）
├── requirements.txt         # Python 依赖
├── backend/
│   ├── handlers.py          # HTTP 请求处理器（API 路由）
│   ├── ws_server.py         # WebSocket 实时同步服务
│   ├── excel_ops.py         # Excel 导入导出
│   └── upload_handler.py    # 文件上传处理
├── frontend/
│   ├── index.html           # 主页面
│   ├── css/style.css        # 样式表
│   └── js/app.js            # 前端逻辑（Canvas 渲染、交互）
├── utils/
│   ├── image_gen.py         # 标注图片生成（Pillow 渲染）
│   └── multipart.py         # Multipart 表单解析
├── config/
│   ├── app_settings.json    # 应用配置（端口、默认设置、渲染参数）
│   └── device_types.json    # 设备类型定义
├── icons/                   # 设备图标 PNG 文件
├── uploads/                 # 上传的图纸图片
├── outputs/                 # 生成的标注图片
└── data/                    # 运行时数据（cameras_data.json）
```

## 快速开始

### 环境要求

- Python 3.8+
- 现代浏览器（Chrome / Firefox / Edge）

### 安装依赖

```bash
pip install -r requirements.txt
```

可选依赖（WebSocket 实时同步）：

```bash
pip install websockets
```

### 启动服务

```bash
cd device_marker
python server.py
```

浏览器访问 `http://localhost:8080`

### 首次使用

1. 上传图纸：点击「上传图纸」按钮，选择图片文件（支持 PNG/JPG/BMP/TIFF）
2. 放置设备：在图纸上点击放置设备，选择设备类型
3. 调整属性：在右侧面板调整角度、类型、显示设置等
4. 导出数据：点击「导出 Excel」保存标注数据
5. 生成图片：点击「生成标注图」导出带标注的 PNG 图片

## API 接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/` | 主页面 |
| GET | `/api/image-info` | 获取当前图纸信息（宽高、文件名） |
| GET | `/api/image` | 获取当前图纸图片 |
| GET | `/api/icon/{name}.png` | 获取设备图标 |
| POST | `/api/save` | 保存标注数据（含 settings） |
| GET | `/api/data` | 获取标注数据 |
| GET | `/api/export` | 导出 Excel |
| GET | `/api/template` | 下载 Excel 导入模板 |
| POST | `/api/import` | 导入 Excel |
| GET | `/api/generate-image` | 生成标注图片 |
| POST | `/api/upload-image` | 上传图纸 |
| GET | `/api/images` | 列出已上传图纸 |
| GET | `/api/device-types` | 获取设备类型列表 |
| POST | `/api/device-types` | 更新设备类型 |
| GET | `/api/settings` | 获取当前设置 |
| WS | `ws://localhost:8081` | WebSocket 实时同步 |

## 配置说明

配置文件位于 `config/app_settings.json`：

```json
{
  "server": {
    "port": 8080,
    "max_upload_size_mb": 50,
    "sync_mode": "poll",
    "sync_poll_interval": 3,
    "ws_port": 8081
  },
  "defaults": {
    "iconSize": 28,
    "labelSize": 13,
    "showIcon": true,
    "showCrosshair": false,
    "showDirection": false,
    "showFov": false,
    "showOrigin": false,
    "showGrid": false
  }
}
```

### 显示设置参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| iconSize | int | 28 | 图标大小（px） |
| labelSize | int | 13 | 标签字号（px） |
| showIcon | bool | true | 显示/隐藏图标 |
| showCrosshair | bool | false | 十字线 |
| showDirection | bool | false | 方向线 |
| directionStartX | float | 50 | 方向线起点 X%（图标未旋转时） |
| directionStartY | float | 50 | 方向线起点 Y%（图标未旋转时） |
| directionLength | int | 30 | 方向线长度（px） |
| showFov | bool | false | 视野扇形 |
| fov | int | 90 | 视野角度（0-180°） |
| fovRadius | int | 80 | 视野半径（px） |
| showOrigin | bool | false | 原点标记 |
| originX | float | 0 | 原点 X 位置（背景图百分比） |
| originY | float | 0 | 原点 Y 位置（背景图百分比） |
| showGrid | bool | false | 网格 |
| gridX | int | 100 | 网格 X 间距（px） |
| gridY | int | 100 | 网格 Y 间距（px） |
| labelShowId | bool | true | 标签显示编号 |
| labelShowType | bool | false | 标签显示类型 |
| labelShowCoord | bool | false | 标签显示坐标 |
| labelShowAngle | bool | false | 标签显示角度 |

## 设备类型管理

设备类型定义在 `config/device_types.json`，支持在界面上直接编辑：

| 字段 | 说明 |
|------|------|
| 名称 | 设备类型名称（如"枪机"） |
| 图标 | 图标形状（camera/dome/light/bridge/circle/diamond/triangle/square/star/pin） |
| 颜色 | 十六进制颜色值（如 #ea4335） |
| 基点 X% / Y% | 旋转基点在图标上的百分比位置（左下角 0,0） |

预置设备类型：

| 类型 | 颜色 | 图标 | 基点 |
|------|------|------|------|
| 枪机 | #ea4335 | camera | (11.7%, 69.1%) |
| 球机 | #1a73e8 | dome | (49.6%, 29.7%) |
| 路灯 | #ff9800 | light | (49.6%, 10.2%) |
| 网桥 | #4caf50 | bridge | (50.0%, 16.4%) |

## Excel 导入格式

导入模板可通过「下载模板」获取，格式如下：

| id | x | y | angle | typeName |
|----|---|---|-------|----------|
| 1 | 100 | 200 | 45 | 枪机 |
| 2 | 300 | 400 | 90 | 球机 |

- `x`, `y`：设备在图纸上的像素坐标
- `angle`：设备朝向角度（0°=右，逆时针为正）
- `typeName`：设备类型名称，需与系统中已有类型匹配

## 前后端渲染一致性

前端 Canvas 渲染和后端 Pillow 渲染保持参数一致，确保「所见即所得」：

| 渲染元素 | 关键参数 |
|----------|----------|
| 十字线 | rgba(234,67,53,0.3), dash=[4,4] |
| 方向线 | 起点=图标百分比旋转映射, 线宽=3, 箭头=10px/30° |
| 视野 | 填充alpha=0.15, 描边alpha=0.5 |
| 原点 | 半径=8, 描边=2, 标签="(0,0)" |
| 网格 | rgba(0,0,0,0.08), 线宽=1 |
| 标签 | 白字黑边, 偏移=iconSize×2.2 |

## 键盘快捷键

| 快捷键 | 功能 |
|--------|------|
| Delete | 删除选中设备 |
| Ctrl+S | 保存数据 |
| Ctrl+Z | 撤销 |
| 滚轮 | 缩放画布 |
| 右键拖拽 | 平移画布 |

## 许可证

MIT License