# HEIC

**Repository Path**: yngeek/heic

## Basic Information

- **Project Name**: HEIC
- **Description**: 一款专为Deepin 25系统或其他 Debian 系发行版设计的多功能图片批处理工具，支持 HEIC/JPG/PNG图片批量压缩、尺寸调整、元数据清理、重命名和水印添加。支持HEIC/HEIF批量转换为JPG/PNG/WebP格式。
- **Primary Language**: Python
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2026-01-06
- **Last Updated**: 2026-03-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# From scratch 图片批处理工具 v3.1

一款专为 Deepin 25 系统或其他 Debian 系发行版设计的多功能图片批处理工具，支持 HEIC/JPG/PNG图片批量压缩、尺寸调整、元数据清理、重命名和水印添加。支持HEIC/HEIF批量转换为JPG/PNG/WebP格式。

--- 

## 版本信息

- **版本号**: v3.1
- **发布日期**: 2026年1月21日
- **更新类型**: 功能增强

--- 

## ✨ 特性

### 核心功能

- 🚀 **批量转换**：支持添加多个文件，自动队列处理（最多 50 个文件）

- 🖱️ **拖拽支持**：直接拖拽文件到应用界面，快速添加

- 🎨 **多格式支持**：JPG、PNG、WebP、HEIC、HEIF

- ⚡ **多线程处理**：支持 1-8 个并发线程，提升转换速度

- 🛡️ **智能容错**：自动处理元数据错误，解决转换失败问题

- 📁 **自定义输出**：支持自定义输出目录

- 📊 **进度统计**：实时显示处理进度和统计信息

- 💾 **配置持久化**：自动保存用户偏好设置

- 📝 **详细日志**：完整的处理日志和历史记录

- 🎯 **现代化 UI**：符合 Deepin 视觉风格，操作简单直观

- 📋 **顶部菜单栏**：专业的文件、编辑、帮助菜单，操作更便捷

- ⌨️ **快捷键支持**：常用操作快捷键（Ctrl+O、Ctrl+S、Ctrl+Q 等），提升效率

- 📚 **使用教程系统**：内置浏览器方式打开帮助文档，支持完整渲染

- 🗜️ **图片压缩**：智能压缩算法，预设压缩等级（邮件、文档、网页、高质量、超轻量）

- 📐 **尺寸调整**：批量调整图片尺寸，支持宽度、高度、百分比和预设尺寸

- 🧹 **元数据清理**：一键清除 EXIF 信息，保护隐私

- ✏️ **批量重命名**：自定义前缀+序号模式，快速重命名文件

- 💧 **水印添加**：支持文字和图片水印，独立的位置和透明度控制

- 🔄 **多功能组合**：可同时启用多个功能，按顺序自动处理

- ✅ 转换图片错误修复以及水印图片自动修复功能

--- 

## 3.1新增功能

### 1. 顶部菜单栏

为应用添加了专业的顶部菜单栏，提供更便捷的操作方式：

**文件菜单**

- 添加文件 (Ctrl+O)
- 退出应用 (Ctrl+Q)

**编辑菜单**

- 全选文件 (Ctrl+A)
- 删除选中文件 (Delete)
- 清空列表

**帮助菜单**

- 使用教程 - 在浏览器中打开完整的使用教程
- 关于 - 显示应用版本和开发者信息

### 2. 快捷键支持

新增以下快捷键，提升操作效率：

| 快捷键    | 功能     |
| ------ | ------ |
| Ctrl+O | 添加文件   |
| Ctrl+S | 开始处理   |
| Ctrl+Q | 退出应用   |
| Delete | 删除选中文件 |
| Ctrl+A | 全选文件   |

### 3. 使用教程系统

- 使用浏览器方式打开帮助文档
- 支持完整的 Markdown 渲染
- 美观的 HTML 样式设计
- 支持搜索、打印、书签等浏览器功能
- 包含详细的操作指南和常见问题解答

---

## 优化改进

### 1. 退出确认提示

- 按 Ctrl+Q 或点击菜单"退出"时，会弹出确认对话框
- 防止用户不小心按错键导致意外退出
- 用户可以选择"是"退出或"否"返回软件界面

### 2. 默认文件目录优化

- 文件选择对话框默认打开用户主目录
- 简化了目录选择流程
- 提升用户体验

### 3. 菜单交互优化

- 点击菜单按钮显示下拉菜单
- 点击菜单外部区域自动关闭菜单
- 菜单项点击后自动关闭菜单
- 流畅的交互体验

---

## 技术细节

### 菜单系统

- 使用 CustomTkinter 实现现代化菜单界面
- 支持深色/浅色主题自动切换
- 菜单项包含快捷键提示

