基于 OpenCV 的图像/视频处理全栈系统 — GUI 桌面应用、REST API 后端、CLI 命令行，三种使用方式。
| 说明 |
效果图 |
| 主界面 ：加载图片、侧边栏操作 |
 |
| 滤镜预览 ：11 种滤镜实时对比 |
 |
| 格式转换 ： PNG / JPG / WebP / BMP |
 |
| 模板匹配 ： 在大图中定位模板区域 |
 |
| 说明 |
效果图 |
| 主界面 ： 播放控制栏、进度条拖拽 |
 |
| 逐帧滤镜 ：选滤镜后实时播放预览 |
 |
| 格式转换：MP4 / AVI / MOV / MKV |
 |
| 视频剪辑 ：按时间区间精确裁剪 |
 |
| 视频信息： 分辨率、帧率、时长、编码器 |
 |
| 抽帧导出 ：指定时间点抽帧保存为图片 |
 |
| 说明 |
效果图 |
| 暗色模式 ： Ctrl+D 一键切换 |
 |
| 鸟瞰图 ：右下角浮动小窗，点击跳转 |
 |
| 文字水印 ：右下角半透明文字 |
 |
| 说明 |
效果图 |
| CLI 命令行 — 批量处理、脚本自动化 |
 |
| API Swagger — 在线调试、11 个接口 |
 |
