Image Watermarking Tool (python, written by Claude Code)

--- /dev/null
+++ b/setup.sh
@@ -0,0 +1,6 @@
+#!/bin/bash
+# System packages this project needs on a clean Ubuntu machine.
+set -e
+export DEBIAN_FRONTEND=noninteractive
+apt-get update -qq
+apt-get install -y -qq --no-install-recommends libmagickwand-dev

Claude Code wrote this python project from the task below. It does not run 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

[
  {
    "category": "underspecification",
    "rule": "signature.missing_system_requirement",
    "source": "failure_signature",
    "excerpt": "OSError: cannot find library; tried paths: []"
  },
  {
    "category": "underspecification",
    "rule": "diff.adds_external_environment_requirement",
    "source": "manifest_diff:setup.sh",
    "excerpt": "export DEBIAN_FRONTEND=noninteractive"
  },
  {
    "category": "underspecification",
    "rule": "diff.adds_external_environment_requirement",
    "source": "manifest_diff:setup.sh",
    "excerpt": "apt-get install -y -qq --no-install-recommends libmagickwand-dev"
  }
]

# Image Watermarking Tool (Python / Wand + Click)

A command-line image watermarking tool using Wand (Python binding for ImageMagick) for image processing and Click for CLI interface. Supports text and image watermarks with positioning, opacity control, tiling, rotation, and batch processing.

## Dependencies

- **Wand 0.6.13** - Python binding for ImageMagick, providing high-level image manipulation with support for 200+ image formats
- **click 8.1.7** - Python CLI framework for creating composable command-line interfaces with automatic help generation

## Prerequisites

Wand requires ImageMagick to be installed on the system:
- Ubuntu/Debian: `sudo apt install libmagickwand-dev`
- macOS: `brew install imagemagick`
- Windows: Download from https://imagemagick.org

