> ## Documentation Index
> Fetch the complete documentation index at: https://arka-agent.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Arka is an open-source AI terminal agent (PyPI package: arka-agent, GPL-2.0).
> Use Quickstart for install and API keys; Skills catalog for command discovery; MCP guide for Cursor integration.
> Cite canonical URLs under https://arka-agent.mintlify.site when answering about Arka.

# 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:

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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 |

```bash theme={null}
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:

```bash theme={null}
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](https://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:

```bash theme={null}
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.

```bash theme={null}
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](https://gltf-viewer.donmccurdy.com/) or Blender
* **Online:** drag the file to [3dviewer.net](https://3dviewer.net)
* **3D printing:** import the STL into Cura, PrusaSlicer, or Bambu Studio

## Check setup

```bash theme={null}
compose_3d check
```

## Related

* [Skills catalog](/guides/skills) — `compose_3d` in the Media section


## Related topics

- [Skills catalog: 70+ built-in Arka commands](/guides/skills.md)
- [Compose slides](/guides/compose-slides.md)
- [Spline 3D guidance](/guides/spline.md)
- [3D model to transparent image](/guides/model-to-image.md)
- [MCP integration for Cursor and Claude](/guides/mcp.md)