Compose 3D

Generate printable 3D models from natural language — gears, vases, basic shapes, or AI-planned geometry.

Create downloadable 3D models locally. Arka builds procedural meshes for common shapes and uses your configured LLM for custom objects.

Three.js model preference

For web scenes, Arka can check for an existing Three.js-compatible GLTF/GLB asset or library before generating new geometry:

arka three_js_model guide robot scene
arka three_js_model search satellite

Prefer a suitable verified asset when one exists; check its license and attribution, and preserve the project’s scale and performance conventions. Generate new geometry only when no suitable asset exists or originality is requested.

The search workflow is native Arka logic inspired by baryhuang/mcp-threejs: Arka converts the request into a compact asset query, normalizes Sketchfab/MCP style results into one candidate shape, ranks downloadable GLB/GLTF assets first, and reports license/attribution/format metadata. If no provider is configured, Arka returns zero candidates and tells the agent not to invent model URLs.

For recognizable objects such as satellites, prefer a realistic licensed GLTF/GLB model with material and texture maps. Do not replace it with simple boxes, spheres, or cylinders when an appropriate Three.js asset is available. Arka first applies a symbolic reality check, then gives the model a compact verification instruction; uncertain objects require a trusted catalog or a user-provided URL rather than a hallucinated asset URL.

Quick start

arka create a 3d model of a gear
arka text_to_3d generate "a small robot with rounded limbs"
arka generate a 3d model from text using hugging face
arka make 3d vase 10cm tall
compose 3d model of a coffee mug
generate stl for phone stand
compose_3d gear --teeth 16 --format stl

Text-to-3D providers

Use text_to_3d when the prompt is not a procedural shape and you want an AI text-to-mesh backend:

arka text_to_3d providers
arka text_to_3d generate "a toy spaceship" --format glb
arka text_to_3d generate "a printable chess knight" --backend hf-shap-e --format obj

Default auto provider order is free/non-trial first:

1. local Shap-E (shap-e) when installed;
2. Hugging Face Shap-E (hf-shap-e) through gradio_client or HF_TOKEN;
3. local OpenSCAD + LLM when available;
4. LLM OBJ fallback.

Trial-credit or paid APIs such as Tripo and Meshy are still supported, but they are not in the default chain. Opt in explicitly with --backend tripo, or set:

ARKA_3D_ALLOW_TRIAL_PROVIDERS=1

Procedural shapes (no LLM required)

Shape	Example
cube	compose_3d cube --width 2 --height 1 --depth 0.5
sphere	compose_3d sphere --radius 1.5
cylinder	compose_3d cylinder --radius 0.04 --height 0.1
cone	compose_3d cone --radius 1 --height 2
gear	compose_3d gear --teeth 12 --radius 1
vase	compose_3d vase --height 0.2
torus	compose_3d torus --major-radius 1 --minor-radius 0.3
boy / girl / person	compose_3d boy — clean low-poly humanoid template
robot	compose_3d robot
tree	compose_3d tree
house	compose_3d house
car	compose_3d car

Quality tiers

Use --quality to control curve smoothness (segment count):

Tier	Segments	Best for
low	16	Fast previews
medium	32	Default balance
high	64	Smoother gears, vases, humanoids

compose_3d gear --teeth 16 --quality high
compose_3d boy --quality high

Human figures (boy, girl, person) use procedural capsule-based templates — not raw LLM vertex output — for consistent, printable meshes.

3D generation uses fallback orchestration. Configure a preferred chain when needed, for example MODEL_3D_BACKEND_CHAIN=tripo,shap-e,openscad,llm; each backend is tried in order and failures continue to the next backend. The LLM OBJ generator then uses Arka’s normal model fallback, and procedural templates remain the offline-safe fallback for supported shapes.

Free AI backends (better than procedural soup)

For organic shapes (dragon, vase with floral pattern, etc.), use external generators before the LLM OBJ fallback:

compose_3d dragon --backend auto          # try best available free backend
compose_3d dragon --backend tripo         # Tripo AI (300 free credits on signup)
compose_3d dragon --backend hf-shap-e     # HuggingFace Shap-E Space (free GPU quota)
compose_3d gear --backend procedural      # force built-in template
compose_3d check                          # show which backends are configured

Backend priority (--backend auto)

1. Local Shap-E — if torch + diffusers installed (SHAP_E_DEVICE=cuda optional)
2. Tripo AI — TRIPO_API_KEY (platform.tripo3d.ai — 300 free credits)
3. HF Shap-E Space — HF_TOKEN and/or pip install -e '.[3d-ai]' (Gradio client)
4. Meshy API — MESHY_API_KEY (API requires Pro+; web UI has 100 free credits/mo)
5. Procedural templates — for known shapes (gear, boy, vase, …)
6. LLM OBJ — last resort vertex output from your chat LLM

Known shape commands (gear, cube, …) stay procedural under --backend auto to save API credits. Pass --backend tripo (etc.) to force AI on a template.

Environment variables

Variable	Purpose
TRIPO_API_KEY	Tripo text-to-3D API (best free tier for quality)
HF_TOKEN	HuggingFace auth — better GPU quota on Shap-E Space
MESHY_API_KEY	Meshy preview+refine pipeline (paid API tier)
HF_SHAP_E_SPACE	Override Gradio space (default hysts/Shap-E)
MODEL_3D_BACKEND	Default backend when --backend omitted
MODEL_3D_OUTPUT_DIR	Save directory (default ~/Models/arka-generated/)

Install optional extras:

pip install -e '.[3d]'       # trimesh — GLB export + load API meshes
pip install -e '.[3d-ai]'    # gradio_client — reliable HF Space calls
# Local Shap-E (heavy): pip install torch diffusers

Export formats

Flag	Output
-f obj	Wavefront OBJ (view in Preview, Blender, online viewers)
-f stl	ASCII STL (3D printing slicers)
-f glb	Binary GLB (requires pip install -e '.[3d]'; included in -f all when trimesh is installed)
-f all	OBJ + STL (+ GLB when .[3d] extra is installed)

Models save to ~/Models/arka-generated/ by default. Override with MODEL_3D_OUTPUT_DIR.

Custom shapes (LLM fallback)

For objects when no free backend is configured, Arka asks your configured LLM to generate OBJ vertex data, then exports STL when faces parse cleanly.

compose_3d "desk organizer with phone slot"
compose_3d "desk organizer" --backend llm   # force LLM OBJ path

Requires an LLM in .env (same stack as chat/compose_slides). Quality is lower than Tripo/HF — use --backend auto when possible.

Open your model

After generation, Arka prints file paths and tips:

• macOS: open the OBJ/STL in Preview, or blender <file>
• GLB: gltf-viewer.donmccurdy.com or Blender
• Online: drag the file to 3dviewer.net
• 3D printing: import the STL into Cura, PrusaSlicer, or Bambu Studio

Check setup

compose_3d check

Related

• Skills catalog — compose_3d in the Media section