# ar-tag-system

**Repository Path**: yeti1/ar-tag-system

## Basic Information

- **Project Name**: ar-tag-system
- **Description**: AR标签系统 - 一个基于Web的增强现实标签管理应用，支持实时视频流上的AR标签创建、编辑和管理
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-10-11
- **Last Updated**: 2025-11-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AR 视频流标签叠加系统 🚀

一个基于 FastAPI 和 AI 视觉模型的实时视频流AR标签叠加系统，支持多协议视频流播放、智能图像识别、动态标签管理和高级绘制功能。

## ✨ 功能特性

### 🎥 **多协议视频流播放**
- **HLS 支持**: 基于 HLS.js 的 HTTP Live Streaming 播放
- **FLV 支持**: 基于 flv.js 的 Flash Video 流播放  
- **RTMP 支持**: 基于 Video.js 的实时流媒体协议支持
- **自动协议检测**: 智能识别视频流协议类型
- **实时状态监控**: 显示视频状态、帧率、分辨率、当前协议等信息

### 🏷️ **AR 标签系统**
- **图片标签**: 支持多种 AR 素材（立方体、球体、钻石、星星、三角形等）
- **表情标签**: 丰富的 SVG 表情图标库（微笑、大笑、酷表情、爱心眼等）
- **文字标签**: 动态文字叠加，支持字体大小、颜色、位置调整
- **拖拽交互**: 实时拖拽调整标签位置，支持边界检测
- **缩放控制**: 图片标签支持实时缩放，带有可视化控制点
- **动画效果**: 支持标签动画效果（缩放、透明度变化等）

### 🎨 **高级绘制工具**
- **钢笔工具**: 精确路径绘制，支持路径闭合检测（20像素容差）
- **套索工具**: 自由形状绘制，智能路径闭合
- **样式控制**: 
  - 填充色和边框色独立设置
  - 透明度实时调整（0-1范围）
  - 线条宽度控制（1-10像素）
- **路径管理**: 
  - 实时路径预览
  - 路径闭合状态检测
  - 绘制项目列表管理
- **交互功能**: 
  - 绘制模式切换
  - 绘制项目删除
  - 样式实时编辑

### 🤖 **AI 图像识别**
- **智能识别**: 集成豆包视觉模型，识别图像中的对象、人物、车辆等
- **实时处理**: 支持视频帧截取和实时AI分析
- **格式转换**: 自动将上传图像转换为JPG格式，支持尺寸调整

### 🌐 **现代化 Web 界面**
- **响应式设计**: 支持多设备访问的现代化UI
- **标签页管理**: 图片标签、文字标签、绘制标签分类管理
- **实时预览**: Canvas实时渲染，支持视频流和标签叠加
- **优化布局**: 
  - 颜色选择器单行布局优化
  - Flexbox响应式布局
  - 现代化渐变背景和毛玻璃效果

### ⚡ **性能优化**
- **高性能渲染**: 基于Canvas的高效绘制引擎
- **智能重绘**: 按需重绘机制，优化性能
- **异步处理**: FastAPI异步HTTP服务
- **内存管理**: 智能的动画帧管理和资源释放

## 🏗️ 项目结构

```
ar/
├── server.py              # FastAPI 主服务器
├── pyproject.toml         # 项目配置和依赖
├── .python-version        # Python 版本配置
├── .gitignore            # Git 忽略文件配置
├── src/                  # 源代码目录
│   ├── ai.py            # AI 图像识别模块
│   └── image_converter.py # 图像格式转换模块
├── static/              # 静态文件目录
│   ├── index.html       # 主页面（包含绘制功能和优化的UI布局）
│   ├── js/             # JavaScript 库
│   │   ├── hls.min.js  # HLS 视频流支持
│   │   ├── flv.min.js  # FLV 视频流支持
│   │   └── video.min.js # Video.js 播放器
│   ├── images/         # 图标和图片资源
│   │   ├── ar-*.svg    # AR 相关图标
│   │   └── *-emoji.svg # 表情图标
│   └── uploads/        # 上传文件存储目录
└── uv.lock             # 依赖锁定文件
```

## 🛠️ 技术栈

### 后端技术
- **Web框架**: FastAPI - 高性能异步Web框架
- **Python版本**: Python 3.9+
- **AI模型**: 豆包视觉模型 (doubao-seed-1-6-vision)
- **图像处理**: Pillow (PIL) - 图像格式转换和处理
- **HTTP服务**: Uvicorn - ASGI服务器
- **文件上传**: python-multipart - 多部分文件上传支持

### 前端技术
- **核心技术**: HTML5, CSS3, JavaScript (ES6+)
- **视频流播放**:
  - HLS.js - HTTP Live Streaming 支持
  - flv.js - Flash Video 流播放
  - Video.js - 通用视频播放器
