Crop Image
Procedural runbook and tooling for inspecting image boundaries, trimming empty margins (transparent or solid color backgrounds), and executing precision crops.
Includes a zero-dependency Python 3 utility (crop.py) for bit-perfect PNG handling and automatic fallback to Pillow when installed.
Workflows
Choose the matching workflow based on your objective:
- Inspect Image & Subject Bounding Box
- Autocrop Transparent Blank Space
- Trim Solid Color Borders (White / Black / Custom)
- Crop by Explicit Bounding Box or Dimensions
- Validate Cropped Asset
1. Inspect Image & Subject Bounding Box
Before modifying an image, inspect its current dimensions, color channels, and where the actual subject pixels reside.
- Run the inspection command using crop.py:
python3 .agents/skills/crop-image/scripts/crop.py <path/to/image> --inspect - Review the diagnostic output:
- Dimensions: Overall pixel width and height.
- Detected Border/Corner Color: Color sampled from corners.
- Alpha Subject Bounding Box: Coordinate extent
[left, top, right, bottom]where alpha > 0. - Subject Margins: Number of blank pixels on left, right, top, and bottom edges. (Note: iOS Simulator captures taken via
xcrun simctl io booted screenshot /abs/path/to/file.png—see/ios-simulator-screenshot—capture the exact device framebuffer with0pxouter margin, whereas macOS window captures include transparent shadow margins that need--autocrop.)
- Completion Criterion: Bounding box coordinates and margin sizes are printed to stdout without modifying the source image.
2. Autocrop Transparent Blank Space
Remove excess transparent padding around a subject, optionally preserving a small aesthetic margin (e.g. 8–16 px) so the graphic does not touch container boundaries.
- Run autocrop with desired padding (default is 0 for tight crop):
# In-place overwrite with 12px padding around subject: python3 .agents/skills/crop-image/scripts/crop.py <path/to/image.png> --autocrop --padding 12 --in-place # Or output to a new file: python3 .agents/skills/crop-image/scripts/crop.py <input.png> -o <output.png> --autocrop --padding 12 - For semi-transparent edge artifacts, increase
--alpha-thresh(e.g.--alpha-thresh 10). - Completion Criterion: Target image exists on disk with reduced dimensions tightly bounding the subject.
3. Trim Solid Color Borders (White / Black / Custom)
Trim uniform solid background colors (e.g. white borders 255,255,255 or dark borders 0,0,0):
- Specify the RGB color to trim and tolerance (0–255):
# Trim pure white border with tolerance 5 and 10px margin: python3 .agents/skills/crop-image/scripts/crop.py <path/to/image> -o <output> --autocrop --color 255,255,255 --tolerance 5 --padding 10 # Trim pure black border: python3 .agents/skills/crop-image/scripts/crop.py <path/to/image> -o <output> --autocrop --color 0,0,0 --tolerance 5 - Completion Criterion: Script reports
Successwith adjusted dimensions matching the bounded subject.
4. Crop by Explicit Bounding Box or Dimensions
Extract a specific rectangle by pixel coordinates left,top,right,bottom (inclusive):
- Compute or select the target coordinates
left,top,right,bottom:python3 .agents/skills/crop-image/scripts/crop.py <path/to/image> -o <output> --box 100,50,900,650 - If working on macOS and only cropping from the center or fixed width/height:
sips --cropToHeightWidth <targetHeight> <targetWidth> <input> --out <output> - Completion Criterion: Output image matches the exact target pixel dimensions
(right - left + 1) × (bottom - top + 1).
5. Validate Cropped Asset
Always verify the cropped image before declaring completion:
- Query file metadata with
sips(macOS) or crop.py--inspect:sips -g pixelWidth -g pixelHeight <path/to/cropped-image> python3 .agents/skills/crop-image/scripts/crop.py <path/to/cropped-image> --inspect - Confirm:
pixelWidthandpixelHeightmatch expected cropped dimensions.- The file is readable and not corrupted.
- For web/slides projects, run local build/linter (e.g.
npm --prefix slides run build) to ensure layouts using the asset compile cleanly.
- Completion Criterion: Image metadata returns expected dimensions and project build exits with code 0.