@saifymatteo/pi-vision 0.0.0-stage → 0.1.0

package/skills/vision-tools/references/restore-graphic.md

@@ -0,0 +1,92 @@
+# Extracting or rebuilding a graphic asset
+
+**When to use**: the deliverable is an isolated icon, logo, illustration,
+decorative mark, or other visual asset as a transparent PNG or SVG. For a full
+page or component, read `restore-ui.md` and use this workflow only for the
+individual visual assets it identifies.
+
+## Choose the least destructive representation
+
+Use this order:
+
+1. Reuse the original source asset if it already exists in the project.
+2. Extract a transparent PNG from the reference when the visual only needs to
+   be displayed at the captured size. This preserves the original pixels and
+   is the default for screenshot-only brand artwork.
+3. Trace an irregular, flat, high-contrast shape when SVG is required.
+4. Hand-write simple editable geometry or stroke icons, using the trace or
+   pixel measurements as evidence rather than visual estimates.
+
+## Extract a transparent PNG
+
+The final extraction region must be tight around the target ink. A loose crop
+that touches neighboring text, borders, or decoration may preserve those
+pixels as foreground.
+
+```bash
+# Known tight region
+python3 scripts/extract_fg.py shot.png \
+  --region X1,Y1,X2,Y2 -o asset.png
+
+# Dark or gray line art
+python3 scripts/extract_fg.py shot.png \
+  --region X1,Y1,X2,Y2 --mode dark -o asset.png
+
+# Center and enlarge a small visual before automatic extraction
+crop shot.png --region X1,Y1,X2,Y2 --scale 4 -o work/asset4x.png
+python3 scripts/extract_fg.py work/asset4x.png
+```
+
+Use `--exclude-color '#RRGGBB'` when a connected background color would
+otherwise be retained. If automatic centering is wrong, provide a tighter
+region or a target box rather than repeatedly widening the crop.
+
+Inspect the result on both light and dark backgrounds. Confirm complete ink,
+clean alpha edges, and no neighboring fragments before reuse.
+
+## Rebuild an SVG only when the deliverable needs one
+
+```bash
+trace asset.png -o asset.svg
+trace asset.png --polygon -o asset.svg
+trace shot.png --region X1,Y1,X2,Y2 -o asset.svg
+```
+
+Ship traced paths directly for organic or irregular shapes. For rectangles,
+circles, pills, and other simple editable geometry, use the trace as an
+approximate outline and write the simpler SVG yourself. Filtering, upscaling
+and curve fitting can change boundaries; measure pixels directly when exact
+dimensions matter.
+
+A small stroke icon often suits a hand-written SVG: tracing outlines both
+sides of the raster stroke, while the desired asset is normally a centerline
+path with `stroke` and `fill="none"`. If an outline would help, use
+`trace --polygon` as a reference for endpoints and corners, then write and
+render the clean centerline path.
+
+When reusing traced paths:
+
+- Composite transparent SVG output on the intended background before judging
+  it; transparent regions may appear black in some viewers.
+- Copy each path's `transform` together with its `d` data. Dropping the
+  transform displaces otherwise correct geometry.
+- Keep opposite-winding subpaths together so holes remain holes.
+
+## Verify
+
+Render the asset at its intended size and compare it with the same tight box
+from the reference. Use an overlay or `scripts/pixel_diff.py` to locate missing
+parts, contamination, wrong scale, or displaced paths. Judge the asset at its
+actual delivery size as well as zoomed in; a technically detailed SVG that
+looks worse at 16px is not an improvement.
+
+## Boundaries
+
+- Whole screenshots and photos do not trace usefully.
+- Low-contrast art may disappear during binarization. Tighten the region,
+  increase scale, or invert light-on-dark input before reaching for color
+  tracing.
+- Use color tracing only for genuinely multicolor artwork; antialiased single-
+  color input can otherwise fragment into many gray-level paths.
+- If the visual contains live text, controls, or data-driven content, rebuild
+  those parts natively and use the extracted asset only for the static artwork.

package/skills/vision-tools/references/restore-structure.md

