Scripting  IceSLNext
This is the official IceSL scripting language documentation wiki. Examples featured here are for the most part selfcontained unless they use an external asset (svg or stl files). Their associated illustrations are accurate depictions of their output.
We welcome IceSL users to redirect their questions about the scripting language in the IceSL forum page.
Legend:
 _{IceSL}: Supported by IceSL
 _{IceSLonline}: Supported by IceSLOnline IceSLOnline
Contents 
Syntax
The scripting language of IceSL (hereafter refered to as IceSL) is a superset of Lua. Moreover, IceSL has been designed to facilitate conversion from/to OpenSCAD. IceSL also extends Lua's types in order to specify shapes and transforms. The main basic types are:
 Vector (e.g.
v(1,0,0)
)  Matrix (e.g.
m(1,0,0,1, 0,1,0,1, 0,0,1,1, 0,0,0,1)
)  Shapes:
 Primitive (e.g.
sphere(1)
)  Mesh (e.g.
'fox.stl'
)  Voxels
 Primitive (e.g.
Emitting and Scale
Creating a shape in IceSL will not automatically render it in the final scene. In order to do this, you need to emit it.
emit( shape, brush )
_{IceSL}  _{IceSLonline}

shape
: the shape to render 
brush
: the brush's index to render the shape with. 0 by default
Brushes are an internalized concept of IceSL, there are a total of 128 indexes starting from 0. Their use is meant to group shapes under a set of parameters (usally printing parameters like infill percentage). In case of overlapping, the group with the lower index takes priority. The next code exemplifies the use of emit
:
b = box(10) emit( b, 0 ) c = sphere(5) emit( translate(0,0,5) * c, 1 ) 
Finally, a unit in the scripting language corresponds to 1mm in the printing world. IceSL always renders a scene with a virtual printing bed; a grid that represents the 3d printer bed (see image below). Each square of IceSL's printing bed corresponds to 1cm^{2}.
Notice that, in order to have a visual aid on view orientation, axes are drown in the bottomleft corner. The red, green and blue lines correspond to the positive X, Y, and Z axes respectively.
Vectors, Matrices, Constants and Trigonometric Functions
Vectors
 Construction:

v(x,y,z)
 or
v{x,y,z}
: creates the vector . 
v(x,y)
 or
v{x,y}
: : creates the vector.
 Operations: Let
v
andu
be vectors andn
a number.

v + u
: vector addition. 
v  u
: vector subtraction. 
v * u
: vector componentwise multiplication. 
v / u
: vector componentwise division 
v * n
orn * v
: vector scalar multiplication. 
v / n
: vector scalar division. 
v
: syntatic sugar for1 * v
. 
dot(v, u)
: dot product. 
cross(v, u)
: cross product. 
normalize(v)
: returns the unit vector . 
length(v)
: return the norm ofv
(i.e.   v   ).
Matrices
 Construction:
m( m11, m12, m13, m14, m21, m22, m23, m24, m31, m32, m33, m34, m41, m42, m43, m44 )
m{ m11, m12, m13, m14, m21, m22, m23, m24, m31, m32, m33, m34, m41, m42, m43, m44 }
Creates the matrix .
 Operations: Let
M
andQ
be matrices, letv
be a vector and lets
be a shape.

M * Q
: matrix multiplication. Returns a matrix 
M * v
: matrixvector multiplication. Returns a vector 
M * s
: shape transformation. Returns the shape transformed byM
. 
inverse(M)
: matrix inversion. Returns the inverse of matrixM
.
Constants and Trigonometric Functions
The following are constants in IceSL

Pi
: the π constant. 
X
: the vectorv(1,0,0)
. 
Y
: the vectorv(0,1,0)
. 
Z
: the vectorv(0,0,1)
. 
Path
: the path of the current script.
IceSl offers the next trigonometric functions:
sin,asin,cos,acos,tan,atan,atan2
.
Shapes
Primitive Shapes
load(path)
_{IceSL}
loadmesh(path)
_{IceSL}
 Loads the 3d mesh at
path
. The mesh must be watertight.

path
: Absolute path to a 3d mesh. It supports the following extensions: stl
 obj
 3ds
sphere(r, c)
_{IceSL}  _{IceSLonline}
 Creates a sphere of radius
r
centered on thec
.sphere(r)
is syntactic sugar forsphere(r,v(0,0,0))
a centered sphere.

r
: the sphere's radius 
c
: the sphere's center
cube(dx, dy, dz)
_{IceSL}  _{IceSLonline}
 Creates a cube with with sides
dx
,dy
,dz
with its bottom face centered on the origin.cube(d)
andcube(v)
are syntactic sugars forcube(d,d,d)
andcube(v.x,v.y,v.z)
respectively.

dx
: length of the face perdendicular to the Xaxis 
dy
: length of the face perpendicular to the Yaxis 
dz
: length of the face perpendicular to the Zaxis
cone(r0, r1, c0, c1)
_{IceSL}  _{IceSLonline}
 Creates a cone with base radius
r0
, top radiusr1
, base centerc0
and top centerc1
. Moreover,cone(r0,r1,h)
is syntactic sugar forcone(r0,r1,v(0,0,0),v(0,0,h))
.

r0
: the cone's base radius 
r1
: the cone's top radius 
c0
: the cone's base center 
c1
: the cone's top center
cylinder(r, c0, c1)
_{IceSL}  _{IceSLonline}
 Creates a cylinder with radius
r
, base centerc0
and top centerc1
. It is syntactic sugar forcone(r,r,c0,c1)
. Additionally,cylinder(r,h)
is also syntactic sugar forcone(r,r,h)
.
polyhedron(points,indices)
_{IceSL}  _{IceSLonline}
 Creates a polyhedron with
points
as its vertex andindices
to specify its faces.

points
: an array of vectors containing the polyhedron's vertex 
indices
: an array of vectors specifying the polyhedron's faces. Each vector specifies the three vertex's indices indices (starting with 0) to build a face. Indices specified counterclockwise face outwards.
p = polyhedron( { v(0,0,0), v(1,0,0), v(0,1,0), v(1,1,0), v(0.5,0.5,1) }, { v(0,3,1), v(0,2,3), v(0,1,4), v(1,3,4), v(3,2,4), v(2,0,4) } ) emit( p ) 
Centered Primitives
Many primitives can be automatically centered at creation to their center of symmetry with respect to their bounding boxes. The following table lists their centered versions.
Primitive  Centered Version  Alternative Centered Version 

load(path)

load_centered(path) 

cube(dx,dy,dz)

ccube(dx,dy,dz) 
box(dx,dy,dz)

cone(r0,r1,h)

ccone(r0,r1,h) 

cylinder(r,h)

ccylinder(r,h) 
Additionally, the cube and box primitives have the versions ocube(dx,dy,dz)
and cornerbox(dx,dy,dz)
that position their front lowerleft corners at the origin.
Nonprimitive Shapes
linear_extrude(dir, points)
_{IceSL}  _{IceSLonline}
 Creates a closed object from the extrusion of a polygon along a direction
dir
. The polygon's orientations is specified as set of either clockwise or counterclockwise 2D vertices inpoints
.

dir
: extruding direction 
points
: polygon specification
triangle = { v(10,0), v(0,10), v(10,0) }  50 units along the Zaxis dir = v(0,0,50) emit( linear_extrude(dir, triangle) ) 
linear_extrude_from_oriented(dir, points)
_{IceSL}  _{IceSLonline}
 Creates a closed object from the extrusion of a polygon along a direction
dir
. Solid geometry is specified as set of closed (i.e. the last vertex matches the first one) counterclockwise 2D vertices and hollow geomtry is specified as a set of closed clockwise 2D vertices inpoints
.

dir
: extruding direction 
points
: polygon specification
polygon = { v(10,10), v(10,10), v(10,10), v(10,10), v(10,10),  Solid v(0,6), v(6,6), v(6,6), v(0,6) }  Hollow dir = v(0,0,10) emit( linear_extrude_from_oriented(dir, polygon)) 
rotate_extrude(points, nsteps)
_{IceSL}  _{IceSLonline}
 Creates a closed object from the spinning of a polygon along the Zaxis (axis of revolution). The polygon is specified as set of counterclockwise 2D vertices in
points
.nsteps
defines the number of steps in the revolution of the polygon, the more the smoother.
radius = v(10,0,0) triangle = { radius + v(1,0,0), radius + v(0,1,0), radius + v(1,0,0) } emit( rotate_extrude( triangle, 100 ) ) 
svg_ex(file,dpi)
_{IceSL}
 Extracts contours out of a SVG file. Returns a table of
SVGContour
objects.

file
: input svg file 
dpi
: dots per inch. Use 90 for Inkscape files
The SVGContour
object has the following members:

outline
: The contour 
fill
: ID of fill color for the contour 
stroke
: ID of stroke color for the contour
svg_shapes = svg_ex('restroom.svg',90) for i,contour in pairs(svg_shapes) do emit(linear_extrude(v(0,0,5),contour:outline()), i) end 
Void
_{IceSL}  _{IceSLonline}
 Creates an empty primitive
Implicits
IceSL supports implicits by way of the GL Shading Language (GLSL). A comprehensive list of the builtin functions of GLSL can be found here
implicit(boxMin, boxMax, fragment)
_{IceSL}
 Creates a solid geometry out of the distance field calculated in
fragment
. The bounding box constructed byboxMin
andboxMax
defines the boundaries of the implicit shape.

boxMin, boxMax
: domain of the implicit. The domain is specified by the box constructed with cornersboxMin
andboxMax

fragment
: string containing the GLSL progam. This program calculates the distance field that defines the constructed solid geometry
Implicits are calculated in IceSL with a sphere tracing method (detailed here). The program specified in fragment
must contain a function called float distanceEstimator(vec3 p)
that calculates the distance field for every point of the domain of the box. A negative value in the distance field means solid whereas a positive value means hollow. Consider the following example.
cube = implicit( v(10,10,10), v(10,10,10), [[ float distanceEstimator(vec3 p) { return 1; } ]]) emit (cube) 
Above, every point in the domain of the implicit is marked as solid, therefore the geometry created has the shape of the boundary box.
Uniform variables and file support
It is possible to set in uniform variables specified in the implicti's GLSL program via lua commands.
set_uniform_{booleanscalarvectormatrix}(implicit, var_name, var_value)
_{IceSL}
 sets
var_name
tovar_value
insideimplicit
.

implicit
: a created implicit 
var_name
: string specifying the name of the uniform variable in the implicit 
var_value
: new boolean/scalar/vector/matrix value
Furthermore, implicits can be loaded directly from files as the next function shows.
implicit_from_file(boxMin, boxMax, fileName)
_{IceSL}
 Similar to
implicit
where the fragment program is infileName
.

boxMin, boxMax
: domain of the implicit. The domain is specified by the box constructed with cornersboxMin
andboxMax

fileName
: file containing the GLSL implicit program.
In the next example, we create an implicit whose points inside an origincentered sphere are considered solid. The radius of the sphere is changed using set_uniform_scalar
.
sphere = implicit(v(10,10,10), v(10,10,10), [[ uniform float r = 5; float distanceEstimator(vec3 p) { return length(p)  r; } ]]) set_uniform_scalar(sphere, 'r', 10.5) emit(sphere) 
Notice how in the above example, the implicit boundary cuts off some parts of the sphere. Implicits are commonly used to construct geometry that is impossible to create with CSG or lowresolution meshes. See the follwing example.
spahe = implicit(v(2,2,0), v(2,2,8), [[ float distanceEstimator(vec3 p) { return 0.01 * ((pow(sqrt(p.x*p.x + p.y*p.y)  3, 3) + p.z*p.z  1) + noise(p)); } ]]) emit(scale(5) * shape) 
Transformations
This section deals with linear transformations and as expected, IceSL offers functions to calculate transformations matrices. To apply the transformation, a transformation matrix is multiplied to a shape. In order to combine more than one transformation, the result of successive multiplications of transformation matrices may also be multiplied to a shape. All applications of transformations should be consistent with a righthanded coordinate system. This means the rightmost transformation in a combination takes precedence.
translate(dx,dy,dz)
_{IceSL}  _{IceSLonline}
 Returns a transformation matrix that translates a shape by
dx,dy,dz
units in the Xaxis, Yaxis and Zaxis respectively.

dx
: number of units to translate in the Xaxis 
dy
: number of units to translate in the Xaxis 
dy
: number of units to translate in the Xaxis
translate(v)
_{IceSL}  _{IceSLonline}
 Syntactic sugar for
translate(v.x,v.y,v.z)
.
rotate(angle,axis)
_{IceSL}  _{IceSLonline}
 Returns a transformation matrix that rotates a shape by
angle
degrees around the vectoraxis
.

angle
: angle of roation. In degrees 
axis
: a vector specifying the axis of rotation
rotate(rx,ry,rz)
_{IceSL}  _{IceSLonline}
rotate(v)
_{IceSL}  _{IceSLonline}
 Syntactic sugar for
rotate(rx,X) * rotate(ry,Y) * rotate(rz,Z)
androtate(v.x,X) * rotate(v.y,Y) * rotate(v.z,Z)
respectively.
scale(sx, sy, sz)
_{IceSL}  _{IceSLonline}
 Returns a transformation matrix that scales a shape by
sx,sy,sz
factors in the Xaxis, Yaxis and Zaxis respectively.

sx
: scale factor in the Xaxis 
sy
: scale factor in the Xaxis 
sy
: scale factor in the Xaxis
scale(s)
_{IceSL}  _{IceSLonline}
scale(v)
_{IceSL}  _{IceSLonline}
 Syntactic sugar for
scale(s,s,s)
andscale(v.x,v.y,v.z)
respectively.
The above transformations have alternative names (mainly for compatibility purposes). The next table summarizes them:
Transformation  Alternative 

translate

translation

rotate

rotation

scale

scaling

mirror(normal)
_{IceSL}  _{IceSLonline}
 Returns a transformation matrix that mirrors a shape along the vector
normal
.

normal
: vector specifying the direction to mirror
mesh = load_centered('fox.stl') emit( mesh ) emit( translate(0,100,0) * mirror(v(0,1,0)) * mesh ) 
frame(v)
_{IceSL}  _{IceSLonline}
 Returns a transformation matrix that orients (i.e. aligns) a shape's up vector to the direction
v
.

v
: a vector specifying the direction to orientate in the transformation.
Magnets
Magnets are volumeless shapes that help building objects by way of assembling parts. Think of a magnet as a fastener in a shape that eventually couples with others from different shapes.
magnet('name')
_{IceSL}  _{IceSLonline}
name
: magnet name
case = union( cylinder(5,10), translate(0,0,10) * magnet('m1') ) head = union( cone(5,1,10), translate(0,0,0) * rotate(180,X) * magnet('m2') ) emit(case) emit(translate(20,0,0) * head) 
Magnets have orientation (the coupling orientation). To couple the magnets, the function snap
returns a transformation matrix that assembles one shape's magnet (i.e. shape1
) to another (i.e. shape0
). The example below builds upon the previous one with the last two emit
statements removed.
snap(shape0, magnet0, shape1, magnet1)
_{IceSL}  _{IceSLonline}

