Nymiro
61 lines
2.0 KiB
Markdown
61 lines
2.0 KiB
Markdown
# pyheic-struct
|
||
|
||
`pyheic-struct` 是一个用于解析、分析以及重建 HEIC/HEIF 文件的 Python 库，专注于不同厂商（如三星、苹果）在实现上的差异。项目同时提供命令行工具与可复用的 API，可嵌入其他项目，帮助你处理跨平台的动态照片与静态 HEIC 内容。
|
||
|
||
## 功能特点
|
||
|
||
- **HEIC 结构解析**：读取 `ftyp`、`meta`、`iloc`、`iinf`、`iprp` 等核心盒信息，便于调试与分析。
|
||
- **网格图像重建**：支持将三星网格化存储的主图像还原为标准平面图像。
|
||
- **元数据安全重建**：通过 `HEICBuilder` 自动处理偏移量与引用更新，生成结构正确的新 HEIC 文件。
|
||
- **跨厂商兼容转换**：提供 `convert_samsung_motion_photo` 高阶函数，将三星动态照片转换为苹果可识别的 HEIC + MOV 组合，并可选择性写入 `ContentIdentifier`。
|
||
- **命令行工具**：内置 CLI，可直接在终端运行转换任务。
|
||
|
||
## 使用方式
|
||
|
||
### 安装
|
||
|
||
```bash
|
||
pip install .
|
||
```
|
||
|
||
### 命令行
|
||
|
||
```bash
|
||
pyheic-struct samsung.heic \
|
||
--output-heic samsung_fixed.HEIC \
|
||
--output-mov samsung_fixed.MOV
|
||
```
|
||
|
||
常用参数：
|
||
- `--output-heic`：指定生成的 HEIC 文件路径
|
||
- `--output-mov`：指定生成的 MOV 文件路径
|
||
- `--skip-mov-tag`：跳过对 MOV 写入 `ContentIdentifier`（无需 exiftool）
|
||
|
||
### 作为库使用
|
||
|
||
```python
|
||
from pyheic_struct import (
|
||
HEICFile,
|
||
HEICBuilder,
|
||
convert_samsung_motion_photo,
|
||
)
|
||
|
||
# 解析 HEIC 结构
|
||
heic = HEICFile("samsung.heic")
|
||
print(heic.get_primary_item_id())
|
||
|
||
# 执行三星 -> 苹果动态照片转换
|
||
heic_path, mov_path = convert_samsung_motion_photo("samsung.heic")
|
||
print("新 HEIC：", heic_path)
|
||
print("新 MOV：", mov_path)
|
||
```
|
||
|
||
## 开发调试
|
||
|
||
```bash
|
||
python -m pyheic_struct path/to/samsung.heic
|
||
python inspect_heic.py samsung_apple_compatible.HEIC
|
||
```
|
||
|
||
项目要求 Python 3.10 及以上版本。欢迎根据实际需求扩展解析器或加入更多厂商的兼容逻辑。
|