Home My Page Projects IceSL
 Summary Activity SCM Files Mediawiki

# Scripting - IceSL-Next

(Redirected from Scripting)

This is the official IceSL scripting language documentation wiki. Examples featured here are for the most part self-contained 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:

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

1. Vector (e.g.  v(1,0,0) )
2. Matrix (e.g.  m(1,0,0,1, 0,1,0,1, 0,0,1,1, 0,0,0,1) )
3. Shapes:
1. Primitive (e.g.  sphere(1) )
2. Mesh (e.g. 'fox.stl')
3. Voxels

## 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 | IceSL-online

•  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 1cm2.

Notice that, in order to have a visual aid on view orientation, axes are drown in the bottom-left 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 $\begin{bmatrix} x \\ y \\ z \end{bmatrix}$.
•  v(x,y)
• or  v{x,y} : : creates the vector$\begin{bmatrix} x \\ y \\ 0 \end{bmatrix}$.
Operations: Let v and u be vectors and n a number.
•  v + u : vector addition.
•  v - u : vector subtraction.
•  v * u : vector component-wise multiplication.
•  v / u : vector component-wise division
•  v * n  or  n * v : vector scalar multiplication.
•  v / n : vector scalar division.
•  -v : syntatic sugar for -1 * v.
•  dot(v, u) : dot product.
•  cross(v, u) : cross product.
•  normalize(v) : returns the unit vector $\hat{v}$.
•  length(v) : return the norm of v (i.e. | | v | | ).

### Matrices

Construction:
 m( m11, m12, m13, m14,
m21, m22, m23, m24,
m31, m32, m33, m34,
m41, m42, m43, m44 )
or
 m{ m11, m12, m13, m14,
m21, m22, m23, m24,
m31, m32, m33, m34,
m41, m42, m43, m44 }

Creates the matrix $\begin{bmatrix} m_{11} & m_{12} & m_{13} & m_{14} \\ m_{21} & m_{22} & m_{23} & m_{24} \\ m_{31} & m_{32} & m_{33} & m_{34}\\ m_{41} & m_{42} & m_{43} & m_{44}\end{bmatrix}$.

Operations: Let M and Q be matrices, let v be a vector and let s be a shape.
•  M * Q : matrix multiplication. Returns a matrix
•  M * v : matrix-vector multiplication. Returns a vector
•  M * s : shape transformation. Returns the shape transformed by M .
•  inverse(M) : matrix inversion. Returns the inverse of matrix M.

### Constants and Trigonometric Functions

The following are constants in IceSL

