OpenFigura：本地 3D 资产工具链，支持 CLI 与 MCP 接口

OpenFigura is a local 3D asset toolchain with CLI and MCP interfaces. Drop in a reference image and a plain-language brief; get back a textured GLB, a Blender-checkable scene, multi-view renders, and a provenance record that says exactly how every artifact was made.

Agent users: the manual is docs/usage.md — or register the MCP server (openfigura-mcp) and let figura_* tools self-describe.

No reference art yet? docs/input-guide.md has copy-paste prompts for GPT Image / Seedream / Grok / Midjourney that produce OpenFigura-friendly inputs.

It is a replacement for the paid "upload your art to someone's cloud" workflow — Tripo, Meshy and friends — not for any specific tool. The generation itself comes from swappable open backends (Pixal3D/TRELLIS.2 runtimes, and anything you register later). OpenFigura provides the boring, valuable parts: a stable tool surface, capability detection, reproducibility ledgers, and real render-based inspection instead of trusting one pretty preview.

reference image + brief
        │
        ▼
  ┌───────────────┐    backends: pixal3d.cpp, trellis, …   ┌──────────────┐
  │ openfigura-core│ ─────────────────────────────────────▶ │  GLB + PBR   │
  │  (engine)      │    generate → render → inspect → export│              │
  └───────┬───────┘                                         └──────────────┘
          │
   ┌─────────────┬─────────────┐
   ▼              ▼             ▼
 CLI         MCP server    (optional asset
 (scripts,   (Codex,       workbench)
  CI)        opencode,
             Claude…)

vs. commercial platforms

What "平替" (alternative) honestly means here: same category of capability, different architecture of trust. Category-level differences, from public documentation of each service as of 2026-10:

What we do not claim: that generation quality matches or beats these services. The backends we wrap (Pixal3D, TRELLIS.2) are open peers of the models behind commercial sites, but quality depends on inputs, resolution and luck-of-the-seed — and we refuse to claim a comparison we haven't run. The golden suite (docs/testing-guide.md) exists precisely so same-input comparisons become measurable, not rhetorical.

Tripo, Meshy and Hi3D are trademarks of their respective owners. This project is not affiliated with or endorsed by any of them; the table describes our architecture versus their publicly documented one.

External rigging and motion tools

Experimental asset/workflow foundation adds immutable hash-linked assets, project pixel-style validation and durable SQLite stage requests with matching CLI/MCP tools. It records requests and verified transitions; automatic execution, GPU scheduling and pixel generation are separate integrations. Source review and implementation decisions describe the 3D/2D routes and optional upstreams.

Experimental autorig invokes Make-It-Animatable v1 for neural joint/weight prediction; retarget invokes Godot and Blender for motion transfer, native IK and mandatory regional contact checks. No chat-model coordinate or keyframe construction is required. Actual CPU trials passed the upstream control character and rejected Xiaoman's incorrect wrist prediction; general quality is not claimed. See tool guide and real evidence.

3DGenStudio source review maps further independent ComfyUI, material, topology, rigging and motion integrations. Its restricted project code is not copied into OpenFigura.

Why not just an agent?

Agents (Codex, opencode, Claude Code, pi) already schedule tool calls better than any framework we could ship today. What they lack is a local, private, free, inspectable 3D pipeline with stable tool contracts. That is exactly the layer OpenFigura is. The MCP server is the primary interface; a CLI with identical commands exists for scripts and CI, and an optional self-hosted agent loop may come later — all three share one core.

Quick start

Full manual for agents and humans: docs/usage.md.

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"           # core + CLI
pip install -e ".[mcp]"           # + MCP server

# Register a backend binary (e.g. a prebuilt pixal3d.cpp runtime)
openfigura backends

# Generate → render → inspect → export, one task, one ledger
openfigura generate input.png --backend pixal3d --seed 42 -o out/
openfigura render  out/task.json
openfigura inspect out/task.json
openfigura export  out/task.json --format glb

Every run writes provenance.json: input SHA-256, exact command line, backend version, wall time, peak memory, output hashes. If it cannot be re-run from that file, it is a bug.

Requirements & honest limits

• Generation backends have their own hardware needs. The Pixal3D Q8 path is verified on Apple Silicon (Metal); CPU-only x86 works but is slow — local + private + free is the promise, speed is a per-backend property.
• Outputs are dense triangle meshes (~10⁶ tris). Rigging/animation needs retopology; OpenFigura tracks that as a post-processing step, it does not pretend one-shot generation is game-ready.
• Visual quality is judged by rendered views, not by the generator's own preview. That is a design rule, not a disclaimer.

License

AGPL-3.0-only — code only. Assets you generate are yours (output exemption, Blender-style); backends and model weights carry their own licenses, which every task's provenance ledger records. See LICENSES.md and TRADEMARK.md.

Calibrated texture refinement

openfigura refine-texture and figura_refine_texture preserve a model's geometry and recover visible source-image detail into a separate candidate. Optional CPU dependency extra: openfigura[detail]. See workflow and limits and source integration / animation path. This does not repair finger geometry or add a skeleton.

Experimental calibrated rigging

openfigura rig / figura_rig bind a static character using Blender Rigify and explicit bone calibration. Optional FK keyframes produce an animated GLB; render --frame checks real poses. Automatic skinning failure is explicit, with an opt-in approximate capsule method for motion proofs. No finger repair or game-ready deformation claim. See workflow and limits.