openscad-mechanical

# OpenSCAD Mechanical Part Authoring ## When to Use Load this skill when asked to: - Create or update a `.scad` file for any printable mechanical part (housing, frame, bracket, spacer, backplate, faceplate …) - Add parametric models for PCB mounting, connector cutouts, or panel assemblies - Adapt tolerances or clearances for a new printer/material - Explain or review OpenSCAD geometry logic ## Language Reference Full language reference: [language-reference.md](./references/language-reference.md) Quick syntax recap: - Variables are **single-assignment** within a scope; use `let()` for local rebinding. - Modules define reusable 3-D geometry; functions return values (no geometry). - Boolean: `union()`, `difference()`, `intersection()`. - 3-D primitives: `cube([x,y,z])`, `sphere(r)`, `cylinder(h,d)`, `polyhedron()`. - 2-D primitives + extrusion: `square()`, `circle()`, `polygon()` → `linear_extrude()` / `rotate_extrude()`. - Transforms: `translate()`, `rotate()`, `mirror()`, `scale()`, `resize()`. - Rounding via 2-D `offset(r)` inside `linear_extrude()`, or `minkowski()`. - Special variables: `$fn` (facets), `$fs` (min-segment size), `$fa` (min-angle). - Flow: `for()`, `if/else`, conditional `? :`. - Includes: `use <file.scad>` (modules/functions only), `include <file.scad>` (full execution). ## Project Conventions (this repository) Derived from the existing `doc/boards/hub75/housing/hub75.scad`: ### File Header ```scad // <Short description of what this part is> // // Dimensions: <link or "measured" or "N/A"> // Units: mm // Print orientation: // - <part-name>: <orientation advice> // // Author: <Name> (<email>) // License: MIT License (https://opensource.org/licenses/MIT) ``` ### Parameter Block Order 1. **Global constants** — `eps`, `fit_tolerance`, `rounded_fn` 2. **Component parameters** — one group per physical object, prefixed (`frame_`, `panel_`, `board_`, …) 3. **Derived dimensions** — calculated from the above, never hard-coded 4. **Preview/export selector** — `part = "assembly";` ```scad // Global constants eps = 0.01; // Boolean overlap in mm fit_tolerance = 0.2; // Assembly clearance in mm rounded_fn = 96; // Facet count for outer curves // Part selector (assembly | frame | faceplate | …) part = "assembly"; ``` ### Naming Conventions | Item | Convention | Example | |------|-----------|---------| | Parameters | `snake_case` prefixed by component | `frame_wall_thickness` | | Modules | `snake_case` verbs or nouns | `rounded_cube_xz()`, `board_mount_pattern()` | | Pure functions | `snake_case` | `centered_offset(outer, inner)` | | Booleans | descriptive flag | `show_panel = false;` | ### Inline Comment Rule Every parameter must have a `// Description in mm` (or relevant unit) comment on the same line: ```scad frame_wall_thickness = 3; // Thickness of the frame walls in mm ``` ### Boolean Operation Patterns Always add `eps` overlap to avoid z-fighting / non-manifold edges: ```scad eps = 0.01; difference() { cube([width, depth, height]); // Cutout starts eps below the surface, extends eps beyond the far side translate([x, y, -eps]) cylinder(d=hole_d, h=height + 2*eps, $fn=48); } ``` ### Hole Sizing Guidelines | Purpose | Diameter formula | |---------|-----------------| | Clearance (bolt passes through) | `bolt_nominal + 0.4` | | Tapped / press-fit | `bolt_nominal - 0.2` (tune per material) | | General assembly fit | `nominal + fit_tolerance` | ### Rounded Corners Prefer the 2-D `offset(r)` + `linear_extrude()` pattern (avoids Minkowski overhead): ```scad module rounded_profile_xz(width, height, radius) { $fn = rounded_fn; if (radius > 0) translate([radius, radius]) offset(r=radius) square([width - 2*radius, height - 2*radius]); else square([width, height]); } module rounded_cube_xz(size_xyz, radius) { translate([0, size_xyz[1], 0]) rotate([90, 0, 0]) linear_extrude(height=size_xyz[1]) rounded_profile_xz(size_xyz[0], size_xyz[2], radius); } ``` ### Part Selector Pattern Use a top-level `if` chain on a `part` string so each piece can be exported independently or shown in assembly: ```scad if (part == "assembly") { assembly(); } else if (part == "frame") { frame(); } else if (part == "faceplate"){ faceplate(); } ``` ## Procedure ### 1. Gather Requirements Collect these before writing any geometry: - Overall envelope (width × height × depth in mm) - List of sub-parts to model (frame, lid, spacer, …) - External components that must fit inside (PCB, connectors, panels) - Mounting interfaces (screw holes, snap fits, press fits) - Print orientation constraints (overhang limits, layer strength direction) - Clearances and tolerances (default: `fit_tolerance = 0.2 mm`) ### 2. Read Existing File (if editing) Always read the full file before modifying. Identify: - Existing parameter names to reuse - Module and function signatures to extend, not replace - The `part` selector — add new values rather than removing old ones ### 3. Structure the File Use the template in [assets/template.scad](./assets/template.scad): 1. File header comment 2. Global constants block 3. Per-component parameter blocks (ordered by assembly depth: outermost first) 4. Derived dimensions 5. `part` selector variable 6. Pure functions 7. Reusable geometry modules (primitives → composites) 8. Top-level part modules 9. `if/else` part-selector dispatcher ### 4. Implement Geometry **Work outside-in** (define outer shell first, then subtract holes/cutouts): 1. Build the solid body as a `union()` or single primitive. 2. Subtract connector cutouts, mounting holes, and internal cavities via `difference()`. 3. Add small features last (chamfers, lips, standoffs). **Parametrize everything** — no magic numbers in geometry calls. Every numeric literal must trace back to a named variable. ### 5. Verify Check all of the following before finishing: - [ ] No hard-coded mm values in geometry calls (only in the parameter block) - [ ] Every parameter has a `// ... in mm` (or unit) inline comment - [ ] `eps` is applied to all `difference()` cutouts - [ ] Holes use the correct clearance formula (see table above) - [ ] `$fn` or `$fn=48` set on every `cylinder()` / `circle()` - [ ] Print orientation note added to file header - [ ] Part selector works: each `part` value renders without error - [ ] Assembly preview (`part = "assembly"`) shows correct relative positions ### 6. Export Notes - Render to STL per part: `File → Export → Export as STL` (or CLI: `openscad -o part.stl -D 'part="frame"' file.scad`) - For FFF printing: slice with part-specific orientation noted in the file header - Recommended `$fn` for final export: ≥ 96 for outer curves, 48 for holes