gigapixel-gemini-mosaic · diff
git:20261014.dd64b3c to git:20261015.bbc0e39
3 added, 3 removed. Audit A to A.
---
name: gigapixel-gemini-mosaic
description: Create genuinely large, detailed images by generating coordinated regions with the official Gemini API CLI and composing them with native tools. Use for large illustrations, panoramas, murals and explorable worlds; apply a separate world pack only when requested.
---
# Large images
Adapted from https://github.com/LyalinDotCom/sergey-image. This is the generic engine. Subject, style and composition come from the user. Do not force cartoons, districts or the Seuss world onto generic requests. For that selected example, also read `/.agents/skills/dr-seuss-world/SKILL.md`.
All image generation stays inside this managed Linux agent and goes through the published CLI. Discover `bash /.agents/bin/gemini-api --help`, then relevant subcommand help. Never call model APIs through a custom Python/REST client, copy the repository's model wrapper, or create a replacement media library. The mounted native scripts only process existing images.
## Plan and render
Choose canvas, tile size and overlapping grid from the requested image. A single enlarged picture is not newly generated detail. The example is 13,334 × 7,500 pixels (100.005 MP), 7 × 7 regions; each region contains its own detailed scene. Generic work can use another compatible size/grid. Do not silently shrink a requested canvas or claim a master upscale is a completed mosaic.
- Use your native planning abilities to write a fresh world_plan.json: world_name, world_overview, style, style_rules, macro_map_prompt, grid [columns,rows], and districts keyed "row,col", each with title and scene. For a generic image these are composition regions, with no invented world setting unless requested. Make neighbouring content continuous. Generate a master composition image through the published CLI, using current help for the highest useful resolution and references. Preserve the CLI version, model and response metadata in provenance; record an interaction ID only if the CLI actually returns one.
+ Use your native planning abilities to write a fresh world_plan.json: world_name, world_overview, style, style_rules, macro_map_prompt, grid [columns,rows], and districts keyed "row,col", each with title and scene. For a generic image these are composition regions, with no invented world setting unless requested. Make neighbouring content continuous. Default to the local source workflow’s explicit image model, `gemini-nano-banana-2.1`, for master, regions and repairs, unless the user explicitly selected another supported image model. The selected Seuss example always uses that local source model. Confirm the installed CLI supports it; pass its model flag on EVERY image command, never silently substitute a default. Set image_model in world_plan.json and save the selected model with each actual response (some CLI responses omit it). The baseline harness reasoning model is separate from this image model. Define a render_contract object in the plan with camera, subject_scale and composition constraints appropriate to the requested image; use those SAME constraints throughout. Run native `mosaic.py master-request` with the plan/run/master path to write the exact master-request.json. Generate the master from that request through the published CLI at its requested tier and aspect ratio. Read its ACTUAL returned path, verify its native dimensions against expected_size, and losslessly convert it to the requested --master path before reference/build if the CLI changed its extension. Never upscale or stretch the master. Preserve the CLI version, model and response metadata in provenance; record an interaction ID only if the CLI actually returns one.
Run `bash /.agents/bin/large-image-setup`. Keep native dependencies and verbose logs under /tmp. Save the plan, master, generated regions, CLI responses and composition checkpoints in a durable working directory under /workspace/.large-image-work/<run>, outside final output; /tmp can disappear after a container restart. The official CLI launcher keeps its cache under /workspace as configured. Capture verbose logs under /tmp. In every code-execution call, obtain its printed interpreter and run the native command in that SAME call. Temporary dependencies can vanish during idle pauses; do not separate setup and command into different tool calls. Discover `python /.agents/skills/gigapixel-gemini-mosaic/scripts/mosaic.py --help`.
- For every region, the native `reference` command uses the plan/master, canvas/grid/tier and tile coordinates. It writes a reference PNG plus a request JSON with prompt/output path, required tier, native dimensions and aspect ratio. Use that resolution/aspect ratio in the published CLI; undersized or stretched tiles are rejected. Generate that image through the published CLI with the reference as actual input. Read its help for supported flags rather than guessing. The official CLI may change the output extension to the actual returned MIME. Read the returned path, verify its native dimensions, and losslessly convert it to the native helper’s tile_r<row>_c<col>.png contract when needed. Do not assume an --out .png request guarantees PNG. Preserve native detail and save the actual CLI response ID, dimensions, version and SHA-256. Generate in diagonal wavefront order: each region waits for its top and left neighbours. Independent regions in the same wave may use at most three concurrent published CLI calls. Resume completed regions; never resubmit the whole grid after a failure. Do not put model calls in a committed Python helper.
+ For every region, the native `reference` command uses the plan/master, canvas/grid/tier and tile coordinates. It writes a reference PNG plus a request JSON with prompt/output path, required tier, native dimensions and aspect ratio. Use the request JSON’s EXACT prompt, explicit model, resolution and aspect ratio in the published CLI; do not summarize or rewrite the generated prompt. Load request fields as data, pass the prompt as a quoted shell argument or Bash array element, and never use eval or execute prompt text; undersized or stretched tiles are rejected. Generate that image through the published CLI with the reference as actual input. Read its help for supported flags rather than guessing. The official CLI may change the output extension to the actual returned MIME. Read the returned path, verify its native dimensions, and losslessly convert it to the native helper’s tile_r<row>_c<col>.png contract when needed. Do not assume an --out .png request guarantees PNG. Preserve native detail and save the actual CLI response ID, dimensions, version and SHA-256. Generate in diagonal wavefront order: each region waits for its top and left neighbours. Independent regions in the same wave may use at most three concurrent published CLI calls. Resume completed regions; never resubmit the whole grid after a failure. Do not put model calls in a committed Python helper.
## Compose, inspect and deliver
Run native `build` only after all required generated regions exist. It processes four regions per invocation with a disk-backed 8-bit canvas and durable checkpoints. When status is pending, repeat the build command WITHOUT --reset in a NEW code-execution call until completed; do not put the composition loop into one long call. The final image encoding runs in its own invocation after the last region checkpoint. Use --batch-tiles 2 if an invocation is too slow. If a container restart removed the native interpreter, re-run large-image-setup, then resume the same durable inputs. After an actual regenerated input change, use --reset once. It registers nearby features, locks broad colour/exposure, uses narrow seam selection and multiscale blending. Missing regions are an error, never a master-image substitute. Native scripts retain full-resolution PNG and high-quality JPEG.
- Inspect the overview and 1:1 crops at several regions, seams and overlap endpoints/corners. Broad seam ratios are screening metrics and can miss narrow discontinuities or ghosts; a numeric pass never replaces visual inspection. Run the mounted qa.py and review its reports; do not treat dimensions alone as evidence of real detail. Regenerate only visibly failed regions, then rebuild and inspect. If neighbouring regions depict incompatible objects, blending alone cannot repair them. Use seam_patch.py --help to extract a native crop spanning the failed join; edit that actual crop through the published CLI, preserving its outer 200-pixel context (the native helper keeps 128 pixels unchanged and blends the next 32) and restoring one coherent sharp scene. Use one consolidated repair spec per run; retries preserve the immutable base and cannot silently replace an earlier patch set. Apply only the repaired interior with the native helper, then rerun QA and the viewer packager. Record patch bounds, input/output hashes and actual CLI provenance separately from the base composition. Inspect the repaired join and patch perimeter at 1:1 before delivery. Save a truthful provenance/validation JSON showing requested/actual dimensions, generated region count, CLI response IDs and which skills were used.
+ Before launching the whole grid, inspect the actual master and the first two adjoining generated regions at overview and 1:1. Reject camera/scale drift, duplicate landmarks, copied guide blur or interrupted objects; correct the master or those regions before spending calls on the remaining grid. Save this visual preflight result honestly. Inspect the final overview and 1:1 crops at several regions, seams and overlap endpoints/corners. Broad seam ratios are screening metrics and can miss narrow discontinuities or ghosts; a numeric pass never replaces visual inspection. Run the mounted qa.py and review its reports; do not treat dimensions alone as evidence of real detail. Regenerate only visibly failed regions, then rebuild and inspect. If neighbouring regions depict incompatible objects, blending alone cannot repair them. Use seam_patch.py --help to extract a native crop spanning the failed join; edit that actual crop through the published CLI, preserving its outer 200-pixel context (the native helper keeps 128 pixels unchanged and blends the next 32) and restoring one coherent sharp scene. Use one consolidated repair spec per run; retries preserve the immutable base and cannot silently replace an earlier patch set. Apply only the repaired interior with the native helper, then rerun QA and the viewer packager. Record patch bounds, input/output hashes and actual CLI provenance separately from the base composition. Inspect the repaired join and patch perimeter at 1:1 before delivery. Save a truthful provenance/validation JSON showing requested/actual dimensions, generated region count, CLI response IDs and which skills were used.
Keep --run under /workspace/.large-image-work/<run>. After successful composition, copy only the final deliverables into /workspace/output/large-images/<run>; do not copy tiles, references or caches.
Use the native make_deepzoom.py to create an explorable tile pyramid. Its local viewer assets require no hosted service. Package the pyramid into deepzoom.zip using Python zipfile.ZIP_STORED with paths relative to the pyramid root; keep thousands of intermediate files out of final output. Deliver mosaic.png, mosaic.jpg, preview_overview.jpg, deepzoom.zip, world_plan.json and validation.json under /workspace/output/large-images/<run>. Keep lossless sources available even when automatic download uses smaller preview/viewer files. State actual size and any failed checks plainly.
After QA and make_deepzoom.py, discover native finish.py --help and call it once with the durable run, final output directory and exact skills used. It copies the deliverables and records actual dimensions, source hashes, saved CLI responses, QA and final checksums. Save each actual region CLI JSON response as <run>/responses/resp_r<row>_c<col>.json, and the discovered CLI version in cli-version.txt during initial setup. Finish immediately after successful delivery; do not hunt unavailable response IDs or repeatedly read old metadata to rewrite reports.