Image Watermarking Tool (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 Watermarking Tool

Write a program that adds text and image watermarks to photographs with configurable positioning, opacity, tiling, and batch processing capabilities.

FUNCTIONAL REQUIREMENTS:
- Accept an image file path as a command-line argument
- Support text watermarks via --text flag with configurable font size (--font-size, default 24), color (--color, hex format, default #FFFFFF), and font family (--font, default: a bundled or system sans-serif font)
- Support image overlay watermarks via --watermark flag (accepts a PNG file path with transparency)
- Support configurable position via --position flag: center, top-left, top-right, bottom-left, bottom-right, or custom coordinates (x,y)
- Support configurable opacity via --opacity flag (0.0 to 1.0, default 0.3)
- Support tiled/repeated watermark mode via --tile flag that repeats the watermark across the entire image with configurable spacing (--spacing, default 100 pixels) and rotation angle (--angle, default -30 degrees)
- Support adding a semi-transparent background band behind text watermarks for better readability via --background-band flag
- Support batch watermarking of all images in a directory via --batch flag
- Preserve original image quality and metadata in the output
- Print processing details to console: input file, watermark type, position, opacity, output file, processing time
- Save watermarked images to a path specified by --output flag (default: original name with _watermarked suffix)
- If no input is given, generate a sample 1024x768 photograph-like image, apply both a text watermark and a tiled watermark, then save both versions to demonstrate the capabilities
- Handle errors: missing font files, invalid watermark images, unsupported image formats, images too small for the watermark

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 Watermarking Tool (Python / Pillow)

A command-line image watermarking tool that supports text and image watermarks with positioning, opacity control, tiling, rotation, and batch processing.

## Dependencies

- **Pillow 10.2.0** - Python Imaging Library for image manipulation

## Installation

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

## Usage

### Text Watermark

```bash
# Basic text watermark
python watermark.py text input.png output.png --text "Copyright 2024"

# Custom position and styling
python watermark.py text input.png output.png --text "CONFIDENTIAL" \
    --position center --font-size 60 --color "255,0,0,200" --opacity 0.7

# Rotated tiled watermark
python watermark.py text input.png output.png --text "DRAFT" \
    --tile --rotation 45 --opacity 0.3 --tile-spacing "100,100"

# Batch processing
python watermark.py text ./input_dir/ ./output_dir/ --text "Sample" --batch
```

### Image Watermark

```bash
# Basic image watermark
python watermark.py image input.png output.png --watermark logo.png

# Custom positioning and scale
python watermark.py image input.png output.png --watermark logo.png \
    --position bottom-left --scale 0.15 --opacity 0.8

# Tiled image watermark with rotation
python watermark.py image input.png output.png --watermark logo.png \
    --tile --rotation 30 --scale 0.1 --opacity 0.2

# Batch processing
python watermark.py image ./input_dir/ ./output_dir/ --watermark logo.png --batch
```

### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--position` | Watermark position (e.g., bottom-right, center) | bottom-right |
| `--opacity` | Opacity from 0.0 to 1.0 | 0.5 |
| `--rotation` | Rotation angle in degrees | 0.0 |
| `--tile` | Tile watermark across the entire image | off |
| `--tile-spacing` | Spacing between tiles as X,Y | 50,50 |
| `--offset` | Position offset as X,Y | 0,0 |
| `--batch` | Process all images in a directory | off |

## Features

- Text watermarks with customizable font, size, and color
- Image watermarks with scaling control
- Nine named positions (top-left through bottom-right)
- Adjustable opacity
- Rotation support
- Tiled watermarks with configurable spacing
- Batch processing of entire directories

Pillow==10.2.0

"""
Image Watermarking Tool using Pillow.
Supports text and image watermarks with positioning, opacity, tiling, rotation, and batch processing.
"""

import os
import sys
import argparse
import math
from PIL import Image, ImageDraw, ImageFont, ImageEnhance


def load_image(path: str) -> Image.Image:
    """Load an image from the given path."""
    if not os.path.isfile(path):
        raise FileNotFoundError(f"Image not found: {path}")
    return Image.open(path).convert("RGBA")


def create_text_watermark(
    text: str,
    size: tuple,
    font_path: str = None,
    font_size: int = 40,
    color: tuple = (255, 255, 255, 128),
    rotation: float = 0.0,
) -> Image.Image:
    """Create a text watermark image with the given parameters."""
    # Create a transparent layer larger than needed for rotation
    diagonal = int(math.sqrt(size[0] ** 2 + size[1] ** 2))
    txt_layer = Image.new("RGBA", (diagonal * 2, diagonal * 2), (0, 0, 0, 0))
    draw = ImageDraw.Draw(txt_layer)

    if font_path and os.path.isfile(font_path):
        font = ImageFont.truetype(font_path, font_size)
    else:
        try:
            font = ImageFont.truetype("arial.ttf", font_size)
        except (IOError, OSError):
            font = ImageFont.load_default()

    bbox = draw.textbbox((0, 0), text, font=font)
    text_width = bbox[2] - bbox[0]
    text_height = bbox[3] - bbox[1]

    x = (diagonal * 2 - text_width) // 2
    y = (diagonal * 2 - text_height) // 2
    draw.text((x, y), text, fill=color, font=font)

    if rotation != 0.0:
        txt_layer = txt_layer.rotate(rotation, resample=Image.BICUBIC, expand=False)

    # Crop to the target size centered
    cx, cy = txt_layer.size[0] // 2, txt_layer.size[1] // 2
    left = cx - size[0] // 2
    top = cy - size[1] // 2
    txt_layer = txt_layer.crop((left, top, left + size[0], top + size[1]))

    return txt_layer


def apply_opacity(watermark: Image.Image, opacity: float) -> Image.Image:
    """Apply opacity to a watermark image (0.0 to 1.0)."""
    opacity = max(0.0, min(1.0, opacity))
    if watermark.mode != "RGBA":
        watermark = watermark.convert("RGBA")

    r, g, b, a = watermark.split()
    a = a.point(lambda x: int(x * opacity))
    return Image.merge("RGBA", (r, g, b, a))


def calculate_position(
    base_size: tuple, wm_size: tuple, position: str, offset: tuple = (0, 0)
) -> tuple:
    """Calculate watermark position based on named position or coordinates."""
    positions = {
        "top-left": (0, 0),
        "top-center": ((base_size[0] - wm_size[0]) // 2, 0),
        "top-right": (base_size[0] - wm_size[0], 0),
        "center-left": (0, (base_size[1] - wm_size[1]) // 2),
        "center": (
            (base_size[0] - wm_size[0]) // 2,
            (base_size[1] - wm_size[1]) // 2,
        ),
        "center-right": (base_size[0] - wm_size[0], (base_size[1] - wm_size[1]) // 2),
        "bottom-left": (0, base_size[1] - wm_size[1]),
        "bottom-center": (
            (base_size[0] - wm_size[0]) // 2,
            base_size[1] - wm_size[1],
        ),
        "bottom-right": (base_size[0] - wm_size[0], base_size[1] - wm_size[1]),
    }

    pos = positions.get(position, positions["bottom-right"])
    return (pos[0] + offset[0], pos[1] + offset[1])


def tile_watermark(
    base_size: tuple,
    watermark: Image.Image,
    spacing: tuple = (50, 50),
) -> Image.Image:
    """Create a tiled watermark layer covering the entire base image."""
    tiled = Image.new("RGBA", base_size, (0, 0, 0, 0))
    wm_w, wm_h = watermark.size
    step_x = wm_w + spacing[0]
    step_y = wm_h + spacing[1]

    for y in range(0, base_size[1] + wm_h, step_y):
        for x in range(0, base_size[0] + wm_w, step_x):
            tiled.paste(watermark, (x, y), watermark)

    return tiled


def apply_text_watermark(
    base_image: Image.Image,
    text: str,
    position: str = "bottom-right",
    font_path: str = None,
    font_size: int = 40,
    color: tuple = (255, 255, 255, 128),
    opacity: float = 0.5,
    rotation: float = 0.0,
    tile: bool = False,
    tile_spacing: tuple = (50, 50),
    offset: tuple = (0, 0),
) -> Image.Image:
    """Apply a text watermark to an image."""
    base = base_image.copy().convert("RGBA")

    if tile:
        # Create a single watermark stamp for tiling
        stamp_size = (font_size * len(text), font_size * 2)
        stamp = create_text_watermark(
            text, stamp_size, font_path, font_size, color, rotation
        )
        stamp = apply_opacity(stamp, opacity)
        watermark_layer = tile_watermark(base.size, stamp, tile_spacing)
    else:
        watermark_layer = create_text_watermark(
            text, base.size, font_path, font_size, color, rotation
        )
        watermark_layer = apply_opacity(watermark_layer, opacity)

    result = Image.alpha_composite(base, watermark_layer)
    return result


def apply_image_watermark(
    base_image: Image.Image,
    watermark_path: str,
    position: str = "bottom-right",
    opacity: float = 0.5,
    scale: float = 0.2,
    rotation: float = 0.0,
    tile: bool = False,
    tile_spacing: tuple = (50, 50),
    offset: tuple = (0, 0),
) -> Image.Image:
    """Apply an image watermark to an image."""
    base = base_image.copy().convert("RGBA")
    wm = load_image(watermark_path)

    # Scale the watermark relative to the base image
    new_width = int(base.size[0] * scale)
    aspect_ratio = wm.size[1] / wm.size[0]
    new_height = int(new_width * aspect_ratio)
    wm = wm.resize((new_width, new_height), Image.LANCZOS)

    if rotation != 0.0:
        wm = wm.rotate(rotation, resample=Image.BICUBIC, expand=True)

    wm = apply_opacity(wm, opacity)

    if tile:
        watermark_layer = tile_watermark(base.size, wm, tile_spacing)
    else:
        watermark_layer = Image.new("RGBA", base.size, (0, 0, 0, 0))
        pos = calculate_position(base.size, wm.size, position, offset)
        watermark_layer.paste(wm, pos, wm)

    result = Image.alpha_composite(base, watermark_layer)
    return result


def batch_process(
    input_dir: str,
    output_dir: str,
    watermark_func,
    watermark_kwargs: dict,
    extensions: tuple = (".png", ".jpg", ".jpeg", ".bmp", ".tiff", ".webp"),
) -> list:
    """Process all images in a directory with the given watermark function."""
    os.makedirs(output_dir, exist_ok=True)
    processed = []

    for filename in sorted(os.listdir(input_dir)):
        if not any(filename.lower().endswith(ext) for ext in extensions):
            continue

        input_path = os.path.join(input_dir, filename)
        output_path = os.path.join(output_dir, filename)

        try:
            base = load_image(input_path)
            result = watermark_func(base_image=base, **watermark_kwargs)
            # Convert to RGB if saving as JPEG
            if filename.lower().endswith((".jpg", ".jpeg")):
                result = result.convert("RGB")
            result.save(output_path)
            processed.append(output_path)
            print(f"  Processed: {filename}")
        except Exception as e:
            print(f"  Error processing {filename}: {e}")

    return processed


def parse_color(color_str: str) -> tuple:
    """Parse a color string like '255,255,255,128' into a tuple."""
    parts = [int(x.strip()) for x in color_str.split(",")]
    if len(parts) == 3:
        parts.append(128)
    return tuple(parts)


def main():
    parser = argparse.ArgumentParser(
        description="Image Watermarking Tool - Add text or image watermarks"
    )
    subparsers = parser.add_subparsers(dest="command", help="Watermark type")

    # Text watermark subcommand
    text_parser = subparsers.add_parser("text", help="Add a text watermark")
    text_parser.add_argument("input", help="Input image path or directory for batch")
    text_parser.add_argument("output", help="Output image path or directory for batch")
    text_parser.add_argument("--text", "-t", required=True, help="Watermark text")
    text_parser.add_argument(
        "--position",
        "-p",
        default="bottom-right",
        choices=[
            "top-left", "top-center", "top-right",
            "center-left", "center", "center-right",
            "bottom-left", "bottom-center", "bottom-right",
        ],
        help="Watermark position (default: bottom-right)",
    )
    text_parser.add_argument("--font", help="Path to a TrueType font file")
    text_parser.add_argument(
        "--font-size", type=int, default=40, help="Font size (default: 40)"
    )
    text_parser.add_argument(
        "--color",
        default="255,255,255,128",
        help="Text color as R,G,B,A (default: 255,255,255,128)",
    )
    text_parser.add_argument(
        "--opacity", type=float, default=0.5, help="Opacity 0.0-1.0 (default: 0.5)"
    )
    text_parser.add_argument(
        "--rotation", type=float, default=0.0, help="Rotation angle in degrees"
    )
    text_parser.add_argument(
        "--tile", action="store_true", help="Tile watermark across entire image"
    )
    text_parser.add_argument(
        "--tile-spacing",
        default="50,50",
        help="Tile spacing as X,Y (default: 50,50)",
    )
    text_parser.add_argument(
        "--offset", default="0,0", help="Position offset as X,Y (default: 0,0)"
    )
    text_parser.add_argument(
        "--batch", action="store_true", help="Process all images in input directory"
    )

    # Image watermark subcommand
    img_parser = subparsers.add_parser("image", help="Add an image watermark")
    img_parser.add_argument("input", help="Input image path or directory for batch")
    img_parser.add_argument("output", help="Output image path or directory for batch")
    img_parser.add_argument(
        "--watermark", "-w", required=True, help="Watermark image path"
    )
    img_parser.add_argument(
        "--position",
        "-p",
        default="bottom-right",
        choices=[
            "top-left", "top-center", "top-right",
            "center-left", "center", "center-right",
            "bottom-left", "bottom-center", "bottom-right",
        ],
        help="Watermark position (default: bottom-right)",
    )
    img_parser.add_argument(
        "--opacity", type=float, default=0.5, help="Opacity 0.0-1.0 (default: 0.5)"
    )
    img_parser.add_argument(
        "--scale",
        type=float,
        default=0.2,
        help="Scale relative to base image width (default: 0.2)",
    )
    img_parser.add_argument(
        "--rotation", type=float, default=0.0, help="Rotation angle in degrees"
    )
    img_parser.add_argument(
        "--tile", action="store_true", help="Tile watermark across entire image"
    )
    img_parser.add_argument(
        "--tile-spacing",
        default="50,50",
        help="Tile spacing as X,Y (default: 50,50)",
    )
    img_parser.add_argument(
        "--offset", default="0,0", help="Position offset as X,Y (default: 0,0)"
    )
    img_parser.add_argument(
        "--batch", action="store_true", help="Process all images in input directory"
    )

    args = parser.parse_args()

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

    if args.command == "text":
        color = parse_color(args.color)
        tile_spacing = tuple(int(x) for x in args.tile_spacing.split(","))
        offset = tuple(int(x) for x in args.offset.split(","))

        kwargs = dict(
            text=args.text,
            position=args.position,
            font_path=args.font,
            font_size=args.font_size,
            color=color,
            opacity=args.opacity,
            rotation=args.rotation,
            tile=args.tile,
            tile_spacing=tile_spacing,
            offset=offset,
        )

        if args.batch:
            print(f"Batch processing directory: {args.input}")
            results = batch_process(
                args.input, args.output, apply_text_watermark, kwargs
            )
            print(f"Processed {len(results)} images.")
        else:
            base = load_image(args.input)
            result = apply_text_watermark(base_image=base, **kwargs)
            if args.output.lower().endswith((".jpg", ".jpeg")):
                result = result.convert("RGB")
            result.save(args.output)
            print(f"Watermarked image saved to: {args.output}")

    elif args.command == "image":
        tile_spacing = tuple(int(x) for x in args.tile_spacing.split(","))
        offset = tuple(int(x) for x in args.offset.split(","))

        kwargs = dict(
            watermark_path=args.watermark,
            position=args.position,
            opacity=args.opacity,
            scale=args.scale,
            rotation=args.rotation,
            tile=args.tile,
            tile_spacing=tile_spacing,
            offset=offset,
        )

        if args.batch:
            print(f"Batch processing directory: {args.input}")
            results = batch_process(
                args.input, args.output, apply_image_watermark, kwargs
            )
            print(f"Processed {len(results)} images.")
        else:
            base = load_image(args.input)
            result = apply_image_watermark(base_image=base, **kwargs)
            if args.output.lower().endswith((".jpg", ".jpeg")):
                result = result.convert("RGB")
            result.save(args.output)
            print(f"Watermarked image saved to: {args.output}")


if __name__ == "__main__":
    main()