µcad

µcad (pronounced microcad) is a description language for modeling parameterizable geometric objects. Simple basic shapes can be composed to create complex geometries which then can be rendered into STL or SVG files for 3D printing or CNC milling.

Note: This project is in an early stage of development and is not yet feature complete. Feel free to contribute by opening issues or pull requests.

Content

• µcad
  • Content
  • Quick Start
    • Installation
    • Basic Example
      • Source Code Explanation
  • Documentation
  • Contribute
    • Get Source Code
    • Get External Libraries
    • Build µcad
    • Install µcad locally from source
    • Contributing to Documentation
      • User Manual
  • Test List

Quick Start

µcad is programmed in Rust which easily can be installed on several operating systems. You can try it out with an example by using the command line tool microcad-cli which can be installed from crates.io by using cargo.

Note: Currently µcad has no binary install packages so the only ways to install it are with cargo install or from the source code (see section Contribute).

Installation

To install the latest release of µcad via cargo, type:

cargo install microcad-cli

Basic Example

After installing, you can run a basic example by typing:

microcad eval ./examples/lid.µcad

This will evaluate the input file and will calculate and output the volume of the geometry:

Volume: 48.415571412489506cm³

The evaluate command will not export the output geometry. Instead, it will simply run the program, which prints out the volume.

To generate an STL model file use the export command with an additional output file name:

microcad export ./examples/lid.µcad

The output file lid.stl can be displayed e.g. with MeshLab. The resulting STL model looks like this:

Source Code Explanation

The source file defines a module called lid, which instantiates two cylinders with different diameters and geometrically subtracts them with each other to generate a round lid.

// We have module called `lid` with three parameters
module lid(
    thickness = 1.6mm,
    inner_diameter = 16cm,
    height = 20mm,
) {
    // Calculate the outer diameter
    outer_diameter = 2 * thickness + inner_diameter;

    // Create two cylinders, one for the outer and one for the inner
    outer = std::geo3d::cylinder(d = outer_diameter, h = height);
    inner = std::translate(z = thickness) std::geo3d::cylinder(d = inner_diameter, h = height);

    // Calculate the difference between two translated cylinders and output them
    outer - inner;
}

// `l` is the instance of the lid model
l = lid();

// Print out the volume of the model instance
std::print("Volume: {l.volume() / 1000}cm³");

// Insert `l` into resulting object tree
std::export("lid.stl") l;

The above program prints out the following text and exports the model into a STL file called lid.stl.

Volume: 48.415571412489506cm³

The STL file can now be loaded in a slicer program like Cura and print it on a 3D printer.

Documentation

• Description of language features
• Basic concepts
• Code documentation:
  • microcad-lang module
  • microcad-core module
  • microcad-export module
• Glossary

Contribute

We welcome contributions to µcad, whether it is a bug report, feature request, or a pull request.

First install Git and Rust.

Get Source Code

git clone https://github.com/Rustfahrtagentur/microcad.git
cd microcad

Get External Libraries

git submodule init
git submodule update

Build µcad

cargo build

Install µcad locally from source

cargo install --path tools/cli

Contributing to Documentation

User Manual

The user manual consists of several markdown files stored in the /doc folder, starting with the inside README.md.

One may insert µcad code into the markdown files, which then will get tested automatically if you run cargo test and name them like:

```µcad,my_test

The markdown will be searched for any µcad code and appropriate rust tests will be generated.

beside the name you may add a test mode (see table below):

```µcad,my_test#fail

The tests will create .test folders beside the markdown files. The tests will then copy an image file (*.png) for every test which signals the test result into the .test folder. They can be included in the markdown, if you use this code:

![test](.test/my_test.png)
```µcad,my_test

Image	MD Code Type	Mark	Code	What do do?
	µcad		succeeds	ok
	µcad		fails	fix test or code
	µcad	#fail	succeeds but should fail	find out why
	µcad	#fail	fails intentionally	ok
	µcad	#todo	needs more work to succeed	create issue/implement
	µcad	#todo	Succeeds but still marked to do	remove #todo
-	µcad	#no-test	Ignore completely	yolo!
-	-	`	Ignore completely	yolo!
-	(other)	`	Ignore completely	yolo!

You may also give the reader access to the logs by clicking on the banner with:

[![test](.test/my_test.png)](.test/my_test.log)
```µcad,my_test

Test List

There is a list of all tests included in this documentation.