gig-line/Tools/facade_detail_concepts.py

#!/usr/bin/env python3
"""Generate architectural detail studies from the local reference photography.

Each study takes one photograph we already hold (`Art/reference/`, gitignored) as
the geometric anchor and asks an image model to re-stage it as a clean
architectural detail plate — no crowd, no staging, straight-on, evenly lit — so
the modelling pass has something to measure against instead of a tourist photo.

    python3 Tools/facade_detail_concepts.py --list
    python3 Tools/facade_detail_concepts.py --only door-recess,parapet-motto
    python3 Tools/facade_detail_concepts.py --all
    python3 Tools/facade_detail_concepts.py --all --model google/gemini-2.5-flash-image

Output: `Art/reference/facade-details/<study>.png` plus a `<study>.refgen.json`
sidecar recording the model, the source photograph, the prompt and the SHA-256 of
the result. `Art/reference/` is gitignored, so **neither the images nor the
sidecars are committed** — they are local working material. The study list and
the tool are the committed part.

Design notes
------------
* Standard library only: the OpenRouter chat-completions call is `urllib`, and
  the returned `data:` URL is decoded with `base64` and written straight to disk.
* An existing output is never overwritten; `-v2`, `-v3` … are used instead, so
  re-running after a prompt edit keeps both studies comparable.
* Generation costs money, so it is never automatic: `--list` is free, and every
  generating run prints the model and the study count first.
* The token is read from `OPENROUTER_API_KEY` or the ignored `.env` and is never
  written to a sidecar or a log line.
"""

from __future__ import annotations

import argparse
import base64
import json
import os
import re
import sys
import time
import urllib.error
import urllib.request

ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
REFERENCE_DIR = os.path.join(ROOT, "Art", "reference")
OUT_DIR = os.path.join(REFERENCE_DIR, "facade-details")
API_URL = "https://openrouter.ai/api/v1/chat/completions"
DEFAULT_MODEL = "google/gemini-2.5-flash-image"

# The instruction appended to every study. Kept identical to the sibling
# project's convention so the two sets stay comparable: the photograph fixes the
# geometry, the prompt only restages light, weather, people and surface.
ANCHOR_SUFFIX = (
    "Use the attached reference photograph as the fixed source of geometry and "
    "composition: keep the building's proportions, column rhythm, band heights, "
    "signage placement and camera angle exactly as photographed. Only restage "
    "lighting, weather, people and surface condition where the request asks for "
    "it. Do not invent extra storeys, wings or ornaments that the photo does not "
    "show."
)

# name -> (reference photo relative to Art/reference/, what the study must show)
STUDIES: dict[str, tuple[str, str]] = {
    "door-recess": (
        "el-capitan-entrance/01-hollywood-el-capitan-entrance-detail.jpg",
        "A clean architectural detail plate of exactly the subject in the "
        "reference photograph. Render it as an even-daylight stone study: crisp "
        "surface carving, readable depth of every recess and moulding, no people, "
        "no signage or banners in front of it, no shop clutter, straight-on to the "
        "subject.",
    ),
    "entrance-wide": (
        "el-capitan-entrance/01-hollywood-el-capitan-entrance.jpg",
        "A straight-on architectural study of the street entrance in the "
        "reference photograph, the portal group centred and filling the frame, "
        "threshold and pavement readable, no pedestrians or vehicles, even "
        "overcast daylight, stone surface legible.",
    ),
    "column-order": (
        "hollywood/el-capitan-facade-day-wikimedia-2009-10-27.jpg",
        "A close architectural study of the column order visible in the "
        "reference photograph: the base, shaft and capital read clearly, "
        "neighbouring columns framing it. Straight-on, evenly lit, stone surface "
        "and carving legible, no people or banners.",
    ),
    "entablature-cornice": (
        "hollywood/el-capitan-facade-day-wikimedia-2009-10-27.jpg",
        "An architectural detail study of the horizontal stone bands above the "
        "columns in the reference photograph: every band edge and the projecting "
        "cornice with its shadow line. The layered depth of the stone must be "
        "readable, flat even light, no people.",
    ),
    "parapet-motto": (
        "hollywood/el-capitan-facade-day-wikimedia-2009-10-27.jpg",
        "An architectural study of the parapet above the colonnade in the "
        "reference photograph: the inset panel, any round medallions beside it "
        "and the coping at the top. Lettering on the panel is blocked out as "
        "unreadable texture. Flat even light, no people.",
    ),
    "window-rhythm": (
        "hollywood/el-capitan-facade-day-wikimedia-2009-10-27.jpg",
        "An architectural study of the wall surface behind and between the "
        "columns in the reference photograph: the opening or window rhythm and "
        "the reveal depth. Straight-on, no people, no banners covering the wall.",
    ),
    "street-wall": (
        "hollywood/el-capitan-theatre-blade-sign-day-wikimedia-2008-10.jpg",
        "A clean street-wall study from the opposite pavement, as framed in the "
        "reference photograph: the building line, the parapet heights of the "
        "neighbouring buildings, the shopfront line and the pavement depth. No "
        "crowd, even daylight.",
    ),
    "banner-detail": (
        "el-capitan-premiere/02-premiere-of-spielberg-s-west-side-story---el-capitan---holly.jpg",
        "An architectural study of the vertical banner in the reference "
        "photograph: how it is fixed, its proportions against the column behind "
        "it, and how it sits against the stone. Daylight, no crowd.",
    ),
}


