cadrum

Rust CAD library powered by statically linked, headless OpenCASCADE (OCCT 8.0.0-beta1).

Usage

primitives	write read	transform	boolean
extrude	loft	sweep	shell
bspline	fillet	chamfer

More examples with source code are available at lzpel.github.io/cadrum.

Add this to your Cargo.toml:

[dependencies]
cadrum = "^0.7"

Build

cargo build automatically downloads a prebuilt OCCT 8.0.0-rc5 binary for the targets below.

	Target	Prebuilt
	x86_64-unknown-linux-gnu	✅
	aarch64-unknown-linux-gnu	✅
	x86_64-pc-windows-msvc	✅
	x86_64-pc-windows-gnu	✅

For other targets, build OCCT from source:

OCCT_ROOT=/path/to/occt cargo build --features source-build

If OCCT_ROOT is not set, built binaries are cached under target/.

Requirements when building OpenCASCADE from source

• C++17 compiler (GCC, Clang, or MSVC)
• CMake

Examples

Primitives

Primitive solids: box, cylinder, sphere, cone, torus — colored and exported as STEP + SVG.

cargo run --example 01_primitives

//! Primitive solids: box, cylinder, sphere, cone, torus — colored and exported as STEP + SVG.

use cadrum::{DVec3, Solid};

fn main() {
    let example_name = std::path::Path::new(file!()).file_stem().unwrap().to_str().unwrap();

    let solids = [
        Solid::cube(10.0, 20.0, 30.0)
            .color("#4a90d9"),
        Solid::cylinder(8.0, DVec3::Z, 30.0)
            .translate(DVec3::X * 30.0)
            .color("#e67e22"),
        Solid::sphere(8.0)
            .translate(DVec3::X * 60.0 + DVec3::Z * 15.0)
            .color("#2ecc71"),
        Solid::cone(8.0, 0.0, DVec3::Z, 30.0)
            .translate(DVec3::X * 90.0)
            .color("#e74c3c"),
        Solid::torus(12.0, 4.0, DVec3::Z)
            .translate(DVec3::X * 130.0 + DVec3::Z * 15.0)
            .color("#9b59b6"),
    ];

    let mut f = std::fs::File::create(format!("{example_name}.step")).expect("failed to create file");
    Solid::write_step(&solids, &mut f).expect("failed to write STEP");

    let mut svg = std::fs::File::create(format!("{example_name}.svg")).expect("failed to create SVG file");
    Solid::mesh(&solids, 0.5).and_then(|m| m.write_svg(DVec3::ONE, DVec3::Z, true, false, &mut svg)).expect("failed to write SVG");
}

• 01_primitives.step

Write read

Read and write: chain STEP, BRep text, and BRep binary round-trips with progressive rotation.

cargo run --example 02_write_read

//! Read and write: chain STEP, BRep text, and BRep binary round-trips with progressive rotation.

use cadrum::{Compound, DVec3, Solid};
use std::f64::consts::FRAC_PI_8;

fn main() -> Result<(), cadrum::Error> {
    let example_name = std::path::Path::new(file!()).file_stem().unwrap().to_str().unwrap();
    let step_path = format!("{example_name}.step");
    let text_path = format!("{example_name}_text.brep");
    let brep_path = format!("{example_name}.brep");

    // 0. Original: read colored_box.step
    let manifest_dir = env!("CARGO_MANIFEST_DIR");
    let original = Solid::read_step(
        &mut std::fs::File::open(format!("{manifest_dir}/steps/colored_box.step")).expect("open file"),
    )?;

    // 1. STEP round-trip: rotate 30° → write → read
    let a_written = original.clone().rotate_x(FRAC_PI_8);
    Solid::write_step(&a_written, &mut std::fs::File::create(&step_path).expect("create file"))?;
    let a = Solid::read_step(&mut std::fs::File::open(&step_path).expect("open file"))?;

    // 2. BRep text round-trip: rotate another 30° → write → read
    let b_written = a.clone().rotate_x(FRAC_PI_8);
    Solid::write_brep_text(&b_written, &mut std::fs::File::create(&text_path).expect("create file"))?;
    let b = Solid::read_brep_text(&mut std::fs::File::open(&text_path).expect("open file"))?;

    // 3. BRep binary round-trip: rotate another 30° → write → read
    let c_written = b.clone().rotate_x(FRAC_PI_8);
    Solid::write_brep_binary(&c_written, &mut std::fs::File::create(&brep_path).expect("create file"))?;
    let c = Solid::read_brep_binary(&mut std::fs::File::open(&brep_path).expect("open file"))?;

    // 4. Arrange side by side and export SVG + STL
    let [min, max] = original[0].bounding_box();
    let spacing = (max - min).length() * 1.5;
    let all: Vec<Solid> = [original, a, b, c].into_iter()
        .enumerate()
        .flat_map(|(i, solids)| solids.translate(DVec3::X * spacing * i as f64))
        .collect();

    let mut svg = std::fs::File::create(format!("{example_name}.svg")).expect("create file");
    Solid::mesh(&all, 0.5).and_then(|m| m.write_svg(DVec3::new(1.0, 1.0, 2.0), DVec3::Z, true, false, &mut svg))?;

    let mut stl = std::fs::File::create(format!("{example_name}.stl")).expect("create file");
    Solid::mesh(&all, 0.1).and_then(|m| m.write_stl(&mut stl))?;

    // 5. Print summary
    let stl_path = format!("{example_name}.stl");
    for (label, path) in [("STEP", &step_path), ("BRep text", &text_path), ("BRep binary", &brep_path), ("STL", &stl_path)] {
        let size = std::fs::metadata(path).map(|m| m.len()).unwrap_or(0);
        println!("{label:12} {path:30} {size:>8} bytes");
    }

    Ok(())
}

