image-enhancement-suite

name	image-enhancement-suite
description	Batch image processing: resize, crop, watermark, color correction, format conversion, compression. Quality presets for web, print, and social media.

Image Enhancement Suite

Professional image processing toolkit that handles common image tasks without requiring Photoshop or similar software. Process single images or entire folders with consistent, high-quality results.

Core Capabilities

• Resize & Crop: Smart resizing with aspect ratio preservation, crop to specific dimensions
• Watermark: Add text or image watermarks with positioning and opacity control
• Color Correction: Brightness, contrast, saturation, sharpness adjustments
• Format Conversion: Convert between PNG, JPEG, WebP, BMP, TIFF, GIF
• Compression: Optimize file size with quality presets
• Filters: Apply preset filters (grayscale, sepia, vintage, blur, sharpen)
• Batch Processing: Process multiple images with same settings

Quick Start

from scripts.image_enhancer import ImageEnhancer

# Single image processing
enhancer = ImageEnhancer("photo.jpg")
enhancer.resize(width=800).sharpen(0.5).save("photo_enhanced.jpg")

# Batch processing
from scripts.image_enhancer import batch_process
batch_process(
    input_dir="raw_photos/",
    output_dir="processed/",
    operations=[
        ("resize", {"width": 1200}),
        ("watermark", {"text": "© 2024"}),
        ("compress", {"quality": 85})
    ]
)

Operations Reference

Resize

# By width (maintain aspect ratio)
enhancer.resize(width=800)

# By height (maintain aspect ratio)
enhancer.resize(height=600)

# Exact dimensions (may distort)
enhancer.resize(width=800, height=600, maintain_aspect=False)

# Fit within bounds
enhancer.resize(max_width=1200, max_height=800)

# Scale by percentage
enhancer.resize(scale=0.5)  # 50%

Crop

# Crop to specific dimensions from center
enhancer.crop(width=800, height=600)

# Crop with position
enhancer.crop(width=800, height=600, position='top-left')
# Positions: 'center', 'top-left', 'top-right', 'bottom-left', 'bottom-right'

# Crop to exact coordinates (left, top, right, bottom)
enhancer.crop(box=(100, 100, 900, 700))

# Smart crop (content-aware)
enhancer.smart_crop(width=800, height=600)

Watermark

# Text watermark
enhancer.watermark(
    text="© 2024 Company",
    position='bottom-right',
    opacity=0.5,
    font_size=24,
    color='white'
)

# Image watermark
enhancer.watermark(
    image="logo.png",
    position='bottom-right',
    opacity=0.3,
    scale=0.2  # 20% of main image width
)

# Tiled watermark
enhancer.watermark(
    text="DRAFT",
    tiled=True,
    opacity=0.1,
    rotation=45
)

Color Adjustments

# Individual adjustments (range: -1.0 to 1.0, 0 = no change)
enhancer.brightness(0.2)    # +20% brightness
enhancer.contrast(0.3)      # +30% contrast
enhancer.saturation(-0.2)   # -20% saturation
enhancer.sharpen(0.5)       # Sharpen

# Combined adjustment
enhancer.adjust(
    brightness=0.1,
    contrast=0.2,
    saturation=0.1,
    sharpen=0.3
)

# Auto-enhance
enhancer.auto_enhance()

Filters

# Apply preset filters
enhancer.filter('grayscale')
enhancer.filter('sepia')
enhancer.filter('vintage')
enhancer.filter('blur')
enhancer.filter('sharpen')
enhancer.filter('edge_enhance')
enhancer.filter('emboss')

# Custom blur
enhancer.blur(radius=2)

# Gaussian blur
enhancer.gaussian_blur(radius=3)

Format Conversion

# Convert to different format
enhancer.save("output.png")   # Auto-detect from extension
enhancer.save("output.webp")
enhancer.save("output.jpg")

# Explicit format
enhancer.convert('PNG').save("output.png")
enhancer.convert('WEBP').save("output.webp")

Compression

# JPEG quality (1-100)
enhancer.compress(quality=85).save("compressed.jpg")

# WebP with quality
enhancer.save("output.webp", quality=80)

# PNG optimization
enhancer.optimize_png().save("optimized.png")

