Openscad

OpenSCAD Skill

Design, render, preview, and export 3D models using OpenSCAD's programmatic CAD engine.

Speed comes from picking the right mode, not from cutting corners inside one. Generating code takes seconds in every mode; what costs time is asking questions that could have been guessed, rendering four views when one answers, reconstructing a mesh that only needed a hole moved, and printing a part whose clearances were never measured. The mode table below exists to spend that time only where it buys something.

Environment

• OpenSCAD binary: resolved at runtime by every script as $OPENSCAD_BIN, else command -v openscad. Linux: sudo pacman -S openscad (Arch) or the distro equivalent. macOS: brew install openscad. Never hardcode a path.
• Python deps (Reconstruct and Replicate only — Quick, Modify, Design and Export do not need them): trimesh, numpy, scipy, shapely, rtree. On Arch install them from the repos (python-trimesh and friends), not with pip: the interpreter is externally managed.
• Working directory for designs: ~/openscad-projects/, one subdirectory per project. Quick mode is the exception and writes flat files into ~/openscad-projects/_quick/.
• Skill scripts: ~/.claude/skills/openscad/scripts/
• Templates: ~/.claude/skills/openscad/templates/
• Printer profile: ~/.claude/skills/openscad/templates/printer-profile.scad — the measured behaviour of the actual printer. Read it before emitting any part whose function depends on a fit, and say out loud when profile_measured is still false.
• Language reference: ~/.claude/skills/openscad/references/

Modes

The skill operates in eight modes, auto-detected from the user's request. The first two are the fast ones and cover most real requests — reach for the others only when they are the job.

Choosing between Quick, Modify and Design. Quick guesses and shows; Design asks and then shows. If the part is simple enough that wrong guesses are cheap to correct on screen, Quick wins because it costs one round trip instead of two. If the user hands you an existing STL, Modify beats both — and it beats Reconstruct too, unless they actually need the geometry to become parametric.

Workflow: Quick Mode

The default for "I need a simple part". The point is one round trip: the user describes the object and gets back a rendered part plus the list of everything that was assumed. They correct the assumptions that are wrong instead of answering a questionnaire first.

Step 1: Do not ask. Infer, and write down what you inferred.

Skip the clarification round. Derive whatever can be derived from the request, pick defensible defaults for the rest, and keep an explicit list of every value you invented. That list is what you hand back, and it is what makes guessing safe.

Standing defaults, unless the request says otherwise: wall 2mm, floor 2mm, corner radius 2mm, fit_clearance("close") for anything receiving a screw or a shaft, $fn = 64, flat bottom on the bed, no support.

Only stop and ask when a missing number makes the part meaningless rather than merely wrong — you cannot invent the diameter of the tube a holder has to hold. One question, then proceed.

Step 2: Start from the library, not from an empty file

mkdir -p ~/openscad-projects/_quick

Write a single file ~/openscad-projects/_quick/<name>.scad. No project scaffolding, no src/ and output/ tree: a quick part that needs a directory structure is not quick.

use <printable-lib.scad>   // resolved via OPENSCADPATH, set by the skill scripts

⚠️ Never write a ~ inside use <> or include <>. OpenSCAD does not expand the tilde, and the failure is silent: the library is simply not found and every module call errors out. The skill scripts export OPENSCADPATH pointing at templates/, so the bare filename works from any directory. If you invoke openscad by hand outside those scripts, export it yourself:

export OPENSCADPATH=~/.claude/skills/openscad/templates

The library already carries counterbores, heat-set bosses, screw posts, ribs, snap tabs, rounded boxes, shells, vents and lid lips, and those modules already read the printer profile. Keep the Feature Tree structure from Design mode (parameters, derived, profile, body, add, cut, assembly): it costs nothing and makes the next change trivial.

Step 3: Deterministic gate, before you look at anything

bash ~/.claude/skills/openscad/scripts/openscad-validate.sh ~/openscad-projects/_quick/<name>.scad

Check what can be computed rather than seen:

• it compiles, with no warnings about unassigned variables
• the bounding box matches the dimensions the user actually gave
• no wall thinner than min_wall, no floor thinner than min_floor (printer profile)
• overhangs within max_overhang, or support is called out
• the part fits bed_size

