text-to-cad

name Text to CAD description Use when the user provides a natural language description of a 3D object or mechanical part and wants to generate a CAD model. Converts the description into CadQuery Python code, automatically detects or sets up the CadQuery environment, executes the script, and produces STL and STEP output files. allowed-tools [] Text to CAD (CadQuery) This skill converts a natural language description of a 3D object into a fully functional CadQuery Python script, executes it, and delivers STL + STEP files. The workflow is designed to handle everything from simple primitives ("a cube with rounded edges") to complex mechanical assemblies ("a flanged bearing housing with bolt holes"). Phase 0: Environment Detection & Setup Before generating any model, automatically detect a working CadQuery environment . Follow this sequence -- stop at the first success: Check if cadquery is already importable : python -c "import cadquery; print(cadquery.__version__)" If this succeeds, use python directly as the interpreter. Search for conda/mamba environments that have cadquery : conda env list For each environment found, test: conda run -n <env_name> python -c "import cadquery; print(cadquery.__version__)" If one succeeds, use conda run -n <env_name> python as the interpreter. Search for virtual environments in the working directory or common locations ( .venv , venv , env ): # Linux/macOS .venv/bin/python -c "import cadquery; print(cadquery.__version__)" # Windows .venv/Scripts/python -c "import cadquery; print(cadquery.__version__)" If no environment found, install cadquery : Preferred: pip install cadquery (in current Python) Fallback: conda install -c conda-forge cadquery (if conda is available) Confirm installation succeeded before proceeding. Cache the result : Once a working interpreter command is found, reuse it for all subsequent executions in this session. Store it as CADQUERY_PYTHON (e.g., python , conda run -n myenv python , .venv/bin/python ). If all attempts fail, inform the user and provide manual installation instructions: pip install cadquery # or conda install -c conda-forge cadquery Phase 1: Requirement Analysis & Clarification When the user provides a natural language description: Parse the description to extract: Geometry type : primitive (box, cylinder, sphere), composite, or assembly Dimensions : explicit measurements (mm by default) or relative sizing Features : holes, fillets, chamfers, patterns, text, threads, etc. Spatial relationships : positions, alignments, symmetry Material/functional hints : load-bearing, aesthetic, printable, etc. Fill in missing details intelligently : If no units specified -> assume millimeters (mm) If no dimensions specified -> infer reasonable engineering defaults based on the object type If ambiguous geometry -> choose the most common/standard engineering interpretation If "printable" mentioned -> ensure manifold geometry, add appropriate tolerances Confirm understanding (brief, 2-3 sentences): Summarize what you will model State key dimensions and features Note any assumptions made Ask the user to confirm or adjust before proceeding Phase 2: Code Generation Generate a complete, self-contained CadQuery Python script following these mandatory rules : Code Structure Template """ CadQuery Model: {model_name} Description: {user_description} Generated dimensions: {key_dimensions} Units: millimeters (mm) """ import cadquery as cq import os # ============================================================ # Parameters (easy to modify) # ============================================================ # Group all dimensional parameters at the top for easy tweaking PARAM_NAME = value # description, unit # ============================================================ # Output Configuration # ============================================================ # Output to an "output" folder relative to this script's location. # The user can override OUTPUT_DIR if they prefer a different path. OUTPUT_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "output" ) MODEL_NAME = "{model_name}" os.makedirs(OUTPUT_DIR, exist_ok= True ) # ============================================================ # Model Construction # ============================================================ # Build the model step by step with comments explaining each operation result = ( cq.Workplane( "XY" ) .box(...) # ... operations ... ) # ============================================================ # Export # ============================================================ step_path = os.path.join(OUTPUT_DIR, f" {MODEL_NAME} .step" ) stl_path = os.path.join(OUTPUT_DIR, f" {MODEL_NAME} .stl" ) cq.exporters.export(result, step_path) cq.exporters.export(result, stl_path) print ( f"Model ' {MODEL_NAME} ' generated successfully!" ) print ( f" STEP: {step_path} " ) print ( f" STL: {stl_path} " ) # Print bounding box for verification bb = result.val().BoundingBox() print ( f" Bounding Box: {bb.xlen: .2 f} x {bb.ylen: .2 f} x {bb.zlen: .2 f} mm" ) CadQuery API Best Practices Primitives & Basic Shapes: cq.Workplane("XY").box(length, width, height) -- centered box cq.Workplane("XY").cylinder(height, radius) -- centered cylinder cq.Workplane("XY").sphere(radius) -- sphere cq.Workplane("XY").wedge(dx, dy, dz, xmin, zmin, xmax, zmax) -- wedge/prism 2D Sketch -> 3D Extrusion (most versatile pattern): result = ( cq.Workplane( "XY" ) .moveTo(x, y).lineTo(...).lineTo(...).close() # sketch profile .extrude(height) # or .revolve(angleDegrees, axisStart, axisEnd) ) Feature Operations: .fillet(radius) -- round all edges (use with .edges("|Z") etc. for selective) .chamfer(distance) -- chamfer edges .hole(diameter, depth=None) -- through or blind hole at center .cboreHole(diameter, cboreDiameter, cboreDepth) -- counterbore hole .cskHole(diameter, cskDiameter, cskAngle) -- countersink hole .shell(thickness) -- hollow out (negative = inward) Face/Edge Selection (critical for targeted operations): .faces(">Z") -- topmost face in Z .faces("<Z") -- bottommost face in Z .edges("|Z") -- edges parallel to Z .edges(">Z") -- topmost edges in Z .edges("%Circle") -- circular edges .faces("+Z") -- faces with normal pointing in +Z direction Boolean Operations: .cut(other_shape) -- subtract .union(other_shape) -- add .intersect(other_shape) -- intersection Patterns & Arrays: .pushPoints([(x1,y1), (x2,y2), ...]) -- place features at points .rarray(xSpacing, ySpacing, xCount, yCount) -- rectangular array .polarArray(radius, startAngle, angle, count) -- circular array Advanced: .sweep(path) -- sweep a profile along a path .loft() -- loft between profiles .twistExtrude(height, angleDegrees) -- helical extrusion .text("text", fontsize, distance) -- embossed/engraved text .mirror("XY") -- mirror about a plane .translate((x, y, z)) -- move .rotate((0,0,0), (0,0,1), angleDeg) -- rotate Multi-body / Assembly Pattern: part_a = cq.Workplane( "XY" ).box( 10 , 10 , 10 ) part_b = cq.Workplane( "XY" ).transformed(offset=( 20 , 0 , 0 )).cylinder( 10 , 5 ) result = part_a.union(part_b) Code Quality Rules All parameters at the top -- no magic numbers in the modeling section Descriptive variable names -- flange_diameter , not d1 Step-by-step comments -- explain what each operation does in context Build incrementally -- complex models should be built in logical stages Selective fillet/chamfer -- use face/edge selectors, not blanket .fillet() which often fails Error-safe ordering : fillet/chamfer operations MUST come AFTER all boolean cuts/unions. Fillets on edges that get modified by later booleans will crash Manifold geometry -- ensure the result is a valid solid (no self-intersections) Reasonable tolerances -- if parts need to fit together, add 0.1-0.2mm clearance Common Pitfalls to AVOID .fillet() with radius >= smallest edge length -> crash. Always use conservative radii. .shell() on complex geometry with thin walls -> often fails. Keep wall thickness reasonable. Chaining too many operations without .clean() -> geometry corruption. Add .clean() after complex booleans. Forgetting that .box() and .cylinder() are centered by default. Using .faces(">Z").fillet() when there are multiple faces at the same Z height -> ambiguous selection. Applying .fillet() before .cut() -- fillet edges may be destroyed by the cut. Phase 3: Execution Determine the working directory : Use the user's current working directory (or a temporary directory) to write the script. Write the script to {working_dir}/{model_name}.py . Execute using the interpreter found in Phase 0: {CADQUERY_PYTHON} {working_dir}/{model_name}.py Where {CADQUERY_PYTHON} is the cached interpreter command from environment detection. Set timeout to 60 seconds (complex models may take time) Phase 4: Auto-Debug (up to 5 attempts) If execution fails, follow this diagnostic protocol: | Error Type | Diagnosis | Fix Strategy |