Geoscript Builtin Functions

bits

bit_and

bit_and ( a : Numeric , b : Numeric ) : Int

Bitwise AND operation of two integers (`a & b`)

Arguments:

a : Numeric
b : Numeric

bit_and ( a : Mesh , b : Mesh ) : Mesh

Returns the boolean intersection of two meshes (`a & b`)

Arguments:

a : Mesh
b : Mesh

bit_or

bit_or ( a : Numeric , b : Numeric ) : Int

Bitwise OR operation of two integers (`a | b`)

Arguments:

a : Numeric
b : Numeric

bit_or ( a : Mesh , b : Mesh ) : Mesh

Returns the boolean union of two meshes (`a | b`)

Arguments:

a : Mesh
b : Mesh

core

assert

assert ( condition : Bool , message : String String(Assertion failed) ) : Nil

Raises an error if `condition` is false, optionally including `message` in the error

Arguments:

condition : Bool
message : String String(Assertion failed) - Optional message to include in the error if the assertion fails

float

float ( value : String | Numeric ) : Float

Converts a value to a float

Arguments:

value : String | Numeric

int

int ( value : String | Numeric ) : Int

Converts a value to an int

Arguments:

value : String | Numeric

len

aliases: length, magnitude, mag

len ( v : Vec3 ) : Float

Returns the length/magnitude of a Vec3

Arguments:

v : Vec3

len ( v : Vec2 ) : Float

Returns the length/magnitude of a Vec2

Arguments:

v : Vec2

len ( v : String ) : Int

Returns the number of unicode characters in a string

Arguments:

v : String

len ( v : Sequence ) : Int

Returns the number of elements in a sequence. This will fully evaluate the sequence. Calling this with an infinite sequence will result in the program hanging or crashing.

Arguments:

v : Sequence

len ( m : Mesh ) : Int

Returns the number of vertices in a mesh

Arguments:

m : Mesh

print

print ( ... Any ) : Nil

Prints all provided args and kwargs to the console

Arguments:

render

render ( mesh : Mesh ) : Nil

Renders a mesh to the scene

Arguments:

mesh : Mesh

render ( light : Light ) : Nil

Renders a light to the scene

Arguments:

light : Light

render ( meshes : Sequence ) : Nil

Renders a sequence of entities to the scene. The sequence can contain a heterogeneous mix of meshes, lights, and paths (`Seq<Vec3>` or `Seq<Vec2>`). `Vec2` paths are rendered in the XZ plane. Each entity will be rendered separately.

Arguments:

meshes : Sequence - Either: - `Seq<Mesh | Light | Seq<Vec3 | Vec2>>` of objects to render to the scene, or - `Seq<Vec3>` of points representing a path to render, or - `Seq<Vec2>` of 2D points representing a path to render in the XZ plane

render ( path : Callable ) : Nil

Renders a `PathSampler` as a closed path in the XZ plane. The sampler is evaluated at 10,000 evenly-spaced points and the resulting 2D positions are projected onto the XZ plane (y=0).

Arguments:

path : Callable - A `PathSampler` callable (e.g. from `trace_svg_path`, `trace_path`, `lerp_path`) to render as a closed path in the XZ plane

render_path

alias: path_render

render_path ( path : Callable , resolution : Numeric Int(1000) ) : Nil

Renders a path callable as a 2D path in the XZ plane. For PathSampler callables (e.g. from `trace_path`, `trace_svg_path`, `text_to_path`), subpaths and topology are handled correctly. For plain callables, uniform sampling is used.

Arguments:

path : Callable - A path sampler (from `trace_path`, `trace_svg_path`, `text_to_path`, etc.) or any `|t: num|: vec2` callable.
resolution : Numeric Int(1000) - Sample count for non-PathSampler callables. PathSampler callables use adaptive sampling instead.

str

alias: string

str ( value : Any ) : String

Converts a value to a string. For simple types like numbers and booleans, this performs the basic conversion as you'd expect. For more complicated or internal types like meshes, lights, sequences, etc., the format is not defined and may change at a later time.

Arguments:

value : Any

vec2

alias: v2

vec2 ( x : Numeric , y : Numeric ) : Vec2

Creates a Vec2 given x, y

Arguments:

x : Numeric
y : Numeric

vec2 ( value : Numeric ) : Vec2

Creates a Vec2 with both components set to `value`

Arguments:

value : Numeric

vec3

alias: v3

vec3 ( x : Numeric , y : Numeric , z : Numeric ) : Vec3

Creates a Vec3 given x, y, z

Arguments:

x : Numeric
y : Numeric
z : Numeric

vec3 ( xy : Vec2 , z : Numeric ) : Vec3

Creates a Vec3 from a Vec2 and a z component

Arguments:

xy : Vec2
z : Numeric

vec3 ( x : Numeric , yz : Vec2 ) : Vec3

Creates a Vec3 from an x component and a Vec2

Arguments:

x : Numeric
yz : Vec2

vec3 ( value : Numeric ) : Vec3

Creates a Vec3 with all components set to `value`

Arguments:

value : Numeric

fn

call

call ( fn : Callable ) : Any

Calls `fn` with no arguments, returning its return value

Arguments:

fn : Callable

call ( fn : Callable , args : Sequence ) : Any

Calls `fn` with the provided arguments, returning its return value

Arguments:

fn : Callable
args : Sequence

compose

Example

move_and_scale = compose(
  translate(3, 3, 0),
  scale(0.5),
)

cube = box(2)

cube
  | set_material('blue')
  | render

cube 
  | move_and_scale
  | set_material('red')
  | render

Open in editor

compose ( ... Sequence ) : Callable

Composes all arguments, returning a callable like `|x| arg1(arg2(arg3(x)))`

Arguments:

compose ( callables : Sequence ) : Callable

Composes a sequence of callables, returning a callable like `|x| callables[0](callables[1](...callables[n](x)))`

Arguments:

callables : Sequence - Sequence of callables to compose

light

ambient_light

ambient_light ( color : Vec3 | Numeric Int(16777215) , intensity : Numeric Float(1.8) ) : Light

Creates an ambient light. Note: This will not do anything until it is added to the scene via `render`

Arguments:

color : Vec3 | Numeric Int(16777215) - Color of the light in hex format (like 0xffffff) or webgl format (like `vec3(1., 1., 1.)`)
intensity : Numeric Float(1.8)

dir_light

Example

box(8) | render;
(sphere(radius=5, resolution=4) + v3(8, 8, -4)) | render

light_pos = v3(10, 13, -10)

sphere(radius=0.5, resolution=4)
  | trans(light_pos * 1.1)
  | set_material('light_marker')
  | render

dir_light(intensity=25, color=0xff00ff)
  | trans(light_pos)
  | render

Open in editor

dir_light ( target : Vec3 Vec3(0, 0, 0) , color : Vec3 | Numeric Int(16777215) , intensity : Numeric Float(5) , cast_shadow : Bool Bool(true) , shadow_map_size : Map | Numeric {"width": Int(4096), "height": Int(4096)} , shadow_map_radius : Numeric Float(4) , shadow_map_blur_samples : Numeric Int(16) , shadow_map_type : String String(vsm) , shadow_map_bias : Numeric Float(-0.0001) , shadow_camera : Map {"far": Float(300), "bottom": Float(-140), "left": Float(-300), "near": Float(8), "right": Float(380), "top": Float(94)} ) : Light

Creates a directional light. Note: This will not do anything until it is added to the scene via `render`

Arguments:

target : Vec3 Vec3(0, 0, 0) - Target point that the light is pointing at. If the light as at the same position as the target, it will point down towards negative Y
color : Vec3 | Numeric Int(16777215) - Color of the light in hex format (like 0xffffff) or webgl format (like `vec3(1., 1., 1.)`)
intensity : Numeric Float(5)
cast_shadow : Bool Bool(true)
shadow_map_size : Map | Numeric {"width": Int(4096), "height": Int(4096)} - Size of the shadow map. Allowed keys: `width`, `height`. OR, a single integer value that will be used for both width and height.
shadow_map_radius : Numeric Float(4) - Radius for shadow map filtering
shadow_map_blur_samples : Numeric Int(16) - Number of samples for shadow map blur
shadow_map_type : String String(vsm) - Allowed values: `vsm`
shadow_map_bias : Numeric Float(-0.0001)
shadow_camera : Map {"far": Float(300), "bottom": Float(-140), "left": Float(-300), "near": Float(8), "right": Float(380), "top": Float(94)} - Camera parameters for the shadow map. Allowed keys: `near`, `far`, `left`, `right`, `top`, `bottom`

hemisphere_light

hemisphere_light ( sky_color : Vec3 | Numeric Int(16777215) , ground_color : Vec3 | Numeric Int(4473924) , intensity : Numeric Float(1) ) : Light

Creates a hemisphere light: a cheap directional ambient that blends `sky_color` (from above) and `ground_color` (from below) by surface normal. Note: This will not do anything until it is added to the scene via `render`

Arguments:

sky_color : Vec3 | Numeric Int(16777215) - Color of the light coming from above (the sky), in hex format (like 0xffffff) or webgl format (like `vec3(1., 1., 1.)`)
ground_color : Vec3 | Numeric Int(4473924) - Color of the light coming from below (the ground), in hex format (like 0x444444) or webgl format (like `vec3(0.2, 0.2, 0.2)`)
intensity : Numeric Float(1)

rect_area_light

rect_area_light ( color : Vec3 | Numeric Int(16777215) , intensity : Numeric Float(1) , width : Numeric Float(10) , height : Numeric Float(10) ) : Light

Creates a rectangular area light (e.g. a softbox or window). The rectangle emits from its local -Z face; position and orientation come from transforms applied via `translate`/`rotate`/etc. Does not cast shadows. Note: This will not do anything until it is added to the scene via `render`

Arguments:

color : Vec3 | Numeric Int(16777215) - Color of the light in hex format (like 0xffffff) or webgl format (like `vec3(1., 1., 1.)`)
intensity : Numeric Float(1)
width : Numeric Float(10) - Width of the emitting rectangle
height : Numeric Float(10) - Height of the emitting rectangle

logic

and

and ( a : Bool , b : Bool ) : Bool

Logical AND operation of two booleans

Arguments:

a : Bool
b : Bool

not

not ( value : Bool ) : Bool

Inverts the boolean value (logical NOT)

Arguments:

value : Bool

or

or ( a : Bool , b : Bool ) : Bool

Logical OR operation of two booleans

Arguments:

a : Bool
b : Bool

xor

xor ( a : Bool , b : Bool ) : Bool

Logical XOR operation of two booleans

Arguments:

a : Bool
b : Bool

math

abs

abs ( value : Numeric ) : Int

Absolute Value

Arguments:

value : Numeric

abs ( value : Numeric ) : Float

Absolute Value

Arguments:

value : Numeric

abs ( value : Vec3 ) : Vec3

Component-wise absolute value of a Vec3

Arguments:

value : Vec3

abs ( value : Vec2 ) : Vec2

Component-wise absolute value of a Vec2

Arguments:

value : Vec2

acos

acos ( value : Numeric ) : Float

Returns the arccosine of a numeric value

Arguments:

value : Numeric

acos ( value : Vec3 ) : Vec3

Returns a Vec3 with the arccosine of each component

Arguments:

value : Vec3

acos ( value : Vec2 ) : Vec2

Returns a Vec2 with the arccosine of each component

Arguments:

value : Vec2

add

add ( a : Vec3 , b : Vec3 ) : Vec3

Adds two Vec3s component-wise

Arguments:

a : Vec3
b : Vec3

add ( a : Numeric , b : Numeric ) : Float

a + b

Arguments:

a : Numeric
b : Numeric

add ( a : Numeric , b : Numeric ) : Float

a + b

Arguments:

a : Numeric
b : Numeric

add ( a : Numeric , b : Numeric ) : Int

a + b

Arguments:

a : Numeric
b : Numeric

add ( a : Mesh , b : Mesh ) : Mesh

Combines two meshes into one mesh containing all geometry from both inputs. This does NOT perform a boolean union; for that, use the `union` function or the `|` operator.

Arguments:

a : Mesh
b : Mesh

add ( mesh : Mesh , offset : Vec3 ) : Mesh

Translates the given mesh by a Vec3 offset

Arguments:

mesh : Mesh
offset : Vec3

add ( vec : Vec3 , num : Numeric ) : Vec3

Adds a numeric value to each component of a Vec3

Arguments:

vec : Vec3
num : Numeric

add ( a : Vec2 , b : Vec2 ) : Vec2

Adds two Vec2s component-wise

Arguments:

a : Vec2
b : Vec2

add ( a : Vec2 , b : Numeric ) : Vec2

Adds a numeric value to each component of a Vec2

Arguments:

a : Vec2
b : Numeric

add ( a : String , b : String ) : String

Concatenates two strings

Arguments:

a : String
b : String

asin

asin ( value : Numeric ) : Float

Returns the arcsine of a numeric value

Arguments:

value : Numeric

asin ( value : Vec3 ) : Vec3

Returns a Vec3 with the arcsine of each component

Arguments:

value : Vec3

asin ( value : Vec2 ) : Vec2

Returns a Vec2 with the arcsine of each component

Arguments:

value : Vec2

atan

atan ( value : Numeric ) : Float

Returns the arctangent of a numeric value

Arguments:

value : Numeric

atan ( value : Vec3 ) : Vec3

Returns a Vec3 with the arctangent of each component

Arguments:

value : Vec3

atan ( value : Vec2 ) : Vec2

Returns a Vec2 with the arctangent of each component

Arguments:

value : Vec2

atan2

atan2 ( y : Numeric , x : Numeric ) : Float

Returns the arctangent of `y / x`, using the signs of both arguments to determine the correct quadrant.

Arguments:

y : Numeric
x : Numeric

atan2 ( xy : Vec2 ) : Float

Returns the arctangent of `y / x` for a Vec2, using the signs of both components to determine the correct quadrant.

Arguments:

xy : Vec2

ceil

ceil ( value : Numeric ) : Float

Rounds a numeric value up to the nearest integer

Arguments:

value : Numeric

ceil ( value : Vec3 ) : Vec3

Rounds each component of a Vec3 up to the nearest integer

Arguments:

value : Vec3

ceil ( value : Vec2 ) : Vec2

Rounds each component of a Vec2 up to the nearest integer

Arguments:

value : Vec2

clamp

clamp ( min : Numeric , max : Numeric , value : Numeric ) : Int

Clamps a value between min and max

Arguments:

min : Numeric
max : Numeric
value : Numeric

clamp ( min : Numeric , max : Numeric , value : Numeric ) : Float

Clamps a value between min and max

Arguments:

min : Numeric
max : Numeric
value : Numeric

clamp ( min : Numeric , max : Numeric , value : Vec3 ) : Vec3

Clamps each component of a Vec3 between min and max

Arguments:

min : Numeric
max : Numeric
value : Vec3

clamp ( min : Numeric , max : Numeric , value : Vec2 ) : Vec2

Clamps each component of a Vec2 between min and max

Arguments:

min : Numeric
max : Numeric
value : Vec2

cos

cos ( value : Numeric ) : Float

Cosine

Arguments:

value : Numeric

cos ( value : Vec3 ) : Vec3

Returns a Vec3 with the cosine of each component

Arguments:

value : Vec3

cos ( value : Vec2 ) : Vec2

Returns a Vec2 with the cosine of each component

Arguments:

value : Vec2

cosh

cosh ( value : Numeric ) : Float

Returns the hyperbolic cosine of a numeric value

Arguments:

value : Numeric

cosh ( value : Vec3 ) : Vec3

Returns a Vec3 with the hyperbolic cosine of each component

Arguments:

value : Vec3

cosh ( value : Vec2 ) : Vec2

Returns a Vec2 with the hyperbolic cosine of each component

Arguments:

value : Vec2

cross

cross ( a : Vec3 , b : Vec3 ) : Vec3

Cross product of two Vec3s, returning the Vec3 perpendicular to both (right-handed)

Arguments:

a : Vec3
b : Vec3

deg2rad

deg2rad ( value : Numeric ) : Float

Converts degrees to radians

Arguments:

value : Numeric

distance

alias: dist

distance ( a : Vec3 , b : Vec3 ) : Float

`sqrt((a.x - b.x)^2 + (a.y - b.y)^2 + (a.z - b.z)^2)`

Arguments:

a : Vec3
b : Vec3

distance ( a : Vec2 , b : Vec2 ) : Float

`sqrt((a.x - b.x)^2 + (a.y - b.y)^2`

Arguments:

a : Vec2
b : Vec2

div

div ( a : Vec3 , b : Vec3 ) : Vec3

Returns the component-wise division of two Vec3 values

Arguments:

a : Vec3
b : Vec3

div ( a : Vec3 , b : Numeric ) : Vec3

Divides each element of a Vec3 by a scalar

Arguments:

a : Vec3
b : Numeric

div ( a : Numeric , b : Numeric ) : Float

a / b

Arguments:

a : Numeric
b : Numeric

div ( a : Numeric , b : Numeric ) : Float

a / b

Arguments:

a : Numeric
b : Numeric

div ( a : Numeric , b : Numeric ) : Float

Divides two integers a / b and returns a float. The integers are converted to floats before division. If you need true integer division, use the `mod` function or `%` operator instead.

Arguments:

a : Numeric
b : Numeric

div ( a : Vec2 , b : Vec2 ) : Vec2

Returns the component-wise division of two `Vec2`s

Arguments:

a : Vec2
b : Vec2

div ( a : Vec2 , b : Numeric ) : Vec2

Divides each component of a Vec2 by a scalar

Arguments:

a : Vec2
b : Numeric

dot

dot ( a : Vec3 , b : Vec3 ) : Float

Dot product of two Vec3s: `a.x*b.x + a.y*b.y + a.z*b.z`

Arguments:

a : Vec3
b : Vec3

dot ( a : Vec2 , b : Vec2 ) : Float

Dot product of two Vec2s: `a.x*b.x + a.y*b.y`

Arguments:

a : Vec2
b : Vec2

eq

eq ( a : Numeric , b : Numeric ) : Bool

`a == b`

Arguments:

a : Numeric
b : Numeric

eq ( a : Numeric , b : Numeric ) : Bool

`a == b`

Arguments:

a : Numeric
b : Numeric

eq ( a : Nil , b : Any ) : Bool

`a == b`

Arguments:

a : Nil
b : Any

eq ( a : Any , b : Nil ) : Bool

`a == b`

Arguments:

a : Any
b : Nil

eq ( a : Bool , b : Bool ) : Bool

`a == b`

Arguments:

a : Bool
b : Bool

eq ( a : String , b : String ) : Bool

`a == b`

Arguments:

a : String
b : String

exp

exp ( value : Numeric ) : Float

Returns the exponential of a numeric value

Arguments:

value : Numeric

exp ( value : Vec3 ) : Vec3

Returns a Vec3 with the exponential of each component

Arguments:

value : Vec3

exp ( value : Vec2 ) : Vec2

Returns a Vec2 with the exponential of each component

Arguments:

value : Vec2

fix_float

fix_float ( value : Numeric ) : Float

If the provided float is NaN, non-infinite, or subnormal, returns 0.0. Otherwise, returns the float unchanged.

Arguments:

value : Numeric

fix_float ( value : Vec3 ) : Vec3

For each component of the Vec3, if it is NaN, non-infinite, or subnormal, returns 0.0. Otherwise, returns the component unchanged.

Arguments:

value : Vec3 - Vec3 value to fix

fix_float ( value : Vec2 ) : Vec2

For each component of the Vec2, if it is NaN, non-infinite, or subnormal, returns 0.0. Otherwise, returns the component unchanged.

Arguments:

value : Vec2 - Vec2 value to fix

floor

floor ( value : Numeric ) : Float

Rounds a numeric value down to the nearest integer

