playbooks

home / skills / openclaw / skills / image-to-relief-stl

image-to-relief-stl skill

/skills/ajmwagar/image-to-relief-stl

This skill converts a source image into a watertight printable STL by mapping colors or grayscale to heights for bas relief models.

npx playbooks add skill openclaw/skills --skill image-to-relief-stl

Review the files below or copy the command above to add this skill to your agents.

Files (4)
SKILL.md
1.9 KB
---
name: image-to-relief-stl
description: Turn a source image (or multi-color mask image) into a 3D-printable bas-relief STL by mapping colors (or grayscale) to heights. Use when you have an image from an image-gen skill (nano-banana-pro, etc.) and want a real, printable model (STL) via a deterministic pipeline.
metadata:
  openclaw:
    requires:
      bins: ["python3", "potrace", "mkbitmap"]
    install:
      - id: apt
        kind: apt
        package: potrace
        bins: ["potrace", "mkbitmap"]
        label: Install potrace + mkbitmap (apt)
      - id: brew
        kind: brew
        formula: potrace
        bins: ["potrace", "mkbitmap"]
        label: Install potrace + mkbitmap (brew)
---

# image-to-relief-stl

Generate a **watertight, printable STL** from an input image by mapping colors (or grayscale) to heights.

This is an orchestrator-friendly workflow:
- Use **nano-banana-pro** (or any image model) to generate a **flat-color** image.
- Run this skill to convert it into a **bas-relief** model.

## Practical constraints (to make it work well)

Ask the image model for:
- **exactly N solid colors** (no gradients)
- **no shadows / no antialiasing**
- bold shapes with clear edges

That makes segmentation reliable.

## Quick start (given an image)

```bash
bash scripts/image_to_relief.sh input.png --out out.stl \
  --mode palette \
  --palette '#000000=3.0,#ffffff=0.0' \
  --base 1.5 \
  --pixel 0.4
```

### Grayscale mode

```bash
bash scripts/image_to_relief.sh input.png --out out.stl \
  --mode grayscale \
  --min-height 0.0 \
  --max-height 3.0 \
  --base 1.5 \
  --pixel 0.4
```

## Outputs

- `out.stl` (ASCII STL)
- optional `out-preview.svg` (vector preview via potrace; best-effort)

## Notes

- This v0 uses a **raster heightfield** meshing approach (robust, no heavy CAD deps).
- The `--pixel` parameter controls resolution (smaller = higher detail, bigger STL).

Overview

This skill converts a source image or a multi-color mask into a watertight, 3D-printable bas-relief STL by mapping colors or grayscale values to heights. It provides a deterministic pipeline tuned for images produced by image-generation models, producing an ASCII STL and optional SVG preview. The output uses a raster heightfield meshing approach to remain robust without heavy CAD dependencies. Parameters let you control base thickness, pixel resolution, and height mapping.

How this skill works

The skill analyzes the input image either as a color palette (discrete labels) or as grayscale and builds a heightfield where each pixel maps to a z value based on color-to-height rules. It generates a raster mesh from that heightfield, adds a flat base for printability, and writes an ASCII STL; an optional vector preview (SVG) is created via tracing for quick inspection. Resolution and fidelity are governed by the pixel parameter; smaller values yield higher detail and larger STL files.

When to use it

  • You have a flat-color image or mask from an image-generation model and need a printable bas-relief.
  • You want a deterministic, scriptable pipeline from image to STL without CAD software.
  • You need quick previews and a watertight mesh for FDM or resin printing.
  • You want to convert grayscale artwork into variable-depth bas-relief.
  • You need a lightweight toolchain that avoids complex dependencies.

Best practices

  • Ask the image model for exactly N solid colors, no gradients, and no shadows to make segmentation reliable.
  • Use bold shapes with clear edges and avoid antialiasing to reduce noise in the heightfield.
  • Start with a coarser --pixel value to test sizing, then decrease for final detail to manage file size and processing time.
  • Set a reasonable base thickness to ensure the model prints flat and stays stable on the build plate.
  • When using palette mode, provide explicit color=height mappings to avoid unexpected defaults.

Example use cases

  • Turn character or emblem art from an image model into a printable plaque or coaster.
  • Create tactile maps or signage by mapping distinct colors to specific heights.
  • Produce decorative bas-relief panels for hobby models and dioramas.
  • Convert grayscale renderings into variable-depth carvings for CNC or 3D printing.
  • Batch-process masks from a generative pipeline to produce multiple printable variations.

FAQ

What input image types work best?

Flat-color PNGs or masks with solid colors and no antialiasing work best; grayscale JPG/PNG is fine for continuous-height results.

How does the --pixel parameter affect output?

Smaller --pixel yields higher spatial resolution and finer detail but increases STL size and processing time; larger values simplify geometry and speed up generation.

Is the STL watertight and ready to print?

Yes—the pipeline produces a watertight ASCII STL with a flat base designed for direct 3D printing; you may still want to check scale and orientation in your slicer.