def load_token() -> str:
    token = os.environ.get("OPENROUTER_API_KEY")
    if token:
        return token.strip()
    env_path = os.path.join(ROOT, ".env")
    if os.path.exists(env_path):
        with open(env_path, encoding="utf-8") as handle:
            for line in handle:
                line = line.strip()
                if line.startswith("OPENROUTER_API_KEY="):
                    return line.split("=", 1)[1].strip().strip('"').strip("'")
    raise SystemExit("no OpenRouter key: set OPENROUTER_API_KEY or add it to .env")


def build_prompt(study: str) -> str:
    """The full prompt for a study: its request plus the fixed anchor suffix."""
    if study not in STUDIES:
        raise KeyError(f"unknown study {study!r}; known: {sorted(STUDIES)}")
    return f"{STUDIES[study][1]}\n\n{ANCHOR_SUFFIX}"


def reference_path(study: str) -> str:
    return os.path.join(REFERENCE_DIR, STUDIES[study][0])


def missing_references() -> list[str]:
    """Studies whose source photograph is not present locally."""
    return [name for name in STUDIES if not os.path.isfile(reference_path(name))]


def next_free_path(study: str, directory: str = OUT_DIR) -> str:
    """`<study>.png`, or `<study>-v2.png`, `-v3` … if the name is taken."""
    base = os.path.join(directory, f"{study}.png")
    if not os.path.exists(base):
        return base
    index = 2
    while True:
        candidate = os.path.join(directory, f"{study}-v{index}.png")
        if not os.path.exists(candidate):
            return candidate
        index += 1