shape0
: base shape 
magnet0
: the base shape's magnet name 
shape1
: shape to be coupled 
magnet1
: coupling shape's magnet name
smatrix = snap(case, 'm1', head, 'm2') emit(union(smatrix * head, case)) 
Snap matrices are not commutative. Notice in the previous example that multiplying smatrix
with case
will not yield the same result.
Operations
IceSL suports Constructive Solid Geometry (hereafter refered to as CSG). The following is a list of CSG operations:
CSG Operations
union(s0,s1)
_{IceSL}  _{IceSLonline}
 Returns a shape as the union of shape
s0
and shapes1
. This operation is commutative.

s0
: A shape 
s1
: A shape
intersection(s0,s1)
_{IceSL}  _{IceSLonline}
 Returns a shape as the intersection of shape
s0
and shapes1
. This operation is commutative.

s0
: A shape 
s1
: A shape
difference(s0,s1)
_{IceSL}  _{IceSLonline}
 Returns a shape as the difference of shape
s0
and shapes1
. This operation is not commutative.

s0
: A shape 
s1
: A shape
IceSL supports abbreviated multiinput versions of these operations. The following is a table detailing them.
Operation  NArgument Version  Short Version 

union(s0,s1)

union{s0,...,sn} 
U(s0,s1), U{s0,...,s1}

