Image Histogram Analyzer (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 Histogram Analyzer

Write a program that computes and analyzes color histograms of images, providing statistical analysis of color distribution, channel comparisons, and similarity scoring between images.

FUNCTIONAL REQUIREMENTS:
- Accept an image file path as a command-line argument
- Compute per-channel histograms (Red, Green, Blue) with 256 bins each, plus a luminance/grayscale histogram
- Calculate statistics for each channel: mean intensity, median, standard deviation, skewness, dominant intensity ranges, and dynamic range (difference between darkest and brightest used values)
- Detect if an image is overexposed (high mean, clipped highlights), underexposed (low mean, clipped shadows), or low contrast (narrow histogram spread)
- Support histogram comparison between two images via --compare flag: compute correlation, chi-squared distance, intersection, and Bhattacharyya distance between their histograms
- Support cumulative histogram computation for each channel via --cumulative flag
- Generate a histogram data output as a CSV file with columns (bin, red_count, green_count, blue_count, luminance_count) via --export flag
- Support analyzing specific regions of an image via --crop flag (x,y,width,height)
- Print a text-based summary to console: per-channel statistics, exposure assessment, contrast assessment, and color balance analysis
- Save the full analysis as JSON with --output flag (default: histogram_analysis.json)
- Support batch analysis of multiple images via --batch flag with a summary comparison table
- If no input is given, generate three sample images (one overexposed, one underexposed, one well-balanced), analyze each, and display comparative results
- Handle errors: unsupported image formats, corrupted files, grayscale images (single-channel analysis)

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 Histogram Analyzer
Computes per-channel color histograms, detects exposure issues,
and compares histograms between images.

Dependencies: Pillow 10.2.0, matplotlib 3.8.2, numpy 1.26.4
"""

import sys
import argparse
import numpy as np
from PIL import Image
import matplotlib.pyplot as plt
from pathlib import Path


def compute_histogram(image_path: str) -> dict:
    """
    Compute per-channel color histograms for an image.

    Args:
        image_path: Path to the image file.

    Returns:
        Dictionary with channel names as keys and histogram arrays as values.
    """
    img = Image.open(image_path).convert("RGB")
    pixels = np.array(img)

    histograms = {}
    channel_names = ["Red", "Green", "Blue"]

    for i, name in enumerate(channel_names):
        hist, _ = np.histogram(pixels[:, :, i], bins=256, range=(0, 256))
        histograms[name] = hist

    # Compute luminance histogram
    luminance = (
        0.2126 * pixels[:, :, 0]
        + 0.7152 * pixels[:, :, 1]
        + 0.0722 * pixels[:, :, 2]
    )
    lum_hist, _ = np.histogram(luminance, bins=256, range=(0, 256))
    histograms["Luminance"] = lum_hist

    return histograms


def compute_statistics(histograms: dict) -> dict:
    """
    Compute statistical measures for each channel histogram.

    Args:
        histograms: Dictionary of channel histograms.

    Returns:
        Dictionary of statistics per channel.
    """
    stats = {}
    for channel, hist in histograms.items():
        total_pixels = hist.sum()
        values = np.arange(256)
        mean = np.average(values, weights=hist)
        variance = np.average((values - mean) ** 2, weights=hist)
        std_dev = np.sqrt(variance)

        # Find median
        cumulative = np.cumsum(hist)
        median_idx = np.searchsorted(cumulative, total_pixels / 2)

        # Find mode
        mode = np.argmax(hist)

        stats[channel] = {
            "mean": float(mean),
            "median": int(median_idx),
            "mode": int(mode),
            "std_dev": float(std_dev),
            "total_pixels": int(total_pixels),
        }

    return stats


def detect_exposure_issues(histograms: dict, threshold: float = 0.25) -> dict:
    """
    Detect exposure issues based on histogram distribution.

    Analyzes the luminance histogram to determine if an image is
    overexposed, underexposed, or has low contrast.

    Args:
        histograms: Dictionary of channel histograms.
        threshold: Fraction of pixels threshold for detecting issues.

    Returns:
        Dictionary describing detected exposure issues.
    """
    lum_hist = histograms.get("Luminance")
    if lum_hist is None:
        return {"error": "No luminance histogram available"}

    total_pixels = lum_hist.sum()
    if total_pixels == 0:
        return {"error": "Empty histogram"}

    # Analyze distribution regions
    shadow_pixels = lum_hist[:64].sum() / total_pixels
    midtone_pixels = lum_hist[64:192].sum() / total_pixels
    highlight_pixels = lum_hist[192:].sum() / total_pixels

    # Check for clipping
    shadow_clipping = lum_hist[:5].sum() / total_pixels
    highlight_clipping = lum_hist[251:].sum() / total_pixels

    issues = []
    severity = "normal"

    if shadow_pixels > threshold and highlight_pixels < 0.1:
        issues.append("Image appears underexposed (heavy shadows)")
        severity = "underexposed"

    if highlight_pixels > threshold and shadow_pixels < 0.1:
        issues.append("Image appears overexposed (heavy highlights)")
        severity = "overexposed"

    if shadow_clipping > 0.05:
        issues.append(
            f"Shadow clipping detected ({shadow_clipping * 100:.1f}% of pixels)"
        )

    if highlight_clipping > 0.05:
        issues.append(
            f"Highlight clipping detected ({highlight_clipping * 100:.1f}% of pixels)"
        )

    # Check contrast
    values = np.arange(256)
    mean = np.average(values, weights=lum_hist)
    variance = np.average((values - mean) ** 2, weights=lum_hist)
    std_dev = np.sqrt(variance)

    if std_dev < 30:
        issues.append(f"Low contrast detected (std dev: {std_dev:.1f})")
        if severity == "normal":
            severity = "low_contrast"

    if std_dev > 80:
        issues.append(f"High contrast detected (std dev: {std_dev:.1f})")
        if severity == "normal":
            severity = "high_contrast"

    if not issues:
        issues.append("No exposure issues detected")

    return {
        "severity": severity,
        "issues": issues,
        "shadow_fraction": float(shadow_pixels),
        "midtone_fraction": float(midtone_pixels),
        "highlight_fraction": float(highlight_pixels),
        "shadow_clipping": float(shadow_clipping),
        "highlight_clipping": float(highlight_clipping),
    }


def compare_histograms(hist1: dict, hist2: dict) -> dict:
    """
    Compare histograms between two images using multiple metrics.

    Args:
        hist1: Histograms of the first image.
        hist2: Histograms of the second image.

    Returns:
        Dictionary of comparison metrics per channel.
    """
    comparison = {}

    for channel in hist1:
        if channel not in hist2:
            continue

        h1 = hist1[channel].astype(np.float64)
        h2 = hist2[channel].astype(np.float64)

        # Normalize histograms
        h1_norm = h1 / (h1.sum() + 1e-10)
        h2_norm = h2 / (h2.sum() + 1e-10)

        # Correlation
        h1_centered = h1_norm - h1_norm.mean()
        h2_centered = h2_norm - h2_norm.mean()
        denom = np.sqrt((h1_centered ** 2).sum() * (h2_centered ** 2).sum()) + 1e-10
        correlation = float((h1_centered * h2_centered).sum() / denom)

        # Chi-squared distance
        chi_squared = float(
            np.sum((h1_norm - h2_norm) ** 2 / (h1_norm + h2_norm + 1e-10))
        )

        # Bhattacharyya distance
        bc = np.sum(np.sqrt(h1_norm * h2_norm))
        bhattacharyya = float(-np.log(bc + 1e-10))

        # Earth Mover's Distance (1D Wasserstein)
        cdf1 = np.cumsum(h1_norm)
        cdf2 = np.cumsum(h2_norm)
        emd = float(np.sum(np.abs(cdf1 - cdf2)))

        # Intersection
        intersection = float(np.minimum(h1_norm, h2_norm).sum())

        comparison[channel] = {
            "correlation": correlation,
            "chi_squared": chi_squared,
            "bhattacharyya": bhattacharyya,
            "earth_movers_distance": emd,
            "intersection": intersection,
        }

    return comparison


def plot_histogram(
    histograms: dict, title: str = "Image Histogram", output_path: str = None
):
    """
    Plot per-channel histograms using matplotlib.

    Args:
        histograms: Dictionary of channel histograms.
        title: Title for the plot.
        output_path: If provided, save the plot to this path.
    """
    fig, axes = plt.subplots(2, 2, figsize=(12, 8))
    fig.suptitle(title, fontsize=14, fontweight="bold")

    colors = {
        "Red": "red",
        "Green": "green",
        "Blue": "blue",
        "Luminance": "gray",
    }

    channel_list = ["Red", "Green", "Blue", "Luminance"]

    for idx, channel in enumerate(channel_list):
        ax = axes[idx // 2][idx % 2]
        if channel in histograms:
            ax.fill_between(
                range(256),
                histograms[channel],
                alpha=0.5,
                color=colors.get(channel, "black"),
            )
            ax.plot(
                range(256),
                histograms[channel],
                color=colors.get(channel, "black"),
                linewidth=0.8,
            )
        ax.set_title(channel)
        ax.set_xlabel("Pixel Value")
        ax.set_ylabel("Frequency")
        ax.set_xlim(0, 255)

    plt.tight_layout()

    if output_path:
        plt.savefig(output_path, dpi=150, bbox_inches="tight")
        print(f"Histogram plot saved to: {output_path}")
    else:
        plt.show()

    plt.close()


def plot_comparison(
    hist1: dict,
    hist2: dict,
    label1: str = "Image 1",
    label2: str = "Image 2",
    output_path: str = None,
):
    """
    Plot overlaid histograms for comparison between two images.

    Args:
        hist1: Histograms of the first image.
        hist2: Histograms of the second image.
        label1: Label for the first image.
        label2: Label for the second image.
        output_path: If provided, save the plot to this path.
    """
    fig, axes = plt.subplots(2, 2, figsize=(12, 8))
    fig.suptitle(f"Histogram Comparison: {label1} vs {label2}", fontsize=14)

    channels = ["Red", "Green", "Blue", "Luminance"]
    colors = ["red", "green", "blue", "gray"]

    for idx, (channel, color) in enumerate(zip(channels, colors)):
        ax = axes[idx // 2][idx % 2]

        if channel in hist1:
            h1_norm = hist1[channel] / (hist1[channel].sum() + 1e-10)
            ax.plot(range(256), h1_norm, color=color, alpha=0.7, label=label1)

        if channel in hist2:
            h2_norm = hist2[channel] / (hist2[channel].sum() + 1e-10)
            ax.plot(
                range(256),
                h2_norm,
                color=color,
                alpha=0.7,
                linestyle="--",
                label=label2,
            )

        ax.set_title(channel)
        ax.set_xlabel("Pixel Value")
        ax.set_ylabel("Normalized Frequency")
        ax.set_xlim(0, 255)
        ax.legend()

    plt.tight_layout()

    if output_path:
        plt.savefig(output_path, dpi=150, bbox_inches="tight")
        print(f"Comparison plot saved to: {output_path}")
    else:
        plt.show()

    plt.close()


def print_report(image_path: str, stats: dict, exposure: dict):
    """Print a formatted analysis report for an image."""
    print(f"\n{'=' * 60}")
    print(f"Image Histogram Analysis Report")
    print(f"File: {image_path}")
    print(f"{'=' * 60}")

    print(f"\nChannel Statistics:")
    print(f"{'Channel':<12} {'Mean':>8} {'Median':>8} {'Mode':>8} {'StdDev':>8}")
    print(f"{'-' * 48}")

    for channel, s in stats.items():
        print(
            f"{channel:<12} {s['mean']:>8.1f} {s['median']:>8d} "
            f"{s['mode']:>8d} {s['std_dev']:>8.1f}"
        )

    print(f"\nExposure Analysis:")
    print(f"  Severity: {exposure['severity']}")
    for issue in exposure["issues"]:
        print(f"  - {issue}")
    print(
        f"  Shadows:    {exposure['shadow_fraction'] * 100:.1f}% "
        f"(clipping: {exposure['shadow_clipping'] * 100:.1f}%)"
    )
    print(
        f"  Midtones:   {exposure['midtone_fraction'] * 100:.1f}%"
    )
    print(
        f"  Highlights: {exposure['highlight_fraction'] * 100:.1f}% "
        f"(clipping: {exposure['highlight_clipping'] * 100:.1f}%)"
    )
    print()


def main():
    parser = argparse.ArgumentParser(
        description="Image Histogram Analyzer - Compute and compare color histograms"
    )
    subparsers = parser.add_subparsers(dest="command", help="Available commands")

    # Analyze command
    analyze_parser = subparsers.add_parser(
        "analyze", help="Analyze histogram of a single image"
    )
    analyze_parser.add_argument("image", help="Path to the image file")
    analyze_parser.add_argument(
        "--plot", "-p", metavar="OUTPUT", help="Save histogram plot to file"
    )
    analyze_parser.add_argument(
        "--threshold",
        type=float,
        default=0.25,
        help="Exposure detection threshold (default: 0.25)",
    )

    # Compare command
    compare_parser = subparsers.add_parser(
        "compare", help="Compare histograms of two images"
    )
    compare_parser.add_argument("image1", help="Path to the first image")
    compare_parser.add_argument("image2", help="Path to the second image")
    compare_parser.add_argument(
        "--plot", "-p", metavar="OUTPUT", help="Save comparison plot to file"
    )

    args = parser.parse_args()

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

    if args.command == "analyze":
        if not Path(args.image).exists():
            print(f"Error: File not found: {args.image}")
            sys.exit(1)

        histograms = compute_histogram(args.image)
        stats = compute_statistics(histograms)
        exposure = detect_exposure_issues(histograms, threshold=args.threshold)

        print_report(args.image, stats, exposure)

        if args.plot:
            plot_histogram(
                histograms,
                title=f"Histogram: {Path(args.image).name}",
                output_path=args.plot,
            )

    elif args.command == "compare":
        for img_path in [args.image1, args.image2]:
            if not Path(img_path).exists():
                print(f"Error: File not found: {img_path}")
                sys.exit(1)

        hist1 = compute_histogram(args.image1)
        hist2 = compute_histogram(args.image2)

        stats1 = compute_statistics(hist1)
        stats2 = compute_statistics(hist2)
        exposure1 = detect_exposure_issues(hist1)
        exposure2 = detect_exposure_issues(hist2)

        print_report(args.image1, stats1, exposure1)
        print_report(args.image2, stats2, exposure2)

        comparison = compare_histograms(hist1, hist2)

        print(f"\n{'=' * 60}")
        print("Histogram Comparison Metrics")
        print(f"{'=' * 60}")

        for channel, metrics in comparison.items():
            print(f"\n  {channel}:")
            print(f"    Correlation:           {metrics['correlation']:.4f}")
            print(f"    Chi-Squared Distance:  {metrics['chi_squared']:.4f}")
            print(f"    Bhattacharyya Dist:    {metrics['bhattacharyya']:.4f}")
            print(f"    Earth Mover's Dist:    {metrics['earth_movers_distance']:.4f}")
            print(f"    Intersection:          {metrics['intersection']:.4f}")

        if args.plot:
            plot_comparison(
                hist1,
                hist2,
                label1=Path(args.image1).name,
                label2=Path(args.image2).name,
                output_path=args.plot,
            )


if __name__ == "__main__":
    main()

# Image Histogram Analyzer (Python - Trial 1)

Computes per-channel color histograms, detects exposure issues, and compares histograms between images.

## Dependencies

- **Pillow** (10.2.0) - Image loading and pixel access
- **matplotlib** (3.8.2) - Histogram visualization and plotting
- **numpy** (1.26.4) - Numerical computation for histogram calculation

## Installation

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

## Usage

### Analyze a single image

```bash
python histogram.py analyze image.jpg
python histogram.py analyze image.jpg --plot output.png
python histogram.py analyze image.jpg --threshold 0.30
```

### Compare two images

```bash
python histogram.py compare image1.jpg image2.jpg
python histogram.py compare image1.jpg image2.jpg --plot comparison.png
```

## Features

- Per-channel (R, G, B) and luminance histogram computation
- Statistical analysis: mean, median, mode, standard deviation
- Exposure issue detection: overexposure, underexposure, clipping, contrast
- Histogram comparison using correlation, chi-squared, Bhattacharyya distance, Earth Mover's distance, and intersection metrics
- Visualization with matplotlib plots

Pillow==10.2.0
matplotlib==3.8.2
numpy==1.26.4