imgcli

imgcli — 用 C 实现的命令行图像转换与处理工具

兼具 ImageMagick 的强大功能与 ffmpeg 的语法，且零依赖。 一个小巧的 C 二进制程序，可转换、调整大小、裁剪、滤镜处理和合成图像——支持 PNG、JPEG、BMP、TGA、GIF、PPM、QOI——由 ffmpeg 风格的滤镜图驱动。不依赖系统库；只要有 C11 编译器，就能编译。

⚡ 在常见的缩放和滤镜操作中，速度比 ImageMagick 快约 8 倍，且只有一个 232 KB 的二进制文件（体积约小 470 倍）——查看基准测试。适用于静态图像的轻量级 ImageMagick convert 或 ffmpeg 替代方案。

# Convert + resize + filter in one pass:
imgcli -i photo.jpg -vf "scale=1024:-1,grayscale,contrast=1.2,gblur=1.5" out.png

功能： 格式转换 · 调整大小／缩放 · 裁剪 · 填充 · 旋转 · 翻转 · 亮度／对比度／饱和度／伽马／色相 · 灰度 · 棕褐色 · 反色 · 阈值 · 方框与高斯模糊 · 锐化 · Sobel 边缘检测 · 浮雕 · 自定义卷积核 · Alpha 叠加合成 · 绘制方框 · 纯色填充。

设计： 与 ffmpeg 采用相同范式——解码 → 规范化为统一帧格式（RGBA）→ 运行以逗号分隔的滤镜图 → 根据输出扩展名编码。

基准测试

在 Apple Silicon Mac 上对比 imgcli 与 ImageMagick（单线程、热缓存）。 运行 make && bench/bench.sh 可复现结果——完整方法和注意事项请见 bench/RESULTS.md。

操作	imgcli	ImageMagick	加速比
PNG→JPEG + 调整大小（单次操作）	1.6 ms	4.7 ms	2.9×
调整大小：1200×1200 → 300w	6.0 ms	51.6 ms	8.6×
1200×1200 图像转灰度	48.4 ms	389 ms	8.0×

占用空间	imgcli	ImageMagick
安装大小	232 KB	~109 MB（大约大 470 倍）
依赖项	0（仅 libc）	17 个软件包

ImageMagick 是功能广泛的 16 位／HDRI 工具包，支持 200 多种格式；imgcli 则是精简的 8 位处理流程，在速度、体积和启动速度方面更胜一筹——这正是 Agent 或脚本为每项任务启动一个进程时所看重的特性。

依赖项与格式

默认构建不依赖任何外部库——生成的单个二进制文件仅链接系统 C 库（libc）。解码和编码由内置的、属于公有领域的 stb 和 qoi 单头文件库处理，并直接编译到程序中。无需运行 apt install，无需共享库，也没有版本兼容问题。

• 内置格式——无依赖： PNG、JPEG、BMP、TGA、GIF、PPM、QOI。其他可用纯 C 实现的格式（例如 TIFF）也会内置，且不会增加二进制文件的依赖项。
• 需要外部库的格式——仅可选启用：WebP、AVIF、HEIC 和 JPEG XL 无法在不使用大型外部库（libwebp、libavif、libheif、libjxl）的情况下解码；这些格式没有公有领域的单头文件解码器，也不适合手动实现。如果 imgcli 添加这些格式支持，也只会通过可选的构建标志启用（例如 make WEBP=1），并链接相应的库。

“零依赖”这一说法适用于默认构建，而且始终如此——可选启用的格式库绝不会编译到默认构建中。 启用了此类标志的构建，按定义就不再是无依赖构建；启用时会明确说明这一取舍。

采用这种结构的原因

ffmpeg 概念	imgcli 对应项
AVFrame / pixfmt	每张图像都会规范化为打包的 8 位 RGBA（Image）
demuxer/decoder	通过 vendored stb_image 加载图像（PNG/JPEG/BMP/TGA/GIF/…）
-vf filtergraph	filters.c 中解析的 name=a:b:c, name, … 链
AVFilter	每个滤镜都会修改或替换当前帧
muxer（按扩展名）	img_save（png/jpg/bmp/tga，以及手写的 PPM 写入器）
lavfi 测试源	testsrc=、color=、gradient=、checker= 生成器