intersection(s0,s1)

intersection{s0,...,sn} 
I(s0,s1), I{s0,...,s1}

difference(s0,s1)

difference{s0,...,sn} 
D(s0,s1), D{s0,...,s1}

Other Operations
merge( s0, s1 )
_{IceSL}  _{IceSLonline}
merge{ s0,...,sn }
_{IceSL}  _{IceSLonline}
 Same as
union
, however this operation internally discards the CSG tree.merge
therefore creates a shape that produces less computational overhead, specially when the union consists of a large number of shapes.
flip(m)
_{IceSL}
 Inverts the orientation of the faces from the mesh
m
. This is specially useful when loading a mesh that has its faces defined clockwise.

m
: input mesh
convex_hull(shape)
_{IceSL}
 Created the convex hull of
shape
. It only works with meshes or union of meshes.

shape
: input primitive
mesh = load('crystal.stl') emit( translate(100,0,0) * mesh ) emit( convex_hull(mesh) ) 
dilate(mesh, factor)
_{IceSL}
erode(mesh, factor)
_{IceSL}

mesh
: input mesh 
factor
: dilation/erosion factor
mesh = scale(0.1) * merge_vertices(load_centered('fox.stl')) emit(translate(0,0,6) * erode(mesh,0.3)) emit(translate(15,0,0) * dilate(mesh,0.5)) 
linear_offset(mesh,direction,offset)
_{IceSL}
 Creates a linear offset of