Arguments:

value : Numeric

floor ( value : Vec3 ) : Vec3

Rounds each component of a Vec3 down to the nearest integer

Arguments:

value : Vec3

floor ( value : Vec2 ) : Vec2

Rounds each component of a Vec2 down to the nearest integer

Arguments:

value : Vec2

fract

fract ( value : Numeric ) : Float

Returns the fractional part of a numeric value

Arguments:

value : Numeric

fract ( value : Vec3 ) : Vec3

Returns a Vec3 with the fractional part of each component

Arguments:

value : Vec3

fract ( value : Vec2 ) : Vec2

Returns a Vec2 with the fractional part of each component

Arguments:

value : Vec2

gt

gt ( a : Numeric , b : Numeric ) : Bool

`a > b`

Arguments:

a : Numeric
b : Numeric

gt ( a : Numeric , b : Numeric ) : Bool

`a > b`

Arguments:

a : Numeric
b : Numeric

gte

gte ( a : Numeric , b : Numeric ) : Bool

`a >= b`

Arguments:

a : Numeric
b : Numeric

gte ( a : Numeric , b : Numeric ) : Bool

`a >= b`

Arguments:

a : Numeric
b : Numeric

lerp

alias: mix

lerp ( t : Numeric , a : Vec3 , b : Vec3 ) : Vec3

Linearly interpolates between two Vec3 values `a` and `b` by a factor `t`

Arguments:

t : Numeric
a : Vec3
b : Vec3

lerp ( t : Numeric , a : Numeric , b : Numeric ) : Float

Linearly interpolates between two numeric values `a` and `b` by a factor `t`

Arguments:

t : Numeric
a : Numeric
b : Numeric

lerp ( t : Numeric , a : Vec2 , b : Vec2 ) : Vec2

Linearly interpolates between two Vec2 values `a` and `b` by a factor `t`

Arguments:

t : Numeric
a : Vec2
b : Vec2

linearstep

linearstep ( edge0 : Numeric , edge1 : Numeric , x : Numeric ) : Float

Same as `smoothstep` but with simple linear interpolation instead of Hermite interpolation. It returns 0 if `x < edge0`, 1 if `x > edge1`, and a linear interpolation between 0 and 1 for values of `x` between `edge0` and `edge1`.

Arguments:

edge0 : Numeric
edge1 : Numeric
x : Numeric

ln

ln ( value : Numeric ) : Float

Returns the natural logarithm of a numeric value

Arguments:

value : Numeric

ln ( value : Vec3 ) : Vec3

Returns a Vec3 with the natural logarithm of each component

Arguments:

value : Vec3

ln ( value : Vec2 ) : Vec2

Returns a Vec2 with the natural logarithm of each component

Arguments:

value : Vec2

log10

log10 ( value : Numeric ) : Float

Returns the base-10 logarithm of a numeric value

Arguments:

value : Numeric

log10 ( value : Vec3 ) : Vec3

Returns a Vec3 with the base-10 logarithm of each component

Arguments:

value : Vec3

log10 ( value : Vec2 ) : Vec2

Returns a Vec2 with the base-10 logarithm of each component

Arguments:

value : Vec2

log2

log2 ( value : Numeric ) : Float

Returns the base-2 logarithm of a numeric value

Arguments:

value : Numeric

log2 ( value : Vec3 ) : Vec3

Returns a Vec3 with the base-2 logarithm of each component

Arguments:

value : Vec3

log2 ( value : Vec2 ) : Vec2

Returns a Vec2 with the base-2 logarithm of each component

Arguments:

value : Vec2

look_at

look_at ( pos : Vec3 , target : Vec3 , up : Vec3 Vec3(0, 1, 0) ) : Vec3

Euler angles (radians, XYZ) for an orientation whose local -Z points from `pos` toward `target`, with local +Y aligned to `up`. Feed the result to `rot`.

Arguments:

pos : Vec3 - Source position (the eye)
target : Vec3 - Target position to look at
up : Vec3 Vec3(0, 1, 0) - Up hint used to control roll

look_at ( mesh : Mesh , target : Vec3 , up : Vec3 Vec3(0, 1, 0) ) : Mesh

Orients a mesh so its local -Z points at `target`, with `up` controlling roll. Replaces the current rotation while preserving position and scale.

Arguments:

mesh : Mesh
target : Vec3 - Target position to look at
up : Vec3 Vec3(0, 1, 0) - Up hint used to control roll

look_at ( light : Light , target : Vec3 , up : Vec3 Vec3(0, 1, 0) ) : Light

Orients a light so its local -Z (emission direction) points at `target`, with `up` controlling roll. Replaces the current rotation while preserving position.

Arguments:

light : Light
target : Vec3 - Target position to look at
up : Vec3 Vec3(0, 1, 0) - Up hint used to control roll

lt

lt ( a : Numeric , b : Numeric ) : Bool

`a < b`

Arguments:

a : Numeric
b : Numeric

lt ( a : Numeric , b : Numeric ) : Bool

`a < b`

Arguments:

a : Numeric
b : Numeric

lte

lte ( a : Numeric , b : Numeric ) : Bool

`a <= b`

Arguments:

a : Numeric
b : Numeric

lte ( a : Numeric , b : Numeric ) : Bool

`a <= b`

Arguments:

a : Numeric
b : Numeric

max

max ( a : Numeric , b : Numeric ) : Int

Returns the minimum of the provided arguments

Arguments:

a : Numeric
b : Numeric

max ( a : Numeric , b : Numeric ) : Float

Returns maximum of the provided arguments

Arguments:

a : Numeric
b : Numeric

max ( a : Vec3 , b : Vec3 ) : Vec3

Component-wise maximum of two Vec3s

Arguments:

a : Vec3
b : Vec3

max ( a : Vec2 , b : Vec2 ) : Vec2

Component-wise maximum of two Vec2s

Arguments:

a : Vec2
b : Vec2

min

min ( a : Numeric , b : Numeric ) : Int

Returns the minimum of the provided arguments

Arguments:

a : Numeric
b : Numeric

min ( a : Numeric , b : Numeric ) : Float

Returns minimum of the provided arguments

Arguments:

a : Numeric
b : Numeric

min ( a : Vec3 , b : Vec3 ) : Vec3

Component-wise minimum of two Vec3s

Arguments:

a : Vec3
b : Vec3

min ( a : Vec2 , b : Vec2 ) : Vec2

Component-wise minimum of two Vec2s

Arguments:

a : Vec2
b : Vec2

mod

mod ( a : Numeric , b : Numeric ) : Int

a % b

Arguments:

a : Numeric
b : Numeric

mod ( a : Numeric , b : Numeric ) : Float

Floating point modulus (`a % b`)

Arguments:

a : Numeric
b : Numeric

mul

mul ( a : Vec3 , b : Vec3 ) : Vec3

Returns the component-wise product of two Vec3 values

Arguments:

a : Vec3
b : Vec3

mul ( a : Vec3 , b : Numeric ) : Vec3

Multiplied each element of a Vec3 by a scalar

Arguments:

a : Vec3
b : Numeric

mul ( a : Numeric , b : Numeric ) : Float

a * b

Arguments:

a : Numeric
b : Numeric

mul ( a : Numeric , b : Numeric ) : Float

a * b

Arguments:

a : Numeric
b : Numeric

mul ( a : Numeric , b : Numeric ) : Int

a * b

Arguments:

a : Numeric
b : Numeric

mul ( mesh : Mesh , factor : Numeric ) : Mesh

Uniformly scales a mesh by a scalar factor

Arguments:

mesh : Mesh - Mesh to scale
factor : Numeric - Uniform scale to apply to the mesh

mul ( mesh : Mesh , factor : Vec3 ) : Mesh

Scales `mesh` by `factor` along each axis

Arguments:

mesh : Mesh
factor : Vec3

mul ( a : Vec2 , b : Vec2 ) : Vec2

Returns the component-wise product of two Vec2 values

Arguments:

a : Vec2
b : Vec2

mul ( a : Vec2 , b : Numeric ) : Vec2

Multiplied each element of a Vec2 by a scalar

Arguments:

a : Vec2
b : Numeric

mul ( a : Numeric , b : Vec2 ) : Vec2

Multiplied each element of a Vec2 by a scalar

Arguments:

a : Numeric
b : Vec2

mul ( a : Numeric , b : Vec3 ) : Vec3

Multiplied each element of a Vec3 by a scalar

Arguments:

a : Numeric
b : Vec3

neg

neg ( value : Numeric ) : Int

Negates an integer

Arguments:

value : Numeric

neg ( value : Numeric ) : Float

Negates a float

Arguments:

value : Numeric

neg ( value : Vec3 ) : Vec3

Negates each component of a Vec3

Arguments:

value : Vec3

neg ( value : Bool ) : Bool

Inverts a boolean (logical NOT)

Arguments:

value : Bool

neg ( value : Vec2 ) : Vec2

Negates each component of a Vec2

Arguments:

value : Vec2

neq

neq ( a : Numeric , b : Numeric ) : Bool

`a != b`

Arguments:

a : Numeric
b : Numeric

neq ( a : Numeric , b : Numeric ) : Bool

`a != b`

Arguments:

a : Numeric
b : Numeric

neq ( a : Nil , b : Any ) : Bool

`a != b`

Arguments:

a : Nil
b : Any

neq ( a : Any , b : Nil ) : Bool

`a != b`

Arguments:

a : Any
b : Nil

neq ( a : Bool , b : Bool ) : Bool

`a != b`

Arguments:

a : Bool
b : Bool

neq ( a : String , b : String ) : Bool

`a != b`

Arguments:

a : String
b : String

normalize

normalize ( v : Vec3 ) : Vec3

Returns a normalized Vec3 (length 1) in the same direction as the input vector

Arguments:

v : Vec3

normalize ( v : Vec2 ) : Vec2

Returns a normalized Vec2 (length 1) in the same direction as the input vector

Arguments:

v : Vec2

pos

pos ( value : Numeric ) : Numeric

Passes through the input unchanged (implementation detail of the unary `+` operator)

Arguments:

value : Numeric - h

pos ( value : Vec3 ) : Vec3

Passes through the input unchanged (implementation detail of the unary `+` operator)

Arguments:

value : Vec3

pos ( value : Vec2 ) : Vec2

Passes through the input unchanged (implementation detail of the unary `+` operator)

Arguments:

value : Vec2

pow

pow ( base : Numeric , exponent : Numeric ) : Numeric

`Returns `base` raised to the power of `exponent``

Arguments:

base : Numeric
exponent : Numeric

pow ( base : Vec3 , exponent : Numeric ) : Vec3

Returns a Vec3 with each component raised to the power of `exponent`

Arguments:

base : Vec3
exponent : Numeric

pow ( base : Vec3 , exponent : Numeric ) : Vec3

Returns a Vec3 with each component raised to the power of `exponent`

Arguments:

base : Vec3
exponent : Numeric

rad2deg

rad2deg ( value : Numeric ) : Float

Converts radians to degrees

Arguments:

value : Numeric

round

round ( value : Numeric ) : Float

Rounds a numeric value to the nearest integer

Arguments:

value : Numeric

round ( value : Vec3 ) : Vec3

Rounds each component of a Vec3 to the nearest integer

Arguments:

value : Vec3

round ( value : Vec2 ) : Vec2

Rounds each component of a Vec2 to the nearest integer

Arguments:

value : Vec2

sigmoid

sigmoid ( value : Numeric ) : Float

Sigmoid function

Arguments:

value : Numeric

sigmoid ( value : Vec3 ) : Vec3

Component-wise sigmoid of a Vec3

Arguments:

value : Vec3

sigmoid ( value : Vec2 ) : Vec2

Component-wise sigmoid of a Vec2

Arguments:

value : Vec2

signum

alias: sign

signum ( x : Numeric ) : Float

Returns -1, 0, or 1 depending on the sign of the input. For infinity, NaN, etc, the behavior is undefined.

Arguments:

x : Numeric

signum ( x : Numeric ) : Int

Returns -1, 0, or 1 depending on the sign of the input

Arguments:

x : Numeric

signum ( x : Vec2 ) : Vec2

Returns -1, 0, or 1 depending on the sign of the input element-wise

Arguments:

x : Vec2

signum ( x : Vec3 ) : Vec3

Returns -1, 0, or 1 depending on the sign of the input element-wise

Arguments:

x : Vec3

sin

sin ( value : Numeric ) : Float

Returns the sine of a numeric value

Arguments:

value : Numeric

sin ( value : Vec3 ) : Vec3

Returns the sine of each component of a Vec3

Arguments:

value : Vec3

sinh

sinh ( value : Numeric ) : Float

Returns the hyperbolic sine of a numeric value

Arguments:

value : Numeric

sinh ( value : Vec3 ) : Vec3

Returns a Vec3 with the hyperbolic sine of each component

Arguments:

value : Vec3

sinh ( value : Vec2 ) : Vec2

Returns a Vec2 with the hyperbolic sine of each component

Arguments:

value : Vec2

smoothstep

smoothstep ( edge0 : Numeric , edge1 : Numeric , x : Numeric ) : Float

Works the same as `smoothstep` in GLSL. It returns 0 if `x < edge0`, 1 if `x > edge1`, and a smooth Hermite interpolation between 0 and 1 for values of `x` between `edge0` and `edge1`.

Arguments:

edge0 : Numeric
edge1 : Numeric
x : Numeric

sqrt

sqrt ( value : Numeric ) : Float

Square Root

Arguments:

value : Numeric

sqrt ( value : Vec3 ) : Vec3

Component-wise square root of a Vec3

Arguments:

value : Vec3

sqrt ( value : Vec2 ) : Vec2

Component-wise square root of a Vec2

Arguments:

value : Vec2

sub

sub ( a : Vec3 , b : Vec3 ) : Vec3

Component-wise subtraction of two Vec3s

Arguments:

a : Vec3
b : Vec3

sub ( a : Numeric , b : Numeric ) : Float

a -b

Arguments:

a : Numeric
b : Numeric

sub ( a : Numeric , b : Numeric ) : Float

a - b

Arguments:

a : Numeric
b : Numeric

sub ( a : Numeric , b : Numeric ) : Int

a - b

Arguments:

a : Numeric
b : Numeric

sub ( a : Mesh , b : Mesh ) : Mesh

Returns the boolean difference of two meshes (`a - b`). This is equivalent to the `difference` function.

Arguments:

a : Mesh - Base mesh
b : Mesh - Mesh to subtract

sub ( mesh : Mesh , offset : Vec3 ) : Mesh

Translates the mesh by (`-offset`)

Arguments:

mesh : Mesh
offset : Vec3

sub ( vec : Vec3 , num : Numeric ) : Vec3

Subtracts a numeric value from each component of a Vec3

Arguments:

vec : Vec3
num : Numeric

sub ( a : Vec2 , b : Vec2 ) : Vec2

Subtracts two Vec2s component-wise

Arguments:

a : Vec2
b : Vec2

sub ( a : Vec2 , b : Numeric ) : Vec2

Subtracts a numeric value from each component of a Vec2

Arguments:

a : Vec2
b : Numeric

tan

tan ( value : Numeric ) : Float

Tangent

Arguments:

value : Numeric

tan ( value : Vec3 ) : Vec3

Returns the tangent of each component of a Vec3

Arguments:

value : Vec3

tan ( value : Vec2 ) : Vec2

Returns a Vec2 with the tangent of each component

Arguments:

value : Vec2

tanh

tanh ( value : Numeric ) : Float

Returns the hyperbolic tangent of a numeric value

Arguments:

value : Numeric

tanh ( value : Vec3 ) : Vec3

Returns a Vec3 with the hyperbolic tangent of each component

Arguments:

value : Vec3

tanh ( value : Vec2 ) : Vec2

Returns a Vec2 with the hyperbolic tangent of each component

Arguments:

value : Vec2

trunc

trunc ( value : Numeric ) : Float

Truncates a numeric value to its integer part

Arguments:

value : Numeric

trunc ( value : Vec3 ) : Vec3

Truncates each component of a Vec3 to its integer part

Arguments:

value : Vec3

trunc ( value : Vec2 ) : Vec2

Truncates each component of a Vec2 to its integer part

Arguments:

value : Vec2

mesh

aabb

aabb ( mesh : Mesh ) : Sequence

