# billiards_label_apps

**Repository Path**: oftenlin/billiards_label_apps

## Basic Information

- **Project Name**: billiards_label_apps
- **Description**: app/static/transformed
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-04-12
- **Last Updated**: 2025-11-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 台球标注后台管理系统

## 项目概述
本项目是一个基于Flask和MySQL的台球标注后台管理系统Web应用，主要支持台球标注、球杆标注以及台球桌透视变换处理等功能。系统设计为多用户系统，包括超级管理员和普通标注人员两种角色，支持任务分配和权限管理。

## 技术栈
- 后端：Flask
- 数据库：MySQL
- 前端：HTML, CSS, JavaScript, Bootstrap
- 图像处理：OpenCV
- 数据处理：NumPy, SQLAlchemy

## 主要功能模块

### 1. 用户管理模块
- 用户登录、退出
- 用户角色管理（超级管理员、普通标注人员）
- 权限控制

### 2. 台球标注模块
- 批次管理：上传、解压、预览数据包
- 标注功能：
  - 台球位置标注
  - 球类型分类（大号、小号、黑八、白球）
  - 球号码标注
- 标注状态管理与跟踪
- 标注数据导出

### 3. 球杆标注模块
- 球杆位置标注（起点、终点）
- 单击添加起点，移动鼠标预览，双击确认终点
- 标注数据自动保存
- 标注状态与任务管理

### 4. 台球桌透视变换模块
- 台球桌四个角点标注功能
- 透视变换矩阵计算
- 实时变换预览
- 批量应用透视变换

### 5. 任务分配管理模块
- 任务创建与分配
- 任务状态管理
- 标注进度跟踪

### 6. 数据导出工具
- 全数据库导出工具
- 标注数据专项导出工具
- 支持导出标注数据和相关图片

## 数据库设计

以下是系统数据库表结构的创建SQL语句：

### 用户表（users）
```sql
CREATE TABLE users (
    id INT PRIMARY KEY AUTO_INCREMENT,
    username VARCHAR(50) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    role ENUM('admin', 'annotator') NOT NULL DEFAULT 'annotator',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
```

### 批次表（batches）
```sql
CREATE TABLE batches (
    id INT PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(100) NOT NULL,
    type ENUM('billiard', 'cue', 'table') NOT NULL,
    upload_path VARCHAR(255) NOT NULL,
    status ENUM('uploaded', 'extracting', 'extracted', 'completed') DEFAULT 'uploaded',
    created_by INT NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    FOREIGN KEY (created_by) REFERENCES users(id)
);
```

### 图片表（images）
```sql
CREATE TABLE images (
    id INT PRIMARY KEY AUTO_INCREMENT,
    batch_id INT NOT NULL,
    filename VARCHAR(255) NOT NULL,
    filepath VARCHAR(255) NOT NULL,
    width INT,
    height INT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (batch_id) REFERENCES batches(id) ON DELETE CASCADE
);
```

### 任务分配表（billiards_anno_task_assignments）
```sql
CREATE TABLE billiards_anno_task_assignments (
    id INT PRIMARY KEY AUTO_INCREMENT,
    image_id INT NOT NULL,
    user_id INT NOT NULL,
    task_type ENUM('billiard_category', 'billiard_number', 'cue', 'table') NOT NULL,
    status ENUM('assigned', 'in_progress', 'completed') DEFAULT 'assigned',
    progress FLOAT DEFAULT 0,  -- 进度百分比
    assigned_by INT NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    FOREIGN KEY (image_id) REFERENCES images(id) ON DELETE CASCADE,
    FOREIGN KEY (user_id) REFERENCES users(id),
    FOREIGN KEY (assigned_by) REFERENCES users(id)
);
```

### 台球标注表（billiard_annotations）
```sql
CREATE TABLE billiard_annotations (
    id INT PRIMARY KEY AUTO_INCREMENT,
    image_id INT NOT NULL,
    position_data JSON NOT NULL,  -- 存储球的位置坐标 [x, y]
    category_data JSON,  -- 存储球的大小号分类
    number_data JSON,  -- 存储球的号码
    category_status ENUM('not_started', 'in_progress', 'completed') DEFAULT 'not_started',
    number_status ENUM('not_started', 'in_progress', 'completed') DEFAULT 'not_started',
    annotated_by INT,
    task_id INT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    FOREIGN KEY (image_id) REFERENCES images(id) ON DELETE CASCADE,
    FOREIGN KEY (annotated_by) REFERENCES users(id),
    FOREIGN KEY (task_id) REFERENCES billiards_anno_task_assignments(id)
);
```

### 球杆标注表（cue_annotations）
```sql
CREATE TABLE cue_annotations (
    id INT PRIMARY KEY AUTO_INCREMENT,
    image_id INT NOT NULL,
    start_position JSON NOT NULL,  -- 起点坐标 [x, y]
    end_position JSON NOT NULL,  -- 终点坐标 [x, y]
    cue_data JSON,  -- 球杆数据
    status ENUM('not_started', 'in_progress', 'completed') DEFAULT 'not_started',
    annotated_by INT,
    task_id INT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    FOREIGN KEY (image_id) REFERENCES images(id) ON DELETE CASCADE,
    FOREIGN KEY (annotated_by) REFERENCES users(id),
    FOREIGN KEY (task_id) REFERENCES billiards_anno_task_assignments(id)
);
```

