Skip to content

Module Reference

This page describes each custom module in cable-box-parametric.scad, what it builds, and where it is used.

  • Entry point: full_render()
  • Main branches:
    • Slicing disabled: render m_box_with_openings() and/or m_lid()
    • Slicing enabled: render m_box_slice(i) and/or m_lid_slice(i)

Builds base box solids and subtractive cavities before side openings are cut.

Includes:

  • Outer shell and inner hollow shell
  • Optional center post outer/inner solids
  • Optional stabilizers
  • Optional bottom openings subtract
  • Optional Gridfinity feet, with their magnet pockets and screw holes subtracted

Used by:

  • m_box_with_openings()

Wraps m_box_base() and subtracts side openings for enabled walls.

Behavior:

  • Applies global offsets and per-side offsets
  • Uses per-side width/height overrides when override values are greater than 0

Used by:

  • non-sliced render path
  • m_box_slice()

Builds the lid: the body from m_lid_body(), plus the optional center-post collar and socket, magnet pockets, Gridfinity lid top, and finger relief.

Behavior:

  • Handles the post socket if Enable_Post=true. The socket bore is Post_Diameter + 2*Lid_Lip_Gap, so the post has the same clearance as the lip.

Used by:

  • non-sliced render path
  • m_lid_slice()

Builds the lid’s slab and its lip, in the style Lid_Style selects. Both styles share the footprint Lid_Outer_Width x Lid_Outer_Depth and the total height Lid_Height + Lid_Lip_Gap_Height.

  • Skirt: one shell with a pocket cut into its top Lid_Lip_Gap_Height. The pocket is the box’s outline plus Lid_Lip_Gap per side, so the skirt wraps the outside of the wall.
  • Plug: a slab with a ring on top. The ring’s outside is the box interior minus Lid_Lip_Gap per side, it is Wall_Thickness thick, and it is notched around the magnet bosses when Enable_Lid_Magnets=true.

Before 2.0.0-rc.5 the lip was a ring that overlapped the outer half of the box wall, so the lid stood on the rim. The assembly_* scenarios seat the lid on the box through tests/assembly/lid_seated.scad and fail on any overlap.

m_opening(side, width, height, corner_radius)

Section titled “m_opening(side, width, height, corner_radius)”

Generates a side opening profile and extrudes through wall thickness.

Behavior:

  • Orientation depends on side
  • corner_radius < 0 uses fully rounded slot ends
  • corner_radius = 0 produces a square-corner opening
  • corner_radius > 0 produces a rounded rectangle (clamped to valid half-extents)
  • Works with vertical, horizontal, and square dimensions
  • With All_Opening_Top_Style="Teardrop", the two top corner circles of the hull become BOSL2 teardrop() shapes capped at the circle’s top (cap_h = r), so the top prints without support and the opening keeps its height. teardrop() extrudes along Y with its point at +Z, so the side walls spin it onto X. Square openings are unchanged

Creates one triangular-wedge fin as a polyhedron.

Places stabilizers on front/back walls.

Key logic:

  • Alignment modes: Centered, Distributed, Custom
  • Centered/Custom pitch is controlled by Stabilizer_FB_Spacing
  • Optional opening avoid zones per wall
  • Avoid fallback: if all candidate positions are suppressed and distributed positions exist, it falls back to distributed

Places stabilizers on left/right walls with matching alignment/avoid behavior.

Key logic:

  • Alignment modes: Centered, Distributed, Custom
  • Centered/Custom pitch is controlled by Stabilizer_LR_Spacing
  • Optional opening avoid zones per wall
  • Avoid fallback: if all candidate positions are suppressed and distributed positions exist, it falls back to distributed

Wrapper that dispatches both stabilizer placement modules when enabled.

m_bottom_opening_shape(width, length, corner_radius)

Section titled “m_bottom_opening_shape(width, length, corner_radius)”

Builds one bottom opening footprint with optional rounded corners.

Primary dispatcher for bottom openings.

Chooses:

  • arrangement axis handling (Along X, Along Y)
  • secondary-axis alignment
  • post-avoid path vs normal path

When post-avoid is enabled, primary and secondary alignment settings still apply while openings are kept outside the post-clearance zone.

m_place_openings_along_x(opening_size, y_pos, available_x)

Section titled “m_place_openings_along_x(opening_size, y_pos, available_x)”

Places arrayed bottom openings along X with primary alignment logic.

m_place_openings_along_y(opening_size, x_pos, available_y)

Section titled “m_place_openings_along_y(opening_size, x_pos, available_y)”

Places arrayed bottom openings along Y with primary alignment logic.

m_place_openings_avoid_post_x(opening_size, y_pos)

Section titled “m_place_openings_avoid_post_x(opening_size, y_pos)”

Splits opening placement around center post clearance when arranged along X.

m_place_openings_avoid_post_y(opening_size, x_pos)