• 02_write_read.brep
• 02_write_read.step
• 02_write_read.stl

Transform

Transform operations: translate, rotate, scale, and mirror applied to a cone.

cargo run --example 03_transform

//! Transform operations: translate, rotate, scale, and mirror applied to a cone.

use cadrum::{DVec3, Solid};
use std::f64::consts::PI;

fn main() {
    let example_name = std::path::Path::new(file!()).file_stem().unwrap().to_str().unwrap();

    let base = Solid::cone(8.0, 0.0, DVec3::Z, 20.0)
        .color("#888888");

    let solids = [
        // original — reference, no transform
        base.clone(),
        // translate — shift +20 along Z
        base.clone()
            .color("#4a90d9")
            .translate(DVec3::X * 40.0 + DVec3::Z * 20.0),
        // rotate — 90° around X axis so the cone tips toward Y
        base.clone()
            .color("#e67e22")
            .rotate_x(PI / 2.0)
            .translate(DVec3::X * 80.0),
        // scaled — 1.5x from its local origin
        base.clone()
            .color("#2ecc71")
            .scale(DVec3::ZERO, 1.5)
            .translate(DVec3::X * 120.0),
        // mirror — flip across Z=0 plane so the tip points down
        base.clone()
            .color("#e74c3c")
            .mirror(DVec3::ZERO, DVec3::Z)
            .translate(DVec3::X * 160.0),
    ];

    let mut f = std::fs::File::create(format!("{example_name}.step")).expect("failed to create file");
    Solid::write_step(&solids, &mut f).expect("failed to write STEP");

    let mut svg = std::fs::File::create(format!("{example_name}.svg")).expect("failed to create SVG file");
    Solid::mesh(&solids, 0.5).and_then(|m| m.write_svg(DVec3::ONE, DVec3::Z, true, false, &mut svg)).expect("failed to write SVG");
}

• 03_transform.step

Boolean

Boolean operations: union, subtract, and intersect between a box and a cylinder.

cargo run --example 04_boolean

//! Boolean operations: union, subtract, and intersect between a box and a cylinder.

use cadrum::{Compound, DVec3, Solid};

fn main() -> Result<(), cadrum::Error> {
    let example_name = std::path::Path::new(file!()).file_stem().unwrap().to_str().unwrap();

    let make_box = Solid::cube(20.0, 20.0, 20.0)
        .color("#4a90d9");
    let make_cyl = Solid::cylinder(8.0, DVec3::Z, 30.0)
        .translate(DVec3::new(10.0, 10.0, -5.0))
        .color("#e67e22");

    // union: merge both shapes into one — offset X=0
    let union = make_box
        .union(&[make_cyl.clone()])?;

    // subtract: box minus cylinder — offset X=40
    let subtract = make_box
        .subtract(&[make_cyl.clone()])?
        .translate(DVec3::X * 40.0);

    // intersect: only the overlapping volume — offset X=80
    let intersect = make_box
        .intersect(&[make_cyl])?
        .translate(DVec3::X * 80.0);

    let shapes: Vec<Solid> = [union, subtract, intersect].concat();

    let mut f = std::fs::File::create(format!("{example_name}.step")).expect("failed to create file");
    Solid::write_step(&shapes, &mut f).expect("failed to write STEP");

    let mut svg = std::fs::File::create(format!("{example_name}.svg")).expect("failed to create SVG file");
    Solid::mesh(&shapes, 0.5).and_then(|m| m.write_svg(DVec3::new(1.0, 1.0, 2.0), DVec3::Z, true, false, &mut svg)).expect("failed to write SVG");

    Ok(())
}

• 04_boolean.step

Extrude

Demo of Solid::extrude: push a closed 2D profile along a direction vector.

cargo run --example 05_extrude

//! Demo of `Solid::extrude`: push a closed 2D profile along a direction vector.
//!
//! - **Box**: square polygon extruded along Z
//! - **Oblique cylinder**: circle extruded at a steep angle
//! - **L-beam**: L-shaped polygon extruded along Z
//! - **Heart**: BSpline heart-shaped profile extruded along Z

use cadrum::{BSplineEnd, DVec3, Edge, Error, Solid};

/// Square polygon → box (simplest extrude).
fn build_box() -> Result<Solid, Error> {
	let profile = Edge::polygon(&[
		DVec3::new(0.0, 0.0, 0.0),
		DVec3::new(5.0, 0.0, 0.0),
		DVec3::new(5.0, 5.0, 0.0),
		DVec3::new(0.0, 5.0, 0.0),
	])?;
	Solid::extrude(&profile, DVec3::Z * 8.0)
}

/// Circle extruded at a steep angle → oblique cylinder.
fn build_oblique_cylinder() -> Result<Solid, Error> {
	let profile = [Edge::circle(3.0, DVec3::Z)?];
	Solid::extrude(&profile, DVec3::new(-4.0, -6.0, 8.0))
}

/// L-shaped polygon → L-beam.
fn build_l_beam() -> Result<Solid, Error> {
	let profile = Edge::polygon(&[
		DVec3::new(0.0, 0.0, 0.0),
		DVec3::new(4.0, 0.0, 0.0),
		DVec3::new(4.0, 1.0, 0.0),
		DVec3::new(1.0, 1.0, 0.0),
		DVec3::new(1.0, 3.0, 0.0),
		DVec3::new(0.0, 3.0, 0.0),
	])?;
	Solid::extrude(&profile, DVec3::Z * 12.0)
}

