图片拼接工具箱
成品文件公式:用户给多张图片 → 直接拿到拼接好的成品图片文件(不是教程、不是参数建议)。核心刚需:电商卖家把多张商品图拼成九宫格/主图详情;把一长串聊天截图拼成一张长图分享;把分屏网页截图拼成完整长图归档。全程本地处理(Pillow),无需网络与 API Key。
功能
| 子命令 | 作用 | 典型场景 |
|---|---|---|
hstack |
横向拼接(左右并排) | 前后对比图、多图并排展示 |
vstack |
纵向拼接(上下堆叠) | 商品多角度堆叠、方案上下对比 |
grid |
网格拼图(--cols/--rows) |
九宫格拼图、拼图墙、3×3 商品图 |
auto |
智能拼接(按尺寸自动判方向) | 一叠同尺寸截图一键拼好 |
long |
长图模式(统一宽度后纵向拼接) | 聊天记录拼接、网页截图拼长图 |
拼接哲学(agent 无需操心,脚本已内建):
hstack/vstack/auto不做任何缩放 —— 直接按原始像素贴图,无二次压缩、清晰度零损失。高度/宽度不一致时,按--align对齐、空档用--bg背景色补(所以不会变形,只会留底色)。grid会把每张图等比适配到统一单元格(默认单元格=最大图的宽高,contain居中留白),让拼图整齐;可用--cell指定正方形/固定单元格,--fit cover改为等比裁剪填满。long会把所有图等比缩放到统一宽度(默认取最宽图宽度,可--width指定)再无缝纵向堆叠,专治宽度不一的聊天/网页截图。- 网格自动排版:未给行列时按图片数取近似正方形;给了
--rows但用不满时自动去掉多余的整行空位;不在末行末尾的空位用背景色补齐。 - 背景/透明:
--bg支持#RRGGBB、#RRGGBBAA、white、transparent等;背景半透明或任一输入带 alpha 时自动使用 RGBA 画布,保留透明通道(PNG/WebP)。 - 输出保真:默认输出 PNG(无损);指定
-o out.jpg时用 JPEGquality=95 + subsampling=0(最高质量);.webp用无损编码。
工作流程
- 拿三要素:①图片来源(文件列表 or 目录)②拼接方式(横排 / 竖排 / 九宫格 / 长图;不说就按下面默认判断)③是否要间距/背景色/输出名。
- 按意图选子命令(用户描述 → 子命令映射):
- "并排 / 左右 / 横着拼" →hstack
- "上下 / 竖着拼 / 叠起来" →vstack
- "九宫格 / 宫格 / 拼图 / 网格 / 拼成 3×3" →grid
- "聊天记录 / 聊天截图 / 网页截图 / 拼长图 / 一整条" →long
- 一叠同尺寸截图、用户懒得说方向 →auto(自动判横竖) - 执行命令(一律用绝对路径):
bash
SKILL_DIR="$HOME/.workbuddy/skills/img-stitch-toolbox"
[ -f "$SKILL_DIR/scripts/img_stitch.py" ] || SKILL_DIR="$PWD/.workbuddy/skills/img-stitch-toolbox"
[ -f "$SKILL_DIR/scripts/img_stitch.py" ] || SKILL_DIR="/sandbox/workspace/skills/img-stitch-toolbox"
S="$SKILL_DIR/scripts/img_stitch.py"
python3 $S grid /path/商品图 --cols 3 --rows 3 --gap 8 --bg '#FFFFFF' -o /path/九宫格.png
- 交付:命令会打印
✅ 完成 [子命令]:N 张 → 宽×高 px及输出文件路径与大小;把输出文件的绝对路径 + 尺寸报给用户即可,无需解释技术细节。 - 目录 → 直接传目录:脚本按文件名顺序读取目录内所有图片(
.jpg/.jpeg/.png/.webp/.bmp/.tif/.tiff/.gif,不递归子目录);顺序不对时让用户先重命名,或显式逐个按期望顺序列文件。 auto报错时(尺寸既不同宽也不同高):这不是 bug,按提示改用grid或long,并告诉用户原因。
命令参考
S="$SKILL_DIR/scripts/img_stitch.py"
# 1) 横向拼接(等高对齐,不缩放)
python3 $S hstack a.png b.png c.png --align center --gap 10 --bg '#FFFFFF' -o out.png
# --align top|center|bottom 上下对齐(默认 center)
# 2) 纵向拼接(等宽对齐,不缩放)
python3 $S vstack a.png b.png c.png --align center --gap 10 -o out.png
# --align left|center|right 左右对齐(默认 center)
# 3) 网格拼图 / 九宫格
python3 $S grid ./photos --cols 3 --rows 3 --gap 8 --bg '#FFFFFF' -o 九宫格.png
# --cols 列数(默认按图片数取近似正方形)
# --rows 行数(默认由列数推导;给多了会自动去掉多余空行)
# --cell 单元格尺寸,如 500(正方形)或 500x800(默认取最大图的宽高)
# --fit contain 等比留白(默认)/ cover 等比裁剪填满
# 4) 智能拼接(全同宽→纵向;全同高→横向;否则报错)
python3 $S auto ./screenshots -o merged.png
# 5) 长图模式(统一宽度后纵向拼接,适合聊天记录/网页截图)
python3 $S long ./chat --width 1080 --gap 0 -o 长图.png
# --width 统一宽度像素(默认取最宽图宽度)
# 通用参数(所有子命令可用)
# inputs 位置参数:一个或多个图片文件/目录(可混合)
# -o 输出路径(默认:<首图名>_<子命令>.png;按扩展名决定格式 png/jpg/webp/bmp/tiff)
# --gap 图片间距像素(默认 0)
# --bg 背景/空档色(默认 #FFFFFF;支持 #RRGGBB、#RRGGBBAA、white、transparent)
示例对话
例 1:九宫格拼图
> 用户:我这 9 张商品图,帮我拼成九宫格
> Agent:(执行 grid ./商品图 --cols 3 --rows 3 --gap 8 -o ./九宫格.png)
> "拼好了:9 张 → 3×3 九宫格,尺寸 XXXX×XXXX,文件在 ./九宫格.png。需要无白边的话我可以用 --fit cover 改成裁满。"
例 2:聊天记录拼长图
> 用户:这几张聊天截图帮我拼成一张长图,方便发朋友圈
> Agent:(执行 long ./聊天截图 -o ./聊天长图.png)
> "已拼成长图:5 张截图统一宽度 XXXpx 纵向无缝拼接,总尺寸 XXX×XXXX,文件在 ./聊天长图.png。"
例 3:并排对比
> 用户:把这两张前后对比图左右拼一起
> Agent:(执行 hstack 前.jpg 后.jpg --gap 12 -o 对比图.png)
> "已左右拼接:尺寸 XXX×XXX,文件在 ./对比图.png。"
例 4:一叠同尺寸截图自动拼
> 用户:目录里同尺寸的手机截图,自动拼一下
> Agent:(执行 auto ./截图 -o 汇总.png)
> "智能判断:全部同宽(1080px)→ 纵向拼接,N 张 → 1080×XXXX,输出 ./汇总.png。"
例 5:尺寸太乱
> 用户:把这堆尺寸乱七八糟的图拼一起
> Agent:(先试 auto 报错 → 改用)long ./图 --width 1080 -o 长图.png
> "这些图宽高都不一致,无法自动判方向,我改用长图模式:统一缩放到宽 1080px 后纵向拼接,输出 ./长图.png。"
运行环境
- 脚本：
scripts/img_stitch.py（相对技能根目录） - Python：3.9+
- 第三方库：
Pillow（pip install Pillow）
开工前先跑一次自检，缺什么当场补，别等跑到一半报错：
python3 -c "import PIL" 2>/dev/null || echo "缺 Pillow，请执行 pip install Pillow"
> 缺依赖时用中文告诉用户缺什么、装完就能用，不要把 Python 的英文 traceback 原样贴给用户。
注意事项
- 清晰度:
hstack/vstack/auto全程不缩放,原像素贴图,零画质损失;grid会把图等比适配到单元格、long会统一缩放宽度——这是"整齐"与"保真"的天然取舍。追求零损失就选前三种。 - 对齐留白:横拼/竖拼时高(宽)不一致的图按
--align对齐,空白处填--bg颜色;想要彻底无白边,横排前把图裁成等高、或用long。 - 网格单元格:
grid默认单元格=最大图的宽高。想要统一正方形瓷砖(典型九宫格)请传--cell 500(或--cell 500x500);contain不裁内容、cover裁满格子(照片裁边)。 - 目录顺序:传目录时按文件名排序读取(不递归);拼接顺序重要时,建议让用户重命名或按期望顺序逐个列文件。
- 格式:输入支持 jpg/jpeg/png/webp/bmp/tiff/gif(动图取首帧);输出支持 png/jpg/webp/bmp/tiff;默认 PNG 无损,
-o x.jpg为最高质量 JPEG,-o x.webp为无损 WebP。 - 透明:
--bg transparent或输入含 alpha 时输出带透明通道(存 PNG/WebP);输出 JPG 时透明处自动铺白底(JPEG 不支持透明)。 - 错误处理:文件不存在、无法识别的图片、不支持的输出格式、
auto无法判方向,都会打印明确中文错误并返回非零退出码,不会产出半成品。 - 依赖:仅 Pillow(Pillow 11.3.0,当前运行环境自带)与标准库,无需联网、无需 API Key。
- 不支持:图片压缩(img-compress-toolbox)、加水印(img-watermark-toolbox)、证件照排版(id-photo-toolbox)、视频拼接(video-toolbox)、抠图/美颜。
