图片处理工具箱
铁律
- 绝不覆盖原图。 结果一律另存为新文件，默认放在原图旁边新建的「处理后」文件夹，重名自动加 (2)、(3)。
- 不联网、不上传。 全部在本机处理。
- 不偷偷装软件。 缺组件时脚本会给出安装说法，你把它转告用户；用户说「帮我装」后，你才运行安装命令。
- 数字（大小、像素、画质）一律用脚本输出的，不要估算。
需要的组件
- Python 3（必需）。
- Pillow（必需）：没装时脚本提示「在命令行输入 pip install pillow」。
- pillow-heif（只有处理苹果 HEIC 照片才需要）：没装时提示「pip install pillow-heif」。
怎么调用
python {baseDir}/scripts/image_tools.py <功能> <图片或文件夹…> [选项]
图片和文件夹都能给，可以给多个；给文件夹就处理里面最外层的所有图片（批量）。
| 功能 | 写法 | 说明 |
|---|---|---|
| 压缩到指定大小 | compress 图 --max-kb 200 |
二分调画质，实在压不下来再缩尺寸；--min-kb 20 设下限；--preset 一寸 顺便做成证件照规格 |
| 改尺寸 | resize 图 --preset 一寸 / --size 800x600 / --percent 50 / --width 1080 / --height 1080 |
给定宽高时默认等比放大后居中裁掉多余部分（不变形）；加 --pad 改为补白边不裁；--to jpg 顺便转格式 |
| 裁剪 | crop 图 --ratio 3:4 / --preset 一寸 / --size 600x800 / --box 左,上,宽,高 |
比例和规格为居中裁剪（证件照稍偏上保住头部）；--size 是从正中间切出这么大一块 |
| 格式转换 | convert 图 --to jpg |
支持 jpg、png、webp、bmp；能读 HEIC、GIF（取第一帧）、TIF |
| 文字水印 | watermark 图 --text "仅供办理社保使用" --position 右下 --opacity 40 |
位置：右下、左下、右上、左上、中间、平铺；--color 灰/白/黑/红；--font-scale 5 字高占短边百分比 |
| 清除隐私信息 | strip 图 |
去掉拍摄位置、手机型号、拍摄时间等，并按原方向摆正；会说清原图带了哪几类信息 |
| 拼图 | join 图1 图2 --direction 竖 |
横 / 竖；--gap 20 间距；--max-kb 500 额外出一份压缩版 |
| 旋转 | rotate 图 --angle 90 / rotate 图 --auto |
角度按顺时针：90、180、270（逆时针 90 = 270）；--auto 按手机记录自动摆正 |
| 看信息 | info 图 |
尺寸、大小、格式、是否带位置等隐私信息 |
| 规格表 | presets |
列出内置证件照规格 |
通用选项：--out 文件夹 指定另存到哪（仍然不覆盖）；--quality 92 JPG/WEBP 画质。
注意：除了 PNG/WEBP 保留透明，转成 JPG 时透明部分铺白底。所有输出都不带原图的拍摄信息（顺带保护隐私）。
内置证件照规格（宽×高像素）：一寸 295×413、小一寸 260×378、大一寸 390×567、二寸 413×579、小二寸 413×531、身份证 358×441、护照 390×567、驾驶证 260×378、教师资格证 295×413、计算机等级考试 144×192、初级会计 114×156、人事考试网 295×413。详见 references/photo-sizes.md，以报名网站要求为准——用户给了具体像素就用 --size。
退出码：0 正常；2 输入有误或缺组件；3 意外错误。出错时固定两行「出错了：…」「下一步：…」，原样转告用户。
用户说大白话 → 你怎么做
| 用户这样说 | 你跑 | 然后 |
|---|---|---|
| 「报名照片要小于 200KB，传不上去」 | compress 照片 --max-kb 200 |
告诉他新文件多大、在「处理后」文件夹；尺寸被缩了要说一声 |
| 「教资报名照，295×413，200K 以内」 | compress 照片 --max-kb 200 --preset 教师资格证（或 --size 295x413 先 resize 再 compress） |
提醒背景色、着装这些工具管不了，以报名页为准 |
| 「帮我弄成一寸照」「要二寸的电子版」 | resize 照片 --preset 一寸 |
说出像素；提醒照片要是正面免冠，人像不在正中的话再说「往上/下一点」改用 crop --box |
| 「苹果手机传到电脑上是 HEIC，打不开」 | convert 照片或文件夹 --to jpg |
缺 pillow-heif 就把安装说法转告；可顺带教他手机「设置→相机→格式→兼容性最佳」 |
| 「这一文件夹照片都缩小一半」「全部转成 JPG」 | resize 文件夹 --percent 50 / convert 文件夹 --to jpg |
报成功几张、失败几张和原因 |
| 「身份证复印件加个水印，仅供办理 XX 使用」 | watermark 图 --text "仅供办理XX使用，他用无效" --position 平铺 --opacity 35 |
平铺最防挪用；问他要不要更淡/更深 |
| 「发照片前把位置信息去掉」「怕照片暴露住址」 | strip 照片或文件夹 |
念出原图带了哪几类信息、已清掉；提醒发新文件，别发原图 |
| 「把身份证正反面拼成一张」 | join 正面 反面 --direction 竖 |
网站有大小限制就加 --max-kb |
| 「照片是歪的/倒的」「手机拍的传上去躺着」 | rotate 照片 --auto；不对再 --angle 90/180/270 |
说清是顺时针转了多少度 |
| 「裁成正方形」「裁成 3:4」 | crop 照片 --ratio 1:1 |
居中裁；要保留某块就问位置后用 --box |
| 「这张照片多大、多少像素」 | info 照片 |
直接报数 |
这个技能不做什么
- 不做 AI 抠图、不换底色（白底/蓝底/红底）、不美颜、不去除画面里的东西、不修复老照片。换底色请去照相馆或用报名网站推荐的工具。
- 不改原图、不删任何文件；处理结果都在「处理后」文件夹，不想要用户自己删。
- 不判断照片是否符合报名审核（表情、着装、露耳等），只管尺寸、大小、格式。
- 不识别图片里的文字（OCR），不处理视频和动图（GIF 只取第一帧）。
- 不联网、不上传、不自动安装任何组件。
说话方式
- 面向电脑小白：说「照片」「文件夹」「处理后文件夹」「画质」，不念命令、选项名、变量名。
- 结论先说：「压好了，183 KB，在原照片旁边的『处理后』文件夹里，原图没动。」
- 画质被压得很低或尺寸被缩小时，要提醒「放大看会有点糊」，并建议换一张更清楚的原图。
