tools/cutPic/README.md

cutpic - 图片裁切工具 🖼️

一个简单易用的命令行图片裁切工具，可以将图片按指定的行列数均匀分割成多个小图片。

✨ 功能特性

• 📐 灵活分割: 支持自定义水平和垂直分割数
• 🎯 均匀裁切: 自动计算每块尺寸，均匀分割图片
• 📁 智能输出: 默认在输入文件同级目录创建 dist 文件夹
• 🖼️ 多格式支持: 支持 PNG, JPG, JPEG, BMP, GIF, WebP 等常见图片格式
• 🔢 智能命名: 自动生成带序号的文件名，方便识别和管理
• ⚡ 高性能: 基于 Rust 开发，处理速度快

📦 安装

从源码编译

cd cutPic
cargo build --release

编译后的可执行文件位于 target/release/cutpic.exe

添加到系统路径（可选）

将 target/release/cutpic.exe 复制到系统 PATH 目录，或将其所在目录添加到 PATH 环境变量中。

🚀 快速开始

基本用法

# 将图片分割成 3x2 的网格（共6块）
cutpic -i image.png -w 3 -h 2

# 将图片分割成 4x4 的网格（共16块）
cutpic -i photo.jpg -w 4 -h 4

指定输出目录

# 指定输出到 custom_output 目录
cutpic -i image.png -w 2 -h 2 --out ./custom_output

📖 命令参数

cutpic [OPTIONS] -i <INPUT>

参数:
  -i, --input <FILE>      📁 输入图片路径（必需）
  -w, --width <NUM>       📐 水平方向分割数（默认: 1）
  -h, --height <NUM>      📏 垂直方向分割数（默认: 1）
      --out <DIR>         📂 输出目录（默认: 输入文件同级的 dist 文件夹）
  -h, --help              显示帮助信息
  -V, --version           显示版本信息

💡 使用示例

示例 1: 制作拼图素材

将一张大图分割成 5x5 的拼图块：

cutpic -i puzzle.png -w 5 -h 5

输出:

• 生成 25 张图片
• 文件命名: puzzle_1_25.png, puzzle_2_25.png, ..., puzzle_25_25.png
• 输出位置: ./dist/ 目录

示例 2: 提取图标集中的单个图标

从 4x4 排列的图标集中提取每个图标：

cutpic -i icons.png -w 4 -h 4 --out ./individual_icons

输出:

• 生成 16 张单独的图标
• 输出到 ./individual_icons/ 目录

示例 3: 分割游戏精灵图（Sprite Sheet）

横向分割角色动画帧（8 帧动画）：

cutpic -i character.png -w 8 -h 1 --out ./animation_frames

输出:

• 生成 8 张动画帧图片
• 适合用于游戏开发中的帧动画

示例 4: 只进行水平分割

将横幅广告图分割成 4 部分：

cutpic -i banner.png -w 4 -h 1

示例 5: 只进行垂直分割

将长图分割成 3 段：

cutpic -i long-image.jpg -w 1 -h 3

📊 输出说明

文件命名规则

生成的文件遵循以下命名格式：

{原文件名}_{序号}_{总数}.{扩展名}

示例:

• 原文件: image.png
• 分割: 3x2 (共6块)
• 输出文件:
  • image_1_6.png - 第1块
  • image_2_6.png - 第2块
  • ...
  • image_6_6.png - 第6块

输出目录结构

项目目录/
├── image.png              # 原始图片
└── dist/                  # 默认输出目录
    ├── image_1_6.png
    ├── image_2_6.png
    ├── image_3_6.png
    ├── image_4_6.png
    ├── image_5_6.png
    └── image_6_6.png

如果指定了 --out 参数：

项目目录/
├── image.png              # 原始图片
└── my_output/             # 自定义输出目录
    ├── image_1_6.png
    ├── image_2_6.png
    └── ...

⚙️ 工作原理

1. 加载图片: 读取输入图片并获取尺寸信息
2. 计算尺寸:
   • 每块宽度 = 总宽度 ÷ 水平分割数
   • 每块高度 = 总高度 ÷ 垂直分割数
3. 逐块裁切: 按行列顺序遍历，裁切每一块
4. 处理边界: 最后一行/列可能包含剩余像素，自动调整尺寸
5. 保存文件: 按命名规则保存到输出目录

边界处理示例

假设图片尺寸为 100x100 像素，分割为 3x3：

• 理论每块: 33.33 x 33.33 像素
• 实际处理:
  • 第1、2块: 33 x 33 像素
  • 第3块: 34 x 34 像素（包含剩余像素）

这样确保所有像素都被保留，不会丢失任何内容。

🎯 应用场景

1. 游戏开发

• 分割 Sprite Sheet 为单独的动画帧
• 提取瓦片地图（Tilemap）的单个瓦片
• 处理角色、道具等资源图片

2. 网页设计

• 将大图分割成小块用于懒加载
• 制作图片拼图效果
• 优化大图的加载性能

3. 社交媒体

• 制作 Instagram 九宫格图片
• 分割长图为适合移动端查看的多张图片
• 创建有趣的图片分割效果

4. 数据处理

• 批量处理扫描文档
• 分割大幅面图纸
• 处理卫星图像或地图切片

5. 教育用途

• 制作教学用拼图
• 分解复杂图表
• 创建互动学习材料

⚠️ 注意事项

1. 图片格式: 输出格式与输入格式相同
2. 最小分割: 分割数为 1x1 时，会生成原图的副本
3. 内存使用: 处理超大图片时会占用较多内存
4. 文件数量: 分割数越多，生成的文件越多，注意磁盘空间
5. 索引顺序: 文件按先行后列的顺序编号（从左到右，从上到下）

🔧 技术细节

依赖库

• clap: 命令行参数解析
• image: 图片处理和裁切

性能特点

• 使用 Rust 编写，性能优异
• 支持多线程（取决于 image 库的实现）
• 内存效率高，逐块处理

平台支持

• ✅ Windows
• ✅ macOS
• ✅ Linux

📝 完整示例工作流

工作流 1: 制作 Instagram 九宫格

# 1. 准备一张正方形图片（建议 1080x1080 或更高）
# 2. 分割成 3x3 的九宫格
cutpic -i instagram-post.png -w 3 -h 3 --out ./instagram-grid

# 3. 上传生成的 9 张图片到 Instagram（按逆序上传以获得正确显示顺序）

工作流 2: 提取游戏资源

# 1. 从游戏中提取 sprite sheet
# 2. 分析 sprite sheet 的布局（例如 8x4 排列）
cutpic -i spritesheet.png -w 8 -h 4 --out ./game-assets

# 3. 重命名生成的文件为有意义的名称
# 4. 在游戏引擎中使用这些单独的资源

工作流 3: 创建拼图游戏

# 1. 选择一张有趣的图片
# 2. 根据难度选择分割数（简单: 3x3, 中等: 5x5, 困难: 8x8）
cutpic -i puzzle-image.jpg -w 5 -h 5 --out ./puzzle-pieces

# 3. 打乱文件顺序
# 4. 开发拼图游戏逻辑

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

本项目采用 MIT 许可证。

🙏 致谢

感谢以下开源项目：

• clap - 优秀的命令行参数解析库
• image - 强大的图片处理库

---

Made with ❤️ using Rust