### 帮助系统

- Markdown 到 HTML 自动转换
- 临时 HTML 文件生成和清理
- 使用系统默认浏览器打开
- 完整的 CSS 样式美化

### 快捷键系统

- 绑定到主窗口
- 支持大小写不敏感
- 与现有功能完美集成

--- 

## 🚀 快速开始

### 安装方式

#### 方式 1：安装 Deb 包（推荐）

```bash
# 下载 Deb 包后直接安装
sudo dpkg -i from-scratch-img_3.1_amd64.deb

# 或使用 apt
sudo apt install ./from-scratch-img_3.1_amd64.deb
```

**优势**：

- ✅ 所有依赖已打包，无需额外配置
- ✅ 包含桌面快捷方式和图标
- ✅ 一键安装，开箱即用

#### 方式 2：Windows 版本

**下载 Windows 安装程序**

```bash
# 下载 Windows 安装包 （暂无）
FromScratchImageProcessor_v3.0.0_Windows_x64_Setup.exe

# 或下载压缩包 （有）
FromScratchImageProcessor_v3.0.0_Windows_x64.zip
```

**安装方法**

1. 双击运行 `FromScratchImageProcessor_v3.0.0_Windows_x64_Setup.exe`
2. 按照安装向导完成安装
3. 从开始菜单或桌面快捷方式启动应用

**系统要求**

- Windows 10/11 (64-bit)
- 4GB RAM
- 100MB 可用磁盘空间

详细说明请参考 [Windows 用户手册](WINDOWS_USER_MANUAL.md)

#### 方式 3：从源码运行

