name: thumbnail-generator description: Generate thumbnails from images with smart cropping, multiple sizes, and batch processing. Ideal for web galleries, social media, and app icons.

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

thumbnail-generator

$ インストール