\r \r

Pillow Image Processing Skill\r

\r English | 简体中文\r \r This skill provides comprehensive image processing capabilities through executable scripts and reference documentation for Pillow (PIL).\r \r

When to Use This Skill\r

\r Activate this skill when the user requests:\r \r

• Image editing operations (resize, crop, rotate, color adjustments)\r
• Batch processing multiple images\r
• Adding watermarks (text or image)\r
• Image format conversions\r
• Extracting image metadata or EXIF data\r
• Applying filters or effects\r
• Creating thumbnails\r \r

Core Capabilities\r

\r

1. Image Editor (scripts/image_editor.py)\r

\r Edit single images with various operations:\r \r Usage:\r

python scripts/image_editor.py input.jpg output.jpg [options]\r
```\r
\r
**Options:**\r
- `--width WIDTH` / `--height HEIGHT`: Resize dimensions\r
- `--no-aspect`: Ignore aspect ratio when resizing\r
- `--crop X Y WIDTH HEIGHT`: Crop rectangle\r
- `--rotate DEGREES`: Rotate image\r
- `--flip {horizontal,vertical}`: Flip image\r
- `--brightness FACTOR`: Adjust brightness (0.0-2.0)\r
- `--contrast FACTOR`: Adjust contrast (0.0-2.0)\r
- `--color FACTOR`: Adjust color saturation (0.0-2.0)\r
- `--sharpness FACTOR`: Adjust sharpness (0.0-2.0)\r
- `--filter {blur,contour,detail,edge_enhance,emboss,sharpen,smooth}`: Apply filter\r
- `--format FORMAT`: Output format (JPEG, PNG, etc.)\r
- `--quality QUALITY`: JPEG quality (1-100)\r
\r
**Examples:**\r
```bash\r
# Resize maintaining aspect ratio\r
python scripts/image_editor.py photo.jpg resized.jpg --width 800\r
\r
# Multiple operations\r
python scripts/image_editor.py input.jpg output.jpg \\r
    --crop 100 100 800 600 \\r
    --rotate 90 \\r
    --brightness 1.2 \\r
    --sharpen 1.5\r
```\r
\r
### 2. Batch Processor (`scripts/batch_processor.py`)\r
\r
Process multiple images in parallel:\r
\r
**Usage:**\r
```bash\r
python scripts/batch_processor.py input_dir output_dir [options]\r
```\r
\r
**Options:**\r
- `--pattern PATTERN`: File pattern (e.g., *.jpg)\r
- `--resize WIDTH HEIGHT`: Resize all images\r
- `--thumbnail MAX_W MAX_H`: Create thumbnails (maintains aspect)\r
- `--grayscale`: Convert to grayscale\r
- `--brightness FACTOR`: Adjust brightness\r
- `--format FORMAT`: Convert format\r
- `--quality QUALITY`: JPEG quality\r
- `--workers N`: Number of parallel workers (default: 4)\r
\r
**Examples:**\r
```bash\r
# Create thumbnails\r
python scripts/batch_processor.py ./photos ./thumbs --thumbnail 300 300\r
\r
# Batch convert and resize\r
python scripts/batch_processor.py ./raw ./processed \\r
    --resize 1920 1080 \\r
    --format JPEG \\r
    --quality 90\r
```\r
\r
### 3. Watermark Tool (`scripts/watermark.py`)\r
\r
Add text or image watermarks:\r
\r
**Usage:**\r
```bash\r
python scripts/watermark.py input.jpg output.jpg --text "TEXT" [options]\r
python scripts/watermark.py input.jpg output.jpg --image logo.png [options]\r
```\r
\r
**Common Options:**\r
- `--position {top-left,top-right,bottom-left,bottom-right,center}`: Position\r
- `--opacity 0-255`: Transparency level\r
- `--margin PIXELS`: Margin from edge\r
\r
**Text Options:**\r
- `--font-size SIZE`: Font size\r
- `--color COLOR`: Text color (white/black/red/etc)\r
\r
**Image Options:**\r
- `--scale RATIO`: Watermark scale (0.0-1.0)\r
\r
**Examples:**\r
```bash\r
# Text watermark\r
python scripts/watermark.py photo.jpg marked.jpg \\r
    --text "© 2026 Company" \\r
    --position bottom-right \\r
    --opacity 128\r
\r
# Logo watermark\r
python scripts/watermark.py image.jpg output.jpg \\r
    --image logo.png \\r
    --scale 0.2 \\r
    --position top-left\r