@@ -0,0 +1,47 @@
+# Turning a visual diagram into structured code
+
+**When to use**: the task is converting a sketch, flowchart, architecture
+diagram, or whiteboard into Mermaid, Graphviz, JSON, or another structured
+representation. The goal is semantic and topological fidelity, not matching
+the source renderer pixel for pixel.
+
+## Steps
+
+1. Inspect the image natively with the main agent's image reader for diagram
+   type, reading direction, major groups, and visual conventions.
+2. Inventory nodes and labels. Preserve visible spelling, punctuation, and
+   abbreviations verbatim; write `[unreadable]` instead of guessing.
+3. For ambiguous arrows, connectors, labels, legends, or group boundaries,
+   crop the relevant region and read it natively. Use `detect`, `ground`, or
+   `glance` (including OCR) only when a specialist pass would resolve a
+   remaining question. Model boxes are estimates: they can select the wrong
+   object or omit substantial parts, so verify them against the image.
+4. Build an explicit intermediate inventory before writing the output:
+   nodes, labels, groups, edges, directions, and edge labels.
+5. Generate the Mermaid, Graphviz, or requested structure from that inventory.
+
+## Verify structure, not pixels
+
+Render the result, inventory it again, and compare these facts with the
+reference:
+
+- node count and label set
+- group membership and nesting
+- edge list and direction
+- edge labels and branch conditions
+- start/end or input/output roles
+
+Pixel differences are expected because the target renderer chooses its own
+fonts, spacing, and routing. A missing node or reversed arrow is a failure even
+when the two images look broadly similar; a different curve or gap is not a
+failure when the structure is correct.
+
+## Boundaries
+
+- Do not tidy labels, expand abbreviations, or silently repair wording unless
+  the user asks for editorial cleanup.
+- Do not infer an edge from proximity alone. If its endpoint or direction is
+  unclear, zoom into the connector and mark unresolved facts explicitly.
+- If the user wants a visual SVG copy rather than structured code, follow
+  `restore-graphic.md` instead. `trace` is approximate vectorization, not
+  exact measurement or a reliable source of graph topology.

package/skills/vision-tools/references/restore-ui.md