mesh
in the directiondirection
by factoroffset
. Depending on the sign ofoffset
, the offset either goes inwards (i.e. negative sign) or outwards (i.e. positive sign). Only works with meshes with connectivity information, callmerge_vertices
when such information does not exists (e.g. stl meshes).

mesh
: input mesh 
direction
: offset direction 
offset
: offset factor
mesh = merge_vertices(load('fox.stl')) emit( mesh ) emit( translate(100,0,0) * linear_offset(mesh,v(0,1,0),10) ) 
linear_offsets(mesh,directions,offsets)
_{IceSL}
 Same as
linear_offset
but multiple offsets can be applied at the same time.directions
andoffsets
are arrays of vectors and numbers respectively and they have an ordered onetoone correspondance.
Shape Representation
IceSL offers several functions for calculating representations of shapes (i.e., mehses, voxels, etc).
to_voxel_volume(shape, voxSize)
_{IceSL}
 Creates a voxel volume from
shape
where each voxel measuresvoxSize
units.

shape
: input shape 
voxSize
: voxel size (in mm)
to_voxel_distance_field(shape, voxSize)
_{IceSL}
 Creates a voxel distance field from
shape
using this technique. Each voxel measuresvoxSize
units.

shape
: input shape 
voxSize
: voxel size (in mm)
smooth_voxels(voxShape, windowSize)
_{IceSL}
 Smoothes the voxel shape
