Foremka scripting language reference

A script builds the model the same way the interface does: every function is one operation in the history. Run on an empty document it rebuilds the model from scratch; run on an existing one it appends operations at the end.

Basics

# comment to end of line

thickness = 12          # variable
side = param("side", 40)  # document parameter, returns its value

b = box([80, 20, 40])          # positional argument
fillet(edges(b), radius: 3)    # named argument after a colon

Numbers may carry a unit: 12mm, 2.5cm, 1in, 30deg, 1.57rad. Without a unit, lengths are millimetres and angles are degrees.

A sketch point is [x, y], a point or vector in space is [x, y, z]. Vectors add and scale: [10, 0, 0] * 2.

World

Up is Y, not Z. The constant up is [0, 1, 0], down is [0, -1, 0], axes are x_axis, y_axis, z_axis. Base planes are plane.xy (horizontal, normal up), plane.yz and plane.xz (both vertical). A sketch on plane.xy therefore extrudes upwards, and box([80, 20, 40]) is 20 mm tall.

Control flow

if thickness > 10 {
  print("thick")
} else {
  print("thin")
}

for i in range(0, 5) {
  hole(face(b, "top"), at: [10 + i * 15, 20], diameter: 5)
}

def rib_height(length) {
  return length / 3
}

Operators: + - * / % ^, comparisons < > <= >= == !=, and and, or, not.

Three things worth knowing

1. Bodies are results of operations. b = extrude(sk, 10) yields a body and b = fillet(edges(b), 2) replaces it with the rounded one. An older variable still works: references follow the current shape of the body.

2. Geometry is picked by description, not by number. Instead of remembering edge number seven you write edges(b, dir: up) or faces(b, kind: "cylinder", diameter: 6). Such a query survives a change of dimensions; an index does not.

3. A sketch has its own coordinate system. [0, 0] is its origin, also when it lies on a face of a body. An extrusion goes perpendicular to the sketch.

Example

thickness = param("thickness", 12)

plate = sketch(plane.xy) {
  rect(center: [0, 0], width: 120, height: 80)
}
b = extrude(plate, thickness)
b = fillet(edges(b, dir: up), 8)
b = shell(b, 2, openings: faces(b, side: "top"))

for i in range(0, 4) {
  b = hole(face(b, "bottom"), at: [-45 + i * 30, 0], diameter: 5, depth: 6)
}
name(b, "Base")

Functions

Parameters

param

Stores a document parameter and returns its value. Dimensions built from that value, also computed from it (w / 2 + 3), are bound to the parameter and recompute when it changes in the parameters panel: primitive sizes and positions, extrude distances, revolve angles, fillet radii, thicknesses, patterns, sketch dimensions and the points of lines, rectangles, circles and polylines.

Returns: number: the resolved parameter value.

grubosc = param("grubosc", 12)
kat = param("pochylenie", 3, unit: "deg")
bok = param("bok", "grubosc * 4")

Sketch

arc

An arc through three points: start, end and a point lying on the arc.

Returns: sketch entity.

arc([0, 0], [20, 0], [10, 6])

arc_center

An arc about the given centre, from the start point to the end point, counter-clockwise.

Returns: sketch entity.

center

Centre of a circle or an arc.

Works only inside a sketch block.

Returns: sketch point.

chamfer_2d

Cuts the corner between two sketch lines.

Works only inside a sketch block.

Returns: nothing.

circle

A circle about the given centre. The size is given by a radius or a diameter.

Returns: sketch entity.

circle([0, 0], diameter: 20)
circle([10, 10], 5)

circle_2pt

A circle through two points lying at the ends of a diameter.

Returns: sketch entity.

circle_3pt

A circle passing through three points.

Returns: sketch entity.

construction

Switches drawing to construction geometry and back. Holds until the end of the sketch block.

Works only inside a sketch block.

Returns: nothing.

construction(true)
line([0,0], [50,0])
construction(false)

end

End point of a line, an arc or a curve.

Works only inside a sketch block.

Returns: sketch point.

fillet_2d

Rounds the corner between two sketch entities.

Works only inside a sketch block.

Returns: nothing.

intersect_curves

Inserts the curves and points where the given geometry crosses the sketch plane.

Works only inside a sketch block.

Returns: list of entities.

