THE MARSUPIUM POUCH PLUG-IN — Image/text to 3D CAD Compiler
THE MAGIC JSON SUITCASE is your Grasshopper “state compiler” for contemporary architecture:
- reads a reference image (URL / local JPG / corpus ID)
- generates Prompt + Metadata (optional)
- outputs CFG overrides + SFG narrative + RAG docs
- packages everything into STATE_OUT JSON for downstream geometry nodes
No more brittle prompt chaos—just a reliable, repeatable design state that actually changes the model.
Wickerson Studios — https://www.wickersonstudios.com
THE MAGIC JSON SUITCASE — Image/Text to 3D CAD Compiler
================================================================
THE MAGIC JSON SUITCASE is the “front-end brain” node in a Grasshopper/Rhino pipeline that converts a
contemporary architecture reference image (URL / local JPG / corpus ID) + optional user text into:
- A clean, clamped, downstream-safe CFG (key=value parameters)
- A narrative SFG (reference/program/style/massing/facade/math/notes)
- Generated Prompt + Metadata text (optional, image-aware)
- A compact RAG corpus (precedent docs) and selected rag_docs
- A serialized STATE_OUT JSON that downstream geometry nodes can trust
IMPORTANT: THE MAGIC JSON SUITCASE does NOT generate Breps directly.
It generates a stable “design state” + configuration layer for geometry assembly nodes downstream.
----------------------------------------------------------------
1) What It Does (Conceptually)
----------------------------------------------------------------
Input:
(Image + Prompt/Metadata + CFG/SFG + Seed + Mode switches)
Process:
1) Resolve the image spec:
- Corpus ID (e.g., GHERKIN_01) -> uses that precedent’s imageUrl
- Web URL -> uses as-is
- Local file path -> base64 encodes as data URL (size-capped)
- Blank -> chooses a precedent from built-in corpus using seed
2) Parse and sanitize:
- Parse CFG_IN into a dictionary (opts)
- Parse SFG_IN into narrative slots (ai)
- Apply defaults for missing keys
- Clamp numeric ranges and normalize booleans/enums
- Remove any disallowed keys (CFG is restricted to an ALLOWED list)
- Force llmModel to the hard-coded model (so the pipeline stays deterministic)
3) Optionally call OpenAI (Responses API) if Run=true and API_KEY is valid:
- Sends image + baseline cfg + user prompt/meta
- Receives STRICT JSON schema: prompt, metadata, cfg overrides, sfg, rag_docs
4) If no key or API fails:
- Uses a deterministic fallback override generator (seeded, stable)
5) Merge overrides into CFG based on OverrideMode
Output:
STATE_OUT JSON + merged cfg/sfg + override deltas + rag docs + debug/log
----------------------------------------------------------------
2) Inputs (Grasshopper Node Inputs)
----------------------------------------------------------------
Run (bool)
- false: initialize only; outputs defaults/parsed state; no LLM call
- true: perform override generation (LLM or fallback) and update outputs
AutoFromImage (bool)
- false: prompt/meta inputs are used as provided (no auto fill)
- true: prompt/meta can be generated from image depending on AutoTextMode
AutoTextMode (string)
Recommended values:
- "fill_missing" (recommended default)
Only fills prompt/meta if your inputs are blank.
- "replace"
Always replaces your prompt/meta with generated text.
Notes:
- If you want your authored prompt to stay in control, use "fill_missing".
- If you want an “image-first” pipeline, use "replace".
API_KEY (string)
- Your OpenAI API key (kept as a GH panel input)
- If missing/invalid, THE MAGIC JSON SUITCASE uses deterministic fallback mode.
CFG_IN (string)
- Key=value pairs (one per line or separated by semicolons)
- Missing keys are filled with defaults.
- Keys outside the allowed set are removed.
SFG_IN (string)
- Free text with fields (any order):
reference: ...
program: ...
style: ...
massing: ...
facade: ...
math: ...
notes: ...
Prompt (string)
- Your current ArchitecturePrompt (optional)
- If AutoFromImage=true:
- replace: overwritten
- fill_missing: used unless blank
ReferenceImageUrl (string)
Accepts:
- Corpus ID: "WDCH_01", "GHERKIN_01", "SEATTLE_LIB_01", "KAUFFMAN_01", "HEYDAR_01"
- Web URL to a JPG/PNG
- Local path (e.g., C:\images\ref.jpg) or file:// URI
- Blank -> seed-based selection from built-in corpus
MetadataText (string)
- Any notes or scraped context (optional)
- If AutoFromImage=true: may be filled or replaced
OverrideMode (string)
Recommended values:
- "merge" (recommended default)
Overrides overwrite baseline keys.
- "replace"
Resets to baseline then applies overrides.
- "append"
Only adds missing keys (often has no visible effect because defaults fill everything).
SeedOverride (int)
- 0 uses internal seed default
- Non-zero changes the deterministic fallback and seed-based choices.
RagDocCount (int)
- Number of rag_docs to keep in output (clamped to a safe range).
----------------------------------------------------------------
3) Outputs (Grasshopper Node Outputs)
----------------------------------------------------------------
STATE_OUT (string JSON)
- Full EngineState snapshot for downstream nodes.
CFG_OVERRIDE (string)
- Only the override delta applied (key=value).
SFG_OVERRIDE (string)
- Generated narrative override block.
CFG_MERGED (string)
- Final, clamped, cleaned CFG that downstream geometry nodes should use.
SFG_MERGED (string)
- Final SFG (original + appended override, or replaced depending on mode).
RAG_JSON_OUT (string JSON)
- The precedent list used for rag_docs.
LLM_JSON (string)
- Raw assistant JSON (empty in fallback mode).
PROMPT_GENERATED (string)
- AI-generated ArchitecturePrompt block (even if you don’t use it).
METADATA_GENERATED (string)
- AI-generated metadata derived from image.
IMAGE_DISPLAY (string)
- Human-friendly image selection (URL / ID / local path).
IMAGE_API (string)
- What was sent to the API (URL or “data_url(n chars)”)
DEBUG (string)
- Summary of run mode, caching, flags, etc.
LOG (string)
- Time-stamped log messages
----------------------------------------------------------------
4) Typical Workflow (Recommended)
----------------------------------------------------------------
1) Drop THE MAGIC JSON SUITCASE at the top of your Grasshopper chain.
2) Set:
Run = false
AutoFromImage = true
AutoTextMode = "fill_missing"
OverrideMode = "merge"
3) Provide:
- ReferenceImageUrl (web jpg OR a corpus ID)
- Optional Prompt and MetadataText
4) Inspect outputs:
CFG_MERGED should show updated values that reflect the reference image.
5) When satisfied:
Run = true (if API_KEY provided) OR keep in fallback mode for deterministic results.
6) Wire:
STATE_OUT -> downstream STATE_IN for geometry assembly.
----------------------------------------------------------------
5) Recommended Starter Settings
----------------------------------------------------------------
AutoFromImage: true
AutoTextMode: "fill_missing"
OverrideMode: "merge"
RagDocCount: 8
SeedOverride: 13 (or any stable non-zero seed for repeatability)
----------------------------------------------------------------
6) Common Issues & Fixes
----------------------------------------------------------------
A) “Nothing changes when I run it”
- If OverrideMode = "append", defaults already fill keys -> no visible changes.
Use OverrideMode = "merge".
- If AutoFromImage=true, keep OverrideMode = "merge" so image-derived overrides overwrite defaults.
B) API calls every recompute
- THE MAGIC JSON SUITCASE caches using a signature of (cfg/sfg/prompt/meta/image/seed/modes).
- If something changes every solve (like a timestamp in CFG), caching won’t hit.
Keep volatile inputs out of CFG_IN.
C) Local image too large
- Local images are base64 encoded only if <= size cap.
- Prefer a web URL or downscale/compress your JPG.
D) Image URL doesn’t load in API
- Use a direct image link (ending with .jpg/.png).
- Some sites block hotlinking; use Wikimedia/commons or your own hosted file.
E) CFG keys getting removed
- Only ALLOWED keys survive. Put custom notes into SFG or MetadataText instead.
----------------------------------------------------------------
7) Security Notes
----------------------------------------------------------------
- Do not embed your API key into definitions you share publicly.
- Use a GH Panel for API_KEY and keep the definition private when possible.
----------------------------------------------------------------
8) Versioning
----------------------------------------------------------------
If you fork and modify, bump:
- EngineState.version
- CFG key "version"
- CFG key "stepId"
----------------------------------------------------------------
9) License / Attribution
----------------------------------------------------------------
Use within your own Grasshopper/Rhino workflows. If distributing commercially, consider adding your preferred
license text here and branding:
Wickerson Studios — https://www.wickersonstudios.com
----------------------------------------------------------------
END OF README