---
name: image
description: 'Resize, crop, convert, compress, and diff raster images. Tools: chyron, diff, qr, transform. Use when a request needs any of these; each tool''s own trigger is in SKILL.md.'
compatibility: 'Requires fragletc and Docker. Hermetic: no network access.'
metadata:
  tags: media
  tools: chyron.py, diff.py, qr.py, transform.py
---

# Image

Resize, crop, convert, compress, and diff raster images.

Every tool below is one executable file beside this `SKILL.md`, in the directory the commands below call `<skill-dir>`. Run it directly. Two host requirements: [`fragletc`](https://github.com/ofthemachine/fraglet) (`curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh && fragletc version`) and Docker; the image, parameters, outputs and network reach are declared in the file itself. Before running a tool, print its contract:

```sh
<skill-dir>/chyron.py --fraglet-help
```

Parameters are passed as `-p name=value` (a `file` parameter takes a host path); declared outputs are copied out with `--output <name>[=<host path>]`. A missing required parameter fails host-side with exit 2 before any container starts; otherwise the tool's own exit code is the run's. A declared output not named with `--output` is produced and discarded (a stderr note says what you could have copied). Add `--receipt run.json` (or set `FRAGLETC_RECEIPT_DIR`) to record the run: the receipt carries the tool's `procedure_hash`, image digest, parameters, and every input and output by content hash, and `receipt/attest.py` can verify it later without re-running anything.

## Tools

### `chyron.py`

Draw a TV-news lower third as a PNG: a studio backdrop, a red kicker box (BREAKING, LIVE, DEVELOPING), the headline bar, an optional ticker strip along the bottom, and the show's name as the corner bug. A still for a satirical or real broadcast; meme/caption puts text on a meme template instead.

Use when a news-style card, chyron, lower third or "breaking news" banner is wanted for a headline.

```sh
<skill-dir>/chyron.py -p headline="<headline>" [-p kicker=BREAKING] [-p ticker="<ticker>"] [-p show=NEWS] [-p width=1280] [-p mood=on-air] --output chyron.png
```

Parameters:
- `headline` (string, required) — The headline across the bar, one line (long ones are shrunk, then cut with an ellipsis)
- `kicker` (string, optional, default `BREAKING`) — The word in the red box before the headline, e.g. BREAKING, LIVE, DEVELOPING
- `ticker` (string, optional) — Text for the ticker strip along the bottom; empty: no ticker
- `show` (string, optional, default `NEWS`) — The show's name, drawn as the corner bug
- `width` (string, optional, default `1280`) — Image width in pixels (height is 9/16 of it)
- `mood` (string, optional, default `on-air`) — How the anchor looks: on-air (composed), frazzled (hair up, tie loose, sweating) or beaming (a grin)

Outputs:
- `chyron.png` — copy out with `--output chyron.png[=<host path>]`

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.

### `diff.py`

Compare two images pixel by pixel and report a machine-readable result (RESULT: IDENTICAL or RESULT: DIFFERENT) with the changed-pixel percentage, maximum channel delta, and bounding box of the change, alongside a PNG that tints every changed region red over the after image. Set tolerance to ignore per-channel noise below a 0-255 threshold, such as antialiasing jitter.

Use when the user wants to know whether two images differ, how much, and where -- visual regression checks, before/after comparisons.

```sh
<skill-dir>/diff.py -p before="<before>" -p after="<after>" [-p tolerance=0] --output diff.png
```

Parameters:
- `before` (file, required) — Baseline image
- `after` (file, required) — Comparison image
- `tolerance` (string, optional, default `0`) — Ignore per-channel deltas below this 0-255 threshold

Outputs:
- `diff.png` — copy out with `--output diff.png[=<host path>]`

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.

### `qr.py`

Make a QR code (PNG or SVG) for a link or any text, computed locally with segno and no network: what it encodes never leaves the container. Text that is a secret (an invite link, a Wi-Fi password) goes on stdin, not in text=: params are written into every receipt in plain text, stdin only as a hash. Prints the code's version and size, and with show=true the code itself, drawn in the terminal.

Use when the user wants a QR code, a scannable link, or a printable code for a URL, an invite, Wi-Fi details or any short text.

```sh
<skill-dir>/qr.py [-p text="<text>"] [-p format=png] [-p scale=8] [-p border=4] [-p error=M] [-p show=false] --output qr.png:optional
```

Parameters:
- `text` (string, optional) — What the code encodes (or pipe it on stdin, which a secret must use)
- `format` (string, optional, default `png`) — png (raster) or svg (vector)
- `scale` (string, optional, default `8`) — Pixels per module (the code's smallest square)
- `border` (string, optional, default `4`) — Quiet zone around the code, in modules (scanners want 4)
- `error` (string, optional, default `M`) — Error correction: L 7%, M 15%, Q 25%, H 30% of the code may be lost and still scan
- `show` (string, optional, default `false`) — Also draw the code on stdout with text blocks, to scan from a terminal
- stdin (optional) — piped input is read in full and hashed into the run's receipt

Outputs:
- `qr.png:optional` — copy out with `--output qr.png:optional[=<host path>]`
- `qr.svg:optional` — copy out with `--output qr.svg:optional[=<host path>]`

Runs in `ofthemachine/python3@sha256:1a6a8e9cd91c93359794245e2a36b883ee54dfef06356ff8be1d4d863ee3823a`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.

### `transform.py`

Resize, crop, convert, and compress images (PNG, JPEG, WebP, GIF, TIFF, BMP), reporting the byte savings on stdout. Set max_dimension to fit the longest edge inside a box while preserving aspect ratio, or give width and/or height directly; crop takes "x,y,w,h" in pixels and is applied before any resize. Shrinks oversized screenshots before they consume an agent's context or get embedded in a PDF.

Use when an image must be resized, cropped, converted to another format, or compressed to a smaller file size.

```sh
<skill-dir>/transform.py -p image="<image>" [-p max_dimension="<max_dimension>"] [-p width="<width>"] [-p height="<height>"] [-p crop="<crop>"] [-p format="<format>"] [-p quality=85] [-p grayscale=false] --output image
```

Parameters:
- `image` (file, required) — Source image mounted at /input/image
- `max_dimension` (string, optional) — Fit longest edge inside this many pixels
- `width` (string, optional) — Target width in pixels
- `height` (string, optional) — Target height in pixels
- `crop` (string, optional) — Crop box as x,y,w,h in pixels (before resize)
- `format` (string, optional) — Output format (PNG, JPEG, WEBP, …); default keeps source
- `quality` (string, optional, default `85`) — JPEG/WebP quality 1-100
- `grayscale` (string, optional, default `false`) — Convert to grayscale when true

Outputs:
- `image` — copy out with `--output image[=<host path>]`

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.
