# doc-image-enhance

**Repository Path**: devoink/doc-image-enhance

## Basic Information

- **Project Name**: doc-image-enhance
- **Description**: 文本图像增强
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-12-19
- **Last Updated**: 2025-12-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 文档扫描增强工具

一个最小可行的文档图像处理工具，用于将拍摄的文档图片转换为类似扫描件的清晰黑白图像。

## 功能特性

### 核心功能

1. **文档图像增强**

   - 自适应阈值处理，保持文字粗细均匀
   - CLAHE 对比度增强
   - OTSU 背景清理，去除噪点
   - 智能边缘清理，去除纸张外的黑色条纹

2. **文档方向校正**
   - 自动检测文档方向（0°、90°、180°、270°）
   - 自动旋转到正确方向

### 扩展功能（模块化设计）

3. **切边增强** - 自动检测文档边缘并裁剪，切除无关背景
4. **文字锐化** - 专门针对文字的锐化处理，增强文字边缘清晰度
5. **去除阴影** - 检测并去除文档阴影，使文档更加清晰明亮
6. **灰度模式** - 保留灰度信息的灰度图输出（非二值化）
7. **去摩尔纹** - 去除拍摄屏幕产生的摩尔纹

### 输出模式

所有输出模式都在预处理（切边、去阴影、锐化等）之后最后应用：

- **原图模式**：只应用预处理功能，保持原始图像格式和颜色
- **黑白模式**：将图片转化为黑白二值图，保留原始图片中的边缘信息（默认）
- **灰度模式**：简单去色，转换为灰度图

## 安装

### 方式一：使用 Conda（推荐）

1. 创建 conda 虚拟环境：

```bash
conda create -n doc-scanner python=3.10 -y
```

2. 激活环境并安装依赖：

```bash
conda activate doc-scanner
pip install -r requirements.txt
```

### 方式二：使用 venv

1. 创建虚拟环境：

```bash
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
```

2. 安装依赖：

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

## 使用方法

### 方式一：Web UI 界面（推荐）

使用 Gradio 提供的图形界面，操作简单直观：

#### 开发模式（支持热重载）

```bash
# 激活环境
conda activate doc-scanner

# 使用 gradio 命令启动（支持热重载，代码更改自动重新加载）
gradio app.py

# 或者直接使用 conda run
conda run -n doc-scanner gradio app.py
```

#### 生产模式

```bash
# 激活环境
conda activate doc-scanner

# 使用 python 启动
python app.py

# 或者直接使用 conda run
conda run -n doc-scanner python app.py
```

启动后，在浏览器中打开 `http://localhost:7860` 即可使用。

**Web UI 功能：**

- 📤 拖拽或点击上传文档图片
- ⚙️ 丰富的处理选项（方向校正、切边、去阴影、锐化、去摩尔纹等）
- 🎨 多种输出模式（原图模式、黑白模式、灰度模式）
- 🚀 一键处理，实时查看结果
- 💾 右键保存处理后的图片
- 🔥 开发模式支持热重载，无需手动重启

### 方式二：命令行界面

#### 使用 Conda 环境

```bash
# 激活环境
conda activate doc-scanner

# 运行程序
python main.py input.jpg output.jpg

# 或者直接使用 conda run（无需激活）
conda run -n doc-scanner python main.py input.jpg output.jpg
```

#### 使用 venv 环境

```bash
# 激活环境后运行
python main.py input.jpg output.jpg
```

#### 参数说明

- `input.jpg`: 输入的文档图片路径
- `output.jpg`: 输出处理后的图片路径
- `--no-orientation`: 可选，禁用方向校正（仅进行图像增强）

#### 示例

```bash
# 完整处理（方向校正 + 图像增强）
python main.py input/001.jpg output/001_enhanced.jpg

# 仅增强，不校正方向
python main.py input/001.jpg output/001_enhanced.jpg --no-orientation
```

## 项目结构

```
doc-scanner/
├── app.py                  # Gradio Web UI 界面（支持热重载）
├── main.py                 # 命令行主程序入口
├── image_processor.py      # 图像处理主流程（整合所有模块）
├── image_enhancer.py       # 黑白模式模块（黑白二值化，保留边缘信息）
├── orientation_corrector.py # 方向校正模块
├── modules/                # 功能模块目录
│   ├── __init__.py
│   ├── edge_detection.py   # 切边增强模块
│   ├── text_sharpening.py  # 文字锐化模块
│   ├── shadow_removal.py   # 去除阴影模块
│   ├── grayscale_mode.py   # 灰度模式模块
│   └── moire_removal.py    # 去摩尔纹模块
├── requirements.txt        # 依赖包列表
├── environment.yml         # Conda 环境配置
├── OPTIMIZATION_PLAN.md   # 功能优化计划
└── README.md              # 使用说明
```

## 技术栈

- Python 3.8+
- OpenCV: 图像处理核心库
- NumPy: 数值计算
- Pillow: 图像 I/O
- Gradio: Web UI 界面框架