/// Heart-shaped BSpline profile extruded along Z.
fn build_heart() -> Result<Solid, Error> {
	let profile = [Edge::bspline(
		&[
			DVec3::new(0.0, -4.0, 0.0),   // bottom tip
			DVec3::new(2.0, -1.5, 0.0),
			DVec3::new(4.0, 1.5, 0.0),
			DVec3::new(2.5, 3.5, 0.0),    // right lobe top
			DVec3::new(0.0, 2.0, 0.0),    // center dip
			DVec3::new(-2.5, 3.5, 0.0),   // left lobe top
			DVec3::new(-4.0, 1.5, 0.0),
			DVec3::new(-2.0, -1.5, 0.0),
		],
		BSplineEnd::Periodic,
	)?];
	Solid::extrude(&profile, DVec3::Z * 7.0)
}

fn main() -> Result<(), Error> {
	let example_name = std::path::Path::new(file!()).file_stem().unwrap().to_str().unwrap();

	let box_solid = build_box()?.color("#b0d4f1");
	let oblique = build_oblique_cylinder()?.color("#f1c8b0").translate(DVec3::X * 10.0);
	let l_beam = build_l_beam()?.color("#b0f1c8").translate(DVec3::X * 20.0);
	let heart = build_heart()?.color("#f1b0b0").translate(DVec3::X * 30.0);

	let result = [box_solid, oblique, l_beam, heart];

	let mut f = std::fs::File::create(format!("{example_name}.step")).expect("failed to create STEP file");
	Solid::write_step(&result, &mut f).expect("failed to write STEP");

	let mut f = std::fs::File::create(format!("{example_name}.svg")).expect("failed to create SVG file");
	Solid::mesh(&result, 0.5).and_then(|m| m.write_svg(DVec3::ONE, DVec3::Z, true, false, &mut f)).expect("failed to write SVG");

	println!("wrote {example_name}.step / {example_name}.svg");
	Ok(())
}

• 05_extrude.step

Loft

Demo of Solid::loft: skin a smooth solid through cross-section wires.

cargo run --example 06_loft

//! Demo of `Solid::loft`: skin a smooth solid through cross-section wires.
//!
//! - **Frustum**: two circles of different radii → truncated cone (minimal loft)
//! - **Morph**: square polygon → circle (cross-section shape transition)
//! - **Tilted**: three non-parallel circular sections → twisted loft

use cadrum::{DVec3, Edge, Error, Solid};

/// Two circles → frustum (minimal loft example).
fn build_frustum() -> Result<Solid, Error> {
	let lower = [Edge::circle(3.0, DVec3::Z)?];
	let upper = [Edge::circle(1.5, DVec3::Z)?.translate(DVec3::Z * 8.0)];
	Ok(Solid::loft(&[lower, upper])?.color("#cd853f"))
}

/// Square polygon → circle (2-section morph loft).
fn build_morph() -> Result<Solid, Error> {
	let r = 2.5;
	let square = Edge::polygon(&[
		DVec3::new(-r, -r, 0.0),
		DVec3::new(r, -r, 0.0),
		DVec3::new(r, r, 0.0),
		DVec3::new(-r, r, 0.0),
	])?;
	let circle = Edge::circle(r, DVec3::Z)?.translate(DVec3::Z * 10.0);

	Ok(Solid::loft([square.as_slice(), std::slice::from_ref(&circle)])?.color("#808000"))
}

/// Three non-parallel circular sections → twisted loft.
fn build_tilted() -> Result<Solid, Error> {
	let bottom = [Edge::circle(2.5, DVec3::Z)?];
	let mid = [Edge::circle(2.0, DVec3::new(0.3, 0.0, 1.0).normalize())?
		.translate(DVec3::X + DVec3::Z * 5.0)];
	let top = [Edge::circle(1.5, DVec3::new(-0.2, 0.3, 1.0).normalize())?
		.translate(DVec3::new(-0.5, 1.0, 10.0))];

	Ok(Solid::loft(&[bottom, mid, top])?.color("#4682b4"))
}

fn main() -> Result<(), Error> {
	let example_name = std::path::Path::new(file!()).file_stem().unwrap().to_str().unwrap();

	let frustum = build_frustum()?;
	let morph = build_morph()?.translate(DVec3::X * 10.0);
	let tilted = build_tilted()?.translate(DVec3::X * 20.0);

	let result = [frustum, morph, tilted];

	let mut f = std::fs::File::create(format!("{example_name}.step")).expect("failed to create STEP file");
	cadrum::Solid::write_step(&result, &mut f).expect("failed to write STEP");

	let mut f = std::fs::File::create(format!("{example_name}.svg")).expect("failed to create SVG file");
	cadrum::Solid::mesh(&result, 0.5).and_then(|m| m.write_svg(DVec3::ONE, DVec3::Z, true, false, &mut f)).expect("failed to write SVG");

	println!("wrote {example_name}.step / {example_name}.svg");
	Ok(())
}

• 06_loft.step

Sweep

Sweep showcase: M2 screw (helix spine) + U-shaped pipe (line+arc+line spine)

cargo run --example 07_sweep