# Target file size
enhancer.compress_to_size(max_kb=500).save("sized.jpg")

Quality Presets

# Web optimized
enhancer.preset('web')  # 1200px max, 85 quality, WebP

# Social media
enhancer.preset('instagram')  # 1080x1080, optimized
enhancer.preset('twitter')    # 1200x675
enhancer.preset('facebook')   # 1200x630
enhancer.preset('linkedin')   # 1200x627

# Print quality
enhancer.preset('print_4x6')   # 1800x1200, 300dpi
enhancer.preset('print_8x10')  # 3000x2400, 300dpi

# Thumbnail
enhancer.preset('thumbnail')   # 150x150, center crop
enhancer.preset('preview')     # 400px max, 70 quality

Batch Processing

Process Directory

from scripts.image_enhancer import batch_process

# Apply same operations to all images
results = batch_process(
    input_dir="photos/",
    output_dir="processed/",
    operations=[
        ("resize", {"width": 1200}),
        ("watermark", {"text": "© 2024", "position": "bottom-right"}),
        ("compress", {"quality": 85})
    ],
    formats=['jpg', 'png'],  # Only process these formats
    recursive=True           # Include subdirectories
)

print(f"Processed: {results['success']} images")
print(f"Failed: {results['failed']} images")

Rename Pattern

batch_process(
    input_dir="photos/",
    output_dir="processed/",
    operations=[("resize", {"width": 800})],
    rename_pattern="{name}_web_{index:03d}"
)
# Output: photo_web_001.jpg, photo_web_002.jpg, ...

Generate Multiple Sizes

from scripts.image_enhancer import generate_sizes

# Create multiple sizes from one image
sizes = generate_sizes(
    "hero.jpg",
    output_dir="responsive/",
    widths=[320, 640, 1024, 1920],
    format='webp'
)
# Output: hero_320.webp, hero_640.webp, etc.

Icon Generation

from scripts.image_enhancer import generate_icons

# Generate favicon and app icons from single image
icons = generate_icons(
    "logo.png",
    output_dir="icons/",
    sizes=[16, 32, 48, 64, 128, 256, 512]
)

Metadata Operations

# Read EXIF data
metadata = enhancer.get_metadata()
print(metadata['camera'])
print(metadata['date_taken'])
print(metadata['gps'])

# Strip metadata (privacy)
enhancer.strip_metadata()

# Preserve specific metadata
enhancer.strip_metadata(keep=['copyright', 'artist'])

CLI Usage

# Single file
python image_enhancer.py input.jpg -o output.jpg --resize 800 --quality 85

# Batch processing
python image_enhancer.py photos/ -o processed/ --resize 1200 --watermark "© 2024"

# Apply preset
python image_enhancer.py photo.jpg --preset instagram

# Generate icons
python image_enhancer.py logo.png --icons icons/

Supported Formats

Format	Read	Write	Notes
JPEG	Yes	Yes	Lossy, best for photos
PNG	Yes	Yes	Lossless, supports transparency
WebP	Yes	Yes	Modern format, good compression
GIF	Yes	Yes	Animation support
BMP	Yes	Yes	Uncompressed
TIFF	Yes	Yes	High quality, large files
ICO	Yes	Yes	Icon format
HEIC	Yes	No	iPhone photos (read only)

Error Handling

from scripts.image_enhancer import ImageEnhancer, ImageError

try:
    enhancer = ImageEnhancer("photo.jpg")
    enhancer.resize(width=800).save("output.jpg")
except ImageError as e:
    print(f"Image error: {e}")
except FileNotFoundError:
    print("Image file not found")

Configuration

enhancer = ImageEnhancer("photo.jpg")

# Global settings
enhancer.config.update({
    'default_quality': 85,
    'default_format': 'webp',
    'preserve_metadata': False,
    'color_profile': 'sRGB',
    'dpi': 72
})

Performance Tips

1. Large batches: Use batch_process() with parallel=True
2. Memory: Process one image at a time for very large files
3. Speed: WebP encoding is slower but produces smaller files
4. Quality: Start at 85 quality, reduce if file size is critical

Dependencies

pillow>=10.0.0
opencv-python>=4.8.0
numpy>=1.24.0