{"id":50348085,"url":"https://github.com/redredchen01/banner-studio","last_synced_at":"2026-05-29T20:01:32.874Z","repository":{"id":357571710,"uuid":"1237560121","full_name":"redredchen01/banner-studio","owner":"redredchen01","description":"1200×248 Banner Studio image processing service with Celery async, WebSocket real-time feedback, and Gallery curation workflow. Python 3.11 + Flask + OpenCV AI face detection.","archived":false,"fork":false,"pushed_at":"2026-05-13T09:45:31.000Z","size":1208,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"feat/ai-composition-integration","last_synced_at":"2026-05-13T11:36:02.802Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/redredchen01.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-13T09:44:51.000Z","updated_at":"2026-05-13T09:45:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/redredchen01/banner-studio","commit_stats":null,"previous_names":["redredchen01/banner-studio"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/redredchen01/banner-studio","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redredchen01%2Fbanner-studio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redredchen01%2Fbanner-studio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redredchen01%2Fbanner-studio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redredchen01%2Fbanner-studio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/redredchen01","download_url":"https://codeload.github.com/redredchen01/banner-studio/tar.gz/refs/heads/feat/ai-composition-integration","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redredchen01%2Fbanner-studio/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33668186,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-29T20:01:31.991Z","updated_at":"2026-05-29T20:01:32.866Z","avatar_url":"https://github.com/redredchen01.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 📸 Banner Studio 图片处理系统\n\n\u003e **版本 v0.4.0** · Python 3.11 · 611+ 测试通过 · Celery + WebSocket 实时反馈\n\nPC 桌面主版位（1200×248）优先的智能图片处理服务。一张原图自动产出多规格（PC banner、移动卡片、母版等）；多张原图可进入 Gallery 做策展和批量预览。\n\n## 🎯 核心特性\n\n- **AI 人脸检测**：OpenCV Haar cascade + head-and-shoulders 完整包围盒对焦\n- **多规格自动派生**：从 1200×248 主版位直接派生移动卡片、HD 宽屏等，避免二次失真\n- **Gallery 策展工作流**：批量预览、标记/拒绝/置顶、CSV 导出、键盘快捷键\n- **异步后台处理**：Celery 队列（独立 GPU 队列支持）+ Redis 缓存\n- **实时进度反馈**：WebSocket 长连接、前端实时显示处理进度\n- **生产级部署**：Canary 策略、性能基线监控、故障自动告警\n\n## 📂 项目结构\n\n```\nresizer_0429/\n├── README.md                          # 本文件\n├── image-resizer/                     # 核心图片处理模块（Git submodule）\n│   ├── master_system/\n│   │   ├── config.py                  # 规格配置（frozen dataclass）\n│   │   ├── core/\n│   │   │   ├── face_detector.py       # 人脸检测 + 显著区识别\n│   │   │   ├── face_compositor.py     # head-and-shoulders 裁切核心\n│   │   │   ├── outpaint_engine.py     # 横向不足智能填充\n│   │   │   ├── export_manager.py      # 主流水线编排\n│   │   │   └── validator.py           # 输入验证 + 素材评分\n│   │   ├── tests/                     # 611+ 单元 / 集成 / E2E 测试\n│   │   └── main.py                    # CLI 入口\n│   ├── start_web.py                   # Web 工作室入口\n│   └── README.md                      # image-resizer 子模块详细文档\n│\n├── app.py                             # Flask 主应用 + WebSocket\n├── celery_config.py                   # Celery 配置（GPU 队列）\n├── celery_tasks.py                    # Celery 后台任务定义\n├── requirements.txt                   # Python 依赖\n│\n├── docs/\n│   ├── plans/                         # 技术规划与设计文档\n│   ├── solutions/                     # 问题修复与最佳实践库\n│   └── deployments/                   # 部署与监控方案\n│\n├── DEPLOYMENT_PLAN_2026-05-05.md      # 生产部署 Canary 策略\n├── PRODUCTION_READINESS_2026-05-13.md # 生产就绪评估\n└── COMPLETE_DEPLOYMENT_REPORT.md      # 完整部署报告\n```\n\n## 🚀 快速开始\n\n### 本地开发（Web 工作室）\n\n**macOS:**\n```bash\n# 方式1：便捷脚本\n./启动Web服务.command\n\n# 方式2：直接 Python\npython3 start_web.py\n```\n\n**Windows:**\n```bash\n# 双击运行\n启动Web服务.bat\n```\n\n**访问：** http://localhost:8080\n\n### CLI 命令行\n\n```bash\n# 单图处理（推荐：包模式）\npython3 -m master_system.main photo.jpg -o ./output\n\n# 多图处理（自动取最高分主图）\npython3 -m master_system.main photo1.jpg photo2.jpg photo3.jpg -o ./output\n\n# JSON 输出（脚本集成）\npython3 -m master_system.main photo.jpg -o ./output --json\n```\n\n### 生产部署（Gunicorn + Celery）\n\n```bash\n# 启动 Gunicorn（Flask Web）\ngunicorn -c gunicorn.conf.py app:app\n\n# 启动 Celery Worker（后台任务）\ncelery -A celery_tasks worker -l info -Q default,gpu\n\n# 启动 Celery Beat（定时任务，如果需要）\ncelery -A celery_tasks beat -l info\n```\n\n**监控 Celery 任务：**\n```bash\n# 实时任务面板\ncelery -A celery_tasks events\n```\n\n## 📊 输出规格\n\n| 规格 | 尺寸 | 用途 |\n|------|------|------|\n| `primary_banner` | 1200×248 | **PC 桌面主版位**（设计起点） |\n| `master` | 1300×640 | 编辑端上传母版 |\n| `card_medium` | 420×260 | 移动端卡片 |\n| `landscape_hd` | 1920×400 | HD 宽屏横版 |\n| `portrait_story` | 750×1334 | 手机竖版 Story（9:16） |\n| `square_thumbnail` | 600×600 | 正方形缩略图 |\n\n## 🔧 核心算法\n\n1. **人脸检测**：OpenCV Haar cascade + FIFO 缓存（256 条）\n2. **完整包围盒**：脸顶 +0.5×fh、脸底 +1.0×fh（≈2.5×fh 总高）\n3. **自检 Retry**：距视口边 \u003c8px 则自动降低 face_height_ratio（0.40→0.35→0.30）\n4. **多脸策略**：单脸居中、双脸左右对称、三脸+ 取外接矩形\n5. **横向填充**：原图宽度不足时自动 outpaint（同图镜像 + 高斯模糊）\n6. **无脸兜底**：saliency 主体检测；失败时显式返回 None，调用方决定降级\n7. **EXIF 修正**：手机竖拍照片自动方向修正；损坏时静默退化为原图\n\n## 🎯 Gallery 策展工作流（v0.4.0）\n\n上传 ≥2 张图后选择「批量预览 Gallery」：\n\n- **可视化**：lightbox + safeZone overlay、逐张评估\n- **快速标记**：`s`=select / `r`=reject / `p`=pin / `d`=delete / `?`=帮助\n- **编辑操作**：filter bar、批量操作 toolbar、拖拽重排序\n- **数据导出**：CSV 一键导出选中项及打分\n- **状态持久化**：sessionStorage（`gallery_session` / `gallery_selection_v1` / `gallery_order_v1`）\n\n## 💾 异步处理架构\n\n### Celery 队列设计\n\n```\n队列 (Queue)          用途                   Worker 配置\n─────────────────────────────────────────────────────────\ndefault              图片处理主流程          标准 Worker\ngpu                  GPU 密集任务            GPU Worker（专用）\n                     （future-ready）\n```\n\n### 实时进度反馈（WebSocket）\n\n- **连接**：客户端上传后建立长连接 `/ws/progress`\n- **消息**：每秒推送当前处理进度（单位 %）\n- **状态流**：`pending` → `processing` → `completed` / `failed`\n- **前端显示**：实时进度条 + 预期完成时间估算\n\n### 任务生命周期\n\n```\nPOST /upload\n  ↓\n1. 前端验证（MIME type、尺寸）\n2. 服务端入队（Celery）→ Redis 缓存任务 ID\n3. Worker 处理（parallel pipeline）\n4. WebSocket 推送实时进度\n5. 完成 → 静态资源存储 → 返回下载链接\n```\n\n## 📈 性能基线\n\n- **单图处理**：~220ms（含检测、裁切、导出）\n- **Gallery 批处理**：N×220ms（可配置并行度）\n- **单元测试覆盖**：99%\n- **E2E 覆盖**：32 Chromium + 26 Firefox + 26 WebKit\n\n## ✅ 测试与质量\n\n```bash\n# 运行单元 + 集成测试\npython3 -m pytest -q\n# 611+ passed, 1 skipped\n\n# 代码覆盖率报告\npython3 -m coverage run -m pytest \u0026\u0026 python3 -m coverage report\n\n# 静态类型检查\npython3 -m mypy master_system/\n\n# 代码风格检查\nruff check master_system/ app.py celery_tasks.py\n```\n\n### E2E 测试（真实浏览器）\n\n```bash\n# 快速验证（Chromium）\nmake e2e-install \u0026\u0026 make e2e\n\n# 完整验证（Chromium + Firefox + WebKit）\nmake e2e-install-cross \u0026\u0026 make e2e-cross\n```\n\n## 🛠️ 技术栈\n\n| 层 | 技术 | 版本 |\n|---|---|---|\n| **语言** | Python | 3.11+ |\n| **图像处理** | Pillow, NumPy, OpenCV | 最新 |\n| **Web 框架** | Flask | 2.x |\n| **异步队列** | Celery + Redis | 5.x |\n| **实时通信** | WebSocket (python-socketio) | 5.x |\n| **部署** | Gunicorn / Waitress | 最新 |\n| **监控** | Prometheus + Grafana（optional） | 最新 |\n\n## 📚 文档导航\n\n| 文档 | 适用场景 |\n|---|---|\n| [image-resizer/README.md](./image-resizer/README.md) | 核心算法、API 详细说明 |\n| [DEPLOYMENT_PLAN_2026-05-05.md](./DEPLOYMENT_PLAN_2026-05-05.md) | 生产 Canary 部署策略 |\n| [PRODUCTION_READINESS_2026-05-13.md](./PRODUCTION_READINESS_2026-05-13.md) | 生产就绪评估清单 |\n| [COMPLETE_DEPLOYMENT_REPORT.md](./COMPLETE_DEPLOYMENT_REPORT.md) | 部署验证详细报告 |\n| [docs/solutions/](./docs/solutions/) | 问题修复库 \u0026 最佳实践 |\n\n## 🔐 配置与安全\n\n### 环境变量\n\n```bash\n# Redis\nREDIS_HOST=localhost\nREDIS_PORT=6379\nREDIS_DB=0\n\n# Celery\nCELERY_BROKER_URL=redis://localhost:6379/0\nCELERY_RESULT_BACKEND=redis://localhost:6379/1\n\n# Flask\nFLASK_ENV=development|production\nSECRET_KEY=\u003cyour-secret-key\u003e\n\n# 可选：Sentry 错误追踪\nSENTRY_DSN=https://...\n```\n\n### 关键契约\n\n- **Frozen Config**：`MASTER_CONFIG`、`OutputProfile` 是 frozen dataclass，运行时不可变\n- **类型安全**：`PipelineResult` TypedDict 定义，静态自描述\n- **统一异常**：`OutpaintRequired` 显式抛出，调用方逻辑清晰\n- **PIL Bomb 防护**：`Image.MAX_IMAGE_PIXELS = 200M`（在加载时初始化）\n- **极端纵横比拦截**：max/min ratio \u003e 20.0 直接拒绝\n\n## 📋 常见问题\n\n**Q: 支持哪些图片格式？**\nA: JPEG、PNG、WebP、GIF（单帧）。推荐 JPEG（压缩率最优）。\n\n**Q: 如何自定义输出规格？**\nA: 编辑 `image-resizer/master_system/config.py` 的 `OUTPUT_PROFILES`，然后重启服务。\n\n**Q: 可以在 Docker 中部署吗？**\nA: 可以。示例 Dockerfile 见 `DEPLOYMENT_PLAN_2026-05-05.md`。\n\n**Q: 支持 GPU 加速吗？**\nA: 是的。启用 GPU Worker：`celery -A celery_tasks worker -Q gpu -l info`。\n\n**Q: 如何监控任务队列？**\nA: 使用 Celery Flower（Web UI）：`pip install flower \u0026\u0026 celery -A celery_tasks flower`\n\n## 🚢 发布历史\n\n- **v0.4.0** (2026-05-07) — Gallery 策展、Celery 集成、WebSocket 实时反馈\n- **v0.3.x** — head-and-shoulders 算法优化、多脸策略完善\n- **v0.2.x** — 初版，多规格导出、CLI 支持\n- **v0.1.x** — MVP，单图处理核心\n\n详见 [image-resizer/CHANGELOG.md](./image-resizer/CHANGELOG.md)\n\n## 👥 贡献\n\n问题反馈或改进建议？请在 GitHub Issues 提交。\n\n开发环境搭建：\n```bash\ngit clone --recursive \u003crepo-url\u003e\ncd resizer_0429\npip install -r image-resizer/requirements.txt\npython3 start_web.py\n```\n\n## 📄 许可\n\nMIT License\n\n---\n\n**最后更新**：2026-05-13  \n**维护者**：Banner Studio Team\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredredchen01%2Fbanner-studio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fredredchen01%2Fbanner-studio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredredchen01%2Fbanner-studio/lists"}