SCAD Architecture
This document explains how the primary model is structured and how data flows from Customizer values to final geometry.
File Structure
Section titled “File Structure”The primary SCAD is organized in this order:
- Header and licensing block
- Customizer parameter sections
- Hidden constants and validation assertions
- Derived dimensions and helper functions
- Feature modules:
- Stabilizers
- Bottom openings
- Slicing clips
- Box/Lid assembly
- Render dispatcher (
full_render()) - (BOSL2 is an external include, not part of the file; see below)
Coordinate System and Axes
Section titled “Coordinate System and Axes”- X: left/right across box width
- Y: front/back across box depth
- Z: vertical
Side-opening directional conventions are intentionally wall-relative, not globally symmetric:
- Front
Move_Opening_Front_to_Right: positive toward+X - Back
Move_Opening_Back_to_Right: positive toward-X - Right
Move_Opening_Right_to_Right: positive toward+Y - Left
Move_Opening_Left_to_Right: positive toward-Y
Parameter Layers
Section titled “Parameter Layers”1) Global sizing
Section titled “1) Global sizing”Controls overall shell dimensions and base topology:
Box_Width,Box_Depth,Box_HeightWall_Thickness,Box_Corner_Radius
2) Feature toggles
Section titled “2) Feature toggles”Enable/disable major geometry branches:
Enable_PostEnable_StabilizersEnable_Bottom_OpeningsEnable_Slicing
3) Placement and offsets
Section titled “3) Placement and offsets”Refine location and distribution:
- Side-opening global/per-side offsets
- Stabilizer alignments and margins
- Bottom opening axis/alignment/margins
4) Slice join mechanics
Section titled “4) Slice join mechanics”Define seam mechanics for split builds:
Slice_CountClip_*parametersSlice_Piece_To_Render
Derived Values
Section titled “Derived Values”Key computed values used across modules:
Slice_Width = Box_Width / Slice_CountInner_Width = Box_Width - Wall_Thickness * 2Inner_Depth = Box_Depth - Wall_Thickness * 2
These drive placement math for stabilizers, bottom openings, and slice clipping extents.
Geometry Composition Pattern
Section titled “Geometry Composition Pattern”Core pattern is constructive solid geometry (CSG):
union()for additive solidsdifference()for cavities, openings, and clip socketshull()for rounded slot-like opening shapes
The model generally builds robust base solids first, then subtractive features.
Render Modes
Section titled “Render Modes”Non-sliced
Section titled “Non-sliced”- box path:
m_box_with_openings() - lid path:
m_lid(), whose slab and lip come fromm_lid_body()in theLid_Stylechosen - selected by
Part_To_Render
Sliced preview (Slice_Piece_To_Render = 0)
Section titled “Sliced preview (Slice_Piece_To_Render = 0)”- Iterates
i = 1..Slice_Count - Places each slice with preview spacing
- Renders box and/or lid depending on
Part_To_Render
Sliced single part (Slice_Piece_To_Render > 0)
Section titled “Sliced single part (Slice_Piece_To_Render > 0)”- Renders only selected index
- Useful for export and printing
Validation Philosophy
Section titled “Validation Philosophy”Assertions block combinations that produce broken geometry or ambiguous output.
The bar for adding one is that the bad input would otherwise render successfully
and exit 0, since that is the failure mode a user cannot detect without
inspecting the mesh.
Current assertions enforce:
- positive box, wall, and opening dimensions
- wall thickness that leaves a real interior
- post diameter that both has a wall and fits inside the box
- stabilizer height, depth, width, and counts that fit the box
- side opening height within box height
- bottom opening count and dimensions when the feature is enabled
- non-negative per-side override values and corner radius sentinels
- valid slice index range and minimum slicing and clip constraints
- positive clip geometry dimensions
Two constraints are clamped instead of asserted, because the correct
interpretation is unambiguous: an over-large Box_Corner_Radius is reduced to
what the inner cavity allows, and a seam clip landing inside the post opening is
moved clear of it. Both report via echo rather than failing.
See Validation rules for each rule with its trigger and resolution.
BOSL2 Dependency
Section titled “BOSL2 Dependency”The model includes BOSL2 as an external library (include <BOSL2/std.scad>
and include <BOSL2/joiners.scad>); it no longer carries embedded copies of
BOSL2 code. The pinned version lives in BOSL2_REF in
.github/workflows/scad-smoke.yml, and scripts/bump-bosl2.sh is the only
thing that should change it.
Implications:
- Everything in
cable-box-parametric.scadis this project’s own code. - A missing BOSL2 install stops the render with a message naming the library;
tests/fixtures/missing_bosl2.scadexercises that guard. - For users who cannot install a library,
scripts/build_bundle.pyproduces a two-file standalone bundle with BOSL2 inlined, and releases attach it. - Attribution is tracked in
THIRD_PARTY_NOTICES.md.
Maintenance Workflow Recommendation
Section titled “Maintenance Workflow Recommendation”For safe iteration:
- Change one feature branch at a time.
- Verify unsliced rendering first.
- Verify sliced rendering with both preview and single-slice modes.
- Run smoke scripts.
- Update docs and assertions together when behavior changes.