Section titled “m_place_openings_avoid_post_y(opening_size, x_pos)”

Splits opening placement around center post clearance when arranged along Y.

Creates one male clip tab for box slice seams. m_place_floor_clips stands it on z=0, so it spans z 0 to Clip_Tab_Height and the piece sits flat on its floor. Before 2.0.0-rc.5 it was centred on the floor and hung 0.575 mm below it.

Creates one female clip pocket using Clip_Tolerance and SPACER clearances.

Places floor seam clips across depth based on Clips_Per_Edge.

m_edge_treated_shell(size, fillet, chamfer, bottom_style = "Fillet")

Section titled “m_edge_treated_shell(size, fillet, chamfer, bottom_style = "Fillet")”

The outer shell of the box or the lid slab. With both treatments at 0 it is the cuboid() it has always been, which is how an untreated model is guaranteed unchanged rather than merely expected to be. With a treatment it becomes a BOSL2 offset_sweep() over the same rounded rectangle, which resolves how a horizontal fillet meets the vertical corner radius. offset_sweep expresses “no profile” by omitting the argument, so the cases are enumerated rather than passed a flat value.

bottom_style picks the bottom profile through bottom_edge_profile(). Only the box passes Bottom_Edge_Style. The lid keeps the default, so that setting never reaches the lid.

A function that returns the offset_sweep() bottom profile for a Bottom_Edge_Style: os_circle(r) for Fillet, os_teardrop(r) for Teardrop, and os_chamfer(width = r) for Chamfer. The teardrop is a one-eighth arc that ends in a 45 degree chamfer, inset 0.59 * r at the bed instead of r. Every profile is at most r deep and r tall.

m_gridfinity_bottom_solid() and m_box_outline_prism(h)

Section titled “m_gridfinity_bottom_solid() and m_box_outline_prism(h)”

The Gridfinity feet under the box. One foot is swept once, at load time, into GF_FOOT_VNF with BOSL2 offset_sweep(). m_gridfinity_bottom_solid() copies it to every cell and emits all the copies as one polyhedron, because CGAL on OpenSCAD 2021.01 unions separate children one at a time. It then clips the feet to the box’s outline with m_box_outline_prism(). That prism is built the same way m_edge_treated_shell() builds the walls, so the corner arcs of the two share vertices exactly. A clip whose arcs only nearly matched the wall’s would leave slivers that CGAL cannot read back.

Magnet pockets cut up from each foot’s bottom face, two stepped bridging layers above each pocket, and the screw hole from there to the box’s underside. The first bridging layer is a slot across the pocket and the second a square, so each layer’s material spans a supported edge. Each layer is Print_Layer_Height tall, so it matches one sliced layer.

m_gridfinity_lid_top_solid() and m_gridfinity_lid_top_cavities()

Section titled “m_gridfinity_lid_top_solid() and m_gridfinity_lid_top_cavities()”

The Gridfinity baseplate on the lid’s exposed face: a slab spanning the whole lid, with one spec pocket cut into each cell. One pocket is swept once, at load time, into GF_POCKET_VNF with BOSL2 offset_sweep(), from the pocket’s own numbers rather than the foot’s; the standard puts the fit clearance in the gap between a 41.5 mm foot and a 42 mm pocket.

The pockets are separate children rather than one joined polyhedron, which is the opposite of what the feet do. The feet stand 0.5 mm apart and never meet, so joining them costs CGAL nothing. Pocket mouths sit exactly a pitch apart and are exactly a pitch wide, so they would have to overlap, and overlapping shells inside one polyhedron are a self-intersection rather than a saving.

Each mouth is trimmed SPACER on every side for the same reason. Built to a full 42 mm, two mouths meet in a line of zero width lying in the plate’s own face: CGAL renders that and reports Simple: yes, and the exported mesh then makes CGAL assert on re-import, so every point probe against it is meaningless. Letting them overlap instead is worse, because the rounded outlines then cross at a shallow angle at each corner and leave slivers.

At the default clearance the pocket is exactly as deep as the plate is thick, so each floor lands on the lid panel’s own face. A render dissolves that coincident pair into one surface, but a preview’s depth buffer cannot order two coplanar faces and speckles the floors. PREVIEW_OVERCUT lifts the whole cutter 0.01 mm clear of that plane, gated on $preview, which OpenSCAD sets false for every render. WELD is the usual cure for a coincident pair and is far too deep here: 0.2 mm off a pocket floor is a real change to the printed part.

Finger relief on the lid’s outer face, one shape per enabled wall, at the wall centre. is_cut = true yields the scallop, a cylinder whose axis lies on the face so the groove is a half cylinder and Lid_Relief_Depth is both its depth and its half width. is_cut = false yields the tab, a rounded block centred on the face so it overlaps rather than merely touching, for the same reason the seam clips overlap their slice.