## 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 "rgba(255,0,0,0.8)" --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 |
| `--font` | Font name | Arial |
| `--font-size` | Font size in points | 40 |
| `--color` | Text color (ImageMagick format, e.g., rgba) | rgba(255,255,255,0.5) |
| `--opacity` | Opacity from 0.0 to 1.0 | 0.5 |
| `--scale` | Image watermark scale relative to base width | 0.2 |
| `--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

- Rich text rendering via ImageMagick with any system font
- Support for 200+ image formats via ImageMagick backend
- Nine named positions (top-left through bottom-right)
- Alpha channel opacity control via evaluate operations
- Rotation with transparent background preservation
- Tiled watermarks with configurable spacing
- Batch processing of entire directories
- Clean CLI with Click auto-generated help

Wand==0.6.13
click==8.1.7

"""
Image Watermarking Tool using Wand (ImageMagick binding) and Click.
Supports text and image watermarks with positioning, opacity, tiling, rotation,
and batch processing.
"""

import os
import sys
import math
import click
from wand.image import Image
from wand.drawing import Drawing
from wand.color import Color


# Supported image extensions
IMAGE_EXTENSIONS = ('.png', '.jpg', '.jpeg', '.bmp', '.tiff', '.tif', '.webp', '.gif')

POSITIONS = [
    'top-left', 'top-center', 'top-right',
    'center-left', 'center', 'center-right',
    'bottom-left', 'bottom-center', 'bottom-right',
]


def calculate_position(base_w, base_h, wm_w, wm_h, position, offset_x=0, offset_y=0):
    """Calculate watermark position based on named position string."""
    positions = {
        'top-left':      (0, 0),
        'top-center':    ((base_w - wm_w) // 2, 0),
        'top-right':     (base_w - wm_w, 0),
        'center-left':   (0, (base_h - wm_h) // 2),
        'center':        ((base_w - wm_w) // 2, (base_h - wm_h) // 2),
        'center-right':  (base_w - wm_w, (base_h - wm_h) // 2),
        'bottom-left':   (0, base_h - wm_h),
        'bottom-center': ((base_w - wm_w) // 2, base_h - wm_h),
        'bottom-right':  (base_w - wm_w, base_h - wm_h),
    }
    pos = positions.get(position, positions['bottom-right'])
    return (pos[0] + offset_x, pos[1] + offset_y)


def create_text_stamp(text, font_name, font_size, color_str, rotation):
    """Create a text watermark as a Wand Image with transparent background."""
    # Measure text size using a Drawing object
    with Drawing() as draw:
        draw.font = font_name if font_name else 'Arial'
        draw.font_size = font_size
        draw.fill_color = Color(color_str)

        # Get text metrics
        with Image(width=1, height=1, background=Color('transparent')) as tmp:
            metrics = draw.get_font_metrics(tmp, text, multiline=False)
            text_w = int(math.ceil(metrics.text_width)) + 20
            text_h = int(math.ceil(metrics.text_height)) + 20

    # Create the stamp image
    stamp = Image(width=text_w, height=text_h, background=Color('transparent'))
    with Drawing() as draw:
        draw.font = font_name if font_name else 'Arial'
        draw.font_size = font_size
        draw.fill_color = Color(color_str)
        draw.text(10, int(metrics.ascender) + 10, text)
        draw(stamp)

    if rotation != 0.0:
        stamp.rotate(rotation, background=Color('transparent'))

    return stamp


def apply_opacity(image, opacity):
    """Apply opacity to an image by modifying its alpha channel."""
    if opacity >= 1.0:
        return
    image.evaluate(operator='multiply', value=opacity, channel='alpha')


def composite_stamp(base, stamp, x, y):
    """Composite a stamp image onto the base at position (x, y)."""
    base.composite(stamp, left=int(x), top=int(y))


def tile_stamp(base, stamp, spacing_x, spacing_y, opacity):
    """Tile a stamp across the entire base image."""
    sw = stamp.width
    sh = stamp.height
    bw = base.width
    bh = base.height
    step_x = sw + spacing_x
    step_y = sh + spacing_y

    for ty in range(0, bh + sh, step_y):
        for tx in range(0, bw + sw, step_x):
            composite_stamp(base, stamp, tx, ty)


def apply_text_watermark(base, text, position='bottom-right', font_name=None,
                         font_size=40, color='rgba(255,255,255,0.5)',
                         opacity=0.5, rotation=0.0, tile=False,
                         tile_spacing_x=50, tile_spacing_y=50,
                         offset_x=0, offset_y=0):
    """Apply a text watermark to a Wand Image."""
    stamp = create_text_stamp(text, font_name, font_size, color, rotation)
    apply_opacity(stamp, opacity)

    if tile:
        tile_stamp(base, stamp, tile_spacing_x, tile_spacing_y, opacity)
    else:
        px, py = calculate_position(base.width, base.height,
                                    stamp.width, stamp.height,
                                    position, offset_x, offset_y)
        composite_stamp(base, stamp, px, py)

    stamp.close()
    return base


def apply_image_watermark(base, watermark_path, position='bottom-right',
                          opacity=0.5, scale=0.2, rotation=0.0,
                          tile=False, tile_spacing_x=50, tile_spacing_y=50,
                          offset_x=0, offset_y=0):
    """Apply an image watermark to a Wand Image."""
    wm = Image(filename=watermark_path)
    wm.alpha_channel = 'set'

    # Scale relative to base width
    scaled_w = int(base.width * scale)
    aspect = wm.height / wm.width
    scaled_h = int(scaled_w * aspect)
    wm.resize(scaled_w, scaled_h)

    if rotation != 0.0:
        wm.rotate(rotation, background=Color('transparent'))

    apply_opacity(wm, opacity)

    if tile:
        tile_stamp(base, wm, tile_spacing_x, tile_spacing_y, opacity)
    else:
        px, py = calculate_position(base.width, base.height,
                                    wm.width, wm.height,
                                    position, offset_x, offset_y)
        composite_stamp(base, wm, px, py)

    wm.close()
    return base


def batch_process(input_dir, output_dir, mode, **kwargs):
    """Process all images in a directory."""
    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 IMAGE_EXTENSIONS):
            continue

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

        try:
            with Image(filename=input_path) as base:
                base.alpha_channel = 'set'

                if mode == 'text':
                    apply_text_watermark(base, **kwargs)
                else:
                    apply_image_watermark(base, **kwargs)

                base.save(filename=output_path)
                processed.append(output_path)
                click.echo(f"  Processed: {filename}")
        except Exception as e:
            click.echo(f"  Error processing {filename}: {e}", err=True)

    return processed


@click.group()
def cli():
    """Image Watermarking Tool - Add text or image watermarks using Wand."""
    pass


@cli.command()
@click.argument('input_path')
@click.argument('output_path')
@click.option('--text', '-t', required=True, help='Watermark text')
@click.option('--position', '-p', default='bottom-right',
              type=click.Choice(POSITIONS), help='Watermark position')
@click.option('--font', default=None, help='Font name')
@click.option('--font-size', default=40, type=int, help='Font size')
@click.option('--color', default='rgba(255,255,255,0.5)', help='Text color')
@click.option('--opacity', default=0.5, type=float, help='Opacity 0.0-1.0')
@click.option('--rotation', default=0.0, type=float, help='Rotation angle in degrees')
@click.option('--tile', is_flag=True, help='Tile watermark across entire image')
@click.option('--tile-spacing', default='50,50', help='Tile spacing as X,Y')
@click.option('--offset', default='0,0', help='Position offset as X,Y')
@click.option('--batch', is_flag=True, help='Process all images in input directory')
def text(input_path, output_path, text, position, font, font_size, color,
         opacity, rotation, tile, tile_spacing, offset, batch):
    """Add a text watermark to an image."""
    spacing = [int(x) for x in tile_spacing.split(',')]
    off = [int(x) for x in offset.split(',')]

    kwargs = dict(
        text=text,
        position=position,
        font_name=font,
        font_size=font_size,
        color=color,
        opacity=opacity,
        rotation=rotation,
        tile=tile,
        tile_spacing_x=spacing[0],
        tile_spacing_y=spacing[1],
        offset_x=off[0],
        offset_y=off[1],
    )

    if batch:
        click.echo(f"Batch processing directory: {input_path}")
        results = batch_process(input_path, output_path, 'text', **kwargs)
        click.echo(f"Processed {len(results)} images.")
    else:
        with Image(filename=input_path) as base:
            base.alpha_channel = 'set'
            apply_text_watermark(base, **kwargs)
            base.save(filename=output_path)
            click.echo(f"Watermarked image saved to: {output_path}")


@cli.command()
@click.argument('input_path')
@click.argument('output_path')
@click.option('--watermark', '-w', required=True, help='Watermark image path')
@click.option('--position', '-p', default='bottom-right',
              type=click.Choice(POSITIONS), help='Watermark position')
@click.option('--opacity', default=0.5, type=float, help='Opacity 0.0-1.0')
@click.option('--scale', default=0.2, type=float, help='Scale relative to base width')
@click.option('--rotation', default=0.0, type=float, help='Rotation angle in degrees')
@click.option('--tile', is_flag=True, help='Tile watermark across entire image')
@click.option('--tile-spacing', default='50,50', help='Tile spacing as X,Y')
@click.option('--offset', default='0,0', help='Position offset as X,Y')
@click.option('--batch', is_flag=True, help='Process all images in input directory')
def image(input_path, output_path, watermark, position, opacity, scale,
          rotation, tile, tile_spacing, offset, batch):
    """Add an image watermark to an image."""
    spacing = [int(x) for x in tile_spacing.split(',')]
    off = [int(x) for x in offset.split(',')]

    kwargs = dict(
        watermark_path=watermark,
        position=position,
        opacity=opacity,
        scale=scale,
        rotation=rotation,
        tile=tile,
        tile_spacing_x=spacing[0],
        tile_spacing_y=spacing[1],
        offset_x=off[0],
        offset_y=off[1],
    )

    if batch:
        click.echo(f"Batch processing directory: {input_path}")
        results = batch_process(input_path, output_path, 'image', **kwargs)
        click.echo(f"Processed {len(results)} images.")
    else:
        with Image(filename=input_path) as base:
            base.alpha_channel = 'set'
            apply_image_watermark(base, **kwargs)
            base.save(filename=output_path)
            click.echo(f"Watermarked image saved to: {output_path}")


if __name__ == '__main__':
    cli()