Overview

omdl, OpenSCAD Mechanical Design Library, is an open-source parametric framework for mechanical design in OpenSCAD. It provides reusable design primitives and fabrication-oriented modules intended to support real mechanical workflows rather than isolated geometric modeling.

omdl was originally conceived to support the design of mechanically engineered objects intended for real-world CNC-based fabrication. A central goal of the library is to separate design intent from implementation parameters, enabling late-time parameter binding during model composition.

By decoupling intent from geometry, designers can work at a higher level of abstraction, describing what a component must achieve rather than committing early to specific dimensions or configurations. This approach increases target outcome flexibility, allowing designs to be recomposed or adapted to new requirements without rewriting core geometry.

In practice, this means that assemblies can be adjusted to match a particular application, manufacturing constraint, or the commodity components currently available. Late parameter binding allows the same design definition to integrate different off-the-shelf parts, making omdl well suited for iterative engineering workflows and fabrication-driven design.

The library emphasizes:

Parametric mechanical design: components are defined by properties and intent rather than fixed geometry.
Standardized data types: Structured parameter abstractions used to convey configuration, intent, and implementation details between modules.
Minimal global state: modules are designed to be predictable and composable.
Unit operations: consistent handling of lengths, angles, and dimensional data.
Integrated documentation: API behavior and usage are documented directly in source using Doxygen and openscad-amu.
Validation-driven development: automated scripts verify functionality of core primitives across evolving OpenSCAD versions.

Instead of treating OpenSCAD purely as a shape generator, omdl introduces a structured mechanical design layer that helps bridge conceptual design, drafting, and fabrication.

Design Philosophy

omdl is shaped by a set of design decisions that follow from its engineering focus.

Geometry is treated as a consequence of mechanical decisions, not their starting point. Rather than exposing low-level shape primitives as the primary interface, omdl encourages working at the level of components, operations, and assemblies — describing what a part must achieve before specifying how it is constructed.

Modules are designed to be included individually as needed, helping keep projects lightweight and reducing unnecessary dependencies. This modular approach also supports interoperability, making it easier to integrate omdl alongside other OpenSCAD design libraries without imposing a rigid project structure.

The library is organized into modular groups that represent distinct functional areas, including tooling utilities, drafting operations, design data, mathematical operations, geometric primitives, and mechanical components. This structure encourages separation of concerns while allowing developers to work at the appropriate level of abstraction for their design.

Documentation Approach

All documentation is generated from inline source comments using Doxygen. The documentation is retrieved from the source code and pre-processed by openscad-amu before being sent to Doxygen for processing into the desired output format.

This approach ensures that:

examples remain synchronized with the implementation,
parameter behavior is clearly described,
documentation can be exported to multiple formats such as HTML or PDF.

Validation scripts are executed during the documentation build process to confirm that core operations behave consistently across supported OpenSCAD versions. This has become less pressing with the maturing OpenSCAD language.

Who This Library Is For

omdl is intended for:

Mechanical engineers using OpenSCAD for parametric design
Makers building fabrication-ready components
Developers creating reusable mechanical modules
Projects that benefit from application-specific mechanical design
“Just-fit” solutions using available commodity components

It may be less suitable for purely artistic modeling workflows where strict dimensional control is unnecessary.

Getting Started

Before running examples, follow the [installing] instructions to set up omdl and its build environment. For an introduction to the type system and parameter conventions used throughout the library, see [data types].

The minimal example below demonstrates how omdl modules can be combined to construct a fabrication-oriented component. The example builds a custom linear rod bearing using parametric dimensions and unit conversion functions.

Hello world script

    include <omdl-base.scad>;
    include <transforms/base_cs.scad>;
    include <tools/2d/drafting/draft-base.scad>;
    include <parts/3d/motion/bearing_linear_rod.scad>;
 
    $fn = 36;
 
    p = [length(0.706, "in"), length(0.622, "in")];
    b = length(6, "mm");
 
    r = 21.5; c = 6; a = 85;
    h = [b*8, undef, false];
 
    v = is_undef ( __mfs__diag ) ? 2: undef;
 
    bearing_linear_rod(pipe=p, ball=b, count=c, angle=a, h=h, align=4, view=v)
    minkowski() {cylinder(r=r-b*2/3, h=first(h)-b*3/2, center=true); sphere(r=r/5);};
 
    // end_include

In this example, bearing_linear_rod() is used to construct a custom linear bearing for fabrication on a 3D printer.

Hello world diagram
right	top	front	diag

The dimension operations in the above example can be found near the end of docs_home.scad within the scope quickstart.

Contributing

omdl is developed using Git and hosted on GitHub. Contributions typically follow the standard forking and pull requests workflow. Because the project is licensed under the GNU Lesser General Public License, modified files should retain original copyright notices alongside any new authorship.

Ideas, bug reports, feature requests, and improvements to documentation are encouraged.

Support

Questions, feature requests, or issues can be submitted through the project’s issue tracker.

Table of Contents