# cutpic

**Repository Path**: xdds/cutpic

## Basic Information

- **Project Name**: cutpic
- **Description**: 专为分镜稿从业者打造的智能宫格图片切分工具，零成本切分九宫格/四宫格图片，自动去除黑边/白边，告别手动切图繁琐与AI模型积分浪费
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-01-20
- **Last Updated**: 2026-02-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 切图, 分镜稿切图, 九宫格切图, 四宫格切图, 九宫格

## README

# 智能图片切分工具 (CutPic)

一个基于 Flask 的智能图片切分工具，专门用于将九宫格或四宫格图片智能分割成单张图片，支持自动去除黑边 / 白边。

**作者**：老猫

## 🎯 项目初衷

做这个工具的核心初衷，是想帮分镜稿创作的朋友们解决实际工作中的切图痛点：

- **手动切分繁琐**：九宫格 / 四宫格分镜稿图片手动切分操作繁琐，裁剪、去边耗时又费力
- **AI模型成本高**：依赖 AI 模型切分图片会产生不必要的积分 / 费用消耗，仅为切图浪费成本不划算
- **通用工具不精准**：市面上通用切图工具无法精准适配分镜稿的黑 / 白边框、分割线识别需求

为此开发了 **CutPic 智能图片切分工具**，以零成本、高效率的方式解决分镜稿宫格图片的精准切分问题，无需依赖外部模型，本地即可完成智能切分与去边处理。

## ✨ 功能特性

- **智能切分**：支持九宫格(3×3)和四宫格(2×2)的图片切分，精准适配分镜稿切分需求
- **自动去边**：智能识别并去除图片的黑边/白边，无需手动二次处理
- **多种模式**：
  - 标准宫格模式：适用于无间隙的紧密宫格
  - 智能宫格模式：适用于有间隙的宫格，自动去除分割线（分镜稿优选）
- **背景边线适配**：支持白色背景和黑色背景的识别，贴合分镜稿常见样式
- **智能识别**：自动检测图片是九宫格还是四宫格，显示检测置信度
- **批量下载**：一键打包下载所有切分后的子图，提升分镜稿整理效率
- **在线预览**：实时预览切分结果，支持缩放、拖拽查看，便于核对切分效果
- **历史记录**：保存所有处理记录，方便分镜稿切分记录追溯
- **删除功能**：安全删除图片及相关文件，避免冗余文件堆积

## 📋 系统要求

- Python 3.11+
- MySQL 5.7+ / MariaDB 10.2+

## 🚀 快速开始

### 1. 克隆项目

```bash
git clone https://gitee.com/xdds/cutpic.git
cd cutpic
```

### 2. 安装依赖

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

### 3. 配置环境变量

复制 `.env.example` 为 `.env` 并配置数据库连接：

```bash
cp .env.example .env
```

编辑 `.env` 文件：

```env
# 数据库配置
DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_password_here
DB_NAME=cutpic_db

# Flask配置
FLASK_HOST=127.0.0.1
FLASK_PORT=5000
FLASK_DEBUG=False
```

### 4. 初始化数据库

运行数据库初始化脚本：

```bash
python init_db.py
```

这将自动创建：
- `cutpic_db` 数据库
- `uploaded_images` 表（上传图片）
- `cut_image_results` 表（切图结果）
- `sub_images` 表（子图详情）

### 5. 启动服务

```bash
python main.py
```

服务将在 `http://127.0.0.1:5000` 启动。

## 📖 使用说明

### 上传图片

1. 访问首页，点击上传区域或拖拽图片
2. 支持的格式：JPG、PNG、WEBP
3. 最大文件大小：20MB

### 切分图片

