# image_lama

**Repository Path**: tree23/image_lama

## Basic Information

- **Project Name**: image_lama
- **Description**: 基于 LaMa (Large Mask Inpainting) 算法的高质量图像修复 Web 应用，支持智能填充和修复图片中的缺失区域。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-04
- **Last Updated**: 2026-06-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LaMa 图像修复工具

基于 LaMa (Large Mask Inpainting) 算法的高质量图像修复 Web 应用，支持智能填充和修复图片中的缺失区域。

## 🚀 快速开始（Docker）

### 拉取并运行 Docker 容器

```bash
# 1. 拉取镜像
docker pull crpi-vd2np7sloa8wv5h3.cn-qingdao.personal.cr.aliyuncs.com/rhzz/my_tools:imagelama

# 2. 运行容器（挂载本地项目目录到容器的/app，端口映射 8002）
docker run -d \
  --name imagelama \
  -p 8002:8002 \
  -v /home/liping/liping123/lamaP图项目/img_gradio:/app \
  crpi-vd2np7sloa8wv5h3.cn-qingdao.personal.cr.aliyuncs.com/rhzz/my_tools:imagelama \
  python /app/app.py
```

### 访问应用

浏览器打开：**http://localhost:8002**

局域网访问：**http://[服务器IP]:8002**

---

## 📖 项目简介

本项目使用 ModelScope 框架集成的 LaMa 模型，采用 FFT (快速傅里叶变换) 卷积技术，能够：
- 🎨 **智能修复**: 自动填充图片中的缺失区域
- 🖌️ **手绘涂抹**: 直观的画笔涂抹方式标记修复区域
- 🖼️ **高分辨率支持**: 支持高达 2K 分辨率的图像修复
- 💻 **CPU 友好**: 完全支持 CPU 推理，无需 GPU
- 🌐 **Web 界面**: 基于 Gradio 的友好用户界面

## ✨ 功能特性

### 核心功能
- **图像修复**: 使用 LaMa 算法进行高质量的图像内容填充
- **手绘涂抹**: 直接使用白色画笔在图片上涂抹需要修复的区域
- **多种掩码方式**:
  - 矩形掩码: 自定义位置和大小
  - 圆形掩码: 自定义位置和半径
  - 自定义掩码: 上传黑白掩码图片
- **实时预览**: 查看修复前后的对比效果

### 技术特点
- 采用 FFT 卷积 + 普通卷积的混合架构
- 仅在 256x256 分辨率下训练，即可处理高分辨率图像
- 适用于室外自然场景的图像修复

## 🛠️ 环境要求

- Python 3.8+
- 操作系统: Linux / Windows / macOS
- 内存: 建议 4GB 以上
- 存储: 至少 2GB 可用空间（用于模型文件）
- Docker（可选，推荐使用）

## 📦 安装步骤

### 方式一：Docker 部署（推荐）

见上方「快速开始」部分。

### 方式二：本地安装

#### 1. 配置国内镜像源（加速下载）

##### 配置 pip 镜像源
```bash
# 临时使用
pip install -i https://pypi.mirrors.ustc.edu.cn/simple <package_name>

# 永久配置
pip config set global.index-url https://pypi.mirrors.ustc.edu.cn/simple
```

##### 配置 apt 镜像源（Ubuntu/Debian）
```bash
# 备份原始源
cp /etc/apt/sources.list /etc/apt/sources.list.bak

# 编辑源列表
sudo nano /etc/apt/sources.list

# 替换为中科大镜像源
deb https://mirrors.ustc.edu.cn/ubuntu/ jammy main restricted universe multiverse
deb https://mirrors.ustc.edu.cn/ubuntu/ jammy-updates main restricted universe multiverse
deb https://mirrors.ustc.edu.cn/ubuntu/ jammy-backports main restricted universe multiverse
deb https://mirrors.ustc.edu.cn/ubuntu/ jammy-security main restricted universe multiverse

# 更新源
sudo apt update
```

#### 2. 从 ModelScope 下载模型

```bash
# 使用 ModelScope CLI 下载模型到当前目录
modelscope download --model iic/cv_fft_inpainting_lama --local_dir .
```

**说明**：
- `--model iic/cv_fft_inpainting_lama`: 指定要下载的模型 ID
- `--local_dir .`: 将模型下载到当前目录，会自动创建 `iic/cv_fft_inpainting_lama/` 文件夹
- 下载完成后，代码中通过 `model='./iic/cv_fft_inpainting_lama'` 加载本地模型

#### 3. 模型目录结构

下载完成后，模型文件结构如下：

```
iic/cv_fft_inpainting_lama/
├── pytorch_model.pt              # 主模型文件 (~500MB)
├── resnet50-imagenet.pth         # ResNet50 预训练权重
├── configuration.json            # 模型配置文件
├── README.md                     # 模型说明文档
├── ade20k/                       # ADE20K 语义分割相关权重
│   └── ade20k-resnet50dilated-ppm_deepsup/
│       └── encoder_epoch_20.pth
└── data/                         # 示例数据
    ├── 1.gif
    └── 2.gif
```