•  Pi : the π constant.
•  X : the vector v(1,0,0).
•  Y : the vector v(0,1,0).
•  Z : the vector v(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 | IceSL-online

Creates a sphere of radius r centered on the c. sphere(r) is syntactic sugar for sphere(r,v(0,0,0)) -a centered sphere.
•  r : the sphere's radius
•  c : the sphere's center

 cube(dx, dy, dz)  IceSL | IceSL-online

Creates a cube with with sides dx, dy, dz with its bottom face centered on the origin. cube(d) and cube(v) are syntactic sugars for  cube(d,d,d) and cube(v.x,v.y,v.z) respectively.
•  dx : length of the face perdendicular to the X-axis
•  dy : length of the face perpendicular to the Y-axis
•  dz : length of the face perpendicular to the Z-axis

 cone(r0, r1, c0, c1)  IceSL | IceSL-online

Creates a cone with base radius r0, top radius r1, base center c0 and top center c1. Moreover,  cone(r0,r1,h) is syntactic sugar for cone(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 | IceSL-online

Creates a cylinder with radius r, base center c0 and top center c1. It is syntactic sugar for cone(r,r,c0,c1). Additionally, cylinder(r,h) is also syntactic sugar for cone(r,r,h).

 polyhedron(points,indices)  IceSL | IceSL-online

Creates a polyhedron with points as its vertex and indices 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 lower-left corners at the origin.

### Non-primitive Shapes

 linear_extrude(dir, points)  IceSL | IceSL-online

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 counter-clockwise 2D vertices in points.
•  dir : extruding direction
•  points : polygon specification
 triangle = { v(-10,0), v(0,10), v(10,0) } -- 50 units along the Z-axis dir = v(0,0,50) emit( linear_extrude(dir, triangle) )

 linear_extrude_from_oriented(dir, points)  IceSL | IceSL-online

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) counter-clockwise 2D vertices and hollow geomtry is specified as a set of closed clockwise 2D vertices in points.
•  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 | IceSL-online

Creates a closed object from the spinning of a polygon along the Z-axis (axis of revolution). The polygon is specified as set of counter-clockwise 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 | IceSL-online

Creates an empty primitive

### Implicits

IceSL supports implicits by way of the GL Shading Language (GLSL). A comprehensive list of the built-in 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 by boxMin and boxMax defines the boundaries of the implicit shape.
•  boxMin, boxMax : domain of the implicit. The domain is specified by the box constructed with corners boxMin and boxMax
• 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_{boolean|scalar|vector|matrix}(implicit, var_name, var_value) IceSL

sets var_name to var_value inside implicit.
• 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 in fileName.
•  boxMin, boxMax : domain of the implicit. The domain is specified by the box constructed with corners boxMin and boxMax
• fileName: file containing the GLSL implicit program.

In the next example, we create an implicit whose points inside an origin-centered 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 low-resolution 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 right-handed coordinate system. This means the rightmost transformation in a combination takes precedence.

translate(dx,dy,dz)  IceSL | IceSL-online

Returns a transformation matrix that translates a shape by dx,dy,dz units in the X-axis, Y-axis and Z-axis respectively.
• dx : number of units to translate in the X-axis
• dy : number of units to translate in the X-axis
• dy : number of units to translate in the X-axis

translate(v) IceSL | IceSL-online

Syntactic sugar for translate(v.x,v.y,v.z).

rotate(angle,axis) IceSL | IceSL-online

Returns a transformation matrix that rotates a shape by angle degrees around the vector axis.
• angle : angle of roation. In degrees
• axis : a vector specifying the axis of rotation

rotate(rx,ry,rz) IceSL | IceSL-online

rotate(v) IceSL | IceSL-online

Syntactic sugar for rotate(rx,X) * rotate(ry,Y) * rotate(rz,Z)  and rotate(v.x,X) * rotate(v.y,Y) * rotate(v.z,Z)  respectively.

 scale(sx, sy, sz)  IceSL | IceSL-online

Returns a transformation matrix that scales a shape by sx,sy,sz factors in the X-axis, Y-axis and Z-axis respectively.
• sx : scale factor in the X-axis
• sy : scale factor in the X-axis
• sy : scale factor in the X-axis

 scale(s)  IceSL | IceSL-online

 scale(v)  IceSL | IceSL-online

Syntactic sugar for scale(s,s,s) and scale(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 | IceSL-online

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

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

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

• 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 | IceSL-online

Returns a shape as the union of shape s0 and shape s1. This operation is commutative.
•  s0 : A shape
•  s1 : A shape

 intersection(s0,s1)  IceSL | IceSL-online

Returns a shape as the intersection of shape s0 and shape s1. This operation is commutative.
•  s0 : A shape
•  s1 : A shape

 difference(s0,s1)  IceSL | IceSL-online

Returns a shape as the difference of shape s0 and shape s1. This operation is not commutative.
•  s0 : A shape
•  s1 : A shape

IceSL supports abbreviated multi-input versions of these operations. The following is a table detailing them.

Operation N-Argument 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 | IceSL-online

 merge{ s0,...,sn }  IceSL | IceSL-online

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

Dilates and erodes a mesh respectively by factor.
•  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 direction direction by factor offset. Depending on the sign of offset, the offset either goes inwards (i.e. negative sign) or outwards (i.e. positive sign). Only works with meshes with connectivity information, call merge_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 and offsets are arrays of vectors and numbers respectively and they have an ordered one-to-one 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 measures voxSize 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 measures voxSize 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 of windowSize. 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 size voxSize 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 argument density.
•  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 object AAB.
•  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 file filename
• shape : shape to save
• filename : destination file to save the shape. Supports stl and obj extensions