Image Format Converter (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 Format Converter

Write a program that converts images between common formats (PNG, JPEG, BMP, TIFF, WebP) with configurable quality settings, preserving metadata where possible.

FUNCTIONAL REQUIREMENTS:
- Accept an image file path and target format as command-line arguments
- Support conversions between: PNG, JPEG, BMP, TIFF, and WebP formats
- Support a --quality flag for lossy formats (JPEG, WebP) with a value from 1-100 (default: 85)
- Support a --resize flag to resize during conversion using WxH syntax (e.g., --resize 800x600), preserving aspect ratio by default
- Support --maintain-aspect flag (default true) to control whether resizing preserves the original aspect ratio by fitting within the specified dimensions
- Preserve EXIF metadata during conversion where the target format supports it, with a --strip-metadata flag to optionally remove it
- Support alpha channel handling: when converting from formats with transparency (PNG, WebP) to formats without (JPEG, BMP), use a configurable background color via --background flag (default: white)
- Support batch conversion of all images in a directory via --batch flag, optionally filtering by input format with --filter flag
- Print conversion details to console: input format, output format, original dimensions, new dimensions, file size before and after, compression ratio
- Save the converted image to a path specified by --output flag (default: same name with new extension)
- If no input is given, generate a sample 800x600 PNG image with gradients, text, and transparency, then convert it to all other supported formats and display a comparison table
- Handle errors: unsupported formats, corrupted images, insufficient disk space, invalid resize dimensions

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 Format Converter using Pillow.

Converts between PNG, JPEG, BMP, TIFF, and WebP formats with quality settings,
resize capabilities, and metadata preservation.
"""

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

from PIL import Image, ExifTags
from PIL.ExifTags import TAGS


SUPPORTED_FORMATS = {
    ".png": "PNG",
    ".jpg": "JPEG",
    ".jpeg": "JPEG",
    ".bmp": "BMP",
    ".tiff": "TIFF",
    ".tif": "TIFF",
    ".webp": "WEBP",
}


def get_format_from_extension(filepath: str) -> str:
    """Determine the Pillow format string from file extension."""
    ext = Path(filepath).suffix.lower()
    if ext not in SUPPORTED_FORMATS:
        raise ValueError(
            f"Unsupported format: '{ext}'. Supported: {list(SUPPORTED_FORMATS.keys())}"
        )
    return SUPPORTED_FORMATS[ext]


def extract_metadata(image: Image.Image) -> dict:
    """Extract EXIF metadata from an image."""
    metadata = {}
    exif_data = image.getexif()
    if exif_data:
        for tag_id, value in exif_data.items():
            tag_name = TAGS.get(tag_id, tag_id)
            try:
                metadata[tag_name] = str(value)
            except Exception:
                metadata[tag_name] = repr(value)
    return metadata


def print_metadata(metadata: dict) -> None:
    """Print image metadata in a readable format."""
    if not metadata:
        print("  No EXIF metadata found.")
        return
    for key, value in metadata.items():
        print(f"  {key}: {value}")


def convert_image(
    input_path: str,
    output_path: str,
    quality: int = 85,
    resize: Optional[Tuple[int, int]] = None,
    preserve_metadata: bool = True,
    verbose: bool = False,
) -> str:
    """
    Convert an image from one format to another.

    Args:
        input_path: Path to the source image file.
        output_path: Path for the output image file.
        quality: Quality setting for lossy formats (1-100). Default is 85.
        resize: Optional (width, height) tuple for resizing.
        preserve_metadata: Whether to preserve EXIF metadata. Default is True.
        verbose: Whether to print detailed information. Default is False.

    Returns:
        The absolute path to the converted output file.

    Raises:
        FileNotFoundError: If the input file does not exist.
        ValueError: If an unsupported format is specified.
    """
    if not os.path.isfile(input_path):
        raise FileNotFoundError(f"Input file not found: {input_path}")

    output_format = get_format_from_extension(output_path)

    if verbose:
        print(f"Opening: {input_path}")

    image = Image.open(input_path)
    original_size = image.size

    # Extract metadata before any transformations
    exif_data = image.getexif() if preserve_metadata else None
    metadata_dict = extract_metadata(image) if verbose else {}

    if verbose:
        print(f"Original size: {original_size[0]}x{original_size[1]}")
        print(f"Original mode: {image.mode}")
        print("Original metadata:")
        print_metadata(metadata_dict)

    # Resize if requested
    if resize:
        width, height = resize
        if width <= 0 or height <= 0:
            raise ValueError("Resize dimensions must be positive integers.")
        image = image.resize((width, height), Image.LANCZOS)
        if verbose:
            print(f"Resized to: {width}x{height}")

    # Handle mode conversion for format compatibility
    if output_format == "JPEG" and image.mode in ("RGBA", "P", "LA"):
        # JPEG does not support transparency; composite onto white background
        background = Image.new("RGB", image.size, (255, 255, 255))
        if image.mode == "P":
            image = image.convert("RGBA")
        background.paste(image, mask=image.split()[-1])
        image = background
        if verbose:
            print("Converted RGBA/P to RGB for JPEG compatibility.")
    elif output_format == "BMP" and image.mode not in ("RGB", "L", "1"):
        image = image.convert("RGB")
        if verbose:
            print(f"Converted mode to RGB for BMP compatibility.")

    # Build save parameters
    save_kwargs = {}

    # Quality setting for lossy formats
    if output_format in ("JPEG", "WEBP"):
        save_kwargs["quality"] = max(1, min(100, quality))
    elif output_format == "PNG":
        # PNG uses compress_level (0-9), map quality to it
        compress_level = max(0, min(9, (100 - quality) // 11))
        save_kwargs["compress_level"] = compress_level
    elif output_format == "TIFF":
        save_kwargs["compression"] = "tiff_lzw"

    # Preserve metadata if possible
    if preserve_metadata and exif_data:
        try:
            exif_bytes = exif_data.tobytes()
            if output_format in ("JPEG", "PNG", "WEBP", "TIFF"):
                save_kwargs["exif"] = exif_bytes
        except Exception as e:
            if verbose:
                print(f"Warning: Could not preserve metadata: {e}")

    # Ensure output directory exists
    output_dir = os.path.dirname(output_path)
    if output_dir:
        os.makedirs(output_dir, exist_ok=True)

    # Save the image
    image.save(output_path, format=output_format, **save_kwargs)

    output_abs = os.path.abspath(output_path)
    output_size = os.path.getsize(output_abs)

    if verbose:
        print(f"Saved: {output_abs}")
        print(f"Output format: {output_format}")
        print(f"Output file size: {output_size:,} bytes")

    return output_abs


def batch_convert(
    input_dir: str,
    output_dir: str,
    target_format: str,
    quality: int = 85,
    resize: Optional[Tuple[int, int]] = None,
    preserve_metadata: bool = True,
    verbose: bool = False,
) -> list:
    """
    Convert all supported images in a directory to a target format.

    Args:
        input_dir: Path to the directory containing source images.
        output_dir: Path to the output directory.
        target_format: Target file extension (e.g., '.png', '.jpg').
        quality: Quality setting for lossy formats.
        resize: Optional (width, height) tuple for resizing.
        preserve_metadata: Whether to preserve EXIF metadata.
        verbose: Whether to print detailed information.

    Returns:
        A list of output file paths.
    """
    if not os.path.isdir(input_dir):
        raise FileNotFoundError(f"Input directory not found: {input_dir}")

    os.makedirs(output_dir, exist_ok=True)

    target_ext = target_format if target_format.startswith(".") else f".{target_format}"
    if target_ext.lower() not in SUPPORTED_FORMATS:
        raise ValueError(f"Unsupported target format: {target_ext}")

    results = []
    for filename in sorted(os.listdir(input_dir)):
        ext = Path(filename).suffix.lower()
        if ext in SUPPORTED_FORMATS:
            input_path = os.path.join(input_dir, filename)
            output_filename = Path(filename).stem + target_ext
            output_path = os.path.join(output_dir, output_filename)

            try:
                result = convert_image(
                    input_path,
                    output_path,
                    quality=quality,
                    resize=resize,
                    preserve_metadata=preserve_metadata,
                    verbose=verbose,
                )
                results.append(result)
            except Exception as e:
                print(f"Error converting {filename}: {e}", file=sys.stderr)

    return results


def get_image_info(filepath: str) -> dict:
    """
    Get detailed information about an image file.

    Args:
        filepath: Path to the image file.

    Returns:
        A dictionary containing image information.
    """
    if not os.path.isfile(filepath):
        raise FileNotFoundError(f"File not found: {filepath}")

    image = Image.open(filepath)
    info = {
        "path": os.path.abspath(filepath),
        "format": image.format,
        "mode": image.mode,
        "width": image.size[0],
        "height": image.size[1],
        "file_size_bytes": os.path.getsize(filepath),
        "metadata": extract_metadata(image),
    }
    return info


def main():
    """Main entry point for the CLI."""
    parser = argparse.ArgumentParser(
        description="Image Format Converter - Convert between PNG, JPEG, BMP, TIFF, and WebP."
    )
    subparsers = parser.add_subparsers(dest="command", help="Available commands")

    # Convert command
    convert_parser = subparsers.add_parser("convert", help="Convert a single image")
    convert_parser.add_argument("input", help="Path to the input image")
    convert_parser.add_argument("output", help="Path for the output image")
    convert_parser.add_argument(
        "-q", "--quality", type=int, default=85,
        help="Quality setting (1-100, default: 85)"
    )
    convert_parser.add_argument(
        "-r", "--resize", type=str, default=None,
        help="Resize to WIDTHxHEIGHT (e.g., 800x600)"
    )
    convert_parser.add_argument(
        "--no-metadata", action="store_true",
        help="Strip metadata from the output"
    )
    convert_parser.add_argument(
        "-v", "--verbose", action="store_true",
        help="Print detailed conversion information"
    )

    # Batch command
    batch_parser = subparsers.add_parser("batch", help="Batch convert images in a directory")
    batch_parser.add_argument("input_dir", help="Input directory path")
    batch_parser.add_argument("output_dir", help="Output directory path")
    batch_parser.add_argument(
        "-f", "--format", required=True,
        help="Target format extension (e.g., .png, .jpg)"
    )
    batch_parser.add_argument(
        "-q", "--quality", type=int, default=85,
        help="Quality setting (1-100, default: 85)"
    )
    batch_parser.add_argument(
        "-r", "--resize", type=str, default=None,
        help="Resize to WIDTHxHEIGHT (e.g., 800x600)"
    )
    batch_parser.add_argument(
        "--no-metadata", action="store_true",
        help="Strip metadata from the output"
    )
    batch_parser.add_argument(
        "-v", "--verbose", action="store_true",
        help="Print detailed conversion information"
    )

    # Info command
    info_parser = subparsers.add_parser("info", help="Display image information")
    info_parser.add_argument("input", help="Path to the image file")

    args = parser.parse_args()

    if args.command is None:
        parser.print_help()
        sys.exit(1)

    # Parse resize argument
    resize = None
    if hasattr(args, "resize") and args.resize:
        try:
            parts = args.resize.lower().split("x")
            resize = (int(parts[0]), int(parts[1]))
        except (ValueError, IndexError):
            print("Error: Resize must be in WIDTHxHEIGHT format (e.g., 800x600).")
            sys.exit(1)

    if args.command == "convert":
        try:
            output = convert_image(
                args.input,
                args.output,
                quality=args.quality,
                resize=resize,
                preserve_metadata=not args.no_metadata,
                verbose=args.verbose,
            )
            print(f"Converted successfully: {output}")
        except Exception as e:
            print(f"Error: {e}", file=sys.stderr)
            sys.exit(1)

    elif args.command == "batch":
        try:
            results = batch_convert(
                args.input_dir,
                args.output_dir,
                target_format=args.format,
                quality=args.quality,
                resize=resize,
                preserve_metadata=not args.no_metadata,
                verbose=args.verbose,
            )
            print(f"Batch conversion complete. {len(results)} file(s) converted.")
        except Exception as e:
            print(f"Error: {e}", file=sys.stderr)
            sys.exit(1)

    elif args.command == "info":
        try:
            info = get_image_info(args.input)
            print(f"File: {info['path']}")
            print(f"Format: {info['format']}")
            print(f"Mode: {info['mode']}")
            print(f"Dimensions: {info['width']}x{info['height']}")
            print(f"File size: {info['file_size_bytes']:,} bytes")
            print("Metadata:")
            print_metadata(info["metadata"])
        except Exception as e:
            print(f"Error: {e}", file=sys.stderr)
            sys.exit(1)


if __name__ == "__main__":
    main()

# Image Format Converter (Python - Pillow)

An image format converter that supports PNG, JPEG, BMP, TIFF, and WebP formats with quality settings, resize capabilities, and metadata preservation.

## Dependencies

- **Pillow 10.2.0** - Python Imaging Library fork for image processing

## Installation

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

## Usage

### Convert a single image

```bash
python converter.py convert input.png output.jpg
python converter.py convert input.bmp output.webp -q 90
python converter.py convert input.tiff output.png -r 800x600
python converter.py convert input.jpg output.tiff --no-metadata -v
```

### Batch convert images

```bash
python converter.py batch ./input_dir ./output_dir -f .png
python converter.py batch ./photos ./thumbnails -f .jpg -q 75 -r 200x200
```

### Display image information

```bash
python converter.py info photo.jpg
```

## Options

| Option | Description |
|--------|-------------|
| `-q, --quality` | Quality setting (1-100, default: 85) |
| `-r, --resize` | Resize to WIDTHxHEIGHT (e.g., 800x600) |
| `--no-metadata` | Strip EXIF metadata from output |
| `-v, --verbose` | Print detailed conversion information |

## Supported Formats

| Format | Read | Write | Notes |
|--------|------|-------|-------|
| PNG | Yes | Yes | Lossless compression |
| JPEG | Yes | Yes | Lossy, quality configurable |
| BMP | Yes | Yes | Uncompressed |
| TIFF | Yes | Yes | LZW compression |
| WebP | Yes | Yes | Lossy, quality configurable |

Pillow==10.2.0