//! Sweep showcase: M2 screw (helix spine) + U-shaped pipe (line+arc+line spine)
//! + twisted ribbon (`Auxiliary` aux-spine mode).
//!
//! `ProfileOrient` controls how the profile is oriented as it travels along the spine:
//!
//! - `Fixed`: profile is parallel-transported without rotating. Cross-sections
//!   stay parallel to the starting orientation. Suited for straight extrusions;
//!   on a curved spine the profile drifts off the tangent and the result breaks.
//! - `Torsion`: profile follows the spine's principal normal (raw Frenet–Serret
//!   frame). Suited for constant-curvature/torsion curves like helices and for
//!   3D free curves where the natural twist should carry into the profile.
//!   Fails near inflection points where the principal normal flips.
//! - `Up(axis)`: profile keeps `axis` as its binormal — at every point the
//!   profile is rotated around the tangent so one in-plane axis stays in the
//!   tangent–`axis` plane. Suited for roads/rails/pipes that must preserve a
//!   gravity direction. On a helix, `Up(helix_axis)` is equivalent to `Torsion`.
//!   Fails when the tangent becomes parallel to `axis`.
//! - `Auxiliary(aux_spine)`: profile's tracked axis points from the main spine
//!   toward a parallel auxiliary spine. Arbitrary twist control — e.g. a
//!   helical `aux_spine` on a straight `spine` produces a twisted ribbon.

use cadrum::{Compound, DVec3, Edge, Error, ProfileOrient, Solid, Wire};

// ==================== Component 1: M2 ISO screw ====================

fn build_m2_screw() -> Result<Vec<Solid>, Error> {
	let r = 1.0;
	let h_pitch = 0.4;
	let h_thread = 6.0;
	let r_head = 1.75;
	let h_head = 1.3;
	// ISO M thread fundamental triangle height: H = √3/2 · P (sharp 60° triangle).
	let r_delta = 3f64.sqrt() / 2.0 * h_pitch;

	// Helix spine at the root radius. x_ref=+X anchors the start at (r-r_delta, 0, 0).
	let helix = Edge::helix(r - r_delta, h_pitch, h_thread, DVec3::Z, DVec3::X)?;

	// Closed triangular profile in local coords (x: radial, y: along helix tangent).
	let profile = Edge::polygon(&[DVec3::new(0.0, -h_pitch / 2.0, 0.0), DVec3::new(r_delta, 0.0, 0.0), DVec3::new(0.0, h_pitch / 2.0, 0.0)])?;

	// Align profile +Z with the helix start tangent, then translate to the start point.
	let profile = profile.align_z(helix.start_tangent(), helix.start_point()).translate(helix.start_point());

	// Sweep along the helix. Up(+Z) ≡ Torsion for a helix and yields a correct thread.
	let thread = Solid::sweep(&profile, &[helix], ProfileOrient::Up(DVec3::Z))?;

	// Reconstruct the ISO 68-1 basic profile (trapezoid) from the sharp triangle:
	//   union(shaft) fills the bottom H/4 → P/4-wide flat at the root
	//   intersect(crest) trims the top H/8 → P/8-wide flat at the crest
	let shaft = Solid::cylinder(r - r_delta * 6.0 / 8.0, DVec3::Z, h_thread);
	let crest = Solid::cylinder(r - r_delta / 8.0, DVec3::Z, h_thread);
	let thread_shaft = thread.union([&shaft])?.intersect([&crest])?;

	// Stack the flat head on top. Screw ends up centered on the origin.
	let head = Solid::cylinder(r_head, DVec3::Z, h_head).translate(DVec3::Z * h_thread);
	Ok(thread_shaft.union([&head])?.color("red"))
}

// ==================== Component 2: U-shaped pipe ====================

fn build_u_pipe() -> Result<Vec<Solid>, Error> {
	let pipe_radius = 0.4;
	let leg_length = 6.0;
	let gap = 3.0;
	let half_gap = gap / 2.0;
	let bend_radius = half_gap;

	// U-shaped path in the XZ plane, centered on origin in X: A↑B ⌒ C↓D.
	let a = DVec3::new(-half_gap, 0.0, 0.0);
	let b = DVec3::new(-half_gap, 0.0, leg_length);
	let arc_mid = DVec3::new(0.0, 0.0, leg_length + bend_radius);
	let c = DVec3::new(half_gap, 0.0, leg_length);
	let d = DVec3::new(half_gap, 0.0, 0.0);

	// Spine wire: line → semicircle → line.
	let up_leg = Edge::line(a, b)?;
	let bend = Edge::arc_3pts(b, arc_mid, c)?;
	let down_leg = Edge::line(c, d)?;

	// Circular profile in XY (normal +Z) translated to the spine start `a`.
	// Spine tangent at `a` is +Z, so the XY-plane circle is already aligned.
	let profile = Edge::circle(pipe_radius, DVec3::Z)?.translate(a);

	// Up(+Y) fixes the binormal to the path-plane normal, avoiding Frenet
	// degeneracy on the straight segments.
	let pipe = Solid::sweep(&[profile], &[up_leg, bend, down_leg], ProfileOrient::Up(DVec3::Y))?;
	Ok(vec![pipe].translate(DVec3::X * 6.0).color("blue"))
}

// ==================== Component 3: Auxiliary-spine twisted ribbon ====================

// Sweeping a straight spine with `Auxiliary(&[helix])` rotates the tracked
// axis of the profile at each point to face the corresponding helix point.
// A pitch=h helix makes exactly one 360° turn over [0, h], so a flat
// rectangular profile becomes a ribbon twisted once. With `Fixed` or
// `Torsion` the profile wouldn't rotate along a straight spine — visible
// twist is therefore proof that Auxiliary is in effect.
fn build_twisted_ribbon() -> Result<Vec<Solid>, Error> {
	let h = 8.0;
	let aux_r = 3.0;

	let spine = Edge::line(DVec3::ZERO, DVec3::Z * h)?;
	let aux = Edge::helix(aux_r, h, h, DVec3::Z, DVec3::X)?;

	// Flat rectangle (10:1 aspect) — circles or squares wouldn't reveal any twist.
	let profile = Edge::polygon(&[DVec3::new(-2.0, -0.2, 0.0), DVec3::new(2.0, -0.2, 0.0), DVec3::new(2.0, 0.2, 0.0), DVec3::new(-2.0, 0.2, 0.0)])?;

	let ribbon = Solid::sweep(&profile, &[spine], ProfileOrient::Auxiliary(&[aux]))?;
	Ok(vec![ribbon].translate(DVec3::X * 12.0).color("green"))
}

