diff --git a/README.md b/README.md index 79013ae..e320fe2 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,60 @@ # pyheic-struct -Utilities for inspecting, modifying, and rebuilding HEIC/HEIF files with a focus on -cross-vendor quirks between Samsung and Apple motion photos. +`pyheic-struct` 是一个用于解析、分析以及重建 HEIC/HEIF 文件的 Python 库,专注于不同厂商(如三星、苹果)在实现上的差异。项目同时提供命令行工具与可复用的 API,可嵌入其他项目,帮助你处理跨平台的动态照片与静态 HEIC 内容。 -## Features +## 功能特点 -- Lightweight parser that exposes core ISOBMFF boxes (`ftyp`, `meta`, `iloc`, `iinf`, etc.) -- Helpers for reconstructing Samsung grid images into flat HEIC pictures -- Rebuilder that writes updated metadata and payload offsets safely -- High-level `convert_samsung_motion_photo` function to create Apple-compatible - HEIC/MOV pairs (with optional MOV ContentIdentifier injection via `exiftool`) -- CLI tool: `pyheic-struct samsung.heic` +- **HEIC 结构解析**:读取 `ftyp`、`meta`、`iloc`、`iinf`、`iprp` 等核心盒信息,便于调试与分析。 +- **网格图像重建**:支持将三星网格化存储的主图像还原为标准平面图像。 +- **元数据安全重建**:通过 `HEICBuilder` 自动处理偏移量与引用更新,生成结构正确的新 HEIC 文件。 +- **跨厂商兼容转换**:提供 `convert_samsung_motion_photo` 高阶函数,将三星动态照片转换为苹果可识别的 HEIC + MOV 组合,并可选择性写入 `ContentIdentifier`。 +- **命令行工具**:内置 CLI,可直接在终端运行转换任务。 -## Installation +## 使用方式 + +### 安装 ```bash pip install . ``` -## Usage - -```python -from pyheic_struct import convert_samsung_motion_photo - -convert_samsung_motion_photo("samsung.heic") -``` - -Command line: +### 命令行 ```bash -pyheic-struct samsung.heic --output-heic samsung_fixed.HEIC +pyheic-struct samsung.heic \ + --output-heic samsung_fixed.HEIC \ + --output-mov samsung_fixed.MOV ``` -## Development +常用参数: +- `--output-heic`:指定生成的 HEIC 文件路径 +- `--output-mov`:指定生成的 MOV 文件路径 +- `--skip-mov-tag`:跳过对 MOV 写入 `ContentIdentifier`(无需 exiftool) -The package targets Python 3.10+. Run the CLI in editable mode: +### 作为库使用 + +```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 及以上版本。欢迎根据实际需求扩展解析器或加入更多厂商的兼容逻辑。 diff --git a/pyproject.toml b/pyproject.toml index 5f3c810..51a546d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -3,7 +3,7 @@ name = "pyheic-struct" version = "0.1.0" description = "Low-level utilities for parsing and rebuilding HEIC/HEIF files, with Samsung-to-Apple motion photo conversion helpers." authors = [ - { name = "Your Name", email = "you@example.com" } + { name = "Nymiro Yi", email = "dmwf994@dmwf994.com" } ] license = { text = "MIT" } readme = "README.md"