openscad-engine

name	openscad-engine
display_name	Virtual OpenSCAD Engine
description	Generate, preview, and export parametric 3D models using OpenSCAD scripting, including primitive shapes, CSG operations, transformations, full script execution, and STL/3MF export via the OpenSCAD CLI
category	dev-tools
icon	box
skill_type	sandbox
catalog_type	addon
requirements	httpx>=0.25
tool_schema	{"name":"openscad-engine","description":"Generate parametric 3D models using OpenSCAD scripting — create primitive shapes, perform CSG boolean operations, apply transformations, export .scad scripts, and render to STL or 3MF using the OpenSCAD CLI","parameters":{"type":"object","properties":{"action":{"type":"string","description":"Which operation to perform","enum":["generate_script","primitive","csg_operation","transform","full_model","inspect_script","export"]},"shape":{"type":"string","description":"Primitive shape for 'primitive' action: cube, sphere, cylinder, cone, torus, polyhedron","default":""},"params":{"type":"object","description":"Shape or operation parameters as a JSON object (e.g. {\"size\": [10,10,10], \"center\": true} for cube)","default":{}},"operation":{"type":"string","description":"CSG operation for 'csg_operation' action: union, difference, intersection, hull, minkowski","default":""},"children":{"type":"array","description":"List of OpenSCAD child shape strings for CSG or transform operations","default":[]},"transform":{"type":"string","description":"Transformation for 'transform' action: translate, rotate, scale, mirror, linear_extrude, rotate_extrude, offset","default":""},"transform_params":{"type":"object","description":"Parameters for the transformation (e.g. {\"v\": [10, 0, 0]} for translate)","default":{}},"script":{"type":"string","description":"Raw OpenSCAD script string for 'generate_script' or 'inspect_script' actions","default":""},"description":{"type":"string","description":"Natural language description of the 3D model to generate for 'full_model' action","default":""},"filename":{"type":"string","description":"Output filename without extension (default: 'model')","default":"model"},"include_comments":{"type":"boolean","description":"Include explanatory comments in the generated script","default":true},"export_format":{"type":"string","description":"Export format for 'export' action: stl, 3mf, off, amf, csg, dxf, svg, png","default":"stl"},"scad_file":{"type":"string","description":"Path to an existing .scad file to export (used with 'export' action)","default":""},"use_bosl2":{"type":"boolean","description":"Include BOSL2 library import at the top of generated scripts (requires BOSL2 installed in OpenSCAD libraries)","default":false}},"required":["action"]}}

Virtual OpenSCAD Engine

Generate, compose, export, and render parametric 3D models using OpenSCAD scripting. Supports primitive shapes, CSG boolean operations, transformations, full model generation from natural language descriptions, and export to STL or 3MF via the OpenSCAD CLI. Optionally leverages the BOSL2 open-source OpenSCAD library for advanced geometry.

Actions

primitive

Generate a single OpenSCAD primitive shape with parameters.

• shape: cube | sphere | cylinder | cone | torus | polyhedron
• params: shape-specific parameters
• filename: output file name
• use_bosl2: prepend BOSL2 include for access to its primitives

Examples:

• action: primitive, shape: "cube", params: {"size": [20, 10, 5], "center": true}
• action: primitive, shape: "sphere", params: {"r": 15, "$fn": 64}
• action: primitive, shape: "cylinder", params: {"h": 20, "r1": 10, "r2": 5, "$fn": 32}

Returns: script content, filename, shape summary.

csg_operation

Combine shapes using Constructive Solid Geometry boolean operations.

• operation: union | difference | intersection | hull | minkowski
• children: list of OpenSCAD shape strings to combine
• filename: output file name

Example:

• action: csg_operation, operation: "difference", children: ["cube([20,20,20], center=true)", "sphere(r=12, $fn=64)"]

Returns: combined OpenSCAD script, filename.

transform

Apply a geometric transformation to one or more shapes.

• transform: translate | rotate | scale | mirror | linear_extrude | rotate_extrude | offset
• transform_params: parameters for the transform
• children: shapes to transform
• filename: output file name

Example:

• action: transform, transform: "translate", transform_params: {"v": [0, 0, 10]}, children: ["sphere(r=5, $fn=32)"]

Returns: transformed OpenSCAD script, filename.

generate_script

Save a raw OpenSCAD script string to a .scad file with optional validation and formatting.

• script: raw OpenSCAD code
• filename: output file name
• include_comments: add header comments
• use_bosl2: prepend BOSL2 include

Example:

• action: generate_script, script: "cube([10,10,10]); translate([15,0,0]) sphere(r=5);", filename: "my_model"

Returns: saved file path, line count, detected constructs.

full_model

Generate a complete parametric OpenSCAD model from a natural language description. The engine interprets the description and builds an appropriate multi-part script, optionally using BOSL2 for advanced features.

• description: what the model should look like
• filename: output file name
• include_comments: add explanatory comments
• use_bosl2: use BOSL2 library primitives where applicable

Examples:

• action: full_model, description: "a hollow cylinder with a flat base and 4 mounting holes"
• action: full_model, description: "a gear with 20 teeth, 5mm bore, 2mm module"
• action: full_model, description: "chess pawn piece"

Returns: full .scad file, part breakdown, parameter list.

inspect_script

Analyze an existing OpenSCAD script and return a structured summary of its constructs, modules, variables, and suggestions.

• script: OpenSCAD code to inspect

Returns: modules found, variables, primitives, transformations, CSG ops, suggestions.

export

Export an existing .scad file to STL, 3MF, or another format using the OpenSCAD CLI.

• scad_file: path to the .scad file (or leave empty and set filename if the file was just generated)
• export_format: stl | 3mf | off | amf | csg | dxf | svg | png (default: stl)
• filename: base name for the output file

The skill auto-detects the OpenSCAD binary from common installation paths (openscad, /usr/bin/openscad, /usr/local/bin/openscad, /Applications/OpenSCAD.app/Contents/MacOS/OpenSCAD, C:\Program Files\OpenSCAD\openscad.exe).

Returns: exported file path, format, file size, or an error if OpenSCAD is not installed.

BOSL2 Library

When use_bosl2: true is set, the generated script prepends:

include <BOSL2/std.scad>

This gives access to BOSL2's extended primitives (cuboid, cyl, sphere, rounded shapes), attachments, threading, gears, and much more. BOSL2 must be installed in your OpenSCAD libraries folder. See https://github.com/BelfrySCAD/BOSL2 for installation instructions.

Usage Tips

• Be proactive: When a user asks for any 3D shape or model, immediately call full_model with their description — don't ask for clarification unless the request is truly ambiguous.
• Export after generation: After generating a .scad file, call export with export_format: "stl" or "3mf" to produce a print-ready file.
• Compose operations: For complex models, chain actions — first create primitives, then combine with csg_operation, then apply transform.
• Always provide $fn: Include $fn (e.g. 32 or 64) in sphere/cylinder params for smooth curves in the output.
• Suggest improvements: After generating, mention parametric variables the user could tweak (radius, height, wall thickness, etc.).
• File naming: Use descriptive filename values matching the model (e.g. "chess_pawn", "mounting_bracket").
• Full model is preferred: For anything beyond a single primitive, use full_model — it produces the most complete, commented, parametric output.
• BOSL2 for complex geometry: For threads, gears, rounded shapes, or attachments, enable use_bosl2: true.