# Image Fitz - 高质量图像预处理插件

**Author:** chenlong028  
**Version:** 0.0.1  
**Type:** Dify Plugin Tool  

## 📖 项目描述

Image Fitz 是一个基于 PyMuPDF(fitz) 的 Dify 插件，专门用于图像预处理和高质量渲染。该插件能够将输入的图片按指定 DPI 重新渲染，生成高质量的图像输出，特别适用于需要提升图像质量或统一图像规格的场景。

## ✨ 功能特性

- 🖼️ **多种输入格式支持**：支持本地文件路径、HTTP(S) URL、Base64 数据 URI 和 PIL.Image 对象
- 🎯 **自定义 DPI 渲染**：可指定目标 DPI 进行高质量图像渲染（默认 200 DPI）
- 🚀 **智能优化**：自动处理超大图像，避免内存溢出问题
- 🔧 **易于集成**：作为 Dify 插件，可直接在工作流中使用
- 📦 **轻量级**：基于成熟的 PyMuPDF 库，性能稳定可靠

## 🛠️ 安装说明

### 依赖要求

- Python 3.11+
- PyMuPDF >= 1.23.0
- Pillow >= 10.0.0
- requests >= 2.31.0
- dify_plugin >= 0.4.0

### 安装步骤

1. 克隆项目到本地：
```bash
git clone <repository-url>
cd image_fitz
```

2. 安装依赖：
```bash
pip install -r requirements.txt
```

3. 在 Dify 中安装插件：
   - 将插件目录复制到 Dify 插件目录
   - 或通过 Dify 插件市场安装

## 🚀 使用示例

### 在 Dify 工作流中使用

1. 在工作流中添加 "Image Fitz Processor" 工具
2. 配置参数：
   - **image_input**: 图像输入（URL、文件路径或 Base64）
   - **target_dpi**: 目标 DPI（可选，默认 200）

### API 调用示例

```python
from tools.image_fitz import render_image_at_dpi

# 处理本地图片
processed_image = render_image_at_dpi("path/to/image.jpg", target_dpi=300)

# 处理网络图片
processed_image = render_image_at_dpi("https://example.com/image.png", target_dpi=200)

# 处理 PIL Image 对象
from PIL import Image
img = Image.open("image.jpg")
processed_image = render_image_at_dpi(img, target_dpi=150)
```

## 📋 参数说明

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| image_input | string | 是 | - | 图像输入，支持 URL、文件路径、Base64 数据 URI |
| target_dpi | number | 否 | 200 | 目标渲染 DPI，影响输出图像质量 |

## 🔧 核心功能

### 主要函数

- `render_image_at_dpi()`: 主要 API，按指定 DPI 渲染图像
- `get_image_by_fitz_doc()`: 兼容函数，功能同上
- `fitz_doc_to_image()`: 将 fitz.Page 渲染为 PIL.Image

### 支持的输入格式

- **本地文件路径**: `/path/to/image.jpg`
- **HTTP(S) URL**: `https://example.com/image.png`
- **Base64 数据 URI**: `data:image/png;base64,iVBORw0KGgo...`
- **PIL.Image 对象**: 直接传入 PIL Image 实例

## 🎯 使用场景

- 📸 **图像质量提升**: 将低分辨率图像渲染为高质量版本
- 📏 **规格统一**: 将不同来源的图像统一为相同 DPI
- 🔄 **格式转换**: 在保持质量的同时进行格式转换
- 🖨️ **打印准备**: 为打印输出准备高 DPI 图像
- 🤖 **AI 预处理**: 为 AI 模型提供标准化的图像输入

## ⚠️ 注意事项

- 超大图像（宽度或高度 > 4500px）会自动回退到默认 DPI 以避免内存问题
- 网络图片下载可能受网络环境影响，建议添加适当的错误处理
- 高 DPI 设置会增加处理时间和内存使用

## 📄 许可证

本项目采用 MIT 许可证，详见 LICENSE 文件。

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request 来改进这个项目！

1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📞 联系方式

如有问题或建议，请通过以下方式联系：

- 作者: chenlong028
- 项目地址: [GitHub Repository]