Kerf language reference

module material(name = "default", thickness = 3, color = "wood", opacity = 1, kerf = 0.1, sheet = [600, 400], margin = 5, gap = 3)

Defines (or changes) a material. Later calls with the same name update only the settings they give. Without any material() call, parts use a 3 mm default.

material("ply3", thickness = 3, color = "wood", kerf = 0.12, sheet = [300, 300]);

module part(name = "part", material = undef, qty = 1, thickness = undef, center = false, color = undef)

Makes its 2D children into one cut part. Transforms outside the part place it in 3D; the part lies on z = 0 to thickness before that. Holes are anything subtracted with difference().

translate([0, 0, 20]) part("lid", "ply3", qty = 2) difference() {
  square([80, 60]);
  translate([40, 30]) circle(d = 10);
}

function thickness(material)

A material's thickness in mm.

t = thickness("ply3");

function kerf(material)

A material's kerf (laser cut width) in mm.

function sheet_size(material)

The usable area of one sheet: [w, h] minus the margins.

module engrave()

Fill-engraves the children's areas (exported as black fill). Lines inside become scores.

part("tag", "ply3") {
  square([40, 15]);
  engrave() translate([20, 7.5]) text("HELLO", size = 8, halign = "center", valign = "center");
}

module score()

Line-engraves the outlines of the children without cutting (exported as blue lines).

module cut()

Cuts the children's outlines as lines without making them holes, e.g. a cut line through a living hinge.

module line(points, closed = false)

An open line (not an area). Cut inside a part, or scored inside engrave()/score().

part("card", "ply3") {
  square([40, 20]);
  score() line([[5, 10], [20, 15], [35, 10]]);   // a scored fold line
}

module image(file, width = undef, height = undef, dpi = 300, center = false)

A bitmap to engrave (embedded in the exported SVG). Give width or height and the other follows the image's shape.

engrave() image("photo.png", width = 50);

module square(size = 1, center = false)

A rectangle with its corner at the origin.

module circle(r = 1, d = undef)

A circle centred on the origin.

circle(d = 3.2);

module polygon(points, paths = undef)

A polygon from points. With paths, the first path is the outline and the rest are holes.

module text(text, size = 10, font = "Liberation Sans", halign = "left", valign = "baseline", spacing = 1)

Text as outlines. Bundled fonts and .ttf/.otf files in the project both work.

module import(file, center = false)

Shapes from an SVG file. Closed paths fill even-odd (like most drawing programs); open paths become lines.

function round_corners(points, r = 0)

A closed path (list of points) with its corners rounded. A radius too big for its edges is reduced, with a warning.

polygon(round_corners([[0, 0], [60, 0], [60, 40], [0, 40]], [0, 10, 10, 0]));

module translate(v = [0, 0, 0])

Moves the children.

module rotate(a = 0, v = undef)

Rotates the children. A single number rotates about z.

module scale(v = 1)

Scales the children.

module mirror(v = [1, 0, 0])

Mirrors the children across the plane through the origin with normal v.

module multmatrix(m)

Applies a 4 × 4 (or 3 × 4) transformation matrix.

module resize(newsize = [0, 0], auto = false)

Scales 2D children to an exact size.

module offset(r = undef, delta = undef, chamfer = false)

Grows (positive) or shrinks (negative) 2D shapes.

offset(r = 2) square([20, 10]);

module color(c, alpha = 1)

Colour of the children in the 3D view (parts and reference solids). Doesn't affect the export.

module union()

Merges the children into one shape. Shapes inside a part are merged anyway.

module difference()

The first child minus all the others: how holes are made.

module intersection()

Only the area all the children share.

module hull()

The convex hull of the children: like a rubber band around them.

hull() { circle(5); translate([30, 0]) circle(8); }

module minkowski()

Minkowski sum of the children: traces the second shape around the first (rounds a square with a circle).

module group()

Groups children without changing them.

module render()

Accepted for OpenSCAD compatibility; does nothing.

module children(index = undef)

Inside a module: the children it was called with.

module cube(size = 1, center = false)

A box with its corner at the origin.

module cylinder(h = 1, r = 1, d = undef, r1 = r, r2 = r1, d1 = undef, d2 = undef, center = false)

A cylinder (or cone) standing on z = 0.

module sphere(r = 1, d = undef)

A sphere centred on the origin.

module flex_plate(path, t, lip = 0, fw = 12, sag = 0.1, margin = 3, max_len = undef)

Bottom or top plate: the outline with notches for the wall's fingers (lip = 0, flush) or slots they poke through (lip > 0).