⚠️ openscad-validate.sh is a report, not a gate: it exits 0 even when the file is broken. Read the Category: line — OK passes, anything else (SYNTAX_ERROR, WARNING, …) stops the part here. Do not rely on the exit code or on set -e to catch it.

A part that fails here never reaches the render. The eye is for shape; these are arithmetic, and arithmetic should not cost a vision call.

Step 4: One render, isometric

bash ~/.claude/skills/openscad/scripts/openscad-render.sh quick ~/openscad-projects/_quick/<name>.scad

One image, not four. Read it and check the shape is what was asked for. Four angles belong to Design mode, where the geometry is complex enough to hide something.

Step 5: Hand it back with the assumptions visible

Report, in this order:

1. the preview
2. the assumptions list — every invented number, one per line, so the wrong ones are obvious at a glance
3. the parametric knobs, so a change is a -D away and not a rewrite
4. ⚠️ if profile_measured is false and the part has a fit, say that the clearances are declared defaults and not measurements, and that the first print is the one that tells

Then stop. The user corrects an assumption or asks for the STL. Do not iterate on your own initiative: in Quick mode a second unrequested render is wasted time.

Step 6: Export, when asked

bash ~/.claude/skills/openscad/scripts/openscad-render.sh export ~/openscad-projects/_quick/<name>.scad

When to abandon Quick mode: the moment the part grows a third interacting feature, or a dimension turns out to depend on a measurement nobody has, switch to Design mode and say so. Quick mode that keeps iterating is Design mode with worse manners.

Workflow: Modify Mode

The fastest useful thing in this skill, and the most common real job. A model already exists — downloaded, or printed once and not quite right — and it needs one change: a hole somewhere else, two millimetres more clearance, a boss added, a face flattened.

Do not reconstruct it. Reconstruction turns a mesh back into parametric code and costs hours. Modify treats the mesh as a solid and cuts into it, which costs minutes and needs nothing beyond openscad itself: no Python, no analysis pipeline.

Step 1: Import and see it

// modify.scad
$fn = 64;
eps = 0.01;
original = "/absolute/path/to/model.stl";

import(original, convexity = 10);

convexity matters: without it a preview of a mesh with internal cavities renders wrong. Render once with openscad-render.sh quick and confirm you are looking at the right object.

Step 2: Find the coordinates you need

The mesh arrives in its own coordinate system, which is rarely the one you want.

python3 ~/.claude/skills/openscad/scripts/openscad-profile-extract.py model.stl --json /tmp/m.json

If the Python stack is not available, the bounding box alone covers most edits, and OpenSCAD gives it for free by rendering the model against a known reference cube. Do not guess coordinates from a picture: that is Rule 2 of Reconstruct mode, and it applies here just as hard.

Step 3: Cut, add, or trim

difference() {
    import(original, convexity = 10);

    // a new hole, positioned against a real reference, never a magic number
    translate([hole_x, hole_y, -eps])
        cylinder(h = part_h + 2*eps, d = 4 + fit_clearance("close"));
}

The three edits that cover almost everything:

Widening an existing hole is a subtraction, not an edit: put a larger cylinder exactly on the old axis. Finding that axis is the whole job, and it comes from measurement, not from the render.

⚠️ Booleans on an imported mesh are only as sound as the mesh. If the STL is not manifold, OpenSCAD will still produce something and it will be wrong. Check first:

bash ~/.claude/skills/openscad/scripts/openscad-stl-analyze.sh model.stl

A non-manifold input is the one case where Modify is not the answer: repair the mesh first, or reconstruct it.

Step 4: Verify against the original

bash ~/.claude/skills/openscad/scripts/openscad-stl-compare.sh model.stl modified.stl /tmp/cmp/

The boolean difference should show exactly the change that was asked for and nothing else. A surprise elsewhere in the diff means a coordinate is wrong, and seeing it here is far cheaper than seeing it after the print.

Step 5: Export

bash ~/.claude/skills/openscad/scripts/openscad-render.sh stl ~/openscad-projects/_quick/modify.scad

The result is a mesh, not parametric code: the change is repeatable by editing modify.scad, but the original geometry stays opaque. That is the trade — minutes instead of hours, at the price of not owning the shape. When the user needs to own it, that is Reconstruct mode, and it should be chosen deliberately rather than fallen into.