intersect_curves(b)
intersect_curves(faces(b, kind: "cylinder"))

A face and a body give section curves, an edge and an axis a piercing point, a plane a common line. Geometry that does not touch the sketch plane is an error, because a quietly empty result would hide a mistake in the script.

line

A segment between two sketch points.

Returns: sketch entity.

a = line([0, 0], [80, 0])

mirror_curves

Mirrors the given entities about a sketch line and ties the copies with a symmetry constraint.

Works only inside a sketch block.

Returns: number: how many entities were mirrored.

offset_curves

Offsets the given curves by a distance, creating a parallel contour.

Works only inside a sketch block.

Returns: list of entities.

offset_curves(kontur, 3)

pattern_rect

A grid pattern in the sketch: copies of the entities in rows and columns.

Works only inside a sketch block.

Returns: nothing.

pattern_rect(otwor, cols: 4, rows: 2, dx: 20, dy: 15)

pattern_ring

A circular pattern in the sketch: copies of the entities spread around a point.

Works only inside a sketch block.

Returns: nothing.

pattern_ring(otwor, [0, 0], count: 6)

point

A standalone sketch point. Creates no region; serves as a reference for constraints and patterns.

Returns: sketch entity.

polygon

A regular polygon inscribed in a circle or circumscribed about it.

Returns: list of entities.

polygon([0, 0], sides: 6, diameter: 20)

polyline

A polyline through consecutive points. With the closing option gives a closed contour.

Returns: list of entities.

polyline([[0,0], [40,0], [40,20], [0,20]], closed: true)

project

Projects geometry onto the sketch plane along its normal. The projection stays linked to its source.

Works only inside a sketch block.

Returns: list of entities.

project(faces(b, side: "top"))
project(edges(b, dir: up))
project(sk1)

A projection flattens the source along the sketch normal, so it always comes out. When you need the trace of geometry exactly on the plane, use intersect_curves.

rect

A rectangle. Given either by two opposite corners or by a centre with width and height.

Returns: list of four entities.

rect([0, 0], [80, 40])
rect(center: [0, 0], width: 80, height: 40)

rect_3pt

A rotated rectangle: two points set one side, the third sets the height.

Returns: list of four entities.

sketch

Creates a sketch on a plane and fills it with geometry from a block or from a list of entities.

Returns: sketch.

sk = sketch(plane.xy) {
  rect([0, 0], [80, 40])
  circle([40, 20], diameter: 10)
}
sk = sketch(face(b, "top"), [circle([0, 0], diameter: 6)])

Constraints work only in the block form, because only there do entities have names.

spline

A free curve passing through the given points.

Returns: sketch entity.

spline([[0,0], [20,15], [40,0]], closed: false)

start

Start point of a line, an arc or a curve.

Works only inside a sketch block.

Returns: sketch point.

text

Text set in a font: at a point, in a frame given by two corners, or along a sketch curve. Letters are closed contours, so the text extrudes and cuts like any profile.

Returns: sketch entity.

text("FOREMKA", at: [0, 0], height: 8, font: "Roboto", bold: true)
text("Pokrywa\nrev. 2", [-30, -10], [30, 10], font: "Liberation Serif")
c = circle([0, 0], 20)
text("NA OKRĘGU", path: c, height: 4)

Text in a frame and along a curve can be edited later in the sketch by double-clicking, like text from the Text tool. extrude(sk, ...) extrudes the letter regions; in a sketch with a rectangle around the text the letters are holes in the plate.

trim

Removes the piece of a curve marked by a point, cutting it where other curves cross it.

Works only inside a sketch block.

Returns: nothing.

Constraints

angle

An angle dimension between two lines.

Works only inside a sketch block.

Returns: nothing.

circle_line_distance

A dimension for the distance from the rim of a circle to a line. For a dimension to the centre use point_line_distance.

Works only inside a sketch block.

Returns: nothing.

coincident

Merges two sketch points into one. The strongest constraint there is: the points stop existing separately.

Works only inside a sketch block.

Returns: nothing.

coincident(end(a), start(b))

diameter

A diameter dimension of a circle.

Works only inside a sketch block.

Returns: nothing.

distance

A distance dimension between two points. The value you type drives the geometry.

Works only inside a sketch block.