// ==================== main: side-by-side layout ====================
//
// Each builder places its component at its final world position (screw at
// origin, U-pipe at x=6, ribbon at x=12) and applies its color, so main
// just concatenates them.

fn main() -> Result<(), Error> {
	let example_name = std::path::Path::new(file!()).file_stem().unwrap().to_str().unwrap();
	let all: Vec<Solid> = [build_m2_screw()?, build_u_pipe()?, build_twisted_ribbon()?].concat();

	let mut f = std::fs::File::create(format!("{example_name}.step")).expect("failed to create STEP file");
	cadrum::Solid::write_step(&all, &mut f)?;
	let mut f_svg = std::fs::File::create(format!("{example_name}.svg")).expect("failed to create SVG file");
	// Helical threads have dense hidden lines that clutter the SVG; disable them.
	cadrum::Solid::mesh(&all, 0.5)?.write_svg(DVec3::new(1.0, 1.0, -1.0), DVec3::Z, false, false, &mut f_svg)?;
	println!("wrote {example_name}.step / {example_name}.svg ({} solids)", all.len());
	Ok(())
}

• 07_sweep.step

Shell

Demo of Solid::shell:

cargo run --example 08_shell

//! Demo of `Solid::shell`:
//! - Cube: remove top face, offset inward → open-top container
//! - Sealed cube: empty open_faces → solid with an internal void (outer skin
//!   + reversed inner shell)
//! - Torus: bisect with a half-space to introduce planar cut faces, then
//!   shell using those cut faces as the openings → thin-walled half-ring
//!   with both cross-sections exposed

use cadrum::{DVec3, Error, Solid};

fn hollow_cube() -> Result<Solid, Error> {
	let cube = Solid::cube(8.0, 8.0, 8.0);
	// TopExp_Explorer order on a box is stable; +Z face ends up last.
	let top = cube.iter_face().last().expect("cube has faces");
	cube.shell(-1.0, [top])
}

fn sealed_cube() -> Result<Solid, Error> {
	let cube = Solid::cube(8.0, 8.0, 8.0);
	cube.shell(-1.0, std::iter::empty::<&cadrum::Face>())
}

fn halved_shelled_torus(thickness: f64) -> Result<Solid, Error> {
	let torus = Solid::torus(6.0, 2.0, DVec3::Y);
	// Bisect with Y=0 half-space (normal +Y): keep the +Y half of the ring — always 1 solid.
	let cutter = Solid::half_space(DVec3::ZERO, -DVec3::Z);
	// `iter_history()` yields [post_id, src_id] pairs for every result face.
	// Filter to those whose src_id is one of the cutter's faces, then collect
	// their post_ids — these are the planar cut faces in the result that we
	// want to use as shell openings.
	let cutter_face_ids: std::collections::HashSet<u64> =
		cutter.iter_face().map(|f| f.id()).collect();
	let halves = torus.intersect(&[cutter])?;
	let half = halves.into_iter().next().ok_or(Error::BooleanOperationFailed)?;
	let from_cutter: std::collections::HashSet<u64> = half
		.iter_history()
		.filter_map(|[post, src]| cutter_face_ids.contains(&src).then_some(post))
		.collect();
	half.shell(thickness, half.iter_face().filter(|f| from_cutter.contains(&f.id())))
}

fn main() -> Result<(), Error> {
	let example_name = std::path::Path::new(file!()).file_stem().unwrap().to_str().unwrap();

	let result = [
		hollow_cube()?.color("#d0a878"),
		sealed_cube()?.color("#6fbf73").translate(DVec3::Y * 10.0),
		halved_shelled_torus(1.0)?.color("#ff5e00").translate(DVec3::X * 18.0),
		halved_shelled_torus(-1.0)?.color("#0052ff").translate(DVec3::X * 18.0 + DVec3::Y * 10.0),
	];

	let mut f = std::fs::File::create(format!("{example_name}.step")).expect("failed to create STEP file");
	cadrum::Solid::write_step(&result, &mut f).expect("failed to write STEP");

	// Isometric view from (1, 1, 2) with shading so the cavity depth reads
	// naturally.
	let mut f = std::fs::File::create(format!("{example_name}.svg")).expect("failed to create SVG file");
	cadrum::Solid::mesh(&result, 0.2).and_then(|m| m.write_svg(DVec3::new(1.0, 1.0, 2.0), DVec3::Z, true, true, &mut f)).expect("failed to write SVG");

	println!("wrote {example_name}.step / {example_name}.svg");
	Ok(())
}

• 08_shell.step

Bspline

cargo run --example 09_bspline

use cadrum::{DQuat, DVec3, Solid};
use std::f64::consts::TAU;