Workflow: Design Mode

When the user asks to create a new 3D object:

Step 1: Understand Requirements

Clarify with the user:

• What is the object? (enclosure, bracket, gear, container, etc.)
• Dimensions — key measurements in mm
• Purpose — functional print, aesthetic, mechanical fit?
• Constraints — printer bed size, material, wall thickness preferences
• Parametric? — which dimensions should be adjustable?

Step 2: Set Up Project

bash ~/.claude/skills/openscad/scripts/openscad-project.sh init "<project-name>"

This creates ~/openscad-projects/<project-name>/ with subdirectories for source, output, and previews.

Step 3: Generate the .scad File

Write the OpenSCAD code to ~/openscad-projects/<project-name>/src/main.scad.

Mandatory file structure (Feature Tree pattern):

// 1. PARAMETERS (independent variables)
width = 60;  height = 30;  wall = 2;

// 2. DERIVED DIMENSIONS (calculated from parameters)
inner_width = width - 2 * wall;

// 3. BASE PROFILE (2D sketch — the core shape)
module sketch_base() {
    offset(r = corner_r)
        square([width - 2*corner_r, depth - 2*corner_r], center=true);
}

// 4. PRIMARY BODY (extrude the sketch)
module body() { linear_extrude(height = height) sketch_base(); }

// 5. ADDITIVE FEATURES (bosses, ribs, tabs)
module features_add() { ... }

// 6. SUBTRACTIVE FEATURES (holes, slots, pockets — ALWAYS LAST)
module features_cut() { ... }

// 7. ASSEMBLY (the Feature Tree)
difference() {
    union() { body(); features_add(); }
    features_cut();
}

Profile-first design rules:

• Prefer polygon() + linear_extrude() over hull() of 3D primitives
• Use offset(r=radius) for corner rounding instead of hull() with cylinders
• Use rotate_extrude() for axially symmetric parts (never stack cylinders)
• Define dimensions relative to edges/features, not absolute coordinates: hole_x = total_length - edge_margin (not magic numbers)
• Cascade tolerances from a single fit_clearance parameter

Critical rules for generating OpenSCAD code:

• Read ~/.claude/skills/openscad/references/language-reference.md if unsure about syntax
• Always define parametric dimensions as variables at the top of the file
• Use $fn = 64; for smooth curves (or higher for final renders)
• Add comments explaining each section
• Use modules for reusable parts
• Keep wall thickness >= 1.2mm for FDM printing
• Design with the print orientation in mind (flat bottom, minimal overhangs)

Step 4: Preview

Render a multi-angle PNG preview:

bash ~/.claude/skills/openscad/scripts/openscad-render.sh preview ~/openscad-projects/<project-name>/src/main.scad

This generates 4 preview images (front, side, top, isometric) in the project's previews/ directory.

Step 5: Analyze Preview

Read each preview PNG using the Read tool to see the rendered object. Evaluate:

• Does the shape match the user's description?
• Are proportions correct?
• Are there visible artifacts or unintended geometry?
• Would this print well? (overhangs, bridging, thin walls)

Report findings to the user with the preview images.

Step 6: Iterate

If changes are needed, edit the .scad file and re-render. Repeat Steps 4-5 until the user is satisfied. Each iteration should be targeted — change one aspect at a time.

Step 7: Export

When the design is approved:

bash ~/.claude/skills/openscad/scripts/openscad-render.sh export ~/openscad-projects/<project-name>/src/main.scad

This produces:

• output/model.stl — for slicing and printing
• output/model.3mf — alternative format (better metadata)
• previews/final-preview.png — high-res final render

Workflow: Replicate Mode

When the user provides reference images of a physical object to reproduce in OpenSCAD:

Step 1: Analyze Reference Images

Read ALL provided reference images using the Read tool. For each image, extract:

• Overall shape: What geometric primitives compose this object?
• Proportions: Relative dimensions (height-to-width ratio, etc.)
• Features: Holes, fillets, chamfers, textures, slots, lips, threads
• Symmetry: Is it symmetric along any axis?
• Construction: How would you decompose it into boolean operations?

If dimensions are provided, note them. If not, estimate proportions from the images and ask the user for at least one known measurement to establish scale.

Step 2: Create Decomposition Plan