Returns: nothing.

distance(start(a), end(a), 80)

equal

Forces two lines to the same length, or two circles to the same radius.

Works only inside a sketch block.

Returns: nothing.

equal(a, b)

h_distance

A horizontal distance dimension between two points.

Works only inside a sketch block.

Returns: nothing.

horizontal

Forces a line to lie horizontally, or a horizontal straight line through two points. Horizontal is measured in sketch coordinates.

Works only inside a sketch block.

Returns: nothing.

horizontal(a)
horizontal(center(c1), center(c2))

midpoint

Forces a point to lie halfway between two others.

Works only inside a sketch block.

Returns: nothing.

parallel

Forces two lines to be parallel.

Works only inside a sketch block.

Returns: nothing.

parallel(a, b)

perpendicular

Forces two lines to be perpendicular.

Works only inside a sketch block.

Returns: nothing.

perpendicular(a, b)

point_line_distance

A dimension for the distance from a point to a line.

Works only inside a sketch block.

Returns: nothing.

point_on

Forces a point to lie on a line or on a circle.

Works only inside a sketch block.

Returns: nothing.

radius

A radius dimension of a circle or an arc.

Works only inside a sketch block.

Returns: nothing.

symmetric

Forces two points to be symmetric about a line.

Works only inside a sketch block.

Returns: nothing.

tangent

Forces a line to be tangent to a circle, or two circles to be tangent to each other.

Works only inside a sketch block.

Returns: nothing.

tangent(l, c)

v_distance

A vertical distance dimension between two points.

Works only inside a sketch block.

Returns: nothing.

vertical

Forces a line to lie vertically, or a vertical straight line through two points.

Works only inside a sketch block.

Returns: nothing.

Selection

axis

An axis given by a point and a direction. For revolve and circular pattern.

Returns: axis.

revolve(sk, axis([0,0,0], up), 360)

axis_of

An axis taken from geometry: from a straight edge its direction, from a circular one or from a cylindrical face the axis of revolution.

Returns: axis.

pattern_circular(b, axis_of(face(b, kind: "cylinder")), count: 6)

bodies

A list of all visible bodies in the document.

Returns: list of bodies.

for b in bodies() { print(b.name) }

body

A body by its name in the tree. Without an argument gives the most recently created one.

Returns: body.

b = body("Bryła 1")

edges

Edges of a body matching every given condition. Without conditions gives every edge.

Returns: edge set.

fillet(edges(b, dir: up), radius: 3)
chamfer(edges(b, kind: "circle", diameter: 6), 0.5)
edges(b, where: def(e) { return e.length > 20 and e.mid.z > 0 })

Tangent, seam and degenerate edges are skipped, just like when picking with the mouse.

face

A single face. Short for faces(...) with the requirement that exactly one comes back; on more than one the script stops instead of quietly taking the first that fits.

Returns: face set holding exactly one face.

sk = sketch(face(b, "top"))
hole(face(b, "top"), at: [10, 10], diameter: 5)

faces

Faces of a body matching every given condition.

Returns: face set.

shell(b, 2, openings: faces(b, side: "top"))
faces(b, kind: "cylinder", diameter: 6, internal: true)
faces(b, normal: up, min_area: 100)

find_sketch

A sketch by its name in the tree. Without an argument gives the most recently created one.

Returns: sketch.

sk = find_sketch("Sketch1")
b = extrude(find_sketch(), 10)

The counterpart of "body" for sketches: reaches a sketch from an earlier run of a script, where the variable holding it no longer exists.

plane_from

A plane given by a point and a normal.

Returns: plane.

mirror(b, plane_from([0,0,0], x_axis))

profile

Sketch regions to extrude or revolve. Without further conditions takes every closed region of the sketch.

Returns: profile.

extrude(profile(sk, index: 0), 10)

Usually the sketch alone is enough: extrude(sk, 10) takes all of its regions.

sketches

A list of all sketches in the document.

Returns: list of sketches.

print(count(sketches()))

Primitives

box

A box with the given dimensions.

Returns: body.

b = box([80, 40, 20])

cylinder

A cylinder with a vertical axis.

Returns: body.

b = cylinder(diameter: 30, height: 50)

gear_rack

