thumbnail-generator

Thumbnail Generator

Create optimized thumbnails with smart cropping, multiple output sizes, and batch processing.

Features

• Smart Cropping: Center, face-aware, or edge-detection based
• Multiple Sizes: Generate multiple thumbnail sizes at once
• Presets: Web, social media, app icon presets
• Batch Processing: Process entire folders
• Quality Control: Optimize file size vs quality
• Formats: JPEG, PNG, WebP output

Quick Start

from thumbnail_gen import ThumbnailGenerator

gen = ThumbnailGenerator()
gen.load("photo.jpg")

# Create single thumbnail
gen.resize(200, 200).save("thumb.jpg")

# Create multiple sizes
gen.generate_sizes([
    (100, 100),
    (200, 200),
    (400, 400)
], output_dir="./thumbs/")

CLI Usage

# Single thumbnail
python thumbnail_gen.py --input photo.jpg --size 200x200 --output thumb.jpg

# Multiple sizes
python thumbnail_gen.py --input photo.jpg --sizes 100x100,200x200,400x400 --output ./thumbs/

# Batch process folder
python thumbnail_gen.py --input ./photos/ --size 200x200 --output ./thumbs/

# Use preset
python thumbnail_gen.py --input photo.jpg --preset social --output ./thumbs/

# Smart crop
python thumbnail_gen.py --input photo.jpg --size 200x200 --crop smart --output thumb.jpg

# WebP output
python thumbnail_gen.py --input photo.jpg --size 200x200 --format webp --output thumb.webp

API Reference

ThumbnailGenerator Class

class ThumbnailGenerator:
    def __init__(self)

    # Loading
    def load(self, filepath: str) -> 'ThumbnailGenerator'

    # Resizing
    def resize(self, width: int, height: int,
              crop: str = "fit") -> 'ThumbnailGenerator'
    def resize_width(self, width: int) -> 'ThumbnailGenerator'
    def resize_height(self, height: int) -> 'ThumbnailGenerator'

    # Cropping
    def crop_center(self, width: int, height: int) -> 'ThumbnailGenerator'
    def crop_smart(self, width: int, height: int) -> 'ThumbnailGenerator'
    def crop_position(self, width: int, height: int,
                     position: str = "center") -> 'ThumbnailGenerator'

    # Output
    def save(self, output: str, quality: int = 85,
            format: str = None) -> str
    def to_bytes(self, format: str = "JPEG", quality: int = 85) -> bytes

    # Batch operations
    def generate_sizes(self, sizes: list, output_dir: str,
                      prefix: str = None) -> list
    def process_folder(self, input_dir: str, output_dir: str,
                      width: int, height: int, recursive: bool = False) -> list

    # Presets
    def apply_preset(self, preset: str, output_dir: str) -> list

Resize Modes

Fit (Default)

Resize to fit within bounds, maintaining aspect ratio:

gen.resize(200, 200, crop="fit")
# Result: Image fits within 200x200, may have letterboxing

Fill

Resize to fill bounds, cropping excess:

gen.resize(200, 200, crop="fill")
# Result: Exactly 200x200, some content may be cropped

Stretch

Resize to exact dimensions (distorts aspect ratio):

gen.resize(200, 200, crop="stretch")
# Result: Exactly 200x200, may be distorted

Smart Cropping

Automatically detect the most interesting part of the image:

gen.load("photo.jpg")
gen.crop_smart(200, 200)
gen.save("thumb.jpg")

Uses edge detection to find areas of interest.

Crop Positions

# Predefined positions
gen.crop_position(200, 200, position="center")
gen.crop_position(200, 200, position="top")
gen.crop_position(200, 200, position="bottom")
gen.crop_position(200, 200, position="left")
gen.crop_position(200, 200, position="right")
gen.crop_position(200, 200, position="top-left")
gen.crop_position(200, 200, position="top-right")
gen.crop_position(200, 200, position="bottom-left")
gen.crop_position(200, 200, position="bottom-right")

Presets

Web Preset

gen.apply_preset("web", "./output/")

# Generates:
# - thumb_small.jpg (150x150)
# - thumb_medium.jpg (300x300)
# - thumb_large.jpg (600x600)

Social Media Preset

gen.apply_preset("social", "./output/")

# Generates:
# - instagram_square.jpg (1080x1080)
# - instagram_portrait.jpg (1080x1350)
# - instagram_landscape.jpg (1080x566)
# - twitter.jpg (1200x675)
# - facebook.jpg (1200x630)
# - linkedin.jpg (1200x627)

App Icons Preset

gen.apply_preset("icons", "./output/")

# Generates:
# - icon_16.png (16x16)
# - icon_32.png (32x32)
# - icon_48.png (48x48)
# - icon_64.png (64x64)
# - icon_128.png (128x128)
# - icon_256.png (256x256)
# - icon_512.png (512x512)

Favicon Preset

gen.apply_preset("favicon", "./output/")

# Generates:
# - favicon_16.png (16x16)
# - favicon_32.png (32x32)
# - apple_touch.png (180x180)
# - android_192.png (192x192)
# - android_512.png (512x512)

Multiple Sizes

Generate multiple thumbnail sizes at once:

gen.load("photo.jpg")
files = gen.generate_sizes(
    sizes=[(100, 100), (200, 200), (400, 400), (800, 800)],
    output_dir="./thumbs/",
    prefix="product"
)

# Creates:
# - product_100x100.jpg
# - product_200x200.jpg
# - product_400x400.jpg
# - product_800x800.jpg

Batch Processing

Process entire folders:

gen = ThumbnailGenerator()
results = gen.process_folder(
    input_dir="./photos/",
    output_dir="./thumbnails/",
    width=200,
    height=200,
    recursive=True
)

print(f"Processed {len(results)} images")

Quality and Format

Quality Settings

# High quality (larger file)
gen.save("thumb.jpg", quality=95)

# Balanced (default)
gen.save("thumb.jpg", quality=85)

# Web optimized (smaller file)
gen.save("thumb.jpg", quality=70)

Output Formats

# JPEG (best for photos)
gen.save("thumb.jpg", format="JPEG")

# PNG (best for graphics/transparency)
gen.save("thumb.png", format="PNG")

# WebP (modern, smaller files)
gen.save("thumb.webp", format="WEBP", quality=80)

Output Structure

result = gen.generate_sizes(
    sizes=[(100, 100), (200, 200)],
    output_dir="./thumbs/"
)

# Returns:
[
    {
        "size": "100x100",
        "path": "./thumbs/image_100x100.jpg",
        "file_size": 5432
    },
    {
        "size": "200x200",
        "path": "./thumbs/image_200x200.jpg",
        "file_size": 15234
    }
]

Example Workflows

E-commerce Product Images

gen = ThumbnailGenerator()
gen.load("product.jpg")

# Generate product thumbnails
gen.generate_sizes(
    sizes=[
        (80, 80),    # Cart thumbnail
        (200, 200),  # Category listing
        (400, 400),  # Product page
        (800, 800)   # Zoom view
    ],
    output_dir="./product_images/",
    prefix="sku_12345"
)

Gallery Thumbnails

gen = ThumbnailGenerator()
results = gen.process_folder(
    input_dir="./gallery/",
    output_dir="./gallery/thumbs/",
    width=300,
    height=200
)

Social Media Batch

gen = ThumbnailGenerator()

for image in Path("./photos/").glob("*.jpg"):
    gen.load(str(image))
    gen.apply_preset("social", f"./social/{image.stem}/")

Dependencies

• pillow>=10.0.0
• numpy>=1.24.0