1. 在图片列表中选择要处理的图片
2. 配置处理参数：
   - **宫格类型**：
     - ✨ 自动检测（默认）：系统会智能识别图片是九宫格还是四宫格，并显示检测置信度
     - 九宫格(3×3)：手动选择九宫格模式
     - 四宫格(2×2)：手动选择四宫格模式
   - **处理模式**：
     - 标准宫格：适用于无间隙的紧密宫格
     - 智能宫格：适用于有间隙的宫格（推荐，分镜稿优选）
   - **背景类型**：白色背景 或 黑色背景（改变此项会自动触发检测）
3. 点击"开始处理"按钮

**智能识别说明**：
- 系统会根据图片的分割线数量和内容分布自动判断宫格类型
- 有间隙模式：通过检测水平和垂直分割线判断（2条=九宫格，1条=四宫格）
- 无间隙模式：通过宽高比和边缘检测分析
- 检测结果会显示置信度（高/中等/低），用户可以根据实际情况手动覆盖

### 预览和下载

1. 处理完成后，点击"预览结果"查看切分效果
2. 可以逐张下载子图或批量下载ZIP文件
3. 在预览页面支持：
   - 缩放查看
   - 拖拽移动
   - 键盘快捷键（← → 切换，+ - 缩放，F 全屏）

### 查看历史记录

1. 点击"查看历史记录"按钮
2. 可按宫格类型筛选记录
3. 查看每个切图结果的详细信息

### 删除图片

1. 在图片列表中点击"删除"按钮
2. 确认删除操作
3. 系统将同时删除：
   - 原始图片文件
   - 所有切分后的子图
   - ZIP压缩包
   - 数据库记录

## 🏗️ 项目结构

```
cutpic/
├── main.py                 # 主应用文件
├── init_db.py             # 数据库初始化脚本
├── requirements.txt       # Python依赖包
├── .env.example           # 环境变量示例
├── .gitignore            # Git忽略文件
├── static/
│   ├── css/
│   │   └── custom.css    # 自定义样式
│   ├── images/           # 静态图片资源
│   └── temp/             # 临时文件存储（上传的图片和切分结果）
└── templates/
    ├── index.html        # 首页模板
    ├── preview.html      # 预览页面模板
    └── history.html      # 历史记录模板
```

## 🛠️ 技术栈

### 后端
- **Flask** - Web框架
- **Pillow** - 图像处理
- **NumPy** - 数值计算（用于智能算法）
- **MySQL** - 数据库
- **python-dotenv** - 环境变量管理

### 前端
- **HTML5** - 页面结构
- **CSS3** - 样式设计
- **JavaScript** - 交互逻辑
- **Jinja2** - 模板引擎

## 🧠 智能算法

### 自适应阈值算法
- 根据图片内容自动计算最佳阈值
- 支持白色和黑色背景的智能识别
- 确保边框去除的准确性

### 多次迭代去边框
- 多次迭代去除边框，确保彻底清除
- 每次迭代都重新计算阈值
- 验证四个角的颜色，防止残留边框

### 分割线检测
- 智能识别宫格间的分割线
- 检测分割线的颜色和宽度
- 确保切分后的图片干净无残留

## 🔧 配置说明

### 数据库配置

在 `.env` 文件中配置数据库连接：

```env
DB_HOST=127.0.0.1          # 数据库主机
DB_PORT=3306               # 数据库端口
DB_USER=root               # 数据库用户名
DB_PASSWORD=your_password  # 数据库密码
DB_NAME=cutpic_db          # 数据库名称
```

### Flask配置

```env
FLASK_HOST=127.0.0.1       # 服务器主机
FLASK_PORT=5000             # 服务器端口
FLASK_DEBUG=False           # 调试模式（生产环境请关闭）
```

### 上传配置

在 `main.py` 中修改上传配置：

```python
UPLOAD_FOLDER = 'static/temp'
MAX_CONTENT_LENGTH = 20 * 1024 * 1024  # 20MB限制
```

## 📊 数据库设计