def data_url(path: str) -> str:
    suffix = os.path.splitext(path)[1].lower()
    mime = {".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".png": "image/png"}.get(suffix)
    if not mime:
        raise SystemExit(f"unsupported reference type: {path}")
    with open(path, "rb") as handle:
        return f"data:{mime};base64,{base64.b64encode(handle.read()).decode('ascii')}"


def decode_image(payload: dict) -> bytes:
    """Extract the returned image bytes from a chat-completions payload."""
    message = (payload.get("choices") or [{}])[0].get("message", {})
    urls = [item.get("image_url", {}).get("url", "")
            for item in (message.get("images") or []) if isinstance(item, dict)]
    if not urls:
        match = re.search(r"data:image/[a-z]+;base64,[A-Za-z0-9+/=]+",
                          str(message.get("content") or ""))
        if match:
            urls.append(match.group(0))
    if not urls or not urls[0]:
        raise SystemExit(f"model returned no image data: {json.dumps(payload)[:400]}")
    url = urls[0]
    if url.startswith("data:"):
        return base64.b64decode(url.split(",", 1)[1])
    with urllib.request.urlopen(urllib.request.Request(url), timeout=120) as response:
        return response.read()


def generate(study: str, token: str, model: str, force: bool = False) -> str:
    """Generate one study; returns the written path. Never overwrites by default."""
    path = next_free_path(study)
    if force and os.path.exists(os.path.join(OUT_DIR, f"{study}.png")):
        path = os.path.join(OUT_DIR, f"{study}.png")
        # Write to a temp name then replace, so a failed call cannot destroy the
        # previous result.
        target = path + ".new"
    else:
        target = path

    body = {
        "model": model,
        "messages": [{
            "role": "user",
            "content": [
                {"type": "text", "text": build_prompt(study)},
                {"type": "image_url", "image_url": {"url": data_url(reference_path(study))}},
            ],
        }],
    }
    request = urllib.request.Request(
        API_URL,
        data=json.dumps(body).encode("utf-8"),
        headers={
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json",
            "HTTP-Referer": "https://git.allucanget.biz/zwitschi/gig-line",
            "X-Title": "gig-line facade details",
        },
        method="POST",
    )

    payload = None
    for attempt in range(3):
        try:
            with urllib.request.urlopen(request, timeout=180) as response:
                payload = json.load(response)
            break
        except urllib.error.HTTPError as exc:
            if exc.code == 429 or exc.code >= 500:
                wait = 5 * (attempt + 1)
                sys.stderr.write(f"  HTTP {exc.code}; retrying in {wait}s\n")
                time.sleep(wait)
                continue
            detail = exc.read().decode("utf-8", "replace")[:300]
            raise SystemExit(f"{study}: HTTP {exc.code} — {detail}")
        except urllib.error.URLError as exc:
            sys.stderr.write(f"  network error ({exc.reason}); retrying\n")
            time.sleep(5 * (attempt + 1))
    if payload is None:
        raise SystemExit(f"{study}: no response after retries")

    image = decode_image(payload)
    os.makedirs(OUT_DIR, exist_ok=True)
    with open(target, "wb") as handle:
        handle.write(image)
    if target != path:
        os.replace(target, path)

    import hashlib
    sidecar = {
        "study": study,
        "generated": os.path.basename(path),
        "generated_utc": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
        "model": model,
        "prompt": build_prompt(study),
        "reference": {
            "file": STUDIES[study][0],
            "note": "local reference photography; Art/reference is gitignored and never shipped",
        },
        "sha256": hashlib.sha256(image).hexdigest(),
        "bytes": len(image),
        "redistribution": "local development reference only; not committed, not shipped",
    }
    sidecar_path = os.path.splitext(path)[0] + ".refgen.json"
    with open(sidecar_path, "w", encoding="utf-8") as handle:
        json.dump(sidecar, handle, indent=2)
    if token in json.dumps(sidecar):
        raise SystemExit("refusing to write a sidecar containing the token")
    return path


def main(argv=None) -> int:
    ap = argparse.ArgumentParser(description=__doc__,
                                 formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("--list", action="store_true", help="list studies and exit (free)")
    ap.add_argument("--all", action="store_true", help="generate every study")
    ap.add_argument("--only", help="comma-separated study names")
    ap.add_argument("--model", default=DEFAULT_MODEL)
    ap.add_argument("--force", action="store_true",
                    help="replace the existing <study>.png instead of writing a -vN")
    args = ap.parse_args(argv)

    if args.list or not (args.all or args.only):
        missing = set(missing_references())
        print(f"{len(STUDIES)} studies; model {args.model}")
        for name, (ref, _prompt) in STUDIES.items():
            state = "MISSING reference" if name in missing else "ready"
            print(f"  {name:22} {state:18} <- {ref}")
        if missing:
            print(f"\n{len(missing)} study(ies) cannot run without their reference photograph.")
        return 0

    names = list(STUDIES) if args.all else [s.strip() for s in args.only.split(",") if s.strip()]
    unknown = [n for n in names if n not in STUDIES]
    if unknown:
        raise SystemExit(f"unknown study(ies): {unknown}; known: {sorted(STUDIES)}")
    blocked = [n for n in names if n in set(missing_references())]
    if blocked:
        raise SystemExit(f"missing reference photograph for: {blocked}")
    token = load_token()

    print(f"generating {len(names)} study(ies) with {args.model} -> {OUT_DIR}")
    for index, name in enumerate(names, 1):
        print(f"[{index}/{len(names)}] {name}")
        try:
            path = generate(name, token, args.model, force=args.force)
        except SystemExit as exc:
            sys.stderr.write(f"  FAILED: {exc}\n")
            continue
        print(f"  wrote {os.path.relpath(path, ROOT)}")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())