diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..34a849f --- /dev/null +++ b/.gitignore @@ -0,0 +1,52 @@ +# macOS +.DS_Store + +# Python +**/__pycache__ +*.py[cod] +*$py.class +*.so +.Python +*.egg-info/ +IOPaint.egg-info/ +.pytest_cache/ +.coverage + +# Virtual environments +venv/ +env/ +ENV/ + +# IDEs +.idea/ +.vscode/ +*.swp +*.swo + +# Build artifacts +build/ +!iopaint/app/build +dist/ +tmp/ + +# Frontend +iopaint/web_app/ +web_app/node_modules/ +web_app/dist/ +web_app/.env.local + +# Examples +examples/ +example/ + +# Model cache (optional - uncomment if you don't want to commit models) +# .cache/ +# *.pt +# *.ckpt +# *.safetensors + +# Logs +*.log + +# OS +Thumbs.db diff --git a/.vscode/preview.yml b/.vscode/preview.yml index bf69849..7fca036 100644 --- a/.vscode/preview.yml +++ b/.vscode/preview.yml @@ -1,10 +1,34 @@ -# .vscode/preview.yml -autoOpen: false # 打开工作空间时是否自动开启所有应用的预览 +# IOPaint Preview Configuration +autoOpen: true # 打开工作空间时是否自动开启所有应用的预览 apps: - - port: 5000 # 应用的端口 - run: python ./example.py # 应用启动命令 - root: ./example # 应用的启动目录 - name: Python Cloud Studio Demo # 应用名称 - description: Python Cloud Studio Demo Project # 应用描述 - autoOpen: false # 打开工作空间时是否自动运行命令(优先级高于根级 autoOpen) - autoPreview: false # 是否自动打开预览, 若无则默认为true \ No newline at end of file + - port: 8080 # IOPaint 服务器端口 + run: python3 main.py start --model lama --device cuda --port 8080 # 启动命令(使用 LaMa 模型和 GPU) + root: . # 应用的启动目录(项目根目录) + name: IOPaint - LaMa Model # 应用名称 + description: IOPaint 图像修复工具 - 使用 LaMa 模型快速擦除(GPU 加速) # 应用描述 + autoOpen: true # 打开工作空间时是否自动运行命令 + autoPreview: true # 自动打开预览 + + - port: 8080 # IOPaint 服务器端口 + run: python3 main.py start --model runwayml/stable-diffusion-inpainting --device cuda --port 8080 # SD Inpainting 模型 + root: . # 应用的启动目录 + name: IOPaint - SD Inpainting # 应用名称 + description: IOPaint 图像修复工具 - 使用 Stable Diffusion Inpainting(支持文本提示) # 应用描述 + autoOpen: false # 不自动运行(手动切换) + autoPreview: false # 不自动预览 + + - port: 8080 # IOPaint 服务器端口 + run: python3 main.py start --model diffusers/stable-diffusion-xl-1.0-inpainting-0.1 --device cuda --low-mem --port 8080 # SDXL 模型 + root: . # 应用的启动目录 + name: IOPaint - SDXL Inpainting # 应用名称 + description: IOPaint 图像修复工具 - 使用 SDXL(高质量,低内存模式) # 应用描述 + autoOpen: false # 不自动运行(手动切换) + autoPreview: false # 不自动预览 + + - port: 8080 # IOPaint 服务器端口 + run: python3 main.py start --model lama --device cpu --port 8080 # CPU 模式 + root: . # 应用的启动目录 + name: IOPaint - LaMa (CPU) # 应用名称 + description: IOPaint 图像修复工具 - LaMa 模型 CPU 模式(无需 GPU) # 应用描述 + autoOpen: false # 不自动运行(手动切换) + autoPreview: false # 不自动预览 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..d269c7f --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,241 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## 项目概述 + +IOPaint 是一个免费开源的图像修复(inpainting)和扩展(outpainting)工具,基于最先进的 AI 模型。项目包括 Python 后端(FastAPI)和 React TypeScript 前端(Vite)。 + +**关键特性:** +- 支持多种 AI 模型:LaMa、Stable Diffusion、SDXL、BrushNet、PowerPaint、AnyText 等 +- 插件系统:Segment Anything、RemoveBG、RealESRGAN、GFPGAN 等 +- 批处理功能 +- WebUI 界面和命令行界面 +- 支持 CPU、GPU、Apple Silicon + +## 常用命令 + +### 开发环境设置 + +**前端开发:** +```bash +cd web_app +npm install +npm run dev # 开发服务器运行在 http://localhost:5173 +``` + +**前端构建:** +```bash +cd web_app +npm run build +cp -r dist/ ../iopaint/web_app +``` + +**后端开发:** +```bash +pip install -r requirements.txt +python3 main.py start --model lama --port 8080 --device cpu +``` + +**安装插件依赖:** +```bash +iopaint install-plugins-packages +``` + +### 生产环境 + +**安装并启动:** +```bash +pip3 install iopaint +iopaint start --model=lama --device=cpu --port=8080 +``` + +**批处理图像:** +```bash +iopaint run --model=lama --device=cpu \ + --image=/path/to/image_folder \ + --mask=/path/to/mask_folder \ + --output=output_dir +``` + +**下载模型:** +```bash +iopaint download --model runwayml/stable-diffusion-inpainting +``` + +**列出已下载的模型:** +```bash +iopaint list +``` + +### 构建与发布 + +**构建 Python 包:** +```bash +bash publish.sh +# 会构建前端并打包成 wheel +``` + +**构建 Docker 镜像:** +```bash +bash build_docker.sh +``` + +## 架构概览 + +### 后端架构 (iopaint/) + +**入口点流程:** +1. `__init__.py::entry_point()` - 主入口,处理 Windows PyTorch 修复 +2. `cli.py::typer_app` - Typer CLI 应用,定义所有命令(start, run, download, list) +3. `api.py::Api` - FastAPI 应用,处理 WebUI 和 REST API +4. `model_manager.py::ModelManager` - 核心模型管理器,负责加载和切换模型 + +**模型系统:** +- `model/base.py::InpaintModel` - 所有模型的抽象基类 +- 模型实现分为两类: + - **擦除模型** (erase models): LaMa, MAT, MI-GAN, OpenCV2, Manga 等 - 用于移除物体、水印 + - **扩散模型** (diffusion models): SD, SDXL, ControlNet, BrushNet, PowerPaint, AnyText 等 - 用于替换物体或扩展图像 +- 每个模型实现 `forward()` 方法,接收图像、mask 和 InpaintRequest 配置 + +**插件架构:** +- `plugins/base_plugin.py::BasePlugin` - 插件抽象基类 +- 插件独立于主模型运行,可以启用/禁用 +- 主要插件: InteractiveSeg, RemoveBG, AnimeSeg, RealESRGAN, GFPGAN, RestoreFormer + +**文件管理:** +- `file_manager/` - 处理图像浏览、存储后端(本地文件系统) + +**批处理:** +- `batch_processing.py::batch_inpaint()` - 批量处理图像的主函数 + +### 前端架构 (web_app/) + +- React + TypeScript + Vite +- 使用 Recoil/Zustand 进行状态管理 +- TailwindCSS + Radix UI 组件 +- Socket.IO 用于实时通信 +- React Query 用于数据获取 + +### 数据流 + +**WebUI 模式:** +1. 用户在浏览器中操作(绘制 mask、选择模型、调整参数) +2. 前端通过 HTTP API 发送 InpaintRequest 到 FastAPI 后端 +3. `api.py` 接收请求,调用 `ModelManager` +4. `ModelManager.__call__()` 预处理图像,调用模型的 `forward()` +5. 模型返回修复后的图像 +6. 后端将结果返回给前端显示 + +**批处理模式:** +1. CLI 命令触发 `batch_processing.py` +2. 遍历输入目录中的图像和 mask +3. 为每个图像调用 ModelManager +4. 保存结果到输出目录 + +### 模型加载与管理 + +- `download.py::scan_models()` - 扫描本地和 HuggingFace 可用模型 +- `ModelManager.init_model()` - 根据模型类型初始化相应的模型类 +- 支持动态模型切换(通过 `/api/v1/switch_model` 端点) +- 模型文件缓存在 `~/.cache` (可通过 `--model-dir` 修改) + +### 关键配置模式 + +**模型配置:** +- SD/SDXL 模型使用 `model/original_sd_configs/` 中的 YAML 配置 +- AnyText 使用专门的 `model/anytext/anytext_sd15.yaml` + +**设备管理:** +- 支持 CPU、CUDA、MPS(Apple Silicon) +- `helper.py::switch_mps_device()` - 处理 MPS 不兼容的模型 +- `model/utils.py::torch_gc()` - 清理 GPU/CPU 内存 + +**HD 策略:** +- `schema.py::HDStrategy` - 处理高分辨率图像的策略(CROP, RESIZE, ORIGINAL) +- 大图像会被分块处理或调整大小 + +## 重要注意事项 + +### 添加新模型 + +1. 在 `model/` 目录创建新的模型文件 +2. 继承 `InpaintModel` 基类 +3. 实现 `init_model()` 和 `forward()` 方法 +4. 在 `model/__init__.py` 注册模型 +5. 更新 `const.py` 中的 `AVAILABLE_MODELS` 或 `DIFFUSION_MODELS` + +### 前端开发 + +- 前端代码修改后自动热重载 +- 后端代码修改需要重启服务 +- 创建 `web_app/.env.local` 文件配置后端地址: + ``` + VITE_BACKEND=http://127.0.0.1:8080 + ``` + +### 性能优化选项 + +- `--low-mem`: 低内存模式,减少 VRAM 使用 +- `--cpu-offload`: CPU 卸载,将部分模型移到 CPU +- `--no-half`: 禁用半精度(FP16),提高精度但增加内存使用 +- `--cpu-textencoder`: 将文本编码器放在 CPU 上 + +### 环境变量 + +项目在 `__init__.py` 中设置了关键的 PyTorch 环境变量: +- `PYTORCH_ENABLE_MPS_FALLBACK=1` - 启用 MPS 回退 +- `TORCH_CUDNN_V8_API_LRU_CACHE_LIMIT=1` - 防止 GPU 上的 CPU 内存泄漏 + +### Docker 支持 + +- `docker/CPUDockerfile` - CPU 版本 +- `docker/GPUDockerfile` - GPU 版本(需要 NVIDIA GPU) +- 使用 `build_docker.sh` 构建镜像 + +## 依赖管理 + +- `requirements.txt` - 生产依赖(已更新到最新兼容版本) +- `requirements-dev.txt` - 开发依赖(wheel, twine, pytest-loguru) +- `web_app/package.json` - 前端依赖 +- PyTorch 版本: >= 2.0.0 +- Python 版本: >= 3.7 + +### 包版本更新 (2025-11-28) + +项目依赖已更新到最新稳定版本: +- `diffusers`: 0.27.2 → 0.35.2+ +- `huggingface_hub`: 0.25.2 → 0.26.0+ +- `peft`: 0.7.1 → 0.13.0+ +- `transformers`: 4.39.1+ → 4.45.0+ +- `controlnet-aux`: 0.0.3 → 0.0.9+ +- `fastapi`: 0.108.0 → 0.115.0+ +- `gradio`: 4.21.0 → 5.0.0+ (限制 < 6.0.0) +- `python-socketio`: 5.7.2 → 5.11.0+ +- `Pillow`: 9.5.0 → 10.0.0+ + +**代码修改:** +- 修复了 `iopaint/model/ldm.py:279` 中 `torch.cuda.amp.autocast()` 的弃用警告,改为 `torch.amp.autocast('cuda')` + +**安装建议:** +- 优先使用国内镜像源加速安装: + ```bash + pip3 install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com + ``` + +## 常见模式 + +### 图像处理流程 + +1. `helper.py::load_img()` - 加载图像 +2. `helper.py::decode_base64_to_image()` - 解码 base64 图像 +3. `helper.py::adjust_mask()` - 调整 mask 大小和格式 +4. `helper.py::pad_img_to_modulo()` - 填充图像到模型要求的倍数 +5. 模型处理 +6. `helper.py::pil_to_bytes()` / `numpy_to_bytes()` - 转换输出格式 + +### WebSocket 通信 + +- 使用 Socket.IO 进行实时通信 +- 主要用于长时间运行的任务进度更新 +- 定义在 `api.py` 的 Socket.IO 服务器中 diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..261eeb9 --- /dev/null +++ b/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/README.md b/README.md index ae2cafe..cb1ac8c 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,217 @@ -## 欢迎来到 Cloud Studio ## +

IOPaint

+

A free and open-source inpainting & outpainting tool powered by SOTA AI model.

-当前模板包含最简单的Hello World以及运行指令的Python示例代码仓库 +

+ + total download + + + version + + + python version + + + HuggingFace Spaces + + + Open in Colab + +

-## “运行”按钮怎么使用 ## +|Erase([LaMa](https://www.iopaint.com/models/erase/lama))|Replace Object([PowerPaint](https://www.iopaint.com/models/diffusion/powerpaint))| +|-----|----| +|