// 2 field-period stellarator-like torus.
// `Solid::bspline` is fed a 2D control-point grid to build a periodic B-spline solid.
// Every variation below is invariant under phi → phi+π (or shifts by a multiple
// of 2π), so the resulting shape has 180° rotational symmetry around the Z axis:
//   a(phi)       = 1.8 + 0.6 * sin(2φ)      radial semi-axis
//   b(phi)       = 1.0 + 0.4 * cos(2φ)      Z semi-axis
//   psi(phi)     = 2 * phi                  cross-section twist (2 turns per loop)
//   z_shift(phi) = 1.0 * sin(2φ)            vertical undulation
const M: usize = 48; // toroidal (U) — must be even for 180° symmetry
const N: usize = 24; // poloidal (V) — arbitrary
const RING_R: f64 = 6.0;

fn point(i: usize, j: usize) -> DVec3 {
	let phi = TAU * (i as f64) / (M as f64);
	let theta = TAU * (j as f64) / (N as f64);
	let two_phi = 2.0 * phi;
	let a = 1.8 + 0.6 * two_phi.sin();
	let b = 1.0 + 0.4 * two_phi.cos();
	let psi = two_phi; // twist: 2 full turns per toroidal loop
	let z_shift = 1.0 * two_phi.sin();
	// 1. Local cross-section (pre-twist ellipse in the (X, Z) plane)
	let local_raw = DVec3::X * (a * theta.cos()) + DVec3::Z * (b * theta.sin());
	// 2. Rotate by psi around the local Y axis (major-circle tangent) — the twist
	let local_twisted = DQuat::from_axis_angle(DVec3::Y, psi) * local_raw;
	// 3. Undulate vertically in the local frame
	let local_shifted = local_twisted + DVec3::Z * z_shift;
	// 4. Push outward along the major radius by RING_R
	let translated = local_shifted + DVec3::X * RING_R;
	// 5. Rotate the whole point around the global Z axis by phi
	DQuat::from_axis_angle(DVec3::Z, phi) * translated
}

fn main() {
	let example_name = std::path::Path::new(file!()).file_stem().unwrap().to_str().unwrap();

	let plasma = Solid::bspline(M, N, true, point).expect("2-period bspline torus should succeed");
	let objects = [plasma.color("cyan")];
	let mut f = std::fs::File::create(format!("{example_name}.step")).unwrap();
	cadrum::Solid::write_step(&objects, &mut f).unwrap();
	let mut f_svg = std::fs::File::create(format!("{example_name}.svg")).unwrap();
	cadrum::Solid::mesh(&objects, 0.1).and_then(|m| m.write_svg(DVec3::new(0.05, 0.05, 1.0), DVec3::Y, false, true, &mut f_svg)).unwrap();
	println!("wrote {example_name}.step / {example_name}.svg");
}

• 09_bspline.step

Fillet

Demo of Solid::fillet_edges:

cargo run --example 10_fillet

//! Demo of `Solid::fillet_edges`:
//! - All 12 cube edges filleted uniformly (rounded cube)
//! - Only top 4 edges filleted (soft top, sharp base)
//! - Cylinder top circular edge filleted (coin shape)

use cadrum::{DVec3, Error, Solid};

fn rounded_cube(size: f64) -> Result<Solid, Error> {
	let cube = Solid::cube(size, size, size).translate(-DVec3::ONE * (size / 2.0));
	let radius = size * 0.2;
	cube.fillet_edges(radius, cube.iter_edge())
}

fn soft_top_cube(size: f64) -> Result<Solid, Error> {
	let cube = Solid::cube(size, size, size).translate(-DVec3::ONE * (size / 2.0));
	let radius = size * 0.2;
	// Top cap boundary: a closed circular edge whose start == end lives at z = h.
	let top_edges = cube
		.iter_edge()
		.filter(|e| [e.start_point(), e.end_point()].iter().all(|p| (p.z - size / 2.0).abs() < 1e-6));
	cube.fillet_edges(radius, top_edges)
}

fn coin(radius: f64, height: f64) -> Result<Solid, Error> {
	let cyl = Solid::cylinder(radius, DVec3::Z, height);
	let radius = height * 0.3;
	// Top cap boundary: a closed circular edge whose start == end lives at z = h.
	let top_circle = cyl
		.iter_edge()
		.filter(|e| [e.start_point(), e.end_point()].iter().all(|p| (p.z - height).abs() < 1e-6));
	cyl.fillet_edges(radius, top_circle)
}

fn main() -> Result<(), Error> {
	let example_name = std::path::Path::new(file!()).file_stem().unwrap().to_str().unwrap();

	let result = [
		rounded_cube(8.0)?.color("#d0a878"),
		soft_top_cube(8.0)?.color("#6fbf73").translate(DVec3::X * 12.0),
		coin(4.0, 2.0)?.color("#0052ff").translate(DVec3::X * 24.0),
	];

	let mut f = std::fs::File::create(format!("{example_name}.step")).expect("failed to create STEP file");
	cadrum::Solid::write_step(&result, &mut f).expect("failed to write STEP");

	let mut f = std::fs::File::create(format!("{example_name}.svg")).expect("failed to create SVG file");
	cadrum::Solid::mesh(&result, 0.2).and_then(|m| m.write_svg(DVec3::new(1.0, 1.0, 2.0), DVec3::Z, true, true, &mut f)).expect("failed to write SVG");

	println!("wrote {example_name}.step / {example_name}.svg");
	Ok(())
}

• 10_fillet.step

Chamfer

Demo of Solid::chamfer_edges — mirror of 10_fillet.rs using bevels:

cargo run --example 11_chamfer

//! Demo of `Solid::chamfer_edges` — mirror of `10_fillet.rs` using bevels:
//! - All 12 cube edges chamfered uniformly (beveled cube)
//! - Only top 4 edges chamfered (soft top, sharp base)
//! - Cylinder top circular edge chamfered (coin with beveled rim)

use cadrum::{DVec3, Error, Solid};

