Getting started with µcad

This guide takes you from installing µcad to your first 2D drawing and 3D model, and shows the tools to view and edit models.

The easiest way to get started is using the playground. We do not publish any binaries yet.

Note: µcad is in an early stage of development. Some features described here are only available when installing from the source code.

Content

Install µcad

Although you can use the playground to test µcad without installation, you can install it via cargo.

µcad is written in Rust. Install Rust with rustup, then install the µcad command line tool mucad from crates.io:

cargo install mucad

For the latest features, install it from the source code instead:

git clone https://codeberg.org/mucad/mucad.git
cd mucad
cargo install --path crates/cli

Check the installation:

mucad --version

The standard library (std) is installed automatically, when mucad needs it the first time, into your configuration directory, e.g. ~/.config/mucad/lib on Linux.

Your first sketch

A sketch creates 2D geometry. Save the following code as plate.mu:

// A plate with four holes.
sketch Plate(width: Length, height: Length, hole: Length) {
    // The holes are moved to the four corners.
    holes = Circle(d = hole)
        .translate(
            x = [-1, 1] * (width / 2 - 2 * hole),
            y = [-1, 1] * (height / 2 - 2 * hole),
        );
    Rect(width, height) - holes;
}

Plate(width = 60mm, height = 40mm, hole = 5mm);

sketch Plate(...) defines a sketch with three parameters of the type Length.
Rect and Circle are shapes of the standard library, which can be used by name.
translate moves a geometry.
A list of values, e.g. [-1, 1] * ..., creates a copy for each value, so the we have four circle at each position.
- subtracts geometry, so the circle become holes.
The last line creates the model of the file: a plate of 60 mm × 40 mm with 5 mm holes.

Check the file for errors:

mucad check plate.mu

Export it:

mucad export plate.mu

This writes plate.svg next to plate.mu, because a sketch is 2D. Open it with a web browser or a vector graphics program.

From 2D to 3D

A sketch can be extruded into a 3D model. Save the following code as box.mu:

// The plate, extruded into a 3D model.
sketch Plate(width: Length, height: Length, hole: Length) {
    holes = Circle(d = hole)
        .translate(
            x = [-1, 1] * (width / 2 - 2 * hole),
            y = [-1, 1] * (height / 2 - 2 * hole),
        );
    Rect(width, height) - holes;
}

#[export = "plate.stl"]
Plate(width = 60mm, height = 40mm, hole = 5mm).extrude(5mm);

The attribute #[export = "plate.stl"] tells mucad export the file to write. List the files an export would write, without writing them:

mucad export box.mu --dry-run

Then export the model:

mucad export box.mu

This writes plate.stl, e.g. for a 3D printer. An output file given on the command line is used instead of the attributes. Round shapes are approximated by straight lines and flat faces, use --resolution for a finer export, e.g. twice as fine:

mucad export box.mu plate_fine.stl --resolution 200%

Working on a model

You can use the watch command to re-export a model whenever you save the file:

mucad watch box.mu

Format a µcad source file:

mucad format box.mu

You can also use mucad format via stdin and stdout:

cat box.mu > mucad fmt # Will output the formatted code.

mucad --help lists all commands, e.g. mucad compile to show the inner workings of the compiler.

Viewing models

The µcad viewer shows a model and updates it, whenever the file changes:

cargo install mucad-viewer
mucad-viewer box.mu

The web viewer runs µcad in the browser: edit the code and see the model at once, and export it as STL or SVG.

See its README to run it locally.

Editor support

Zed: syntax highlighting and, with the µcad language server, errors, completion and formatting.
VS Code: syntax highlighting and the µcad language server.

Next steps

Study the examples in the playground.
in progress The language reference describes µcad in detail.
Contribute to µcad, e.g. by reporting issues or improving the documentation.