git:20260827.ae998b6 to git:20260827.d2b68b3

---

name: image-trim

description: >-

Trims invalid border regions (transparent or solid-color padding) from images

using Pillow. Default crop preserves the source aspect ratio. Use when the user

wants image trim, crop empty borders, remove transparent margins, trim white

padding, auto-crop sprites, or tighten cutouts before Godot import.

---

# Image Trim

Unlike `--crop` on [image-remove-white-background](../image-remove-white-background/SKILL.md) (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

- Run `trim.py` through the **`image-trim` manifest entry** (`.dependency/image-trim/.venv/`). Never use host `python`, `py`, `python3`, or any interpreter outside `.dependency/`.

- **Single file only.** Pass one image with `--image`; directories are not supported.

- `populated: false` for `image-trim` is not a reason to skip. Install first, set `populated: true`, retry the same command.

- Output filenames keep the **original asset name** (e.g. `bullet_speed.png`). Cursor chat attachment paths like `empty-window_images_bullet_speed-<uuid>.png` are shortened automatically.

## Setup (first run)

From project root:

```bash

.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`:

```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:

```bash

# Auto-detect transparent or solid-color borders (default)

.dependency/image-trim/.venv/Scripts/python.exe .ai/image-trim/trim.py --image image/sprites/hero.png

```

Custom output path:

```bash

.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 |

| `color` | Trim pixels matching `--color` (or corner sample) within `--tolerance` |

```bash

# 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.

```bash

.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

## Agent Notes

1. Use the bundled script, not hand-written ImageMagick / FFmpeg crop commands.

## 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 |

| Long Cursor attachment filenames | Script auto-renames to the embedded asset name (`bullet_speed.png`, etc.) |

## Related

- Background removal: [image-remove-white-background](../image-remove-white-background/SKILL.md), [image-remove-background](../image-remove-background/SKILL.md)

- Resize after trim: [image-resize](../image-resize/SKILL.md)