Metadata-Version: 2.4
Name: pixcraft
Version: 0.1.0
Summary: 本地批量图片处理 CLI 工具——压缩、转格式、改尺寸、去信息，一行命令搞定
Home-page: https://github.com/your-org/pixcraft
Author: PixCraft
Project-URL: Bug Tracker, https://github.com/your-org/pixcraft/issues
Project-URL: Source Code, https://github.com/your-org/pixcraft
Keywords: image,compress,convert,resize,cli,batch,webp,avif,exif
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click>=8.0.0
Requires-Dist: Pillow>=10.0.0
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# PixCraft

**批量处理图片的命令行工具。压缩、转格式、改尺寸、清除元数据，一条命令的事。**

写这个工具的原因很简单——每次要批量压缩图片就得打开 TinyPNG 网页，或者翻出 Photoshop 脚本，太烦了。PixCraft 把这些操作全部搬到了终端里。

---

## 安装

Python 3.10 以上，依赖 Click 和 Pillow，pip 会自动装好。

```bash
pip install pixcraft
```

也可以从源码装：

```bash
git clone https://github.com/your-org/pixcraft.git
cd pixcraft
pip install .
```

---

## 快速开始

五个命令，覆盖最常见的图片处理需求：

```bash
# 批量压缩到 500KB 以内
pixcraft compress ./images/ -s 500k

# 整个目录转 WebP
pixcraft convert ./images/ -t webp

# 等比缩放到 1200 宽
pixcraft resize hero.jpg -w 1200

# 清除 EXIF/GPS/相机信息
pixcraft strip ./photos/

# 查看图片详情
pixcraft info photo.jpg
```

---

## 命令详解

### pixcraft compress

压缩图片。可以指定质量，也可以指定目标文件大小让工具自己找最佳参数。

```bash
pixcraft compress <PATH> [OPTIONS]
```

| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `-q, --quality` | int | `85` | 压缩质量 1-100，越大质量越好，文件也越大 |
| `-s, --max-size` | str | — | 目标文件大小上限，比如 `500k`、`5mb`。指定后自动二分搜索找最佳质量值 |
| `-o, --output` | path | `./pixcraft-output` | 输出目录 |
| `-f, --format` | str | — | 输出格式（`jpg`/`png`/`webp`/`avif`），不指定就用原格式 |
| `--no-resize` | flag | `false` | 禁止自动缩小尺寸，只靠降低质量来压缩 |

几个默认行为值得注意：

- `PATH` 可以是单个文件或目录，目录会递归处理
- 默认把图片最长边缩到 2000px，防止超大尺寸撑爆文件体积
- 指定 `--max-size` 时用二分搜索找质量值，比你自己试快得多
- 质量降到最低还是超的话，会自动逐级缩小尺寸（2000px → 1000px → 500px）

### pixcraft convert

JPG、PNG、WebP、AVIF 四种格式互转。

```bash
pixcraft convert <PATH> -t <TARGET_FORMAT> [OPTIONS]
```

| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `-t, --to` | str | **必填** | 目标格式（`jpg`/`png`/`webp`/`avif`） |
| `-q, --quality` | int | `85` | 输出质量，只对 jpg/webp/avif 生效 |
| `-o, --output` | path | `./pixcraft-output` | 输出目录 |
| `--lossless` | flag | `false` | 无损模式，目前只支持 PNG → WebP |

转换时会做一些自动处理，防止出问题：

- PNG → JPG 会自动填白色背景（透明区域没法往 JPG 里塞）
- JPG → PNG 直接拒绝，JPG 已经有损了，转 PNG 只是浪费空间
- PNG → WebP 加 `--lossless` 能保留透明通道
- 其他方向正常转

### pixcraft resize

四种缩放模式，比 ImageMagick 的参数好记多了。

```bash
pixcraft resize <PATH> [OPTIONS]
```

| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `-w, --width` | int | — | 目标宽度，高度自动按比例算 |
| `-h, --height` | int | — | 目标高度，宽度自动按比例算 |
| `--fit` | str | — | 适配尺寸如 `1200x630`，图片完整显示，空白处填白 |
| `--fill` | str | — | 填充尺寸如 `1200x630`，铺满区域，超出居中裁剪 |
| `--scale` | float | — | 缩放倍数，`0.5` 就是缩小一半 |
| `-o, --output` | path | `./pixcraft-output` | 输出目录 |

四种模式：

- `-w` / `-h`：等比缩放。只给一个边就自动算另一边，两个都给就按固定尺寸来
- `--fit`：把图片塞进指定区域，保持比例，留白不裁剪
- `--fill`：填满指定区域，保持比例，多出来的裁掉
- `--scale`：直接按倍数缩放，最简单直接

### pixcraft strip

清除元数据，保护隐私。去掉 EXIF、GPS 坐标、相机型号、拍摄时间。

```bash
pixcraft strip <PATH> [OPTIONS]
```

| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `-o, --output` | path | — | 输出目录，不指定就覆盖原文件 |

在社交媒体发照片之前跑一下这个命令，就不用担心别人从 EXIF 里读到你家的 GPS 坐标了。

### pixcraft info

查看图片的详细信息。

```bash
pixcraft info <PATH>
```

> 只接受单个文件，不支持目录。

会输出这些内容：文件名、格式、尺寸、文件大小、颜色模式，还有 EXIF 里藏的各种信息（相机型号、拍摄时间、GPS 等）。

---

## 输出示例

批量处理时会逐文件显示状态和体积变化：

```text
  ✓ hero.jpg (4.2MB -> 0.3MB)
  ✓ photo.png (2.1MB -> 0.5MB)
  ✓ banner.webp (1.8MB -> 0.4MB)
  ✗ broken.jpg (无法读取，已跳过)

  处理完成：3/4 个文件，节省 6.9MB
```

成功打勾，失败打叉并附原因，最后汇总成功数和节省的总体积。

---

## 测试

```text
89 passed in 4.24s
```

---

## 开源协议

MIT License

---

PixCraft —— 给开发者用的命令行版 TinyPNG。
