godot-fun Image Trim
Remove invalid border padding — transparent margins, flat white/green edges, or unused canvas space — with Pillow. Default: preserve the source aspect ratio so trimmed sprites stay proportionally consistent with the original frame.
Unlike --crop on image-remove-white-background (tight alpha bbox only), this skill expands the crop box to match the original width:height ratio while removing as much empty area as possible.
Rules
When this skill applies, read and follow skill-dependency-manager — run scripts as documented, install missing tools into .dependency/.
- Run
trim.pythrough theimage-trimmanifest entry (.dependency/image-trim/.venv/). Never use hostpython,py,python3, or any interpreter outside.dependency/. - Do not hand-write ImageMagick / FFmpeg crop commands — use the bundled script.
- Single file only. Pass one image with
--image; directories are not supported. populated: falseforimage-trimis not a reason to skip. Install first, setpopulated: true, retry the same command.- Pass the input path as-is. Output goes to
<image-dir>/image-trim/by default — no path rewriting; never overwrite sources. - Crop only — preserve source pixel data and alpha; never composite onto black/white or fill background colors.
- Output filenames keep the original asset name (e.g.
bullet_speed.png). Cursor chat attachment paths likeempty-window_images_bullet_speed-<uuid>.pngare shortened automatically.
Setup (first run)
From project root:
.dependency/python/python -m venv .dependency/image-trim/.venv
.dependency/image-trim/.venv/Scripts/python.exe -m pip install Pillow
Register in .dependency/manifest.json:
"image-trim": {
"populated": true,
"bin": ".dependency/image-trim/.venv/Scripts/python.exe"
}
Use bin/python on Unix.
Quick Start
Default: create an image-trim/ folder beside the input file and write the output there:
# Auto-detect transparent or solid-color borders (default)
# image/sprites/hero.png → image/sprites/image-trim/hero.png
.dependency/image-trim/.venv/Scripts/python.exe .ai/image-trim/trim.py --image image/sprites/hero.png
Custom output path:
.dependency/image-trim/.venv/Scripts/python.exe .ai/image-trim/trim.py --image image/sprites/hero.png -o image/sprites_trimmed
Detection Modes
| Mode | Behavior |
|---|---|
auto (default) |
Use alpha when the image has transparency; otherwise sample corner color and trim solid borders |
alpha |
Trim only by alpha — pixels above --alpha-threshold count as content |
color |
Trim pixels matching --color (or corner sample) within --tolerance |
# Force alpha-only trim on RGBA cutouts
.dependency/image-trim/.venv/Scripts/python.exe .ai/image-trim/trim.py --image image/cutout.png --mode alpha
# Trim white padding on opaque JPG/PNG
.dependency/image-trim/.venv/Scripts/python.exe .ai/image-trim/trim.py --image image/foo.jpg --mode color --color FFFFFF
Defaults
| Option | Default | Notes |
|---|---|---|
--image |
Required | Single supported image file |
| Output | <image-dir>/image-trim/<name> |
Use -o / --output for custom file or directory |
| Aspect ratio | Preserve source | Pass --tight for tight bbox crop (no aspect lock) |
--mode |
auto |
alpha for transparent PNGs; color for flat backgrounds |
--alpha-threshold |
10 |
Lower = stricter transparency detection |
--tolerance |
25 |
Color distance for solid-border trim |
--padding |
0 |
Extra pixels kept around detected content |
Supported inputs: .png, .jpg, .jpeg, .webp, .gif, .bmp, .tif, .tiff, .avif, .ico.
Aspect Ratio Behavior
Default (preserve source): After detecting the content bounding box, the script expands the crop rectangle to the same width:height ratio as the source image, centered on the content. This removes empty borders while keeping frame proportions stable for animation sheets and UI assets.
Tight crop (--tight): Crop exactly to the content bbox (plus --padding) — same behavior as --crop on background-removal skills.
# Tight crop — smallest rectangle around content
.dependency/image-trim/.venv/Scripts/python.exe .ai/image-trim/trim.py --image image/sprites/hero.png --tight
# Keep 4 px breathing room, still preserve aspect ratio
.dependency/image-trim/.venv/Scripts/python.exe .ai/image-trim/trim.py --image image/sprites/hero.png --padding 4
Agent Workflow
- Pick skill — remove padding/margins → this skill; remove backgrounds → image-remove-white-background or image-remove-background.
- Paths — Pass whatever image path the user gives. Output lands in
image-trim/next to that file by default. - One file per run — trim one image, verify dimensions, then repeat for additional files if needed.
- After background removal — run on
image-remove-background/outputs to drop excess transparent canvas. - Revert — delete output file or
git restore; sources are never modified.
Agent Notes
- Use the bundled script, not hand-written ImageMagick / FFmpeg crop commands.
- Missing image-trim venv → populate
.dependency/per skill-dependency-manager, retry same command. - Do not copy, move, or replace the source with trimmed output — tell the user where the output file is.
- Need background removal first → image-remove-white-background or image-remove-background.
Troubleshooting
| Issue | Fix |
|---|---|
image-trim missing in manifest |
Follow Setup; update manifest |
Directory passed to --image |
Run once per file; this skill accepts image files only |
| Output already exists | Delete the existing output or choose a different -o path |
| Nothing trimmed | Content may already fill the canvas; try --mode color with --color |
| Too much removed | Lower --tolerance or --alpha-threshold; add --padding |
| Borders remain | Raise --tolerance; use --mode color with explicit --color |
| Distorted proportions after trim | Do not pass --tight unless user wants tight bbox |
| JPEG saved with wrong mode | Script converts RGBA → RGB automatically for .jpg output |
| Output has black instead of transparency | Source may be JPEG data saved with a .png extension (Cursor attachments) — re-supply the original RGBA PNG |
| Long Cursor attachment filenames | Script auto-renames to the embedded asset name (bullet_speed.png, etc.) |
CLI
Copy-paste commands: cli/image-trim.md
Related
- Background removal: image-remove-white-background, image-remove-background
- Resize after trim: image-resize