m3dscad

Language Overview

m3dscad uses an OpenSCAD-like syntax with expression evaluation, user-defined symbols, and block-based geometry composition.

Calls And Modifiers

Function/module calls use parentheses. Modifiers like translate() can wrap a single call directly or a block of children.

sphere(r=1);
translate([2, 0, 0]) sphere(r=1);

translate([0, 0, 3]) {
  sphere(r=1);
}

Variables

Variables are assigned with = and then referenced in later expressions.

radius = 1.5;
height = 4;

cylinder(r=radius, h=height, center=true);

Functions

User-defined functions return a single expression and can be used in parameters and other expressions.

function ring_r(base, wall) = base - wall;

difference() {
  cylinder(h=2, r=2);
  cylinder(h=2, r=ring_r(2, 0.4));
}

Anonymous Functions

Anonymous functions are expression values created with function(...). They can be assigned, passed to functions, returned, and called later.

add3 = function(x) x + 3;
echo(add3(2));

selector = function(which)
  which == "add"
  ? function(x) x + x + 1
  : function(x) x * x + 1;

echo(selector("add")(5));

Modules

User-defined modules package reusable geometry statements.

module post(z, r=0.6) {
  translate([0, 0, z]) sphere(r=r);
}

post(0);
post(3);

If / Else

Conditionals choose which branch of geometry to evaluate. Note that they introduce their own scope, so assignments cannot escape.

use_big = true;

if (use_big)
  sphere(r=2);
else
  sphere(r=1);

For Loops

for loops iterate ranges/lists and emit geometry each iteration.

for (i = [0:3])
  translate([i * 3, 0, 0]) sphere(r=1);

List Comprehension

List comprehensions build arrays from iteration expressions, which can then be indexed or reused.

values = [for (a = [1:4]) a * a];
radius = values[2];

sphere(r=radius);

3D Primitives

sphere

Creates a sphere solid centered at the origin.

sphere(r=1)
  • r: Sphere radius.

sphere_metaball

Creates a spherical metaball field contribution.

sphere_metaball(r=1)
  • r: Sphere radius.

sphere_sdf

Creates a sphere represented as an SDF.

sphere_sdf(r=1)
  • r: Sphere radius.

cube

Creates an axis-aligned box solid.

cube(size=1, center=false)
  • size: Edge length or per-axis size vector.
  • center: If true, centers the cube at the origin.

cube_metaball

Creates an axis-aligned box as a metaball primitive.

cube_metaball(size=1, center=false)
  • size: Edge length or per-axis size vector.
  • center: If true, centers the box at the origin.

cube_sdf

Creates an axis-aligned box represented as an SDF.

cube_sdf(size=1, center=false)
  • size: Edge length or per-axis size vector.
  • center: If true, centers the box at the origin.

cylinder

Creates a cylinder, cone, or frustum solid along the Z axis.

cylinder(h=1, r | d | r1/r2 | d1/d2, center=false)
  • h: Height along Z.
  • r: Uniform radius for both ends.
  • d: Uniform diameter for both ends.
  • r1: Radius at the first end (low Z if not centered).
  • r2: Radius at the second end (high Z if not centered).
  • d1: Diameter at the first end.
  • d2: Diameter at the second end.
  • center: If true, centers height around Z=0.

cylinder_metaball

Creates a cylinder-family primitive as a metaball.

cylinder_metaball(h=1, r | d | r1/r2 | d1/d2, center=false)
  • h: Height along Z.
  • r: Uniform radius for both ends.
  • d: Uniform diameter for both ends.
  • r1: Radius at the first end.
  • r2: Radius at the second end.
  • d1: Diameter at the first end.
  • d2: Diameter at the second end.
  • center: If true, centers height around Z=0.

cylinder_sdf

Creates a cylinder-family primitive as an SDF.

cylinder_sdf(h=1, r | d | r1/r2 | d1/d2, center=false)
  • h: Height along Z.
  • r: Uniform radius for both ends.
  • d: Uniform diameter for both ends.
  • r1: Radius at the first end.
  • r2: Radius at the second end.
  • d1: Diameter at the first end.
  • d2: Diameter at the second end.
  • center: If true, centers height around Z=0.

capsule

Creates a capsule solid with hemispherical end caps.