module flex_panel(path, height, t, panel = 0, top = true, fw = 12, sag = 0.1, margin = 3, max_len = undef, pitch = 1.5, seg = 18, bridge = 3)

One flat wall panel: fingers along the bottom (and top) edges, hinge cuts where it bends, finger corners at sharp corners.

module flex_bend(path, t, panel = 0, fw = 12, sag = 0.1, margin = 3, max_len = undef)

Shows a flat panel part bent into place in 3D, and fit-checks it bent. It is still laid out and cut flat. Wrap it around the part.

for (i = [0 : flex_count(shape, t) - 1])
  flex_bend(shape, t, i) part(str("wall", i), "ply3") flex_panel(shape, 60, t, i);

function flex_count(path, t, fw = 12, sag = 0.1, margin = 3, max_len = undef)

How many wall panels the outline needs.

function flex_lengths(path, t, fw = 12, sag = 0.1, margin = 3, max_len = undef)

The flat length of each wall panel, for planning sheets.

module echo()

Prints values to the console: echo(w = w) prints w = 40.

module assert(condition, message = undef)

Stops with an error if the condition is false.

assert(w > 2 * t, "too narrow");

function abs(x)

Absolute value.

function sign(x)

-1, 0 or 1.

function floor(x)

Round down.

function ceil(x)

Round up.

function round(x)

Round to the nearest whole number (halves away from 0).

function sqrt(x)

Square root.

function exp(x)

e to the power x.

function ln(x)

Natural logarithm.

function log(x)

Base-10 logarithm.

function pow(base, exponent)

base to the power exponent (also base ^ exponent).

function sin(a)

Sine of an angle in degrees. Also cos, tan.

function cos(a)

Cosine of an angle in degrees.

function tan(a)

Tangent of an angle in degrees.

function asin(x)

Inverse sine, in degrees. Also acos, atan.

function acos(x)

Inverse cosine, in degrees.

function atan(x)

Inverse tangent, in degrees.

function atan2(y, x)

Angle of the point [x, y] in degrees (note the order: y first).

function min(values…)

Smallest of the arguments, or of one list.

function max(values…)

Largest of the arguments, or of one list.

function norm(v)

Length of a vector.

function cross(a, b)

Cross product (a number for 2D vectors).

function len(v)

Number of items in a list, or characters in a string.

function concat(lists…)

Joins lists into one list.

function lookup(key, table)

Interpolates in a table of [key, value] rows sorted by key.

echo(lookup(2.5, [[0, 0], [10, 100]]));   // 25

function rands(lo, hi, n, seed = undef)

A list of n random numbers between lo and hi. With a seed, the same every time.

function str(values…)

Joins values into a string.

part(str("wall", i), "ply3") …

function chr(codes…)

Characters from character codes.

function ord(s)

Character code of the first character.

function is_undef(v)

True if the value is undef. Also is_num, is_bool, is_string, is_list, is_function.

function is_num(v)

True if the value is a number.

function is_bool(v)

True if the value is a boolean.

function is_string(v)

True if the value is a string.

function is_list(v)

True if the value is a list.

function is_function(v)

True if the value is a function.

function version()

Kerf's version as [year, month, n].

module rounded_square(size, r = 2, center = false)

A rectangle with rounded corners.

module ngon(n, r)

A regular polygon centred on the origin, with a corner on +x.

module slot(len, w)

A slot with round ends, centred on the origin, running along x.

function finger_count(len, w = 10)

Odd number of fingers that fit len with fingers about w wide.

module finger_tabs(len, t, n = undef, odd = true, w = 10)

Tabs along the x axis from 0..len, t deep (y = 0..t). The edge is split into n segments and every other one is kept. Two mating edges use the same len and n and opposite odd.

module finger_slots(len, t, n = undef, odd = true, w = 10)

Slots through a panel for tabs of another panel crossing it (a "tab and slot" joint away from the edge). Slots run along x from 0..len, t wide, centred on y = 0. Use odd/n matching the tabs.

module tslot(d = 3, len = 12, nut_w = 5.5, nut_t = 2.4, nut_at = 6)

T-slot for a captive nut + bolt, cut into an edge. The edge lies on y = 0 and the slot goes inward along +y. Subtract it from the panel.

module tslot_hole(d = 3)

Matching bolt hole for a T-slot in the panel it screws through.

module living_hinge(w, h, pitch = 1.5, seg = 18, bridge = 3)

Straight-line living hinge: cut lines parallel to y across a w × h area so the sheet bends around an axis parallel to y. The flex.kerf boxes lay these out for you.