### 台球桌透视变换表（table_perspective）
```sql
CREATE TABLE table_perspective (
    id INT PRIMARY KEY AUTO_INCREMENT,
    batch_id INT NOT NULL,
    reference_image_id INT NOT NULL,
    corner_points JSON NOT NULL,  -- 4个顶点坐标 [[x1,y1], [x2,y2], [x3,y3], [x4,y4]]
    transform_matrix JSON,  -- 变换矩阵
    created_by INT NOT NULL,
    task_id INT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    FOREIGN KEY (batch_id) REFERENCES batches(id) ON DELETE CASCADE,
    FOREIGN KEY (reference_image_id) REFERENCES images(id),
    FOREIGN KEY (created_by) REFERENCES users(id),
    FOREIGN KEY (task_id) REFERENCES billiards_anno_task_assignments(id)
);
```

### 导出任务表（export_tasks）
```sql
CREATE TABLE export_tasks (
    id INT PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(100) NOT NULL,
    export_type ENUM('billiard_category', 'billiard_number', 'cue', 'table', 'all') NOT NULL,
    batch_id INT,
    status ENUM('pending', 'processing', 'completed', 'failed') DEFAULT 'pending',
    file_path VARCHAR(255),
    file_size INT,
    copy_images BOOLEAN DEFAULT TRUE,
    created_by INT NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    completed_at TIMESTAMP,
    FOREIGN KEY (batch_id) REFERENCES batches(id),
    FOREIGN KEY (created_by) REFERENCES users(id)
);
```

## 项目结构
```
billiards_label_web_app/
├── app/
│   ├── __init__.py          # Flask应用初始化
│   ├── config.py            # 应用配置
│   ├── controllers/         # 控制器
│   │   ├── __init__.py
│   │   ├── admin.py         # 管理员控制器
│   │   ├── auth.py          # 认证控制器
│   │   ├── billiard.py      # 台球标注控制器
│   │   ├── cue.py           # 球杆标注控制器
│   │   ├── table.py         # 台球桌透视变换控制器
│   │   └── task.py          # 任务管理控制器
│   ├── models/              # 数据模型
│   │   ├── __init__.py
│   │   ├── batch.py         # 批次模型
│   │   ├── billiard_annotation.py  # 台球标注模型
│   │   ├── cue_annotation.py       # 球杆标注模型
│   │   ├── image.py         # 图片模型
│   │   ├── table_perspective.py    # 台球桌透视变换模型
│   │   ├── task_assignment.py      # 任务分配模型
│   │   └── user.py          # 用户模型
│   ├── services/            # 服务层
│   │   ├── __init__.py
│   │   └── ... 
│   ├── static/              # 静态资源
│   │   ├── css/
│   │   ├── js/
│   │   └── img/
│   ├── templates/           # 模板
│   │   ├── admin/           # 管理界面模板
│   │   ├── auth/            # 认证模板
│   │   ├── billiard/        # 台球标注模板
│   │   ├── cue/             # 球杆标注模板
│   │   ├── errors/          # 错误页面模板
│   │   └── table/           # 台球桌透视变换模板
│   └── utils/               # 工具函数
│       ├── __init__.py
│       ├── decorators.py    # 装饰器
│       ├── file_utils.py    # 文件处理工具
│       └── image_utils.py   # 图像处理工具
├── extracted/               # 解压后的图片存储目录
├── exports/                 # 导出数据存储目录
├── transformed/             # 透视变换后的图片存储目录
├── uploads/                 # 上传文件存储目录
├── create_admin.py          # 创建管理员账号脚本
├── export_annotations.py    # 标注数据导出工具
├── export_database.py       # 数据库导出工具
├── init_db.py               # 数据库初始化脚本
├── requirements.txt         # 依赖包列表
├── run.py                   # 应用启动入口
└── README.md                # 项目说明文档
```

## 数据导出与导入工具
项目包含专用的数据导出和导入工具：

### 数据导出工具

1. **全数据库导出**：`export_database.py`
   ```bash
   # 导出所有数据库表到JSON文件
   python export_database.py
   ```

2. **标注数据专项导出**：`export_annotations.py`
   ```bash
   # 仅导出标注数据
   python export_annotations.py
   
   # 导出标注数据并包含相关图片
   python export_annotations.py --copy-images
   ```

### 数据导入工具

1. **全数据库导入**：`import_database.py`
   ```bash
   # 从导出目录导入所有数据
   python import_database.py -d exports/database_backup/20250412_151756
   
   # 导入特定表的数据
   python import_database.py -d exports/database_backup/20250412_151756 -t users batches images 
   
   # 清除现有数据后导入
   python import_database.py -d exports/database_backup/20250412_151756 --clear
   ```

2. **标注数据专项导入**：
   ```bash
   # 导入标注数据（透视变换、台球标注、球杆标注）
   python import_database.py -d exports/annotations_export/20250412_160243 --annotations
   
   # 清除现有标注数据后导入
   python import_database.py -d exports/annotations_export/20250412_160243 --annotations --clear
   ```

## 环境配置与启动
1. 创建并激活虚拟环境
   ```bash
   conda create -n billiards_label_ws python=3.10
   conda activate billiards_label_ws
   ```

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

3. 初始化数据库
   ```bash
   python init_db.py
   ```

4. 创建管理员账号
   ```bash
   python create_admin.py
   ```

5. 启动应用
   ```bash
   python run.py
   ```

## 使用指南
1. 管理员账号登录系统
2. 上传数据批次（支持zip压缩包）
3. 分配标注任务给标注人员
4. 标注人员登录执行标注任务
5. 使用导出工具导出标注数据

## 开发者
- 项目负责人：@oftenlin