capsule(h=1, r=1, center=false)
  • h: Distance between cap centers along Z.
  • r: Capsule radius.
  • center: If true, centers the capsule around Z=0.

capsule_metaball

Creates a capsule as a metaball primitive.

capsule_metaball(h=1, r=1, center=false)
  • h: Distance between cap centers along Z.
  • r: Capsule radius.
  • center: If true, centers the capsule around Z=0.

capsule_sdf

Creates a capsule represented as an SDF.

capsule_sdf(h=1, r=1, center=false)
  • h: Distance between cap centers along Z.
  • r: Capsule radius.
  • center: If true, centers the capsule around Z=0.

line_join

Creates a rounded 3D tube-like solid around a polyline path.

line_join(points, r=1, norm="l2")
  • points: List of 3D points [[x, y, z], ...] (at least two points).
  • r: Join radius (non-negative).
  • norm: Distance norm, either "l2" (euclidean) or "l1" (manhattan).
line_join(points=[[0,0,0], [2,0,0], [2,2,0]], r=0.25, norm="l2");

fn_solid

Creates a 3D solid by evaluating a function over bounded 3D coordinates.

fn_solid(min, max, fn)
  • min: 3D minimum corner vector [x, y, z].
  • max: 3D maximum corner vector [x, y, z].
  • fn: Function taking one coordinate vector [x, y, z] and returning bool.
fn_solid([-1,-1,-1], [1,1,1], function(c) norm(c) <= 1);

2D Primitives

circle

Creates a circle solid centered at the origin.

circle(r=1)
  • r: Circle radius.

circle_metaball

Creates a circle as a 2D metaball primitive.

circle_metaball(r=1)
  • r: Circle radius.

circle_sdf

Creates a circle represented as a 2D SDF.

circle_sdf(r=1)
  • r: Circle radius.

circle_hull

Creates a 2D convex-hull input primitive from a circle. Combine multiple hull primitives with union(), then convert the result with hull_solid() or hull_sdf().

circle_hull(r=1)
  • r: Circle radius. Use r=0 to contribute a point to the convex hull instead of a rounded circle.
  • behavior: Positive radii create a rounded arc hull; if all contributing radii are zero, the hull becomes the ordinary convex hull of the circle centers.

teardrop

Creates a centered 2D teardrop solid.

teardrop(radius=1)
  • radius (or r): Teardrop radius.

The tip direction is fixed to positive Y. Use rotate() to orient it differently.

square

Creates an axis-aligned rectangle solid in 2D.

square(size=1, center=false)
  • size: Edge length or per-axis size vector.
  • center: If true, centers the rectangle at the origin.

square_metaball

Creates an axis-aligned rectangle as a 2D metaball primitive.

square_metaball(size=1, center=false)
  • size: Edge length or per-axis size vector.
  • center: If true, centers the rectangle at the origin.

square_sdf

Creates an axis-aligned rectangle represented as a 2D SDF.

square_sdf(size=1, center=false)
  • size: Edge length or per-axis size vector.
  • center: If true, centers the rectangle at the origin.

fn_solid (2D)

Creates a 2D solid from a boolean function over 2D coordinates.

fn_solid(min, max, fn)
  • min: 2D minimum corner vector [x, y].
  • max: 2D maximum corner vector [x, y].
  • fn: Function taking one coordinate vector [x, y] and returning bool.
fn_solid([-1,-1], [1,1], function(c) c.x*c.x + c.y*c.y <= 1);

polygon

Creates a 2D polygon solid from points and optional path indices.

polygon(points, paths, convexity=1)
  • points: Vertex list used by the polygon.
  • paths: Optional index list(s) describing outer ring and holes.
  • convexity: Compatibility parameter (currently unused for evaluation behavior).

polygon_mesh

Creates a 2D polygon boundary mesh from points and optional path indices.

polygon_mesh(points, paths, convexity=1)
  • points: Vertex list used by the polygon.
  • paths: Optional index list(s) describing contours.
  • convexity: Compatibility parameter (currently unused for evaluation behavior).

polygon_sdf

Creates a polygon as a 2D SDF by converting polygon mesh to SDF.

polygon_sdf(points, paths, convexity=1)
  • points: Vertex list used by the polygon.
  • paths: Optional index list(s) describing contours.
  • convexity: Compatibility parameter (currently unused for evaluation behavior).

polygon_hull

