# billiards_labels

**Repository Path**: oftenlin/billiards_labels

## Basic Information

- **Project Name**: billiards_labels
- **Description**: 台球标注工具
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-03-11
- **Last Updated**: 2025-03-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 台球标注系统

这是一个用于台球桌球标注的 Web 应用，支持多种标注功能以及透视变换处理。

## 功能特性

- 多用户登录与权限管理
- 台球位置标注
- 球杆位置标注
- 台球桌透视变换
- 文件上传与管理
- 分组批量处理
- MySQL数据库存储（支持数据持久化）

## 安装与设置

### 前提条件

- Python 3.7 或以上
- pip 包管理器
- MySQL 5.7 或以上

### 安装步骤

1. 克隆项目仓库
```bash
git clone <仓库地址>
cd billiards_labels
```

2. 安装依赖
```bash
pip install -r requirements.txt
```

3. 配置MySQL数据库
```bash
# 以root身份运行初始化脚本
sudo bash migrations/init_database.sh
```
或手动执行以下SQL命令：
```sql
CREATE DATABASE IF NOT EXISTS billiards_labels CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER IF NOT EXISTS 'billiards_user'@'localhost' IDENTIFIED BY 'billiards_password';
GRANT ALL PRIVILEGES ON billiards_labels.* TO 'billiards_user'@'localhost';
FLUSH PRIVILEGES;
```

4. 迁移数据（从JSON文件到MySQL数据库）
```bash
python3 migrations/migrate_data.py
```

5. 配置应用
根据需要修改 `src/config.py` 中的设置。

6. 运行应用
```bash
python run.py
```
或使用提供的脚本
```bash
bash run.sh
```

7. 访问应用
浏览器中访问 `http://localhost:5000`

### 数据导出

如需将MySQL数据库中的数据导出为JSON文件，可以运行：
```bash
python3 migrations/export_data.py

# 可以使用以下参数选择性导出数据
python3 migrations/export_data.py --export-users       # 只导出用户数据
python3 migrations/export_data.py --export-groups      # 只导出分组数据
python3 migrations/export_data.py --export-status      # 只导出状态数据
python3 migrations/export_data.py --export-annotations # 只导出标注数据
```

## 项目结构

```
billiards_labels/
│
├── data/                       # 数据存储目录
│   ├── upload/                 # 文件上传目录
│   ├── labels/                 # 标注数据存储
│   ├── cue_labels/             # 球杆标注数据存储
│   └── perspective_config/     # 透视变换配置存储
│
├── migrations/                 # 数据库迁移相关
│   ├── models.py               # 数据库模型定义
│   ├── db_config.py            # 数据库配置
│   ├── migrate_data.py         # 数据迁移脚本
│   ├── export_data.py          # 数据导出脚本
│   └── init_database.sh        # 数据库初始化脚本
│
├── static/                     # 静态资源
│   ├── css/                    # 样式文件
│   ├── js/                     # JavaScript 文件
│   ├── img/                    # 图像资源
│   ├── perspective_images/     # 透视变换源图像
│   └── transformed/            # 透视变换后图像
│
├── templates/                  # HTML 模板
│
├── src/                        # 源代码
│   ├── app.py                  # 应用主文件
│   ├── config.py               # 配置文件
│   ├── routes/                 # 路由模块
│   │   ├── auth.py             # 认证相关路由
│   │   ├── billiards.py        # 台球标注路由
│   │   ├── cue.py              # 球杆标注路由
│   │   ├── main.py             # 主页和任务选择路由
│   │   ├── perspective.py      # 透视变换路由
│   │   └── upload.py           # 文件上传路由
│   │
│   ├── models/                 # 数据模型
│   │   ├── groups.py           # 分组模型
│   │   └── status.py           # 状态管理模型
│   │
│   └── utils/                  # 工具函数
│       ├── decorators.py       # 装饰器
│       ├── file_utils.py       # 文件处理工具
│       └── image_utils.py      # 图像处理工具
│
├── run.py                      # 应用入口文件
├── run.sh                      # 运行脚本
├── extract_frames.py           # 视频帧提取工具
└── requirements.txt            # 依赖文件
```

## 使用说明

1. 登录系统：使用分配的用户名和密码登录
2. 任务选择：在主页选择要执行的任务
3. 台球标注：标记台球位置并保存
4. 球杆标注：标记球杆位置并保存
5. 透视变换：设置台球桌变换参数并应用到图像
6. 文件管理：上传、下载或删除文件

## 透视变换功能

透视变换功能允许您：
1. 标记台球桌的四个角点
2. 设置台球桌的实际尺寸（默认为标准尺寸254cm×127cm）
3. 生成俯视图，便于进行标准化的位置分析
4. 批量应用透视变换到多张图像

## 图像分组功能

系统支持将图像分配到不同组，便于多人同时标注：
1. 管理员可以重新分配图像到指定数量的组
2. 用户登录后可以选择特定组进行标注
3. 每个组的图像及其标注状态会被单独跟踪

## 技术栈

- 后端：Flask, Python
- 图像处理：OpenCV, NumPy
- 前端：HTML, CSS, JavaScript, jQuery

## 许可证

[MIT](LICENSE) 

## 数据库架构

系统使用MySQL数据库存储所有数据，主要表结构如下：

1. `users` - 用户信息表
   - id, username, password, name, is_admin, created_at, updated_at

2. `groups` - 分组表
   - id, name, created_at, updated_at

3. `user_groups` - 用户-组关联表
   - id, user_id, group_id, created_at

4. `raw_data` - 原始数据表（存储图片元数据）
   - id, filename, video_name, frame_number, width, height, status, created_at, updated_at

5. `data_groups_rs` - 数据-组关联表
   - id, data_id, group_id, created_at

6. `ball_annotations` - 台球标注表
   - id, data_id, user_id, annotation_data (JSON字符串), created_at, updated_at
   - annotation_data字段包含所有球的标注信息，采用JSON格式存储

7. `cue_annotations` - 球杆标注表
   - id, data_id, user_id, annotation_data (JSON字符串), created_at, updated_at
   - annotation_data字段采用JSON格式存储球杆的位置信息

8. `system_configs` - 系统配置表
   - id, key, value, description, created_at, updated_at