**关键文件说明**：
- `pytorch_model.pt`: LaMa 主模型，包含 FFT 卷积网络权重
- `resnet50-imagenet.pth`: ResNet50 骨干网络的预训练权重
- `configuration.json`: 模型配置信息（输入输出格式、参数等）
- `ade20k/`: ADE20K 数据集相关的语义分割模型权重（用于辅助修复）

#### 4. 安装 Python 依赖

```bash
# 进入项目目录
cd img_gradio

# 安装 Python 依赖（使用清华镜像源）
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

#### 5. 验证模型文件

确保以下模型文件存在:
```
iic/cv_fft_inpainting_lama/
├── pytorch_model.pt          # 主模型
├── resnet50-imagenet.pth     # ResNet50 预训练权重
├── configuration.json        # 模型配置
└── ade20k/                   # ADE20K 相关权重
    └── ade20k-resnet50dilated-ppm_deepsup/
        └── encoder_epoch_20.pth
```

## 🎯 使用方法

### 启动服务

#### Docker 方式
已在上文「快速开始」中说明。

#### 本地运行
```bash
# 运行应用
python app.py
```

服务将在 `http://0.0.0.0:8002` 启动

### 使用流程

#### 1. 上传图片
- 点击左侧"上传图片"区域
- 选择需要修复的图片（JPG/PNG格式）
- 或直接拖拽图片到上传区域

#### 2. 手绘涂抹 ⭐
- **自动进入画笔模式**: 图片加载后，可以直接用画笔涂抹
- **白色画笔**: 默认使用白色画笔（修复区域标记）
- **调整画笔大小**: 
  - 在"🖌️ 画笔设置"中调整滑块
  - 范围: 5-50像素
  - 推荐: 20-30像素用于大范围，5-10像素用于精细区域

#### 3. 涂抹技巧
- **涂抹要修复的区域**: 用白色画笔覆盖想要去除/修复的物体
- **略大于目标**: 建议涂抹区域略大于实际要修复的物体
- **边缘平滑**: 尽量保持涂抹边缘平滑，不要过于锯齿状
- **可以多次涂抹**: 可以在不同位置涂抹多个区域

#### 4. 开始修复
- 点击 "🚀 开始修复" 按钮
- 等待AI处理（CPU模式约5-30秒）
- 右侧实时显示修复结果

#### 5. 保存结果
- 在修复结果图片上右键
- 选择"图片另存为"
- 或截图保存

#### 6. 清除与重置
- **清除涂抹**: 点击 "🗑️ 清除涂抹" 按钮，只清除画笔痕迹，保留原始图片
- **完全重置**: 点击 "🔄 重置" 按钮，清除所有内容和状态

### 其他掩码方式（高级）

#### 矩形掩码
1. 选中"矩形"选项
2. 调整滑块:
   - 中心X位置: 控制左右位置（0-100%）
   - 中心Y位置: 控制上下位置（0-100%）
   - 宽度: 控制修复区域宽度（5-80%）
   - 高度: 控制修复区域高度（5-80%）

#### 圆形掩码
1. 选中"圆形"选项
2. 调整滑块:
   - 中心X/Y位置: 控制圆心位置
   - 半径: 控制圆形大小（5-50%）

#### 自定义掩码
1. 选中"自定义"选项
2. 上传黑白掩码图片:
   - 白色区域 = 需要修复的部分
   - 黑色区域 = 保持不变的部分
   - 尺寸需与原图相同

## 📁 项目结构

```
img_gradio/
├── app.py                      # 主应用程序
├── requirements.txt            # Python 依赖
├── README.md                   # 项目说明文档
├── start.sh                    # 启动脚本
└── iic/
    └── cv_fft_inpainting_lama/ # LaMa 模型文件
        ├── pytorch_model.pt
        ├── resnet50-imagenet.pth
        ├── configuration.json
        └── ...
```

## 🛠️ 技术栈

- **深度学习框架**: PyTorch (CPU 版本)
- **模型库**: ModelScope
- **Web 框架**: Gradio
- **图像处理**: OpenCV, Pillow, NumPy
- **模型算法**: LaMa (FFT-based Image Inpainting)

## 🧠 模型说明

### LaMa 模型

LaMa (Resolution-robust Large Mask Inpainting with Fourier Convolutions) 是一种先进的图像修复算法:

- **核心创新**: 使用 FFT 卷积捕获全局上下文信息
- **训练数据**: Places2 数据集（800 万张自然图像）
- **性能指标**:
  - FID: 2.97 (Places2 验证集)
  - SSIM: 高质量结构相似性
- **适用场景**: 室外自然场景、物体移除、内容填充

### 局限性

- ❌ 不支持人脸修复
- ❌ 不适合文本区域的修复
- ⚠️ 复杂纹理区域可能需要多次尝试
- ⚠️ 首次加载模型需要一定时间

## ❓ 常见问题

### Q1: 模型加载失败怎么办?
A: 检查 `iic/cv_fft_inpainting_lama/` 目录下是否有完整的模型文件，特别是 `pytorch_model.pt` 和 `resnet50-imagenet.pth`。