voxShape
using a trilinear interpolation with a windows size ofwindowSize
. This functions does not return a shape, instead it modifies the shape received in the first parameter.

voxShape
: input shape. Only supports voxels 
windowSize
: interpolation 3D window size
s = sphere(5) v = to_voxel_volume(s, 0.1) vs = to_voxel_volume(s, 0.1) smooth_voxels(vs,10) emit(translate(0,0,0) * s) emit(translate(15,0,0) * v) emit(translate(30,0,0) * vs) 
to_mesh(shape, voxSize)
_{IceSL}
 Creates a mesh from
shape
using the marching cubes algorithm. Before calculating the resulting mesh, the 3D space containing the shape is discretized using voxels of sizevoxSize
units.

shape
: input shape 
voxSize
: voxel size of space discretization (in mm)
Distribute
Additionally to changing the representations of a shape, IceSL also provides a function to calculate the points covering a surface as well as its surface normals and maximum distance between each point.
distribute(shape, density)
_{IceSL}
 Returns a Lua array describing the surface of
shape
using Voronoid Iteration. The array is made out of triplets wherein the first element is a position of the surface, the second its surface normal and the third its distance to the furthest neighboring position in the array. How sparse the positions are is determined by the argumentdensity
.

shape
: input shape 
density
: position density. This argument is clamped to the unit inverval where 1 signifies high density and 0 no density
shape = cube(10) s = distribute(shape, 0.2) centroids = {} for i = 1,#s,1 do centroids[i] = translate(s[i][1]) * frame(s[i][2]) * merge{ cone(s[i][3],0,1), mirror(Z) * cone(s[i][3],0,1) } end emit(merge(centroids)) 
Other Functions
Mesh Information
bbox(shape)
_{IceSL}
 Returns the bounding box of
shape
as an objectAAB
.

shape
: Input shape
The AAB
object has the following members:

min_corner
: Minimum corner of the bounding box 
max_corner
: Maximum corner of the bounding box 
center
: Center of the bounding box 
extent
: Dimensions of the bounding box 
empty
: Boolean value indicating wether the bounding box is empty
mesh_vertices(mesh)
_{IceSL}
 Returns a table containing the vertices of a mesh.

mesh
: Input mesh
mesh_normals(mesh)
_{IceSL}
 Returns a table containing the normals of a mesh.

mesh
: Input mesh
Miscellaneous Functions
print(str)
_{IceSL}
 Prints the message
str

str
: input string
handle(name, shape)
_{IceSL}
 Assigns a handle to a shape. Handles are used to avoid ambiguity when selecting a shape in the user interface. They can be nested whereas in that case, the disambiguation will be settled by a windows asking the user to chose one of the nested handles.

name
: hande name. Optional 
shape
: shape to assign handle to.
sleep(ms)
_{IceSL}
 Suspends execution of IceSL by
ms
milliseconds.

ms
: numer of milliseconds
dofile(path)
_{IceSL}
 Executes the scipt in
path

path
: path to the script file
dump(shape, filename)
_{IceSL}
 Saves the shape
shape
in filefilename

shape
: shape to save 
filename
: destination file to save the shape. Supports stl and obj extensions