Before writing any code, describe the object as a series of OpenSCAD operations:

Object: Phone stand
Decomposition:
1. Base: flat rectangle with rounded corners (80x60x5mm)
2. Back support: angled plate (60x3mm, tilted 70 degrees)
3. Front lip: small ridge to hold phone (60x3x8mm)
4. Fillet: smooth transition between base and back support
5. Cable channel: cylinder subtracted from base center

Present this plan to the user for confirmation before coding.

Step 3: Generate Initial .scad File

Write the OpenSCAD code based on the decomposition. Set up the project:

bash ~/.claude/skills/openscad/scripts/openscad-project.sh init "<object-name>"

Write the .scad to the project's src/main.scad.

Step 4: Render and Compare

Generate a preview from the same angle as the reference image:

bash ~/.claude/skills/openscad/scripts/openscad-render.sh quick ~/openscad-projects/<name>/src/main.scad

Read both the reference image and the rendered preview. Compare them side by side mentally:

• Does the overall silhouette match?
• Are proportions correct?
• Are features (holes, edges, curves) in the right places?
• What's the biggest discrepancy?

Step 5: Iterative Refinement Loop

For each discrepancy found:

1. Identify which part of the .scad code controls the mismatched feature
2. Make a single targeted edit to improve the match
3. Re-render from the same angle
4. Re-compare with the reference

Refinement priorities (fix in this order):

1. Overall shape and proportions
2. Major features (holes, cutouts, protrusions)
3. Angles and curves
4. Fillets, chamfers, and surface details
5. Fine details

Step 6: Multi-Angle Validation

Once the primary angle looks good, render from all angles that have reference images:

bash ~/.claude/skills/openscad/scripts/openscad-render.sh preview ~/openscad-projects/<name>/src/main.scad

Compare each rendered view against its corresponding reference image. Fix any angle-specific discrepancies.

Step 7: Dimensional Verification

If the user provided measurements, add echo() statements to verify:

echo("Total width:", width);
echo("Total height:", height);
echo("Wall thickness:", wall);

Render with echo capture to verify dimensions match specifications.

Step 8: Export

When the user confirms the replication is satisfactory, export for printing.

Tips for Accurate Replication

• Start simple: Begin with bounding-box primitives, then refine
• Use reference dimensions: If user says "it's about 10cm tall", anchor ALL proportions to that
• Match camera angle: Use --camera to match the reference photo's perspective
• Organic shapes: Approximate with hull(), minkowski(), or rotate_extrude() of a profile
• Iterate small: Change one thing per render cycle
• Ask when unsure: If a feature is ambiguous from the images, ask the user rather than guessing

Workflow: Reconstruct Mode (STL-to-SCAD)

When the user provides an STL file and wants it converted to parametric OpenSCAD code:

Overview

STL files are triangle meshes with no semantic information about the original primitives or operations that created them. Reconstruction is the process of analyzing the mesh geometry and re-expressing it as clean, parametric OpenSCAD code. This is valuable because:

• Parametric code can be modified (change dimensions, add features)
• OpenSCAD code is human-readable and version-controllable
• The resulting model can be adapted to different use cases

Critical Rules for Reconstruction

Read references/reconstruction-guide.md before starting any reconstruction. It contains the complete best practices guide learned from real reconstructions.

Rule 1: SCULPTOR APPROACH (mandatory). Start from a full solid block, subtract ALL features. Never build up from pieces — CSG ordering bugs cause added material to cover previously-cut holes. Structure: difference() { solid_body(); channels(); tapers(); ALL_holes_LAST(); }

Rule 2: NEVER add features based on assumptions. Always verify with SVG contour data AND reference images. If a feature doesn't appear as a separate contour in the SVG slices, IT DOES NOT EXIST. Known hallucinations to avoid:

• Pyramids/cones from render shadows
• Cylinders from curved wall edges
• Top holes from through-hole exit points

Rule 3: Bounding box match ≠ correct model. 0.000mm bbox delta can mean only 70% geometric accuracy. Always use mesh comparison (openscad-stl-compare.sh) with boolean diff images.

Rule 4: ANALYZE FIRST, DECOMPOSE, THEN CHOOSE per-component approach. Do NOT jump to code. The analysis phase must answer these questions:

