Parametric 3D Printing with CadQuery

Real-World Dimension Research

When designing objects that interface with real products (phones, chargers, PCBs, connectors, etc.), use web search to find accurate dimensions before writing any geometry code. Don't guess or use approximate values — even 1-2mm off can make a part unusable.

What to research:

• Connector/port dimensions (USB-C: 8.4 x 2.6mm opening, Lightning, barrel jacks)
• Device dimensions (phone width/thickness, PCB footprints, charger puck diameters)
• Mounting hole patterns and screw sizes (M2.5, M3, etc.)
• Standard component specs (MagSafe puck: 56mm diameter, 5.6mm thick)
• Cable bend radii and strain relief requirements

How to use it:

1. Search for "[product] dimensions mm" or "[component] datasheet"
2. Cross-reference at least 2 sources when precision matters
3. Add the sourced dimensions as comments in the PARAMETERS section:

   # MagSafe puck dimensions (source: Apple spec + iFixit teardown)
   puck_diameter = 56.0    # mm
   puck_thickness = 5.6    # mm
   

4. When in doubt, add 0.3-0.5mm clearance to external dimensions

This is especially important for: phone cases/stands, charger mounts, PCB enclosures, cable management, adapter fittings, and anything that clips onto or wraps around an existing product.

Core Workflow

1. Gather requirements (see Requirements Gathering below)
2. Research dimensions of any real-world products involved (see above)
3. Phase 1 — Base shape: Build outer shell, preview, get user feedback
4. Phase 2 — Features: Add functional details, preview, get user feedback
5. Phase 3 — Final delivery: Fillets, cleanup, final preview + STL + print recommendations
6. Offer parameter tweaks after delivery

This is a collaborative, show-as-you-go process. Do NOT disappear and come back with a finished model. Show the user your progress at each phase and incorporate their feedback before moving on.

Requirements Gathering

Before writing any code, walk through these topics with the user conversationally. Don't dump all questions at once — ask the most important ones first, then follow up based on answers. Use reasonable defaults when the user doesn't specify.

What is it? Object type, purpose, what it holds/protects/attaches to. Get a clear mental model of the object before anything else.

Critical dimensions Must-fit measurements — PCB size, phone width, screw spacing, diameter of the thing it wraps around, etc. These are non-negotiable and drive everything else.

Mounting & attachment How does it connect to things? Screws (what size?), snap-fit, adhesive tape, magnets, freestanding on a desk? This affects wall thickness, boss placement, and overall structure.

Printer & material What printer do they have? (Bambu, Prusa, Ender, etc.) Nozzle size? Material — PLA, PETG, TPU? This directly affects tolerances, minimum feature sizes, and design constraints. Defaults: 0.4mm nozzle, PLA, 0.2mm layer height.

Functional needs Ventilation/airflow, water resistance, cable routing, access panels, visibility windows, stacking, weight limits. Ask only what's relevant to the object.

Aesthetic preferences Rounded vs sharp edges, minimal vs industrial look, color considerations (affects visibility of layer lines). Ask briefly — most users care more about function than form.

Start with the first two (what + dimensions), then ask about mounting and material if relevant. Only ask about aesthetics if the user seems to care or if it affects structural choices.

Progressive Preview Workflow

Build the model in phases. At each phase, export an STL, render a preview, self-review it, then show it to the user and ask for feedback before proceeding. This catches problems early and keeps the user involved.

Preview recipe (use at every phase)

python3 preview.py model.stl preview.png --views multi

Then view the preview image, self-review it against the checklist in design-review.md, and fix any issues you spot before showing it to the user.

Phase 1 — Base Shape

Build the basic outer form: overall dimensions, shell/walls, bottom plate. No cutouts, no fillets, no details yet.

1. Write the script with parameters and basic geometry
2. Export STL and render preview
3. Self-review: Does the shape and size look right? Is the bottom flat for printing?
4. Show the preview to the user: "Here's the basic shape — does this look right before I add details?" Include key dimensions.
5. Wait for feedback. If the user wants changes, iterate here before moving on.

Phase 2 — Features

Add functional details: holes, cutouts, mounting bosses, cable slots, ventilation, snap-fits, internal structures.

1. Add features to the script
2. Export STL and render preview
3. Self-review: Are all features visible? Do booleans look clean? Are holes in the right positions?
4. Show the preview to the user: "I've added [list features]. Anything to change before I finalize?"
5. Wait for feedback. Iterate if needed.

Phase 3 — Final Delivery

Apply finishing touches: fillets, chamfers, edge cleanup. Do a full printability review.

1. Add fillets/chamfers (largest radius first, apply after shell)
2. Export final STL and render preview
3. Full self-review using the complete checklist from design-review.md — visual inspection, dimensional verification, printability analysis
4. Fix any issues found, re-export if needed
5. Deliver to the user: final STL + preview image + print recommendations (orientation, supports, infill, material notes)

Important: Do NOT skip phases or combine them unless the model is very simple (e.g., a flat bracket with two holes). For anything with enclosed geometry, multiple features, or tight tolerances, follow all three phases.

Read design-review.md for the full visual inspection checklist, dimensional verification code, and printability analysis helpers.

Script Template

ALWAYS structure scripts like this:

import cadquery as cq

# ============================================================
# PARAMETERS - Edit these to customize the model
# ============================================================
# Overall dimensions
width = 60.0        # mm - outer width
depth = 40.0        # mm - outer depth  
height = 25.0       # mm - outer height

# Wall and structural
wall = 2.0          # mm - wall thickness (min 1.2 for FDM)
corner_r = 2.0      # mm - corner fillet radius

