Metadata-Version: 2.4
Name: claw3d
Version: 0.1.0
Summary: CLI for converting sketches/images to 3D models and printing via Moonraker (OpenClaw skill)
Author: claw3d
License: MIT
Keywords: 3d-printing,openclaw,fal,moonraker,curaengine,tripo,flux
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Requires-Dist: scipy>=1.9.0
Requires-Dist: trimesh>=4.0.0
Requires-Dist: fal-client>=0.4.0
Requires-Dist: Pillow>=10.0.0
Requires-Dist: pyrender>=0.1.45
Requires-Dist: imageio>=2.31.0
Requires-Dist: imageio-ffmpeg>=0.4.9
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="assets/claw3d-logo.png" alt="claw3d" width="300">
</p>

# claw3d

Open-source OpenClaw skill for converting sketches/images to 3D models and printing via Moonraker. Powers image-to-3D, sketch-to-print, and text-to-3D workflows.

---

## What It Does

1. **Convert** — Sketch/image or text prompt → 3D model (GLB) via FAL.ai (FLUX + Tripo)
2. **Search** — Find 3D models on Thingiverse (`claw3d search "dragon"`)
3. **Scale** — Resize 3D model
4. **Slice** — 3D model → G-code via CuraEngine
5. **Print** — Upload G-code to Moonraker and start print

→ **[Full workflow map & architecture](WORKFLOW.md)** — coordinate systems, all flows, improvement roadmap

## Install

**From PyPI** (recommended):
```bash
pip install claw3d
# or
uv tool install claw3d
```

**From source** (development):
```bash
cd claw3d
pip install -e .
```

The `claw3d` command is available after install.

## Quick Start

```bash
# 1. Set your FAL API key
export FAL_API_KEY=your-key

# 2. Convert a sketch or prompt to 3D
claw3d convert --image sketch.png --prompt "a toy robot" --output model.glb          # Sketch → Tripo
claw3d convert --prompt "a blue rocket figurine" --output model.glb                 # Text → image → Tripo
claw3d convert --image multiview.png --multiview --output model.glb                 # Multiview quad → Gemini → Hunyuan
claw3d convert --edit-3d model.glb --prompt "make it blue" --output edited.glb      # 3D-to-3D: render → enhance → Hunyuan
claw3d convert --image sketch.png --no-enhance --output model.glb                   # Direct to Tripo (no enhance)

# Per-step model overrides (e.g. --sketch-enhance-model flux2_pro_edit)
claw3d convert --help  # lists --*-model flags

# 3. Scale (optional)
claw3d scale --input model.glb --output scaled.glb --scale 0.5

# 4. Slice (requires CuraEngine API)
# Or search for models: claw3d search "dragon" --limit 5 (needs THINGIVERSE_ACCESS_TOKEN)
export CLAW3D_SLICER_URL=http://localhost:8000
claw3d slice --input scaled.glb --profile <profile_id> --output model.gcode
# Or GLB + 3MF: claw3d slice -i model.glb --profile-from-3mf settings.3mf -o model.gcode
# Run `claw3d profile list` first to get profile_id; if multiple, ask which one.

# 5. Print (requires Moonraker on LAN)
claw3d print --gcode model.gcode [--printer <id>]
# Run `claw3d printers` first; if multiple printers, ask which one.
```

## Slicing API

claw3d uses the CuraEngine slicing API (`curaengine-slicer-api`). It lives in the sibling folder `../curaengine-slicer-api`. With Docker Compose, the slicer runs as a companion service. Standalone:

```bash
# Run slicer (sibling folder)
cd ../curaengine-slicer-api
docker compose up -d
```

Then create a slicing profile via `claw3d profile create --from-3mf settings.3mf --name my_printer` or `POST /profiles/from-3mf`.

## OpenClaw Skill

**I have OpenClaw + Telegram. What's next?** Run the setup script — it asks which skills you want:

```bash
cd claw3d
./scripts/setup-openclaw-docker.sh ../openclaw-base
```

- **3d-ai-forger** — Convert images/text to 3D. Prompts for FAL_API_KEY.
- **3d-printing** — Slice and print. Choose local or cloud slicer.
- **3d-directory** — Search Thingiverse. Prompts for THINGIVERSE_ACCESS_TOKEN.

The installer prompts for API keys (FAL, Thingiverse) and writes them to `.env`. Use `--force-recreate` when starting so the gateway uses the freshly built image.

**Test from scratch:** [docs/TEST_FROM_SCRATCH.md](docs/TEST_FROM_SCRATCH.md) — cleanup, reinstall, verify `claw3d search`.

Full guides:
- [docs/OPENCLAW_DOCKER.md](docs/OPENCLAW_DOCKER.md) — General Docker setup
- [docs/INSTALL_LOCAL.md](docs/INSTALL_LOCAL.md) — **Step-by-step install from local repo** (pre-ClawHub)

**Troubleshooting:** If the bot says it can't convert images to 3D, see [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md).

**Manual** (no Docker): Sync skills with `./scripts/sync-skills.sh`

**ClawHub** — When published, use OpenClaw’s skill install (one-click via `uv tool install claw3d`).

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `FAL_API_KEY` | Yes | — | FAL.ai API key |
| `CLAW3D_SLICER_URL` | No | `http://localhost:8000` | CuraEngine API URL |
| `CLAW3D_PRINTER` | No | — | Default printer `ip:port` |

## Project Structure

```
claw3d/                    # This repo (claw3d CLI)
├── src/claw3d/            # convert, scale, slice, print, config
├── scripts/
│   ├── sync-skills.sh     # Sync 3d-ai-forger + 3d-printing to workspace
│   └── setup-openclaw-docker.sh
├── reference/             # Architecture notes
├── pyproject.toml
└── README.md
curaengine-slicer-api/     # CuraEngine HTTP API (port 8000, sibling folder)
```

## Related projects

| Repo | Description |
|------|-------------|
| [clarvis-ai](https://github.com/makermate/clarvis-ai) | One-command distro — bundles everything into a single Docker Compose stack |
| [claw3d-skill](https://github.com/makermate/claw3d-skill) | AI agent instructions that teach OpenClaw how to orchestrate the 3D printing workflow |
| [curaengine-slicer-api](https://github.com/makermate/curaengine-slicer-api) | CuraEngine REST API for slicing and mesh conversion |

## License

MIT

---

<p align="center">
  <a href="https://clarv.is">
    <img src="assets/clarvis_logo.png" alt="Clarvis" width="140">
  </a>
</p>

<p align="center">
  For a ready-to-use, anything-to-3D-print experience, check out <a href="https://clarv.is">clarv.is</a>
</p>