A gear rack with straight teeth, the partner of a spur_gear with the same module and pressure angle. It lies on the horizontal plane: the rack runs along +X, the teeth point to -Z and the width grows upwards.

Returns: body.

r = gear_rack(24, 2, thickness: 10, at: [-75.4, 0, 20])
p = spur_gear(20, 2, thickness: 10, hole: 8)

A gear with pitch radius r meshes with the rack when its centre lies r from the pitch line on the teeth side: a rack with at: [x, 0, r] fits a gear at the origin. Tooth number k has its axis at x + (k + 1/2) * pi * module, so both ends of the rack fall in the middle of a gap. Turning the gear by an angle a (radians) moves the rack by a * r.

sphere

A sphere.

Returns: body.

spur_gear

A spur gear with straight teeth and an involute profile (ISO 53 basic rack). It lies on the horizontal plane with a vertical axis, tooth number 0 points along +X.

Returns: body.

g = spur_gear(24, 2, thickness: 8, hole: 8)
p = spur_gear(13, 2, thickness: 8, at: [37, 0, 0])

A pair meshes at a centre distance of module * (z1 + z2) / 2. A gear placed along +X from the other faces it with a gap when its tooth count is odd; with an even count rotate it by half a pitch first: move(p, rotate: 180 / z, axis: up), then move it into place. Below 17 teeth (20°) the teeth are not undercut, so a small pinion also touches a large gear below its base circle.

torus

A torus with a vertical axis.

Returns: body.

Solids

emboss

Raises or recesses a sketch profile on a body face, curved ones too (text or a logo on a cylinder).

Returns: body.

emboss(face(walec, kind: "cylinder"), napis, 1)
emboss(walec, napis, 1, at: [0, 20, 20])
emboss(face(b, "top"), logo, 0.5, deboss: true)

The reference point is the centre of the profile projected along the sketch normal onto the face, so draw the sketch on a plane facing the face (for a cylinder: through its axis or tangent to it).

extrude

Extrudes a profile perpendicular to its plane. The profile is a sketch, its selected regions or a face of a body (then it works as a face extrusion).

Returns: body or list of bodies.

b = extrude(sk, 20)
extrude(sk, -10, op: "cut", target: b)
extrude(sk, -1, op: "cut", target: b, through_all: true)
extrude(face(b, "top"), 5, op: "join", target: b)
extrude(sk, 0, to: face(other, "bottom"), offset: 1)

An extrusion from a sketch made on a face of a body adds or removes material by default, depending on the sign of the distance.

loft

Spans a body between profiles on different planes, in the given order.

Returns: body or list of bodies.

b = loft([dol, srodek, gora])
b = loft([dol, gora], twist: 90)

pipe

A pipe of circular section along a path from a sketch.

Returns: body.

b = pipe(sciezka, diameter: 12)

project_to_surface

Lays sketch curves onto body faces, curved ones too. The result is a body of curves only, for example a face split line.

Returns: curve body.

k = project_to_surface(face(walec, kind: "cylinder"), napis)
split_face(face(walec, kind: "cylinder"), k)

Curves add no material. They serve as a face split tool or a reference; emboss puts material on the face.

revolve

Revolves a profile about an axis.

Returns: body or list of bodies.

b = revolve(sk, axis([0,0,0], up), 360)
gwint = revolve(trapez, axis([0,0,0], up), pitch: 4, length: 30, op: "join", target: pret)
czasza = revolve(luk, axis([0,0,0], up), 360, solid: false)

rib

A rib from an open profile: it grows towards the body and stops where it meets it.

Returns: body.

sweep

Sweeps a profile along a path from another sketch.

Returns: body or list of bodies.

b = sweep(profil, sciezka)
filar = sweep(kwadrat, os, rail: sylwetka, twist: 120, spin: 180)

web

A web from an open profile: unlike a rib it enters the body along its whole length.

Returns: body.

Modify

chamfer

Cuts the given edges.

Returns: body.

b = chamfer(edges(b, kind: "circle", diameter: 8), 0.5)

copy

A copy of the body in the same place. The original stays.

Returns: body.

druga = move(copy(b), [40, 0, 0])

draft

Tapers the given faces relative to the pull direction. For cast and moulded parts.

Returns: body.

b = draft(faces(b, kind: "plane", normal: x_axis), 3, neutral: face(b, "bottom"))

