# 图片尺寸调整工具使用说明

## 功能描述

`resize_image.py` 是福建水务营收系统文档生成工具的配套脚本，用于通过调整图片DPI元数据来控制Mermaid图表的打印高度，确保图片打印时高度不超过23公分，适合A4纸张打印。该方法保持图片像素不变，仅修改打印尺寸信息。

## 依赖要求

- Python 3.6+
- Pillow库：`pip3 install Pillow`

## 使用方法

### 基本用法

```bash
# 调整单个图片（默认限制23公分高度）
python3 scripts/resize_image.py path/to/image.png

# 指定最大高度（厘米）
python3 scripts/resize_image.py path/to/image.png --max-height 20

# 指定DPI（默认96）
python3 scripts/resize_image.py path/to/image.png --dpi 300

# 显示详细信息
python3 scripts/resize_image.py path/to/image.png --verbose
```

### 参数说明

- `image_path`: 要处理的图片文件路径
- `--max-height`: 最大高度（厘米），默认23.0
- `--dpi`: DPI设置，默认96
- `--verbose`: 显示详细处理信息

## 自动集成

该脚本已集成到 `unified_export.sh` 中，在Mermaid图表转换成功后自动调用，无需手动执行。

### 集成流程

1. Mermaid代码转换为PNG图片
2. 自动调用 `resize_image.py` 调整图片尺寸
3. 继续文档生成流程

### 错误处理

- 如果Python3未安装，会显示警告但不影响文档生成
- 如果图片调整失败，会显示警告但继续使用原图
- 如果图片高度已符合要求，不会进行调整

## 技术细节

### DPI计算原理

- 计算公式：DPI = 像素高度 ÷ (目标高度厘米 ÷ 2.54)
- 例如：1000像素高度，目标23cm → DPI = 1000 ÷ (23 ÷ 2.54) ≈ 110 DPI

### 图片处理方式

- **元数据调整**：仅修改DPI元数据，不改变像素
- **像素完整性**：保持原始图片像素质量
- **打印控制**：通过DPI控制物理打印尺寸
- **高质量保存**：质量设置为95%，启用图片优化

### 支持格式

- PNG（主要格式）
- JPEG
- GIF
- BMP
- 其他PIL支持的格式

## 示例输出

### 需要调整的图片
```
📏 图片信息:
   像素尺寸: 1200x1000px
   当前DPI: 96
   当前打印高度: 26.46cm
🔧 调整DPI元数据:
   原始DPI: 96
   调整后DPI: 110
   目标打印高度: 23.0cm
   像素尺寸保持不变: 1200x1000px
✅ 图片DPI元数据调整完成: temp_mermaid_demo_12345/diagram_1.png
   现在图片将以 23.0cm 高度打印
```

### 无需调整的图片
```
📏 图片信息:
   像素尺寸: 800x600px
   当前DPI: 96
   当前打印高度: 15.88cm
✅ 图片打印高度 15.88cm 符合要求，无需调整
```

## 故障排除

### 常见问题

1. **"文件不存在"错误**
   - 检查文件路径是否正确
   - 确认文件确实存在

2. **"Pillow未安装"错误**
   ```bash
   pip3 install Pillow
   ```

3. **权限错误**
   ```bash
   chmod +x scripts/resize_image.py
   ```

4. **图片格式不支持**
   - 确保图片格式为PNG、JPEG等常见格式
   - 检查图片文件是否损坏

### 调试模式

使用 `--verbose` 参数可以查看详细的处理信息：

```bash
python3 scripts/resize_image.py image.png --verbose
```

## 版本信息

- 版本：1.0
- 最后更新：2024-12-19
- 兼容性：Python 3.6+, Pillow 8.0+