### uploaded_images（上传图片表）
| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT | 图片ID（主键）|
| original_name | VARCHAR(255) | 原文件名 |
| original_path | VARCHAR(500) | 文件路径 |
| file_size | BIGINT | 文件大小（字节）|
| file_type | VARCHAR(50) | 文件类型 |
| width | INT | 图片宽度 |
| height | INT | 图片高度 |
| upload_time | DATETIME | 上传时间 |
| status | TINYINT | 状态：0-待处理，1-处理中，2-完成，3-失败 |

### cut_image_results（切图结果表）
| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT | 结果ID（主键）|
| image_id | INT | 关联的上传图片ID（外键）|
| grid_type | TINYINT | 宫格类型：4/9 |
| sub_image_count | INT | 子图数量 |
| save_path | VARCHAR(500) | 子图保存路径 |
| zip_path | VARCHAR(500) | ZIP文件路径 |
| cut_time | DATETIME | 切分时间 |
| download_count | INT | 下载次数 |

### sub_images（子图详情表）
| 字段 | 类型 | 说明 |
|------|------|------|
| id | INT | 子图ID（主键）|
| result_id | INT | 关联的切图结果ID（外键）|
| sub_image_path | VARCHAR(500) | 子图路径 |
| sub_image_name | VARCHAR(255) | 子图文件名 |
| sequence | INT | 子图序号 |
| width | INT | 子图宽度 |
| height | INT | 子图高度 |

## 🔐 安全建议

1. **生产环境部署**：
   - 修改默认数据库密码
   - 启用HTTPS
   - 设置防火墙规则
   - 定期备份数据库

2. **文件安全**：
   - 限制上传文件类型
   - 设置文件大小限制
   - 定期清理临时文件

3. **数据库安全**：
   - 使用强密码
   - 限制数据库用户权限
   - 定期备份数据

## 🐛 常见问题

### 1. 数据库连接失败

**问题**：启动时提示数据库连接错误

**解决方案**：
- 检查MySQL服务是否启动
- 验证 `.env` 文件中的数据库配置
- 确认数据库用户权限是否正确

### 2. 图片切分失败

**问题**：切分后提示"处理失败"

**解决方案**：
- 确认图片是标准的九宫格或四宫格
- 尝试切换处理模式（标准/智能）
- 检查背景类型设置是否正确

### 3. 文件路径错误

**问题**：预览或下载时404错误

**解决方案**：
- 确认 `static/temp` 目录存在且有写入权限
- 检查路径分隔符（Windows使用`\`，URL需要`/`）
- 重启Flask应用

### 4. 端口被占用

**问题**：启动时提示端口5000被占用

**解决方案**：
- 程序会自动查找可用端口
- 或在 `.env` 中修改 `FLASK_PORT`

## 📝 更新日志

### v1.0.0 (2026-01-20)
- ✨ 初始版本发布
- 🎯 支持九宫格和四宫格切分
- 🧠 智能去边框算法
- 📦 批量下载功能
- 🗑️ 删除功能
- 📜 历史记录功能

## 🤝 贡献指南

欢迎提交Issue和Pull Request！

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) 文件

## 📞 联系方式

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

- 提交 Issue
- 发送邮件 dhwzy@126.com

## 📸 功能截图

### 首页 - 上传图片
![首页截图](screenshots/home.png)
### 图片列表
![智能识别截图](screenshots/piclist.png)
### 图片处理 - 智能识别
![智能识别截图](screenshots/detect.png)

### 子图列表
![预览截图](screenshots/childlist.png)
### 切分结果 - 在线预览
![预览截图](screenshots/preview.png)

### 历史记录
![历史记录截图](screenshots/history.png)

## ☕ 请作者喝杯咖啡

如果您觉得这个工具对您有帮助，欢迎请作者喝杯咖啡，您的支持是持续开发的动力！

### 微信
![微信支付二维码](screenshots/wechat_pay.png)

### 支付宝
![支付宝二维码](screenshots/alipay.png)

---

**⭐ 如果这个项目对您有帮助，请给个 Star！**