DOCSEARCHbyAlgolia
Submit Docs

BOSL (The Belfry OpenScad Library)

repository·master·Indexed 20 days ago

https://github.com/revarbat/bosl

A comprehensive collection of tools, shapes, and helpers for OpenSCAD designed to make modeling more efficient and intent-based. BOSL provides high-level transformation functions (such as up, xrot, and zring), structured shape modules with automatic centering and fillets (such as cuboid and prismoid), and specialized masks for boolean operations.

Tokens
2K
Snippets
6
Records
9
Agent score
22%

What's inside BOSL

  1. Understand BOSL terminology and coordinate orientation

    master

    BOSL uses specific terminology for directions and axes to simplify coding intent. Understanding these is crucial for using the library's transformation and shape functions correctly.

    Directional Mapping

    • Left: Towards X-
    • Right: Towards X+
    • Front/Forward: Towards Y-
    • Back/Behind: Towards Y+
    • Bottom/Down/Below: Towards Z-
    • Top/Up/Above: Towards Z+

    Axis Orientation

    • Axis-Positive: Towards the positive end of the axis (X+, Y+, or Z+).
    • Axis-Negative: Towards the negative end of the axis (X-, Y-, or Z-).

  2. Install the BOSL library

    master

    Follow these steps to install BOSL into your OpenSCAD environment:

    1. Download the .zip or .tar.gz release file.
    2. Unpack the archive. It will contain a directory named BOSL-v1.0.
    3. Rename the BOSL-v1.0 directory to BOSL.
    4. Move the BOSL directory into your platform's OpenSCAD library folder:
      • Windows: My Documents\OpenSCAD\libraries\
      • Linux: $HOME/.local/share/OpenSCAD/libraries/
      • Mac OS X: $HOME/Documents/OpenSCAD/libraries/
    5. Restart OpenSCAD.

  3. Format LibFile, Section, and CommonCode comments

    master

    Documentation and images are automatically generated from source code comments using scripts/docs_gen.py. To include content in the wiki, use specific comment keywords. Indentation is critical: blocks end when a line is not indented with at least three spaces after the comment marker.

    Keywords

    • // LibFile: NAME: Defines a library file header. Can be followed by markdown text.
    • // Section: NAME: Defines a documentation section. Can include Figure: blocks for images.
    • // CommonCode:: Defines code that is shared across all Figure and Example blocks in the file but is not displayed itself.
    // LibFile: foo.scad
//   This is markdown text for the library file.
//
// Section: Foobar
//   Markdown text for a section.
// Figure: Figure description
//   cylinder(h=100, d=50);
//
// CommonCode:
//   module shared_helper() { cube(10); }

  4. Document Modules, Functions, and Constants

    master

    Use // Module: NAME, // Function: NAME, or // Constant: NAME to document code entities. These blocks support several optional sub-blocks to provide rich documentation in the generated wiki.

    Sub-blocks

    • Status: ...: Marks an entity as DEPRECATED and provides usage instructions.
    • Usage: [Title]: Provides usage patterns. Use [opt] for optional arguments and r|d for alternate arguments.
    • Description:: A single-line or multi-line markdown description.
    • Arguments:: An indented list where each line follows the format arg = description.
    • Side Effects:: Describes changes to state or $special_vars.
    • Example:: A single multi-line code block with one image.
    • Examples:: Multiple single-line code blocks, each generating its own example and image.

    Note on Images: Modules always generate images for examples. Functions and Constants only generate images if the example is tagged with 2D or 3D.

    // Module: foo()
// Status: DEPRECATED, use BLAH instead.
// Usage: Basic usage
//   foo(foo, bar, [qux]);
// Description: A long description.
// Arguments:
//   foo = Description of foo.
//   bar = Description of bar.
// Example:
//   foo(foo="a", bar="b");

  5. Use BOSL masks for boolean operations

    master

    The masks.scad file provides shapes specifically designed to be used with difference() or intersect() to create complex profiles or holes.

    BOSL CommandOpenSCAD Equivalent
    chamfer_mask_z(l=20,chamfer=5);rotate(45) cube([5*sqrt(2), 5*sqrt(2), 20], center=true);
    fillet_mask_z(l=20,fillet=5);difference() {cube([10,10,20], center=true); for(dx=[-5,5],dy=[-5,5]) translate([dx,dy,0]) cylinder(h=20.1, r=5, center=true);}
    fillet_hole_mask(r=30,fillet=5);difference() {cube([70,70,10], center=true); translate([0,0,-5]) rotate_extrude(convexity=4) translate([30,0,0]) circle(r=5);}
    // Example of using masks for boolean subtraction
