Refactor: Standardize refactor + add test suite

[CameronBrooks11]

Summary

Comprehensive cleanup and refactor of the OpenSCAD utility libraries and test suite.

• Standardized headers, formatting, and structure across all files.
• Clearer naming and inline docs without changing functionality.
• Inline demos/tests removed → dedicated tests/ suite.
• Expanded regression + visualization coverage.
• No functional regressions — math and algorithms unchanged.

Review Notes

• Large but mechanical changes (formatting, docs, test extraction).
• Test suite: visual (OpenSCAD preview) + numeric (echo).
• Focus review on confirming no regressions in math/geometry.
• Each test file maps 1:1 to a library file.

Documentation (README.md)

• Rewritten into a full module reference with per-file sections, functions, and dependencies.
• Expanded Tests section: regression, visual, edge-case, integration; run via .scad files.
• Added Examples: morphology (with images), mirror, convex hull, splines, SE(3), trajectories.
• Standardized terminology (function signatures, $fn, edge-case notes).
• Added Quick Start snippet.

Source Changes (Highlights)

All files reformatted consistently, with standardized headers and preserved behavior.

• hull.scad: clarified & fixed 2D/3D/collinear use, grouped helpers, removed inline tests.
• linalg.scad: grouped functions (constructors, identities, transforms, ops), simplified invert_rt. Moved general-purpose matrix utilities (matrix_power, det, matrix_invert) here from spline.scad for logical separation of concerns.
• lists.scad: clarified examples, added inline docs, left FIXME on subarray.
• mirror.scad: added optional col tint param, preserved BSD license.
• morphology.scad: grouped ops, clarified shell() behavior, renamed inverse() → _inverse().
• se3.scad: split into helpers/exp/log/Taylor, clarified inputs, removed inline tests.
• shapes.scad: clarified params and $fn dependence, preserved behavior.
• so3.scad: clarified Rodrigues, exp/log maps, Taylor expansions, removed inline tests.
• spline.scad: grouped spline/Bezier utilities, documented recursion, standardized temp vars. Matrix helpers removed to linalg
• trajectory_path.scad: clarified 6D twist → SE(3), documented loop/step logic.
• trajectory.scad: clarified trajectory = [tx,ty,tz,yaw,pitch,roll], documented translation/rotation inputs.
• transformations.scad: clarified Euler vs axis-angle, added inline usage examples.

Test Changes (NEW)

• hull_test: sphere/circle/collinear/3D/random; hull visualization + validation.
• linalg_test: vec/matrix constructors, identities, transforms, Hadamard.
• lists_test: flatten, range, reverse, subarray, set, remove.
• mirror_test: mirrored shapes vs OpenSCAD mirror(), optional color tint.
• morphology_test: 10 ops (inset/outset/rounding/fillet/shell), grid comparison.
• se3_test: round-trip exp/log check, PASS if error < 1e-8.
• shapes_test: square, circle, regular, rectangle; echo + visualization.
• so3_test: round-trip exp/log check, PASS if error < 1e-8.
• spline_test: closed/open splines, Bezier, Frenet frame, regression check.
• trajectory_path_test: multi-segment paths, quantization modes, loop closure.
• trajectory_test: regression values, combined twists, cube visualization.
• transformations_test: rotation, scaling, translation, TRS composition, project/to_3d.

[OskarLinde]

Thanks for the pull request and apologies for the delay in responding. This is great work.

One main question before merging – what testing beyond the added unit tests (which are great!) have you done on e2e usage? Want to minimize the risk for surprises and inadvertently breaking something.

[CameronBrooks11]

Thanks for the pull request and apologies for the delay in responding. This is great work.

One main question before merging – what testing beyond the added unit tests (which are great!) have you done on e2e usage? Want to minimize the risk for surprises and inadvertently breaking something.

Good point. I tested the current master versus this PR on the four projects linked below, which I’ve also listed in a short “Projects using scad-utils” section at the end of the README.
If you know of more projects that would be useful to test before merging, I’m happy to include them.

In openscad/list-comprehension-demos, the current master actually throws an error on spiral-2d due to using logic operators to check undef instead of is_undef(), which was triggering a warning on len() in transformations.scad.
I corrected that by switching to is_undef() in transformations.scad and also updated the same pattern in spline_args of spline.scad and retested everything after.

---

Projects using scad-utils

• openscad/list-comprehension-demos
• adrianschlatter/threadlib
• likeablob/parametric-stackable-box
• likeablob/misc-printable-accessories