### Q2: 修复效果不理想?
A: 
- 尝试调整涂抹区域的大小和位置
- 确保涂抹准确覆盖需要修复的区域
- 对于复杂场景，可以尝试不同的涂抹形状
- 避免修复人脸或文字区域

### Q3: 处理速度慢?
A: 
- CPU 推理本身较慢，这是正常现象
- 降低输入图片分辨率可以加快速度
- 确保系统有足够的内存（建议 4GB+）

### Q4: 如何更换端口?
A: 修改 `app.py` 最后一行:
```python
demo.launch(server_name="0.0.0.0", server_port=8002)  # 修改 port 参数
```

### Q5: 为什么看不到画笔?
A: 
- 确保图片已完全加载
- 检查是否在图片区域内
- 刷新页面重试

### Q6: 涂抹后没反应?
A:
- 检查涂抹区域是否够大（至少100个像素）
- 确认使用的是白色画笔
- 查看状态提示信息

### Q7: 如何保存结果?
A: 
- 在输出图片上右键 → "图片另存为"
- 或者截图保存
- 结果保存在系统临时目录

## ⚡ 性能优化建议

1. **图片预处理**: 
   - 将大图缩放到合适尺寸（如 1024x1024）
   - 保存为 PNG 格式以保持质量

2. **涂抹优化**:
   - 尽量使用较小的修复区域
   - 避免过于复杂的涂抹形状
   - 保持边缘平滑

3. **系统资源**:
   - 关闭其他占用内存的程序
   - 确保有足够的磁盘空间用于临时文件

### 性能参考

| 图片尺寸 | 涂抹区域 | 处理时间(CPU) |
|---------|---------|--------------|
| 512x512 | 小(10%) | ~5秒 |
| 1024x1024 | 中(20%) | ~15秒 |
| 2048x2048 | 大(30%) | ~30秒 |

*注: 实际时间取决于系统性能*

## 🔧 高级配置

### 修改为GPU模式
编辑 `app.py` 第24行:
```python
device='cpu'  # 改为 device='cuda'
```

### 启用公开分享
编辑 `app.py` 最后一行:
```python
demo.launch(server_name="0.0.0.0", server_port=8002, share=True)
```

### 停止服务
在运行应用的终端按 `Ctrl+C`

### 重新启动
```bash
cd img_gradio
./start.sh
# 或者
python app.py
```

## 📊 性能指标

- **内存占用**: ~1.7GB (运行时)
- **模型大小**: ~500MB
- **启动时间**: ~15秒
- **推理速度**: 取决于图片大小，CPU模式下约5-30秒/张

### Q5: 为什么看不到画笔?
A: 
- 确保图片已完全加载
- 检查是否在图片区域内
- 刷新页面重试

### Q6: 涂抹后没反应?
A:
- 检查涂抹区域是否够大（至少100个像素）
- 确认使用的是白色画笔
- 查看状态提示信息

### Q7: 如何保存结果?
A: 
- 在输出图片上右键 → "图片另存为"
- 或者截图保存
- 结果保存在系统临时目录

## ⚡ 性能优化建议

1. **图片预处理**: 
   - 将大图缩放到合适尺寸（如 1024x1024）
   - 保存为 PNG 格式以保持质量

2. **涂抹优化**:
   - 尽量使用较小的修复区域
   - 避免过于复杂的涂抹形状
   - 保持边缘平滑

3. **系统资源**:
   - 关闭其他占用内存的程序
   - 确保有足够的磁盘空间用于临时文件

### 性能参考

| 图片尺寸 | 涂抹区域 | 处理时间(CPU) |
|---------|---------|--------------|
| 512x512 | 小(10%) | ~5秒 |
| 1024x1024 | 中(20%) | ~15秒 |
| 2048x2048 | 大(30%) | ~30秒 |

*注: 实际时间取决于系统性能*

## 📝 引用

如果本项目对您的研究有帮助，请引用相关论文:

```bibtex
@article{suvorov2021resolution,
  title={Resolution-robust Large Mask Inpainting with Fourier Convolutions},
  author={Suvorov, Roman and Logacheva, Elizaveta and Mashikhin, Anton and Remizova, Anastasia and Ashukha, Arsenii and Silvestrov, Aleksei and Kong, Naejin and Goka, Harshith and Park, Kiwoong and Lempitsky, Victor},
  journal={arXiv preprint arXiv:2109.07161},
  year={2021}
}

@article{kulshreshtha2022feature,
  title={Feature Refinement to Improve High Resolution Image Inpainting},
  author={Kulshreshtha, Prakhar and Pugh, Brian and Jiddi, Salma},
  journal={arXiv preprint arXiv:2206.13644},
  year={2022}
}
```

## 📄 许可证

本项目使用的 LaMa 模型遵循 Apache License 2.0

## 📞 联系方式

如有问题或建议，欢迎提交 Issue 或 Pull Request。

---

**⚠️ 注意**: 本项目仅用于学习和研究目的，请遵守相关法律法规和版权规定。

**祝使用愉快！** 🎨✨