feat(skills): OpenSCAD-Skill hinzufuegen
This commit is contained in:
@@ -0,0 +1,278 @@
|
||||
# OpenSCAD Claude Code Skill
|
||||
|
||||
A Claude Code skill for programmatic 3D CAD using [OpenSCAD](https://openscad.org/). Design, preview, iterate, reconstruct from STL, and export 3D-printable models — with AI-driven visual feedback and automated mesh comparison.
|
||||
|
||||
## Features
|
||||
|
||||
- **Programmatic 3D modeling** — Generate `.scad` files from natural language descriptions
|
||||
- **AI vision feedback loop** — Render multi-angle PNG previews and analyze them to iteratively refine designs
|
||||
- **STL-to-SCAD reconstruction** — Reverse-engineer STL meshes into parametric OpenSCAD code using SVG profiling and SDF optimization
|
||||
- **Image-to-CAD replication** — Reproduce physical objects from reference photos
|
||||
- **Parametric design** — All dimensions as variables, overridable via CLI `-D` flags
|
||||
- **Mesh comparison** — Boolean diff rendering and IoU scoring to verify reconstruction accuracy
|
||||
- **Printability analysis** — Wall thickness, overhang, and manifold validation
|
||||
- **Reusable module library** — Common 3D printing patterns (counterbores, heat-set bosses, ribs, snap-fits)
|
||||
- **Eval framework** — Automated testing with 20 binary assertions across 4 scenarios (100% pass rate)
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **OpenSCAD** installed and accessible via CLI
|
||||
```bash
|
||||
brew install openscad # macOS
|
||||
```
|
||||
- **Python packages** (for STL reconstruction):
|
||||
```bash
|
||||
pip3 install trimesh numpy scipy rtree shapely
|
||||
```
|
||||
- **admesh** (for mesh validation):
|
||||
```bash
|
||||
brew install admesh
|
||||
```
|
||||
- **Claude Code** CLI installed
|
||||
|
||||
## Installation
|
||||
|
||||
### Option 1: Clone and symlink (recommended)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/andreahaku/openscad_claude_skill.git ~/Development/Claude/openscad_claude_skill
|
||||
|
||||
mkdir -p ~/.claude/skills
|
||||
ln -sf ~/Development/Claude/openscad_claude_skill ~/.claude/skills/openscad
|
||||
```
|
||||
|
||||
### Option 2: Direct clone into skills
|
||||
|
||||
```bash
|
||||
git clone https://github.com/andreahaku/openscad_claude_skill.git ~/.claude/skills/openscad
|
||||
```
|
||||
|
||||
### Verify installation
|
||||
|
||||
```bash
|
||||
openscad --version
|
||||
bash ~/.claude/skills/openscad/scripts/openscad-render.sh quick ~/.claude/skills/openscad/templates/bracket.scad
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
The skill triggers automatically when you mention 3D modeling, CAD, STL export, or OpenSCAD:
|
||||
|
||||
```
|
||||
/openscad design a phone stand with adjustable angle
|
||||
```
|
||||
|
||||
### Modes
|
||||
|
||||
| Mode | Trigger | Description |
|
||||
|------|---------|-------------|
|
||||
| **Design** | "design a bracket", "make a box" | Create new 3D models from descriptions |
|
||||
| **Replicate** | "reproduce this from the photo" | Reverse-engineer objects from reference images |
|
||||
| **Reconstruct** | "convert this STL to SCAD" | Reverse-engineer STL meshes into parametric code |
|
||||
| **Refine** | "make it taller", "add fillets" | Iterate on existing designs |
|
||||
| **Export** | "export STL", "ready for printing" | Generate production files |
|
||||
| **Analyze** | "check printability" | Validate designs for 3D printing |
|
||||
|
||||
### Example Workflows
|
||||
|
||||
**Design from scratch:**
|
||||
```
|
||||
> Design a parametric enclosure for a Raspberry Pi 4 with ventilation slots
|
||||
```
|
||||
|
||||
**Reconstruct from STL:**
|
||||
```
|
||||
> Convert /path/to/model.stl into parametric OpenSCAD code
|
||||
```
|
||||
|
||||
**Export with parameter overrides:**
|
||||
```
|
||||
> Export the bracket with width=100 and wall=3
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
openscad_claude_skill/
|
||||
├── SKILL.md # Skill definition (6 modes, 762 lines)
|
||||
├── README.md # This file
|
||||
├── scripts/
|
||||
│ ├── openscad-render.sh # Core render/export/preview engine (7 commands)
|
||||
│ ├── openscad-project.sh # Project scaffolding (init/list/clean/info)
|
||||
│ ├── openscad-validate.sh # Strict validation with error categorization
|
||||
│ ├── openscad-stl-analyze.sh # STL mesh analysis (bbox, cross-sections, gaps)
|
||||
│ ├── openscad-stl-reconstruct.sh # Automated reconstruction pipeline (SVG profiling)
|
||||
│ ├── openscad-stl-compare.sh # Mesh comparison (boolean diff, accuracy %)
|
||||
│ └── openscad-sdf-optimize.py # SDF parameter optimizer (IoU scoring)
|
||||
├── references/
|
||||
│ ├── language-reference.md # Complete OpenSCAD v2021.01 cheat sheet
|
||||
│ └── reconstruction-guide.md # Best practices for STL-to-SCAD reconstruction
|
||||
├── templates/
|
||||
│ ├── enclosure.scad # Parametric electronics box with lid
|
||||
│ ├── bracket.scad # L-bracket with countersunk holes
|
||||
│ └── printable-lib.scad # Reusable 3D printing modules
|
||||
└── eval/
|
||||
├── eval.json # 4 test scenarios, 20 binary assertions
|
||||
└── results.jsonl # Test results log
|
||||
```
|
||||
|
||||
## Scripts
|
||||
|
||||
### `openscad-render.sh` — Core Rendering Engine
|
||||
|
||||
```bash
|
||||
bash scripts/openscad-render.sh quick <file.scad> # Single isometric preview
|
||||
bash scripts/openscad-render.sh preview <file.scad> # 4-view (iso, front, right, top)
|
||||
bash scripts/openscad-render.sh stl <file.scad> [-D ...] # Export STL
|
||||
bash scripts/openscad-render.sh 3mf <file.scad> # Export 3MF
|
||||
bash scripts/openscad-render.sh export <file.scad> # Full export (STL + 3MF + PNG)
|
||||
bash scripts/openscad-render.sh analyze <file.scad> # Printability analysis
|
||||
bash scripts/openscad-render.sh custom <file.scad> [opts] # Custom render
|
||||
```
|
||||
|
||||
### `openscad-stl-reconstruct.sh` — Automated STL Analysis
|
||||
|
||||
```bash
|
||||
bash scripts/openscad-stl-reconstruct.sh model.stl output_dir/
|
||||
```
|
||||
|
||||
Runs the full analysis pipeline:
|
||||
1. **trimesh** mesh analysis (volume, watertight, normals, bounding cylinder)
|
||||
2. **SVG profiling** via OpenSCAD `projection(cut=true)` at 5 Z levels
|
||||
3. **Primitive detection** (RANSAC axis estimation, normal-based CSG inference)
|
||||
|
||||
Output: `mesh-info.json`, `primitives.json`, SVG slice files
|
||||
|
||||
### `openscad-stl-compare.sh` — Mesh Comparison
|
||||
|
||||
```bash
|
||||
bash scripts/openscad-stl-compare.sh original.stl reconstruction.stl output_dir/
|
||||
```
|
||||
|
||||
Produces:
|
||||
- **diff-A-minus-B.png** — Geometry in original but MISSING from reconstruction
|
||||
- **diff-B-minus-A.png** — EXTRA geometry in reconstruction
|
||||
- **overlay.png** — Both models overlaid
|
||||
- **Geometric accuracy %** — Based on volume of boolean differences
|
||||
|
||||
### `openscad-sdf-optimize.py` — Parameter Optimizer
|
||||
|
||||
```bash
|
||||
python3 scripts/openscad-sdf-optimize.py model.stl stadium-slot --verbose
|
||||
```
|
||||
|
||||
Uses Signed Distance Fields + IoU scoring to find optimal parameters without invoking OpenSCAD in the loop. Converges in seconds via `scipy.optimize.minimize`.
|
||||
|
||||
### `openscad-stl-analyze.sh` — Raw Mesh Analysis
|
||||
|
||||
```bash
|
||||
bash scripts/openscad-stl-analyze.sh model.stl # Full analysis
|
||||
bash scripts/openscad-stl-analyze.sh model.stl --cross-section z 5.0 # Slice at Z=5
|
||||
bash scripts/openscad-stl-analyze.sh model.stl --gaps y # Find Y-axis gaps
|
||||
```
|
||||
|
||||
## STL-to-SCAD Reconstruction
|
||||
|
||||
The reconstruction pipeline converts triangle meshes into clean, parametric OpenSCAD code:
|
||||
|
||||
### The Sculptor Approach
|
||||
|
||||
All reconstructions follow the sculptor method — start from a solid block, subtract everything:
|
||||
|
||||
```openscad
|
||||
difference() {
|
||||
solid_body(); // 1. Full solid first
|
||||
channels(); // 2. Subtract channels/slots
|
||||
taper_cuts(); // 3. Subtract wedges
|
||||
all_holes(); // 4. ALL holes LAST
|
||||
}
|
||||
```
|
||||
|
||||
### Two-Tier Pipeline
|
||||
|
||||
1. **SVG Profile Analysis** (fast) — `openscad-stl-reconstruct.sh` identifies the model topology by slicing at multiple Z levels
|
||||
2. **SDF Optimization** (precise) — `openscad-sdf-optimize.py` finds exact parameters via IoU scoring
|
||||
|
||||
### Proven Results
|
||||
|
||||
| Model | Complexity | Accuracy | Iterations |
|
||||
|-------|-----------|----------|------------|
|
||||
| Toothpaste Squeezer | Simple (1180 tri) | 96.27% | 2 |
|
||||
| Interior Bracket | Complex (7576 tri) | 95.63% | 8 |
|
||||
|
||||
See `references/reconstruction-guide.md` for the complete best practices guide.
|
||||
|
||||
## Templates
|
||||
|
||||
### `printable-lib.scad` — Reusable Modules
|
||||
|
||||
```openscad
|
||||
use <printable-lib.scad>
|
||||
|
||||
shell_box(outer=[60,40,20], wall=2, floor=2);
|
||||
rounded_box([50,30,10], r=3);
|
||||
screw_clearance_hole(d=3, h=10, fit="close");
|
||||
counterbore_hole(shaft_d=3, head_d=6, head_h=3, h=12);
|
||||
countersink_hole(d=3, cs_d=6, cs_h=2, h=10);
|
||||
heatset_boss(insert_d=4.6, insert_h=5, wall=2, h=8);
|
||||
screw_post(outer_d=7, inner_d=3, h=10);
|
||||
rib(len=20, height=12, thick=2);
|
||||
snap_tab(width=8, length=6, thick=1.5, overhang=0.8);
|
||||
text_label("Hello", size=8, depth=1);
|
||||
|
||||
fit_clearance("press"); // 0.15mm
|
||||
fit_clearance("close"); // 0.25mm
|
||||
fit_clearance("slide"); // 0.30mm
|
||||
fit_clearance("loose"); // 0.40mm
|
||||
```
|
||||
|
||||
## 3D Printing Guidelines
|
||||
|
||||
- **Wall thickness**: min 1.2mm (FDM with 0.4mm nozzle)
|
||||
- **Clearance**: 0.2-0.3mm for fitting parts
|
||||
- **Overhangs**: < 45° from vertical; prefer chamfers on downward faces
|
||||
- **Epsilon** (`eps = 0.01`) in all boolean operations
|
||||
- **Flat bottoms** for bed adhesion
|
||||
- **`assert()`** for self-validating parametric models
|
||||
- **Counterbore vs countersink**: always check reference images
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `OPENSCAD_BIN` | `$(command -v openscad)` | Path to OpenSCAD binary |
|
||||
| `OPENSCAD_IMGSIZE` | `800,600` | Default preview image size |
|
||||
| `OPENSCAD_COLORSCHEME` | `DeepOcean` | Default color scheme |
|
||||
|
||||
## Eval Framework
|
||||
|
||||
The skill includes automated testing:
|
||||
|
||||
```bash
|
||||
ls eval/
|
||||
# eval.json — 4 test scenarios, 20 binary assertions
|
||||
# results.jsonl — Test results log
|
||||
```
|
||||
|
||||
**Baseline: 100% pass rate (20/20)** across:
|
||||
- Design (simple box + sculptor approach)
|
||||
- STL reconstruction (96.27% geometric accuracy)
|
||||
- Parametric export with -D overrides
|
||||
|
||||
## Contributing
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch
|
||||
3. Make changes
|
||||
4. Run: `bash scripts/openscad-render.sh quick templates/bracket.scad`
|
||||
5. Submit a pull request
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
|
||||
## Credits
|
||||
|
||||
Built with Claude Code (Anthropic), with architectural input from Gemini (Google) and Codex (OpenAI).
|
||||
|
||||
Powered by [OpenSCAD](https://openscad.org/) — The Programmers Solid 3D CAD Modeller.
|
||||
Reference in New Issue
Block a user