编解码器来自公共领域的 stb 单头文件库（third_party/）。这些库会随项目打包，而非链接，因此该工具保持可移植且自包含，同时仍可读写人们实际使用的格式——这与 ffmpeg 依赖编解码器库而非从头实现它们的权衡相同。

安装

# Homebrew (macOS / Linux)
brew install swperb/tap/imgcli

# Nix (no install — run straight from GitHub)
nix run github:swperb/imgcli -- -y -i in.png out.jpg
nix profile install github:swperb/imgcli

# Debian / Ubuntu / WSL (.deb from the latest release)
curl -fsSLO https://github.com/swperb/imgcli/releases/latest/download/imgcli_0.5.0_amd64.deb
sudo apt install ./imgcli_0.5.0_amd64.deb

# Arch (AUR)
yay -S imgcli            # or: paru -S imgcli

# Docker
docker run --rm -v "$PWD:/work" -w /work ghcr.io/swperb/imgcli -y -i in.png out.jpg

# Windows — winget
winget install swperb.imgcli
# Windows — Scoop (installs straight from the manifest)
scoop install https://raw.githubusercontent.com/swperb/imgcli/main/packaging/scoop/imgcli.json

# Prebuilt binaries: https://github.com/swperb/imgcli/releases

# From source (only a C compiler and -lm required)
make            # produces ./imgcli
make demo       # generates a few sample images
sudo make install   # installs the binary + man page to /usr/local

将其用作原生 Agent 工具（MCP）

MCP 服务封装了 imgcli，因此 AI Agent 可以直接调用 convert_image、probe_image 和 list_filters——参见 mcp/。

用法

imgcli [-i INPUT]... [-vf GRAPH] [-q N] [-f FMT] [-y|-n] [--json] OUTPUT

  -i INPUT     a file, '-' for stdin, or a generator (testsrc=WxH,
               color=NAME:WxH, gradient=WxH, checker=WxH). Repeat -i for
               compositing inputs; the first is the primary frame, the rest
               feed `overlay`.
  -vf GRAPH    filtergraph, e.g. "scale=800:-1,grayscale,gblur=2"
  -q N         JPEG quality 1..100 (default 90)
  -f FMT       output format (png/jpg/bmp/tga/ppm/qoi); required when OUTPUT
               is '-' (stdout), an optional override for files
  -y / -n      overwrite / never overwrite the output
  --out-dir D  batch mode: write one output per input into D (basename kept,
               extension from -f or the input). Globs in -i are expanded.
  --fail-fast  in batch mode, stop at the first failing file
  --json       emit one machine-readable JSON result line (an array in batch)
  --quiet      suppress the human-readable success line
  --dry-run    validate the filtergraph + report output dims; write nothing
  -filters [NAME]  list every filter, or just NAME's syntax (add --json for a
               machine-readable list)
  -info        print input dimensions and exit
  -V           print version
  -h           help

OUTPUT is a file path or '-' for stdout. When piping, the result line is
written to stderr so stdout carries only the encoded image bytes.

Batch mode (`--out-dir`) processes each input independently and keeps going on
per-file errors (use `--fail-fast` to stop). The exit code is non-zero if any
file failed.

颜色可使用 #rgb、#rrggbb、#rrggbbaa、0x…、r-g-b[-a] 或名称（red、white、transparent、…）。颜色中不能使用逗号，因此可安全地用于滤镜图中。

滤镜

几何 — scale=W:H[:nearest|bilinear|bicubic|lanczos]（-1 保持宽高比；bicubic/lanczos 是高质量的可分离重采样器，缩小时可抗锯齿，放大时保持清晰——默认值为 bilinear），crop=W:H[:X:Y]、pad=W:H[:X:Y[:color]]、hflip、vflip、transpose=90|180|270、rotate=DEG[:color]（任意角度，画布会扩展）。

颜色 — grayscale、invert、sepia、solarize、brightness=V、temperature=V、contrast=V、saturation=V、gamma=V、hue=DEG、threshold=V、opacity=V、tint=color。

卷积 — blur=R（方框模糊）、gblur=SIGMA（可分离高斯模糊）、sharpen[=AMOUNT]、edge（Sobel 边缘检测）、emboss、convolution=K[:DIV:BIAS]（自定义 N×N 卷积核，例如 convolution=0 -1 0 -1 5 -1 0 -1 0）。

合成 / 绘制 — overlay=X:Y[:INDEX]（对另一个 -i 输入进行 Alpha「覆盖」合成）、fill=color、drawbox=X:Y:W:H:color[:fill|thickness]。