Returns the axis-aligned bounding box of `mesh` as a 2-element sequence `[mins, maxs]` of Vec3 corners, in world space (after the mesh's transform is applied). Errors if the mesh is empty.

Arguments:

mesh : Mesh - The mesh to compute the axis-aligned bounding box of.

align

align ( to : Vec3 , mesh : Mesh , from : Vec3 Vec3(0, 0, -1) , up_from : Vec3 | Nil Nil , up_to : Vec3 | Nil Nil ) : Mesh

Rotates a mesh so its local `from` axis points along world-space direction `to`. Without `up_from`/`up_to` this is the minimal rotation (no roll control); supplying them additionally rolls about `to` so `up_from` points toward `up_to`. Replaces the current rotation while preserving position and scale.

Arguments:

to : Vec3 - World-space direction to point the `from` axis along (auto-normalized)
mesh : Mesh
from : Vec3 Vec3(0, 0, -1) - Local-space axis to align (auto-normalized); defaults to -Z
up_from : Vec3 | Nil Nil - Optional secondary local axis for roll control, rolled toward `up_to` (best-effort, projected perpendicular to `from`). Must be paired with `up_to`.
up_to : Vec3 | Nil Nil - World-space target for `up_from`. Must be paired with `up_from`.

align ( to : Vec3 , light : Light , from : Vec3 Vec3(0, 0, -1) , up_from : Vec3 | Nil Nil , up_to : Vec3 | Nil Nil ) : Light

Rotates a light so its local `from` axis points along world-space direction `to`. Without `up_from`/`up_to` this is the minimal rotation (no roll control); supplying them additionally rolls about `to` so `up_from` points toward `up_to`. Replaces the current rotation while preserving position.

Arguments:

to : Vec3 - World-space direction to point the `from` axis along (auto-normalized)
light : Light
from : Vec3 Vec3(0, 0, -1) - Local-space axis to align (auto-normalized); defaults to -Z
up_from : Vec3 | Nil Nil - Optional secondary local axis for roll control, rolled toward `up_to` (best-effort, projected perpendicular to `from`). Must be paired with `up_to`.
up_to : Vec3 | Nil Nil - World-space target for `up_from`. Must be paired with `up_from`.

alpha_wrap

Example

distance_to_circle = |p: vec3, radius: num| sqrt(p.y*p.y + pow(sqrt(p.x*p.x + p.z*p.z) - radius, 2));

radius = 8

0..
  -> || { randv(-radius*1.1, radius*1.1) }
  | filter(|p| distance_to_circle(p, radius) < 2)
  | take(1550)
  | alpha_wrap(alpha=1/100, offset=1/100)
  | smooth(iterations=2)
  | simplify(tolerance=0.01)
  | render

Open in editor

alpha_wrap ( mesh : Mesh , alpha : Numeric Float(0.033333335) , offset : Numeric Float(0.03) ) : Mesh

Computes an alpha-wrap of a mesh. This is kind of like a concave version of a convex hull. This function is guaranteed to produce watertight/2-manifold outputs. For more details, see here: https://doc.cgal.org/latest/Alpha_wrap_3/index.html

Arguments:

mesh : Mesh
alpha : Numeric Float(0.033333335) - Controls the feature size of the computed wrapping. Smaller values will capture more detail and produce more faces. This value is relative to the bounding box of the input mesh. Values should be in the range (0, 1).
offset : Numeric Float(0.03) - Controls the offset distance between the the input and the wrapped output mesh surfaces. Larger values will result in simpler outputs with better triangle quality, potentially at the cost of sharp edges and fine details. This value is relative to the bounding box of the input mesh. Values should be in the range (0, 1).

alpha_wrap ( points : Sequence , alpha : Numeric Float(0.033333335) , offset : Numeric Float(0.03) ) : Mesh

Computes an alpha-wrap of a sequence of points. This is kind of like a concave version of a convex hull. This function is guaranteed to produce watertight/2-manifold outputs. For more details, see here: https://doc.cgal.org/latest/Alpha_wrap_3/index.html

Arguments:

points : Sequence
alpha : Numeric Float(0.033333335) - Controls the feature size of the computed wrapping. Smaller values will capture more detail and produce more faces. This value is relative to the bounding box of the input points. Values should be in the range (0, 1).
offset : Numeric Float(0.03) - Controls the offset distance between the the input and the wrapped output mesh surfaces. Larger values will result in simpler outputs with better triangle quality, potentially at the cost of sharp edges and fine details. This value is relative to the bounding box of the input points. Values should be in the range (0, 1).

apply_mat4

apply_mat4 ( m00 : Numeric , m01 : Numeric , m02 : Numeric , m03 : Numeric , m10 : Numeric , m11 : Numeric , m12 : Numeric , m13 : Numeric , m20 : Numeric , m21 : Numeric , m22 : Numeric , m23 : Numeric , m30 : Numeric , m31 : Numeric , m32 : Numeric , m33 : Numeric , mesh : Mesh ) : Mesh

Sets the transform of a mesh to an explicit 4x4 matrix (row-major order)

Arguments:

m00 : Numeric
m01 : Numeric
m02 : Numeric
m03 : Numeric
m10 : Numeric
m11 : Numeric
m12 : Numeric
m13 : Numeric
m20 : Numeric
m21 : Numeric
m22 : Numeric
m23 : Numeric
m30 : Numeric
m31 : Numeric
m32 : Numeric
m33 : Numeric
mesh : Mesh

apply_transforms

apply_transforms ( mesh : Mesh ) : Mesh

Applies rotation, translation, and scale transforms to the vertices of a mesh, resetting the transforms to identity

Arguments:

mesh : Mesh

apply_transforms ( path : Callable ) : Callable

Bakes the 2D affine transform into the path's segment control points, resetting the transform to identity. Only works with trace_path/trace_svg_path paths.

Arguments:

path : Callable - Path sampler callable whose transform will be baked into its geometry.

apply_transforms ( meshes : Sequence ) : Sequence

Applies transforms to each mesh in a sequence, resetting each transform to identity.

Arguments:

meshes : Sequence - Sequence of meshes whose transforms will be baked into their vertices.

bipyramid

bipyramid ( n : Numeric , radius : Numeric Float(1) , height : Numeric Float(1) ) : Mesh

N-gonal bipyramid: a regular `n`-gon equator (radius) in the XZ plane with apexes at ±`height` on Y. `bipyramid(4)` is the axis-aligned octahedron; larger `n` gives gem-like diamonds.

Arguments:

n : Numeric - Number of sides of the equatorial polygon (>= 3)
radius : Numeric Float(1) - Circumradius of the equatorial polygon
height : Numeric Float(1) - Distance from the center to each apex along Y

box

alias: cube

box ( width : Numeric , height : Numeric , depth : Numeric ) : Mesh

Creates a rectangular prism mesh with the specified width, height, and depth

Arguments:

width : Numeric - Width along the X axis
height : Numeric - Height along the Y axis
depth : Numeric - Depth along the Z axis

box ( size : Vec3 | Numeric Vec3(1, 1, 1) ) : Mesh

Creates a box using a uniform or vector size

Arguments:

size : Vec3 | Numeric Vec3(1, 1, 1) - Size of the box as a Vec3, or a single numeric value for a cube

capsule

capsule ( radius : Numeric Float(1) , height : Numeric Float(1) , cap_segments : Numeric Int(4) , radial_segments : Numeric Int(8) , height_segments : Numeric Int(1) ) : Mesh

Generates a capsule mesh (cylinder with hemispherical caps)

Arguments:

radius : Numeric Float(1) - Radius of the capsule
height : Numeric Float(1) - Height of the cylindrical middle section. The total height of the capsule is `height + 2 * radius`.
cap_segments : Numeric Int(4) - Number of curve segments used to build each hemispherical cap
radial_segments : Numeric Int(8) - Number of segmented faces around the circumference
height_segments : Numeric Int(1) - Number of rows of faces along the height of the middle section

cone

cone ( radius : Numeric , height : Numeric , radial_segments : Numeric , height_segments : Numeric Int(1) ) : Mesh

Generates a cone mesh. The base of the cone is centered at the origin, and the cone extends upwards along the positive Y axis.

Arguments:

radius : Numeric
height : Numeric
radial_segments : Numeric
height_segments : Numeric Int(1)

connected_components

Example

0..10
  -> || { sphere(radius=1.15, resolution=2) | trans(randv(-3, 3)) }
  | union
  | connected_components
  -> |component: mesh, i: int| { component | set_material(str(i)) }
  | render

Open in editor

connected_components ( mesh : Mesh ) : Sequence

Splits a mesh into its connected components, returning a sequence of meshes where each mesh is a connected component of the input mesh. The sequence of connected components is sorted by vertex count from highest to lowest. This is NOT lazy; the connected components are computed at the time this function is called.

Arguments:

mesh : Mesh

convex_hull

Example

// pick 50,000 random points within 1 unit of the origin
points = 0..100000000
  -> || { randv(0, 1) }
  | filter(|v| len(v) < 1)
  | take(50000)

// Create a mesh bounded by the convex hull of all those
// points. This is the smallest convex shape that contains
// all of the points.
points
  | convex_hull
  | render

Open in editor

convex_hull ( points : Sequence ) : Mesh

Computes the convex hull of a sequence of points, returning a mesh representing the convex hull

Arguments:

points : Sequence

convex_hull ( mesh : Mesh ) : Mesh

Computes the convex hull of a mesh, returning a mesh representing the convex hull. This will apply all transforms on the mesh, and the returned mesh will have an identity transform.

Arguments:

mesh : Mesh

cylinder

alias: cyl

cylinder ( radius : Numeric , height : Numeric , radial_segments : Numeric , height_segments : Numeric Int(1) ) : Mesh

Generates a cylinder mesh

Arguments:

radius : Numeric
height : Numeric
radial_segments : Numeric
height_segments : Numeric Int(1)

delaunay_remesh

delaunay_remesh ( mesh : Mesh , facet_distance : Numeric Float(0.14) , target_edge_length : Numeric Float(0.2) , protect_sharp_edges : Bool Bool(true) , sharp_angle_threshold_degrees : Numeric Float(30) ) : Mesh

Remeshes a mesh using a Delaunay refinement of a restricted Delaunay triangulation. TODO improve docs once we understand the behavior of this function better. See the docs for the underlying CGAL function for more details: https://doc.cgal.org/latest/Polygon_mesh_processing/index.html - Section 2.1.2 Remeshing

Arguments:

mesh : Mesh
facet_distance : Numeric Float(0.14) - This controls the precision of the output mesh. Smaller values will produce meshes that more closely approximate the input, but will also produce more faces. This value represents units in the local space of the mesh, so it must be chosen relative to the size of the input mesh.
target_edge_length : Numeric Float(0.2) - This serves as an upper bound for the lengths of curve edges in the underlying Delaunay triangulation. Smaller values will produce more faces. This value represents units in the local space of the mesh, so it must be chosen relative to the size of the input mesh.
protect_sharp_edges : Bool Bool(true) - If true, edges with angles >= the `sharp_angle_threshold_degrees` will not be modified.
sharp_angle_threshold_degrees : Numeric Float(30) - Angle threshold in degrees for edges to be considered sharp. Only used if `protect_sharp_edges` is true.

difference

Example

a = box(size=8)
b = icosphere(radius=5, resolution=5)

// subtract the space inside the sphere from the cube
core = sub(a, b)

// You can also just use `-` instead.  The following is
// equivalent to the previous:
core = a - b

core | render

Open in editor

difference ( a : Mesh , b : Mesh ) : Mesh

Returns the boolean difference of two meshes (`a - b`)

Arguments:

a : Mesh - Base mesh
b : Mesh - Mesh to subtract

difference ( meshes : Sequence ) : Mesh

Returns the boolean difference of a sequence of meshes (`meshes[0] - meshes[1] - ...`)

Arguments:

meshes : Sequence - Sequence of meshes to subtract in order

dodecahedron

dodecahedron ( radius : Numeric Float(1) ) : Mesh

Regular dodecahedron with circumradius `radius` (sits edge-up).

Arguments:

radius : Numeric Float(1) - Circumradius (center-to-vertex distance)

extrude

extrude ( up : Vec3 | Callable , mesh : Mesh ) : Mesh

Extrudes a mesh in the direction of `up` by displacing each vertex along that direction. This is designed to be used with 2D meshes; using it on meshes with volume or thickness will probably not work.

Arguments:

up : Vec3 | Callable - Direction to extrude the mesh. Each vertex will be displaced by this amount. If a callable is provided, it should have signature `|vertex_pos: vec3|: vec3` and return the displacement for each vertex.
mesh : Mesh

extrude_along_normals

extrude_along_normals ( distance : Callable | Numeric , mesh : Mesh ) : Mesh

Extrudes a 2D mesh into a shell along its per-vertex normals. Normals are computed per connected component as the area-weighted average of adjacent face normals. Useful for adding thickness to a surface that follows a curve through space — e.g. a mesh draped over a curved surface via `warp` — where a single global `up` direction won't follow the surface curvature. Like `extrude`, designed for 2D (single-layer) meshes: the input is duplicated, displaced, the original is flipped to face the other way, and boundary edges are stitched into side walls to produce a closed 2-manifold shell. Fails to produce a clean shell when the offset distance exceeds the local radius of curvature on concave regions — adjacent normals converge past their starting positions and the duplicated layer self-intersects. For mild undulation this is a non-issue.

Arguments:

distance : Callable | Numeric - Distance to extrude each vertex along its computed normal. If a callable is provided, it should have signature `|vertex_pos: vec3|: num` and return the per-vertex distance.
mesh : Mesh

extrude_path

extrude_path ( path : Callable | Sequence , up : Vec3 , flipped : Bool Bool(false) , curve_angle_degrees : Numeric Float(1) , sample_count : Nil | Numeric Nil ) : Mesh

Sweeps a path along an `up` vector to produce a triangle-strip surface mesh. Each point along the path is duplicated at `+up` to form the top edge of the strip. Multiple subpaths (from `PathSampler` inputs) are extruded independently; closed paths are not supported and trigger an error.

Arguments:

path : Callable | Sequence - Either: - A path callable: a `PathSampler` (e.g. from `trace_path`, `trace_svg_path`, `catmull_rom`, `lerp_paths`) sampled adaptively per `curve_angle_degrees` and optionally capped by `sample_count`; or a black-box `|t: float|: vec2`, sampled uniformly at `sample_count` points (default 64). Returned 2D points are embedded in the XZ plane (`vec2(x, y)` → `vec3(x, 0, y)`). - A `Seq<Vec2 | Vec3>` of pre-discretized points used as-is (no resampling). `Vec2` points are embedded in the XZ plane; `Vec3` points are used directly, which lets you extrude a polyline that already lives in 3D space. Errors if the sequence has fewer than 2 points or contains any other element type.
up : Vec3 - Direction to sweep the path along. Each point in the path is duplicated at `+up` to form the top of the strip.
flipped : Bool Bool(false) - If true, reverses the winding order of the generated triangles, flipping the strip's facing direction.
curve_angle_degrees : Numeric Float(1) - Max turning angle (degrees) per segment when discretizing curves in a `PathSampler` input. Ignored for black-box callables.
sample_count : Nil | Numeric Nil - For black-box `|t|: vec2` callables: number of uniform samples (defaults to 64 when nil). For `PathSampler` inputs: optional cap on total points across all subpaths after adaptive sampling.

extrude_pipe

Example

spiral = |count, height_factor, radius, resolution| {
  0..count -> |i| {
    t = i * (1. / resolution)
    vec3(
      sin(t) * radius,
      i * height_factor,
      cos(t) * radius
    )
  }
}

spiral(count=400, height_factor=0.1, radius=5.5, resolution=4)
  | extrude_pipe(radius=0.5, resolution=8, close_ends=true)
  | render

Open in editor

Example

// demo of `extrude_pipe` with a dynamic radius for each
// vertex of the pipe's rings

resolution = 12

get_radius = |segment_ix: int, center: vec3| {
  0..resolution
    -> |i| {
      if segment_ix % 12 < 6 {
        if i % 2 == 0 { 2 } else { 1 }
      } else {
        0.5
      }
    }
}

0..78
  -> |i| { vec3(i * 0.15, 0, 0) }
  | extrude_pipe(resolution=resolution, radius=get_radius)
  | simplify(tolerance=0.1)
  | render

Open in editor

extrude_pipe ( radius : Callable | Numeric , resolution : Numeric Int(8) , path : Sequence , close_ends : Bool Bool(true) , connect_ends : Bool Bool(false) , twist : Callable | Numeric Float(0) , adaptive_path_sampling : Bool Bool(false) ) : Mesh

Extrudes a pipe along a sequence of points. The radius can be constant or vary along the path using a callable.

Arguments:

radius : Callable | Numeric - Radius of the pipe or a callable with signature `|point_ix: int, path_point: vec3|: float | seq` that returns the radius at each point along the path. If a sequence is returned by the callback, its length must match the resolution and it should contain the distance of each point along the ring from the pipe's center.
resolution : Numeric Int(8) - Number of segments to use for the pipe's circular cross-section
path : Sequence - Sequence of Vec3 points defining the path of the pipe. Often the output of a function like `bezier3d`.
close_ends : Bool Bool(true) - Whether to close the ends of the pipe with triangle fans
connect_ends : Bool Bool(false) - Whether the pipe should be a closed loop, connecting the last point back to the first. If true, the first and last points of the path will be connected with triangles.
twist : Callable | Numeric Float(0) - Twist angle in radians to apply along the path, or a callable with signature `|point_ix: int, path_point: vec3|: float` that returns the twist angle at each point along the path. A value of 0 means no twist.
adaptive_path_sampling : Bool Bool(false) - When true (default), uses curvature-aware adaptive sampling to distribute path points. Concentrates vertices in high-curvature regions of the path, improving mesh quality at bends while using fewer vertices on straight sections. Set to false to use the input points directly without resampling. Note: automatically disabled when a dynamic twist callable is provided, as twist complicates the geometry in ways the adaptive sampler cannot account for.

fan_fill

Example

// create a path defining the outline of a circle
circle_path = 0..100 -> |i| {
  t = i / 100
  vec3(cos(t * pi * 2), 0, sin(t * pi * 2))
}

// fill the outline into a flat mesh
circle = fan_fill(
  circle_path,
  // flip the direction the triangles are facing so that
  // it is visible when looking from the top down
  flipped=true
)

circle | render

Open in editor

fan_fill ( path : Sequence , closed : Bool Bool(true) , flipped : Bool Bool(false) , center : Vec3 | Nil Nil ) : Mesh

Builds a fan of triangles from a sequence of points, filling the area inside them. One triangle will be built for each pair of adjacent points in the path, connecting them to the center point.

Arguments:

path : Sequence - A sequence of Vec3 points representing the path to fill
closed : Bool Bool(true) - If true, the path will be treated as closed - connecting the last point to the first.
flipped : Bool Bool(false) - If true, the winding order of the triangles generated will be flipped - inverting the inside/outside of the generated mesh.
center : Vec3 | Nil Nil - If provided, the center point for the fan will be placed at this position. Otherwise, the center will be computed as the average of the points in the path.

fan_fill ( path : Callable , closed : Bool | Nil Nil , flipped : Bool Bool(false) , center : Vec2 | Vec3 | Nil Nil , curve_angle_degrees : Numeric Float(1) , sample_count : Nil | Numeric Nil ) : Mesh

Builds a fan of triangles by discretizing a path callable and filling the area inside each subpath. One triangle will be built per pair of adjacent points in each subpath, connecting to that subpath's center. Output lives in the XZ plane.

Arguments:

path : Callable - A `PathSampler` callable (e.g. from `trace_path`, `trace_svg_path`, `lerp_path`, `catmull_rom`) or any `|t: num|: vec2` callable. Sampled in the XZ plane (`vec2(x, y)` -> `vec3(x, 0, y)`). Multi-subpath inputs are fanned independently and combined into one mesh.
closed : Bool | Nil Nil - Optional override for treating each subpath as closed. When nil (default), closedness is inherited from the path sampler's topology (or inferred from `p(0) ~= p(1)` for black-box callables).
flipped : Bool Bool(false) - If true, the winding order of the triangles generated will be flipped - inverting the inside/outside of the generated mesh.
center : Vec2 | Vec3 | Nil Nil - If provided, the center point for each fan will be placed at this position. A `Vec2` is embedded in the XZ plane. Otherwise, the center is computed as the average of each subpath's discretized points.
curve_angle_degrees : Numeric Float(1) - Max turning angle (degrees) per segment when adaptively discretizing curves. Currently honored by traced-path samplers (`trace_path`, `trace_svg_path`); other `PathSampler` inputs (`lerp_path`, `catmull_rom`) and black-box callables fall back to uniform `sample_count` sampling.
sample_count : Nil | Numeric Nil - Uniform sample count, used when adaptive sampling is unavailable (black-box callables, `lerp_path`, `catmull_rom`). Defaults to 64 when nil. For traced-path samplers, optionally caps the total points across all subpaths after adaptive sampling.

flip_normals

flip_normals ( mesh : Mesh ) : Mesh

Flips the normals of a mesh, returning a new mesh with inverted normals. This actually flips the winding order of the mesh's triangles under the hood and re-computes normals based off that.

Arguments:

mesh : Mesh

grid

grid ( size : Vec2 | Numeric , divisions : Vec2 | Numeric Vec2(1, 1) , flipped : Bool Bool(false) ) : Mesh

Generates a flat grid mesh in the XZ plane centered at the origin with the specified size and number of subdivisions.

Arguments:

size : Vec2 | Numeric - Size of the grid along the X and Z axes (providing a number will set the same size for both axes). The grid is centered at the origin, so a size of `vec2(1, 1)` will produce a grid that extends from -0.5 to +0.5 along both axes.
divisions : Vec2 | Numeric Vec2(1, 1) - Number of subdivisions along each axis. If an integer is provided, it will be used for both axes.
flipped : Bool Bool(false) - If true, the winding order of the triangles will be flipped - making the front side face downwards (negative Y).

icosahedron

icosahedron ( radius : Numeric Float(1) ) : Mesh

Regular icosahedron with circumradius `radius` (sits edge-up; same as `icosphere(radius, 0)`).

Arguments:

radius : Numeric Float(1) - Circumradius (center-to-vertex distance)

icosphere

alias: sphere

icosphere ( radius : Numeric , resolution : Numeric ) : Mesh

Generates an icosphere mesh

Arguments:

radius : Numeric
resolution : Numeric - Number of subdivisions to apply when generating the icosphere. 0 -> 20 faces, 1 -> 80 faces, 2 -> 320 faces, ...

intersect

Example

a = cylinder(radius=6, height=20, radial_segments=20)
b = icosphere(radius=10, resolution=5)

// only keep the area that exists inside both the sphere
// and the cylinder, kind of like cutting out the core
// of an apple
core = intersect(a, b)

// `intersect` also has a dedicated operator.  The
// following is equivalent to the previous:
core = a & b

core | render

Open in editor

intersect ( a : Mesh , b : Mesh ) : Mesh

Returns the boolean intersection of two meshes (`a & b`)

Arguments:

a : Mesh
b : Mesh

intersect ( meshes : Sequence ) : Mesh

Returns the boolean intersection of a sequence of meshes (`meshes[0] & meshes[1] & ...`)

Arguments:

meshes : Sequence - Sequence of meshes to intersect

intersects

intersects ( a : Mesh , b : Mesh ) : Bool

Returns true if the two meshes intersect, false otherwise

Arguments:

a : Mesh
b : Mesh

intersects_ray

Example

// generate a 3D matrix of cubes filling all the space
0..10 -> |y_ix| {
  y = y_ix - 5
  0..10 -> |x_ix| {
    x = x_ix - 5
    0..10 -> |z_ix| {
      z = z_ix - 5
      box(0.9) | trans(x, y, z)
    }
  }
}
  | flatten
  | flatten
  -> |cube| {
    has_hit = cube
      | intersects_ray(
          ray_origin=v3(-10, -10, -5),
          ray_direction=vec3(1, 1, 0.5)
        )
    
    if has_hit {
      return cube
    }

    cube
      | scale(0.2)
      | set_material('red')
  }
  | render

Open in editor

intersects_ray ( ray_origin : Vec3 , ray_direction : Vec3 , mesh : Mesh , max_distance : Nil | Numeric Nil ) : Bool

Casts a ray from `ray_origin` in `ray_direction` and checks if it intersects `mesh` within `max_distance` (or any distance if `max_distance` is `nil`)

Arguments:

ray_origin : Vec3
ray_direction : Vec3
mesh : Mesh
max_distance : Nil | Numeric Nil - Max distance to check for intersection (`nil` considers intersections at any distance). If the intersection occurs at a distance greater than this, `false` will be returned.

is_manifold

is_manifold ( mesh : Mesh , two_manifold : Bool Bool(true) ) : Bool

Returns true if the mesh satisfies the manifold condition. Assumes the mesh is a single connected component; disconnected islands or parts may produce incorrect results. By default checks for 2-manifold (watertight): every edge shared by exactly two faces. Set `two_manifold=false` to check only for 1-manifold (no edge shared by more than two faces). This check is purely topological; vertex positions, normals, and winding order are not considered.

Arguments:

mesh : Mesh - The mesh to check
two_manifold : Bool Bool(true) - If true (default), checks that every edge is shared by exactly two faces (watertight/2-manifold). If false, checks only that no edge is shared by more than two faces (1-manifold).

is_self_intersecting

is_self_intersecting ( mesh : Mesh ) : Nil |Map

Checks if a mesh has any self-intersecting triangles. Returns `nil` if no self-intersections are found. If a self-intersection is found, returns a map with keys: `tri0` and `tri1` (sequences of 3 Vec3 vertices for each intersecting triangle), `point` (a Vec3 on the intersection), and `type` ("segment" or "coplanar").

Arguments:

mesh : Mesh - The mesh to check for self-intersections

isotropic_remesh

isotropic_remesh ( target_edge_length : Numeric , mesh : Mesh , iterations : Numeric Int(1) , protect_borders : Bool Bool(true) , protect_sharp_edges : Bool Bool(true) , sharp_angle_threshold_degrees : Numeric Float(30) ) : Mesh

Remeshes a mesh to have more uniform edge lengths, targeting the specified edge length. See the docs for the underlying CGAL function for more details: https://doc.cgal.org/5.6.3/Polygon_mesh_processing/index.html - Section 2.1.2 Remeshing

Arguments:

target_edge_length : Numeric - Target edge length for the remeshed output. Edges will be split or collapsed to try to achieve this length.
mesh : Mesh
iterations : Numeric Int(1) - Number of remeshing iterations to perform. Typical values are between 1 and 5.
protect_borders : Bool Bool(true) - If true, edges on the border of the mesh will not be modified.
protect_sharp_edges : Bool Bool(true) - If true, edges with angles >= the `sharp_angle_threshold_degrees` will not be modified.
sharp_angle_threshold_degrees : Numeric Float(30) - Angle threshold in degrees for edges to be considered sharp. Only used if `protect_sharp_edges` is true.

join

Example

cubes: mesh = 0..10
  -> |i| {
    box(1)
      | trans(0, i * 1.5, 0)
      | rot(0, i * 0.2, 0)
  }
  | join

cubes | render

Open in editor

join ( meshes : Sequence ) : Mesh

Combines a sequence of meshes into one mesh containing all geometry from the inputs. This does NOT perform a boolean union; for that, use the `union` function or the `|` operator to create a union over a sequence of meshes.

Arguments:

meshes : Sequence

join ( separator : String , strings : Sequence ) : String

Joins a sequence of strings into a single string, inserting the `separator` between each element

Arguments:

separator : String - String to insert between each mesh
strings : Sequence - Sequence of strings to join

mesh

Example

// builds a cube mesh from scratch
verts = [
  v3(-1, -1, -1),
  v3(1, -1, -1),
  v3(1, 1, -1),
  v3(-1, 1, -1),
  v3(-1, -1, 1),
  v3(1, -1, 1),
  v3(1, 1, 1),
  v3(-1, 1, 1)
]

indices = [
  0, 2, 1, 0, 3, 2,
  4, 5, 6, 4, 6, 7,
  0, 1, 5, 0, 5, 4,
  2, 3, 7, 2, 7, 6,
  0, 7, 3, 0, 4, 7,
  1, 2, 6, 1, 6, 5,
]

mesh(verts, indices) | render

Open in editor

mesh ( verts : Sequence , indices : Sequence ) : Mesh

Creates a mesh from a sequence of vertices and indices

Arguments:

verts : Sequence - Sequence of Vec3 vertices, pointed into by `faces`
indices : Sequence - A flag sequence of integer indices corresponding to triangles. Must have `length % 3 == 0`

mesh ( ) : Mesh

Creates an empty mesh with no vertices or indices. This can be useful as the initial value for `fold` or and other situations like that.

octahedron

alias: diamond

octahedron ( radius : Numeric Float(1) ) : Mesh

Regular octahedron with vertices on the ±X/±Y/±Z axes (a vertex points straight up). Alias: `diamond`.

Arguments:

radius : Numeric Float(1) - Circumradius (center-to-vertex distance)

origin_to_geometry

origin_to_geometry ( mesh : Mesh ) : Mesh

Moves the mesh so that its origin is at the center of its geometry (averge of all its vertices), returning a new mesh. This will actually modify the vertex positions and preserve any existing transforms.

Arguments:

mesh : Mesh

origin_to_geometry ( path : Callable ) : Callable

Moves a 2D path so that its origin is at the centroid of its segment endpoints, returning a new path sampler. Preserves any existing transforms.

Arguments:

path : Callable - Path sampler callable to center.

parametric_surface

Example

major_r = 2
minor_r = 0.5

parametric_surface(
  u_res=150,
  v_res=50,
  u_closed=true,
  v_closed=true,
  generator=|u, v| {
    theta = u * 2 * pi
    phi = v * 2 * pi
    r = major_r + minor_r * (1 + sin(u*pi*12) * 0.8) * cos(phi)
    v3(r * cos(theta), minor_r * (0.5 + sin(v*pi*4) * 0.4) * sin(phi), r * sin(theta))
  },
  fku_stitching=false,
  flip_normals=true
)
  | render

Open in editor

parametric_surface ( u_res : Numeric , v_res : Numeric , u_closed : Bool Bool(false) , v_closed : Bool Bool(false) , flip_normals : Bool Bool(false) , generator : Callable , fku_stitching : Bool Bool(true) , adaptive_u_sampling : Bool Bool(false) , adaptive_v_sampling : Bool Bool(false) , capped : Bool Bool(false) ) : Mesh

Generates a mesh from a parametric function over a 2D domain. Handles topological wrapping via the closed flags and automatically welds coincident vertices at boundary poles to maintain manifold topology. By default, normals point outward when V increases counter-clockwise (looking down +Y); use flip_normals=true to reverse.

Arguments:

u_res : Numeric - Number of segments along the U axis
v_res : Numeric - Number of segments along the V axis
u_closed : Bool Bool(false) - If true, connects the U-end back to U-start (creates cylindrical topology along U)
v_closed : Bool Bool(false) - If true, connects the V-end back to V-start (creates cylindrical topology along V)
flip_normals : Bool Bool(false) - If true, reverses triangle winding to flip normal direction. By default, normals follow the cross product of U and V tangents.
generator : Callable - A function `|u: num, v: num| -> vec3` that returns the 3D position for each (u, v) coordinate in [0, 1]
fku_stitching : Bool Bool(true) - When true (default), uses the Fuchs/Kedem/Uselton (FKU) dynamic programming algorithm to find optimal triangulation between adjacent rows. FKU minimizes total edge length, avoiding sharp angles and long edges when vertex positions drift between rows. When false, uses simple quad-based stitching for predictable topology and uniform wireframe appearance.
adaptive_u_sampling : Bool Bool(false) - When true, uses curvature-aware adaptive sampling along the U axis. Concentrates rows in high-curvature U regions of the surface. Disabled by default since parametric_surface is very general-purpose and adaptive sampling may not always be appropriate.
adaptive_v_sampling : Bool Bool(false) - When true, uses curvature-aware adaptive sampling along the V axis within each row. Concentrates vertices in high-curvature V regions. Works well with FKU stitching which can handle rows with non-uniform vertex distributions. Disabled by default since parametric_surface is very general-purpose and adaptive sampling may not always be appropriate.
capped : Bool Bool(false) - When true, triangulates the open ends of a tube-like surface (exactly one of `u_closed`/`v_closed` is true). Each end-ring is projected to its best-fit plane (via Newell's normal oriented along the axis) and triangulated with CGAL's constrained Delaunay triangulation — the same machinery rail_sweep uses, and it handles concave/non-convex ring shapes correctly. Rings that aren't co-planar are projected as a best effort. Cap winding follows `flip_normals` so the caps match the surface's facing direction. No-op when both axes are closed (torus) or neither is (sheet).

point_distribute

Example

base = torus_knot_path(
  radius=12, tube_radius=7, p=3, q=4, point_count=400
)
  | extrude_pipe(
    radius=2, resolution=12, connect_ends=true
  )
  | set_material('base')

base | render

surface_points = base
  | point_distribute(count=500)
  -> |pos: vec3| {
    icosphere(radius=0.6, resolution=1) | trans(pos)
  }

surface_points | render

Open in editor

point_distribute ( count : Nil | Numeric , mesh : Mesh , seed : Numeric Int(0) , cb : Callable | Nil Nil , world_space : Bool Bool(true) ) : Sequence

Distributes a specified number of points uniformly across the surface of a mesh returned as a sequence. If `cb` is Nil or not provided, a sequence of vec3 positions will be returned. If `cb` is provided, the sequence will consist of the return values from calling `cb(pos, normal)` for each sampled point. This is lazy; the points will not be generated until the sequence is consumed.

Arguments:

count : Nil | Numeric - The number of points to distribute across the mesh. If `nil`, returns an infinite sequence.
mesh : Mesh
seed : Numeric Int(0)
cb : Callable | Nil Nil - Optional callable with signature `|point: vec3, normal: vec3|: any`. If provided, this function will be called for each generated point and normal and whatever it returns will be included in the output sequence instead of the point.
world_space : Bool Bool(true) - If true, points and normals will be returned in world space. If false, they will be returned in the local space of the mesh.

rail_sweep

Sweeps a profile along a spine to produce a mesh. Profile points are connected in increasing `v` order; for outward-facing normals, the profile winding should be counter-clockwise when viewed along the local tangent.

Arguments:

spine_resolution : Numeric - Number of samples to take along the spine
ring_resolution : Numeric - Number of samples to take around each profile ring
spine : Callable | Sequence - Spine definition as a callable with signature `|u: float|: vec3` or a sequence of Vec3 points. When a sequence is provided, the default behavior is to use the points as-is (requiring `spine_resolution` to match the sequence length); pass an explicit `spine_sampling_scheme` such as "uniform" or "chebyshev" to resample the polyline.
profile : Callable | Nil Nil - Callable with signature `|u: float, v: float, u_ix: int, v_ix: int, spine_center: vec3|: vec2` that returns the local (x, y) offset for each point in the ring. Optional when `dynamic_profile` is provided.
frame_mode : Vec3 | String String(rmf) - Frame mode for the sweep. Use "rmf" (default) for rotation-minimizing frames, or provide a Vec3 up direction for fixed-up framing.
twist : Callable | Numeric Float(0) - Twist angle in radians to apply per ring, or a callable with signature `|point_ix: int, spine_center: vec3|: float`.
closed : Bool Bool(false) - Whether to connect the last ring back to the first.
capped : Bool Bool(true) - Whether to cap the start and end rings with triangulated faces. Ignored when `closed` is true.
profile_samplers : Callable | Sequence | Nil Nil - Optional path sampler or sequence of path samplers (from `trace_path`)`. Used to align profile `v` sampling with critical points.
dynamic_profile : Callable | Nil Nil - Alternative to `profile` (mutually exclusive). Callable with signature `|u: float, u_ix: int|: PathSampler | { sampler: |v|: vec2, path_samplers: PathSampler | Seq<PathSampler>, sharp: bool, adaptive: bool }`. Returns either a path sampler directly (critical points extracted automatically if it's a PathTracerCallable) or a map with a sampler plus optional keys: `path_samplers` (trace_path samplers for critical points), `sharp` (mark ring edges as sharp), `adaptive` (override global adaptive_profile_sampling for this ring). More efficient than `profile` for dynamic profiles as it's called once per ring instead of per vertex. Cannot be used together with `profile_samplers`.
fku_stitching : Bool Bool(true) - When true (default), uses the Fuchs/Kedem/Uselton (FKU) dynamic programming algorithm to find optimal triangulation between adjacent rings. FKU minimizes total edge length, producing better triangle quality when ring vertex counts differ or when vertices drift between rings. When false, uses simple quad-based stitching for predictable topology and uniform wireframe appearance.
spine_sampling_scheme : Callable | Sequence | Map | String | Nil Nil - Controls how sample points are distributed along the spine. When unset (the default), sequence spines are used as-is (requires `spine_resolution` to match the sequence length) and callable spines fall back to "uniform". String options: "passthrough"/"as_is"/"raw" - use sequence points as-is (sequence input only); "uniform" - evenly spaced samples; "chebyshev"/"cos"/"cosine" - Chebyshev node spacing (denser near endpoints); "superellipse"/"bevel" - superellipse-adapted spacing with default exponent 5; "adaptive" - curvature-aware sampling that concentrates vertices in high-curvature regions of the spine. Map options: { type: "uniform" }, { type: "chebyshev" }, { type: "superellipse", exponent: N } - superellipse-adapted spacing where higher exponent concentrates samples more at endpoints (exponent=2 is similar to chebyshev, exponent>2 is progressively sharper), { type: "adaptive" } - adaptive curvature-based sampling. Also accepts: a sequence of floats - explicit t values in [0, 1] (length must match spine_resolution); a callable `|i: int|: float` - returns t value for each sample index. The t values are used both for sampling the spine/rail and as the `u` parameter passed to the profile function.
adaptive_profile_sampling : Bool Bool(true) - When true (default), uses curvature-aware adaptive sampling for profile rings. Concentrates vertices in high-curvature regions of the profile curve, often achieving equivalent visual quality with significantly fewer vertices. Only applies when using `dynamic_profile`. Can be overridden per-ring by returning `{ sampler: ..., adaptive: true/false }` from the dynamic_profile callable. Set to false to use uniform sampling.

remesh_planar_patches

remesh_planar_patches ( mesh : Mesh , max_angle_deg : Numeric Float(5) , max_offset : Nil | Numeric Nil ) : Mesh

Remeshes a mesh by identifying planar regions and simplifying them into a simpler set of triangles. This is useful for optimizing meshes produced by a variety of other built-in methods that tend to produce a lot of small triangles in flat areas. See the docs for the underlying CGAL function for more details: https://doc.cgal.org/5.6.3/Polygon_mesh_processing/index.html - Section 2.1.2 Remeshing

Arguments:

mesh : Mesh
max_angle_deg : Numeric Float(5) - Maximum angle in degrees between face normals for faces to be considered coplanar
max_offset : Nil | Numeric Nil - Maximum distance from the plane for faces to be considered coplanar. This is an absolute distance in the mesh's local space. If not provided or set to `nil`, it will default to 1% of the diagonal length of the mesh's bounding box.

rot

rot ( rotation : Vec3 , mesh : Mesh ) : Mesh

Rotates a mesh in local space using a Vec3 of Euler angles in radians (right-multiply: M = M * R). The rotation is relative to the object's current orientation.

Arguments:

rotation : Vec3 - Rotation defined by Euler angles in radians
mesh : Mesh - Mesh to rotate

rot ( x : Numeric , y : Numeric , z : Numeric , mesh : Mesh ) : Mesh

Rotates a mesh in local space using individual Euler angle components in radians (right-multiply: M = M * R).

Arguments:

x : Numeric - Rotation about X axis (radians)
y : Numeric - Rotation about Y axis (radians)
z : Numeric - Rotation about Z axis (radians)
mesh : Mesh - Mesh to rotate

rot ( rotation : Vec3 , light : Light ) : Light

Rotates a light in local space using a Vec3 of Euler angles in radians (right-multiply: M = M * R).

Arguments:

rotation : Vec3 - Rotation defined by Euler angles in radians
light : Light - Light to rotate

rot ( x : Numeric , y : Numeric , z : Numeric , light : Light ) : Light

Rotates a light in local space using individual Euler angle components in radians (right-multiply: M = M * R).

Arguments:

x : Numeric - Rotation about X axis (radians)
y : Numeric - Rotation about Y axis (radians)
z : Numeric - Rotation about Z axis (radians)
light : Light - Light to rotate

rot_around_center

rot_around_center ( rotation : Vec3 , mesh : Mesh ) : Mesh

Rotates a mesh around its current position (the translation component of its transform matrix). The object spins in place without changing its world-space position. Equivalent to: translate to origin, rotate, translate back.

Arguments:

rotation : Vec3 - Rotation defined by Euler angles in radians
mesh : Mesh - Mesh to rotate

rot_around_center ( x : Numeric , y : Numeric , z : Numeric , mesh : Mesh ) : Mesh

Rotates a mesh around its current position using individual Euler angle components in radians.

Arguments:

x : Numeric - Rotation about X axis (radians)
y : Numeric - Rotation about Y axis (radians)
z : Numeric - Rotation about Z axis (radians)
mesh : Mesh - Mesh to rotate

rot_around_center ( rotation : Vec3 , light : Light ) : Light

Rotates a light around its current position using a Vec3 of Euler angles in radians.

Arguments:

rotation : Vec3 - Rotation defined by Euler angles in radians
light : Light - Light to rotate

rot_around_center ( x : Numeric , y : Numeric , z : Numeric , light : Light ) : Light

Rotates a light around its current position using individual Euler angle components in radians.

Arguments:

x : Numeric - Rotation about X axis (radians)
y : Numeric - Rotation about Y axis (radians)
z : Numeric - Rotation about Z axis (radians)
light : Light - Light to rotate

rot_global

rot_global ( rotation : Vec3 , mesh : Mesh ) : Mesh

Rotates a mesh in world space around the world origin using a Vec3 of Euler angles in radians (left-multiply: M = R * M). This rotates both the object's orientation and its position around the origin.

Arguments:

rotation : Vec3 - Rotation defined by Euler angles in radians
mesh : Mesh - Mesh to rotate

rot_global ( x : Numeric , y : Numeric , z : Numeric , mesh : Mesh ) : Mesh

Rotates a mesh in world space around the world origin using individual Euler angle components in radians (left-multiply: M = R * M).

Arguments:

x : Numeric - Rotation about X axis (radians)
y : Numeric - Rotation about Y axis (radians)
z : Numeric - Rotation about Z axis (radians)
mesh : Mesh - Mesh to rotate

rot_global ( rotation : Vec3 , light : Light ) : Light

Rotates a light in world space around the world origin using a Vec3 of Euler angles in radians (left-multiply: M = R * M).

Arguments:

rotation : Vec3 - Rotation defined by Euler angles in radians
light : Light - Light to rotate

rot_global ( x : Numeric , y : Numeric , z : Numeric , light : Light ) : Light

Rotates a light in world space around the world origin using individual Euler angle components in radians (left-multiply: M = R * M).

Arguments:

x : Numeric - Rotation about X axis (radians)
y : Numeric - Rotation about Y axis (radians)
z : Numeric - Rotation about Z axis (radians)
light : Light - Light to rotate

sample_voxels

Example

dim = 50
dims = v3(dim)

lo = 0
hi = 50

sample_voxels(
  dims,
  |x: int, y: int, z: int| {
    // floor
    if y == lo && z % 2 == (round(x * 0.3) % 2) {
      return 1
    }

    // X structure with hole in middle
    m = x + round(sin(y * 0.48)*3)
    in_center = x >= 16 && x <= 34 && z >= 16 && z <= 34
    cond = !in_center
      && (
        z - y == 1 || (hi-z) - y == 1
        || z - y == 2 || (hi-z) - y == 2
        || z - y == 3 || (hi-z) - y == 3
      )
      && !(y > 40)
      && x > 10 && x < 40
    if cond {
      if m % 4 == 3 {
        return 2
      } else {
        return 1
      }
    }

    // central spire
    x = x-25
    z = z-25
    v = v2(x,z)
    r = 6 + 4 * smoothstep(30, 50, y) + sin(3.5 + y * 0.25) * 3
    if abs(len(v) - r) < 0.5 {
      return 3
    }

    return 0
  },
  ["default", "accent", "copper"],
  // false,
  // false
  // false
) | render

Open in editor

sample_voxels ( dims : Vec3 , cb : Callable , materials : Sequence | Nil Nil , cgal_remesh : Bool | Nil Nil , fill_internal_voids : Bool Bool(false) ) : Mesh |Sequence

Generates a mesh or sequence of meshes by sampling a 3D grid defined by `dims`. For each voxel in the grid, the provided callback will be called with the voxel's coordinate. If the callback returns 0, false, or nil, the voxel will be left empty. If it returns true or any non-zero integer, the voxel will be filled. Values > 1 will use material `n - 1` from the `materials` argument. A separate mesh will be generated for each unique material used. The generated meshes are guaranteed to be 2-manifold/watertight, meaning that they can be further processed by other builtins like `smooth`, `simplify`, CSG (`union`/`intersect`/etc.).

Arguments:

dims : Vec3 - The bounds of the voxel grid to sample
cb : Callable - A callable with signature `|x_ix: int, y_ix: int, z_ix: int|: bool | int | nil` that will be called for each voxel in the grid. Returning 0, false, or nil will leave the voxel empty. Returning true or any non-zero integer will fill the voxel. Values > 1 will use material `n - 1` from the `materials` argument. The maximum material index is 254.
materials : Sequence | Nil Nil - An optional sequence of materials to assign to filled voxels. The first material in the sequence will be used for voxels where the callback returns true or 1, the second material for voxels where the callback returns 2, and so on. If not provided or set to `nil`, all filled voxels will use the default material. The maximum number of materials is 254.
cgal_remesh : Bool | Nil Nil - Determines whether the generated mesh(es) will be remeshed using CGAL's `remesh_planar_patches` function. This produces better outputs with fewer faces and vertices, but takes more time to compute. If not provided or set to `nil`, this will be dynamically enabled/disabled for each output mesh depending on its vertex count.
fill_internal_voids : Bool Bool(false) - If true, internal voids in the generated meshes will be filled. This can help reduce face/vertex counts, but requires extra computation.

scale

scale ( x : Numeric , y : Numeric , z : Numeric , mesh : Mesh ) : Mesh

Scales a mesh in local space by separate factors along each axis (right-multiply: M = M * S).

Arguments:

x : Numeric
y : Numeric
z : Numeric
mesh : Mesh

scale ( scale : Vec3 | Numeric , mesh : Mesh ) : Mesh

Scales a mesh in local space (right-multiply: M = M * S). Accepts a Vec3 for non-uniform scaling or a number for uniform scaling.

Arguments:

scale : Vec3 | Numeric
mesh : Mesh

set_default_material

set_default_material ( material : String | Material ) : Nil

Sets the default material for all meshes that do not have a specific material set

Arguments:

material : String | Material - Can be either a `Material` value or a string specifying the name of an externally defined material

set_material

Example

box(5)
  | trans(5, 0, 0)
  // This requires a material called "red" to have been
  // defined in the material editor for the scene.
  //
  // This can be found in the hamburger menu next to the
  // home button.
  | set_material('red')
  | render

icosphere(radius=3, resolution=4)
  | trans(-5, 0, 0)
  // same for this one
  | set_material('blue')
  | render

Open in editor

set_material ( material : String | Material , mesh : Mesh ) : Mesh

Sets the material for a mesh

Arguments:

material : String | Material - Can be either a `Material` value or a string specifying the name of an externally defined material
mesh : Mesh

set_sharp_angle_threshold

set_sharp_angle_threshold ( angle_degrees : Numeric ) : Nil

Sets the sharp angle threshold for computing auto-smooth-shaded normals (specified in degrees). If the angle between two adjacent faces is greater than this angle, the edge will be considered sharp.

Arguments:

angle_degrees : Numeric - The angle at which edges are considered sharp, in degrees

simplify

simplify ( tolerance : Numeric Float(0.01) , mesh : Mesh ) : Mesh

Simplifies a mesh, reducing the number of vertices. Maintains manifold-ness.

Arguments:

tolerance : Numeric Float(0.01) - The maximum distance between the original and simplified meshes. 0.01 is a good starting point.
mesh : Mesh

smooth

smooth ( mesh : Mesh , type : String String(catmullclark) , iterations : Numeric Int(1) ) : Mesh

Smooths a mesh using the specified algorithm (defaults to catmullclark). More iterations result in a smoother mesh.

Arguments:

mesh : Mesh
type : String String(catmullclark) - Type of smoothing to perform. Supported values are "catmullclark", "loop", "doosabin", and "sqrt".
iterations : Numeric Int(1) - Number of smoothing iterations to perform

split_by_plane

Example

shape = box(10, 5, 10)
  | union(cyl(radius=4, height=8, radial_segments=40))

pieces: seq = shape
  | split_by_plane(
      plane_normal=vec3(1, -1, 1),
      plane_offset=0
    )

pieces = pieces -> |piece: mesh, i: int| {
  if i == 0 {
    piece | set_material('red')
  } else {
    piece | set_material('blue') | trans(0, 1, 0)
  }
}

render(pieces)

Open in editor

split_by_plane ( plane_normal : Vec3 , plane_offset : Numeric , mesh : Mesh ) : Sequence

Splits a mesh by a plane, returning a sequence containing two meshes: the part in front of the plane and the part behind the plane. This will apply all transforms on the mesh, and the returned meshes will have an identity transform.

Arguments:

plane_normal : Vec3 - Normal vector of the plane to cut the mesh with
plane_offset : Numeric - Offset of the plane from the origin along the plane normal
mesh : Mesh

stanford_bunny

alias: bunny

Example

stanford_bunny() | render

Open in editor

stanford_bunny ( ) : Mesh

Generates a Stanford bunny mesh, a well-known 3D model often used in computer graphics as a test object. This mesh IS manifold, so it can be used with functions that require a manifold mesh such as mesh boolean ops, `trace_geodesic_path`, and others.

stitch_contours

Example

height_segments = 40
resolution = 100
radius = 5

// creates a sequence of contours which encode the profile
// of the shape we're building from bottom to top
contours = 0..height_segments -> |y_ix| {
  0..resolution -> |i| {
    t = i / resolution
    // bulge the radius out, but at a different spot
    // depending on how far up the shape we are
    radius = radius + sin(y_ix * 0.5 + t * pi * 4) * 4

    // construct a path tracing the radius of the shape
    // at this height, basing it off the parametric
    // equation for a circle
    vec3(
      cos(t * pi * 2) * radius,
      y_ix * 2.25,
      sin(t * pi * 2) * radius
    )
  }
}

// join the contours into a closed 3D mesh by connecting
// them with a strip of triangles between each one.
contours
  // default options shown
  | stitch_contours(closed=true, cap_ends=true)
  | render

Open in editor

stitch_contours ( contours : Sequence , flipped : Bool Bool(false) , closed : Bool Bool(true) , cap_start : Bool Bool(false) , cap_end : Bool Bool(false) , cap_ends : Bool Bool(false) ) : Mesh

Stitches together a sequence of contours into a single mesh. The contours should be closed loops.

Arguments:

contours : Sequence - A `Seq<Seq<Vec3>>`, where each inner sequence contains points representing a contour that will be stitched together into a mesh
flipped : Bool Bool(false) - If true, the winding order of the triangles generated will be flipped - inverting the inside/outside of the generated mesh.
closed : Bool Bool(true) - If true, the contours will be stitched together as closed loops - connecting the last point to the first for each one.
cap_start : Bool Bool(false) - If true, a triangle fan will be created to cap the first contour
cap_end : Bool Bool(false) - If true, a triangle fan will be created to cap the last contour
cap_ends : Bool Bool(false) - shorthand for `cap_start=true, cap_end=true`

subdivide_by_line

alias: skewer

subdivide_by_line ( line_origin : Vec3 , line_dir : Vec3 , mesh : Mesh , eps : Numeric Float(0.0001) ) : Mesh

Skewers a mesh with an infinite line. Triangles whose interiors are intersected by the line are split into three fan triangles around the hit point. Hits coincident with an edge split the edge (and both adjacent triangles). Hits coincident with a vertex are no-ops. Aliased as `skewer`.

Arguments:

line_origin : Vec3 - A point on the line that skewers the mesh
line_dir : Vec3 - Direction of the line. Need not be unit-length; it will be normalized internally.
mesh : Mesh
eps : Numeric Float(0.0001) - World-space tolerance for snapping the hit point to a nearby vertex or edge. Larger values make the skewer more forgiving of near-coincident geometry; smaller values snap less aggressively.

subdivide_by_plane

subdivide_by_plane ( plane_normal : Vec3 , plane_offset : Numeric , mesh : Mesh ) : Sequence

Subdivides a mesh by a plane, splitting all edges and faces that intersect the plane.

Arguments:

plane_normal : Vec3 - Normal vector of the plane to cut the mesh with
plane_offset : Numeric - Offset of the plane from the origin along the plane normal
mesh : Mesh

subdivide_by_plane ( plane_normals : Sequence , plane_offsets : Sequence , mesh : Mesh ) : Sequence

Subdivides a mesh by a sequence of planes, splitting all edges and faces that intersect any of the planes. This is more efficient than repeatedly subdividing by a single plane multiple times.

Arguments:

plane_normals : Sequence - Sequence of normal vectors of the planes to cut the mesh with
plane_offsets : Sequence - Sequence of offsets of the planes from the origin along the plane normals
mesh : Mesh

tessellate

aliases: tess, subdivide

tessellate ( target_edge_length : Numeric , mesh : Mesh ) : Mesh

Tessellates a mesh, splitting edges to achieve a target edge length.

Arguments:

target_edge_length : Numeric
mesh : Mesh

tessellate_path

Tessellates a 2D path into a triangle mesh in the XZ plane. Path topology — subpaths and the holes they imply via nesting — is preserved by both backends. Build paths-with-holes by either using a multi-subpath path (e.g. `build_path(path { rect(...) rect(...) | reverse })`) or applying a Clipper2 boolean op upstream. CGAL refinement runs when either `max_edge_len` or `min_angle_degrees` is supplied; otherwise the raw constrained Delaunay triangulation is returned. Each constraint independently triggers splitting of triangles that violate it — a triangle is split if it has either an edge longer than `max_edge_len` OR an angle smaller than `min_angle_degrees`.

Arguments:

path : Callable | Sequence - A sequence of Vec2 points, a sequence of Vec2 sequences, or a callable `|t: num|: vec2` (preferably from `trace_path`).
flipped : Bool Bool(false) - If true, the winding order of the generated triangles will be flipped.
curve_angle_degrees : Numeric Float(1) - Max turning angle (degrees) per segment when discretizing trace_path curves.
sample_count : Nil | Numeric Nil - Maximum total number of output points across all subpaths. When provided, adaptively resamples the path to this count using curvature+arc-length weighting while preserving critical corners. When nil (default), uses the path's natural tessellation resolution.
closed : Bool | Nil Nil - Optional override for treating the input as closed. Tessellation always closes the path; passing closed=false will return an error.
fill_rule : String | Nil Nil - Fill rule used to identify the interior of the shape: "nonzero", "evenodd", "positive", or "negative". If nil, inherited from the path sampler (e.g. set via `trace_path`) and otherwise defaulting to "nonzero". The CGAL engine always uses nesting-based fill (equivalent to "evenodd"); requesting any winding-dependent rule ("nonzero"/"positive"/"negative") with multiple subpaths under CGAL is a runtime error. The lyon engine honors all four rules per its tessellator semantics.
engine : String | Nil Nil - Tessellation engine: "cgal" or "lyon". If nil (default), the engine is chosen automatically. - CGAL is preferred: cleaner topology (no T-junctions), supports holes via nesting (any number of subpaths), supports mesh refinement via `max_edge_len`. - lyon is chosen when a winding-dependent fill rule ("nonzero"/"positive"/"negative") is requested with multiple subpaths, since CGAL only implements nesting-based fill. Forcing engine="cgal" in a case lyon would be auto-selected is a runtime error.
max_edge_len : Nil | Numeric Nil - Upper bound on the length of any triangle edge after refinement. Triangles with a longer edge are split. When set together with `min_angle_degrees` or used with the default angle bound, drives the density of the refined mesh. CGAL-only; setting this with engine="lyon" is a runtime error.
min_angle_degrees : Nil | Numeric Nil - Lower bound (in degrees) on the smallest angle in any triangle after refinement. Triangles with a smaller angle are split. Range: [0, ~20.7]; 0 disables the shape criterion entirely (refinement then driven purely by `max_edge_len`). The upper limit comes from CGAL: Delaunay refinement only provably terminates for aspect bounds up to 0.125 (squared sine), i.e. min angle ≲ 20.7°. When this kwarg is omitted but `max_edge_len` is set, CGAL's default ~20.6° applies — narrow regions (e.g. slivers between holes) can then split well below `max_edge_len`. Pass 0 if you want only the edge-length constraint.

tetrahedron

tetrahedron ( radius : Numeric Float(1) ) : Mesh

Regular tetrahedron with circumradius `radius`, inscribed in the cube (sits edge-up).

Arguments:

radius : Numeric Float(1) - Circumradius (center-to-vertex distance)

text_to_mesh

Example

text = text_to_mesh(
  "Vanadium",
  font_weight=700,
  depth=200,
  font_family="IBM Plex Sans",
  height=7.5
)
  | rot(pi/2, 0, 0)
  | trans(-21, 1.5, -100);
(bunny() | scale(4)) - text | render

Open in editor

Generates a 2D path representing the given text string, triangulates it into a mesh, and optionally extrudes it into 3D. The generated mesh lies in the XZ plane, with Y being the up direction.

Arguments:

text : String
font_family : String String(IBM Plex Sans) - Font family to use for the text. Must exist on Google Fonts.
font_size : Numeric Float(24)
font_weight : String | Nil | Numeric Nil
font_style : String | Nil Nil - Must be one of "normal", "italic", or "oblique". If nil, defaults to "normal".
letter_spacing : Nil | Numeric Nil
width : Nil | Numeric Nil - Width of the generated mesh in world units along the X axis. If only one of `width` or `height` is provided, the other dimension will be scaled to maintain the aspect ratio of the text.
height : Nil | Numeric Nil - Height of the generated mesh in world units along the Z axis. If only one of `width` or `height` is provided, the other dimension will be scaled to maintain the aspect ratio of the text.
depth : Nil | Numeric Float(0.2) - Depth to extrude the text into a 3D mesh. If 0 or nil, will produce a flat 2D mesh in the XZ plane.

trace_geodesic_path

Example

c = cyl(radius=6, height=20, radial_segments=40)

// sequence of steps deltas to talk along the surface of
// the mesh
path = 0..20 -> || v2(3, 1);
surface_points: seq = trace_geodesic_path(
  path,
  c,
  full_path=false,
  start_pos_local_space=v3(10, -8, 0)
)

// cut out a cube from the surface of the mesh at each 
// step of the walk
fold(
  c,
  |c: mesh, pt: vec3| c - (box(2) + pt),
  surface_points
) | render

// adds a red directional light to better show off the
// carved out sections
dir_light(intensity=12, color=v3(1,0.3,0.1))
  | trans(40, 20, -10)
  | render

Open in editor

trace_geodesic_path ( path : Sequence , mesh : Mesh , world_space : Bool Bool(true) , full_path : Bool Bool(true) , start_pos_local_space : Vec3 | Nil Nil , up_dir_world_space : Vec3 Vec3(0, 1, 0) ) : Sequence

Traces a geodesic path across the surface of a mesh, following a sequence of 2D points. The mesh must be manifold. Returns a `Seq<Vec3>` of points on the surface of the mesh that were visited during the walk.

Arguments:

path : Sequence - A sequence of `Vec2` points representing movements to take across the surface of the mesh relative to the current position. For example, a sequence of `[vec2(0, 1), vec2(1, 0)]` would move 1 unit up and then 1 unit right.
mesh : Mesh
world_space : Bool Bool(true) - If true, points will be returned in world space. If false, they will be returned in the local space of the mesh.
full_path : Bool Bool(true) - This controls behavior when the path crosses between faces in the mesh. If true, intermediate points will be included in the output for whenever the path hits an edge. This can result in the output sequence having more elements than the input sequence, and it will ensure that all generated edges in the output path lie on the surface of the mesh.
start_pos_local_space : Vec3 | Nil Nil - If provided, the starting position for the path will be snapped to the surface of the mesh at this position. If `nil`, the walk will start at an arbitrary point on the mesh surface.
up_dir_world_space : Vec3 Vec3(0, 1, 0) - When the walk starts, it will be oriented such that the positive Y axis of the local tangent space is aligned as closely as possible with this up direction at the starting position. Another way of saying this is that it lets you set what direction is north when first starting the walk on the mesh's surface.

translate

alias: trans

Example

box(1) | render

box(1)
  | translate(0, 2, 0)
  | render

// you can also use a shorthand for translating meshes
box(1) + vec3(2, 0, 0) | render

Open in editor

translate ( translation : Vec3 , mesh : Mesh ) : Mesh

Translates a mesh in local space (right-multiply: M = M * T). The translation is relative to the object's current orientation. Alias: `trans`.

Arguments:

translation : Vec3
mesh : Mesh

translate ( x : Numeric , y : Numeric , z : Numeric , mesh : Mesh ) : Mesh

Translates a mesh in local space (right-multiply: M = M * T). Alias: `trans`.

Arguments:

x : Numeric
y : Numeric
z : Numeric
mesh : Mesh

translate ( translation : Vec3 , light : Light ) : Light

Translates a light in local space (right-multiply: M = M * T). The translation is relative to the light's current orientation. Alias: `trans`.

Arguments:

translation : Vec3
light : Light

translate ( x : Numeric , y : Numeric , z : Numeric , light : Light ) : Light

Translates a light in local space (right-multiply: M = M * T). Alias: `trans`.

Arguments:

x : Numeric
y : Numeric
z : Numeric
light : Light

translate_global

alias: trans_global

translate_global ( translation : Vec3 , mesh : Mesh ) : Mesh

Translates a mesh in world space (left-multiply: M = T * M). The translation is always along world axes regardless of the object's current orientation. Alias: `trans_global`.

Arguments:

translation : Vec3
mesh : Mesh

translate_global ( x : Numeric , y : Numeric , z : Numeric , mesh : Mesh ) : Mesh

Translates a mesh in world space (left-multiply: M = T * M). Alias: `trans_global`.

Arguments:

x : Numeric
y : Numeric
z : Numeric
mesh : Mesh

translate_global ( translation : Vec3 , light : Light ) : Light

Translates a light in world space (left-multiply: M = T * M). The translation is always along world axes regardless of the light's current orientation. Alias: `trans_global`.

Arguments:

translation : Vec3
light : Light

translate_global ( x : Numeric , y : Numeric , z : Numeric , light : Light ) : Light

Translates a light in world space (left-multiply: M = T * M). Alias: `trans_global`.

Arguments:

x : Numeric
y : Numeric
z : Numeric
light : Light

union

union ( a : Mesh , b : Mesh ) : Mesh

Returns the boolean union of two meshes (`a | b`)

Arguments:

a : Mesh
b : Mesh

union ( meshes : Sequence ) : Mesh

Returns the boolean union of a sequence of meshes (`meshes[0] | meshes[1] | ...`)

Arguments:

meshes : Sequence - Sequence of meshes to union

utah_teapot

alias: teapot

Example

utah_teapot() | render

Open in editor

utah_teapot ( ) : Mesh

Generates a Utah teapot mesh, a well-known 3D model often used in computer graphics as a test object. Note that the teapot is NOT manifold, so it cannot be used with functions that require a manifold mesh such as mesh boolean ops, `trace_geodesic_path`, and others.

verts

verts ( mesh : Mesh , world_space : Bool Bool(false) ) : Sequence

Returns a sequence of all vertices in a mesh in an arbitrary order

Arguments:

mesh : Mesh
world_space : Bool Bool(false) - If true, the vertices will be returned in world space coordinates. If false, they will be returned in the local space of the mesh.

warp

Example

icosphere(radius=8, resolution=4)
  // the position of each vertex in the mesh is set to
  // whatever this function returns.
  | warp(|pos: vec3, normal: vec3| {
    if pos.y >= 0 {
      return pos
    }

    // elongate and distort the bottom half of the sphere
    vec3(
      pos.x + sin(pos.y) * 1.5,
      pos.y * 2,
      pos.z + sin(pos.y) * 1.5
    )
  })
  | render

// warp also has a dedicated shorthand operator.  The
// following two statements are equivalent:

box(4) | warp(|pos| pos * 2)

box(4) -> |pos| pos * 2

Open in editor

warp ( fn : Callable , mesh : Mesh ) : Mesh

Applies a warp function to each vertex of the mesh, returning a new mesh with each vertex transformed by `fn`.

Arguments:

fn : Callable - Callable with signature `|pos: vec3, normal: vec3|: vec3`. Given the position and normal of each vertex in the mesh, returns a new position for that vertex in the output mesh.
mesh : Mesh

path

bezier3d

alias: bezier

bezier3d ( p0 : Vec3 , p1 : Vec3 , p2 : Vec3 , p3 : Vec3 , count : Numeric ) : Sequence

Generates a sequence of `count` evenly-spaced points along a cubic Bezier curve defined by four control points

Arguments:

p0 : Vec3
p1 : Vec3
p2 : Vec3
p3 : Vec3
count : Numeric

build_path

build_path ( cmds : Sequence , closed : Bool Bool(false) , center : Bool Bool(false) , reverse : Bool Bool(false) , fill_rule : String | Nil Nil ) : Callable

Builds a 2D path sampler from a sequence of draw command maps. The canonical input source is the `path { ... }` macro, which evaluates to a sequence of draw command maps. This function turns that sequence into a `|t: num|: vec2` callable, where `t` ranges over the path's arc length from 0 to 1. Values <0 or >1 will be clamped to the start or end of the path respectively. The resulting tracer preserves subpath identity — each `rect`, `circle`, or explicit `move`-delimited run becomes its own subpath. Multi-subpath paths are consumed correctly by boolean ops, tessellation, and the various sampling builtins.

Arguments:

cmds : Sequence - A sequence of draw command maps as produced by the `path { ... }` macro or hand-built via `path_move`, `path_line`, `path_close`, `path_arc`, etc.
closed : Bool Bool(false) - If true, each subpath is closed by connecting the last point back to the first.
center : Bool Bool(false) - If true, the path is centered around the origin after construction.
reverse : Bool Bool(false) - If true, the path is sampled in reverse direction. Applies to the whole path uniformly. To reverse the winding of individual subpaths (e.g. to mark some `rect`/`circle` subpaths as holes), use `path_reverse` / `| reverse` on the relevant draw commands inside the `path { ... }` block.
fill_rule : String | Nil Nil - Optional fill rule: "nonzero", "evenodd", "positive", "negative", or nil. Consumed only by downstream operations that respect it (Clipper2 boolean ops; lyon tessellation). The CGAL tessellation engine uses nesting-based domain identification regardless of this value.

catmull_rom

catmull_rom ( points : Sequence , tension : Numeric Float(0.5) , closed : Bool Bool(false) ) : Callable

Returns a path sampler callable `|t: float|: vec2` that evaluates a Catmull-Rom spline through the given 2D control points. The spline passes through every control point. All interior joints are C1 smooth; only the endpoints of an open spline are non-smooth. `tension` generalises to the full cardinal spline family (`0.5` = standard Catmull-Rom).

Arguments:

points : Sequence - Sequence of `vec2` control points the spline passes through.
tension : Numeric Float(0.5) - Tangent scale factor. `0.5` (default) gives standard Catmull-Rom. Higher values produce more pronounced curves; `0.0` produces a linear interpolation between points.
closed : Bool Bool(false) - If true, the spline wraps from the last control point back to the first, forming a closed loop.

catmull_rom_3d

catmull_rom_3d ( points : Sequence , tension : Numeric Float(0.5) , closed : Bool Bool(false) ) : Callable

Returns a callable `|t: float|: vec3` that evaluates a Catmull-Rom spline through the given 3D control points. The spline passes through every control point. All interior joints are C1 smooth; only the endpoints of an open spline are non-smooth. `tension` generalises to the full cardinal spline family (`0.5` = standard Catmull-Rom).

Arguments:

points : Sequence - Sequence of `vec3` control points the spline passes through.
tension : Numeric Float(0.5) - Tangent scale factor. `0.5` (default) gives standard Catmull-Rom. Higher values produce more pronounced curves; `0.0` produces a linear interpolation between points.
closed : Bool Bool(false) - If true, the spline wraps from the last control point back to the first, forming a closed loop.

critical_points

critical_points ( path : Callable ) : Sequence

Returns the critical t values of a path sampler as a sequence of floats. Critical points are parameter values where sharp features (corners, segment boundaries) occur. Only works with path samplers that have topology information.

Arguments:

path : Callable - A path sampler callable (e.g. from trace_path, offset_path, lerp_paths).

discretize_path

discretize_path ( path : Callable , curve_angle_degrees : Numeric Float(1) , sample_count : Numeric Int(128) , closed : Bool | Nil Nil ) : Callable

Replaces every continuous curve in the input path with a polyline of straight line segments, returning a new path sampler. This is the same discretization step that `path_union` / `offset_path` apply internally before handing geometry to Clipper2; running it explicitly is useful for inspecting the polyline that those operations would see, or for paths where polyline-only consumers need a guaranteed-segment-only input. Uses adaptive curvature-based sampling driven by `curve_angle_degrees` for paths backed by a path tracer. For black-box callables, falls back to uniform sampling at `sample_count` points.

Arguments:

path : Callable - A path sampler callable. Topology-aware paths use adaptive curvature sampling; black-box `|t: num|: vec2` callables fall back to uniform sampling.
curve_angle_degrees : Numeric Float(1) - Max turning angle (degrees) per segment when discretizing curves.
sample_count : Numeric Int(128) - Uniform sample count for black-box callables that don't expose topology.
closed : Bool | Nil Nil - Optional override for treating the input as closed/open. When nil, the input's existing topology is preserved (or inferred from `p(0) ≈ p(1)` for black-box callables).

fillet_path

fillet_path ( path : Sequence , radius : Callable | Numeric , resolution : Numeric Int(8) , clamp_radius : Bool Bool(true) , closed : Bool Bool(false) ) : Sequence

Smooths the interior corners of a 2D polyline by replacing each corner with a circular-arc fillet of the requested radius. Collinear vertices, U-turns, and zero-length segments pass through unmodified. Returns a new sequence of `vec2` points (the original endpoints are preserved when `closed=false`).

Arguments:

path : Sequence - Sequence of `vec2` points defining a polyline whose interior corners will be smoothed.
radius : Callable | Numeric - Target radius of the inscribed circle at each corner. Either a number (constant for every corner) or a callable `|corner_ix: int, vertex: vec2|: float` that returns a per-corner radius.
resolution : Numeric Int(8) - Number of arc segments generated per filleted corner. Higher values produce smoother bends. Each corner replaces 1 input vertex with `resolution + 1` output vertices.
clamp_radius : Bool Bool(true) - When true, automatically reduces the per-corner radius so that the fillet's tangent points never cross the midpoint of an adjacent segment. When false, an error is raised if the requested radius is too large for a given corner.
closed : Bool Bool(false) - If true, the path is treated as a closed loop and the wrap-around corner between the last and first points is also filleted.

fillet_path_3d

fillet_path_3d ( path : Sequence , radius : Callable | Numeric , resolution : Numeric Int(8) , clamp_radius : Bool Bool(true) , closed : Bool Bool(false) ) : Sequence

Smooths the interior corners of a 3D polyline by replacing each corner with a true circular-arc fillet of the requested radius (lying in the plane of the bend). Collinear vertices, U-turns, and zero-length segments pass through unmodified. Returns a new sequence of `vec3` points (the original endpoints are preserved when `closed=false`). Designed to be piped directly into `extrude_pipe` or other path-consuming builtins.

Arguments:

path : Sequence - Sequence of `vec3` points defining a polyline whose interior corners will be smoothed. Often piped directly into `extrude_pipe`.
radius : Callable | Numeric - Target radius of the inscribed circle at each corner. Either a number (constant for every corner) or a callable `|corner_ix: int, vertex: vec3|: float` that returns a per-corner radius.
resolution : Numeric Int(8) - Number of arc segments generated per filleted corner. Higher values produce smoother bends. Each corner replaces 1 input vertex with `resolution + 1` output vertices.
clamp_radius : Bool Bool(true) - When true, automatically reduces the per-corner radius so that the fillet's tangent points never cross the midpoint of an adjacent segment. When false, an error is raised if the requested radius is too large for a given corner.
closed : Bool Bool(false) - If true, the path is treated as a closed loop and the wrap-around corner between the last and first points is also filleted.

lerp_paths

lerp_paths ( path_a : Callable , path_b : Callable , mix : Numeric , sample_count : Numeric Int(64) ) : Callable

Interpolates between two path samplers, returning a new path callable. At each `t`, the output point is `lerp(path_a(t), path_b(t), mix)`. Critical points from both input paths are merged to preserve sharp features during interpolation.

Arguments:

path_a : Callable - First path sampler callable of signature `|t: float|: vec2`.
path_b : Callable - Second path sampler callable of signature `|t: float|: vec2`.
mix : Numeric - Interpolation factor [0, 1]. 0 returns path_a, 1 returns path_b.
sample_count : Numeric Int(64) - Fallback critical point resolution when inputs lack topology data.

lissajous_knot_path

Example

lissajous_knot_path(
  amp=vec3(18),
  freq=vec3(3, 5, 7),
  phase=vec3(0,pi/2,pi/5),
  count=500
)
  | extrude_pipe(radius=1,connect_ends=true, resolution=8)
  | render

Open in editor

lissajous_knot_path ( amp : Vec3 Vec3(1, 1, 1) , freq : Vec3 Vec3(3, 5, 7) , phase : Vec3 Vec3(0, 1.5707964, 0.62831855) , count : Numeric ) : Sequence

Generates a sequence of points defining a Lissajous knot path

Arguments:

amp : Vec3 Vec3(1, 1, 1) - Amplitude of the Lissajous curve in each axis
freq : Vec3 Vec3(3, 5, 7) - Frequency of the Lissajous curve in each axis. These should be "pairwise-coprime" integers, meaning that the ratio of any two frequencies should not be reducible to a simpler fraction.
phase : Vec3 Vec3(0, 1.5707964, 0.62831855) - Phase offset of the Lissajous curve in each axis
count : Numeric - Number of points to sample along the path

offset_path

offset_path ( path : Callable , delta : Numeric , join_type : String | Numeric String(round) , end_type : String | Numeric String(round) , miter_limit : Numeric Float(2) , arc_tolerance : Numeric Float(0) , preserve_collinear : Bool Bool(false) , reverse_solution : Bool Bool(false) , step_count : Numeric Int(0) , superellipse_exponent : Numeric Float(2.5) , end_extension_scale : Numeric Float(1) , arrow_back_sweep : Numeric Float(0) , teardrop_pinch : Numeric Float(0.5) , join_angle_threshold : Numeric Float(0) , chebyshev_spacing : Bool Bool(false) , simplify_epsilon : Numeric Float(0.0001) , curve_angle_degrees : Numeric Float(1) , sample_count : Numeric Int(128) , closed : Bool | Nil Nil ) : Callable

Offsets a 2D path using Clipper2 and returns a new path sampler. Note: continuous curve detail is lost; the output is a polyline representation.

Arguments:

path : Callable - A path sampler callable of signature `|t: num|: vec2`. Use `trace_path` for topology-aware sampling.
delta : Numeric - Offset distance (positive inflates, negative deflates).
join_type : String | Numeric String(round) - Join type at corners: square, bevel, round, miter, superellipse, knob, step, spike (or numeric enum).
end_type : String | Numeric String(round) - End cap type for open paths: polygon, joined, butt, square, round, superellipse, triangle, arrow, teardrop (or numeric enum).
miter_limit : Numeric Float(2) - Miter limit for sharp corners.
arc_tolerance : Numeric Float(0) - Arc tolerance for round joins.
preserve_collinear : Bool Bool(false) - If true, preserve collinear vertices during offset.
reverse_solution : Bool Bool(false) - If true, reverse output path orientation.
step_count : Numeric Int(0) - Number of steps for stepped joins/caps.
superellipse_exponent : Numeric Float(2.5) - Superellipse exponent for superellipse joins/caps.
end_extension_scale : Numeric Float(1) - Scale for open end caps.
arrow_back_sweep : Numeric Float(0) - Arrow back sweep for arrow end caps.
teardrop_pinch : Numeric Float(0.5) - Teardrop pinch amount for teardrop end caps.
join_angle_threshold : Numeric Float(0) - Angle threshold used by some join types.
chebyshev_spacing : Bool Bool(false) - If true, use Chebyshev spacing for round joins.
simplify_epsilon : Numeric Float(0.0001) - Epsilon for pre-offset simplification (0 disables).
curve_angle_degrees : Numeric Float(1) - Max turning angle (degrees) per segment when discretizing curves.
sample_count : Numeric Int(128) - Uniform sample count for non-trace_path callables.
closed : Bool | Nil Nil - Optional override for treating the input as closed/open.

path_aabb

path_aabb ( path : Callable ) : Sequence

Returns the exact axis-aligned bounding box of a 2D path as a 2-element sequence `[mins, maxs]` of Vec2 corners. The bound is computed analytically from the path's line segments, beziers, and arcs (exact modulo floating-point rounding) — not from a polyline discretization. Any transforms applied to the path are baked in. Errors if the path is empty, or if it contains arc segments under a non-uniform transform (skew or non-uniform scale), since transformed arcs are conics with no closed-form axis-aligned bound; bake the transform with `apply_transforms` first in that case.

Arguments:

path : Callable - A path sampler with analytic segment topology (e.g. from `path { ... }`, `trace_path`, `trace_svg_path`, `text_to_path`).

path_arc

path_arc ( rx : Numeric , ry : Numeric , x_axis_rotation : Numeric , large_arc_flag : Bool , sweep_flag : Bool , x : Numeric , y : Numeric ) : Map

Builds an SVG-style elliptical arc draw command tagged dict for use inside a `path { ... }` block.

Arguments:

rx : Numeric - X-axis radius
ry : Numeric - Y-axis radius
x_axis_rotation : Numeric - Rotation of the arc's x-axis in degrees
large_arc_flag : Bool
sweep_flag : Bool
x : Numeric
y : Numeric

path_arc ( rx : Numeric , ry : Numeric , x_axis_rotation : Numeric , large_arc_flag : Bool , sweep_flag : Bool , to : Vec2 ) : Map

Builds an SVG-style elliptical arc draw command tagged dict for use inside a `path { ... }` block.

Arguments:

rx : Numeric - X-axis radius
ry : Numeric - Y-axis radius
x_axis_rotation : Numeric - Rotation of the arc's x-axis in degrees
large_arc_flag : Bool
sweep_flag : Bool
to : Vec2

path_arc ( rx : Numeric , ry : Numeric , x_axis_rotation : Numeric , x : Numeric , y : Numeric ) : Map

Builds an SVG-style elliptical arc draw command tagged dict. When flags are omitted, `large_arc_flag` defaults to false and `sweep_flag` defaults to true.

Arguments:

rx : Numeric - X-axis radius
ry : Numeric - Y-axis radius
x_axis_rotation : Numeric - Rotation of the arc's x-axis in degrees
x : Numeric
y : Numeric

path_arc ( rx : Numeric , ry : Numeric , x_axis_rotation : Numeric , to : Vec2 ) : Map

Builds an SVG-style elliptical arc draw command tagged dict. When flags are omitted, `large_arc_flag` defaults to false and `sweep_flag` defaults to true.

Arguments:

rx : Numeric - X-axis radius
ry : Numeric - Y-axis radius
x_axis_rotation : Numeric - Rotation of the arc's x-axis in degrees
to : Vec2

path_circle

path_circle ( center : Vec2 , radius : Numeric ) : Map

Builds a `circle` draw command tagged dict for use inside a `path { ... }` block. Traced CCW (math Y-up) starting at the rightmost point: right -> top -> left -> bottom -> right. Pipe through `reverse` (i.e. `circle(...) | reverse`) to flip to CW winding, which is the convention for holes under `nonzero`/`positive`/`negative` fill rules. Winding is not significant under `evenodd` or the CGAL tessellation engine, which identify holes by nesting depth.

Arguments:

center : Vec2 - Center of the circle.
radius : Numeric - Radius of the circle.

path_circle ( cx : Numeric , cy : Numeric , radius : Numeric ) : Map

Arguments:

cx : Numeric - X coordinate of the center of the circle.
cy : Numeric - Y coordinate of the center of the circle.
radius : Numeric - Radius of the circle.

path_close

path_close ( ) : Map

Builds a `close` draw command tagged dict. Closes the current subpath by drawing a straight line from the current point back to the initial point of the subpath (the position of the last `move` command). Mirrors the SVG `z` command.

path_cubic_bezier

path_cubic_bezier ( ctrl1 : Vec2 , ctrl2 : Vec2 , to : Vec2 ) : Map

Builds a cubic Bezier draw command tagged dict for use inside a `path { ... }` block.

Arguments:

ctrl1 : Vec2
ctrl2 : Vec2
to : Vec2

path_cubic_bezier ( c1x : Numeric , c1y : Numeric , c2x : Numeric , c2y : Numeric , x : Numeric , y : Numeric ) : Map

Builds a cubic Bezier draw command tagged dict for use inside a `path { ... }` block.

Arguments:

c1x : Numeric
c1y : Numeric
c2x : Numeric
c2y : Numeric
x : Numeric
y : Numeric

path_difference

path_difference ( subject : Callable , clip : Callable , fill_rule : String | Nil | Numeric Nil , curve_angle_degrees : Numeric Float(1) , sample_count : Numeric Int(64) , closed : Bool | Nil Nil , engine : String | Nil Nil ) : Callable

Computes the difference of two 2D paths (subject minus clip). The result contains areas inside subject but not inside clip. See `path_union` for the full fill-rule and engine reference; the same conventions apply here.

Arguments:

subject : Callable - The first path sampler callable of signature `|t: num|: vec2`.
clip : Callable - The second path sampler callable of signature `|t: num|: vec2`.
fill_rule : String | Nil | Numeric Nil - Fill rule for determining path interiors: evenodd, nonzero, positive, negative (or numeric enum 0-3). Defaults to `nonzero` for the `clipper` engine and `evenodd` for `cgal` (the only rule `cgal` accepts).
curve_angle_degrees : Numeric Float(1) - Max turning angle (degrees) per segment when discretizing curves.
sample_count : Numeric Int(64) - Uniform sample count for non-trace_path callables.
closed : Bool | Nil Nil - Optional override for treating the inputs as closed/open.
engine : String | Nil Nil - Backend: `clipper` (default; fast, fixed-point) or `cgal` (slower, exact-arithmetic).

path_frame

path_frame ( t : Numeric , path : Callable , inward_normal : Bool Bool(true) ) : Map

Samples a path at parameter `t` and returns a frame dict `{pos: vec2, tangent: vec2, normal: vec2}`. - `pos`: the path point `p(t)`. - `tangent`: a unit vector along the path direction, computed via central finite difference (with one-sided fallback at t=0 and t=1). - `normal`: a unit vector perpendicular to the tangent. By default it's the left-perpendicular (counter-clockwise rotation by 90°). For closed subpaths whose orientation can be determined, it is flipped to consistently point inward when `inward_normal` is true. Useful for sweeps, ribbons, offset constructions, or any procedural geometry that needs to follow a path with a consistent local frame.

Arguments:

t : Numeric - Arc-length parameter in [0, 1]; clamped if out of range.
path : Callable - Path sampler callable of signature `|t: num|: vec2`.
inward_normal : Bool Bool(true) - When true and `t` lies inside a closed subpath whose orientation can be determined, the normal is flipped to point inward (toward the interior of the closed shape) regardless of CW/CCW winding. For open subpaths or paths without topology, has no effect — the normal is the left-perpendicular of the tangent.

path_intersect

path_intersect ( subject : Callable , clip : Callable , fill_rule : String | Nil | Numeric Nil , curve_angle_degrees : Numeric Float(1) , sample_count : Numeric Int(64) , closed : Bool | Nil Nil , engine : String | Nil Nil ) : Callable

Computes the intersection of two 2D paths. The intersection contains only areas inside both paths. See `path_union` for the full fill-rule and engine reference; the same conventions apply here.

Arguments:

subject : Callable - The first path sampler callable of signature `|t: num|: vec2`.
clip : Callable - The second path sampler callable of signature `|t: num|: vec2`.
fill_rule : String | Nil | Numeric Nil - Fill rule for determining path interiors: evenodd, nonzero, positive, negative (or numeric enum 0-3). Defaults to `nonzero` for the `clipper` engine and `evenodd` for `cgal` (the only rule `cgal` accepts).
curve_angle_degrees : Numeric Float(1) - Max turning angle (degrees) per segment when discretizing curves.
sample_count : Numeric Int(64) - Uniform sample count for non-trace_path callables.
closed : Bool | Nil Nil - Optional override for treating the inputs as closed/open.
engine : String | Nil Nil - Backend: `clipper` (default; fast, fixed-point) or `cgal` (slower, exact-arithmetic).

path_intersects

path_intersects ( a : Callable , b : Callable , fill_rule : String | Numeric String(nonzero) , curve_angle_degrees : Numeric Float(1) , sample_count : Numeric Int(64) , closed : Bool | Nil Nil ) : Bool

Returns `true` if the two 2D path regions overlap under the given fill rule, `false` otherwise. Detects both cases where path segments cross and cases where one path is fully contained inside the other. Uses Clipper2's region intersection internally, so winding order and the chosen fill rule determine what counts as interior. Only supported for path samplers with known topology (e.g. from `path { ... }`, `trace_path`, `trace_svg_path`, `text_to_path`, `lerp_path`, `catmull_rom`); generic black-box `|t|: vec2` callables raise an error.

Arguments:

a : Callable - The first path sampler. Must be a callable with known topology (e.g. from `path { ... }`, `trace_path`, `trace_svg_path`, `text_to_path`, `lerp_path`, `catmull_rom`); black-box `|t|: vec2` callables are rejected.
b : Callable - The second path sampler. Same restriction as `a`.
fill_rule : String | Numeric String(nonzero) - Fill rule used to determine the interior of each path when checking for overlap: evenodd, nonzero, positive, negative (or numeric enum 0-3).
curve_angle_degrees : Numeric Float(1) - Max turning angle (degrees) per segment when discretizing curves.
sample_count : Numeric Int(64) - Uniform sample count fallback for path samplers without curvature-adaptive sampling.
closed : Bool | Nil Nil - Optional override for treating the inputs as closed/open.

path_join

path_join ( path1 : Callable , path2 : Callable ) : Callable

Joins two paths by structurally concatenating their subpath arrays. Avoids the Clipper2 round-trip used by `path_union`/`path_difference` etc.; appropriate when the inputs are known not to overlap. Both inputs must be path samplers with identity transforms. Apply `apply_transforms` first to bake non-identity transforms into geometry before joining. The returned path inherits the `fill_rule` of the first input that has one; conflicting fill rules raise an error.

Arguments:

path1 : Callable - First path sampler (from `build_path`, `trace_svg_path`, etc.).
path2 : Callable - Second path sampler (from `build_path`, `trace_svg_path`, etc.).

path_line

path_line ( x : Numeric , y : Numeric ) : Map

Builds a `line` draw command tagged dict for use inside a `path { ... }` block (which rewrites bare `line` calls to `path_line`).

Arguments:

x : Numeric
y : Numeric

path_line ( pos : Vec2 ) : Map

Builds a `line` draw command tagged dict for use inside a `path { ... }` block.

Arguments:

pos : Vec2

path_move

path_move ( x : Numeric , y : Numeric ) : Map

Builds a `move` draw command tagged dict for use inside a `path { ... }` block (which rewrites bare `move` calls to `path_move`). Equivalent to writing `move(x, y)` inside the block.

Arguments:

x : Numeric
y : Numeric

path_move ( pos : Vec2 ) : Map

Builds a `move` draw command tagged dict for use inside a `path { ... }` block.

Arguments:

pos : Vec2

path_quadratic_bezier

path_quadratic_bezier ( ctrl : Vec2 , to : Vec2 ) : Map

Builds a quadratic Bezier draw command tagged dict for use inside a `path { ... }` block.

Arguments:

ctrl : Vec2
to : Vec2

path_quadratic_bezier ( cx : Numeric , cy : Numeric , x : Numeric , y : Numeric ) : Map

Builds a quadratic Bezier draw command tagged dict for use inside a `path { ... }` block.

Arguments:

cx : Numeric
cy : Numeric
x : Numeric
y : Numeric

path_rect

path_rect ( center : Vec2 , size : Vec2 | Numeric ) : Map

Builds a `rect` draw command tagged dict for use inside a `path { ... }` block. Emitted as a closed subpath of four line segments. Traced CCW (math Y-up) starting at the top-right corner: top-right -> top-left -> bottom-left -> bottom-right -> top-right. Pipe through `reverse` (i.e. `rect(...) | reverse`) to flip to CW winding, which is the convention for holes under `nonzero`/`positive`/`negative` fill rules. Winding is not significant under `evenodd` or the CGAL tessellation engine, which identify holes by nesting depth.

Arguments:

center : Vec2 - Center of the rectangle.
size : Vec2 | Numeric - Size of the rectangle as a `vec2` of `(width, height)`, or a single number for a square.

path_rect ( cx : Numeric , cy : Numeric , width : Numeric , height : Numeric ) : Map

Arguments:

cx : Numeric - X coordinate of the center of the rectangle.
cy : Numeric - Y coordinate of the center of the rectangle.
width : Numeric - Width along the X axis.
height : Numeric - Height along the Y axis.

path_reflect

path_reflect ( axis : Vec2 , path : Callable ) : Callable

Reflects a 2D path across the line running through the origin in the `axis` direction, returning a new path sampler with the transform composed.

Arguments:

axis : Vec2 - Direction of the mirror line (need not be normalized).
path : Callable - Path sampler callable of signature `|t: num|: vec2`.

path_reflect ( axis : Vec2 , offset : Numeric , path : Callable ) : Callable

Reflects a 2D path across the line running in the `axis` direction, shifted perpendicular from the origin by `offset`, returning a new path sampler with the transform composed.

Arguments:

axis : Vec2 - Direction of the mirror line (need not be normalized).
offset : Numeric - Signed perpendicular offset of the mirror line from the origin, measured along the normal `(-axis.y, axis.x)`.
path : Callable - Path sampler callable of signature `|t: num|: vec2`.

path_reflect_x

path_reflect_x ( path : Callable ) : Callable

Reflects a 2D path across the x-axis (negating y), returning a new path sampler with the transform composed.

Arguments:

path : Callable - Path sampler callable of signature `|t: num|: vec2`.

path_reflect_x ( offset : Numeric , path : Callable ) : Callable

Reflects a 2D path across the horizontal line `y = offset`, returning a new path sampler with the transform composed.

Arguments:

offset : Numeric - Y position of the horizontal mirror line.
path : Callable - Path sampler callable of signature `|t: num|: vec2`.

path_reflect_y

path_reflect_y ( path : Callable ) : Callable

Reflects a 2D path across the y-axis (negating x), returning a new path sampler with the transform composed.

Arguments:

path : Callable - Path sampler callable of signature `|t: num|: vec2`.

path_reflect_y ( offset : Numeric , path : Callable ) : Callable

Reflects a 2D path across the vertical line `x = offset`, returning a new path sampler with the transform composed.

Arguments:

offset : Numeric - X position of the vertical mirror line.
path : Callable - Path sampler callable of signature `|t: num|: vec2`.

path_reverse

path_reverse ( path : Callable | Map ) : Map |Callable

Reverses the winding of a path. For a `rect` or `circle` draw command, toggles its `reversed` flag so the shape is traced in the opposite direction (same start point, opposite orientation). For a path tracer callable, returns a new tracer with the whole-path `reverse` flag toggled. Useful for building paths-with-holes: the standard convention is that an outer shape and its enclosed holes have opposite winding. Under the CGAL tessellation engine, winding doesn't matter (holes are identified by nesting), but reversing is still required when feeding the path through fill rules that depend on winding (`nonzero`, `positive`, `negative`). Does not accept bare point sequences — to reverse a `Sequence<Vec2>`, use a sequence operation directly. Aliased to `reverse` inside `path { ... }` blocks.

Arguments:

path : Callable | Map - Either a `rect`/`circle` draw command tagged dict (built by `rect` / `circle` inside a `path { ... }` block) or a path tracer callable (from `build_path`, `trace_svg_path`, `text_to_path`, etc.).

path_rot

path_rot ( angle : Numeric , path : Callable ) : Callable

Rotates a 2D path around the origin by the given angle (radians), returning a new path sampler with the transform composed.

Arguments:

angle : Numeric - Rotation angle in radians.
path : Callable - Path sampler callable of signature `|t: num|: vec2`.

path_scale

path_scale ( scale : Vec2 | Numeric , path : Callable ) : Callable

Scales a 2D path, returning a new path sampler with the transform composed.

Arguments:

scale : Vec2 | Numeric - Scale factor as a vec2 (non-uniform) or number (uniform).
path : Callable - Path sampler callable of signature `|t: num|: vec2`.

path_scale ( x : Numeric , y : Numeric , path : Callable ) : Callable

Scales a 2D path by (x, y), returning a new path sampler with the transform composed.

Arguments:

x : Numeric - X scale factor.
y : Numeric - Y scale factor.
path : Callable - Path sampler callable of signature `|t: num|: vec2`.

path_segments

path_segments ( path : Callable ) : Sequence

Returns a sequence of tagged dicts, one per segment of the path, in subpath traversal order with the path's transform applied. Every segment dict has these common fields: - `type`: `"line"` | `"quad"` | `"cubic"` | `"arc"` - `start`, `end`: vec2 endpoints - `length`: arc length of the segment - `subpath`: int — index of the parent subpath - `closed`: bool — whether the parent subpath is closed - `t_start`, `t_end`: floats in [0, 1] — arc-length parameters within the parent subpath - `t_start_global`, `t_end_global`: floats in [0, 1] — arc-length parameters across the full path Per-type extras: - `quad`: `ctrl: vec2` - `cubic`: `ctrl1: vec2`, `ctrl2: vec2` - `arc`: `center: vec2`, `rx: num`, `ry: num`, `x_axis_rotation: num` (radians), `large_arc: bool`, `sweep: bool`, `theta_start: num`, `theta_delta: num` The path's `reverse` flag is a sampling-order concern and is intentionally not honoured here; segments are always emitted in their as-built order. Only works with paths that expose segment topology (i.e. those backed by a path tracer); paths from `catmull_rom` / `lerp_paths` are not supported.

Arguments:

path : Callable - Path sampler from `build_path` / `trace_svg_path` / `text_to_path` / `offset_path` / boolean ops.

path_smooth_cubic_bezier

path_smooth_cubic_bezier ( ctrl2 : Vec2 , to : Vec2 ) : Map

Builds a smooth cubic Bezier draw command tagged dict for use inside a `path { ... }` block.

Arguments:

ctrl2 : Vec2
to : Vec2

path_smooth_cubic_bezier ( c2x : Numeric , c2y : Numeric , x : Numeric , y : Numeric ) : Map

Builds a smooth cubic Bezier draw command tagged dict for use inside a `path { ... }` block.

Arguments:

c2x : Numeric
c2y : Numeric
x : Numeric
y : Numeric

path_smooth_quadratic_bezier

path_smooth_quadratic_bezier ( to : Vec2 ) : Map

Builds a smooth quadratic Bezier draw command tagged dict for use inside a `path { ... }` block.

Arguments:

to : Vec2

path_smooth_quadratic_bezier ( x : Numeric , y : Numeric ) : Map

Builds a smooth quadratic Bezier draw command tagged dict for use inside a `path { ... }` block.

Arguments:

x : Numeric
y : Numeric

path_trans

path_trans ( offset : Vec2 , path : Callable ) : Callable

Translates a 2D path by the given offset, returning a new path sampler with the transform composed.

Arguments:

offset : Vec2 - Translation offset as a vec2.
path : Callable - Path sampler callable of signature `|t: num|: vec2`.

path_trans ( x : Numeric , y : Numeric , path : Callable ) : Callable

Translates a 2D path by (x, y), returning a new path sampler with the transform composed.

Arguments:

x : Numeric - X translation.
y : Numeric - Y translation.
path : Callable - Path sampler callable of signature `|t: num|: vec2`.

path_union

path_union ( subject : Callable , clip : Callable , fill_rule : String | Nil | Numeric Nil , curve_angle_degrees : Numeric Float(1) , sample_count : Numeric Int(64) , closed : Bool | Nil Nil , engine : String | Nil Nil ) : Callable

Computes the union of two 2D paths. The union contains all areas inside either path. Which regions count as "inside" depends on `fill_rule` (default `nonzero`): - `nonzero`: a point is inside if the signed-crossing count of a ray from it to infinity is non-zero. Inner subpaths must wind opposite to outer subpaths to register as holes. - `evenodd`: a point is inside if the unsigned crossing count is odd. Winding direction is ignored; holes arise purely from nesting. - `positive` / `negative`: like `nonzero` but keep only regions with positive or negative winding number respectively. **Engine selection** (`engine` kwarg, default `clipper`): - `clipper`: Clipper2, fast but operates in fixed-point internally so float coordinates are quantized and exact-coincident points may shift slightly. This can cause T-junctions and tiny gaps in the output topology that break downstream operations like 2-manifold extrusion. - `cgal`: CGAL `Polygon_set_2` over `Exact_predicates_exact_constructions_kernel`; exact arithmetic preserves coincident edges precisely. Slower (often 10–100×) but produces clean topology suitable for `extrude` / `tessellate_path`. Only `evenodd` fill rule is supported; within each input, subpaths combine under XOR (matching the nesting-based fill model). For paths built procedurally as non-overlapping subpaths (e.g. an outer shape plus enclosed holes), skip the boolean op entirely and pass the multi-subpath path directly to downstream consumers — they will treat nested subpaths as holes under their own fill rule.

Arguments:

subject : Callable - The first path sampler callable of signature `|t: num|: vec2`.
clip : Callable - The second path sampler callable of signature `|t: num|: vec2`.
fill_rule : String | Nil | Numeric Nil - Fill rule for determining path interiors: evenodd, nonzero, positive, negative (or numeric enum 0-3). Defaults to `nonzero` for the `clipper` engine and `evenodd` for `cgal` (the only rule `cgal` accepts).
curve_angle_degrees : Numeric Float(1) - Max turning angle (degrees) per segment when discretizing curves.
sample_count : Numeric Int(64) - Uniform sample count for non-trace_path callables.
closed : Bool | Nil Nil - Optional override for treating the inputs as closed/open.
engine : String | Nil Nil - Backend: `clipper` (default; fast, fixed-point) or `cgal` (slower, exact-arithmetic via `Polygon_set_2` over EPECK).

path_xor

path_xor ( subject : Callable , clip : Callable , fill_rule : String | Nil | Numeric Nil , curve_angle_degrees : Numeric Float(1) , sample_count : Numeric Int(64) , closed : Bool | Nil Nil , engine : String | Nil Nil ) : Callable

Computes the exclusive-or (XOR) of two 2D paths. The result contains areas inside either path but not both. See `path_union` for the full fill-rule and engine reference; the same conventions apply here.

Arguments:

subject : Callable - The first path sampler callable of signature `|t: num|: vec2`.
clip : Callable - The second path sampler callable of signature `|t: num|: vec2`.
fill_rule : String | Nil | Numeric Nil - Fill rule for determining path interiors: evenodd, nonzero, positive, negative (or numeric enum 0-3). Defaults to `nonzero` for the `clipper` engine and `evenodd` for `cgal` (the only rule `cgal` accepts).
curve_angle_degrees : Numeric Float(1) - Max turning angle (degrees) per segment when discretizing curves.
sample_count : Numeric Int(64) - Uniform sample count for non-trace_path callables.
closed : Bool | Nil Nil - Optional override for treating the inputs as closed/open.
engine : String | Nil Nil - Backend: `clipper` (default; fast, fixed-point) or `cgal` (slower, exact-arithmetic).

subpaths

subpaths ( path : Callable ) : Sequence

Returns a lazy sequence of path samplers, one for each disconnected subpath in the input path. For example, if a path is created with multiple `move` commands, each segment between moves becomes a separate subpath. Each returned sampler works like the original, with `t` in [0,1] sampling along that particular subpath.

Arguments:

path : Callable - A path sampler created by `trace_path` or similar functions

superellipse

superellipse ( t : Numeric , n : Numeric , width : Numeric Float(1) , height : Numeric Float(1) ) : Vec2

Returns the `Vec2` position at parameter `t` along the perimeter of a superellipse

Arguments:

t : Numeric - Parameter in [0, 1] specifying the position along the superellipse perimeter
n : Numeric - Exponent that controls the shape of the superellipse. A value of 2 produces an ellipse, higher values produce more rectangular shapes, and lower values produce diamond and star-like shapes.
width : Numeric Float(1)
height : Numeric Float(1)

superellipse_path

aliases: rounded_rectangle, rounded_rect

superellipse_path ( n : Numeric , point_count : Numeric , width : Numeric Float(1) , height : Numeric Float(1) ) : Sequence

Generates a sequence of points defining a superellipse, or rounded rectangle. Returns a sequence of `point_count` `Vec2` points

Arguments:

n : Numeric - Exponent that controls the shape of the superellipse. A value of 2 produces an ellipse, higher values produce more rectangular shapes, and lower values produce diamond and star-like shapes.
point_count : Numeric - Number of points to generate along the path
width : Numeric Float(1)
height : Numeric Float(1)

text_to_path

text_to_path ( text : String , font_family : String String(IBM Plex Sans) , font_size : Numeric Float(24) , font_weight : String | Nil | Numeric Nil , font_style : String | Nil Nil , letter_spacing : Nil | Numeric Nil , center : Bool Bool(false) , fill_rule : String | Nil Nil ) : Callable

Fetches SVG path data for the given text and returns a path sampler callable of signature `|t: num|: vec2`. Suitable for use with `tessellate_path`, `render_path`, `subpaths`, etc.

Arguments:

text : String
font_family : String String(IBM Plex Sans) - Font family to use for the text. Must exist on Google Fonts.
font_size : Numeric Float(24)
font_weight : String | Nil | Numeric Nil
font_style : String | Nil Nil - Must be one of "normal", "italic", or "oblique". If nil, defaults to "normal".
letter_spacing : Nil | Numeric Nil
center : Bool Bool(false) - If true, centers the path around the origin after parsing.
fill_rule : String | Nil Nil - Fill rule for tessellation: "nonzero", "evenodd", "positive", "negative", or nil.

text_to_svg

text_to_svg ( text : String , font_family : String String(IBM Plex Sans) , font_size : Numeric Float(24) , font_weight : String | Nil | Numeric Nil , font_style : String | Nil Nil , letter_spacing : Nil | Numeric Nil ) : String

Fetches the SVG path data string for the given text in the specified font. Requires an internet connection to fetch from the font server.

Arguments:

text : String
font_family : String String(IBM Plex Sans) - Font family to use for the text. Must exist on Google Fonts.
font_size : Numeric Float(24)
font_weight : String | Nil | Numeric Nil
font_style : String | Nil Nil - Must be one of "normal", "italic", or "oblique". If nil, defaults to "normal".
letter_spacing : Nil | Numeric Nil

torus_knot_path

Example

ambient_light(color=0xffffff, intensity=1.8) | render

dir_light(
  color=0xffffff,
  intensity=5,
  cast_shadow=true,
  shadow_map_size={width: 2048*2, height: 2048*2},
  shadow_map_radius=4,
  shadow_map_blur_samples=16,
  shadow_map_type="vsm",
  shadow_map_bias=-0.0001,
  shadow_camera={near: 1, far: 25, left: -20, right: 20, top: 20, bottom: -20},
)
  | trans(-10, 10, 0)
  | render;

//-- end prelude

path = torus_knot_path(
  radius=5, tube_radius=2, p=3, q=4, point_count=400
)

path
  | extrude_pipe(radius=1, resolution=12,
                 connect_ends=true)
  | simplify(tolerance=0.05)
  | render

Open in editor

torus_knot_path ( radius : Numeric , tube_radius : Numeric , p : Numeric , q : Numeric , point_count : Numeric ) : Sequence

Generates a sequence of points defining a torus knot path

Arguments:

radius : Numeric
tube_radius : Numeric
p : Numeric - Number of times the knot wraps around the torus in the longitudinal direction
q : Numeric - Number of times the knot wraps around the torus in the meridional direction
point_count : Numeric - Number of points to generate along the path

trace_svg_path

trace_svg_path ( svg_path : String , center : Bool Bool(false) , reverse : Bool Bool(false) , fill_rule : String | Nil Nil ) : Callable

Parses SVG path data and returns a callable of signature `|t: num|: vec2` where `t` is a parameter from 0 to 1 representing the position along the path. Values <0 or >1 will be clamped to the start or end of the path respectively.

Arguments:

svg_path : String - An SVG path data string using move, line, cubic/quadratic, smooth, and arc commands.
center : Bool Bool(false) - If true, the path will be centered around the origin after being traced.
reverse : Bool Bool(false) - If true, the path will be sampled in reverse direction (from end to start). Sampling at t=0 will return the end point and t=1 will return the start point.
fill_rule : String | Nil Nil - Optional fill rule that describes how the interior of this path should be interpreted for operations like tessellation. One of "nonzero", "evenodd", "positive", "negative", or nil.

rand

curl_noise

Example

noise_scale = 0.001
noise_gain = 0.175
origin_bias = 0.0002
step_size = 0.1
seed_offset = v3(-4)

build_path = |count: int| {
  scan({ dir: normalize(randv(-1, 1)) * 50., pos: v3(0) }, |{ dir, pos }, i| {
    field_p = seed_offset + pos * noise_scale

    noise = curl_noise(field_p)

    dir = dir * 0.9
    dir = dir + noise * noise_gain

    dir = dir + -pos * pow((distance(pos, vec3(0)) * origin_bias), 3)

    pos = pos + dir * step_size
    { dir: dir, pos: pos }
  }, 0..count)
    -> |{ pos }| pos
}

paths = 0..800 -> || {
  build_path(2500)
    | filter(|_, i| i % 4 == 0)
    | extrude_pipe(radius=1, resolution=8)
}
paths | for_each(render)

// paths
//   | flatten
//   | alpha_wrap(alpha=1/500, offset=1/700)
//   | simplify(tolerance=0.0125)
//   | smooth(iterations=1)
//   | simplify(tolerance=0.0125)
//   | render

Open in editor

curl_noise ( pos : Vec3 ) : Vec3

Samples 3D curl noise at a given position using default parameters

Arguments:

pos : Vec3

curl_noise ( seed : Numeric Int(0) , octaves : Numeric Int(4) , frequency : Numeric Float(1) , lacunarity : Numeric Float(2) , persistence : Numeric Float(0.5) , pos : Vec3 ) : Vec3

Samples 3D curl noise at a given position using the specified parameters

Arguments:

seed : Numeric Int(0)
octaves : Numeric Int(4)
frequency : Numeric Float(1)
lacunarity : Numeric Float(2)
persistence : Numeric Float(0.5)
pos : Vec3

curl_noise ( pos : Vec2 ) : Vec2

Samples 2D curl noise at a given position using default parameters

Arguments:

pos : Vec2

curl_noise ( seed : Numeric Int(0) , octaves : Numeric Int(4) , frequency : Numeric Float(1) , lacunarity : Numeric Float(2) , persistence : Numeric Float(0.5) , pos : Vec2 ) : Vec2

Samples 2D curl noise at a given position using the specified parameters

Arguments:

seed : Numeric Int(0)
octaves : Numeric Int(4)
frequency : Numeric Float(1)
lacunarity : Numeric Float(2)
persistence : Numeric Float(0.5)
pos : Vec2

fbm

Example

grid(size=300, divisions=300)
  -> |v| {
    noise = fbm(octaves=8, pos=v*0.01, lacunarity=1.8)
    vec3(v.x, noise * 36, v.z)
  }
  | render

Open in editor

fbm ( pos : Vec3 ) : Float

Samples 3D fractal Brownian motion (FBM) at a given position using default parameters

Arguments:

pos : Vec3

fbm ( seed : Numeric Int(0) , octaves : Numeric Int(4) , frequency : Numeric Float(1) , lacunarity : Numeric Float(2) , persistence : Numeric Float(0.5) , pos : Vec3 ) : Float

Samples 3D fractal Brownian motion (FBM) at a given position using the specified parameters

Arguments:

seed : Numeric Int(0)
octaves : Numeric Int(4)
frequency : Numeric Float(1)
lacunarity : Numeric Float(2)
persistence : Numeric Float(0.5)
pos : Vec3

fbm ( pos : Vec2 ) : Float

Samples 2D fractal Brownian motion (FBM) at a given position using default parameters

Arguments:

pos : Vec2

fbm ( seed : Numeric Int(0) , octaves : Numeric Int(4) , frequency : Numeric Float(1) , lacunarity : Numeric Float(2) , persistence : Numeric Float(0.5) , pos : Vec2 ) : Float

Samples 2D fractal Brownian motion (FBM) at a given position using the specified parameters

Arguments:

seed : Numeric Int(0)
octaves : Numeric Int(4)
frequency : Numeric Float(1)
lacunarity : Numeric Float(2)
persistence : Numeric Float(0.5)
pos : Vec2

fbm ( pos : Numeric ) : Float

Samples 1D fractal Brownian motion (FBM) at a given position using default parameters

Arguments:

pos : Numeric

fbm ( seed : Numeric Int(0) , octaves : Numeric Int(4) , frequency : Numeric Float(1) , lacunarity : Numeric Float(2) , persistence : Numeric Float(0.5) , pos : Numeric ) : Float

Samples 1D fractal Brownian motion (FBM) at a given position using the specified parameters

Arguments:

seed : Numeric Int(0)
octaves : Numeric Int(4)
frequency : Numeric Float(1)
lacunarity : Numeric Float(2)
persistence : Numeric Float(0.5)
pos : Numeric

randf

randf ( min : Numeric , max : Numeric ) : Float

Returns a random float between `min` and `max`

Arguments:

min : Numeric
max : Numeric

randf ( ) : Float

Returns a random float between 0. and 1.

randi

randi ( min : Numeric , max : Numeric ) : Int

Returns a random integer between `min` and `max` (inclusive)

Arguments:

min : Numeric
max : Numeric

randi ( ) : Int

Returns a random integer. Any 64-bit integer is equally possible, positive or negative.

randv

alias: randv3

randv ( min : Vec3 , max : Vec3 ) : Vec3

Returns a random Vec3 where each component is between the corresponding components of `min` and `max`

Arguments:

min : Vec3
max : Vec3

randv ( min : Numeric , max : Numeric ) : Vec3

Returns a random Vec3 where each component is between `min` and `max`

Arguments:

min : Numeric
max : Numeric

randv ( ) : Vec3

Returns a random Vec3 where each component is between 0. and 1.

ridged_multifractal

ridged_multifractal ( pos : Vec3 ) : Float

Samples 3D ridged multifractal noise at a given position using default parameters

Arguments:

pos : Vec3

ridged_multifractal ( seed : Numeric Int(0) , octaves : Numeric Int(4) , frequency : Numeric Float(1) , lacunarity : Numeric Float(2) , persistence : Numeric Float(0.5) , gain : Numeric Float(2) , pos : Vec3 ) : Float

Samples 3D ridged multifractal noise at a given position using the specified parameters

Arguments:

seed : Numeric Int(0)
octaves : Numeric Int(4)
frequency : Numeric Float(1)
lacunarity : Numeric Float(2)
persistence : Numeric Float(0.5)
gain : Numeric Float(2)
pos : Vec3

ridged_multifractal ( pos : Vec2 ) : Float

Samples 2D ridged multifractal noise at a given position using default parameters

Arguments:

pos : Vec2

Samples 2D ridged multifractal noise at a given position using the specified parameters

Arguments:

seed : Numeric Int(0)
octaves : Numeric Int(4)
frequency : Numeric Float(1)
lacunarity : Numeric Float(2)
persistence : Numeric Float(0.5)
gain : Numeric Float(2)
pos : Vec2

set_rng_seed

set_rng_seed ( seed : Numeric ) : Nil

Sets the seed for the shared PRNG used by functions like `randi`, `randf`, etc. This will reset the state of the RNG, so it will always return the same value the next time it's used after this is called.

Arguments:

seed : Numeric

worley_noise

alias: worley

worley_noise ( pos : Vec3 , seed : Numeric Int(0) , range_fn : String String(euclidean) , return_type : String String(distance) ) : Float

Samples 3D Worley noise at a given position using default parameters

Arguments:

pos : Vec3
seed : Numeric Int(0)
range_fn : String String(euclidean) - Distance function used to sample the noise. Must be one of the following: "euclidean" (default), "euclidean_squared", "manhattan", "chebyshev", or "quadratic".
return_type : String String(distance) - Flag to control whether distances or values are returned. Must be either "distance" (default) or "value".

worley_noise ( pos : Vec2 , seed : Numeric Int(0) , range_fn : String String(euclidean) , return_type : String String(distance) ) : Float

Samples 2D Worley noise at a given position using the specified parameters

Arguments:

pos : Vec2
seed : Numeric Int(0)
range_fn : String String(euclidean) - Distance function used to sample the noise. Must be one of the following: "euclidean" (default), "euclidean_squared", "manhattan", "chebyshev", or "quadratic".
return_type : String String(distance) - Flag to control whether distances or values are returned. Must be either "distance" (default) or "value".

seq

all

all ( cb : Callable , sequence : Sequence ) : Bool

Returns true if all elements of the sequence make the callback return true

Arguments:

cb : Callable - Callable with signature `|x|: bool`
sequence : Sequence

any

any ( cb : Callable , sequence : Sequence ) : Bool

Returns true if any element of the sequence makes the callback return true

Arguments:

cb : Callable - Callable with signature `|x|: bool`
sequence : Sequence

append

alias: push

append ( val : Any , seq : Sequence ) : Sequence

Appends a value to the end of a sequence, returning a new sequence. The old sequence is left unchanged. If the sequence is not eager (as produced by the `collect` function, an array literal, or similar), it will be collected into memory before this happens. Note that this isn't very efficient and requires collecting and/or cloning the underlying sequence. It's better to keep things lazy and use sequences and sequence combinators where possible.

Arguments:

val : Any - The value to add to the end of the sequence
seq : Sequence - The sequence to which the value should be added

chain

chain ( sequences : Sequence ) : Sequence

Returns a new sequence that concatenates all input sequences. This is lazy and will not evaluate the sequences until the output sequence is consumed.

Arguments:

sequences : Sequence - Sequence of sequences to chain together

collect

collect ( sequence : Sequence ) : Sequence

Makes the sequence eager, collecting all elements into memory. This will allow the sequence to indexed with `[]`.

Arguments:

sequence : Sequence

filter

filter ( fn : Callable , sequence : Sequence ) : Sequence

Filters a sequence using a predicate function. This is lazy and will not evaluate the function until the output sequence is consumed.

Arguments:

fn : Callable - Callable with signature `|x: T, ix: int|: bool`
sequence : Sequence - Sequence to filter

first

first ( sequence : Sequence ) : Any

Returns the first element of a sequence, or `Nil` if the sequence is empty.

Arguments:

sequence : Sequence

flatten

flatten ( sequence : Sequence ) : Sequence

Flattens a sequence of sequences into a single sequence. Any non-sequence elements are passed through unchanged. Note that only a single level of flattening is performed.

Arguments:

sequence : Sequence

fold

fold ( initial_val : Any , fn : Callable , sequence : Sequence ) : Any

Same as `reduce` but with an explicit initial value

Arguments:

initial_val : Any
fn : Callable - Callable with signature `|acc, x, i|: acc`
sequence : Sequence

fold_while

fold_while ( initial_val : Any , fn : Callable , sequence : Sequence ) : Any

Same as `fold` but with the option early-exiting. If the provided callback returns `nil`, the final state of the accumulator passed into that iteration will be returned.

Arguments:

initial_val : Any
fn : Callable - Callable with signature `|acc, x, i|: acc | nil`. If this callback returns `nil`, the final state of the accumulator passed into that iteration will be returned.
sequence : Sequence

for_each

for_each ( cb : Callable , sequence : Sequence ) : Nil

Applies the callback to each element of the sequence, returning `nil`. This is useful for running side effects.

Arguments:

cb : Callable - Callable with signature `|x|`
sequence : Sequence

last

last ( sequence : Sequence ) : Any

Returns the last element of a sequence, or `Nil` if the sequence is empty.

Arguments:

sequence : Sequence

map

map ( fn : Callable , sequence : Sequence ) : Sequence

Applies a function to each element of a sequence and returns a new sequence. This is lazy and will not evaluate the function until the output sequence is consumed.

Arguments:

fn : Callable - Callable with signature `|x: T, ix: int|: y`
sequence : Sequence - Sequence to map over

map ( fn : Callable , mesh : Mesh ) : Mesh

Applies a function to each vertex in a mesh and returns a new mesh with the transformed vertices.

Arguments:

fn : Callable - Callable with signature `|vtx: Vec3, normal: Vec3|: Vec3` that will be invoked for each vertex in the new mesh, returning a new position for that vertex
mesh : Mesh

reduce

reduce ( fn : Callable , sequence : Sequence ) : Any

Same as `fold` but with the first element of the sequence as the initial value

Arguments:

fn : Callable - Callable with signature `|acc, x, i|: acc`
sequence : Sequence - Sequence to reduce

reverse

reverse ( sequence : Sequence ) : Sequence

Returns a new sequence with the elements in reverse order. This is NOT lazy and will evaluate the entire sequence immediately and collect all of its elements into memory.

Arguments:

sequence : Sequence

scan

Example

build_smooth_path = |smoothing: num| {
  // this is essentially applying a low-pass filter
  dirs = scan(
    initial=normalize(randv(-1, 1)),
    fn=|acc, _| {
      new_dir = mix(1 - smoothing, acc, randv(-1, 1))
      normalize(new_dir)
    },
    sequence=0..100
  )

  scan(
    initial=vec3(0),
    fn=|pos, dir| pos + dir,
    sequence=dirs
  )
}

smooth_path = build_smooth_path(0.75)
random_path = build_smooth_path(0)

smooth_path
  | extrude_pipe(radius=0.2, resolution=8)
  | set_material('red')
  | render

random_path
  | extrude_pipe(radius=0.2, resolution=8)
  | set_material('blue')
  | render

Open in editor

scan ( initial : Any , fn : Callable , sequence : Sequence ) : Sequence

Applies a function cumulatively to the elements of a sequence, returning a new sequence of intermediate results. Similar to the `Iterator::scan` function from Rust, but with a little less freedom in the way it can be used. This is lazy and will not evaluate the function until the output sequence is consumed. NOTE: This function may be subject to change in the future. It would be much better for it to return a tuple to allow de-coupling output sequence values from the retained state.

Arguments:

initial : Any - Initial value to seed the state with. This value will NOT be included in the output sequence.
fn : Callable - Callable with signature `|acc, x, ix|: acc`
sequence : Sequence - Sequence to scan

skip

skip ( count : Numeric , sequence : Sequence ) : Sequence

Returns a new sequence with the first `n` elements skipped. If `n` is greater than the length of the sequence, an empty sequence is returned. This is lazy and will not evaluate the sequence until the output sequence is consumed.

Arguments:

count : Numeric - Number of elements to skip from the start of the sequence
sequence : Sequence - Sequence to skip elements from

skip_while

skip_while ( fn : Callable , sequence : Sequence ) : Sequence

Returns a new sequence with elements skipped from the start of the input sequence until the predicate function returns false. This is lazy and will not evaluate the function until the output sequence is consumed.

Arguments:

fn : Callable - Callable with signature `|x|: bool`
sequence : Sequence

take

take ( count : Numeric , sequence : Sequence ) : Sequence

Returns a new sequence containing the first `n` elements of the input sequence. If `n` is greater than the length of the sequence, the entire sequence is returned. This is lazy and will not evaluate the sequence until the output sequence is consumed.

Arguments:

count : Numeric - Number of elements to take from the start of the sequence
sequence : Sequence - Sequence to take elements from

take_while

take_while ( fn : Callable , sequence : Sequence ) : Sequence

Returns a new sequence containing elements from the start of the input sequence until the predicate function returns false. This is lazy and will not evaluate the function until the output sequence is consumed.

Arguments:

fn : Callable - Callable with signature `|x|: bool`
sequence : Sequence - Sequence to take elements from

str

chars

chars ( s : String ) : Sequence

Returns a sequence of the unicode characters in a string

Arguments:

s : String