Image Resizer and Thumbnail Generator (python, written by Claude Code)

Claude Code wrote this python project from the task below. It installed and ran on a clean Ubuntu 22.04 machine as written.

Task given to the agent:

TASK: Image Resizer and Thumbnail Generator

Write a program that resizes images and generates thumbnails at multiple configurable sizes, supporting different resampling algorithms, crop modes, and batch processing of entire directories.

FUNCTIONAL REQUIREMENTS:
- Accept an image file path as a command-line argument
- Resize to exact dimensions via --size flag (WxH format, e.g., --size 1920x1080)
- Resize by percentage via --scale flag (e.g., --scale 50 for 50% of original size)
- Support multiple resampling algorithms selectable via --algorithm flag: nearest neighbor, bilinear, bicubic, and Lanczos
- Support three resize modes via --mode flag: fit (scale within bounds preserving aspect ratio), fill (scale to cover bounds then center-crop), and stretch (distort to exact dimensions)
- Generate a set of standard thumbnails via --thumbnails flag: small (150x150), medium (300x300), large (600x600), all center-cropped squares
- Support custom thumbnail sizes via --thumb-sizes flag (comma-separated, e.g., --thumb-sizes 64x64,128x128,256x256)
- Add optional padding/border around resized images via --padding flag (pixels) and --border-color flag (hex color)
- Support batch processing of all images in a directory via --batch flag, with --recursive to include subdirectories
- Print processing details to console: original dimensions, new dimensions, algorithm used, output file path, processing time per image
- Save resized images to a directory specified by --output flag (default: resized/ subdirectory)
- If no input is given, generate a sample 2000x1500 test image with fine details (grid lines, text at various sizes, gradient bands), then resize it using each algorithm and each mode to demonstrate the visual differences
- Handle errors: invalid dimensions, unsupported image formats, memory limits for very large images

Create a complete Python project for a clean Ubuntu 22.04 machine with only Python 3.10+ installed. Include:
- Source code
- requirements.txt with all dependencies (direct and transitive) pinned to exact versions
- README.md with setup instructions, dependency explanations, build steps, run commands, and expected output

[]

# Image Resizer and Thumbnail Generator (Python / Pillow)

A command-line tool for resizing images and generating thumbnails using multiple
resampling algorithms, crop modes, and batch processing.

## Dependencies

- **Pillow 10.2.0** - Image processing library for opening, manipulating, and saving images.
- **click 8.1.7** - CLI framework for building well-structured command-line interfaces.

## Installation

```bash
pip install -r requirements.txt
```

## Usage

### Resize a single image

```bash
python resizer.py resize input.jpg output.jpg -w 800 -h 600 -a lanczos
```

### Generate a thumbnail

```bash
python resizer.py thumbnail input.jpg thumb.jpg -s 150
```

### Batch resize a directory

```bash
python resizer.py batch ./input_dir ./output_dir -w 1024 -h 768 -a bicubic
```

### Batch generate thumbnails

```bash
python resizer.py batch-thumbnails ./input_dir ./thumbs -s 200
```

## Resampling Algorithms

| Algorithm  | Description                        |
|------------|------------------------------------|
| `nearest`  | Nearest-neighbor (fastest)         |
| `bilinear` | Bilinear interpolation             |
| `bicubic`  | Bicubic interpolation              |
| `lanczos`  | Lanczos resampling (best quality)  |

## Crop Modes

| Mode           | Description                              |
|----------------|------------------------------------------|
| `center`       | Crop from the center of the image        |
| `top-left`     | Crop from the top-left corner            |
| `top-right`    | Crop from the top-right corner           |
| `bottom-left`  | Crop from the bottom-left corner         |
| `bottom-right` | Crop from the bottom-right corner        |
| `smart`        | Center-weighted with upper-third bias    |

## Supported Formats

JPEG, PNG, BMP, TIFF, WebP, GIF

Pillow==10.2.0
click==8.1.7

#!/usr/bin/env python3
"""
Image Resizer and Thumbnail Generator

Resizes images using multiple algorithms (bilinear, bicubic, Lanczos),
supports various crop modes, and batch processing of entire directories.

Dependencies: Pillow 10.2.0, click 8.1.7
"""

import os
import sys
from pathlib import Path
from typing import Optional, Tuple, List

import click
from PIL import Image, ImageFilter