示例

# Thumbnail, preserving aspect ratio (lanczos = best downscale quality)
imgcli -i photo.jpg -vf "scale=400:-1:lanczos" thumb.png

# Stylise: desaturate a touch, boost contrast, soften
imgcli -i photo.jpg -vf "saturation=0.6,contrast=1.15,gblur=1" look.jpg

# Watermark a logo in the top-left, 60% opacity, then convert to JPEG
imgcli -i page.png -i logo.png -vf "opacity=0.6,overlay=24:24" out.jpg

# Rotate 30° onto a transparent canvas
imgcli -i sticker.png -vf "rotate=30:transparent" rotated.png

# No input file? Generate a test card.
imgcli -i testsrc=640x480 card.png

# Pipe-friendly: read stdin, write stdout (use -f to name the output format)
curl -s https://example.com/in.png | imgcli -i - -vf "scale=800:-1" -f jpg - > out.jpg

# Batch a whole folder into thumbnails (one call; per-file results)
imgcli -i "photos/*.jpg" --out-dir thumbs -vf "scale=400:-1:lanczos" -f png

面向 AI Agent 和脚本

imgcli 专为自动化流水线中的可靠工具而构建：单个自包含二进制文件、无依赖、结果确定、非交互且机器可读。参见 AGENTS.md，获取节省 token 的操作指南。

# Always pass -y (don't prompt) and --json (parseable result) in automation:
imgcli --json -y -i in.jpg -vf "scale=512:-1" out.png
# -> {"ok":true,"output":"out.png","width":512,"height":341,"format":"png","bytes":34122}

• 结果确定且非交互 — 从不提示；未指定 -y 时会拒绝覆盖；每次转换使用一个进程。
• 结构化输出 — 使用 --json 输出结果，使用 --quiet 静默运行；退出码稳定（0 表示成功，1 表示运行时错误，2 表示用法错误）。
• 无网络、无子进程 — 可在沙箱中安全处理不可信输入。
• 无需转换即可探测 — imgcli --json -info -i file.jpg。

安全

imgcli 使用 C 解码不可信的图像文件，因此我们非常重视内存安全。 代码库已根据 OWASP Top 10、常见的 C/CWE 类别以及 ffmpeg 历史漏洞类别进行审计。重点如下：

• 可防范解压炸弹 — 在解码像素之前，先根据文件头验证尺寸；严格限制图像大小（每轴 16384 像素，64 Mpx）。
• 安全处理整数溢出的内存分配，通过单一且设有上限的分配入口实现。
• 不支持协议、URL 或子进程 — ffmpeg 最严重的一类漏洞（通过 HLS 播放列表造成 SSRF／文件读取）在此架构下不可能发生。
• 强化构建（_FORTIFY_SOURCE、栈保护、PIE/RELRO、格式警告）、ASan/UBSan（make asan）和模糊测试框架（make fuzz）。

完整的威胁模型、OWASP/CWE 映射、ffmpeg CVE 类别分析和依赖策略，请参阅 SECURITY.md。

目录结构

src/image.{h,c}    Image (RGBA frame) + load/save (stb glue, PPM writer)
src/filters.{h,c}  filtergraph parser + every filter + registry
src/source.{h,c}   synthetic input generators
src/util.{h,c}     colour / size parsing
src/main.c         CLI argument handling (incl. --json output)
third_party/       vendored stb_image.h, stb_image_write.h (public domain)
fuzz/              libFuzzer harness for the decode -> filtergraph path
AGENTS.md          token-economical usage guide for agents/scripts
SECURITY.md        threat model, OWASP/CWE mapping, hardening, dependency policy

贡献

贡献者设置、验证目标、滤镜注册表指南和 PR 要求均见 CONTRIBUTING.md。

有问题或想法？请使用 讨论区。如需报告错误或提出功能／格式请求，请创建 issue — 模板会为你提供指引。

支持

如果 imgcli 对你有帮助，不妨考虑赞助其开发 — 这将为新增格式、安全强化和维护提供资金。请参阅 SPONSORS.md。

许可证

你可以自由使用 imgcli 源代码（MIT）。随附的 stb 头文件属于公有领域（或可按你的选择采用 MIT 许可证），随附的 qoi.h 采用 MIT 许可证；完整的第三方声明见 THIRD_PARTY_NOTICES.md。