bits

bit_and

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

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

Arguments:

a : Int
b : Int

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 : Int , b : Int ) : Int

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

Arguments:

a : Int
b : Int

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 : Numeric | String ) : Float

Converts a value to a float

Arguments:

value : Numeric | String

int

int ( value : Numeric | String ) : Int

Converts a value to an int

Arguments:

value : Numeric | String

len

aliases: length, mag, magnitude

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

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>`). Each entity will be rendered separately.

Arguments:

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

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 ( 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 ( ... ) : 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 : Int | Vec3 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 : Int | Vec3 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 : Int | Vec3 Int(16777215) , intensity : Numeric Float(5) , cast_shadow : Bool Bool(true) , shadow_map_size : Map | Int {"width": Int(4096), "height": Int(4096)} , shadow_map_radius : Numeric Float(4) , shadow_map_blur_samples : Int 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 : Int | Vec3 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 | Int {"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 : Int 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`

logic

and

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

Logical AND operation of two booleans

Arguments:

a : Bool
b : Bool

and ( a : Mesh , b : Mesh ) : Mesh

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

Arguments:

a : Mesh
b : Mesh

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

or ( a : Mesh , b : Mesh ) : Mesh

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

Arguments:

a : Mesh
b : Mesh

xor

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

Logical XOR operation of two booleans

Arguments:

a : Bool
b : Bool

math

abs

abs ( value : Int ) : Int

Absolute Value

Arguments:

value : Int

abs ( value : Float ) : Float

Absolute Value

Arguments:

value : Float

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

add

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

Adds two Vec3s component-wise

Arguments:

a : Vec3
b : Vec3

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

a + b

Arguments:

a : Numeric
b : Float

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

a + b

Arguments:

a : Float
b : Int

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

a + b

Arguments:

a : Int
b : Int

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

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 : Int , max : Int , value : Int ) : Int

Clamps a value between min and max

Arguments:

min : Int
max : Int
value : Int

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

Clamps a value between min and max

Arguments:

min : Numeric
max : Numeric
value : Float

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

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 : Float ) : Float

a / b

Arguments:

a : Numeric
b : Float

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

a / b

Arguments:

a : Float
b : Int

div ( a : Int , b : Int ) : Int

a / b

Arguments:

a : Int
b : Int

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

eq

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

`a == b`

Arguments:

a : Int
b : Int

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 : Int , b : Int ) : Bool

`a > b`

Arguments:

a : Int
b : Int

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

`a > b`

Arguments:

a : Numeric
b : Numeric

gte

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

`a >= b`

Arguments:

a : Int
b : Int

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

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 ) : Vec3

TODO: this is currently broken

Arguments:

pos : Vec3 - Source position
target : Vec3 - Target position

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

Orients a mesh to look at a target point. This replaces any currently applied rotation. There's a good chance this implementation is broken too...

Arguments:

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

lt

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

`a < b`

Arguments:

a : Int
b : Int

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

`a < b`

Arguments:

a : Numeric
b : Numeric

lte

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

`a <= b`

Arguments:

a : Int
b : Int

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

`a <= b`

Arguments:

a : Numeric
b : Numeric

max

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

Returns the minimum of the provided arguments

Arguments:

a : Int
b : Int

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 : Int , b : Int ) : Int

Returns the minimum of the provided arguments

Arguments:

a : Int
b : Int

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 : Int , b : Int ) : Int

a % b

Arguments:

a : Int
b : Int

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 : Float ) : Float

a * b

Arguments:

a : Numeric
b : Float

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

a * b

Arguments:

a : Float
b : Int

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

a * b

Arguments:

a : Int
b : Int

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

neg

neg ( value : Int ) : Int

Negates an integer

Arguments:

value : Int

neg ( value : Float ) : Float

Negates a float

Arguments:

value : Float

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 : Int , b : Int ) : Bool

`a != b`

Arguments:

a : Int
b : Int

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

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

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 : Float ) : Float

a -b

Arguments:

a : Numeric
b : Float

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

a - b

Arguments:

a : Float
b : Int

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

a - b

Arguments:

a : Int
b : Int

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

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

box

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

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 : Int , height_segments : Int Int(1) ) : Mesh

Generates a cylinder mesh

Arguments:

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

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

extrude

extrude ( up : Vec3 , 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 - Direction to extrude the mesh. Vertices will be displaced by this amount.
mesh : Mesh

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 : Numeric | Callable , resolution : Int Int(8) , path : Sequence , close_ends : Bool Bool(true) , connect_ends : Bool Bool(false) , twist : Numeric | Callable Float(0) ) : Mesh

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

Arguments:

radius : Numeric | Callable - 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 : Int 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 : Numeric | Callable 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.

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.

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 | Int 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 | Int 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).

icosphere

alias: sphere

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

Generates an icosphere mesh

Arguments:

radius : Numeric
resolution : Int - 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 : Float | Nil 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 : Float | Nil 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.

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.

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

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 : Int | Nil , mesh : Mesh , seed : Int 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 : Int | Nil - The number of points to distribute across the mesh. If `nil`, returns an infinite sequence.
mesh : Mesh
seed : Int 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.

rot

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

Rotates a mesh using a Vec3 of Euler angles (radians)

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 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

scale

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

Scales a mesh by separate factors along each axis

Arguments:

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

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

Scales a mesh

Arguments:

scale : Vec3 | Numeric
mesh : Mesh

set_default_material

set_default_material ( material : Material ) : Nil

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

Arguments:

material : 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 : Material , mesh : Mesh ) : Nil

Sets the material for a mesh

Arguments:

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

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

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_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

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 | Light ) : Mesh

Translates a mesh or light

Arguments:

translation : Vec3
mesh : Mesh | Light

translate ( x : Numeric , y : Numeric , z : Numeric , object : Mesh | Light ) : Mesh

Translates a mesh or light

Arguments:

x : Numeric
y : Numeric
z : Numeric
object : Mesh | 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 : Int ) : 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 : Int

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 : Int ) : 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 : Int - Number of points to sample along the path

superellipse_path

aliases: superellipse, rounded_rect, rounded_rectangle

superellipse_path ( width : Numeric , height : Numeric , n : Numeric , point_count : Int ) : Sequence

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

Arguments:

width : Numeric
height : Numeric
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 : Int - Number of points to generate along the path

torus_knot_path

Example

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 : Int , q : Int , point_count : Int ) : Sequence

Generates a sequence of points defining a torus knot path

Arguments:

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

rand

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

Generates a fractal Brownian motion (FBM) value at a given position using default parameters

Arguments:

pos : Vec3

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

Samples fractional brownian noise at a given position using the specified parameters

Arguments:

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

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 : Int , max : Int ) : Int

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

Arguments:

min : Int
max : Int

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.

set_rng_seed

set_rng_seed ( seed : Int ) : 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 : Int

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|: 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|: 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|: 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 : Int , 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 : Int - 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 : Int , 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 : Int - 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