difference() {
    cube([50,50,10], center=true);
    chamfer_mask_z(l=20, chamfer=5);
}

  6. Use BOSL transformations for intent-based coding

    master

    BOSL provides high-level transformation functions that replace complex, multi-step OpenSCAD operations with single, readable commands.

    BOSL CommandOpenSCAD Equivalent
    up(5)translate([0,0,5])
    xrot(30,cp=[0,10,20])translate([0,10,20]) rotate([30,0,0]) translate([0,-10,-20])
    xspread(20,n=3)for (dx=[-20,0,20]) translate([dx,0,0])
    zring(n=6,r=20)for (zr=[0:5]) rotate([0,0,zr*60]) translate([20,0,0])
    skew_xy(xa=30,ya=45)multmatrix([[1,0,tan(30),0],[0,1,tan(45),0],[0,0,1,0],[0,0,0,1]])
    // Example of intent-based transformations
u p(5);
xrot(30, cp=[0,10,20]);
xspread(20, n=3);

  7. Use BOSL shapes for structured objects

    master

    BOSL offers advanced shape modules that handle centering, orientation, and complex geometry (like fillets) automatically.

    BOSL CommandOpenSCAD Equivalent
    upcube([10,20,30]);translate([0,0,15]) cube([10,20,30], center=true);
    cuboid([20,20,30], fillet=5, edges=EDGES_Z_ALL);minkowski() {cube([10,10,20], center=true); sphere(r=5, $fn=32);}
    prismoid([30,40],[20,30],h=10);hull() {translate([0,0,0.005]) cube([30,40,0.01], center=true); translate([0,0,9.995]) cube([20,30,0.01],center=true);}
    xcyl(l=20,d=4);rotate([0,90,0]) cylinder(h=20, d=4, center=true);
    cyl(l=100, d=40, fillet=5);translate([0,0,50]) minkowski() {cylinder(h=90, d=30, center=true); sphere(r=5);}
    // Example of using structured shapes
upcube([10,20,30]);
cuboid([20,20,30], fillet=5, edges=EDGES_Z_ALL);
prismoid([30,40],[20,30], h=10);
xcyl(l=20, d=4);
cyl(l=100, d=40, fillet=5);

  8. Common arguments used in BOSL functions

    master

    Many BOSL modules and functions share a set of common arguments to control geometry and placement. It is highly recommended to use the constants provided in constants.scad for these arguments.

    ArgumentDescription
    filletRadius of rounding for interior or exterior edges.
    chamferSize of chamfers/bevels for interior or exterior edges.
    orientAxis a part should be oriented along. Given as an XYZ triplet of rotation angles. Use ORIENT_ constants from constants.scad. Default is usually ORIENT_Z.
    alignSide of the origin that the part should be on. Given as a vector away from the origin. Use V_ constants from constants.scad. Default is usually V_ZERO (centered).

  9. Use Example tags for rendering control

    master

    When documenting Modules, Functions, or Constants, you can add tags inside parentheses immediately after the Example or Examples keyword to control how the generated image is rendered.

    Available Tags

    • 2D: Top-down view.
    • 3D: Oblique view (required to force images in Function/Constant blocks).
    • Spin: Animated camera orbit around the [0,1,1] axis.
    • FlatSpin: Animated camera orbit around the Z axis (above the XY plane).
    • FR: Forces full rendering from OpenSCAD instead of preview.
    • Small, Med, Big: Controls the size of the generated image.
    // Example(2D):
//   foo(foo="b");
//
// Example(Spin):
//   foo(foo="b");
//
// Example(Big):
//   foo(foo="b");