claw3d 0.1.0__tar.gz

claw3d-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 MakerMate
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

claw3d-0.1.0/PKG-INFO

@@ -0,0 +1,178 @@
+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>

claw3d-0.1.0/README.md

@@ -0,0 +1,152 @@
+<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>

claw3d-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "claw3d"
+version = "0.1.0"
+description = "CLI for converting sketches/images to 3D models and printing via Moonraker (OpenClaw skill)"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [{name = "claw3d"}]
+keywords = ["3d-printing", "openclaw", "fal", "moonraker", "curaengine", "tripo", "flux"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "License :: OSI Approved :: MIT License",
+]
+dependencies = [
+    "requests>=2.28.0",
+    "scipy>=1.9.0",
+    "trimesh>=4.0.0",
+    "fal-client>=0.4.0",
+    "Pillow>=10.0.0",
+    "pyrender>=0.1.45",
+    "imageio>=2.31.0",
+    "imageio-ffmpeg>=0.4.9",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "ruff>=0.1.0"]
+
+[project.scripts]
+claw3d = "claw3d.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

claw3d-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

claw3d-0.1.0/src/claw3d/__init__.py

@@ -0,0 +1,3 @@
+"""claw3d - CLI for sketch/image → 3D model → slice → print."""
+
+__version__ = "0.1.0"

claw3d-0.1.0/src/claw3d/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running claw3d as python -m claw3d."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

claw3d-0.1.0/src/claw3d/ai_providers/__init__.py

@@ -0,0 +1,47 @@
+"""AI providers — abstract interface and implementations for image/3D generation."""
+
+from .base import (
+    AIProvider,
+    FlowType,
+    StepType,
+    ImageToImageRequest,
+    ImageToImageResult,
+    ImageResult,
+)
+from .provider_registry import (
+    get_provider,
+    get_available_providers,
+    get_provider_info,
+    list_providers,
+    register_provider,
+)
+from .registry import (
+    ModelRegistry,
+    get_registry,
+    get_step_catalog,
+    get_recommended_model,
+    is_model_allowed,
+)
+from .fal_provider import FALProvider
+from .replicate_provider import ReplicateProvider
+
+__all__ = [
+    "AIProvider",
+    "FlowType",
+    "StepType",
+    "ImageToImageRequest",
+    "ImageToImageResult",
+    "ImageResult",
+    "ModelRegistry",
+    "get_registry",
+    "get_provider",
+    "get_available_providers",
+    "get_provider_info",
+    "list_providers",
+    "register_provider",
+    "get_step_catalog",
+    "get_recommended_model",
+    "is_model_allowed",
+    "FALProvider",
+    "ReplicateProvider",
+]

claw3d-0.1.0/src/claw3d/ai_providers/base.py

@@ -0,0 +1,109 @@
+"""AI provider base — flow/step types and abstract interface."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Optional
+
+
+class FlowType(str, Enum):
+    """High-level convert flow — determines which steps run and in what order."""
+
+    SKETCH_TO_3D = "sketch_to_3d"  # 1 image → enhance → image_to_3d
+    MULTIVIEW_TO_3D = "multiview_to_3d"  # 1 quad image → enhance → split → multiview_to_3d
+    TEXT_TO_3D = "text_to_3d"  # prompt → text_to_image → image_to_3d
+    EDIT_3D = "edit_3d"  # 3D model → render → enhance → split → multiview_to_3d
+
+
+class StepType(str, Enum):
+    """Individual step in a flow — each can have its own model selection.
+
+    Image-to-image steps differ by input/output:
+    - sketch_enhance: 1 sketch in → 1 enhanced out (for Tripo)
+    - multiview_enhance: 1 user-drawn quad in → 1 enhanced quad out (split after)
+    - edit_3d_enhance: 1 rendered grid in → 1 transformed grid out (3d-to-3d pipeline)
+    """
+
+    # Image-to-image (different flows, different default models)
+    SKETCH_ENHANCE = "sketch_enhance"
+    MULTIVIEW_ENHANCE = "multiview_enhance"
+    EDIT_3D_ENHANCE = "edit_3d_enhance"
+
+    # Other steps
+    TEXT_TO_IMAGE = "text_to_image"
+    IMAGE_TO_3D = "image_to_3d"
+    MULTIVIEW_TO_3D = "multiview_to_3d"
+
+
+@dataclass
+class ImageToImageRequest:
+    """Normalized request for image-to-image — flexible input."""
+
+    image_urls: list[str]  # 1 or N images
+    prompt: Optional[str] = None
+    step_type: StepType = StepType.SKETCH_ENHANCE  # Determines which model to use
+
+
+@dataclass
+class ImageToImageResult:
+    """Normalized result from image-to-image."""
+
+    image_urls: list[str]
+
+
+@dataclass
+class ImageResult:
+    """Single image result (text-to-image)."""
+
+    image_url: str
+
+
+class AIProvider(ABC):
+    """Abstract base for AI generation providers (FAL, Replicate, Google, etc.).
+
+    All providers implement the same interface. Under the hood, request/response
+    structures differ per provider (FAL REST, Replicate API, etc.).
+    """
+
+    @property
+    @abstractmethod
+    def provider_id(self) -> str:
+        """e.g. 'fal', 'replicate', 'google'"""
+        ...
+
+    @abstractmethod
+    def upload_file(self, path: Path) -> str:
+        """Upload local file and return URL for the provider to use."""
+        ...
+
+    @abstractmethod
+    def image_to_image(
+        self,
+        request: ImageToImageRequest,
+        model_id: Optional[str] = None,
+    ) -> ImageToImageResult:
+        """Transform 1 or more images. step_type determines default model if model_id omitted."""
+        ...
+
+    @abstractmethod
+    def text_to_image(self, prompt: str, model_id: Optional[str] = None) -> ImageResult:
+        """Generate image from text prompt."""
+        ...
+
+    @abstractmethod
+    def image_to_3d(self, image_url: str, model_id: Optional[str] = None) -> bytes:
+        """Single image → GLB."""
+        ...
+
+    def multiview_to_3d(
+        self,
+        front_url: str,
+        back_url: str,
+        left_url: str,
+        model_id: Optional[str] = None,
+    ) -> bytes:
+        """Multi-view (3 images) → GLB."""
+        raise NotImplementedError(
+            f"{self.provider_id} does not support multiview_to_3d"
+        )