fillet

Rounds the given edges.

Returns: body.

b = fillet(edges(b, dir: up), 3)
fillet(edges(b, kind: "circle"), radius: 1)

A fillet consumes the source body, the same as when working with the mouse. When the radius is too large for the geometry, the operation does not come out and the script reports an error.

hole

Drills a hole in a face of a body: simple, counterbored or countersunk, optionally threaded.

Returns: body.

b = hole(face(b, "top"), at: [10, 10], diameter: 6, depth: 12)
b = hole(face(b, "top"), at: [0, 0], thread: "M8")
b = hole(face(b, "top"), at: [20, 0], diameter: 5, type: "countersink", cs_diameter: 10)

move

Moves and rotates a body.

Returns: body.

move(b, [0, 0, 25])
move(b, rotate: 45, axis: up)

offset_body

Offsets every face of a body at once, fillets and holes included. A negative distance shrinks the body and enlarges holes: compensation for 3D print spread.

Returns: body.

b = offset_body(b, -0.1)
b = offset_body(b, 0.5, corners: "round")

scale

Scales a body; separate factors per axis give a non-uniform scaling.

Returns: body.

scale(b, 2)
scale(b, [2, 1, 1])

shell

Hollows a body out, leaving a wall of the given thickness. The given faces are removed and become openings; without them the shell stays closed, with a cavity inside.

Returns: body.

b = shell(b, 2, openings: faces(b, side: "top"))
b = shell(b, 2)

thicken

Gives thickness to a surface or to the given faces, turning them into a solid.

Returns: body.

b = thicken(powierzchnia, 2)

thread

Cuts a thread on a cylindrical face: on a shaft from the outside, in a hole from the inside.

Returns: body.

b = thread(face(b, kind: "cylinder", diameter: 10), "M10")
b = thread(face(b, kind: "cylinder", diameter: 75), "M75x2", fit: true)
b = thread(face(b, kind: "cylinder", diameter: 10), "M10", chamfer: "end")

Boolean operations

cut

Subtracts the tool bodies from the target body.

Returns: body or list of bodies.

b = cut(korpus, wiertlo)

intersect

Keeps the common part of the bodies.

Returns: body or list of bodies.

mirror

Mirrors bodies about a plane. The originals stay.

Returns: body or list of bodies.

mirror(b, plane.yz)
mirror(b, plane.yz, features: [wyciecie])

split_body

Splits a body with a plane or a tool (a surface, also a bent one, or another body) into separate bodies.

Returns: list of bodies.

czesci = split_body(b, plane.xy)
czesci = split_body(b, tool: zagieta)

union

Joins bodies into one.

Returns: body or list of bodies.

b = union(podstawa, wspornik)

Patterns

pattern_circular

Copies a body around an axis.

Returns: body or list of bodies.

pattern_circular(b, axis([0,0,0], up), count: 6)

pattern_linear

Copies a body along a direction.

Returns: body or list of bodies.

pattern_linear(b, x_axis, count: 5, distance: 20)
pattern_linear(b, x_axis, count: 4, distance: 15, direction2: y_axis, count2: 3, distance2: 10)

pattern_path

Copies a body along a path from a sketch.

Returns: body or list of bodies.

Faces

delete_face

Removes the given faces, closing the body with the neighbouring ones. For taking off fillets and chamfers.

Returns: body.

offset_face

Offsets the given faces by a distance, changing the size of the body.

Returns: body.

replace_face

Replaces the given faces with another surface.

Returns: body.

split_face

Splits faces with another shape, without changing the volume.

Returns: body.

Surfaces

boundary_fill

Spans a surface across the given edges of bodies.

Returns: surface body.

extend_surface

Extends a surface at the given edges.

Returns: surface body.

offset_surface

Creates a surface offset from the given one. The source stays.

Returns: surface body.

patch

Fills a closed sketch contour with a surface.

Returns: surface body.

stitch

Stitches surfaces into a shell, and into a solid when the result comes out watertight.

Returns: body.

trim_surface

Trims a surface with another shape, keeping the piece marked by a point.

Returns: surface body.

unstitch

Breaks a shape apart into separate faces.

Returns: list of surface bodies.

Construction geometry

construction_axis