Places children at the four inside corners, each pushed WELD into the two walls it sits against. The positions are symmetric in both axes, which is what makes box and lid pockets align however the lid is flipped.

m_box_magnet_bosses(), m_box_magnet_pockets(), m_lid_magnet_pockets()

Section titled “m_box_magnet_bosses(), m_box_magnet_pockets(), m_lid_magnet_pockets()”

The magnet features. Bosses run the full box height rather than stopping under the rim, so they print from the bed up instead of overhanging, and stiffen the corner. The box pocket opens at the rim; the lid pocket opens on the face that meets it and reaches down into the slab, leaving the lid’s exposed face solid.

Places lid seam clips with lid-specific Z and depth extents.

The clip sits SPACER (0.04 mm) below the top of the lid panel rather than flush with it. Flush, the clip’s top face and the panel’s top face are one coplanar face, and on the slice seam the clip’s corners become extra collinear vertices along a straight edge; OpenSCAD then tessellates zero-area triangles there, which slicers tolerate but CGAL rejects on re-import. Male and female clips share the offset, so the fit is unaffected.

Cuts the box into one slice and applies seam clip logic. With Seam_Tooth_Depth > 0 each seam is cut by m_seam_cutter using box_seam_bands; at 0 it takes the original flat cube cutters unchanged.

Cuts the lid into one slice and applies seam clip logic, using lid_seam_bands for its seam teeth.

m_seam_cutter(x_seam, keep_left, bands, z_lo, z_hi, reach)

Section titled “m_seam_cutter(x_seam, keep_left, bands, z_lo, z_hi, reach)”

Removes everything on one side of a seam: the right side when keep_left is true, the left side otherwise. Its edge is a profile in the XZ plane, extruded along Y. Inside each [s, e] band of z the edge is a 45 degree sawtooth, closed off by 45 degree lines at both ends; outside the bands it is a straight vertical cut. The two pieces’ edges sit Clip_Tolerance apart inside the bands.

The sawtooth has no undercut, so the pieces still engage by pushing together along X, as the floor clips do. A jigsaw or dovetail cut would only slide together along Y, which the floor clips cannot.

box_seam_bands(x_seam) and lid_seam_bands(x_seam)

Section titled “box_seam_bands(x_seam) and lid_seam_bands(x_seam)”

Return the z bands that carry teeth at a seam.

  • Box: the walls from the floor’s top face to the rim, less the height range of any front or back opening that crosses the seam’s tooth strip.
  • Lid: the slab below the band the lid’s seam clips occupy, or no bands when a front or back lid relief sits on the seam.

Bands shorter than one tooth depth are dropped.

m_box() and m_lid_part() expose the box and lid as BOSL2 attachables, so accessories can be placed against a named feature rather than a coordinate expression.

Render_On_Include = false; // or pass -D Render_On_Include=false
include <cable-box-parametric.scad>
m_box()
attach("wall-back")
my_bracket();

Defaults to anchor=BOTTOM, which reproduces the standard placement with the box sitting on z=0. The declared envelope includes any Gridfinity base.

Anchor Where it is
standard TOP, BOTTOM, LEFT, RIGHT, FRONT, BACK the outer bounding volume
"floor" interior floor surface, pointing up
"rim" top of the wall, pointing up
"wall-front", "wall-back", "wall-left", "wall-right" inner face of that wall at floor level, pointing into the interior
"post-top" top of the centre post, pointing up
Anchor Where it is
"lid-face" the face that ends up exposed when the box is closed, pointing away from the lid
"lip" the free edge of the engagement lip, a skirt or a plug, which meets the box

"lid-face" is worth understanding. The lid prints face-down: its engagement lip points up, into the box, so the exposed face is the model’s z=0 face and anything mounted on it grows downward. Getting this backwards is a real bug this project has already shipped once, in the v1.2.0 Gridfinity lid interface. The anchor exists so nobody has to re-derive it.

With Enable_Gridfinity_Lid_Top, m_lid_placed() turns the whole lid over for export so the pockets print facing up, and both anchors follow it: "lid-face" is then the top of the part and "lip" the bottom. They name features, not coordinates.

This is the only top-level renderer called at file end.

Behavior summary:

  • If Enable_Slicing=false:
    • render unsliced box/lid by Part_To_Render
  • If Enable_Slicing=true and Slice_Piece_To_Render=0:
    • preview all slices spaced by Slice_Preview_Spacing
  • If Enable_Slicing=true and Slice_Piece_To_Render>0:
    • render only selected slice index

When editing geometry, validate in this order:

  1. m_box_base() and m_lid() produce valid unsliced solids
  2. Side openings subtract correctly in m_box_with_openings()
  3. Sliced paths still produce manifold outputs (m_box_slice, m_lid_slice)
  4. Assertions still guard invalid states
  5. Run smoke scripts after every behavior change