1. What are the dominant features? (diagonal arm, clips, channels, holes)
2. What is the thinnest axis? That's the likely extrusion direction — NOT necessarily the stability score winner
3. Can the object be decomposed into simpler sub-objects? Model each with its best technique
4. Where are internal channels/gaps? Slice along Z to find multi-body cross-sections

Rule 5: Choose the extrusion axis by geometry, not just stability score.

The profile extractor's stability score finds the axis with the most uniform cross-section. But this is misleading for models with diagonal features — slicing along Z for a diagonal bracket produces staircase artifacts. Instead:

# Always run ALL analysis tools before writing any code:
bash ~/.claude/skills/openscad/scripts/openscad-stl-reconstruct.sh model.stl analysis/
python3 ~/.claude/skills/openscad/scripts/openscad-profile-extract.py model.stl --json analysis/profile.json
python3 ~/.claude/skills/openscad/scripts/openscad-adaptive-slice.py model.stl analysis/

After analysis, compare: thinnest axis extent vs stability-score axis. If they differ, the thinnest axis is usually better for models with angled features.

Rule 6: Choose the right technique for each component:

Rule 7: hull() ONLY for convex profiles. Hull between two profiles creates the convex hull — it fills in ALL concavities (channels, clips, U-forks, hooks). Only use hull for simple solid zones with 1 contour and no holes. For concave profiles, use linear_extrude of a representative profile instead.

Rule 8: Dense X-slab approach for complex models. When no single extrusion works, slice every 2mm along the thinnest axis:

1. At each X position, extract the full Y-Z cross-section (ALL bodies, not just the largest)
2. Extrude each slab for 2mm width
3. Union all slabs — gaps between bodies are naturally preserved
4. Note: this approach has a ~6% volume overestimate floor from polygon extraction artifacts. Below 6% requires hand-modeled parametric geometry.

Use the automated reconstruction analysis FIRST — before writing any code:

bash ~/.claude/skills/openscad/scripts/openscad-stl-reconstruct.sh model.stl output_dir/

This runs the full pipeline: mesh stats (trimesh), 2D profile slices (OpenSCAD projection), primitive detection (RANSAC/normal analysis), and generates SVG profiles at multiple Z levels. The SVG profile analysis is the MOST IMPORTANT output — it reveals the complete cross-section structure at each height level.

The SVG Profile Method (preferred over vertex analysis):

1. projection(cut=true) slices the STL at a Z height → exports 2D SVG
2. Parse the SVG to count contours: BODY (large area) vs HOLES (small area)
3. Compare contours at different Z levels to understand how the shape changes with height
4. This reveals: channels, slots, holes, wall thickness, taper angles — all from 2D data

After analysis, verify with mesh comparison:

bash ~/.claude/skills/openscad/scripts/openscad-stl-compare.sh original.stl reconstruction.stl output_dir/

Target: >95% geometric accuracy. Use diff images to identify remaining discrepancies.

Step 1: Automated Analysis (run ALL tools)

# Tool 1: SVG profiling + primitive detection
bash ~/.claude/skills/openscad/scripts/openscad-stl-reconstruct.sh model.stl analysis/

# Tool 2: Profile extraction + extrusion axis detection
python3 ~/.claude/skills/openscad/scripts/openscad-profile-extract.py model.stl \
    --output analysis/profile.scad --json analysis/profile.json

# Tool 3: Adaptive multi-axis feature map
python3 ~/.claude/skills/openscad/scripts/openscad-adaptive-slice.py model.stl analysis/

Key outputs to examine:

