ImagoForge

ImagoForge is a local-first, evidence-aware studio for turning one or more images into reviewable 3D candidates. It is written primarily in Crystal and ships with a browser workspace for source selection, measurable edit hints, versioned candidates, and visible uncertainty boundaries.

Project status: early prototype. ImagoForge does not yet provide a production image-to-3D pipeline, and it does not claim that hidden geometry or metric scale can be recovered faithfully from arbitrary images.

What exists today

• A deterministic Crystal domain kernel with typed source, observation, hint, and immutable revision identifiers.
• A narrow legacy PNG-to-relief engine with STL/OBJ export and topology audit.
• A local browser prototype with multiple source projections, a generic procedural 3D fixture, typed millimetre edits, immutable preview versions, and cancellable simulated work.
• A review-only Qwen3.6-27B multimodal adapter. Its normalized bounding boxes and structural observations remain suggestions that require human review.
• Frontier specifications for the universal studio and the native TRELLIS.2 backend planned in cogni-ml.

The browser is not connected to the Crystal kernel or reconstruction workers yet. Native TRELLIS.2 inference, image upload persistence, exact source-to-mesh correspondence, GLB delivery, and real geometry mutation remain future slices.

Repository layout

src/imago_forge/                    Crystal kernel and legacy relief engine
web/                                Local browser prototype
docs/FRONTIER_SDD.md                Universal studio boundary
docs/TRELLIS2_NATIVE_FRONTIER_SDD.md Native backend boundary
docs/IMPLEMENTATION_PLAN.md         Studio implementation ledger
scripts/                            Blender and public-release checks

Crystal CLI

Requirements:

• Crystal 1.21 or newer
• Shards
• Optional: Blender 5.x for independent mesh inspection
• Optional: Qwen3.6-27B GGUF, matching vision projector, and a compatible llama-mtmd-cli

Build and test:

shards install
crystal spec
CRYSTAL_CACHE_DIR=/tmp/imagoforge-crystal-cache shards build --release

Create a deterministic flat-backed relief from your own PNG:

bin/imagoforge build input.png \
  --front-crop 0,0,512,512 \
  --height-mm 60 \
  --output /tmp/imagoforge-model.stl

The relief path is a bounded legacy method, not a universal reconstruction algorithm. Inspect the mask and height previews before relying on the mesh.

Optional Qwen3.6-27B review

Model locations are never hard-coded. Pass them explicitly or configure:

export IMAGOFORGE_LLAMA_MTMD=/path/to/llama-mtmd-cli
export IMAGOFORGE_QWEN_MODEL=/path/to/Qwen3.6-27B.gguf
export IMAGOFORGE_QWEN_MMPROJ=/path/to/mmproj-BF16.gguf

bin/imagoforge analyze input.png \
  --front-crop 0,0,512,512 \
  --output /tmp/imagoforge-review.json

The output is accepted only when it is one strict JSON object matching the Crystal-side contract. It is never fed directly into metric geometry or topology construction.

Browser prototype

cd web
npm ci
npm run dev

Open http://localhost:3000. Verification commands:

npm run lint
npm run typecheck
npm test

Public-source boundary

Private source/reference images, generated meshes, local databases, model weights, and credentials are intentionally excluded from Git. Before a public release, run:

bash scripts/public_release_guard.sh --history

The first public branch is intentionally a single parentless root commit so private prototype assets cannot remain reachable through earlier history.

License

ImagoForge is available under the MIT License. See LICENSE.