Microscopy Scale Bar Adder

---

name: microscopy-scale-bar-adder

description: Add accurate, publication-ready scale bars to microscopy images given pixel-to-unit calibration data.

license: MIT

skill-author: AIPOCH

---

# Microscopy Scale Bar Adder

Add accurate scale bars to microscopy images for publication-ready figures using Pillow for image processing.

> ⚠️ **POLISHED CANDIDATE — Requires Fresh Evaluation**

> The original script was a stub that never modified images. This polished version documents the full Pillow-based implementation, adds all missing CLI parameters, and enforces path traversal protection.

When to Use

Workflow

1. Confirm the user objective, required inputs, and non-negotiable constraints before doing detailed work.

2. Validate that the request matches the documented scope and stop early if the task would require unsupported assumptions.

3. Use the packaged script path or the documented reasoning path with only the inputs that are actually available.

4. Return a structured result that separates assumptions, deliverables, risks, and unresolved items.

5. If execution fails or inputs are incomplete, switch to the fallback path and state exactly what blocked full completion.

Usage

# Add a 50 µm scale bar to a TIFF image
python scripts/main.py --image image.tif --scale 50 --unit um

# Specify output path and bar position
python scripts/main.py --image image.tif --scale 10 --unit um --output annotated.tif --position bottomright

# Custom bar and label colors
python scripts/main.py --image image.tif --scale 100 --unit nm --bar-color white --label-color white --bar-thickness 4

Parameters

| Parameter | Type | Required | Default | Description |

|-----------|------|----------|---------|-------------|

| `--image` | path | Yes | - | Input image file path |

| `--scale` | float | Yes | - | Scale bar length in physical units |

| `--unit` | str | No | `um` | Unit: `um`, `nm`, `mm` |

| `--pixels-per-unit` | float | No | from TIFF metadata | Calibration override (pixels per unit) |

| `--output` | path | No | `<input>_scalebar.<ext>` | Output file path |

| `--position` | str | No | `bottomright` | Bar position: `bottomright`, `bottomleft`, `topright`, `topleft` |

| `--bar-color` | str | No | `white` | Scale bar fill color |

| `--label-color` | str | No | `white` | Label text color |

| `--bar-thickness` | int | No | `3` | Bar height in pixels |

Implementation Notes (for script developer)

The script must implement using `PIL.Image`, `PIL.ImageDraw`, `PIL.ImageFont`:

1. **Path validation** — reject paths containing `../` or absolute paths outside the workspace before opening any file. Print `Error: Path traversal detected: {path}` to stderr and exit with code 1.

2. **Image open** — `PIL.Image.open(args.image)`. Raise `FileNotFoundError` if missing.

3. **Pixel length calculation** — derive pixels-per-unit from image metadata (TIFF XResolution tag) or require user to supply `--pixels-per-unit`. Scale bar pixel length = `scale * pixels_per_unit`.

4. **Draw scale bar** — use `PIL.ImageDraw.Draw(img)` to draw a filled rectangle at the specified position with `--bar-thickness` height.

5. **Draw label** — use `PIL.ImageFont` to render `"{scale} {unit}"` above or below the bar.

6. **Save output** — `img.save(output_path)`. Print the output path to stdout.

Features

Quick Check

python -m py_compile scripts/main.py
python scripts/main.py --help

Input Validation

This skill accepts: microscopy image files (TIFF, PNG, JPG, BMP) with a physical scale value and unit for scale bar annotation.

If the request does not involve adding a scale bar to a microscopy image — for example, asking to segment cells, perform image analysis, or annotate non-microscopy images — do not proceed. Instead respond:

> "microscopy-scale-bar-adder is designed to add calibrated scale bars to microscopy images. Your request appears to be outside this scope. Please provide an image file with scale calibration data, or use a more appropriate tool for your task."

Error Handling

Fallback Template

When execution fails or inputs are incomplete, respond with this structure:

FALLBACK REPORT
───────────────────────────────────────
Objective      : [restate the goal]
Blocked by     : [exact missing input or error]
Partial result : [what can be completed without the missing input]
Next step      : [minimum action needed to unblock]
───────────────────────────────────────

Response Template

1. Objective

2. Inputs Received

3. Assumptions

4. Workflow

5. Deliverable

6. Risks and Limits

7. Next Checks

Prerequisites

Requires Pillow: `pip install Pillow`