| 基础调整 |
特征提取 |
图像编辑 |
滤镜效果 |
高级功能 |
| 黑白照 |
Canny 边缘检测 |
自由裁剪 |
浮雕 |
模板匹配 |
| 二值化 |
轮廓检测 |
图像分割 |
素描 |
直方图均衡 |
| 高斯模糊 |
Harris 角点检测 |
缩放 |
卡通 |
|
| 中值滤波 |
|
旋转 |
怀旧 |
|
| 亮度调整 |
|
文字水印 |
马赛克 |
|
|
|
格式转换 (PNG/JPG/WebP/BMP) |
|
|
| 操作 |
说明 |
| 格式转换 |
MP4 / AVI / MOV / MKV 互转 |
| 视频剪辑 |
按时间范围精确裁剪 |
| 逐帧滤镜 |
11 种滤镜可选，实时预览效果 |
| 抽帧导出 |
指定时间戳抽取帧并保存为图片 |
| 预览播放 |
播放 / 暂停 / 拖拽进度条 Seek |
- 撤销/重做：备忘录模式，无限次撤销
- 缩放平移：滚轮缩放（以鼠标为中心），拖拽平移
- 鸟瞰图：右下角浮动窗口，点击跳转
- 暗色模式：
Ctrl+D 一键切换
- 进度条：视频处理显示帧级进度
- 实时预览：图像参数调节即时反馈，视频滤镜选前预览
ImageStudio/
├── main.py # GUI 桌面应用入口
├── gui.py # 主界面（侧边栏、画布、预览、缩放、播放、暗色模式）
├── gui_video.py # 视频处理 UI 模块（对话框、进度条、播放控制）
├── image_processing.py # 图像处理核心（OpenCV，含撤销/重做）
├── video_processing.py # 视频处理核心（转码/剪辑/滤镜/抽帧）
├── server.py # FastAPI REST 后端（11 个端点）
├── cli.py # 命令行工具（8 个子命令）
├── config.py # 配置管理（dataclass + JSON）
├── config.json # 默认配置文件
├── requirements.txt # Python 依赖
├── Dockerfile # Docker 镜像
├── docker-compose.yml # Docker Compose 编排
├── tests/
│ ├── conftest.py # 共享 fixtures
│ ├── test_image_processing.py # 图像处理测试 (32)
│ ├── test_video_processing.py # 视频处理测试 (10)
│ ├── test_server.py # API 端点测试 (29)
│ └── test_cli.py # CLI 命令测试 (14)
├── screenshots/ # 效果截图（见上方展示）
├── demo.mp4 # 示例视频
└── Tulips.jpg # 示例图片
| 层级 |
技术 |
| 图像/视频处理 |
OpenCV 4.x, NumPy |
| GUI |
Tkinter + Pillow |
| 后端 |
FastAPI + Uvicorn + Pydantic |
| CLI |
argparse |
| 测试 |
pytest (85 条) |
| 容器化 |
Docker + Docker Compose |
| 语言 |
Python 3.9+ |
pip install -r requirements.txt
本项目提供三种使用方式，根据需要选择：
| 启动命令 |
方式 |
适用场景 |
python main.py |
GUI 桌面应用 |
手动编辑图片/视频，所见即所得 |
python server.py |
API 后端服务 |
提供 HTTP 接口，前端/其他程序调用 |
python cli.py --help |
命令行工具 |
批量处理、脚本自动化、无界面服务器 |
- 终端运行：在项目目录打开终端，输入上面的命令
- Spyder 运行：打开
main.py → 按 F5 或点击上方绿色播放按钮
- 弹出 Tkinter 窗口，加载图片/视频后即可操作
启动后终端会打印：
ImageStudio API 启动: http://0.0.0.0:8000
Swagger 文档: http://localhost:8000/docs
浏览器打开 http://localhost:8000/docs 即可看到自动生成的 API 文档页面。
这个文档哪来的？ FastAPI 框架根据 server.py 里的代码自动生成，包括接口路径、参数说明、返回值格式。所有 FastAPI 项目的文档都在 /docs 路径下，不需要手写。
| 地址 |
说明 |
http://localhost:8000/docs |
Swagger UI — 可交互，能直接在网页上调接口 |
http://localhost:8000/redoc |
ReDoc — 只读文档，排版更整洁 |
python cli.py --help # 查看所有子命令
python cli.py image-process photo.jpg -o gray # 灰度处理
python cli.py video-info demo.mp4 # 查看视频信息
适合批量脚本、服务器无 GUI 环境、自动化流水线。
docker compose up -d
# API 文档 → http://localhost:8000/docs
# 格式转换
python cli.py image-convert photo.jpg -f png
# 单张处理
python cli.py image-process photo.jpg -o gray
# 批量处理
python cli.py image-batch "images/*.jpg" -o resize --width 800
可选操作：gray, binary, gaussian_blur, median_blur, edge_detect, corner_detect, contours, segment, emboss, sketch, cartoon, vintage, mosaic, histogram_equalize, brightness, resize
# 视频信息
python cli.py video-info video.mp4
# 转码
python cli.py video-transcode video.mp4 -f avi
# 剪辑（0.5s ~ 2.0s）
python cli.py video-trim video.mp4 --start 0.5 --end 2.0
# 逐帧滤镜
python cli.py video-filter video.mp4 --filter gray
# 抽帧
python cli.py video-extract-frames video.mp4 -t 0.5,1.0,2.5
启动 python server.py 后：
- Swagger 交互文档：
http://localhost:8000/docs（可在页面直接调试接口）
- ReDoc 只读文档：
http://localhost:8000/redoc
原理：FastAPI 根据代码中的类型注解（str、int、UploadFile 等）和 docstring 自动生成 OpenAPI 规范的 JSON，再由 Swagger UI / ReDoc 渲染成网页。路径是框架约定的，所有 FastAPI 项目都一样。
| 方法 |
路径 |
说明 |
GET |
/api/v1/health |
健康检查 |
GET |
/api/v1/operations |
可用操作列表 |
POST |
/api/v1/image/process |
图像处理 |
POST |
/api/v1/image/resize |
图像缩放 |
POST |
/api/v1/image/rotate |
图像旋转 |
POST |
/api/v1/image/watermark |
文字水印 |
POST |
/api/v1/image/convert |
格式转换 |
POST |
/api/v1/image/batch |
批量处理（异步） |
GET |
/api/v1/tasks/{id} |
任务状态 |
GET |
/api/v1/tasks/{id}/download |
下载结果 (ZIP) |
POST |
/api/v1/video/process |
视频处理 |
# 调用示例
curl -X POST http://localhost:8000/api/v1/image/process \
-F "file=@photo.jpg" -F "operation=gray"
curl -X POST http://localhost:8000/api/v1/video/process \
-F "file=@video.mp4" -F "operation=trim" \
-F "start_sec=0.5" -F "end_sec=2.0"
# 全部 85 条测试
pytest tests/ -v
# 带覆盖率
pytest tests/ --cov=. --cov-report=html
# 分类运行
pytest tests/test_server.py -v
pytest tests/test_cli.py -v
.jpg){kind=link}