@@ -0,0 +1,200 @@
+# Rebuilding a UI from a reference image
+
+**When to use**: the task is turning a screenshot or design image into a
+page, component, or application UI in HTML/CSS or the project's existing
+frontend stack. Checking an existing implementation against its reference is
+the same workflow entered at Verify. For an isolated icon, logo, or
+illustration, read `restore-graphic.md`; for Mermaid, Graphviz, or another
+structured diagram, read `restore-structure.md`.
+
+## Choose the restore mode
+
+- Use **fast restore mode** when the user asks for a quick, rough,
+  approximate, prototype, or first-pass reconstruction, or explicitly values
+  speed over fidelity. Its target is a recognizable screenshot in about three
+  minutes when the project already runs.
+- Use the **standard restore workflow** below when the user asks for close,
+  precise, pixel-level, or production-ready alignment, or does not opt into a
+  faster approximation.
+
+## Fast restore mode: first screenshot in about three minutes
+
+Fast mode preserves the page's hierarchy, major regions, visible text, and
+primary state. It deliberately approximates fine spacing, exact colors,
+typography, shadows, decorative details, and icon geometry.
+
+### Hard limits
+
+1. Inspect the existing frontend stack, component library, icon set, source
+   assets, and design tokens before writing code, but stop searching as soon as
+   a usable local primitive is found.
+2. Inspect the reference natively with the main agent's image reader for
+   hierarchy, major regions, visible text, and state. Crop and read a region
+   natively only when a material detail remains unresolved; skip exhaustive
+   region-by-region inventory. Normally one or two inspection rounds suffice.
+3. Do not use `trace`, foreground extraction, repeated color sampling, or
+   iterative `pixel_diff` work in fast mode. Those are fidelity tools and will
+   consume the delivery window.
+
+### Build the approximation
+
+1. Implement the largest layout regions first, then visible text, primary
+   controls, and the most important state. Ignore details that are only visible
+   when zoomed in.
+2. Reuse the project's existing components and CSS tokens. If its frontend or
+   icon library contains a reasonably similar component or icon, use it
+   directly instead of recreating the reference. Prefer an approximate library
+   icon over cropping, tracing, or hand-drawing a new one.
+3. Use nearby existing palette tokens or visually similar CSS values. Exact
+   sampled hex values, gradients, subtle borders, and shadow opacity are out of
+   scope unless one of them defines the whole composition.
+4. Keep text and controls native, selectable, and interactive. Fast mode relaxes
+   visual fidelity, not basic UI behavior.
+
+### Render once, fix once, deliver
+
+1. Render the target viewport with `scripts/html_shot.py` or the project's
+   existing browser setup.
+2. Inspect the screenshot once. If there is an obvious structural failure such
+   as a missing major region, broken wrapping, or a wildly wrong scale, make
+   one focused correction and render once more.
+3. Deliver the screenshot. Stop instead of spending the remaining time on
+   small color, icon, font, shadow, radius, or spacing differences.
+
+A practical time box is roughly 30 seconds for project and native image
+inspection, 90 seconds for implementation, and the remaining minute for startup,
+rendering, one correction, and screenshot delivery. Dependency installation or
+a project that does not already run may extend that target; do not compensate
+by silently switching back to a long precision loop.
+
+## Standard restore workflow
+
+### Core strategy: code-native UI plus screenshot-backed visuals
+
+Do not choose one reconstruction mode for the whole page. Classify each
+element separately. Most finished pages should combine both kinds:
+
+| Kind | Build it this way | Typical examples |
+|---|---|---|
+| **Code-native component** | Reuse the project's component library or build it with semantic HTML, CSS, and simple SVG primitives | layout, text, buttons, inputs, cards, tabs, dividers, backgrounds, simple geometric badges |
+| **Screenshot-backed visual** | Extract the original pixels, remove the background when needed, and place the result as an image asset | logos, proprietary icons, illustrations, decorative artwork, textures, complex static marks |
+
+Use this decision order for every element:
+
+1. **Reuse an existing component or source asset from the project.** Search
+   before recreating anything.
+2. **Use a code-native component** when the element contains text, accepts
+   input, changes state, must respond to layout, or is simple to express with
+   the project's normal primitives.
+3. **Use a screenshot-backed visual** when it is static, visually distinctive,
+   expensive to redraw, and no source asset exists.
+4. Rebuild a vector only when the user requires SVG/editability, the visual
+   must scale beyond the screenshot resolution, or extraction cannot isolate
+   it cleanly. Follow `restore-graphic.md` for that branch. `trace` provides
+   approximate vectorization, not exact geometric measurement.
+
+Never flatten text, controls, or a large layout block into a screenshot. Never
+redraw extractable brand artwork merely to make the implementation look more
+"native". For a complex widget, keep the shell, text, and interaction native;
+use an extracted image only for its static decorative layer.
+
+## Steps
+
+### 1. Inspect the reference and target project
+
+Read the reference directly at its current path. Copy it to durable work
+storage only when it must persist beyond the temporary file's lifetime.
+Inspect the existing stack, component library, fonts, icons, images, and
+design tokens before writing replacements.
+
+### 2. Establish the coordinate system
+
+Record the reference image dimensions and the target viewport. Screenshots may
+be HiDPI: `detect`, `ground`, and `crop` report image pixels, while CSS uses
+logical pixels. Derive the scale from the actual image and viewport dimensions;
+do not assume a fixed 2x ratio.
+
+### 3. Inventory the UI outside-in
+
+1. Inspect the image natively for hierarchy, component types, visible text,
+   state, and styling; list the major regions outside-in.
+2. For unresolved details, crop the relevant region and read it natively.
+3. Use specialist tools only for a remaining concrete need: `detect` for an
+   inventory, `glance` for a second opinion or OCR, `ground` for a target box.
+
+Model boxes are estimates and can identify the wrong element or miss large
+parts of it. Verify them against the pixels before using them for crops or
+layout; they are not measured boundaries.
+
+### 4. Classify before implementing
+
+Make a short element list with one of these decisions: reuse existing source,
+code-native, screenshot-backed, or hybrid. This prevents two costly mistakes:
+rebuilding complex artwork from scratch and turning functional UI into static
+image patches.
+
+### 5. Extract screenshot-backed visuals
+
+Use a padded crop only to inspect and center the target. Before foreground
+extraction, tighten the final region to the visual's own ink; adjacent text or
+rules inside the region can become foreground components too.
+
+```bash
+crop shot.png --region X1,Y1,X2,Y2 --scale 4 -o work/icon4x.png
+python3 scripts/extract_fg.py work/icon4x.png
+
+# Or extract directly from a known tight region:
+python3 scripts/extract_fg.py shot.png \
+  --region X1,Y1,X2,Y2 -o work/icon.png
+python3 scripts/extract_fg.py shot.png \
+  --region X1,Y1,X2,Y2 --mode dark -o work/logo.png
+```
+
+Inspect the transparent result before use. Confirm that the whole visual is
+present, no neighboring text or border leaked in, and the alpha edge remains
+clean. When extracting several assets, inspect them together in a contact
+sheet instead of checking them from filenames alone.
+
+### 6. Implement the native frame
+
+- Follow the project's existing framework and component patterns.
+- Build content, interaction, responsive layout, borders, shadows, and simple
+  shapes natively.
+- Use `scripts/dominant_colors.py` when exact background, text, or accent
+  values matter; visual inspection can name a color but cannot measure its
+  numeric value.
+- Place extracted assets with explicit logical dimensions. Preserve their
+  aspect ratio and avoid baking surrounding whitespace into the asset.
+- Match structure and proportions before tuning small spacing.
+
+## Verify and converge by impact
+
+For an existing implementation, start here.
+
+1. Render at the same logical viewport with `scripts/html_shot.py` or the
+   project's browser test setup.
+2. Compare the render and reference at the same dimensions. Inspect them side
+   by side; use `scripts/pixel_diff.py` to locate differences that are hard to
+   spot or explain.
+3. Fix material discrepancies: missing or wrong content, incorrect hierarchy,
+   broken wrapping, visibly wrong alignment or scale, wrong component state,
+   distorted assets, and clearly different primary colors.
+4. Re-render after a meaningful fix. Continue while the comparison exposes a
+   user-visible defect; stop when the remaining difference is font
+   rasterization, antialiasing, subpixel placement, or another imperceptible
+   rendering detail.
+
+`pixel_diff` is a locator, not the acceptance target. Do not keep iterating only
+to lower its aggregate percentage, and do not promise zero-difference output
+from a screenshot without a separately scoped browser, font, viewport, and
+rendering environment.
+
+## Boundaries
+
+- Do not ship a screenshot of the whole page as the implementation.
+- Do not use screenshot-backed text or controls that must remain selectable,
+  accessible, interactive, localized, or responsive.
+- Do not stretch an extracted bitmap beyond the resolution supported by the
+  reference. Obtain a source asset or rebuild a vector when it must scale.
+- Always compare against the original reference, never only against an earlier
+  version of your own render.

