contact-sheet-image-analysis

Files (1)

• SKILL.md

SKILL.md (first lines)

# Contact Sheet Image Analysis

## Overview

A batch image analysis technique that grids large numbers of images into contact sheets for efficient AI vision review. Instead of reading images one-by-one (which burns tokens, time, and tool calls), this method composites them into 6x6 grids with a position map for drill-down. Validated during the BROGAV Solutions dossier project (June 2026), analyzing 397 images in ~45 minutes vs. an estimated 8+ hours individually.

## When to Use

- You have 50+ images to analyze and need to extract intelligence from all of them
- You are looking for logos, people, products, text, events, or patterns across a large image set
- You want to reduce AI vision API/tool calls by 80-95%
- You are processing images extracted from an MHTML archive, scraped gallery, or document dump
- You need to categorize images before deciding which ones deserve full-resolution analysis

## Prerequisites

- **Python 3.10+**
- **Libraries:** `Pillow` (PIL fork)
- **AI vision capability:** Claude, GPT-4V, or any multimodal model that can read images
- **Disk space:** Contact sheets add ~5-10% to the total image set size
- **Memory:** Processing 400+ images requires ~500MB RAM for thumbnail generation

## Method

### Step 1: Auto-Classify Images

Before gridding, classify every image by its physical properties. This determines sort order and helps the AI agent know what to expect in each cell.

```python
from PIL import Image
from pathlib import Path

def classify_image(filepath):
    """
    Classify an image by dimensions, file size, and properties.
    Returns a category string used for sorting and analysis context.
    """
    filepath = Path(filepath)
    try:
        with Image.open(filepath) as img:
            w, h = img.size
            has_alpha = img.mode in ("RGBA", "LA", "PA")
            size_kb = filepath.stat().st_size / 1024
    except Exception:
        return "skip_corrupt"

    if size_kb < 5:
        return "skip_tiny"       # Tracking pixels, spacer GIFs
    if w < 50 or h < 50:
        return "skip_icon"       # Favicons, tiny UI elements
    
    ratio = w / h if h > 0 else 1.0
    
    if ratio > 2.5:
        return "banner_wide"     # LinkedIn banners, ad units
    if ratio < 0.4:
        return "infographic_tall"  # Vertical infographics, screenshots
    if has_alpha and size_kb < 100:
        return "logo_or_graphic" # Logos, icons with transparency
    if size_kb > 200:
        return "photo_large"     # High-res photos, most content-rich
    if size_kb > 50:
        return "photo_medium"    # Standard photos
    if 0.9 < ratio < 1.1:
        return "photo_square"    # Profile photos, thumbnails
    return "photo_medium"
```

**Category guide:**

| Category | Typical Content | Intelligence Value |
|---|---|---|
| `photo_large` | Event photos, product shots, team photos | High -- most findings come from here |
| `photo_medium` | General posts, screenshots, shared content | Medium |
| `banner_wide` | LinkedIn banners, promotional graphics | Low-Medium -- may show branding |
| `infographic_tall` | Data visualizations, process diagrams | Medium-High -- dense information |
| `logo_or_graphic` | Company logos, partner logos, certificates | Medium -- confirms relationships |
| `photo_square` | Profile pics, headshots | Low unless identifying people |
| `skip_tiny` | Tracking pixels, 1x1 GIFs | None -- exclude |
| `skip_icon` | Favicons, UI elements | None -- exclude |
| `skip_corrupt` | Unreadable files | None -- exclude |

### Step 2: Sort by Size Descending

Largest files contain the most visual information. Sorting by size ensures the AI agent sees the most content-rich images first.

```python
def collect_and_sort_images(image_dir):
    """Collect all images, classify, filter, and sort by size descending."""
    image_dir = Path(image_dir)
    files = []
    for ext in ("*.jpg", "*.jpeg", "*.png", "*.gif", "*.webp", "*.bmp"):
        files.extend(image_dir.glob(ext))
    
    classified = []
    for f in files:
        cat = classify_image(f)
        if cat.startswith("skip_"):
            continue
        classified.append({
            "path": f,
            "size_kb": round(f.stat().st_size / 1024, 1),
            "category": cat,
        })
    
    # Sort by file size descending
    classified.sort(key=lambda x: -x["size_kb"])
    return classified
```

### Step 3: Generate Contact Sheets

Create 6x6 grids (36 images per sheet) using Pillow.

```python
def make_contact_sheets(
    image_list,
    output_dir,
    cols=6,
    rows=6,

From ever-just/agentskills, MIT.

More from ever-just/agentskills