Image Processing
Perform deterministic processing on existing images: resize/crop/pad/format conversion/compression/watermark/round/collage/thumbnail.
All operations go throughskills/shared/scripts/image_ops.py(pure Pillow), no ad-hoc scripting.
Input
- One or more existing image file paths (PNG, JPG, WebP, or other Pillow-supported formats)
- Target operation and parameters (dimensions, aspect ratio, quality, watermark text, collage layout, etc.)
Output
- Processed image file(s) (path specified by user or defaults to
outputs/<topic name>/) - Each command echoes
✅ path (widthxheight, sizeKB);infooutputs JSON
Boundaries (Distinction from card-*)
- card-quote / card-xiaohongshu / poster-hero / comparison-card = design and render new images (HTML → screenshot)
- image-editing = process existing images, no visual design, no content generation, only pixel-level operations
- For "generate an image from data/text" → use chart/infographic/card-*; this skill only processes existing image files
Execution Steps
- Confirm input image exists and ensure the target operation and parameters are clear
- Run the corresponding subcommand of
image_ops.pyfrom the project root (see below) - When platform sizes are needed, consult
references/platform-sizes.mdfor recommended aspect ratios/pixels - Report output path and dimensions; multiple steps can be chained (e.g., resize then compress)
Command Reference
Script path is always skills/shared/scripts/image_ops.py; all subcommands support -h to view parameters.
# Resize: by width/height/percentage, --keep-ratio maintains aspect ratio within bounds without distortion
python skills/shared/scripts/image_ops.py resize -i in.jpg -o out.jpg --width 1080
python skills/shared/scripts/image_ops.py resize -i in.jpg -o out.jpg --percent 50
python skills/shared/scripts/image_ops.py resize -i in.jpg -o out.jpg --width 1080 --height 1440 --keep-ratio
# Crop: by coordinates or center-crop to target dimensions
python skills/shared/scripts/image_ops.py crop -i in.jpg -o out.jpg --box 100,50,900,650
python skills/shared/scripts/image_ops.py crop -i in.jpg -o out.jpg --width 1080 --height 1080
# Pad to target aspect ratio (core social media adaptation): pad any image to 1:1 / 9:16 / 16:9
python skills/shared/scripts/image_ops.py pad -i in.jpg -o out.png --ratio 9:16 --background "#ffffff"
python skills/shared/scripts/image_ops.py pad -i in.jpg -o out.png --ratio 1:1 --background "20,20,30"
# Format conversion png/jpg/webp
python skills/shared/scripts/image_ops.py convert -i in.png -o out.webp --format webp --quality 85
# Compress: fixed quality or approximate target file size (jpg/webp)
python skills/shared/scripts/image_ops.py compress -i in.jpg -o out.jpg --quality 80
python skills/shared/scripts/image_ops.py compress -i in.jpg -o out.jpg --max-kb 200
# Watermark: text (position/opacity/size/color, auto-find Chinese system font) or image (bottom-right, etc.)
python skills/shared/scripts/image_ops.py watermark -i in.jpg -o out.png --text "@handle" --position bottom-right --opacity 0.5 --size 40
python skills/shared/scripts/image_ops.py watermark -i in.jpg -o out.png --image logo.png --position bottom-right --scale 0.3 --opacity 0.8
# Rounded corners (outputs transparent PNG); --radius-percent 50 gives a circle
python skills/shared/scripts/image_ops.py round -i in.jpg -o out.png --radius 60
python skills/shared/scripts/image_ops.py round -i avatar.jpg -o out.png --radius-percent 50
# Collage: horizontal/vertical/grid NxM (columns x rows), --cell-width/height set uniform cell size
python skills/shared/scripts/image_ops.py collage -i a.jpg b.jpg c.jpg -o out.jpg --mode horizontal --gap 12
python skills/shared/scripts/image_ops.py collage -i 1.jpg 2.jpg 3.jpg 4.jpg -o out.jpg --grid 2x2 --gap 10 --cell-width 540 --cell-height 540
# Thumbnail (longest side in pixels)
python skills/shared/scripts/image_ops.py thumbnail -i in.jpg -o thumb.jpg --size 256
# Read image info (JSON: dimensions/format/aspect ratio/size/transparency)
python skills/shared/scripts/image_ops.py info -i in.jpg
Domain Knowledge: Recommended Platform Sizes
Common platform recommendations can be found in references/platform-sizes.md. Quick cheat sheet:
- Xiaohongshu vertical image post: 1080×1440 (3:4); Xiaohongshu video/vertical poster: 1080×1920 (9:16)
- WeChat Moments single image / general square image: 1:1 (e.g., 1080×1080)
- Horizontal quote/cover: 16:9 (e.g., 1920×1080); WeChat Official Account header: 900×383
- Weibo image: 1:1 or 4:3; Douyin/WeChat Channels cover: 9:16 (1080×1920)
Adaptation approach: prefer pad (add padding without cropping content or distorting) to preserve the full image; if a full-bleed edge-to-edge result is desired, use crop center-crop to target ratio; just to reduce file size, use resize/compress.
Profile Awareness
- With Profile: default watermark text uses account name/handle; default output ratio matches the user's primary platform (e.g., Xiaohongshu account defaults to 1080×1440)
- Without Profile: executes according to explicit user parameters; ratio defaults to original, watermark requires user-provided text
Dependencies & Error Handling
- Dependency: Pillow (already installed,
python -c "import PIL"works), pure standard library, no other third-party packages - Built-in boundary checks in the script: file not found / crop box out of bounds / invalid ratio or color → exit code 2 and prints
ERROR: - Falls back to PIL default font with a
WARNif Chinese system font is not found; can specify with--font - Self-test:
python skills/shared/scripts/image_ops.py --selftest