# Tolerances
fit_clearance = 0.3 # mm - clearance for press-fit (adjust per printer)

# ============================================================
# MODEL
# ============================================================
result = (
    cq.Workplane("XY")
    .box(width, depth, height, centered=(True, True, False))
    # ... build geometry using parameters above (bottom at Z=0)
)

# ============================================================
# EXPORT
# ============================================================
cq.exporters.export(result, "output.stl")
print(f"Exported: {width}x{depth}x{height}mm")

Key Rules

Parameters First

• ALL dimensions go in the PARAMETERS section at the top
• Use descriptive names: screw_hole_d, not d1
• Add units in comments (always mm)
• Group related parameters with blank lines and section comments

Print-Friendly Defaults

Key FDM design defaults:

Material-specific adjustments: TPU needs larger clearances (~0.5mm) due to flex. PETG is stickier, so add +0.1mm to fit clearances. ABS shrinks ~0.5-0.7%, so scale critical dimensions up slightly. When in doubt, print a small test piece first.

Orientation Awareness

• Design with print orientation in mind
• Flat bottom surfaces print best
• Avoid supports when possible by designing around overhangs
• Add chamfers to bottom edges instead of fillets (fillets need supports)
• Comment the intended print orientation in the script

CadQuery Patterns

Common patterns to know:

Hollow enclosure:

result = (
    cq.Workplane("XY")
    .box(width, depth, height, centered=(True, True, False))
    .edges("|Z").fillet(corner_r)
    .shell(-wall)  # negative = shell inward
)

Screw boss:

.pushPoints([(x, y)])
.circle(boss_od / 2).extrude(boss_h)
.pushPoints([(x, y)])
.hole(screw_d + fit_clearance)

Snap-fit clip:

# Cantilever beam with overhang hook
.workplane(offset=wall)
.moveTo(x, y).rect(clip_w, clip_l).extrude(clip_h)
# Add hook at tip with a small overhang (< 45 deg)

Ventilation grid:

.pushPoints(vent_positions)
.slot2D(slot_l, slot_w).cutThruAll()

Other patterns: mounting brackets, cable routing channels, text/labels (.text()), multi-part assemblies with alignment pins.

Common Pitfalls

• Zero-thickness geometry: Ensure boolean operations don't create infinitely thin walls
• Fillet failures: Apply fillets from largest to smallest radius. If a fillet fails, reduce its radius.
• Fillet/shell/cut ordering: The correct sequence is .shell() first (hollow out), then .fillet() (round edges), then boolean cuts (holes, slots, pockets). Shelling a filleted body often fails, and filleting edges left by cuts is fragile.
• Coordinate system: CadQuery centers geometry at origin by default. Use centered=(True, True, False) on .box() to place bottom at Z=0.
• Hole direction: .hole() cuts through the entire part by default. Use .cboreHole() or .cskHole() for counterbore/countersink.
• Export errors: If export fails, the geometry may be invalid. Check for self-intersecting shapes.
• Taper direction: In .extrude(taper=angle), a positive taper angle narrows the shape (draft inward), negative flares it outward. This is opposite to what many people expect.
• Shell on tapered/complex geometry: .shell() frequently fails on tapered bodies, lofted shapes, or geometry with many fillets. The reliable alternative is boolean subtraction — create the outer solid, create a slightly smaller inner solid, then use outer.cut(inner) to hollow it out. This gives you full control over wall thickness at every point.
• Loft is fragile: CadQuery's .loft() fails on many cross-section combinations. Prefer .extrude(taper=angle) when transitioning between a shape and a scaled version of itself. Only use .loft() when you need to transition between genuinely different profiles (e.g., circle to rectangle).

Export

# STL (for slicing)
cq.exporters.export(result, "model.stl")

# STEP (for further CAD editing)
cq.exporters.export(result, "model.step")

# Both formats
for fmt in ["stl", "step"]:
    cq.exporters.export(result, f"model.{fmt}")

Always export STL for printing. Optionally export STEP if the user might want to edit in Fusion 360 or similar.

Multi-Part Models

For models with multiple parts (e.g., enclosure + lid):

# Export each part separately
cq.exporters.export(body, "enclosure_body.stl")
cq.exporters.export(lid, "enclosure_lid.stl")

Name files descriptively so the user knows which part is which.

Parameter Adjustment Offer

After delivering the final model, always present the key parameters as a summary table and offer to tweak them. This lets the user fine-tune without re-explaining the whole design.

Example:

Here's your final model! Current parameters:

| Parameter       | Value  |
|----------------|--------|
| Width          | 90 mm  |
| Depth          | 65 mm  |
| Height         | 30 mm  |
| Wall thickness | 4 mm   |
| Cable slot     | 18 mm  |
| Corner radius  | 3 mm   |
| Fit clearance  | 0.3 mm |

Want me to adjust anything? Just say e.g. "make it 5mm taller" or "wider cable slot."

Only include parameters the user would plausibly want to change — skip internal constants like eps or nozzle_d. Group them logically (dimensions first, then structural, then tolerances).

Output Checklist

Before delivering a model, verify:

• All dimensions are parameterized (no magic numbers in geometry code)
• Wall thickness >= 1.2mm
• Designed for printability (minimal overhangs/supports)
• Print orientation noted in comments
• STL exported and file size is reasonable (not 0 bytes)
• Clear parameter names with units
• Script runs without errors
• Multi-view preview generated and visually inspected
• Preview shows correct shape, features, and proportions
• Bounding box dimensions match requirements
• Both STL and preview PNG delivered to user