A smart image cropping tool that supports precise cropping while keeping the image centered, optimized for social media and content creation.
🚀 Quick Start
Command-Line Usage
# 单张裁剪
python scripts/crop_image.py input.jpg --size 900x383 --output output.jpg
# 使用预设尺寸
python scripts/crop_image.py input.jpg --preset wechat-cover --output output.jpg
# 批量裁剪
python scripts/batch_crop.py folder/ --size 900x383 --output cropped_folder/
Python Usage
from image_cropper.scripts.crop_image import crop_to_center
# 裁剪为指定尺寸
crop_to_center("input.jpg", "output.jpg", width=900, height=383)
# 使用预设尺寸
crop_to_center("input.jpg", "output.jpg", preset="wechat-cover")
# 批量裁剪
from image_cropper.scripts.batch_crop import batch_crop
batch_crop("folder/", "output_folder/", size="900x383")
📏 Preset Sizes
WeChat Official Account
wechat-cover: 900x383 (2.35:1, Official Account cover)wechat-share: 900x900 (1:1, share card)wechat-banner: 1080x460 (2.35:1, high-definition cover)
Social Media
instagram: 1080x1080 (1:1, Instagram/Weibo)twitter: 1200x675 (16:9, Twitter landscape)linkedin: 1200x627（1.91:1，LinkedIn）
Article Images
article-16-9: 1792x1024 (16:9, landscape image)article-4-3: 1024x768 (4:3, standard image)article-1-1: 1024x1024 (1:1, square image)
🎯 Use Cases
Use Case 1: WeChat Official Account Cover Cropping
Requirement: Generate a cover suitable for both headline display and Moments sharing
Solution：
# 生成2.35:1封面（900x383）
python scripts/crop_image.py original.jpg --preset wechat-cover --output cover.jpg
# 同时生成1:1测试版本（验证分享效果）
python scripts/crop_image.py original.jpg --preset wechat-share --output test_1to1.jpg
Key Principles：
- All key content must be within the central 60% area
- Ensure text remains intact after cropping to 1:1
- Avoid placing important elements at the edges
Use Case 2: Batch Processing Images
Requirement: Uniformly crop all images in a folder to 16:9
Solution：
python scripts/batch_crop.py raw_images/ --preset article-16-9 --output cropped_images/
Use Case 3: Instagram Square Cropping
Requirement: Crop a landscape photo into a square
Solution：
python scripts/crop_image.py photo.jpg --preset instagram --output photo_square.jpg
🔧 Parameter Description
Single Image Cropping (crop_image.py)
| Parameter | Description | Example |
|---|---|---|
input |
Input image path (required) | photo.jpg |
--size |
Output size (width x height) | 900x383 |
--preset |
Use preset size | wechat-cover |
--output |
Output path (required) | output.jpg |
--quality |
JPEG quality (1-100, default 95) | 95 |
Note：--size and --preset are mutually exclusive; prioritize using --preset
Batch Cropping (batch_crop.py)
| Parameter | Description | Example |
|---|---|---|
input_dir |
Input folder path (required) | images/ |
--size |
Output size | 900x383 |
--preset |
Use preset size | wechat-cover |
--output |
Output folder path (required) | cropped/ |
--pattern |
File matching pattern (default *.jpg) | *.png |
💡 Best Practices
1. Safe Area Design
For scenarios where cropping may occur (such as WeChat covers), follow these principles when designing:
画面布局：
[边缘20%] [中心60%安全区] [边缘20%]
Key content: Place only within the central 60% area Decorative elements: Can be placed at the edges
2. Test Before Cropping
Before official use, test the 1:1 cropping effect first:
# 生成多个测试版本
python scripts/crop_image.py original.jpg --size 900x900 --output test_1to1.jpg
python scripts/crop_image.py original.jpg --size 900x383 --output test_cover.jpg
Check:
- ✅ Is the text intact?
- ✅ Are key elements centered?
- ✅ Are you satisfied with the cropped result?
3. Batch Processing Tips
When batch processing, it is recommended to:
- First test the result with 1-2 images
- After confirming satisfaction, then process in batch
- Keep backups of the original files
📊 Dependency Installation
pip install pillow
🛠️ Troubleshooting
Common Issues
Q1: Prompt shows "PIL not available"
# 安装Pillow库
pip install pillow
Q2: Cropped image is distorted
Cause: The specified size ratio does not match the original image Solution: This tool maintains the original image ratio with center cropping, so it will not distort
Q3: Crop position does not meet expectations
Cause: This tool keeps the image center as the crop position by default Solution: If you need a custom crop position, you can use professional image editing tools
Q4: Some images fail during batch cropping
Cause: The image format is unsupported or the file is corrupted Solution: Check the file format; common formats such as JPG and PNG are supported
📚 Reference Resources
- Preset Size List：
references/preset-sizes.md - Usage Examples: See the descriptions for each scenario above
- Technical Documentation: Pillow official documentation https://pillow.readthedocs.io/
Last Updated：2026-01-11 Skill Version：v1.0 Dependencies：Pillow >= 8.0.0