```bash
# 克隆项目源码到本地
git clone https://gitee.com/yngeek/heic.git

# 进入项目目录，例如：
cd /heic

# 安装依赖（使用虚拟环境）
./start.sh

# 或手动安装
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

### 使用方法

1. **启动应用**
   
   - Deb 包安装后：从应用菜单启动
   - 源码运行：`./start.sh`

2. **添加文件**
   
   - 点击"+ 添加文件"按钮选择图片文件（支持 HEIC、HEIF、JPG、PNG、WebP）
   - 或直接拖拽文件到右侧文件列表区域

3. **选择功能**
   
   - 在左侧选项卡选择需要使用的功能：
     - **格式转换**：HEIC/HEIF 转 JPG/PNG/WebP
     - **压缩**：智能压缩图片，减小文件体积
     - **尺寸**：调整图片尺寸，支持多种模式
     - **元数据**：清理 EXIF 信息，保护隐私
     - **重命名**：批量重命名文件
     - **水印**：添加文字或图片水印

4. **配置参数**
   
   - 根据选择的功能配置相应参数
   - 可同时启用多个功能（如：压缩+尺寸+水印）
   - 设置输出格式和质量
   - 选择输出目录

5. **开始处理**
   
   - 点击"开始处理"按钮
   - 等待处理完成
   - 查看处理结果和统计信息

**注意**：无论在哪个选项卡点击"开始处理"，都会执行所有已启用的功能。

详细使用说明请参考 [用户手册](用户手册.md)。

## 📁 项目结构

```
.
├── main.py                 # 主程序入口
├── requirements.txt        # Python 依赖
├── Makefile               # 构建和测试命令
├── build.spec             # PyInstaller 打包配置
├── from-scratch-img.desktop # 桌面快捷方式
├── start.sh               # 启动脚本
├── src/                   # 源代码目录
│   ├── __init__.py
│   ├── config_manager.py  # 配置管理
│   ├── logger.py          # 日志管理
│   ├── converter.py       # 转换核心
│   ├── history.py         # 历史记录
│   ├── compressor.py      # 图片压缩
│   ├── resizer.py         # 尺寸调整
│   ├── metadata_cleaner.py # 元数据清理
│   ├── renamer.py         # 批量重命名
│   └── watermark.py       # 水印添加
├── tests/                 # 测试目录
│   ├── __init__.py
│   ├── test_config_manager.py
│   ├── test_converter.py
│   └── test_history.py
├── icons/                 # 图标目录
├── logs/                  # 日志目录（自动创建）
├── config/                # 配置目录（自动创建）
├── 开发文档.md            # 开发文档
├── 用户手册.md            # 用户使用手册
├── README.md              # 本文件
└── 拓展功能列表.md        # 拓展功能说明
```

## 🛠️ 开发

### 运行测试

```bash
source venv/bin/activate
python -m pytest tests/ -v
```

### 打包应用

```bash
source venv/bin/activate
pyinstaller build.spec --clean
```

打包后的可执行文件位于 `dist/HEIC-Converter`。

### 安装桌面快捷方式

```bash
cp from-scratch-img.desktop ~/.local/share/applications/from-scratch-img.desktop
chmod +x ~/.local/share/applications/from-scratch-img.desktop
```

## 📋 可用命令

```bash
./start.sh              # 启动应用（推荐）
make install           # 安装依赖
make test              # 运行测试
make run               # 运行应用
make build             # 打包应用
make clean             # 清理构建文件
```

## 🎯 核心功能

### 1. 格式转换

支持一次添加多个 HEIC/HEIF 文件（最多 50 个），自动排队处理。

- **输入格式**：HEIC、HEIF、JPG、PNG、WebP
- **输出格式**：JPG、PNG、WebP
- **质量设置**：0-100 可调
- **EXIF 保留**：可选保留或移除 EXIF 信息

### 2. 拖拽支持

- 直接从文件管理器拖拽文件到应用界面
- 支持批量拖拽多个文件
- 拖拽时有视觉反馈（背景色变化）
- 自动过滤重复文件

### 3. 图片压缩

智能压缩算法，在保持质量的同时减小文件体积。

- **压缩预设**：
  - 邮件：适合邮件附件
  - 文档：适合文档中的图片
  - 网页：适合网页使用
  - 高质量：保持较高画质
  - 超轻量：最大程度压缩

### 4. 尺寸调整

批量调整图片尺寸，支持多种调整模式。

- **调整模式**：
  - 宽度：按宽度调整，自动计算高度
  - 高度：按高度调整，自动计算宽度
  - 百分比：按百分比缩放
  - 预设：常用尺寸预设（4K、2K、FHD、HD、证件照、微信头像等）
- **保持宽高比**：可选是否保持原始宽高比

### 5. 元数据清理

一键清除图片元数据，保护隐私。

- **清理选项**：
  - 清除所有 EXIF 信息
  - 保留拍摄日期（可选）

### 6. 批量重命名

使用自定义前缀和序号快速重命名文件。

- **命名模式**：前缀 + 序号（如：Photo_001.jpg）
- **序号位数**：可自定义（默认3位）
- **起始序号**：可自定义（默认1）

### 7. 水印添加

支持文字和图片水印，独立的位置和透明度控制。

- **文字水印**：
  
  - 自定义文字内容
  - 字体大小（12-72px）
  - 字体颜色（白、黑、红、绿、蓝、黄）
  - 9个位置选项
  - 透明度（0-100%）

- **图片水印**：
  
  - 支持 JPG/PNG 格式
  - 图片大小（5-50%）
  - 9个位置选项
  - 透明度（0-100%）

### 8. 多功能组合

可同时启用多个功能，按顺序自动处理。

**处理顺序**：压缩 → 尺寸调整 → 元数据清理 → 水印添加 → 重命名

### 9. 智能容错

- 自动剥离损坏或过长的 EXIF 元数据
- 内置错误重试机制（默认重试 2 次）
- 详细的错误日志记录

### 10. 配置管理

- 自动保存用户偏好设置
- 支持所有功能的配置项
- 配置文件位置：`~/.config/from-scratch-img/config.json`

### 11. 历史记录

- 记录所有处理操作
- 支持统计查询（成功率、耗时等）
- 自动清理 30 天前的记录

## 📊 技术栈

- **GUI 框架**：CustomTkinter 5.2.0+
- **拖拽支持**：tkinterdnd2 0.4.0+
- **图像处理**：Pillow 10.0.0+ + Pillow-HEIF 0.13.0+
- **并发处理**：ThreadPoolExecutor
- **测试框架**：pytest 7.4.0+
- **打包工具**：PyInstaller 6.0.0+

## 🔧 配置说明

应用会自动保存配置到 `~/.config/from-scratch-img/config.json`：

```json
{
    "output_format": "jpg",
    "jpg_quality": 90,
    "preserve_exif": false,
    "output_directory": "",
    "concurrent_threads": 4,
    "window_width": 700,
    "window_height": 500
}
```

## 📝 日志和历史

- **日志文件**：`~/.local/share/from-scratch-img/logs/from-scratch-img_YYYYMMDD.log`
- **历史记录**：`~/.local/share/from-scratch-img/history/conversion_history.json`

日志和历史记录会自动清理 30 天前的数据。

## ❓ 常见问题

### Q: 为什么转换失败？

A: 最常见的原因是 EXIF 元数据问题。建议取消勾选"保留 EXIF"选项。

### Q: 拖拽功能不工作怎么办？

A: 确保使用的是最新版本（v3.0），拖拽功能需要 tkinterdnd2 支持。如果使用源码运行，请确保已安装所有依赖。

### Q: 如何提高处理速度？

A: 可以增加并发线程数（建议设置为 CPU 核心数的 2 倍），或使用 SSD 作为输出目录。

### Q: 支持哪些输入格式？

A: 支持多种格式：HEIC、HEIF、JPG、PNG、WebP（根据当前选项卡自动过滤）。

### Q: 最多可以处理多少个文件？

A: 单次最多支持 50 个文件。

### Q: 如何同时使用多个功能？

A: 在各个选项卡中启用需要的功能（勾选"启用"复选框），然后点击"开始处理"按钮。系统会按顺序执行所有启用的功能。

### Q: 处理顺序是什么？

A: 处理顺序为：压缩 → 尺寸调整 → 元数据清理 → 水印添加 → 重命名。

### Q: 为什么处理出来的文件数量不对？

A: 请确保只启用了重命名或水印中的一个，或者检查是否有处理失败的文件。查看日志文件了解详细信息。

### Q: 水印图片支持哪些格式？

A: 支持 JPG 和 PNG 格式的图片作为水印。

### Q: 如何使用拖拽功能？

A: 直接从文件管理器拖拽图片文件到右侧文件列表区域，松开鼠标即可添加。支持批量拖拽多个文件。

### Q: 如何使用文件选择功能？

A: 点击右上角的蓝色"+ 添加文件"按钮，在文件选择对话框中选择文件。对话框会自动定位到挂载点，方便访问外部存储设备。

更多问题请参考 [用户手册](用户手册.md)。

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

### 开源许可证（GPLv3）

本项目采用 GPLv3 许可证开源。

- ✅ 个人和学习使用：完全免费
- ✅ 可以自由使用、修改、分发
- ⚠️ 修改后的代码必须开源
- ⚠️ 分发时必须提供源代码

详见 [LICENSE](LICENSE) 文件。

### 商业许可证

如果您需要闭源使用或商业集成，可以购买商业许可证。

- ✅ 闭源使用和修改
- ✅ 集成到商业产品中
- ✅ 优先技术支持
- ✅ 定制化开发服务

详见 [商业许可证说明](COMMERCIAL_LICENSE.md)。

### 许可证对比

| 功能    | GPLv3（开源） | 商业许可证 |
| ----- | --------- | ----- |
| 个人使用  | ✅ 免费      | ✅ 免费  |
| 商业使用  | ⚠️ 需开源    | ✅ 可闭源 |
| 技术支持  | 社区支持      | 优先支持  |
| 定制开发  | ❌         | ✅     |
| 源代码访问 | ✅         | ✅（可选） |

## 🙏 致谢

感谢以下开源项目：

- [CustomTkinter](https://github.com/TomSchimansky/CustomTkinter)
- [tkinterdnd2](https://github.com/pmgagne/tkinterdnd2)
- [Pillow](https://github.com/python-pillow/Pillow)
- [Pillow-HEIF](https://github.com/bigcat88/pillow_heif)
- [PyInstaller](https://github.com/pyinstaller/pyinstaller)

## 📞 支持

### 开源社区支持

如有问题或建议，请：

1. 查看 [用户手册](用户手册.md)
2. 检查 [日志文件](~/.local/share/from-scratch-img/logs/)
3. 提交 Issue 到 [Gitee](https://gitee.com/yngeek/heic)

### 商业支持

如需商业许可证或技术支持：

- 📧 Email: gfbbs@126.com
- 🌐 Website: https://gitee.com/yngeek/heic
- 📄 查看 [商业许可证说明](COMMERCIAL_LICENSE.md)

## 📅 版本历史

### v3.1 (2026-01-21)

**新增功能：**

- ✅ **顶部菜单栏**：
  
  - 文件菜单：添加文件 (Ctrl+O)、退出应用 (Ctrl+Q)
  - 编辑菜单：全选文件 (Ctrl+A)、删除选中文件 (Delete)、清空列表
  - 帮助菜单：使用教程、关于信息

- ✅ **快捷键支持**：
  
  - Ctrl+O：添加文件
  - Ctrl+S：开始处理
  - Ctrl+Q：退出应用
  - Delete：删除选中文件
  - Ctrl+A：全选文件

- ✅ **使用教程系统**：
  
  - 使用浏览器方式打开帮助文档
  - 支持完整的 Markdown 渲染
  - 美观的 HTML 样式设计
  - 支持搜索、打印、书签等浏览器功能

**优化改进：**

- ✅ **退出确认提示**：按 Ctrl+Q 或点击菜单"退出"时，会弹出确认对话框，防止意外退出
- ✅ **默认文件目录优化**：文件选择对话框默认打开用户主目录，简化选择流程
- ✅ **菜单交互优化**：点击菜单按钮显示下拉菜单，点击外部区域自动关闭菜单

**技术细节：**

- ✅ 使用 CustomTkinter 实现现代化菜单界面
- ✅ 支持深色/浅色主题自动切换
- ✅ Markdown 到 HTML 自动转换
- ✅ 快捷键绑定到主窗口，支持大小写不敏感

### v3.0.1 (2026-01-13 晚上)

**新增功能：**

- ✅ **图片自动修复功能**：
  - 转换功能自动检测并修复损坏的 PNG 文件
  - 水印功能自动修复损坏的图片文件（PNG/JPG）
  - 尺寸调整功能自动修复损坏的 PNG 文件
  - 修复后的文件自动保存到桌面（文件名格式：`xxx_fixed.png`）
  - 支持 9 种有问题 chunk 的自动移除（zTXt、iTXt、tEXt、eXIf、iCCP、sRGB、gAMA、cHRM）

**修复问题：**

- ✅ 修复水印图片验证失败后无法正确设置水印路径的问题
- ✅ 改进修复逻辑，使用更完善的修复函数
- ✅ 修复后的文件正确保存到桌面，方便用户使用

**技术细节：**

- ✅ 使用 `safe_open_image` 函数替代直接 `Image.open`
- ✅ 自动清理临时修复文件，避免磁盘空间浪费
- ✅ 完整的错误处理和日志记录

### v3.0.1 (2026-01-13 中午)

**新增功能：**

- ✅ **图片水印文件检测和修复**：自动检测图片文件是否可以正常打开，支持 PNG 和 JPG 格式
- ✅ **自动修复机制**：当所有打开方法都失败时，自动尝试修复图片文件，修复后的文件保存到桌面
- ✅ **UI 层面验证**：选择图片时立即验证，检查图片尺寸、格式和可打开性
- ✅ **用户友好提示**：提供详细的错误提示和修复建议
  - JPG 格式提示不支持透明背景，建议使用 PNG 格式
  - 损坏的 PNG 文件提示 ICC 配置文件损坏，系统会尝试自动修复

**改进：**

- ✅ 增强水印图片的兼容性和稳定性
- ✅ 提供更友好的错误信息和修复建议

### v3.0.0 (2026-01-08)

**新增功能：**

- ✅ **图片压缩**：智能压缩算法，5种预设等级
- ✅ **尺寸调整**：支持宽度、高度、百分比和预设尺寸
- ✅ **元数据清理**：一键清除 EXIF 信息，保护隐私
- ✅ **批量重命名**：自定义前缀+序号模式
- ✅ **水印添加**：支持文字和图片水印，独立的位置和透明度控制
- ✅ **多功能组合**：可同时启用多个功能，按顺序自动处理
- ✅ **格式扩展**：支持 JPG、PNG、WebP 作为输入格式

**核心功能：**

- ✅ 批量处理图片（最多 50 个）
- ✅ 多格式支持（HEIC、HEIF、JPG、PNG、WebP）
- ✅ 选项卡式界面，功能分类清晰
- ✅ 智能处理顺序，避免重复文件
- ✅ 现代化深色主题界面
- ✅ 详细的日志记录和历史

**技术特性：**

- ✅ 模块化架构，易于扩展
- ✅ 智能容错机制
- ✅ 配置持久化
- ✅ 多线程并发处理

### v2.0.0 (2026-01-06)

**新增功能：**

- ✅ 拖拽文件支持（直接拖拽到界面）
- ✅ 双重绑定确保拖拽稳定性
- ✅ 拖拽视觉反馈（背景色变化）
- ✅ 自动过滤重复文件
- ✅ Deb 安装包（包含所有依赖）
- ✅ 完整的桌面集成（图标、快捷方式）

**核心功能：**

- ✅ 批量转换 HEIC/HEIF 图片（最多 50 个）
- ✅ 多格式支持（JPG/PNG/WebP）
- ✅ 自定义输出质量和格式
- ✅ 保留或移除 EXIF 信息
- ✅ 自定义输出目录
- ✅ 多线程并发转换（1-8 线程）
- ✅ 转换历史记录
- ✅ 现代化深色主题界面
- ✅ 详细的日志记录
- ✅ 配置持久化

**技术特性：**

- ✅ 所有依赖已打包，无需额外安装
- ✅ 智能容错机制（自动重试）
- ✅ 完整的单元测试覆盖
- ✅ 模块化代码架构

---

**最后更新**：2026年1月21日
**版本**：v3.1
**作者**：kookboy