fn beveled_cube(size: f64) -> Result<Solid, Error> {
	let cube = Solid::cube(size, size, size).translate(-DVec3::ONE * (size / 2.0));
	let distance = size * 0.2;
	cube.chamfer_edges(distance, cube.iter_edge())
}

fn beveled_top_cube(size: f64) -> Result<Solid, Error> {
	let cube = Solid::cube(size, size, size).translate(-DVec3::ONE * (size / 2.0));
	let distance = size * 0.2;
	// Top cap boundary: a closed circular edge whose start == end lives at z = h.
	let top_edges = cube
		.iter_edge()
		.filter(|e| [e.start_point(), e.end_point()].iter().all(|p| (p.z - size / 2.0).abs() < 1e-6));
	cube.chamfer_edges(distance, top_edges)
}

fn beveled_coin(radius: f64, height: f64) -> Result<Solid, Error> {
	let cyl = Solid::cylinder(radius, DVec3::Z, height);
	let distance = height * 0.3;
	// Top cap boundary: a closed circular edge whose start == end lives at z = h.
	let top_circle = cyl
		.iter_edge()
		.filter(|e| [e.start_point(), e.end_point()].iter().all(|p| (p.z - height).abs() < 1e-6));
	cyl.chamfer_edges(distance, top_circle)
}

fn main() -> Result<(), Error> {
	let example_name = std::path::Path::new(file!()).file_stem().unwrap().to_str().unwrap();

	let result = [
		beveled_cube(8.0)?.color("#d0a878"),
		beveled_top_cube(8.0)?.color("#6fbf73").translate(DVec3::X * 12.0),
		beveled_coin(4.0, 2.0)?.color("#0052ff").translate(DVec3::X * 24.0),
	];

	let mut f = std::fs::File::create(format!("{example_name}.step")).expect("failed to create STEP file");
	cadrum::Solid::write_step(&result, &mut f).expect("failed to write STEP");

	let mut f = std::fs::File::create(format!("{example_name}.svg")).expect("failed to create SVG file");
	cadrum::Solid::mesh(&result, 0.2).and_then(|m| m.write_svg(DVec3::new(1.0, 1.0, 2.0), DVec3::Z, true, true, &mut f)).expect("failed to write SVG");

	println!("wrote {example_name}.step / {example_name}.svg");
	Ok(())
}

• 11_chamfer.step

Features

• color (default): Colored STEP I/O via XDE. Enables write_step_with_colors, read_step_with_colors, and per-face color on Solid.
• source-build: Download and build OCCT from upstream sources via CMake. Enable this on triples without a published prebuilt.

Showcase

Try it now →

A browser-based configurator that lets you tweak dimensions of a STEP model and get an instant 3D preview and quote. cadrum powers the parametric reshaping and meshing on the backend.

Release Notes

0.7.5

Aggregated changes since 0.7.2 (no separate entries were written for 0.7.3 / 0.7.4).