A construction axis in the tree, visible in the scene.

Returns: construction axis.

construction_point

A construction point in the tree.

Returns: construction point.

offset_plane

A construction plane offset parallel to the given one. Lands in the tree and can be sketched on.

Returns: construction plane.

p = offset_plane(plane.xy, 25)
sk = sketch(p)

plane_along_path

A construction plane perpendicular to a sketch curve at the given position along its length.

Returns: construction plane.

przekroj = plane_along_path(sciezka, 0.5)

Useful before a sweep: the profile is drawn on a plane perpendicular to the path.

plane_at_angle

A construction plane containing a sketch line, rotated about it by the given angle.

Returns: construction plane.

skos = plane_at_angle(krawedz, 30)

Measurement

measure

Properties of a body: volume, area, centre of mass, extents.

Returns: record with fields volume, area, center, min, max, size.

m = measure(b)
print("objętość " + round(m.volume / 1000, 2) + " cm3")

Document

color

Sets the colour of a body.

Returns: the same body.

color(b, "#3498db")

hide

Hides a body, a sketch or a plane.

Returns: nothing.

material

Assigns a material from the appearance library to a body. A material with a density lets the mass be computed.

Returns: the same body.

name

Names a body or a sketch. The same name lets you find the object later through body("...").

Returns: the same object.

name(b, "Korpus")

remove

Removes a body, a sketch or a feature from the history.

Returns: nothing.

Removing a feature also removes everything that follows from it.

show

Shows a hidden body, sketch or plane.

Returns: nothing.

Exchange

export_file

Saves bodies to a file in the given format.

Returns: nothing.

export_file(b, "korpus.step")

import_file

Reads a CAD file and inserts its contents as bodies.

Returns: body or list of bodies.

The file has to be reachable for the application: in the browser, from the folder set in the model library settings.

View

fit

Fits the view so that the whole model is visible.

Returns: nothing.

section

Turns on section analysis: the model is shown cut by the given plane. Does not change the geometry.

Returns: nothing.

section(plane.yz)

section_off

Turns section analysis off.

Returns: nothing.

view

Sets the camera to a standard view.

Returns: nothing.

Math

abs

Absolute value.

Returns: number.

acos

Arccosine, result in degrees.

Returns: number.

asin

Arcsine, result in degrees.

Returns: number.

atan

Arctangent, result in degrees.

Returns: number.

atan2

Angle in degrees of the vector (x, y) measured from the X axis.

Returns: number: angle in degrees.

ceil

Rounds up.

Returns: number.

clamp

A value clipped to a range.

Returns: number.

cos

Cosine of an angle given in degrees.

Returns: number.

cross

Cross product: a vector perpendicular to both given ones.

Returns: vector.

deg

Converts radians to degrees.

Returns: number: angle in degrees.

dot

Dot product of two vectors.

Returns: number.

floor

Rounds down.

Returns: number.

length_of

Length of a vector.

Returns: number.

max

The larger of two numbers.

Returns: number.

min

The smaller of two numbers.

Returns: number.

normalized

A vector of length one pointing the same way as the given one.

Returns: vector.

pow

Power. The same as the ^ operator.

Returns: number.

rad

Converts degrees to radians. Rarely needed, because the whole language works in degrees.

Returns: number: angle in radians.

round

Rounds to the given number of decimal places.

Returns: number.

sin

Sine of an angle given in degrees.

Returns: number.

sqrt

Square root.

Returns: number.

tan

Tangent of an angle given in degrees.

Returns: number.

vec

A vector or a point in space. The same as writing [x, y, z], handy when computing.

Returns: vector [x, y, z].

Lists

count

Number of items in a list or in a set of edges or faces.

Returns: number.

item

An item of a list by index, counting from zero. A negative index counts from the end.

Returns: item.

range

A list of numbers from start to end, without the end value. For loops.

Returns: list of numbers.

for i in range(0, 5) { print(i) }
range(0, 100, 25)

Diagnostics

assert

Stops the script when the condition does not hold. For checking assumptions, such as whether a selector matched as many edges as it should.

Returns: nothing.

assert(edges(b, kind: "circle").count == 4, "spodziewam się czterech otworów")

print

Prints a value in the script console.

Returns: nothing.

print("wysokość: " + h)