• analysis/slices/*.svg — 2D profiles at 5 Z levels
• analysis/profile.json — extrusion axis, stability score, profile points, hole count
• analysis/adaptive-slicing.json — feature zones on all 3 axes, transition locations
• analysis/primitives.json — detected cylinders/planes
• analysis/mesh-info.json — volume, dimensions, symmetry

Step 1b: Understand the Object (BEFORE writing code)

After running analysis tools, render multi-angle previews and answer:

1. What are the main components? (e.g. "bottom clip + diagonal arm + top clip")
2. Which axis is thinnest? Compare extents — the thinnest is likely the extrusion direction
3. Are there diagonal/angled features? If yes, the stability-score axis is probably WRONG
4. Where do cross-sections change? Check the adaptive slicer's transition zones
5. Are there multi-body zones? (channels, rails, gaps between parts)

Decision tree — axis selection:

1. If stability_score < 0.1 AND thinnest axis matches stability axis → clean extrusion, use profile.scad
2. If model has diagonal features → use the thinnest axis regardless of stability score
3. If stability_score < 0.3 AND no diagonals → stability axis + feature variations
4. If stability_score > 0.3 → complex shape. Try dense X-slab along thinnest axis, or decompose into sub-objects

Decision tree — technique per component:

• Simple extruded body → profile + linear_extrude along extrusion axis
• Diagonal arm/strut → profile along thinnest axis captures it naturally
• Clips, hooks, U-channels → profile extraction (NOT hull — hull fills concavities)
• Cylindrical features → parametric circle() + square(), NOT polygon profiles
• Smooth convex transitions → hull() between boundary profiles (ONLY if convex)
• Complex multi-width → dense 2mm slabs along thinnest axis

For models with cylindrical features (stability > 0.3 or SVG shows circular contours):

• Do NOT rely on polygon profiles — they approximate curves poorly
• Identify circle centers and radii from the SVG contour data
• Model with circle() + square() in 2D, then extrude

Then render multi-angle previews:

// Temporary viewer file
import("path/to/model.stl");

bash ~/.claude/skills/openscad/scripts/openscad-render.sh preview /tmp/stl-viewer.scad

Read all preview images to understand the 3D shape from multiple angles.

Step 1b: Auto-Reconstruction (NEW — recommended for most models)

After running the adaptive slicer, use the auto-reconstructor to generate parametric .scad directly:

# Option A: With pre-computed analysis
python3 ~/.claude/skills/openscad/scripts/openscad-auto-reconstruct.py model.stl \
    --analysis analysis/ --output project/src/main.scad

# Option B: Run analysis + reconstruction in one step
python3 ~/.claude/skills/openscad/scripts/openscad-auto-reconstruct.py model.stl \
    --output project/src/main.scad --run-analysis

# Option C: Tighter circle fitting for precision parts
python3 ~/.claude/skills/openscad/scripts/openscad-auto-reconstruct.py model.stl \
    --analysis analysis/ --output project/src/main.scad --circle-threshold 0.3

This automatically:

1. Parses the feature map JSON into zones
2. Extracts profiles at zone boundaries
3. Fits circles/arcs to replace polygon approximations (Feature 3)
4. Generates hull() blends for transition zones (Feature 2)
5. Emits one OpenSCAD module per zone with sculptor assembly (Feature 1)

The output is a good starting point — review and refine the generated .scad, then verify with mesh comparison. For models with cylindrical features, this typically achieves >85% accuracy automatically (vs 75% with polygon-only).

Step 2: Detailed Structure Mapping

For simple models (5 SVG slices are enough): Parse the SVG contours to count bodies vs holes at each Z level.

For complex models (brackets, enclosures with multiple features): Use the adaptive multi-axis slicer for efficient feature detection:

python3 ~/.claude/skills/openscad/scripts/openscad-adaptive-slice.py model.stl analysis/

This automatically: scans all 3 axes with coarse pass (5mm) → detects transitions → fine pass (0.5mm) around transitions. Produces a feature map classifying each zone as solid, shell_or_channel, multi_body, or complex.

For manual fine-grained slicing at specific heights:

for z in $(seq 0.5 1 <max_z>); do
    echo "projection(cut=true) translate([0,0,-$z]) import(\"model.stl\");" > /tmp/s.scad
    openscad -o "slices/z${z}.svg" /tmp/s.scad
done

Parse each SVG to build a structural map:

Z=0-5:   1 body (full width) + 8 holes     → Solid base with screw holes
Z=5-10:  2 bodies + 8 holes                → Channel appeared, walls split
Z=10-20: 2 bodies narrowing                → Taper zone (measure rate)
Z=20-33: 2 bodies constant width           → Top section
Z=25-27: Bodies interrupted                → Counterbore pockets at this depth

Hole positions from SVG centroids — for each hole contour at a given Z, compute the centroid. This gives exact X,Y positions far more reliably than vertex analysis.

Feature verification rule: If a feature doesn't appear as a distinct contour in the SVG data, IT DOES NOT EXIST in the model. Never add features based on visual interpretation of 3D renders alone.

Step 3: Choose Approach and Decompose

Based on the analysis data, choose the reconstruction approach:

Approach A — Profile Extrusion (for extruded parts, stability < 0.3):

# The profile extractor already generated the .scad — use it as a starting point
cat analysis/profile.scad
# Adjust: add cavity with offset(delta=-wall), add floor, add features

Approach B — Parametric Primitives (for known shapes or cylindrical features): Create a decomposition plan using measured dimensions from SVG data:

Decomposition:
1. Base: square([80, 80]) + circle tabs — from SVG outer contour at Z=mid
2. Cavity: offset(delta=-wall) of base — from SVG inner contour
3. Floor: solid at Z=0 to floor_h — from SVG at Z=0 (1 contour = solid)
4. Holes: cylinder(d=3) at SVG hole centroids
5. Counterbores: cylinder(d=8, h=2) at same positions

Approach C — Hybrid (for complex shapes with both flat and curved features):

1. Extract polygon profile for the overall outline
2. Identify which curves in the profile are circles (regular spacing, arc-like)
3. Replace those polygon sections with parametric circle(r) operations
4. Assemble: square() + circle() union for tabs, difference() for slots

Counterbore vs Countersink — always verify from reference images:

• Counterbore: flat cylindrical pocket (cylinder(d=cb_d, h=cb_depth))
• Countersink: conical taper (cylinder(d1=cs_d, d2=hole_d, h=cs_depth))
• Most 3D-printed parts use counterbores, not countersinks

Step 4: Write Parametric .scad Code

Create a new project and write the reconstructed code:

bash ~/.claude/skills/openscad/scripts/openscad-project.sh init "<name>-reconstructed"

Key principles for reconstruction:

• Extract ALL dimensions as named variables at the top
• Use meaningful variable names that describe the physical feature
• Add comments linking each section to the original STL features
• Include echo() statements for bounding box verification
• Add assert() for parameter ranges

Step 5: Visual Comparison Loop

Render the reconstructed .scad and compare side-by-side with the original STL renders:

1. Render the reconstruction from the same camera angles as Step 1
2. Read both sets of images
3. Compare silhouettes, proportions, and feature placement
4. Identify the biggest discrepancy
5. Fix it and re-render
6. Repeat until the reconstruction matches the original

Step 6: Overlay Verification

For precise verification, create an overlay .scad file:

// Overlay: original STL (transparent) vs reconstruction
%import("path/to/original.stl");  // % = transparent background
color("red", 0.6) reconstructed_model();

Render this overlay — any RED areas visible through the transparent original indicate reconstruction errors. Any grey areas not covered by red indicate missing geometry.

Step 7: Mesh-to-Mesh Comparison

This is the most important verification step. Export the reconstruction as STL and compare it against the original using boolean difference:

# Export reconstruction
bash ~/.claude/skills/openscad/scripts/openscad-render.sh stl ~/openscad-projects/<name>/src/main.scad

# Run mesh comparison
bash ~/.claude/skills/openscad/scripts/openscad-stl-compare.sh \
    path/to/original.stl \
    ~/openscad-projects/<name>/output/main.stl \
    ~/openscad-projects/<name>/previews/comparison

This produces:

• diff-A-minus-B.png — geometry in original but MISSING from reconstruction (what you need to add)
• diff-B-minus-A.png — EXTRA geometry in reconstruction not in original (what you need to remove)
• overlay.png — both models overlaid for visual check
• Geometric accuracy % — based on volume of boolean differences vs original volume

Target: >95% geometric accuracy. If below 95%, examine the diff images to identify which features are wrong, fix them, re-export, and re-compare. Iterate until accuracy is satisfactory.

Important: Bounding box delta can be 0.000mm while geometric accuracy is only 78% — internal features matter more than outer dimensions.

Step 8: Dimensional Verification

Compare echo output from the reconstruction with the STL bounding box:

echo(str("Reconstructed BBOX: ", width, " x ", depth, " x ", height));

Step 9: SDF Parameter Optimization (Advanced)

If the SVG profile method doesn't achieve >95% accuracy, use the SDF optimizer for automatic parameter tuning:

python3 ~/.claude/skills/openscad/scripts/openscad-sdf-optimize.py \
    path/to/original.stl \
    stadium-slot \
    --verbose \
    --output analysis/sdf-result.json

This works by:

1. Sampling 30,000 random points in the bounding box
2. Computing target occupancy (inside/outside original mesh) via trimesh
3. Defining the reconstruction as a parametric SDF (Signed Distance Field)
4. Using scipy.optimize.minimize(method="Powell") to maximize IoU (Intersection over Union)
5. Generating OpenSCAD code with optimized parameters

When to use: When you know the correct model topology (e.g., "stadium body with cylindrical slot") but can't find the exact parameters. The optimizer finds them automatically.

Supported model types: stadium-slot, box-holes. Add new types by defining an SDF function in the script.

Workflow: Run openscad-stl-reconstruct.sh first (to identify the model topology), then openscad-sdf-optimize.py (to find exact parameters), then openscad-stl-compare.sh (to verify).

Prerequisites: pip3 install trimesh numpy scipy rtree

Common Pitfalls

• Bounding box match ≠ correct model. A model with completely wrong internal geometry can still have a 0.000mm bounding box delta. Always verify visually from multiple angles.
• Don't assume features from renders alone. What looks like a cylinder in a top-down view might just be a curved wall edge. Always verify with vertex analysis.
• Coincident faces cause Z-fighting. If a feature touches the body boundary exactly, use intersection() to clip it cleanly rather than making it the exact same size.
• Don't flip between adding and removing features. If unsure whether a feature exists, run cross-section analysis before deciding. Oscillating between "add bar" and "remove bar" wastes iterations.
• Offset features are common. Cylinders, holes, and channels are often NOT centered. Always calculate the actual center from vertex data rather than assuming symmetry.

Limitations

• Organic shapes (sculpted, freeform surfaces) cannot be fully reconstructed as primitives. For these, keep the STL import and wrap it in a module.
• Very complex models (1000+ features) should be reconstructed incrementally, starting with the major body and adding features one group at a time.
• Thread geometry in STL is extremely difficult to reconstruct. Use threads.scad library instead of trying to match individual thread faces.
• Text/engravings embedded in STL meshes are very hard to extract. It's better to re-add text using OpenSCAD's text() module.

Hybrid Approach

For complex models, use a hybrid strategy:

// Import the complex organic base from STL
module original_base() {
    import("base-section.stl");
}

// Reconstruct and parameterize the mechanical features
module mounting_bracket(width=30, hole_d=5) {
    difference() {
        original_base();
        // Add parametric mounting holes
        for (pos = hole_positions)
            translate(pos) cylinder(d=hole_d, h=50, center=true);
    }
}

This lets the user modify the parametric parts while keeping the complex geometry intact.

Workflow: Refine Mode

When the user wants to modify an existing design:

Step 1: Read the Existing File

# Find .scad files in the project

Read the .scad source to understand the current design.

Step 2: Render Current State

bash ~/.claude/skills/openscad/scripts/openscad-render.sh preview /path/to/file.scad

Read the preview images to see what currently exists.

Step 3: Apply Changes

Edit the .scad file with the requested modifications. Use the Edit tool for surgical changes.

Step 4: Re-render and Compare

Generate new previews and visually compare with the previous version. Report what changed.

Step 5: Repeat or Export

Continue iterating or export when satisfied.

Workflow: Export Mode

Quick export of an existing .scad file:

# Single format
bash ~/.claude/skills/openscad/scripts/openscad-render.sh stl /path/to/file.scad

# Multiple formats
bash ~/.claude/skills/openscad/scripts/openscad-render.sh export /path/to/file.scad

# With parameter overrides
bash ~/.claude/skills/openscad/scripts/openscad-render.sh stl /path/to/file.scad -D 'width=50' -D 'height=30'

Workflow: Analyze Mode

Review a design for printability:

bash ~/.claude/skills/openscad/scripts/openscad-render.sh analyze /path/to/file.scad

This renders cross-section views and reports:

• Object bounding box dimensions
• Whether the mesh is manifold (watertight)
• Estimated print time indicators (volume, surface area from STL)
• Visual check of overhangs via bottom-up view

Script Reference

All scripts live in ~/.claude/skills/openscad/scripts/:

…(truncated)