# Mapping of algorithm names to Pillow resampling constants
ALGORITHMS = {
    "bilinear": Image.Resampling.BILINEAR,
    "bicubic": Image.Resampling.BICUBIC,
    "lanczos": Image.Resampling.LANCZOS,
    "nearest": Image.Resampling.NEAREST,
}

SUPPORTED_EXTENSIONS = {".jpg", ".jpeg", ".png", ".bmp", ".tiff", ".tif", ".webp", ".gif"}

CROP_MODES = ["center", "top-left", "top-right", "bottom-left", "bottom-right", "smart"]


def get_supported_images(directory: str) -> List[Path]:
    """Collect all supported image files from a directory."""
    dir_path = Path(directory)
    images = []
    for ext in SUPPORTED_EXTENSIONS:
        images.extend(dir_path.glob(f"*{ext}"))
        images.extend(dir_path.glob(f"*{ext.upper()}"))
    return sorted(set(images))


def calculate_crop_box(
    img_width: int,
    img_height: int,
    target_width: int,
    target_height: int,
    crop_mode: str,
) -> Tuple[int, int, int, int]:
    """
    Calculate the crop box (left, upper, right, lower) for a given crop mode.
    The crop box is sized to target_width x target_height within the image.
    """
    if crop_mode == "center":
        left = (img_width - target_width) // 2
        upper = (img_height - target_height) // 2
    elif crop_mode == "top-left":
        left = 0
        upper = 0
    elif crop_mode == "top-right":
        left = img_width - target_width
        upper = 0
    elif crop_mode == "bottom-left":
        left = 0
        upper = img_height - target_height
    elif crop_mode == "bottom-right":
        left = img_width - target_width
        upper = img_height - target_height
    elif crop_mode == "smart":
        # Smart crop: center-weighted with slight bias toward the upper third
        left = (img_width - target_width) // 2
        upper = max(0, (img_height - target_height) // 3)
    else:
        raise ValueError(f"Unknown crop mode: {crop_mode}")

    left = max(0, left)
    upper = max(0, upper)
    right = left + target_width
    lower = upper + target_height

    return (left, upper, right, lower)


def resize_image(
    input_path: str,
    output_path: str,
    width: int,
    height: int,
    algorithm: str = "lanczos",
    crop_mode: Optional[str] = None,
    maintain_aspect: bool = True,
    quality: int = 90,
) -> dict:
    """
    Resize a single image with the specified parameters.

    Args:
        input_path: Path to the source image.
        output_path: Path to save the resized image.
        width: Target width in pixels.
        height: Target height in pixels.
        algorithm: Resampling algorithm to use.
        crop_mode: If set, crop to exact dimensions using this mode.
        maintain_aspect: Whether to maintain aspect ratio (ignored if crop_mode is set).
        quality: JPEG/WebP output quality (1-100).

    Returns:
        Dictionary with original and new dimensions and file sizes.
    """
    if algorithm not in ALGORITHMS:
        raise ValueError(
            f"Unsupported algorithm '{algorithm}'. Choose from: {list(ALGORITHMS.keys())}"
        )

    img = Image.open(input_path)
    original_size = os.path.getsize(input_path)
    orig_width, orig_height = img.size

    # Convert RGBA to RGB if saving as JPEG
    output_ext = Path(output_path).suffix.lower()
    if output_ext in (".jpg", ".jpeg") and img.mode == "RGBA":
        background = Image.new("RGB", img.size, (255, 255, 255))
        background.paste(img, mask=img.split()[3])
        img = background

    resampler = ALGORITHMS[algorithm]

    if crop_mode:
        # Crop mode: first resize so the image covers the target area, then crop
        scale_w = width / orig_width
        scale_h = height / orig_height
        scale = max(scale_w, scale_h)

        interim_w = max(width, int(orig_width * scale))
        interim_h = max(height, int(orig_height * scale))

        img = img.resize((interim_w, interim_h), resampler)
        crop_box = calculate_crop_box(interim_w, interim_h, width, height, crop_mode)
        img = img.crop(crop_box)
    elif maintain_aspect:
        # Maintain aspect ratio: fit within width x height
        img.thumbnail((width, height), resampler)
    else:
        # Stretch to exact dimensions
        img = img.resize((width, height), resampler)

    # Ensure output directory exists
    os.makedirs(os.path.dirname(output_path) or ".", exist_ok=True)

    # Save with appropriate options
    save_kwargs = {}
    if output_ext in (".jpg", ".jpeg"):
        save_kwargs["quality"] = quality
        save_kwargs["optimize"] = True
    elif output_ext == ".png":
        save_kwargs["optimize"] = True
    elif output_ext == ".webp":
        save_kwargs["quality"] = quality

    img.save(output_path, **save_kwargs)
    new_size = os.path.getsize(output_path)

    return {
        "input": input_path,
        "output": output_path,
        "original_dimensions": (orig_width, orig_height),
        "new_dimensions": img.size,
        "original_size": original_size,
        "new_size": new_size,
        "algorithm": algorithm,
    }


def generate_thumbnail(
    input_path: str,
    output_path: str,
    size: int = 150,
    algorithm: str = "lanczos",
    quality: int = 85,
) -> dict:
    """Generate a square thumbnail from an image."""
    return resize_image(
        input_path=input_path,
        output_path=output_path,
        width=size,
        height=size,
        algorithm=algorithm,
        crop_mode="center",
        quality=quality,
    )


def format_size(size_bytes: int) -> str:
    """Format file size in human-readable form."""
    for unit in ("B", "KB", "MB", "GB"):
        if size_bytes < 1024.0:
            return f"{size_bytes:.1f} {unit}"
        size_bytes /= 1024.0
    return f"{size_bytes:.1f} TB"


@click.group()
@click.version_option(version="1.0.0")
def cli():
    """Image Resizer and Thumbnail Generator.

    Resize images using bilinear, bicubic, or Lanczos algorithms.
    Supports single file and batch processing with optional cropping.
    """
    pass


@cli.command()
@click.argument("input_path", type=click.Path(exists=True))
@click.argument("output_path", type=click.Path())
@click.option("-w", "--width", type=int, required=True, help="Target width in pixels.")
@click.option("-h", "--height", type=int, required=True, help="Target height in pixels.")
@click.option(
    "-a",
    "--algorithm",
    type=click.Choice(list(ALGORITHMS.keys()), case_sensitive=False),
    default="lanczos",
    help="Resampling algorithm.",
)
@click.option(
    "-c",
    "--crop",
    type=click.Choice(CROP_MODES, case_sensitive=False),
    default=None,
    help="Crop mode for exact dimensions.",
)
@click.option("--no-aspect", is_flag=True, help="Stretch to exact dimensions (ignore aspect ratio).")
@click.option("-q", "--quality", type=click.IntRange(1, 100), default=90, help="Output quality (1-100).")
def resize(input_path, output_path, width, height, algorithm, crop, no_aspect, quality):
    """Resize a single image."""
    try:
        result = resize_image(
            input_path=input_path,
            output_path=output_path,
            width=width,
            height=height,
            algorithm=algorithm,
            crop_mode=crop,
            maintain_aspect=not no_aspect,
            quality=quality,
        )
        click.echo(f"Resized: {result['input']}")
        click.echo(
            f"  {result['original_dimensions'][0]}x{result['original_dimensions'][1]} -> "
            f"{result['new_dimensions'][0]}x{result['new_dimensions'][1]}"
        )
        click.echo(
            f"  Size: {format_size(result['original_size'])} -> {format_size(result['new_size'])}"
        )
        click.echo(f"  Algorithm: {result['algorithm']}")
        click.echo(f"  Output: {result['output']}")
    except Exception as e:
        click.echo(f"Error: {e}", err=True)
        sys.exit(1)


@cli.command()
@click.argument("input_path", type=click.Path(exists=True))
@click.argument("output_path", type=click.Path())
@click.option("-s", "--size", type=int, default=150, help="Thumbnail size (square, default 150).")
@click.option(
    "-a",
    "--algorithm",
    type=click.Choice(list(ALGORITHMS.keys()), case_sensitive=False),
    default="lanczos",
    help="Resampling algorithm.",
)
@click.option("-q", "--quality", type=click.IntRange(1, 100), default=85, help="Output quality (1-100).")
def thumbnail(input_path, output_path, size, algorithm, quality):
    """Generate a square thumbnail from an image."""
    try:
        result = generate_thumbnail(
            input_path=input_path,
            output_path=output_path,
            size=size,
            algorithm=algorithm,
            quality=quality,
        )
        click.echo(f"Thumbnail created: {result['output']}")
        click.echo(f"  Size: {result['new_dimensions'][0]}x{result['new_dimensions'][1]}")
    except Exception as e:
        click.echo(f"Error: {e}", err=True)
        sys.exit(1)


@cli.command()
@click.argument("input_dir", type=click.Path(exists=True, file_okay=False))
@click.argument("output_dir", type=click.Path())
@click.option("-w", "--width", type=int, required=True, help="Target width in pixels.")
@click.option("-h", "--height", type=int, required=True, help="Target height in pixels.")
@click.option(
    "-a",
    "--algorithm",
    type=click.Choice(list(ALGORITHMS.keys()), case_sensitive=False),
    default="lanczos",
    help="Resampling algorithm.",
)
@click.option(
    "-c",
    "--crop",
    type=click.Choice(CROP_MODES, case_sensitive=False),
    default=None,
    help="Crop mode for exact dimensions.",
)
@click.option("--no-aspect", is_flag=True, help="Stretch to exact dimensions.")
@click.option("-q", "--quality", type=click.IntRange(1, 100), default=90, help="Output quality (1-100).")
@click.option(
    "-f",
    "--format",
    "out_format",
    type=click.Choice(["jpg", "png", "webp"], case_sensitive=False),
    default=None,
    help="Convert output to this format.",
)
@click.option("-r", "--recursive", is_flag=True, help="Process subdirectories recursively.")
def batch(input_dir, output_dir, width, height, algorithm, crop, no_aspect, quality, out_format, recursive):
    """Batch resize all images in a directory."""
    input_path = Path(input_dir)
    output_path = Path(output_dir)

    if recursive:
        images = []
        for ext in SUPPORTED_EXTENSIONS:
            images.extend(input_path.rglob(f"*{ext}"))
            images.extend(input_path.rglob(f"*{ext.upper()}"))
        images = sorted(set(images))
    else:
        images = get_supported_images(input_dir)

    if not images:
        click.echo("No supported images found in the input directory.")
        return

    click.echo(f"Found {len(images)} image(s) to process.")

    success_count = 0
    error_count = 0

    with click.progressbar(images, label="Processing") as progress:
        for img_path in progress:
            try:
                # Preserve subdirectory structure for recursive mode
                relative = img_path.relative_to(input_path)
                if out_format:
                    out_name = relative.with_suffix(f".{out_format}")
                else:
                    out_name = relative

                out_file = output_path / out_name

                resize_image(
                    input_path=str(img_path),
                    output_path=str(out_file),
                    width=width,
                    height=height,
                    algorithm=algorithm,
                    crop_mode=crop,
                    maintain_aspect=not no_aspect,
                    quality=quality,
                )
                success_count += 1
            except Exception as e:
                error_count += 1
                click.echo(f"\n  Error processing {img_path.name}: {e}", err=True)

    click.echo(f"\nDone! {success_count} succeeded, {error_count} failed.")


@cli.command()
@click.argument("input_dir", type=click.Path(exists=True, file_okay=False))
@click.argument("output_dir", type=click.Path())
@click.option("-s", "--size", type=int, default=150, help="Thumbnail size (square, default 150).")
@click.option(
    "-a",
    "--algorithm",
    type=click.Choice(list(ALGORITHMS.keys()), case_sensitive=False),
    default="lanczos",
    help="Resampling algorithm.",
)
@click.option("-q", "--quality", type=click.IntRange(1, 100), default=85, help="Output quality.")
def batch_thumbnails(input_dir, output_dir, size, algorithm, quality):
    """Generate thumbnails for all images in a directory."""
    images = get_supported_images(input_dir)
    output_path = Path(output_dir)

    if not images:
        click.echo("No supported images found.")
        return

    click.echo(f"Generating thumbnails for {len(images)} image(s)...")

    success_count = 0
    for img_path in images:
        try:
            out_file = output_path / f"thumb_{img_path.name}"
            generate_thumbnail(
                input_path=str(img_path),
                output_path=str(out_file),
                size=size,
                algorithm=algorithm,
                quality=quality,
            )
            success_count += 1
        except Exception as e:
            click.echo(f"  Error: {img_path.name}: {e}", err=True)

    click.echo(f"Generated {success_count} thumbnail(s) in {output_dir}")


if __name__ == "__main__":
    cli()