Creates a 2D convex-hull input from polygon vertices. This is equivalent to using circle_hull(r=0) at each exterior vertex, then converting the combined hull with hull_solid() or hull_sdf().

polygon_hull(points, paths, convexity=1)
  • points: Vertex list used by the polygon hull.
  • paths: Optional index list(s). Only the first path is used; interior holes are ignored for hull construction.
  • convexity: Compatibility parameter (currently unused for evaluation behavior).

hull_solid

Converts a 2D hull input into a solid. Hull inputs are typically built from circle_hull(), polygon_hull(), or mesh_to_hull().

hull_solid() { hull2d }
  • children: 2D hull child geometry.
  • behavior: Rounded hull circles produce an arc hull; all-zero radii produce the ordinary convex hull of the contributing points.

hull_sdf

Converts a 2D hull input into an SDF.

hull_sdf() { hull2d }
  • children: 2D hull child geometry.
  • behavior: Uses the same hull construction rules as hull_solid(), but preserves SDF output for downstream operations.

path

Parses an SVG path and creates a solid from its sampled curve mesh.

path(path, segments=1000)
  • path: SVG path string.
  • segments: Number of line segments used for curve sampling.

path_mesh

Parses an SVG path and returns the sampled 2D mesh.

path_mesh(path, segments=1000)
  • path: SVG path string.
  • segments: Number of line segments used for curve sampling.

path_sdf

Parses an SVG path and returns a 2D SDF.

path_sdf(path, segments=1000)
  • path: SVG path string.
  • segments: Number of line segments used for curve sampling.

text

Creates filled 2D glyph outlines using the embedded Liberation Sans font.

text(text, size=10, font="Liberation Sans", halign="left", valign="baseline", spacing=1, segments=8)
  • text: Input text content to render.
  • size: Font size scale.
  • font: Font name; currently only Liberation Sans regular is supported.
  • halign: Horizontal alignment (left, center, right).
  • valign: Vertical alignment (baseline, top, center, bottom).
  • spacing: Additional spacing multiplier between glyphs.
  • segments: Curve tessellation segments per glyph curve.

text_mesh

Creates text outlines as a 2D mesh using the embedded Liberation Sans font.

text_mesh(text, size=10, font="Liberation Sans", halign="left", valign="baseline", spacing=1, segments=8)
  • text: Input text content to render.
  • size: Font size scale.
  • font: Font name; currently only Liberation Sans regular is supported.
  • halign: Horizontal alignment (left, center, right).
  • valign: Vertical alignment (baseline, top, center, bottom).
  • spacing: Additional spacing multiplier between glyphs.
  • segments: Curve tessellation segments per glyph curve.

CSG

union

Combines child shapes of the same kind into one shape.

union() { ... }
  • children: One or more child shapes; all children must share the same shape kind.

difference

Subtracts the union of later children from the first child.

difference() { a; b; ... }
  • children: At least one child shape; first is minuend, rest are subtrahends.

intersection

Keeps only the volume/area shared by all children.

intersection() { ... }
  • children: One or more child shapes of the same kind.

Transforms And Extrusion

translate

Moves child geometry by a translation vector.

translate(v=[0,0,0]) { child }
  • v: Translation vector; for 2D children, Z must be 0.
  • children: Exactly one child branch (or multiple children that union first).

scale

Scales child geometry per axis.

scale(v=[0,0,0]) { child }
  • v: Scale vector; for 2D children, Z must be 0.
  • children: Exactly one child branch (or multiple children that union first).

rotate

Rotates child geometry using Euler angles or axis-angle form.

rotate(a, v) { child }
  • a: Either a scalar angle (degrees) or a 3-angle vector.
  • v: Optional axis vector for axis-angle mode.
  • children: Exactly one child branch (or multiple children that union first).

mirror

Reflects child geometry across the hyperplane orthogonal to a given axis.

mirror(v) { child }
  • v: Mirror axis vector. It need not be normalized, but it must be non-zero; for 2D children, Z must be 0.
  • children: Exactly one child branch (or multiple children that union first).

transform

Applies a user-defined coordinate map to solid, SDF, or mesh children.