• OCCT bumped to 8.0.0-beta1 ahead of the May 7 final release. Inherits upstream perf gains (STEP read up to ~75% faster vs 7.7) and the Shape-Healing / BRepFill_PipeShell crash fixes.
• Linux prebuilts are now self-contained (#147): libstdc++.a / libgcc.a / libgcc_eh.a are bundled into the tarball, so binaries linked against the prebuilt no longer depend on the host distro's libstdc++ runtime — fixes link-time __cxa_call_terminate undefined errors on Amazon Linux 2023 and other distros with older default GCC. Same self-contained guarantee that mingw already had since 0.7.2 (#89).
• x86_64-pc-windows-gnullvm prebuilt dropped. The prior "support" was a relabeled windows-gnu artifact, not a real llvm-mingw build. Use --features source-build or switch to the windows-gnu toolchain.
• I/O methods relocated to Solid impl (#145): Solid::write_step / write_brep_binary / write_brep_text / read_step / read_brep. The free-standing cadrum::write_* re-exports are gone. Breaking vs 0.7.4: cadrum::write_step(...) → Solid::write_step(...), etc.
• Edge::id() / Face::id() / Solid::id() (#142, #143): TShape-pointer-based identity exposed as a stable u64 for cross-shape correspondence (e.g. before/after boolean ops). Replaces the underscored tshape_id. Breaking for callers that named the old method.
• Face::iter_edge() -> impl Iterator<Item = &Edge> (#143): face-edge incidence query without going through the Solid boundary explorer.
• Face::project(point) (#142): closest-point + normal query on a face via BRepExtrema_DistShapeShape. Sibling to the existing Edge::project / Wire::project.
• C¹-periodic B-spline seam fix (#120): Solid::bspline(_, periodic=true) no longer emits a discontinuous U=0 seam — surfaces that previously showed dents at the seam now interpolate smoothly. Regression test in tests/bspline.rs.

0.7.2

Aggregated changes since 0.6.0 (no separate entries were written for 0.6.1 – 0.7.1).

• Solid::shell(thickness, open_faces) — hollow a solid via BRepOffsetAPI_MakeThickSolid. Empty open_faces produces a sealed internal void (cavity). Example: examples/08_shell.rs.
• Solid::fillet_edges(radius, edges) / Solid::chamfer_edges(distance, edges) — uniform fillet / chamfer on selected edges via BRepFilletAPI_MakeFillet / MakeChamfer.
• Solid::area() / Solid::center() / Solid::inertia() — surface area, center of mass, inertia tensor. Replaces the previous shell_count query.
• Wire::project(point) — closest-point + tangent query on Edge / Vec<Edge> / [Edge; N] via GeomAPI_ProjectPointOnCurve.
• Edge::end_point() / Edge::end_tangent() — added as siblings to the existing start_* accessors.
• Solid::iter_edge() / Solid::iter_face() — yield &Edge / &Face references through internal OnceLock caches; first call populates, subsequent calls are free.
• Solid::history + Solid::iter_history() — face-derivation pairs [post_id, src_id] populated by boolean ops and clean(). Lets callers select result faces by their original input membership.
• Multi-color STEP read recovery (#129). SolveSpace-style multi-color STEP files (which duplicate EDGE_CURVE entities at face boundaries instead of sharing them) used to land as Compound{Shell×N} with zero solids, breaking every downstream op. A BRepBuilderAPI_Sewing post-process now stitches coincident edges, promotes the result to one valid Solid, and remaps the colormap. The same STEP file is currently unfixable in CadQuery — see sandbox-cadquery/read_step_fillet.py.
• Mesh::write_svg / Mesh::to_svg gained up_dir: DVec3 between view: DVec3 and hidden_lines: bool (#127). Breaking vs 0.7.0: pass DVec3::Z to reproduce earlier output.
• Transform trait no longer in the public prelude (#91) — its methods reach you via Compound / Wire forwarders, so use cadrum::{Compound, Wire}; is enough for every transform call. Breaking vs 0.7.0 for code that imported Transform explicitly.
• *_with_metadata boolean variants removed (#130) — the same information is now available via Solid::iter_history() on the result solid. Breaking for callers that consumed the metadata tuple.
• glam types re-exported from the crate root (#94, #95) — downstream code no longer needs its own glam dependency for DVec3 etc.
• OCCT Statistics on Transfer stdout chatter silenced on every STEP read / write (#97).
• mingw prebuilt is now self-contained (#89): bundles the container's libstdc++.a / libgcc.a, so user-built x86_64-pc-windows-gnu executables do not depend on MinGW runtime DLLs at link time.
• docs.rs build restored (#107, #111): dropped the unsupported x86_64-pc-windows-msvc target and reordered build.rs so trait delegation generation runs before the DOCS_RS early-return.
• New example 08_shell.rs (hollow torus carved by halfspace-cut openings); old 08_bspline.rs renumbered to 09_bspline.rs. Top README image updated to the alphastell stellarator render (#125).

0.6.0

• source-build feature now gates cmake/walkdir as optional build-dependencies. Default cargo build no longer compiles them, significantly reducing build time on prebuilt targets. Users on unsupported targets must enable --features source-build (behavior unchanged — previously these targets also failed, just with a download error instead of a clear message).
• x86_64-pc-windows-gnu prebuilt added via Docker cross-compilation with Debian mingw-w64 (posix thread model). All MinGW runtime DLLs are statically absorbed — the resulting exe depends only on Windows OS DLLs.
• LGPL 2.1 §2 compliance: source builds now retain only the ~9 patched OCCT source files alongside the .a libraries, removing the unmodified bulk (~88 MB of data/dox/tests). The patched files carry timestamped headers per §2(a).
• OCCT_ROOT relative path handling fixed: resolved via env::current_dir() instead of the unreliable CARGO_TARGET_DIR heuristic. --target <triple> flag now works correctly.
• build.rs restructured: resolve_occt uses match chains with #[cfg] for source-build vs prebuilt paths. Source-build code lives in #[cfg(feature = "source-build")] mod source. patch_occt_sources split into walk_occt_sources + patch_or_none (side-effect-free).
• README simplified: Build section moved after Usage with a prebuilt target table + OS icons.

0.5.1

0.4.5 was published briefly but its version number was lower than the already-published 0.5.0 (OCCT 7.9.3, older feature set), so cargo add cadrum would silently pick up 0.5.0 instead of the newer 0.4.5 code. Re-released as 0.5.1 with identical contents. Prefer 0.5.1 over 0.4.5.

• Solid::bspline<const M, const N>(grid, periodic) — new constructor: build a periodic B-spline solid from a 2D control-point grid. V (cross-section) is always periodic; U (longitudinal) is controlled by the periodic flag (torus when true, capped pipe when false). Implemented via GeomAPI_PointsToBSplineSurface::Interpolate over an augmented grid plus SetUPeriodic/SetVPeriodic.
• write_svg / Mesh::to_svg now take shading: bool — opt-in Lambertian shading with head-on light. When true, triangles are tinted by 0.5 + 0.5 * (normal · dir) so curved/organic shapes read clearly; false reproduces the pre-0.5.1 flat rendering. Breaking vs 0.5.0: existing callers must add the flag (pass false to preserve earlier output).
• examples/08_bspline.rs rewritten: 2 field-period stellarator-like torus with twisted + vertically undulating elliptic cross-sections, exercising Solid::bspline and shading=true.
• tests/bspline.rs added: verifies 180° point symmetry of the stellarator shape via XZ/YZ half-space intersection (s1 ≈ s3, s2 ≈ s4).
• Error::BsplineFailed(String) new variant. Breaking for downstream code that does exhaustive match on Error.
• OCCT 8.0.0 deprecation warnings resolved in make_bspline_edge and make_bspline_solid (NCollection_HArray1<gp_Pnt> via local using alias to bypass the Handle() macro comma-splitting issue; NCollection_Array2<gp_Pnt> directly).

License

This project is licensed under the MIT License.

Compiled binaries include OpenCASCADE Technology (OCCT), which is licensed under the LGPL 2.1. Users who distribute applications built with cadrum must comply with the LGPL 2.1 terms. Since cadrum builds OCCT from source, end users can rebuild and relink OCCT to satisfy this requirement.