# py-watermark

**Repository Path**: flyflyrun/py-watermark

## Basic Information

- **Project Name**: py-watermark
- **Description**: 去除文件中的水印
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-03
- **Last Updated**: 2025-07-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PDF水印去除API服务

🎯 **基于 FastAPI 和 uv 包管理的现代化PDF水印去除API服务**

这是一个功能强大的PDF水印去除工具集，提供Web API接口和现代化的用户界面。

## 🚀 主要特性

### 🔧 技术特性
- **现代化架构**: FastAPI + uv 包管理 + 异步处理
- **多种处理方法**: PyMuPDF、PyPDF4、图像处理、混合方法
- **智能检测**: 自动识别文本水印、图像水印、透明层水印
- **灵活配置**: 支持自定义水印关键词和处理参数
- **高质量输出**: 保持原始PDF的质量和格式

### 📡 API特性
- **RESTful API**: 标准的HTTP接口
- **异步处理**: 支持长时间运行的任务
- **实时状态**: 任务状态实时查询
- **批量处理**: 支持多文件并发处理
- **Web界面**: 内置美观的Web界面

## 🛠️ 快速开始

### 1. 安装 uv 包管理器
```bash
# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell
powershell -c "irm https://astral.sh/uv/install.sh | iex"

# 或者访问: https://docs.astral.sh/uv/getting-started/installation/
```

### 2. 启动服务
```bash
# 一键启动（自动安装依赖并启动服务）
python run.py
```

### 3. 访问服务
服务启动后，访问以下地址：
- 🌐 **Web界面**: http://localhost:8000
- 📚 **API文档**: http://localhost:8000/docs  
- 📖 **ReDoc文档**: http://localhost:8000/redoc

## 📦 项目结构

```
pdf-watermark-api/
├── app/                          # 应用核心代码
│   ├── __init__.py
│   ├── main.py                   # FastAPI主应用
│   ├── core/
│   │   └── watermark_remover.py  # 核心水印去除逻辑
│   └── api/
│       ├── models.py             # 数据模型
│       └── routes.py             # API路由
├── pyproject.toml                # 项目配置和依赖
├── run.py                        # 启动脚本
├── client_example.py             # 客户端使用示例
├── test_setup.py                 # 环境测试脚本
├── README.md                     # 项目文档
└── 旧版文件/                     # 命令行版本文件
    ├── pdf_watermark_remover.py
    ├── simple_watermark_remover.py
    └── compare_methods.py

## 📋 API 使用方法

### 1. Web界面使用（推荐新手）

1. 访问 http://localhost:8000
2. 在Web界面中上传PDF文件
3. 选择处理方法和参数
4. 点击开始处理
5. 等待完成后下载结果

### 2. HTTP API调用

#### 异步处理（推荐）
```bash
# 上传文件并开始处理
curl -X POST "http://localhost:8000/api/v1/upload-and-process" \
  -F "file=@input.pdf" \
  -F "method=pymupdf" \
  -F "watermark_keywords=CONFIDENTIAL,DRAFT"

# 查询任务状态
curl "http://localhost:8000/api/v1/task/{task_id}"

# 下载结果
curl "http://localhost:8000/api/v1/download/{task_id}" -o cleaned.pdf
```

#### 同步处理
```bash
curl -X POST "http://localhost:8000/api/v1/process-sync" \
  -F "file=@input.pdf" \
  -F "method=hybrid" \
  -F "watermark_keywords=水印,DRAFT"
```

### 3. Python客户端

```python
from client_example import PDFWatermarkClient

# 创建客户端
client = PDFWatermarkClient("http://localhost:8000")

# 异步处理
task_id = client.upload_and_process_async(
    pdf_path="input.pdf",
    method="pymupdf",
    watermark_keywords=["CONFIDENTIAL", "DRAFT"]
)

# 等待完成
result = client.wait_for_completion(task_id)

# 下载结果
if result['status'] == 'completed':
    client.download_result(task_id, "cleaned.pdf")
```

### 4. 命令行版本（兼容旧版）

```bash
# 使用旧版命令行工具
python simple_watermark_remover.py input.pdf output.pdf "CONFIDENTIAL"
python pdf_watermark_remover.py input.pdf output.pdf --method hybrid
```

## 🎯 处理方法对比

| 方法 | 适用场景 | 优势 | 劣势 |
|------|----------|------|------|
| **PyMuPDF** | 大多数PDF水印 | 速度快，保持原格式 | 对某些复杂水印效果有限 |
| **pypdf** | 简单文本水印 | 现代化，性能优化 | 功能相对有限 |
| **图像处理** | 复杂图像水印 | 效果强大，可处理各种水印 | 速度慢，可能影响质量 |
| **混合方法** | 复杂水印 | 综合多种技术优势 | 处理时间较长 |

## 📋 支持的水印类型

### ✅ 能够处理的水印
- 文本水印（如"CONFIDENTIAL"、"DRAFT"等）
- 透明图像水印（Logo、印章等）
- 重复背景图案
- 页面背景水印
- 半透明覆盖层

### ⚠️ 处理困难的水印
- 深度嵌入的矢量水印
- 加密保护的水印
- 与正文内容高度融合的水印

## 🔧 高级配置

### 在代码中使用
```python
from pdf_watermark_remover import PDFWatermarkRemover

# 创建处理器实例
remover = PDFWatermarkRemover()

# 处理PDF文件
success = remover.process_pdf(
    input_path="input.pdf",
    output_path="output.pdf", 
    method="hybrid",
    watermark_keywords=["水印", "DRAFT"]
)

if success:
    print("水印移除成功！")
```

### 自定义参数调整
在`pdf_watermark_remover.py`中可以调整以下参数：
- `avg_alpha < 180`: 透明度阈值（越小越严格）
- `area < 50000`: 图像大小阈值（小图像可能是水印）
- `count > 10`: 重复图案阈值（重复次数判断）

## 🚨 注意事项

1. **版权合规**: 确保您有权利移除PDF中的水印
2. **备份原文件**: 处理前请备份原始PDF文件
3. **质量检查**: 处理后请检查输出文件的质量
4. **内存使用**: 大文件处理时可能需要较多内存
5. **法律责任**: 仅用于合法用途，不得用于侵权行为

## 🔍 故障排除

### 常见问题

**Q: 提示"无法打开PDF文件"**
A: 检查PDF文件是否损坏或受密码保护

**Q: 处理后水印仍然存在**
A: 尝试使用`hybrid`方法或调整检测参数

**Q: 输出文件质量下降**
A: 避免使用`image_based`方法，优先使用`pymupdf`

**Q: 处理速度很慢**
A: 大文件处理时间较长是正常的，可以先用小文件测试

### 日志分析
程序会输出详细的处理日志，包括：
- 发现的水印类型和位置
- 处理步骤和结果
- 错误信息和警告

## 📈 性能优化建议

1. **选择合适的方法**: 对于简单水印优先使用PyMuPDF
2. **分页处理**: 对于大文件可以考虑分页处理
3. **参数调优**: 根据具体水印类型调整检测参数
4. **硬件配置**: 图像处理方法需要较好的CPU和内存

## 🤝 贡献指南

欢迎提交问题报告和功能建议！如果您想贡献代码：
1. Fork这个项目
2. 创建您的功能分支
3. 提交更改
4. 推送到分支
5. 开启Pull Request

## 📜 许可证

本项目仅供学习和研究使用。使用时请遵守相关法律法规，尊重版权。

---

**免责声明**: 本工具仅用于合法用途。用户应确保有权移除PDF中的水印，并承担使用本工具的所有法律责任。