transform(min, max, fn) { solid_or_sdf }
transform(fn) { mesh }
  • min, max: Required bounds for solid/SDF output; vectors must match child dimensionality (2D or 3D).
  • fn: Mapping function. For solids/SDFs, maps outer coordinates to inner coordinates; for meshes, maps old mesh coordinates to new coordinates.
  • children: Solid, SDF, or mesh child geometry to transform.

linear_extrude

Extrudes 2D geometry along Z, with optional twist and scale.

linear_extrude(height=1, center=false, twist=0, scale=1) { child2d }
  • height: Extrusion distance; alias h.
  • center: If true, centers extrusion around Z=0.
  • twist: Total twist in degrees across extrusion height.
  • scale: End scale factor (scalar or 2D vector).
  • children: 2D child geometry to extrude.

inset_extrude

Extrudes a 2D SDF along Z while applying inset or outset shaping at the top and bottom.

inset_extrude(height=1, center=false, bottom=0, top=0, bottom_fn="chamfer", top_fn="chamfer") { sdf2d }
  • height: Extrusion distance; alias h.
  • center: If true, centers extrusion around Z=0.
  • bottom: Bottom inset radius. Negative values produce an outset instead.
  • top: Top inset radius. Negative values produce an outset instead.
  • bottom_fn: Bottom profile function, either "chamfer" or "fillet". Defaults to "chamfer".
  • top_fn: Top profile function, either "chamfer" or "fillet". Defaults to "chamfer".
  • children: 2D SDF child geometry to extrude.

rotate_extrude

Revolves 2D solid geometry around the Z axis. For SDF children, a full 360-degree revolve preserves SDF output.

rotate_extrude(angle=360, start=0) { child2d }
  • angle: Sweep angle in degrees.
  • start: Start angle in degrees.
  • children: 2D solid or 2D SDF child geometry to revolve.
  • SDF behavior: SDF children require a full 360-degree sweep; partial sweeps are unsupported.

Meshing And SDF

marching_squares

Converts a 2D solid into a mesh using marching squares search.

marching_squares(delta=0.02, subdiv=8) { child2d }
  • delta: Grid spacing for contour extraction.
  • subdiv: Search subdivisions per cell.
  • children: 2D solid child geometry to mesh.

marching_cubes

Converts a 3D solid into a mesh using marching cubes search.

marching_cubes(delta=0.02, subdiv=8) { child3d }
  • delta: Grid spacing for surface extraction.
  • subdiv: Search subdivisions per cell.
  • children: 3D solid child geometry to mesh.

dual_contour

Converts a 3D solid into a mesh using dual contouring.

dual_contour(delta=0.02, repair=true, clip=false) { child3d }
  • delta: Cell size for contouring.
  • repair: Enables additional mesh repair pass.
  • clip: Enables clipping behavior in contouring.
  • children: 3D solid child geometry to mesh.

mesh_to_sdf

Converts a 2D or 3D mesh to an SDF of matching dimensionality.

mesh_to_sdf() { mesh }
  • children: Mesh child geometry to convert.

mesh_to_hull

Converts a 2D mesh into a convex-hull input by using each mesh vertex as a zero-radius hull point.

mesh_to_hull() { mesh2d }
  • children: 2D mesh child geometry.
  • behavior: The resulting hull can be turned into geometry with hull_solid() or hull_sdf().

inset_sdf

Shrinks an SDF shape by an inward field offset.

inset_sdf(delta) { sdf }
  • delta: Inset amount.
  • children: SDF child geometry.

outset_sdf

Expands an SDF shape by an outward field offset.

outset_sdf(delta) { sdf }
  • delta: Outset amount.
  • children: SDF child geometry.

solid

Converts child mesh/SDF geometry back to solid representation.

solid() { child }
  • children: Child geometry to convert to solid.

Metaball

metaball

Converts an SDF into metaball form.

metaball() { sdf }
  • children: SDF child geometry to convert.

weight_metaball

Scales metaball weights during metaball composition.

weight_metaball(weight) { metaball }
  • weight: Multiplier for all child metaball weights (for negation, use -1).
  • children: Exactly one metaball child to scale.

metaball_solid

Combines weighted metaballs into a solid using a thresholded falloff field.

metaball_solid(threshold, falloff="quartic") { metaballs... }
  • threshold: Isosurface threshold for solid extraction.
  • falloff: Falloff kernel name (linear, quadratic, cubic, quartic, quintic, exponential, gaussian).
  • children: One or more metaball child primitives.