imgcli

imgcli — C 言語によるコマンドライン画像変換・処理ツール

ImageMagickのパワーとffmpegの構文を、依存関係ゼロで。 画像の変換、サイズ変更、切り抜き、フィルター処理、合成を行う小さなC言語バイナリです — PNG、JPEG、BMP、TGA、 GIF、PPM、QOIに対応し、ffmpeg形式のフィルターグラフで操作します。システムライブラリは不要で、C11コンパイラーがあればどこでもコンパイルできます。

⚡ 一般的なサイズ変更・フィルター処理ではImageMagickより約8倍高速で、232 KBの単一バイナリ（約470分の1のサイズ）です — ベンチマークを見る。静止画像向けの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エッジ検出 · エンボス · カスタム畳み込みカーネル · アルファ合成オーバーレイ · 矩形の描画 · 単色塗りつぶし。

設計： 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 → 幅300にサイズ変更	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は200以上のフォーマットに対応する、より幅広い16ビット／HDRIツールキットです。一方、imgcliは速度、サイズ、起動時間で優れた軽量な8ビットパイプラインです。エージェントやスクリプトがタスクごとにプロセスを1つ起動する場合に重要となる特長です。

依存関係とフォーマット

デフォルトのビルドには依存関係がありません — システムのCライブラリ（libc）だけをリンクする単一バイナリです。デコードとエンコードには、同梱されたパブリックドメインのstbおよびqoiのシングルヘッダーライブラリを使用し、バイナリに直接コンパイルします。apt installは不要で、共有ライブラリもバージョンの競合もありません。

• 組み込みフォーマット — 依存関係不要： PNG、JPEG、BMP、TGA、GIF、PPM、QOI。 TIFFなど、プレーンなC言語で実装できるほかのフォーマットも組み込まれ、バイナリの依存関係は引き続きありません。
• 外部ライブラリが必要なフォーマット — オプトインのみ： WebP、AVIF、HEIC、JPEG XLのデコードには、大規模な外部ライブラリ（libwebp、libavif、libheif、libjxl）が必要です。これらに対応するパブリックドメインのシングルヘッダーデコーダーはなく、手作業で実装するのも現実的ではありません。imgcliがこれらに対応する場合も、外部ライブラリをリンクするオプトインのビルドフラグ（例：make WEBP=1）のみで対応します。

「依存関係ゼロ」という説明はデフォルトのビルドに適用され、今後も変わりません — オプトインしたフォーマット用ライブラリがデフォルトのビルドにコンパイルされることはありません。 このようなフラグを有効にしたビルドは、定義上、依存関係ゼロではなくなります。そのトレードオフはオプトインする時点で明示されます。

このような構成にしている理由

ffmpeg の概念	imgcli での相当機能
AVFrame / pixfmt	すべての画像を 8 ビットのパック済み RGBA（Image）に正規化します
demuxer/decoder	ベンダー提供の stb_image を使う img_load（PNG/JPEG/BMP/TGA/GIF/…）
-vf フィルターグラフ	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

ネイティブのエージェントツール（MCP）として使用する

MCP サーバーで imgcli をラップすると、AI エージェントから 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 入力をアルファ合成で「over」合成）、 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 エージェントとスクリプト向け

imgcli は、自動化されたパイプラインで信頼性の高いツールとして使えるように設計されています。単一の自己完結型バイナリで、依存関係がなく、決定的かつ非対話型で、機械可読です。トークンを節約できるレシピ集は AGENTS.md をご覧ください。

# 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 がない場合は上書きを拒否し、変換ごとに 1 つのプロセスを実行します。
• 構造化された出力 — 結果には --json、メッセージの抑制には --quiet を使用できます。終了コードは安定しています（0 は成功、1 は実行時エラー、2 は使用方法のエラー）。
• ネットワークもサブプロセスもなし — サンドボックス内で信頼できない入力を安全に処理できます。
• 変換せずにプローブ — imgcli --json -info -i file.jpg。

セキュリティ

imgcli は信頼できない画像ファイルを C でデコードするため、メモリ安全性を重視しています。 コードベースは OWASP Top 10、一般的な C/CWE の脆弱性クラス、および ffmpeg で過去に見られた脆弱性クラスに照らして監査されています。主なポイントは次のとおりです。

• 解凍爆弾への対策 — ピクセルをデコードする前にヘッダーから寸法を検証し、 サイズに厳格な上限を設けています（各軸 16384 px、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 をご覧ください。

ご質問やアイデアがある場合は、Discussions をご利用ください。バグや機能・形式に関するリクエストは、イシューを作成してください。テンプレートに従って進められます。

サポート

imgcli が役立った場合は、開発へのスポンサーをご検討ください。新しい形式への対応、セキュリティ強化、メンテナンスの資金になります。SPONSORS.md もご覧ください。

ライセンス

imgcli のソースは自由にご利用いただけます（MIT）。ベンダー提供の stb ヘッダーはパブリックドメイン（または任意で MIT）で、ベンダー提供の qoi.h は MIT ライセンスです。サードパーティに関する通知の全文は THIRD_PARTY_NOTICES.md に記載されています。