package/skills/vision-tools/scripts/dominant_colors.py

@@ -0,0 +1,224 @@
+#!/usr/bin/env python3
+"""dominant_colors: a region's significant colours, and the exact value among a candidate palette.
+
+Two halves of one job. First you extract the region's palette -- downsample,
+quantize, merge near-duplicates -- so you can see which colours are actually
+there and how much of the region each one owns. That share histogram is the
+role map: a background takes a big share, an accent a small one.
+
+A vision model (glance) names those clusters in prose ("white", "light gray",
+"orange") but not their values. So for the value itself you supply the
+candidate palette your label implies ("light gray" -> #F9FAFA / #F5F5F5 /
+#F3F3F3 / #EDEDED) and this script decides from the pixels: each candidate is
+scored by a distance filter over the region's pixels, and the best one wins.
+The label comes from the model; the number always comes from here.
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+try:
+    from PIL import Image, ImageChops
+except ImportError:
+    Image = None
+    ImageChops = None
+
+
+def load_rgb(path: Path) -> "Image.Image":
+    # Composite transparency on white the way a viewer would; unflattened
+    # alpha reads as black and skews every colour statistic.
+    image = Image.open(path)
+    if image.mode in ("RGBA", "LA", "P"):
+        image = image.convert("RGBA")
+        canvas = Image.new("RGB", image.size, "white")
+        canvas.paste(image, mask=image.split()[-1])
+        image = canvas
+    else:
+        image = image.convert("RGB")
+    return image
+
+
+def parse_region(region: str, width: int, height: int) -> tuple[int, int, int, int]:
+    try:
+        x1, y1, x2, y2 = (int(v) for v in region.split(","))
+    except ValueError:
+        raise ValueError("--region expects four integers: X1,Y1,X2,Y2 (pixels)") from None
+    box = (max(0, min(x1, x2)), max(0, min(y1, y2)),
+           min(width, max(x1, x2)), min(height, max(y1, y2)))
+    if box[2] <= box[0] or box[3] <= box[1]:
+        raise ValueError(f"--region {region} is empty after clamping to {width}x{height}")
+    return box
+
+
+def hex_of(rgb: tuple[int, int, int]) -> str:
+    return "#{:02X}{:02X}{:02X}".format(*rgb)
+
+
+def parse_hex(text: str) -> tuple[int, int, int]:
+    value = text.strip().lstrip("#")
+    if len(value) != 6:
+        raise ValueError(f"invalid colour {text!r}: expected #RRGGBB")
+    return (int(value[0:2], 16), int(value[2:4], 16), int(value[4:6], 16))
+
+
+def chebyshev(a: tuple[int, int, int], b: tuple[int, int, int]) -> int:
+    return max(abs(x - y) for x, y in zip(a, b))
+
+
+def bar(share: float, max_share: float, width: int = 20) -> str:
+    fill = round(share / max_share * width) if max_share else 0
+    return "#" * fill
+
+
+class _Cluster:
+    __slots__ = ("rgb", "count")
+
+    def __init__(self, rgb: tuple[int, int, int], count: int) -> None:
+        self.rgb = rgb
+        self.count = count
+
+
+def extract(image: "Image.Image", box: tuple[int, int, int, int], top: int,
+            quantize_k: int, max_pixels: int, merge_tol: int) -> list[_Cluster]:
+    """Downsample, quantize, merge near-duplicates; return clusters sorted by count."""
+    crop = image.crop(box)
+    width, height = crop.size
+    scale = min(1.0, max_pixels / max(width, height))
+    if scale < 1.0:
+        crop = crop.resize((max(1, round(width * scale)), max(1, round(height * scale))), Image.LANCZOS)
+    quantized = crop.quantize(colors=quantize_k, method=Image.MEDIANCUT)
+    palette = quantized.getpalette()
+    clusters: list[_Cluster] = []
+    for count, index in sorted(quantized.getcolors(maxcolors=quantize_k), reverse=True):
+        rgb = (palette[index * 3], palette[index * 3 + 1], palette[index * 3 + 2])
+        for existing in clusters:
+            if chebyshev(rgb, existing.rgb) <= merge_tol:
+                total = existing.count + count
+                existing.rgb = tuple(
+                    round((existing.rgb[i] * existing.count + rgb[i] * count) / total)
+                    for i in range(3))
+                existing.count = total
+                break
+        else:
+            clusters.append(_Cluster(rgb, count))
+    clusters.sort(key=lambda c: c.count, reverse=True)
+    return clusters
+
+
+def pick(image: "Image.Image", box: tuple[int, int, int, int], candidates: list[str],
+         tol: int) -> tuple[list[dict], dict, dict]:
+    """Score each candidate by how close the region's pixels are to it."""
+    crop = image.crop(box)
+    width, height = crop.size
+    total = width * height
+    bands = crop.split()
+    rows = []
+    for text in candidates:
+        rgb = parse_hex(text)
+        farthest = None
+        for band, value in zip(bands, rgb):
+            diff = ImageChops.difference(band, Image.new("L", (width, height), value))
+            farthest = diff if farthest is None else ImageChops.lighter(farthest, diff)
+        histogram = farthest.histogram()
+        mean_distance = sum(i * count for i, count in enumerate(histogram)) / total
+        hard = sum(count for i, count in enumerate(histogram) if i <= tol)
+        # Soft support: pixels closer to the candidate weigh more, so a match
+        # is not a binary in/out -- a candidate exactly on the colour wins over
+        # a near neighbour that is also inside the tolerance.
+        weighted = sum(max(0, tol - i) * count for i, count in enumerate(histogram))
+        rows.append({"text": text, "rgb": rgb, "mean_distance": mean_distance,
+                     "hard": hard, "weighted": weighted,
+                     "share": hard / total * 100})
+    winner = max(rows, key=lambda r: (r["weighted"], r["hard"]))
+    closest = min(rows, key=lambda r: r["mean_distance"])
+    return rows, winner, closest
+
+
+def format_extract(clusters: list[_Cluster], top: int, box: tuple[int, int, int, int],
+                   merge_tol: int) -> list[str]:
+    total = sum(c.count for c in clusters)
+    if not total:
+        return ["(region has no pixels)"]
+    width = box[2] - box[0]
+    height = box[3] - box[1]
+    max_share = max(c.count / total for c in clusters) * 100
+    lines = [f"region {box[0]},{box[1]},{box[2]},{box[3]} - {width}x{height} px",
+             f"top {top} of {len(clusters)} clusters (merged at distance <= {merge_tol}):"]
+    for cluster in clusters[:top]:
+        share = cluster.count / total * 100
+        lines.append(f"{hex_of(cluster.rgb)}  {share:5.1f}%  {bar(share, max_share)}")
+    return lines
+
+
+def format_pick(rows: list[dict], winner: dict, closest: dict,
+                box: tuple[int, int, int, int], tol: int) -> list[str]:
+    width = box[2] - box[0]
+    height = box[3] - box[1]
+    total = width * height
+    max_share = max(r["share"] for r in rows) or 1.0
+    max_wt = max(r["weighted"] for r in rows)
+    lines = [f"region {box[0]},{box[1]},{box[2]},{box[3]} - {width}x{height} px ({total} px sampled)",
+             "candidate   share   mean_d  wt    bar"]
+    for row in rows:
+        mark = "*" if row is winner else " "
+        wt = (row["weighted"] / max_wt * 100) if max_wt else 0.0
+        lines.append(f"{mark}{row['text']:<9} {row['share']:5.1f}%  {row['mean_distance']:4.1f}  "
+                     f"{wt:4.0f}%  "
+                     f"{bar(row['share'], max_share)}")
+    if winner["hard"] == 0:
+        lines.append(f"note: no candidate is within distance <= {tol} of the region; "
+                     f"closest by mean distance is {closest['text']}")
+    else:
+        lines.append(f"winner: {winner['text']} (* in table) - wt is soft-match closeness, "
+                     f"so the winner need not have the highest share; "
+                     f"{winner['share']:.1f}% of region pixels within distance <= {tol}")
+    return lines
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="dominant_colors",
+        description="Extract a region's significant colours, or pick the concrete value among a candidate palette",
+    )
+    parser.add_argument("image", type=Path, help="the image")
+    parser.add_argument("--region", metavar="X1,Y1,X2,Y2",
+                        help="restrict to this pixel box (e.g. from ground); default: whole image")
+    parser.add_argument("--candidates", metavar="LIST",
+                        help="pick mode: comma-separated candidate palette, e.g. #F9FAFA,#F5F5F5,#F3F3F3,#EDEDED")
+    parser.add_argument("--top", type=int, default=5, help="how many significant clusters to show (default: 5)")
+    parser.add_argument("--quantize", type=int, default=16,
+                        help="palette size before merging near-duplicates (default: 16)")
+    parser.add_argument("--max-pixels", type=int, default=96,
+                        help="downsample the crop to at most this on the long side (default: 96)")
+    parser.add_argument("--merge-tol", type=int, default=8,
+                        help="merge clusters whose centres are within this per-channel distance (default: 8)")
+    parser.add_argument("--tol", type=int, default=16,
+                        help="pick mode: per-channel distance for 'matches this candidate' (default: 16)")
+    args = parser.parse_args()
+
+    if Image is None:
+        parser.exit(1, "dominant_colors: requires Pillow; install the optional dependency pillow first\n")
+    path = args.image.expanduser()
+    if not path.is_file():
+        parser.exit(1, f"dominant_colors: image not found: {path}\n")
+    try:
+        image = load_rgb(path)
+        width, height = image.size
+        box = parse_region(args.region, width, height) if args.region else (0, 0, width, height)
+        if args.candidates:
+            candidates = [candidate.strip() for candidate in args.candidates.split(",") if candidate.strip()]
+            if not candidates:
+                parser.exit(1, "dominant_colors: --candidates needs at least one #RRGGBB\n")
+            rows, winner, closest = pick(image, box, candidates, args.tol)
+            print("\n".join(format_pick(rows, winner, closest, box, args.tol)))
+        else:
+            clusters = extract(image, box, args.top, args.quantize, args.max_pixels, args.merge_tol)
+            print("\n".join(format_extract(clusters, args.top, box, args.merge_tol)))
+    except ValueError as exc:
+        parser.exit(1, f"dominant_colors: {exc}\n")
+
+
+if __name__ == "__main__":
+    main()