OpenSCAD Library Check Skill

Overview

This skill verifies that OpenSCAD libraries (BOSL2, Round-Anything, etc.) are properly installed and provides guidance on common usage issues.

When to Use This Skill

User mentions OpenSCAD library issues
"Can't open library" errors in OpenSCAD
Before starting projects that require BOSL2 or Round-Anything
When debugging geometry generation errors

Library Locations

User's OpenSCAD libraries are located at: /Users/aaronmontgomery/Documents/OpenSCAD/libraries/

Current installed libraries:

BOSL2: v2.0.716 (91 files, installed March 2025)
Round-Anything: 25 files (installed May 2025)

Verification Process

Step 1: Check Library Installation

ls -la ~/Documents/OpenSCAD/libraries/

Expected output should show:

BOSL2/ directory
Round-Anything/ directory

Step 2: Create Test File

Generate a test file that imports both libraries and renders basic shapes:

include <BOSL2/std.scad>
include <Round-Anything/polyround.scad>

// Test BOSL2
echo("BOSL2 Version: ", BOSL_VERSION);
cuboid([20, 20, 20], rounding=2);

// Test Round-Anything
translate([30, 0, 0])
    polyRoundExtrude([[0,0,2], [10,0,2], [10,10,2], [0,10,2]], 5);

Step 3: Verify in OpenSCAD

Open test file in OpenSCAD
Check Console for version info
Verify both shapes render without errors

BOSL2 Usage Notes

Primitive Overrides ⚠️

BOSL2 replaces standard OpenSCAD primitives with "attachable" versions:

cube() → attachable cube with anchor/spin/orient parameters
cylinder() → attachable cylinder
sphere() → attachable sphere

Common Error:

ERROR: Assertion '!approx(spin_dir, [0, 0, 0])' failed:
"spin direction is parallel to anchor"

Cause: Using standard OpenSCAD syntax with BOSL2-overridden primitives.

Solutions:

Option 1 - Use BOSL2 Primitives:

include <BOSL2/std.scad>

// Instead of: cube([10, 10, 10]);
cuboid([10, 10, 10]);

// Instead of: cylinder(h=20, d=10);
cyl(h=20, d=10);

Option 2 - Don't Include BOSL2 for Simple Models: If you only need basic primitives, avoid including BOSL2:

// Use standard OpenSCAD only
cube([10, 10, 10]);
cylinder(h=20, d=10);

Option 3 - Use Standard Namespace:

include <BOSL2/std.scad>

// Explicitly use standard version
translate([0,0,0]) cube([10,10,10]);  // Standard cube

When to Use BOSL2

Use BOSL2 when you need:

Advanced attachments (attach(), position(), orient())
Complex shapes (rounded boxes, threads, gears)
Path operations (path_sweep, spiral paths)
Transformations (move(), up(), back())

Don't use BOSL2 if:

You're only using basic primitives
The model is very simple
You want standard OpenSCAD behavior

Spiral Generation Best Practices

Segment-Based Spirals

When creating spirals with discrete segments:

Critical Rules:

Segment width must exceed angular spacing:
```
segment_width ≥ (360 / steps) * radius * π/180 * overlap_factor
```
- For 200 steps, 35mm radius: minimum ~3mm width
- Recommend 1.5-2x minimum for reliable overlap

Use hull() for continuity:

for (i = [0 : steps-1]) {
    hull() {
        rotate([0, 0, i * angle_step]) segment();
        rotate([0, 0, (i+1) * angle_step]) segment();
    }
}

Avoid thin radial slices:
- 2mm segments with 4.5° spacing = gaps (BAD)
- 20-30mm segments with 4.5° spacing = continuous (GOOD)

Entry/Exit Design

Use difference() for openings:

difference() {
    union() {
        // Build complete spiral
        spiral_ramp();
    }
    // Cut entry slot
    entry_slot_cut();
}

Don't try to skip segments during generation - creates edge cases and gaps.

Common Pitfalls

1. Library Path Issues

Symptom: "Can't open library" error Solution: Verify libraries are in ~/Documents/OpenSCAD/libraries/

2. Version Conflicts

Symptom: Functions don't work as expected Solution: Check BOSL2 version: echo(BOSL_VERSION);

3. Primitive Syntax Errors

Symptom: "spin direction is parallel to anchor" Solution: Use BOSL2 primitives (cuboid()) or avoid including BOSL2

4. Non-Manifold Geometry

Symptom: "Object may not be a valid 2-manifold" Cause: Overlapping segments without proper union Solution: Usually printable if Preview looks correct, but verify with Render (F6)

5. Thin Segment Gaps

Symptom: Spiral looks like a picket fence Solution: Increase segment_width to ≥1.5x angular spacing

Testing Workflow

Preview (F5): Quick iteration, catches syntax errors
Console Check: Look for warnings/errors
Visual Inspection: Rotate model, check from 4+ angles
Full Render (F6): Catches geometry errors, tests manifold
Export STL: Final validation before printing

Reference Links

User's Repository: https://github.com/Euda1mon1a/parametric_projects
BOSL2 Documentation: https://github.com/BelfrySCAD/BOSL2/wiki
OpenSCAD Manual: https://openscad.org/documentation.html

Script: Library Test Generator

The skill includes a Python script to generate test files:

# scripts/create_library_test.py
import os

test_code = '''include <BOSL2/std.scad>
include <Round-Anything/polyround.scad>

echo("BOSL2 Version: ", BOSL_VERSION);

cuboid([20, 20, 20], rounding=2);

translate([30, 0, 0])
    polyRoundExtrude([[0,0,2], [10,0,2], [10,10,2], [0,10,2]], 5);
'''

output_path = os.path.expanduser('~/Documents/OpenSCAD/library-test.scad')
with open(output_path, 'w') as f:
    f.write(test_code)

print(f"Created test file: {output_path}")

Troubleshooting Decision Tree

OpenSCAD error?
├─ "Can't open library"
│  └─ Check ~/Documents/OpenSCAD/libraries/ exists
│     └─ Verify BOSL2/ and Round-Anything/ folders present
│
├─ "spin direction is parallel to anchor"
│  └─ Using cube() with BOSL2 included
│     └─ Replace with cuboid() or remove BOSL2 include
│
├─ Gaps in spiral/surface
│  └─ Check segment_width calculation
│     └─ Increase to ≥1.5x angular spacing
│
└─ Non-manifold geometry
   └─ Check Preview looks correct
      ├─ If yes: Usually printable, proceed
      └─ If no: Check for floating pieces, missing unions

Professional CAD Quality Standard

It is a common pitfall to believe a model is "done" simply because it renders without CGAL errors and is printable. This is the standard for a functional prototype, not a professional product.

When evaluating your design, apply the "Human Standard" test: Would a professional CAD designer at a major toy or consumer product company ship this design?

The Gap Between Functional and Professional

Key Takeaway: Achieving professional quality often requires significantly more effort (e.g., 2x-3x more code) using advanced techniques like minkowski() smoothing, custom rotate_extrude profiles, and careful boolean operations to manage transitions without breaking geometry.

Don't settle for "raw geometry" if the goal is a finished product.

Version History

v1.2 (2024-12-08): Added "Professional CAD Quality Standard" section based on dice tower project learnings.
v1.1 (2024-12-07): Added BOSL2 usage notes, spiral generation best practices, common pitfalls
v1.0 (2024-12-07): Initial creation with BOSL2/Round-Anything verification

Last Updated: 2024-12-08