module hole_grid(cols, rows, pitch, d)

A grid of round holes (subtract it), handy for vents and speaker grilles. The first hole is centred on the origin.

module face_y(t)

Stands a flat part up so its local +y becomes world +z, facing -y. Local x stays world x; its thickness occupies y = 0..t.

module face_x(t)

Stands a flat part up so its local +y becomes world +z, facing +x. Local x runs along world +y; its thickness occupies x = 0..t.

module fj_panel(w, h, t, edges = [1, 2, 0, 2], fw = 12)

One flat panel w × h with finger-jointed edges. Two mating edges: one 1, the other 2.

module box_panel(which, size, t, top = "open", fw = 12)

The 2D outline of one panel of a standard box (top = "lid" gives the walls of an open box). Front/back own the vertical corners; bottom/top own their corners.

module box_place(which, size, t)

Put a part where a panel goes in a box of size with its outside corner at the origin. Walls face outward: the side you engrave ends up outside. Front/back panels are size.x wide; left/right run along y (local x = y for "right", reversed for "left", so text reads correctly from outside).

function box_outside(size, t, top = "open")

Outside size of a box from its inside size.

module finger_box(size, material, top = "open", inside = false, fw = 12, gap = 0.3, label = "", font = "Liberation Sans:style=Bold", label_size = 10, name = "box")

A whole box as parts named <name>_bottom, <name>_front, ..., placed in 3D with the outside corner at the origin.

function bend_length(angle, r, t)

Length of living hinge needed to bend a sheet of thickness t through angle degrees around an inside radius r.

module pivot_ear(at, r, d, a, b)

A round ear with a pin hole at at, joined to the straight edge from a to b (two points on the panel's outline). Union it with the panel.

module hinged_box(size, material, lid_h = 20, pin_d = 3.2, knuckle = undef, gap = 0.5, fw = 12, open = 0, label = "", font = "Liberation Sans:style=Bold", label_size = 12, name = "box")

Box with a lid that swings open on two pins (dowel, filament, M3 bolt...). The lid is a shallow upside-down box, slightly wider than the body, whose sides hang over the body's sides at the back. Both have ears behind the box with a pin hole; the pivot is knuckle mm behind the back and below the rim, which lets the lid open past 90° without hitting anything. Parts: <name>_bottom/_front/_back/_left/_right, <name>_lid_top/_lid_front/...

function gear_pitch_r(teeth, mod = 2)

where the gears roll on each other

function gear_outer_r(teeth, mod = 2)

tooth tips

function gear_root_r(teeth, mod = 2)

bottom of the gaps

function gear_distance(t1, t2, mod = 2)

centre distance for meshing

function gear_ratio(t1, t2)

turns of gear 1 per turn of gear 2

function gear_mesh_angle(t1, t2, a1 = 0, dir = 0)

Rotation for gear 2 so its teeth fall between gear 1's. Gear 1 sits at the origin turned by a1; gear 2 sits in direction dir (degrees) from it. Turning gear 1 by a1 turns gear 2 the other way by a1 * t1 / t2.

module gear_mesh(t1, t2, mod = 2, a1 = 0, dir = 0, extra = 0)

Place children (gear 2, t2 teeth) meshing with a t1-tooth gear at the origin. Works for flat shapes and for parts. extra = added centre distance.

module gear(teeth, mod = 2, pressure_angle = 20, backlash = 0.1, bore = 0, flat = 0, steps = 8)

Spur gear outline, centred on the origin.

module rack(teeth, mod = 2, pressure_angle = 20, backlash = 0.1, base = 5)

Straight rack along +x starting at x = 0, pitch line on y = 0, teeth up, base mm of solid strip under the tooth roots. Place a gear on it with on_rack().

module on_rack(teeth, mod = 2, k = 1, extra = 0)

Place children (a gear with teeth teeth) meshing with a rack, its centre above the rack's k-th gap.

function rounded_rect(size, r)

A rounded-rectangle path with its corner at the origin, to use as a box's outline.

module flex_box(path, height, material, top = "closed", lip = 0, fw = 12, sag = 0.1, pitch = 1.5, seg = 18, bridge = 3, margin = 3, max_len = undef, label = "", font = "Liberation Sans:style=Bold", label_size = 10, name = "flex")

Whole box: <name>_bottom, <name>_top (unless top = "open") and the walls <name>_wall (or _wall1, _wall2, … when sharp corners split them), placed in 3D with the bottom on z = 0. height is the outside height. Walls too long for the material's sheet are split (see max_len above).