- **绘制引擎**: Canvas API - 高性能2D绘制
- **UI布局**: 
  - Flexbox - 响应式布局
  - CSS Grid - 复杂布局管理
  - CSS3 渐变和毛玻璃效果
- **交互功能**:
  - 事件处理 - 鼠标和触摸事件
  - 动态DOM操作 - 实时UI更新
  - 拖拽API - 标签拖拽功能
- **包管理**: uv - 现代Python包管理器

## 📋 系统要求

- Python 3.9 或更高版本
- uv 包管理器

## 🚀 快速开始

### 1. 克隆项目

```bash
git clone <repository-url>
cd ar
```

### 2. 安装依赖

```bash
# 使用 uv 安装依赖
uv sync
```

### 3. 配置环境

在 `src/ai.py` 中配置你的 AI 模型 API 密钥：

```python
# 在 ask_ai 函数中更新你的 API 配置
client = OpenAI(
    base_url="your-api-base-url",
    api_key="your-api-key"
)
```

### 4. 启动服务

```bash
# 使用 uv 运行服务器
uv run python server.py
```

服务器将在 `http://localhost:5657` 启动。

## 📖 API 文档

### 主要端点

- `GET /` - 主页面
- `POST /upload` - 文件上传和处理
- `GET /docs` - API 文档 (Swagger UI)
- `GET /redoc` - API 文档 (ReDoc)

### 文件上传 API

```http
POST /upload
Content-Type: multipart/form-data

Parameters:
- file: 上传的图像文件
- input_xpath: 可选的 XPath 参数
```

**响应**: 返回处理后的图像路径或 AI 识别结果

## 🎯 使用示例

### 图像上传和识别

1. 访问 `http://localhost:5657`
2. 选择要上传的图像文件
3. 系统自动进行格式转换和 AI 识别
4. 查看识别结果

### 绘制功能使用

1. **启用绘制模式**
   - 点击绘制模式按钮激活绘制功能
   - 选择绘制工具（钢笔、矩形、圆形等）

2. **设置绘制样式**
   - 使用优化的颜色选择器设置填充色和边框色
   - 调整透明度滑块控制绘制元素的透明度
   - 所有设置实时生效，支持动态预览

3. **绘制操作**
   - 钢笔工具：自由绘制，支持路径闭合检查
   - 几何图形：点击拖拽创建矩形、圆形等
   - 实时渲染：绘制过程中实时显示效果

4. **管理绘制项目**
   - 查看绘制项目列表
   - 编辑或删除已创建的绘制元素
   - 动态更新绘制设置

### 程序化调用

```python
import requests

# 上传图像文件
with open('image.jpg', 'rb') as f:
    files = {'file': f}
    response = requests.post('http://localhost:5657/upload', files=files)
    result = response.text
    print(result)
```

## 🔧 配置说明

### 图像转换配置

在 `src/image_converter.py` 中可以调整：

- **质量设置**: 默认 JPG 质量为 90
- **尺寸调整**: 支持按比例或固定尺寸调整
- **格式支持**: 自动处理 RGBA 透明背景

### AI 模型配置

在 `src/ai.py` 中可以配置：

- **模型选择**: 当前使用豆包视觉模型
- **提示词**: 自定义图像识别的提示词
- **参数调整**: temperature, top_p, max_tokens 等

## 📁 静态资源

项目包含丰富的静态资源：

- **图标**: AR 相关的 SVG 图标 (立方体、钻石、球体等)
- **表情**: 各种 emoji SVG 图标
- **视频库**: 支持 HLS 和 FLV 视频流播放

## 🤝 贡献指南

1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🆘 故障排除

### 常见问题

1. **依赖安装失败**
   ```bash
   # 确保使用正确的 Python 版本
   python --version  # 应该是 3.9+
   
   # 重新安装依赖
   uv sync --reinstall
   ```

2. **AI 模型调用失败**
   - 检查 API 密钥是否正确配置
   - 确认网络连接正常
   - 查看服务器日志获取详细错误信息

3. **文件上传失败**
   - 检查 `static/uploads/` 目录权限
   - 确认文件大小在允许范围内
   - 验证文件格式是否支持

4. **绘制功能异常**
   - 检查浏览器是否支持 Canvas API
   - 确认 JavaScript 控制台无错误信息
   - 验证颜色选择器和透明度控制是否正常工作
   - 如果钢笔绘制路径未闭合，检查控制台日志获取详细信息

## 📞 联系方式

如有问题或建议，请通过以下方式联系：

- 提交 Issue
- 发起 Pull Request
- 邮件联系: [your-email@example.com]

---

⭐ 如果这个项目对你有帮助，请给它一个星标！