```\r
\r
### 4. Image Info (`scripts/image_info.py`)\r
\r
Extract image metadata and properties:\r
\r
**Usage:**\r
```bash\r
python scripts/image_info.py image.jpg [options]\r
```\r
\r
**Options:**\r
- `--format {text,json}`: Output format\r
- `--output FILE`: Save to file\r
\r
**Provides:**\r
- File information (size, path)\r
- Image properties (dimensions, format, mode)\r
- Color information (bands, palette)\r
- EXIF data (if available)\r
- Metadata\r
\r
**Example:**\r
```bash\r
# Display info\r
python scripts/image_info.py photo.jpg\r
\r
# Save as JSON\r
python scripts/image_info.py photo.jpg -o info.json --format json\r
```\r
\r
## Reference Documentation\r
\r
### `references/common_operations.md`\r
\r
Comprehensive Pillow reference covering:\r
- Opening and saving images\r
- Resizing and cropping\r
- Rotation and flipping\r
- Color adjustments and enhancements\r
- Filters and effects\r
- Drawing on images\r
- Image composition\r
- Working with channels\r
- EXIF data handling\r
- Performance tips\r
\r
**When to use:** When Claude needs specific Pillow syntax or operation patterns.\r
\r
### `references/best_practices.md`\r
\r
Best practices guide covering:\r
- Format selection (JPEG vs PNG vs WebP)\r
- Resizing strategies\r
- Color mode conversion\r
- Memory management\r
- Watermarking strategies\r
- Filter application\r
- Optimization techniques\r
- Error handling patterns\r
- Common workflows\r
\r
**When to use:** When designing image processing workflows or optimizing performance.\r
\r
## Workflow Guidelines\r
\r
### Step 1: Analyze Requirements\r
- What format is the input image?\r
- What operations are needed?\r
- Is it a single image or batch?\r
- Are there quality requirements?\r
\r
### Step 2: Choose the Right Tool\r
- Single image edit → `image_editor.py`\r
- Multiple images → `batch_processor.py`\r
- Add watermark → `watermark.py`\r
- Need info → `image_info.py`\r
\r
### Step 3: Plan Operations\r
- Apply operations in logical order\r
- Consider quality vs file size tradeoffs\r
- Validate input requirements\r
\r
### Step 4: Execute and Validate\r
- Run the script with appropriate options\r
- Check output quality\r
- Verify file sizes and formats\r
\r
## Common Patterns\r
\r
### Pattern 1: Web Image Optimization\r
```bash\r
# Resize and optimize for web\r
python scripts/image_editor.py large.jpg web.jpg \\r
    --width 1200 \\r
    --quality 85 \\r
    --format JPEG\r
```\r
\r
### Pattern 2: Create Image Gallery\r
```bash\r
# Generate thumbnails\r
python scripts/batch_processor.py ./originals ./gallery \\r
    --thumbnail 400 400 \\r
    --format JPEG \\r
    --quality 90\r
```\r
\r
### Pattern 3: Brand Images with Watermark\r
```bash\r
# Add company logo\r
python scripts/watermark.py product.jpg branded.jpg \\r
    --image company_logo.png \\r
    --position bottom-right \\r
    --scale 0.15 \\r
    --opacity 180\r
```\r
\r
### Pattern 4: Batch Format Conversion\r
```bash\r
# Convert PNG to JPEG\r
python scripts/batch_processor.py ./pngs ./jpegs \\r
    --format JPEG \\r
    --quality 95\r
```\r
\r
## Dependencies\r
\r
```bash\r
pip install Pillow\r
```\r
\r
## Tips for Effective Use\r
\r
1. **Preserve originals**: Never overwrite source images\r
2. **Use appropriate formats**: JPEG for photos, PNG for graphics\r
3. **Optimize quality**: Balance quality and file size\r
4. **Batch operations**: Use batch processor for multiple images\r
5. **Check references**: Consult reference docs for advanced operations\r
6. **Validate inputs**: Check image format and size before processing\r
7. **Test first**: Try operations on one image before batch processing\r
\r
## Limitations\r
\r
- Limited to 2D image processing (no video)\r
- Some EXIF data may not be preserved in all formats\r
- Font availability may vary by system\r
- Very large images may require significant memory\r
- Advanced photo editing (layers, masks) requires specialized tools\r
\r
## Troubleshooting\r
\r
**Import errors**: Ensure Pillow is installed (`pip install Pillow`)\r
**Font not found**: Watermark script falls back to default font\r
**Memory errors**: Process large images in smaller batches\r
**Format errors**: Check input image format compatibility\r
**RGBA to JPEG**: Script automatically handles RGBA→RGB conversion\r
\r
For detailed operations and troubleshooting, always refer to `references/common_operations.md` and `references/best_practices.md`.\r