Makeables images

Local reference tools need no generation service, account or repository checkout. Use these when cards needs measured geometry, preparation or selective tracing. Parameters are a JSON object (or @file) passed through --params. Outputs use new paths; originals are never overwritten. Read each generated preview.

makeables image detect --file reference.pngmakeables image prepare --file reference.png --out prepared --params '{"crop":"20,30,1000,630","patch":["80,80,120,80,300,80,6,0"]}'makeables image trace --file prepared --out card.svg --params '{"title":"My card","credit":"Source and author","tones":7}'makeables image sample --file reference.png --params '{"points":["20,30","100,80"]}'makeables image measure --file reference.png --params '{"rows":"100,200","cols":"80","dark":250}'makeables image map --file reference.png --params '{"box":"10,20,100,80","colors":6}'makeables image glyphs --file reference.png --out glyph.svg --params '{"box":"20,30,200,80","at":"100,200","fill":"#111111"}'makeables image rotate --file portrait.svg --out card.svg --params '{"top":"left"}'makeables image compare --file card.svg --ref reference.png --out compare.png --params '{"upright":"left","ref-box":"20,30,756,1200"}'makeables validate --file card.svg --out preview.png

makeables image detect --file reference.pngmakeables image prepare --file reference.png --out prepared --params '{"crop":"20,30,1000,630","patch":["80,80,120,80,300,80,6,0"]}'makeables image trace --file prepared --out card.svg --params '{"title":"My card","credit":"Source and author","tones":7}'makeables image sample --file reference.png --params '{"points":["20,30","100,80"]}'makeables image measure --file reference.png --params '{"rows":"100,200","cols":"80","dark":250}'makeables image map --file reference.png --params '{"box":"10,20,100,80","colors":6}'makeables image glyphs --file reference.png --out glyph.svg --params '{"box":"20,30,200,80","at":"100,200","fill":"#111111"}'makeables image rotate --file portrait.svg --out card.svg --params '{"top":"left"}'makeables image compare --file card.svg --ref reference.png --out compare.png --params '{"upright":"left","ref-box":"20,30,756,1200"}'makeables validate --file card.svg --out preview.png

detect suggests crop regions; inspect the image rather than trusting the heuristic. prepare uses source-pixel coordinates, crops near the 1200:756 ratio, patches from the untouched source and fills background at the crop border. A patch is destinationX,destinationY,width,height,sourceX,sourceY,feather,flop; only remove details the user wants removed. Compare every patched area closely. Optional edge-band and bg-tol tune edge cleanup. A substantially different crop ratio is rejected to avoid stretching; rotate portrait objects instead.

trace uses 2–12 luminance bands and optional ink threshold (0–1). raster:true keeps the prepared image under vector ink. Tracing and glyphs require the optional potrace executable; makeables doctor checks it. Install it only within the user's installation authorization (macOS: brew install potrace). Other operations do not need potrace. No automatic package install occurs.

sample returns a local 3×3 color average and center pixel. measure returns dark runs in rows/columns; use these for borders, stroke slopes and barcodes. map produces a color legend and a small pixel map (at most 160 × 200). For flat reference objects, use measured shapes, shared geometry and original text; trace unusual glyphs selectively. Keep counters with even-odd fill. Draw portrait objects upright, retain proportions, then rotate the entire card.

Web research is optional and uses tools available in the current agent session. Prefer official sources for assets and provenance, use community sources for context, and do not bypass bot checks or invent permission. Preserve attribution and distinguish an unofficial colorway from a documented variant. Respect no-web requests; these CLI tools operate on local inputs.

Optional image generation

Use this after the user chooses generation or requests a change that needs new image content. A style reference alone does not authorize transforming the portrait. Honor an original-photo or filters-only choice; editable monochrome, tint, thermal, crop and other native treatments do not require ai-cli.

Distinguish transforming the person's photo from generating separate decorative artwork. A portrait transformation needs the actual portrait, not just the style reference. Keep the person's identity, framing, pose and proportions. For separate artwork, leave the portrait unchanged unless the user also requested its transformation.

Check makeables preflight --json (add --probe to catch an invalid key before the run). If no generator is ready, use the host's own image tool when it has one; otherwise ask whether to install ai-cli for the requested transformation, then run:

Use the installed CLI's setup instructions for the user's AI Gateway credentials. Never put keys in chat, files, prompts, page storage, WebMCP arguments or the session URL. Explain that generation sends the selected source images to an external provider and uses Gateway credits separately from the coding agent's subscription. Confirm that processing and spending if not already authorized. If declined, offer the original photo or editable filters and continue with the user's choice.

Use the original local photo where available. To transform the current editor photo instead:

makeables studio call badge_get_image --url "$MAKEABLES_URL" --params '{"target":"portrait"}' --json > portrait-response.jsonmakeables image extract --file portrait-response.json --out portrait.webp

makeables studio call badge_get_image --url "$MAKEABLES_URL" --params '{"target":"portrait"}' --json > portrait-response.jsonmakeables image extract --file portrait-response.json --out portrait.webp

The extraction helper also accepts agent-browser's WebMCP JSON envelope and refuses to overwrite files. Keep image bytes out of the conversation.

Choose a currently available model that accepts reference images. Verify the installed ai image --help flags, then use a prompt tailored to the design:

ai image -m "$BADGE_IMAGE_MODEL" -i portrait.webp --output transformed.png --json \  "Transform only the supplied portrait into detailed pixel art. Preserve this person, head-and-shoulders framing, pose and proportions. No typography and no invented body."

ai image -m "$BADGE_IMAGE_MODEL" -i portrait.webp --output transformed.png --json \  "Transform only the supplied portrait into detailed pixel art. Preserve this person, head-and-shoulders framing, pose and proportions. No typography and no invented body."

For a cutout, request background removal explicitly and inspect whether the output has real alpha. An opaque background is not transparency. Do not report an image as transformed if generation failed; keep the original and explain the failure.

Import the result using a fresh state:

makeables studio call badge_inspect --url "$MAKEABLES_URL" --params '{"section":"state"}' --json > state.jsonmakeables image params --file transformed.png --state state.json > image-params.jsonmakeables studio call badge_set_image --url "$MAKEABLES_URL" --params @image-params.json --json

makeables studio call badge_inspect --url "$MAKEABLES_URL" --params '{"section":"state"}' --json > state.jsonmakeables image params --file transformed.png --state state.json > image-params.jsonmakeables studio call badge_set_image --url "$MAKEABLES_URL" --params @image-params.json --json

For artwork, add an image layer first, then pass --target artwork to image params. Inspect the resulting badge on both faces. Original and generated images stay separate so the user can return to the photograph.