Mentions légales du service

Skip to content
Snippets Groups Projects

Changes

Page history
  • New page
  • Templates
    • Update Scripting language authored by Salim Perchy's avatar Salim Perchy
    Hide whitespace changes
    Inline Side-by-side
    Showing
    with 1417 additions and 1402 deletions
    Scripting-language.md
    View page @ c5b36b91
    # IceSL scripting language specification # IceSL scripting language specification
    This is the official documentation of the IceSL scripting language. 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. This is the official documentation of the IceSL scripting language. 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 to the [IceSL forum page](https://groups.google.com/forum/?fromgroups#!forum/icesl). We welcome IceSL users to redirect their questions about the scripting language to the [IceSL forum page](https://groups.google.com/forum/?fromgroups#!forum/icesl).
    1. [Syntax](#syntax) 1. [Syntax](#syntax)
    2. [Drawing and Scale](#drawing) 2. [Drawing and Scale](#drawing)
    3. [Vectors, Matrices, Constants and Trigonometric Functions](#algebra) 3. [Vectors, Matrices, Constants and Trigonometric Functions](#algebra)
    1. [Vectors](#vectors) 1. [Vectors](#vectors)
    2. [Matrices](#matrices) 2. [Matrices](#matrices)
    3. [Constants, Trigonometric Functions and Angles](#constants) 3. [Constants, Trigonometric Functions and Angles](#constants)
    4. [Shapes](#shapes)
    1. [Primitive Shapes](#primitives) 4. [Shapes](#shapes)
    2. [Centered Primitives](#centered) 1. [Primitive Shapes](#primitives)
    3. [Non-primitive Shapes](#nonprimitives) 2. [Centered Primitives](#centered)
    4. [Implicits](#implicits) 3. [Non-primitive Shapes](#nonprimitives)
    1. [Progressive rendering](#progressive) 4. [Implicits](#implicits)
    2. [Uniform variables and file support](#uniforms) 1. [Progressive rendering](#progressive)
    3. [3D Textures](#3dtextures) 2. [Uniform variables and file support](#uniforms)
    5. [Transformations](#transformations) 3. [3D Textures](#3dtextures)
    1. [Magnets](#magnets)
    6. [Operations](#operations) 5. [Transformations](#transformations)
    1. [CSG Operations](#csg) 1. [Magnets](#magnets)
    2. [Other Operations](#otherops)
    7. [Shape Representation](#shaperep) 6. [Operations](#operations)
    1. [From assets](#assets) 1. [CSG Operations](#csg)
    2. [Distribute](#distribute) 2. [Other Operations](#otherops)
    8. [Other functionality](#otherfunc)
    1. [Printing settings](#settings) 7. [Shape Representation](#shaperep)
    2. [Variable caching](#caching) 1. [From assets](#assets)
    3. [Tweaks](#tweaks) 2. [Distribute](#distribute)
    4. [Fields](#fields)
    5. [Mesh Information](#meshinfo) 8. [Other functionality](#otherfunc)
    6. [Miscellaneous Functions](#miscfunc) 1. [Printing settings](#settings)
    9. [Service Mode](#servicemode) 2. [Distance field](#distfield)
    1. [Invoking Service Mode](#invokeservicemode) 3. [Variable caching](#caching)
    2. [Service Mode functions](#servicemodefunctions) 4. [Tweaks](#tweaks)
    3. [Examples](#servicemodeexamples) 5. [Fields](#fields)
    6. [Mesh Information](#meshinfo)
    ## Syntax <a name="syntax"></a> 7. [Miscellaneous Functions](#miscfunc)
    The scripting language of IceSL (hereafter referred to as IceSL) is a superset of [lua](http://www.lua.org/pil/contents.html). Moreover, IceSL has been designed to facilitate conversion from/to [OpenSCAD](https://en.wikibooks.org/wiki/OpenSCAD_User_Manual). 9. [Service Mode](#servicemode)
    1. [Invoking Service Mode](#invokeservicemode)
    IceSL also extends Lua's types in order to specify shapes and transforms. The main basic types are: 2. [Service Mode functions](#servicemodefunctions)
    3. [Examples](#servicemodeexamples)
    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)`) ## Syntax <a name="syntax"></a>
    3. Shapes:
    * Primitives (e.g. `sphere(1)`), The scripting language of IceSL (hereafter referred to as IceSL) is a superset of [lua](http://www.lua.org/pil/contents.html). Moreover, IceSL has been designed to facilitate conversion from/to [OpenSCAD](https://en.wikibooks.org/wiki/OpenSCAD_User_Manual).
    * Meshes (e.g. `load('fox.stl')`),
    * Implicits, IceSL also extends Lua's types in order to specify shapes and transforms. The main basic types are:
    * Voxels.
    1. Vector (e.g. `v(1,0,0)`)
    ## Drawing and Scale <a name="drawing"></a> 2. Matrix (e.g. `m(1,0,0,1, 0,1,0,1, 0,0,1,1, 0,0,0,1)`)
    3. Shapes:
    Creating a shape in IceSL does not automatically render it in the final scene. In order to do this, you need to emit it. * Primitives (e.g. `sphere(1)`),
    * Meshes (e.g. `load('fox.stl')`),
    ```emit( shape, brush )``` * Implicits,
    * Voxels.
    * ```shape```: the shape to render
    * ```brush```: the brush's index to render the shape with. 0 by default ## Drawing and Scale <a name="drawing"></a>
    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 (usually printing parameters like _infill percentage_). In case of overlapping, the group with the lower index takes priority. The next code exemplifies the use of <code>emit</code>: Creating a shape in IceSL does not automatically render it in the final scene. In order to do this, you need to emit it.
    <table> ```emit( shape, brush )```
    <tr>
    <td> * ```shape```: the shape to render
    * ```brush```: the brush's index to render the shape with. 0 by default
    ```lua
    b = box(10) 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 (usually printing parameters like _infill percentage_). In case of overlapping, the group with the lower index takes priority. The next code exemplifies the use of <code>emit</code>:
    emit( b, 0 )
    c = sphere(5) <table>
    emit( translate(0,0,5) * c, 1 ) <tr>
    ``` <td>
    </td> ```lua
    <td> b = box(10)
    <img src="uploads/3ca402a5562e1b73efad21373bd1adcc/Example_emit.png" width="200"> emit( b, 0 )
    </td> c = sphere(5)
    </tr> emit( translate(0,0,5) * c, 1 )
    </table> ```
    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<sup>2</sup>. </td>
    <td>
    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. <img src="uploads/3ca402a5562e1b73efad21373bd1adcc/Example_emit.png" width="200">
    </td>
    <img src="uploads/b4e0712ea9a780482db48e616e486370/Printing_bed.png" width="200"> </tr>
    </table>
    ## Vectors, Matrices, Constants and Trigonometric Functions <a name="algebra"></a>
    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<sup>2</sup>.
    ### Vectors <a name="vectors"></a>
    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.
    Construction
    * ```v(x,y,z)``` or ```v{x,y,z}```: creates the vector $`\begin{bmatrix} x \\ y \\ z <img src="uploads/b4e0712ea9a780482db48e616e486370/Printing_bed.png" width="200">
    \end{bmatrix}`$.
    * ```v(x,y)``` or ```v{x,y}```: creates the vector $`\begin{bmatrix} x \\ y \\ 0 \end{bmatrix}`$. ## Vectors, Matrices, Constants and Trigonometric Functions <a name="algebra"></a>
    Members: ### Vectors <a name="vectors"></a>
    * ```v.x```: $`x`$ coordinate
    * ```v.y```: $`y`$ coordinate Construction
    * ```v.z```: $`z`$ coordinate * ```v(x,y,z)``` or ```v{x,y,z}```: creates the vector $`\begin{bmatrix} x \\ y \\ z
    \end{bmatrix}`$.
    Operations: * ```v(x,y)``` or ```v{x,y}```: creates the vector $`\begin{bmatrix} x \\ y \\ 0 \end{bmatrix}`$.
    Let ```v``` and ```u``` be vectors and ```n``` a number.
    * ```v + u```: vector addition. Members:
    * ```v - u```: vector subtraction. * ```v.x```: $`x`$ coordinate
    * ```v * u```: vector component-wise multiplication. * ```v.y```: $`y`$ coordinate
    * ```v / u```: vector component-wise division * ```v.z```: $`z`$ coordinate
    * ```v * n``` or ```n * v```: vector scalar multiplication.
    * ```v / n```: vector scalar division. Operations:
    * ```v1 == v2```: vector comparison. Let ```v``` and ```u``` be vectors and ```n``` a number.
    * ```-v```: syntactic sugar for ```-1 * v```. * ```v + u```: vector addition.
    * ```dot(v, u)```: dot product. * ```v - u```: vector subtraction.
    * ```cross(v, u)```: cross product. * ```v * u```: vector component-wise multiplication.
    * ```normalize(v)```: returns the unit vector $`\hat{v}`$. * ```v / u```: vector component-wise division
    * ```length(v)```: return the norm of ```v``` (i.e. $`||v||`$). * ```v * n``` or ```n * v```: vector scalar multiplication.
    * ```v / n```: vector scalar division.
    ### Matrices <a name="matrices"></a> * ```v1 == v2```: vector comparison.
    * ```-v```: syntactic sugar for ```-1 * v```.
    Construction: * ```dot(v, u)```: dot product.
    * ```cross(v, u)```: cross product.
    ```m( m11, m12, m13, m14, m21, m22, m23, m24, m31, m32, m33, m34, m41, m42, m43, m44 )``` * ```normalize(v)```: returns the unit vector $`\hat{v}`$.
    * ```length(v)```: return the norm of ```v``` (i.e. $`||v||`$).
    or
    ### Matrices <a name="matrices"></a>
    ```m{ m11, m12, m13, m14, m21, m22, m23, m24, m31, m32, m33, m34, m41, m42, m43, m44 }```
    Construction:
    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}`$.
    ```m( m11, m12, m13, m14, m21, m22, m23, m24, m31, m32, m33, m34, m41, m42, m43, m44 )```
    Members:
    or
    * ```m:at(c,r)```: element at column ```c``` and row ```r```
    ```m{ m11, m12, m13, m14, m21, m22, m23, m24, m31, m32, m33, m34, m41, m42, m43, m44 }```
    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. 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}`$.
    * ```M * v```: matrix-vector multiplication. Returns a vector.
    * ```M * s```: shape transformation. Returns the shape transformed by ```M```. Members:
    * ```M1 == M2```: matrix comparison. Returns a boolean.
    * ```inverse(M)```: matrix inversion. Returns the inverse of matrix ```M```. * ```m:at(c,r)```: element at column ```c``` and row ```r```
    ### Constants, Trigonometric Functions and Angles <a name="constants"></a> 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.
    The following are constants in IceSL: * ```M * v```: matrix-vector multiplication. Returns a vector.
    * ```Pi```: the $`\pi`$ constant. * ```M * s```: shape transformation. Returns the shape transformed by ```M```.
    * ```X```: the vector ```v(1,0,0)```. * ```M1 == M2```: matrix comparison. Returns a boolean.
    * ```Y```: the vector ```v(0,1,0)```. * ```inverse(M)```: matrix inversion. Returns the inverse of matrix ```M```.
    * ```Z```: the vector ```v(0,0,1)```.
    * ```Id```: the identity matrix. ### Constants, Trigonometric Functions and Angles <a name="constants"></a>
    * ```Path```: the path of the current script.
    The following are constants in IceSL:
    IceSl can calculate the next trigonometric functions: * ```Pi```: the $`\pi`$ constant.
    ```sin```, ```asin```, ```cos```, ```acos```, ```tan```, ```atan```, ```atan2```. * ```X```: the vector ```v(1,0,0)```.
    * ```Y```: the vector ```v(0,1,0)```.
    Angles in IceSL are expected to be written in **degrees**. * ```Z```: the vector ```v(0,0,1)```.
    * ```Id```: the identity matrix.
    ## Shapes <a name="shapes"></a> * ```Path```: the path of the current script.
    ### Primitive Shapes <a name="primitives"></a>
    IceSl can calculate the next trigonometric functions:
    ```load(path)``` ```sin```, ```asin```, ```cos```, ```acos```, ```tan```, ```atan```, ```atan2```.
    Loads the 3d mesh at ```path```. The mesh must be watertight. Angles in IceSL are expected to be written in **degrees**.
    * ```path```: Absolute path to a 3d mesh. It supports the following extensions:
    * **stl** ## Shapes <a name="shapes"></a>
    * **obj** ### Primitive Shapes <a name="primitives"></a>
    * **3ds**
    ```load(path)```
    ```sphere(r, c)```
    Loads the 3d mesh at ```path```. The mesh must be watertight.
    Creates a sphere of radius ```r``` centered on ```c```. ```sphere(r)``` is syntactic sugar for ```sphere(r,v(0,0,0))``` -a centered sphere. * ```path```: Absolute path to a 3d mesh. It supports the following extensions:
    * ```r```: the sphere's radius * **stl**
    * ```c```: the sphere's center * **obj**
    * **3ds**
    ```cube(dx, dy, dz)```
    ```sphere(r, c)```
    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 perpendicular to the X-axis Creates a sphere of radius ```r``` centered on ```c```. ```sphere(r)``` is syntactic sugar for ```sphere(r,v(0,0,0))``` -a centered sphere.
    * ```dy```: length of the face perpendicular to the Y-axis * ```r```: the sphere's radius
    * ```dz```: length of the face perpendicular to the Z-axis * ```c```: the sphere's center
    ```cone(r0, r1, c0, c1)``` ```cube(dx, dy, dz)```
    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))```. 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.
    * ```r0```: the cone's base radius * ```dx```: length of the face perpendicular to the X-axis
    * ```r1```: the cone's top radius * ```dy```: length of the face perpendicular to the Y-axis
    * ```c0```: the cone's base center * ```dz```: length of the face perpendicular to the Z-axis
    * ```c1```: the cone's top center
    ```cone(r0, r1, c0, c1)```
    ```cylinder(r, c0, c1)```
    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))```.
    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)```. * ```r0```: the cone's base radius
    * ```r1```: the cone's top radius
    ```polyhedron(points,indices)``` * ```c0```: the cone's base center
    * ```c1```: the cone's top center
    Creates a polyhedron with ```points``` as its vertex and ```indices``` to specify its faces.
    * ```points```: an array of vectors containing the polyhedron's vertex ```cylinder(r, c0, c1)```
    * ```indices```: an array of vectors specifying the polyhedron's faces. Each vector specifies a face constructed from three vertex indices represented by the vector's components. Indices start from 0 and faces point outwards whenever the orientation of the vertices to which the indices refer to is counterclockwise.
    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)```.
    <table>
    <tr> ```polyhedron(points,indices)```
    <td>
    Creates a polyhedron with ```points``` as its vertex and ```indices``` to specify its faces.
    ```lua * ```points```: an array of vectors containing the polyhedron's vertex
    p = polyhedron( * ```indices```: an array of vectors specifying the polyhedron's faces. Each vector specifies a face constructed from three vertex indices represented by the vector's components. Indices start from 0 and faces point outwards whenever the orientation of the vertices to which the indices refer to is counterclockwise.
    { 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) } ) <table>
    emit( p ) <tr>
    ``` <td>
    </td> ```lua
    <td> p = polyhedron(
    <img src="uploads/384b83224915015bc3e3238dff4845b0/Example_polyhedron.png" width="200"> { v(0,0,0), v(1,0,0), v(0,1,0), v(1,1,0), v(0.5,0.5,1) },
    </td> { v(0,3,1), v(0,2,3), v(0,1,4), v(1,3,4), v(3,2,4), v(2,0,4) } )
    </tr> emit( p )
    </table> ```
    ```Void``` </td>
    <td>
    Creates an empty primitive <img src="uploads/384b83224915015bc3e3238dff4845b0/Example_polyhedron.png" width="200">
    </td>
    ### Centered Primitives <a name="centered"></a> </tr>
    </table>
    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.
    ```Void```
    | Primitive | Centered Version | Alternative Centered Version |
    | --------- | ---------------- | ---------------------------- | Creates an empty primitive
    | ```load(path)``` | ```load_centered(path)``` | ```load_centered_on_plate(path)``` |
    | ```cube(dx,dy,dz)``` | ```ccube(dx,dy,dz)``` | ```box(dx,dy,dz)``` | ### Centered Primitives <a name="centered"></a>
    | ```cone(r0,r1,h)``` | ```ccone(r0,r1,h)``` | |
    | ```cylinder(r,h)``` | ```ccylinder(r,h)``` | | 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.
    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. | Primitive | Centered Version | Alternative Centered Version |
    | --------- | ---------------- | ---------------------------- |
    ### Non-primitive Shapes <a name="nonprimitives"></a> | ```load(path)``` | ```load_centered(path)``` | ```load_centered_on_plate(path)``` |
    | ```cube(dx,dy,dz)``` | ```ccube(dx,dy,dz)``` | ```box(dx,dy,dz)``` |
    ```linear_extrude(dir, points)``` | ```cone(r0,r1,h)``` | ```ccone(r0,r1,h)``` | |
    | ```cylinder(r,h)``` | ```ccylinder(r,h)``` | |
    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 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.
    * ```points```: polygon specification
    ### Non-primitive Shapes <a name="nonprimitives"></a>
    <table>
    <tr> ```linear_extrude(dir, points)```
    <td>
    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```.
    ```lua * ```dir```: extruding direction
    triangle = { v(-10,0), v(0,10), v(10,0) } * ```points```: polygon specification
    -- 50 units along the Z-axis
    dir = v(0,0,50) <table>
    emit( linear_extrude(dir, triangle) ) <tr>
    ``` <td>
    </td> ```lua
    <td> triangle = { v(-10,0), v(0,10), v(10,0) }
    <img src="uploads/d49fa94fafa25664d5a02a674f2b21ae/Example_linear_extrude.png" width="200"> -- 50 units along the Z-axis
    </td> dir = v(0,0,50)
    </tr> emit( linear_extrude(dir, triangle) )
    </table> ```
    ```linear_extrude_from_oriented(dir, points)``` </td>
    <td>
    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 geometry is specified as a set of closed clockwise 2D vertices in ```points```. <img src="uploads/d49fa94fafa25664d5a02a674f2b21ae/Example_linear_extrude.png" width="200">
    * ```dir```: extruding direction </td>
    * ```points```: polygon specification </tr>
    </table>
    <table>
    <tr> ```linear_extrude_from_oriented(dir, points)```
    <td>
    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 geometry is specified as a set of closed clockwise 2D vertices in ```points```.
    ```lua * ```dir```: extruding direction
    polygon1 = { v(10,10), v(-10,10), v(-10,-10), v(10,-10), v(10,10) } -- Solid * ```points```: polygon specification
    polygon2 = { v(0,6), v(6,-6), v(-6,-6), v(0,6) } -- Hollow
    dir = v(0,0,10) <table>
    emit( union( <tr>
    linear_extrude_from_oriented(dir, polygon1), <td>
    linear_extrude_from_oriented(dir, polygon2)
    ) ) ```lua
    ``` polygon1 = { v(10,10), v(-10,10), v(-10,-10), v(10,-10), v(10,10) } -- Solid
    polygon2 = { v(0,6), v(6,-6), v(-6,-6), v(0,6) } -- Hollow
    </td> dir = v(0,0,10)
    <td> emit( union(
    <img src="uploads/2c40c2e7a34c7b15751a6425267aaf18/Example_linear_extrude_from_oriented.png" width="200"> linear_extrude_from_oriented(dir, polygon1),
    </td> linear_extrude_from_oriented(dir, polygon2)
    </tr> ) )
    </table> ```
    ```rotate_extrude(points, nsteps)``` </td>
    <td>
    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 steps the smoother the resulting shape is. <img src="uploads/2c40c2e7a34c7b15751a6425267aaf18/Example_linear_extrude_from_oriented.png" width="200">
    </td>
    <table> </tr>
    <tr> </table>
    <td>
    ```rotate_extrude(points, nsteps)```
    ```lua
    radius = v(10,0,0) 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 steps the smoother the resulting shape is.
    triangle = { radius + v(1,0,0), radius + v(0,1,0), radius + v(-1,0,0) }
    emit( rotate_extrude( triangle, 100 ) ) <table>
    ``` <tr>
    <td>
    </td>
    <td> ```lua
    <img src="uploads/ae89126ccae1653103493ffef57bc099/Example_rotate_extrude.png" width="200"> radius = v(10,0,0)
    </td> triangle = { radius + v(1,0,0), radius + v(0,1,0), radius + v(-1,0,0) }
    </tr> emit( rotate_extrude( triangle, 100 ) )
    </table> ```
    ```sections_extrude(contours)``` </td>
    <td>
    Crates a closed object by connecting each polygon contained in ```contours```. Similar to the functions above, a polygon is defined as a table of at least three points. ```contours``` is a table of more than one polygon and all polygons must contain the same number of points. <img src="uploads/ae89126ccae1653103493ffef57bc099/Example_rotate_extrude.png" width="200">
    </td>
    <table> </tr>
    <tr> </table>
    <td>
    ```sections_extrude(contours)```
    ```lua
    se = sections_extrude({ Crates a closed object by connecting each polygon contained in ```contours```. Similar to the functions above, a polygon is defined as a table of at least three points. ```contours``` is a table of more than one polygon and all polygons must contain the same number of points.
    {rotate( 0,Z) * v( 0, 0, 0),
    rotate( 0,Z) * v(10, 0, 0), <table>
    rotate( 0,Z) * v(10,10, 0), <tr>
    rotate( 0,Z) * v( 0,10, 0)}, <td>
    {rotate( 60,Z) * v( 0, 0,10), ```lua
    rotate( 60,Z) * v(10, 0,10), se = sections_extrude({
    rotate( 60,Z) * v(10,10,10), {rotate( 0,Z) * v( 0, 0, 0),
    rotate( 60,Z) * v( 0,10,10)}, rotate( 0,Z) * v(10, 0, 0),
    rotate( 0,Z) * v(10,10, 0),
    {rotate(120,Z) * v( 0, 0,20), rotate( 0,Z) * v( 0,10, 0)},
    rotate(120,Z) * v(10, 0,20),
    rotate(120,Z) * v(10,10,20), {rotate( 60,Z) * v( 0, 0,10),
    rotate(120,Z) * v( 0,10,20)} rotate( 60,Z) * v(10, 0,10),
    }) rotate( 60,Z) * v(10,10,10),
    emit(se) rotate( 60,Z) * v( 0,10,10)},
    ```
    {rotate(120,Z) * v( 0, 0,20),
    </td> rotate(120,Z) * v(10, 0,20),
    <td> rotate(120,Z) * v(10,10,20),
    <img src="uploads/84e315d1cc4e2a6fbad720171f180280/Example_sections_extrude.jpg" width="200"> rotate(120,Z) * v( 0,10,20)}
    </td> })
    </tr> emit(se)
    </table> ```
    ### Implicits <a name="implicits"></a> </td>
    <td>
    IceSL supports implicits by way of the [GL Shading Language](https://www.khronos.org/opengl/wiki/OpenGL_Shading_Language) (GLSL). A comprehensive list of the built-in functions of GLSL can be found [here](http://www.shaderific.com/glsl-functions/) <img src="uploads/84e315d1cc4e2a6fbad720171f180280/Example_sections_extrude.jpg" width="200">
    </td>
    ```implicit_distance_field(boxMin, boxMax, fragment)``` </tr>
    </table>
    ```implicit_solid(boxMin, boxMax, voxSize, fragment)```
    ### Implicits <a name="implicits"></a>
    Creates an object out of the [implicit geometry](https://en.wikipedia.org/wiki/Implicit_function) 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``` IceSL supports implicits by way of the [GL Shading Language](https://www.khronos.org/opengl/wiki/OpenGL_Shading_Language) (GLSL). A comprehensive list of the built-in functions of GLSL can be found [here](http://www.shaderific.com/glsl-functions/)
    * ```voxSize```: voxel output size. Lower values result in greater quality at the expense of higher calculation costs.
    * ```fragment```: string containing the GLSL program. This program calculates the implicit function that defines the output geometry. ```implicit_distance_field(boxMin, boxMax, fragment)```
    Implicits are calculated in IceSL with a sphere tracing method (detailed [here](http://graphics.cs.illinois.edu/sites/default/files/zeno.pdf)). The program specified in ```fragment``` must contain a function called either ```float distance(vec3 p)```, in the case of ```implicit_distance_field```, or ```float solid(vec3 p)``` in the case of ```implicit_solid```. This function calculates the distance field or the solid/empty classification respectively for every point of the domain of the box. A resulting negative value is interpreted as _solid_ whereas a positive value means _hollow_. Consider the following example. ```implicit_solid(boxMin, boxMax, voxSize, fragment)```
    <table> Creates an object out of the [implicit geometry](https://en.wikipedia.org/wiki/Implicit_function) calculated in ```fragment```. The bounding box constructed by ```boxMin``` and ```boxMax``` defines the boundaries of the implicit shape.
    <tr> * ```boxMin, boxMax```: domain of the implicit. The domain is specified by the box constructed with corners ```boxMin``` and ```boxMax```
    <td> * ```voxSize```: voxel output size. Lower values result in greater quality at the expense of higher calculation costs.
    * ```fragment```: string containing the GLSL program. This program calculates the implicit function that defines the output geometry.
    ```lua
    cube = implicit_distance_field( v(-10,-10,-10), v(10,10,10), Implicits are calculated in IceSL with a sphere tracing method (detailed [here](http://graphics.cs.illinois.edu/sites/default/files/zeno.pdf)). The program specified in ```fragment``` must contain a function called either ```float distance(vec3 p)```, in the case of ```implicit_distance_field```, or ```float solid(vec3 p)``` in the case of ```implicit_solid```. This function calculates the distance field or the solid/empty classification respectively for every point of the domain of the box. A resulting negative value is interpreted as _solid_ whereas a positive value means _hollow_. Consider the following example.
    [[
    float distance(vec3 p) { <table>
    return -1; <tr>
    } <td>
    ]])
    emit (cube) ```lua
    ``` cube = implicit_distance_field( v(-10,-10,-10), v(10,10,10),
    [[
    </td> float distance(vec3 p) {
    <td> return -1;
    <img src="uploads/98f1f60e808308d35a4b4f2ea2e9280c/Example_implicit_1.png" width="200"> }
    </td> ]])
    </tr> emit (cube)
    </table> ```
    Above, every point in the domain of the implicit is marked as _solid_, therefore the geometry created has the shape of the boundary box. </td>
    <td>
    Choosing ```implicit_distance_field``` over ```implicit_solid``` can be summarized as follows: The former requires to estimate a distance to the surface, which can prove difficult and prone to artifacts (when the estimate is too far off from reality). The latter is much easier, as the function simply has to return negative for solid and positive for empty. <img src="uploads/98f1f60e808308d35a4b4f2ea2e9280c/Example_implicit_1.png" width="200">
    </td>
    #### Progressive rendering <a name="progressive"></a> </tr>
    </table>
    IceSL by default progressively renders implicits, consequently all the implicit's geometry may not render in one single frame. The order of rendering is defined by the distance to the camera (i.e. scene's point of view). To disable/enable this behavior use the following:
    Above, every point in the domain of the implicit is marked as _solid_, therefore the geometry created has the shape of the boundary box.
    ```enable_progressive_rendering(shape, bool)```
    * ```shape```: output from either the ```implicit_*``` or ```to_voxel_*``` functions. Choosing ```implicit_distance_field``` over ```implicit_solid``` can be summarized as follows: The former requires to estimate a distance to the surface, which can prove difficult and prone to artifacts (when the estimate is too far off from reality). The latter is much easier, as the function simply has to return negative for solid and positive for empty.
    * ```bool```: either ```true``` or ```false```
    #### Progressive rendering <a name="progressive"></a>
    This setting must be set right after the implicit/voxels creation. This is because IceSL clones a shape whenever it is transformed and/or reassigned to another variable. Each clone drags with it the _current_ value of this setting.
    IceSL by default progressively renders implicits, consequently all the implicit's geometry may not render in one single frame. The order of rendering is defined by the distance to the camera (i.e. scene's point of view). To disable/enable this behavior use the following:
    #### Uniform variables and file support <a name="uniforms"></a>
    ```enable_progressive_rendering(shape, bool)```
    It is possible to set values for uniform variables specified inside the implicit's GLSL program via lua commands. * ```shape```: output from either the ```implicit_*``` or ```to_voxel_*``` functions.
    * ```bool```: either ```true``` or ```false```
    ```set_uniform_{boolean|scalar|vector|matrix|texture3d}(implicit, var_name, var_value)```
    This setting must be set right after the implicit/voxels creation. This is because IceSL clones a shape whenever it is transformed and/or reassigned to another variable. Each clone drags with it the _current_ value of this setting.
    sets ```var_name``` to ```var_value``` inside ```implicit```.
    * ```implicit```: a created implicit #### Uniform variables and file support <a name="uniforms"></a>
    * ```var_name```: string specifying the name of the uniform variable in the implicit
    * ```var_value```: new boolean/scalar/vector/matrix/texture3d/voxel_distance_field value It is possible to set values for uniform variables specified inside the implicit's GLSL program via lua commands.
    Furthermore, implicits can be loaded directly from files as the next function shows. ```set_uniform_{boolean|scalar|vector|matrix|texture3d}(implicit, var_name, var_value)```
    ```implicit_distance_field_from_file(boxMin, boxMax, fileName)``` sets ```var_name``` to ```var_value``` inside ```implicit```.
    * ```implicit```: a created implicit
    ```implicit_solid_from_file(boxMin, boxMax, voxSize, fileName)``` * ```var_name```: string specifying the name of the uniform variable in the implicit
    * ```var_value```: new boolean/scalar/vector/matrix/texture3d/voxel_distance_field value
    Similar to ```implicit_distance_field``` and ```implicit_solid``` but 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``` Furthermore, implicits can be loaded directly from files as the next function shows.
    * ```fileName```: file containing the GLSL implicit program.
    * ```voxSize```: voxel output size. ```implicit_distance_field_from_file(boxMin, boxMax, fileName)```
    ```implicit_solid_from_file(boxMin, boxMax, voxSize, fileName)```
    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```.
    Similar to ```implicit_distance_field``` and ```implicit_solid``` but the fragment program is in ```fileName```.
    <table> * ```boxMin, boxMax```: domain of the implicit. The domain is specified by the box constructed with corners ```boxMin``` and ```boxMax```
    <tr> * ```fileName```: file containing the GLSL implicit program.
    <td> * ```voxSize```: voxel output size.
    ```lua
    sphere = implicit_solid(v(-10,-10,-10), v(10,10,10), 0.25, 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```.
    [[
    uniform float r = 5; <table>
    float solid(vec3 p) { <tr>
    return length(p) - r; <td>
    }
    ]]) ```lua
    set_uniform_scalar(sphere, 'r', 10.5) sphere = implicit_solid(v(-10,-10,-10), v(10,10,10), 0.25,
    emit(sphere) [[
    ``` uniform float r = 5;
    float solid(vec3 p) {
    </td> return length(p) - r;
    <td> }
    <img src="uploads/ae21547d9fbf2d1199d8ce753f9441e8/Example_implicit_2.png" width="200"> ]])
    </td> set_uniform_scalar(sphere, 'r', 10.5)
    </tr> emit(sphere)
    </table> ```
    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 following example. </td>
    <td>
    <table> <img src="uploads/ae21547d9fbf2d1199d8ce753f9441e8/Example_implicit_2.png" width="200">
    <tr> </td>
    <td> </tr>
    </table>
    ```lua
    shape = implicit_distance_field(v(-2,-2,0), v(2,2,8), 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 following example.
    [[
    float distance(vec3 p) { <table>
    return 0.01 * ((pow(sqrt(p.x*p.x + p.y*p.y) - 3, 3) + p.z*p.z - 1) + noise(p)); <tr>
    } <td>
    ]])
    emit(scale(5) * shape) ```lua
    ``` shape = implicit_distance_field(v(-2,-2,0), v(2,2,8),
    [[
    </td> float distance(vec3 p) {
    <td> return 0.01 * ((pow(sqrt(p.x*p.x + p.y*p.y) - 3, 3) + p.z*p.z - 1) + noise(p));
    <img src="uploads/06292b311081b3b4ba6f77fe2aa7c356/Example_implicit_3.png" width="200"> }
    </td> ]])
    </tr> emit(scale(5) * shape)
    </table> ```
    #### 3D Textures <a name="3dtextures"></a> </td>
    <td>
    IceSL features the ability to construct 3D textures programmatically. There is support for single channel textures as well as RGB textures in 8bit and 32bit variants. <img src="uploads/06292b311081b3b4ba6f77fe2aa7c356/Example_implicit_3.png" width="200">
    </td>
    ```tex3d_{rgb32f|r32f|rgb8f|r8f}(w,h,d)``` </tr>
    </table>
    Creates a 3d texture class with the following possible specifications:
    * ```rgb32f```: rgb 32bit float texture #### 3D Textures <a name="3dtextures"></a>
    * ```r32f```: luminance 32bit float texture
    * ```rgb8f```: rgb 8bit float texture IceSL features the ability to construct 3D textures programmatically. There is support for single channel textures as well as RGB textures in 8bit and 32bit variants.
    * ```r8f```: luminance 8bit float texture
    ```tex3d_{rgb32f|r32f|rgb8f|r8f}(w,h,d)```
    The 3D texture class possesses the following methods:
    * ```w()```: return the texture's width Creates a 3d texture class with the following possible specifications:
    * ```h()```: return the texture's height * ```rgb32f```: rgb 32bit float texture
    * ```d()```: return the texture's depth * ```r32f```: luminance 32bit float texture
    * ```set(u,v,w,val)```: sets the value ```val``` at texture coordinate ```(u,v,w)```. ```val``` is a vector where each component must be in the range $`[0-1]`$. If the texture type is luminance (i.e., one channel texture), the second and third components of ```val``` are ignored. * ```rgb8f```: rgb 8bit float texture
    * ```r8f```: luminance 8bit float texture
    The following example shows a 1-channel 3D texture created programmatically and used as input in an implicit. Two solid cubes (one on each corner) made of the value ```-1.0``` are drawn into the texture while the rest is left at value ```10.0```. The implicit maps each point of the implicit area to a point of the texture repeated twice.
    The 3D texture class possesses the following methods:
    <table> * ```w()```: return the texture's width
    <tr> * ```h()```: return the texture's height
    <td> * ```d()```: return the texture's depth
    * ```get(u,v,w)```: gets the value at texture coordinate ```(u,v,w)```. Values of each component are in the range $`[0-1]`$.
    ```lua * ```set(u,v,w,val)```: sets the value ```val``` at texture coordinate ```(u,v,w)```. ```val``` is a vector where each component must be in the range $`[0-1]`$. If the texture type is luminance (i.e., one channel texture), the second and third components of ```val``` are ignored.
    tex_dim = v(10,10,10)
    tex = tex3d_r32f(tex_dim.x,tex_dim.y,tex_dim.z) The following example shows a 1-channel 3D texture created programmatically and used as input in an implicit. Two solid cubes (one on each corner) made of the value ```-1.0``` are drawn into the texture while the rest is left at value ```10.0```. The implicit maps each point of the implicit area to a point of the texture repeated twice.
    for ucoord = 0, tex_dim.x-1 do
    for vcoord = 0, tex_dim.y-1 do <table>
    for wcoord = 0, tex_dim.z-1 do <tr>
    if (ucoord < tex_dim.x/2 and vcoord < tex_dim.y/2 and wcoord < tex_dim.z/2) or <td>
    (ucoord >= tex_dim.x/2 and vcoord >= tex_dim.y/2 and wcoord >= tex_dim.z/2) then
    tex:set(ucoord,vcoord,wcoord,v(-1.0,0.0,0.0)) ```lua
    else tex_dim = v(10,10,10)
    tex:set(ucoord,vcoord,wcoord,v(10.0,0.0,0.0)) tex = tex3d_r32f(tex_dim.x,tex_dim.y,tex_dim.z)
    end for ucoord = 0, tex_dim.x-1 do
    end for vcoord = 0, tex_dim.y-1 do
    end for wcoord = 0, tex_dim.z-1 do
    end if (ucoord < tex_dim.x/2 and vcoord < tex_dim.y/2 and wcoord < tex_dim.z/2) or
    (ucoord >= tex_dim.x/2 and vcoord >= tex_dim.y/2 and wcoord >= tex_dim.z/2) then
    imp_dim = v(20,20,20) tex:set(ucoord,vcoord,wcoord,v(-1.0,0.0,0.0))
    imp = implicit_distance_field(v(0,0,0), imp_dim, else
    [[ tex:set(ucoord,vcoord,wcoord,v(10.0,0.0,0.0))
    uniform sampler3D tex_data; end
    uniform vec3 imp_ext; end
    float distance(vec3 p) end
    { end
    return 0.01 * texture(tex_data,(p/imp_ext)*2.0).x;
    } imp_dim = v(20,20,20)
    ]]) imp = implicit_distance_field(v(0,0,0), imp_dim,
    set_uniform_vector(imp, 'imp_ext', imp_dim) [[
    set_uniform_texture3d(imp, 'tex_data', tex) uniform sampler3D tex_data;
    uniform vec3 imp_ext;
    emit(imp) float distance(vec3 p)
    {
    ``` return 0.01 * texture(tex_data,(p/imp_ext)*2.0).x;
    }
    </td> ]])
    <td> set_uniform_vector(imp, 'imp_ext', imp_dim)
    <img src="uploads/ad5c9dcb1ccff2a925dc5061f1e4cbd4/Example_3dtex.png" width="200"> set_uniform_texture3d(imp, 'tex_data', tex)
    </td>
    </tr> emit(imp)
    </table>
    ```
    ## Transformations <a name="transformations"></a>
    </td>
    This section deals with linear transformations. IceSL offers functions to calculate matrices of transformations. To apply a transformation, a transformation matrix is multiplied with a shape. In order to combine more than one transformation, the result of successive multiplications of transformation matrices may also be multiplied with a shape. All applications of transformations should be consistent with a [http://mathworld.wolfram.com/Right-HandedCoordinateSystem.html right-handed coordinate system]. This means the *rightmost transformation* in a combination *takes precedence*. <td>
    <img src="uploads/ad5c9dcb1ccff2a925dc5061f1e4cbd4/Example_3dtex.png" width="200">
    ```translate(dx,dy,dz)``` </td>
    </tr>
    Returns a transformation matrix that translates a shape by ```dx,dy,dz``` units in the X-axis, Y-axis and Z-axis respectively. </table>
    * ```dx```: number of units to translate in the X-axis
    * ```dy```: number of units to translate in the Y-axis ## Transformations <a name="transformations"></a>
    * ```dz```: number of units to translate in the Z-axis
    This section deals with linear transformations. IceSL offers functions to calculate matrices of transformations. To apply a transformation, a transformation matrix is multiplied with a shape. In order to combine more than one transformation, the result of successive multiplications of transformation matrices may also be multiplied with a shape. All applications of transformations should be consistent with a [http://mathworld.wolfram.com/Right-HandedCoordinateSystem.html right-handed coordinate system]. This means the *rightmost transformation* in a combination *takes precedence*.
    ```translate(v)```
    ```translate(dx,dy,dz)```
    Syntactic sugar for ```translate(v.x,v.y,v.z)```.
    Returns a transformation matrix that translates a shape by ```dx,dy,dz``` units in the X-axis, Y-axis and Z-axis respectively.
    ```rotate(angle,axis)``` * ```dx```: number of units to translate in the X-axis
    * ```dy```: number of units to translate in the Y-axis
    Returns a transformation matrix that rotates a shape by ```angle``` degrees around the vector ```axis```. * ```dz```: number of units to translate in the Z-axis
    * ```angle```: angle of rotation. In degrees
    * ```axis```: a vector specifying the axis of rotation ```translate(v)```
    ```rotate(rx,ry,rz)``` Syntactic sugar for ```translate(v.x,v.y,v.z)```.
    ```rotate(v)``` ```rotate(angle,axis)```
    Syntactic sugar for ```rotate(rz,Z) * rotate(ry,Y) * rotate(rx,X)``` and ```rotate(v.z,Z) * rotate(v.y,Y) * rotate(v.x,X)``` respectively. Returns a transformation matrix that rotates a shape by ```angle``` degrees around the vector ```axis```.
    * ```angle```: angle of rotation. In degrees
    ```scale(sx, sy, sz)``` * ```axis```: a vector specifying the axis of rotation
    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 ```rotate(rx,ry,rz)```
    * ```sy```: scale factor in the Y-axis
    * ```sz```: scale factor in the Z-axis ```rotate(v)```
    ```scale(s)``` Syntactic sugar for ```rotate(rz,Z) * rotate(ry,Y) * rotate(rx,X)``` and ```rotate(v.z,Z) * rotate(v.y,Y) * rotate(v.x,X)``` respectively.
    ```scale(v)``` ```scale(sx, sy, sz)```
    Returns a transformation matrix that scales a shape by ```sx,sy,sz``` factors in the X-axis, Y-axis and Z-axis respectively.
    Syntactic sugar for ```scale(s,s,s)``` and ```scale(v.x,v.y,v.z)``` respectively. * ```sx```: scale factor in the X-axis
    * ```sy```: scale factor in the Y-axis
    The above transformations have alternative names (mainly for compatibility purposes). The next table summarizes them: * ```sz```: scale factor in the Z-axis
    | Transformation | Alternative | ```scale(s)```
    | -------------- | ----------- |
    | translate | translation | ```scale(v)```
    | rotate | rotation |
    | scale | scaling | Syntactic sugar for ```scale(s,s,s)``` and ```scale(v.x,v.y,v.z)``` respectively.
    ```mirror(normal)``` The above transformations have alternative names (mainly for compatibility purposes). The next table summarizes them:
    Returns a transformation matrix that mirrors a shape along the vector ```normal```. | Transformation | Alternative |
    * ```normal```: vector specifying the direction to mirror | -------------- | ----------- |
    | translate | translation |
    <table> | rotate | rotation |
    <tr> | scale | scaling |
    <td>
    ```mirror(normal)```
    ```lua
    mesh = load_centered('fox.stl') Returns a transformation matrix that mirrors a shape along the vector ```normal```.
    emit( mesh ) * ```normal```: vector specifying the direction to mirror
    emit( translate(0,-100,0) * mirror(v(0,1,0)) * mesh )
    <table>
    ``` <tr>
    <td>
    </td>
    <td> ```lua
    <img src="uploads/011d458a111f9a042915c0437acc3de4/Example_mirror.png" width="200"> mesh = load_centered('fox.stl')
    </td> emit( mesh )
    </tr> emit( translate(0,-100,0) * mirror(v(0,1,0)) * mesh )
    </table>
    ```
    ```frame(v)```
    </td>
    Returns a transformation matrix that orients (i.e. aligns) a shape's [up vector](http://autodeskmaya.wikia.com/wiki/Up_Vector) to the direction ```v```. <td>
    * ```v```: a vector specifying the direction to orientate in the transformation. <img src="uploads/011d458a111f9a042915c0437acc3de4/Example_mirror.png" width="200">
    </td>
    ### Magnets <a name="magnets"></a> </tr>
    </table>
    Magnets are volumeless shapes that help building objects by way of assembling parts. Think of a magnet as a fastener that eventually couples with other magnets from different shapes.
    ```frame(v)```
    ```magnet('name')```
    Returns a transformation matrix that orients (i.e. aligns) a shape's [up vector](http://autodeskmaya.wikia.com/wiki/Up_Vector) to the direction ```v```.
    * ```name```: magnet name * ```v```: a vector specifying the direction to orientate in the transformation.
    <table> ### Magnets <a name="magnets"></a>
    <tr>
    <td> Magnets are volumeless shapes that help building objects by way of assembling parts. Think of a magnet as a fastener that eventually couples with other magnets from different shapes.
    ```lua ```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') ) * ```name```: magnet name
    emit(case)
    emit(translate(-20,0,0) * head) <table>
    ``` <tr>
    <td>
    </td>
    <td> ```lua
    <img src="uploads/afaab141ada4970939e6adc2f10d215f/Example_magnet.png" width="200"> case = union( cylinder(5,10), translate(0,0,10) * magnet('m1') )
    </td> head = union( cone(5,1,10), translate(0,0,0) * rotate(180,X) * magnet('m2') )
    </tr> emit(case)
    </table> 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.
    </td>
    ```snap(shape0, magnet0, shape1, magnet1)``` <td>
    <img src="uploads/afaab141ada4970939e6adc2f10d215f/Example_magnet.png" width="200">
    * ```shape0```: base shape </td>
    * ```magnet0```: the base shape's magnet name </tr>
    * ```shape1```: shape to be coupled </table>
    * ```magnet1```: coupling shape's magnet name
    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.
    <table>
    <tr> ```snap(shape0, magnet0, shape1, magnet1)```
    <td>
    * ```shape0```: base shape
    ```lua * ```magnet0```: the base shape's magnet name
    smatrix = snap(case, 'm1', head, 'm2') * ```shape1```: shape to be coupled
    emit(union(smatrix * head, case)) * ```magnet1```: coupling shape's magnet name
    ```
    <table>
    </td> <tr>
    <td> <td>
    <img src="uploads/b55ddd1afdae5a1945bd3e26e7ca872e/Example_snap.png" width="200">
    </td> ```lua
    </tr> smatrix = snap(case, 'm1', head, 'm2')
    </table> emit(union(smatrix * head, case))
    ```
    Snap matrices are not commutative with respect to their connecting magnets. Notice in the previous example that multiplying ```smatrix``` with ```case``` does not yield the same result.
    </td>
    ## Operations <a name="operations"></a> <td>
    <img src="uploads/b55ddd1afdae5a1945bd3e26e7ca872e/Example_snap.png" width="200">
    IceSL supports [Constructive Solid Geometry](https://en.wikipedia.org/wiki/Constructive_solid_geometry) (hereafter referred to as CSG). The following is a list of CSG operations: </td>
    </tr>
    ### CSG Operations <a name="csg"></a> </table>
    ```union(s0,s1)``` Snap matrices are not commutative with respect to their connecting magnets. Notice in the previous example that multiplying ```smatrix``` with ```case``` does not yield the same result.
    Returns a shape as the union of shape ```s0``` and shape ```s1```. This operation is commutative. ## Operations <a name="operations"></a>
    * ```s0```: A shape
    * ```s1```: A shape IceSL supports [Constructive Solid Geometry](https://en.wikipedia.org/wiki/Constructive_solid_geometry) (hereafter referred to as CSG). The following is a list of CSG operations:
    ```intersection(s0,s1)``` ### CSG Operations <a name="csg"></a>
    Returns a shape as the intersection of shape ```s0``` and shape ```s1```. This operation is commutative. ```union(s0,s1)```
    * ```s0```: A shape
    * ```s1```: A shape Returns a shape as the union of shape ```s0``` and shape ```s1```. This operation is commutative.
    * ```s0```: A shape
    ```difference(s0,s1)``` * ```s1```: A shape
    Returns a shape as the difference of shape ```s0``` and shape ```s1```. This operation is **not** commutative. ```intersection(s0,s1)```
    * ```s0```: A shape
    * ```s1```: A shape Returns a shape as the intersection of shape ```s0``` and shape ```s1```. This operation is commutative.
    * ```s0```: A shape
    IceSL supports abbreviated multi-input versions of these operations. Assume ```s``` is a shape and ```S``` is a table of shapes. The following table summarizes these operations. * ```s1```: A shape
    | Operation | N-Argument Version | Short Version | ```difference(s0,s1)```
    | --------- | ------------------ | ------------- |
    | ```union(s0,s1)``` | ```union{s0,...,sn}, union(S)``` | ```U(s0,s1), U{s0,...,sn}, U(S)``` | Returns a shape as the difference of shape ```s0``` and shape ```s1```. This operation is **not** commutative.
    | ```intersection(s0,s1)``` | ```intersection{s0,...,sn}, intersection(S)``` | ```I(s0,s1), I{s0,...,sn}, I(S)``` | * ```s0```: A shape
    | ```difference(s0,s1)``` | ```difference{s0,...,sn}, difference(S)``` | ```D(s0,s1), D{s0,...,sn}, D(S)``` | * ```s1```: A shape
    N-ary versions from the above table are associative to the left. For example ```D{s0,s1,s2,s3}``` is equivalent to ```D(D(D(s0,s1),s2),s3)```. For this to be computationally sound [1](https://proofwiki.org/wiki/Union_of_Singleton) [2](https://proofwiki.org/wiki/Intersection_of_Singleton), the result of n-ary operations over a single shape is defined as the shape itself (i.e. ```U{s} = s```, ```I{s} = s``` and ```D{s} = s```). IceSL supports abbreviated multi-input versions of these operations. Assume ```s``` is a shape and ```S``` is a table of shapes. The following table summarizes these operations.
    ### Other Operations <a name="otherops"></a> | Operation | N-Argument Version | Short Version |
    | --------- | ------------------ | ------------- |
    ```flip(m)``` | ```union(s0,s1)``` | ```union{s0,...,sn}, union(S)``` | ```U(s0,s1), U{s0,...,sn}, U(S)``` |
    | ```intersection(s0,s1)``` | ```intersection{s0,...,sn}, intersection(S)``` | ```I(s0,s1), I{s0,...,sn}, I(S)``` |
    Inverts the orientation of the faces from the mesh ```m```. This is specially useful when loading a mesh that has its faces defined clockwise. | ```difference(s0,s1)``` | ```difference{s0,...,sn}, difference(S)``` | ```D(s0,s1), D{s0,...,sn}, D(S)``` |
    * ```m```: input mesh
    N-ary versions from the above table are associative to the left. For example ```D{s0,s1,s2,s3}``` is equivalent to ```D(D(D(s0,s1),s2),s3)```. For this to be computationally sound [1](https://proofwiki.org/wiki/Union_of_Singleton) [2](https://proofwiki.org/wiki/Intersection_of_Singleton), the result of n-ary operations over a single shape is defined as the shape itself (i.e. ```U{s} = s```, ```I{s} = s``` and ```D{s} = s```).
    ```convex_hull(shape)```
    ### Other Operations <a name="otherops"></a>
    Creates the [convex hull](https://en.wikipedia.org/wiki/Convex_hull) of ```shape```. It only works with meshes or union of meshes.
    * ```shape```: input primitive ```flip(m)```
    <table> Inverts the orientation of the faces from the mesh ```m```. This is specially useful when loading a mesh that has its faces defined clockwise.
    <tr> * ```m```: input mesh
    <td>
    ```convex_hull(shape)```
    ```lua
    mesh = load('crystal.stl') Creates the [convex hull](https://en.wikipedia.org/wiki/Convex_hull) of ```shape```. It only works with meshes or union of meshes.
    emit( translate(100,0,0) * mesh ) * ```shape```: input primitive
    emit( convex_hull(mesh) )
    ``` <table>
    <tr>
    </td> <td>
    <td>
    <img src="uploads/276b9ba6c7a260bde586b69e53463ae5/Example_convex_hull.png" width="200"> ```lua
    </td> mesh = load('crystal.stl')
    </tr> emit( translate(100,0,0) * mesh )
    </table> emit( convex_hull(mesh) )
    ```
    ```dilate(mesh, factor)```
    </td>
    ```erode(mesh, factor)``` <td>
    <img src="uploads/276b9ba6c7a260bde586b69e53463ae5/Example_convex_hull.png" width="200">
    [Dilates]( https://en.wikipedia.org/wiki/Dilation_(morphology) ) and [erodes]( https://en.wikipedia.org/wiki/Erosion_(morphology) ) a mesh respectively by ```factor```. The vertices in ```mesh``` need to be merged a priori (use ```merge_vertices```). </td>
    * ```mesh```: input mesh </tr>
    * ```factor```: dilation/erosion factor </table>
    <table> ```dilate(mesh, factor)```
    <tr>
    <td> ```erode(mesh, factor)```
    ```lua [Dilates]( https://en.wikipedia.org/wiki/Dilation_(morphology) ) and [erodes]( https://en.wikipedia.org/wiki/Erosion_(morphology) ) a mesh respectively by ```factor```. The vertices in ```mesh``` need to be merged a priori (use ```merge_vertices```).
    mesh = scale(0.1) * merge_vertices(load_centered('fox.stl')) * ```mesh```: input mesh
    emit(translate(0,0,-6) * erode(mesh,0.3)) * ```factor```: dilation/erosion factor
    emit(translate(15,0,0) * dilate(mesh,0.5))
    ``` <table>
    <tr>
    </td> <td>
    <td>
    <img src="uploads/bc4617409a7b056afd49689462c5706b/Example_dilate_erode.png" width="200"> ```lua
    </td> mesh = scale(0.1) * merge_vertices(load_centered('fox.stl'))
    </tr> emit(translate(0,0,-6) * erode(mesh,0.3))
    </table> emit(translate(15,0,0) * dilate(mesh,0.5))
    ```
    ```linear_offset(mesh,direction,offset)```
    </td>
    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 exist (e.g. _stl_ meshes). <td>
    * ```mesh```: input mesh <img src="uploads/bc4617409a7b056afd49689462c5706b/Example_dilate_erode.png" width="200">
    * ```direction```: offset direction </td>
    * ```offset```: offset factor </tr>
    </table>
    <table>
    <tr> ```linear_offset(mesh,direction,offset)```
    <td>
    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 exist (e.g. _stl_ meshes).
    ```lua * ```mesh```: input mesh
    mesh = merge_vertices(load('fox.stl')) * ```direction```: offset direction
    emit( mesh ) * ```offset```: offset factor
    emit( translate(100,0,0) * linear_offset(mesh,v(0,1,0),10) )
    ``` <table>
    <tr>
    </td> <td>
    <td>
    <img src="uploads/f6b8a5fb516b643473159df5acd0c3ce/Example_linear_offset.png" width="200"> ```lua
    </td> mesh = merge_vertices(load('fox.stl'))
    </tr> emit( mesh )
    </table> emit( translate(100,0,0) * linear_offset(mesh,v(0,1,0),10) )
    ```
    ```linear_offsets(mesh,directions,offsets)```
    </td>
    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 correspondence. <td>
    <img src="uploads/f6b8a5fb516b643473159df5acd0c3ce/Example_linear_offset.png" width="200">
    ## Shape Representation <a name="shaperep"></a> </td>
    </tr>
    IceSL offers several functions for calculating representations of shapes (i.e., meshes, voxels, etc). </table>
    ```to_voxel_solid(shape, voxSize)``` ```linear_offsets(mesh,directions,offsets)```
    ```to_voxel_solid(tex3d, voxSize)``` 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 correspondence.
    Creates a solid voxel volume from ```shape``` or ```tex3d``` where each voxel measures ```voxSize``` units. ## Shape Representation <a name="shaperep"></a>
    * ```shape```: input shape
    * ```tex3d```: 3D texture IceSL offers several functions for calculating representations of shapes (i.e., meshes, voxels, etc).
    * ```voxSize```: voxel size (in mm)
    ```to_voxel_solid(shape, voxSize)```
    ```to_voxel_solid(tex3d, boxMin, boxMax)```
    ```to_voxel_solid(tex3d, voxSize)```
    Creates a solid voxel volume from ```tex3d```. ```boxMin``` and ```boxMax``` specify the volume in space to create the solid. Values in ```tex3d``` below```0.5``` are considered solid, otherwise they are considered empty.
    Creates a solid voxel volume from ```shape``` or ```tex3d``` where each voxel measures ```voxSize``` units.
    ```to_voxel_distance_field(shape, voxSize)``` * ```shape```: input shape
    * ```tex3d```: 3D texture
    Creates a voxel distance field from ```shape``` using [this technique](http://www.comp.nus.edu.sg/~tants/jfa/i3d06.pdf). Each voxel measures ```voxSize``` units. * ```voxSize```: voxel size (in mm)
    * ```shape```: input shape ```to_voxel_solid(tex3d, boxMin, boxMax)```
    * ```voxSize```: voxel size (in mm)
    Creates a solid voxel volume from ```tex3d```. ```boxMin``` and ```boxMax``` specify the volume in space to create the solid. Values in ```tex3d``` below```0.5``` are considered solid, otherwise they are considered empty.
    ```set_distance_field_iso(voxels, threshold)```
    ```to_voxel_distance_field(shape, voxSize)```
    In a distance field, sets the threshold to classify voxels as empty/solid whenever it is less/greater than ```threshold``` respectively.
    Creates a voxel distance field from ```shape``` using [this technique](http://www.comp.nus.edu.sg/~tants/jfa/i3d06.pdf). Each voxel measures ```voxSize``` units.
    * ```voxels```: voxel shape obtained by ```to_voxel_distance_field```
    * ```threshold```: Number between ```0``` (empty) and ```1```(solid). Default is ```0.5``` * ```shape```: input shape
    * ```voxSize```: voxel size (in mm)
    ```smooth_voxels(voxShape, windowSize)```
    ```set_distance_field_iso(voxels, threshold)```
    Smooths the voxel shape ```voxShape``` using a [trilinear interpolation](https://en.wikipedia.org/wiki/Trilinear_interpolation) with a windows size of ```windowSize```. This functions _does not_ return a shape, instead it modifies the shape specified on the first parameter.
    In a distance field, sets the threshold to classify voxels as empty/solid whenever it is less/greater than ```threshold``` respectively.
    * ```voxShape```: input shape. Only supports voxels
    * ```windowSize```: interpolation 3D window size * ```voxels```: voxel shape obtained by ```to_voxel_distance_field```
    * ```threshold```: Number between ```0``` (empty) and ```1```(solid). Default is ```0.5```
    ```smooth_voxels_preserve_volume(voxShape, windowSize)```
    ```smooth_voxels(voxShape, windowSize)```
    Same as above but tries to preserve the shape's volume.
    Smooths the voxel shape ```voxShape``` using a [trilinear interpolation](https://en.wikipedia.org/wiki/Trilinear_interpolation) with a windows size of ```windowSize```. This functions _does not_ return a shape, instead it modifies the shape specified on the first parameter.
    <table>
    <tr> * ```voxShape```: input shape. Only supports voxels
    <td> * ```windowSize```: interpolation 3D window size
    ```lua ```smooth_voxels_preserve_volume(voxShape, windowSize)```
    s = sphere(5)
    vs1 = to_voxel_solid(s, 0.1) Same as above but tries to preserve the shape's volume.
    vs2 = to_voxel_solid(s, 0.1)
    smooth_voxels(vs2,10) <table>
    emit(translate(0,0,0) * s) <tr>
    emit(translate(15,0,0) * vs1) <td>
    emit(translate(30,0,0) * vs2)
    ``` ```lua
    s = sphere(5)
    </td> vs1 = to_voxel_solid(s, 0.1)
    <td> vs2 = to_voxel_solid(s, 0.1)
    <img src="uploads/69b6b0930ded09a9c539f14033397535/Example_voxels.png" width="200"> smooth_voxels(vs2,10)
    </td> emit(translate(0,0,0) * s)
    </tr> emit(translate(15,0,0) * vs1)
    </table> emit(translate(30,0,0) * vs2)
    ```
    ```to_mesh(shape, voxSize)```
    </td>
    ```to_mesh_dual(shape, voxSize)``` <td>
    <img src="uploads/69b6b0930ded09a9c539f14033397535/Example_voxels.png" width="200">
    Creates a mesh from ```shape``` using the marching cubes or dual contouring algorithms respectively. Before calculating the resulting mesh, the 3D space containing the shape is discretized using voxels of size ```voxSize``` units. </td>
    </tr>
    * ```shape```: input shape </table>
    * ```voxSize```: voxel size of space discretization (in mm)
    ```to_mesh(shape, voxSize)```
    ### From assets <a name="assets"></a>
    ```to_mesh_dual(shape, voxSize)```
    ```image_contouring(file,pixel_size)```
    Creates a mesh from ```shape``` using the marching cubes or dual contouring algorithms respectively. Before calculating the resulting mesh, the 3D space containing the shape is discretized using voxels of size ```voxSize``` units.
    Extracts contours out of an image file. Pixels colored black are considered _hollow_, while any other color is considered _solid_. Returns a table of ```IMGContour``` objects.
    * ```file```: input image file (PNG and TGA supported) * ```shape```: input shape
    * ```pixel_size```: size in mm, of a pixel * ```voxSize```: voxel size of space discretization (in mm)
    The ```IMGContour``` object has the following members: ### From assets <a name="assets"></a>
    * ```outline```: The contour _(table)_
    <table> ```image_contouring(file,pixel_size)```
    <tr>
    <td> Extracts contours out of an image file. Pixels colored black are considered _hollow_, while any other color is considered _solid_. Returns a table of ```IMGContour``` objects.
    * ```file```: input image file (PNG and TGA supported)
    ```lua * ```pixel_size```: size in mm, of a pixel
    contours = image_contouring('shapes.png', 0.1)
    for _,contour in pairs(contours) do The ```IMGContour``` object has the following members:
    emit(linear_extrude_from_oriented(v(0,0,1), contour:outline())) * ```outline```: The contour _(table)_
    end <table>
    ``` <tr>
    <td>
    </td>
    <td> ```lua
    <img src="uploads/b5334a3f9d84f701e3727957ce6be7b7/Example_image_contouring.jpg" width="200"> contours = image_contouring('shapes.png', 0.1)
    </td> for _,contour in pairs(contours) do
    <td> emit(linear_extrude_from_oriented(v(0,0,1), contour:outline()))
    <img src="uploads/82d378c0e4efb193bb5ea676e305b6b2/shapes.png" width="200"> end
    </td> ```
    </tr>
    </table> </td>
    <td>
    ```svg_contouring(file,dpi)``` <img src="uploads/b5334a3f9d84f701e3727957ce6be7b7/Example_image_contouring.jpg" width="200">
    </td>
    Extracts contours out of a SVG file. Returns a table of ```SVGContour``` objects. <td>
    * ```file```: input svg file <img src="uploads/82d378c0e4efb193bb5ea676e305b6b2/shapes.png" width="200">
    * ```dpi```: dots per inch. Use 90 for Inkscape files </td>
    </tr>
    The ```SVGContour``` object has the following members: </table>
    * ```outline```: The contour _(table)_
    * ```fill ```: fill color for the contour _(triplet)_ ```svg_contouring(file,dpi)```
    * ```stroke```: stroke color for the contour _(triplet)_
    * ```strokeWidth```: stroke width for the contour _(num)_ Extracts contours out of a SVG file. Returns a table of ```SVGContour``` objects.
    * ```hasFill```: contour is color-filled _(bool)_ * ```file```: input svg file
    * ```hasStroke```: contour is color-bordered _(bool)_ * ```dpi```: dots per inch. Use 90 for Inkscape files
    <table> The ```SVGContour``` object has the following members:
    <tr> * ```outline```: The contour _(table)_
    <td> * ```fill ```: fill color for the contour _(triplet)_
    * ```stroke```: stroke color for the contour _(triplet)_
    ```lua * ```strokeWidth```: stroke width for the contour _(num)_
    svg_shapes = svg_contouring('restroom.svg',90) * ```hasFill```: contour is color-filled _(bool)_
    for i,contour in pairs(svg_shapes) do * ```hasStroke```: contour is color-bordered _(bool)_
    if contour:hasFill() then
    set_brush_color(i, contour:fill()[1], contour:fill()[2], contour:fill()[3]) <table>
    end <tr>
    emit(linear_extrude_from_oriented(v(0,0,5),contour:outline()), i) <td>
    end
    ``` ```lua
    svg_shapes = svg_contouring('restroom.svg',90)
    </td> for i,contour in pairs(svg_shapes) do
    <td> if contour:hasFill() then
    <img src="uploads/434f1733f99e33e71f3666761209ade6/Example_svg_ex.png" width="200"> set_brush_color(i, contour:fill()[1], contour:fill()[2], contour:fill()[3])
    </td> end
    </tr> emit(linear_extrude_from_oriented(v(0,0,5),contour:outline()), i)
    </table> end
    ```
    ```font()```
    </td>
    ```font(ttf)``` <td>
    <img src="uploads/434f1733f99e33e71f3666761209ade6/Example_svg_ex.png" width="200">
    Creates a font object based either using the default font provided by IceSL or the font described in the TrueType Font file ```ttf```. </td>
    * ```ttf```: TrueType Font file </tr>
    </table>
    The interface to the font object is the following:
    * ```str(string, tracking)``` : Returns a 3D geometry of the string ```string```. If present, the font's [kerning](https://en.wikipedia.org/wiki/Kerning) information is added to ```tracking``` [tracking](https://en.wikipedia.org/wiki/Letter-spacing). ```font()```
    <table> ```font(ttf)```
    <tr>
    <td> Creates a font object based either using the default font provided by IceSL or the font described in the TrueType Font file ```ttf```.
    * ```ttf```: TrueType Font file
    ```lua
    f = font(Path .. 'LiberationMono-Regular.ttf') The interface to the font object is the following:
    text = f:str('IceSL', 10) * ```str(string, tracking)``` : Returns a 3D geometry of the string ```string```. If present, the font's [kerning](https://en.wikipedia.org/wiki/Kerning) information is added to ```tracking``` [tracking](https://en.wikipedia.org/wiki/Letter-spacing).
    emit(scale(0.5,0.5,10) * text)
    ``` <table>
    <tr>
    </td> <td>
    <td>
    <img src="uploads/4b1fa3e9b2e4de82b33e286f1a2aaa4d/Example_font.jpg" width="200"> ```lua
    </td> f = font(Path .. 'LiberationMono-Regular.ttf')
    </tr> text = f:str('IceSL', 10)
    </table> emit(scale(0.5,0.5,10) * text)
    ```
    ```load_raw_voxels(fileName, thicken)```
    </td>
    Creates a shape out of raw voxel data in ```fileName```. ```thicken``` stands for the thickening applied to the voxels. <td>
    * ```fileName```: input file <img src="uploads/4b1fa3e9b2e4de82b33e286f1a2aaa4d/Example_font.jpg" width="200">
    * ```thicken```: thickening of voxels </td>
    The format of the file is a continuous chunk of voxels with the following information in sequence: </tr>
    1. Position (3 ints) </table>
    2. Normal (3 floats)
    3. Color (3 unsigned chars) ```load_raw_voxels(fileName, thicken)```
    4. State (1 bool)
    Creates a shape out of raw voxel data in ```fileName```. ```thicken``` stands for the thickening applied to the voxels.
    ### Distribute <a name="distribute"></a> * ```fileName```: input file
    * ```thicken```: thickening of voxels
    Additionally to changing the representations of a shape, IceSL also provides a function to calculate an evenly distributed set of points covering a surface. For each point this function also reports its surface normal and maximum distance to the set of nearest points. The format of the file is a continuous chunk of voxels with the following information in sequence:
    1. Position (3 ints)
    ```distribute(shape, density)``` 2. Normal (3 floats)
    3. Color (3 unsigned chars)
    Returns a Lua array describing the surface of ```shape``` using [Voronoid Iteration](https://en.wikipedia.org/wiki/Lloyd%27s_algorithm). 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```. 4. State (1 bool)
    * ```shape```: input shape ### Distribute <a name="distribute"></a>
    * ```density```: position density. This argument is clamped to the unit interval where ```1``` signifies high density and ```0``` no density
    Additionally to changing the representations of a shape, IceSL also provides a function to calculate an evenly distributed set of points covering a surface. For each point this function also reports its surface normal and maximum distance to the set of nearest points.
    <table>
    <tr> ```distribute(shape, density)```
    <td>
    Returns a Lua array describing the surface of ```shape``` using [Voronoid Iteration](https://en.wikipedia.org/wiki/Lloyd%27s_algorithm). 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```.
    ```lua
    shape = cube(10) * ```shape```: input shape
    s = distribute(shape, 0.2) * ```density```: position density. This argument is clamped to the unit interval where ```1``` signifies high density and ```0``` no density
    centroids = {}
    for i = 1,#s,1 do <table>
    centroids[i] = translate(s[i][1]) * frame(s[i][2]) * <tr>
    union{ cone(s[i][3],0,1), mirror(Z) * cone(s[i][3],0,1) } <td>
    end
    emit(union(centroids)) ```lua
    shape = cube(10)
    ``` s = distribute(shape, 0.2)
    centroids = {}
    </td> for i = 1,#s,1 do
    <td> centroids[i] = translate(s[i][1]) * frame(s[i][2]) *
    <img src="uploads/d1b3017bdeac39f7162c26f9ea279795/Example_distribute.png" width="200"> union{ cone(s[i][3],0,1), mirror(Z) * cone(s[i][3],0,1) }
    </td> end
    </tr> emit(union(centroids))
    </table>
    ```
    ## Other Functionality <a name="otherfunc"></a>
    ### Printing settings <a name="settings"></a> </td>
    <td>
    Scripts also have the ability to change printing settings directly from within them. This allows the user (among other reasons) to specify printing settings tailored to the geometry being described in the script. <img src="uploads/d1b3017bdeac39f7162c26f9ea279795/Example_distribute.png" width="200">
    </td>
    IceSL gives priority to an assignment of a printing setting according to the following list: </tr>
    1. Default IceSL values -- _bottom priority_ </table>
    2. Printer features (i.e., ```features.lua``` in printer profiles)
    3. Print profile (e.g., fast print, high quality, etc.) ## Other Functionality <a name="otherfunc"></a>
    4. Material profile (e.g., abs, pla, etc.) ### Printing settings <a name="settings"></a>
    5. Lua script
    6. User interface -- _top priority_ Scripts also have the ability to change printing settings directly from within them. This allows the user (among other reasons) to specify printing settings tailored to the geometry being described in the script.
    For example, if the value of a setting is specified in a printer profile as well as in the lua script, the latter takes priority. Moreover, if the user sets it manually using the UI then this overrides all other assignments. IceSL gives priority to an assignment of a printing setting according to the following list:
    1. Default IceSL values -- _bottom priority_
    ```set_setting_value(setting, value)``` 2. Printer features (i.e., ```features.lua``` in printer profiles)
    3. Print profile (e.g., fast print, high quality, etc.)
    ```set_setting_value(setting, value, bed_relative)``` 4. Material profile (e.g., abs, pla, etc.)
    5. Lua script
    Sets the printing parameter ```settings``` to ```value``` 6. User interface -- _top priority_
    * ```setting```: Internal name of the printing setting to change
    * ```value```: Value to assign. May be a boolean, a number, a string or a table. The latter is reserved to _per-layer_ assignments whereas the table is to be constructed as follows: For example, if the value of a setting is specified in a printer profile as well as in the lua script, the latter takes priority. Moreover, if the user sets it manually using the UI then this overrides all other assignments.
    * ```{ [key_0]=value_0, ... , [key_n]=value_n }```
    * where ```key_i``` specifies a height and ```value_i``` is a the parameter's value at such height. ```set_setting_value(setting, value)```
    * ```bed_relative```: If per-layer assignment, indicate whether the height is relative to the bed position (i.e., 0 means at bed level) or modeling position (i.e., 0 means at the center of geometry, see for example ```cube``` vs. ```ccube```). This parameter is _false_ by default.
    * **NOTE**: Be aware that, at the point in the script where ```set_setting_value``` is being executed, the totality of the geometry is still unknown. The script hasn't finished executing and there might be more ```emit``` commands ahead. So when the parameter ```bed_relative``` is used, the bed position is still undecided, thus it is recommended to reload the script when this parameter is changing value to allow IceSL to recalculate the bed's final position. ```set_setting_value(setting, value, bed_relative)```
    <table> Sets the printing parameter ```settings``` to ```value```
    <tr> * ```setting```: Internal name of the printing setting to change
    <td> * ```value```: Value to assign. May be a boolean, a number, a string or a table. The latter is reserved to _per-layer_ assignments whereas the table is to be constructed as follows:
    * ```{ [key_0]=value_0, ... , [key_n]=value_n }```
    ```lua * where ```key_i``` specifies a height and ```value_i``` is a the parameter's value at such height.
    emit(cube(10)) * ```bed_relative```: If per-layer assignment, indicate whether the height is relative to the bed position (i.e., 0 means at bed level) or modeling position (i.e., 0 means at the center of geometry, see for example ```cube``` vs. ```ccube```). This parameter is _false_ by default.
    set_setting_value('z_layer_height_mm', { [0.0]=0.2, [5]=0.3 }) * **NOTE**: Be aware that, at the point in the script where ```set_setting_value``` is being executed, the totality of the geometry is still unknown. The script hasn't finished executing and there might be more ```emit``` commands ahead. So when the parameter ```bed_relative``` is used, the bed position is still undecided, thus it is recommended to reload the script when this parameter is changing value to allow IceSL to recalculate the bed's final position.
    ```
    <table>
    </td> <tr>
    </tr> <td>
    </table>
    ```lua
    ```set_setting_value(setting, tex3d, boxMin, boxMax)``` emit(cube(10))
    set_setting_value('z_layer_height_mm', { [0.0]=0.2, [5]=0.3 })
    Sets the printing parameter ```setting``` as a _field_ that extends from ```boxMin``` to ```boxMax``` with values from ```tex3d```. Recall that individual values in textures are in the $`[0-1]`$ range, thus they are interpreted according to the setting's minimum and maximum values (e.g, 0.0 could mean no infill or zero degrees, and 1.0 could mean fully infilled or 360 degrees respectively). ```
    * ```setting```: Internal name of the printing setting to change
    * ```tex3d```: Value of the field as a 3d texture. </td>
    * ```boxMin,boxMax```: Field extent </tr>
    </table>
    <table>
    <tr> ```set_setting_value(setting, tex3d, boxMin, boxMax)```
    <td>
    Sets the printing parameter ```setting``` as a _field_ that extends from ```boxMin``` to ```boxMax``` with values from ```tex3d```. Recall that individual values in textures are in the $`[0-1]`$ range, thus they are interpreted according to the setting's minimum and maximum values (e.g, 0.0 could mean no infill or zero degrees, and 1.0 could mean fully infilled or 360 degrees respectively).
    ```lua * ```setting```: Internal name of the printing setting to change
    height = 50 * ```tex3d```: Value of the field as a 3d texture
    radius = 10 * ```boxMin,boxMax```: Field extent
    obj = cylinder(radius, height)
    emit(obj) <table>
    <tr>
    size_tex3d = 64 <td>
    size_tex3d_half = size_tex3d / 2
    density = tex3d_r8f(size_tex3d, size_tex3d, size_tex3d) ```lua
    height = 50
    for i = 0,size_tex3d - 1 do radius = 10
    for j = 0,size_tex3d - 1 do obj = cylinder(radius, height)
    for k = 0, size_tex3d - 1 do emit(obj)
    r = math.sqrt((i - size_tex3d_half) ^ 2 + (j - size_tex3d_half) ^ 2)
    d = r / size_tex3d_half -- from 0 to 100 inside out size_tex3d = 64
    density:set(i,j,k, v(d,0.0,0.0)) -- y and x values are ignored size_tex3d_half = size_tex3d / 2
    end density = tex3d_r8f(size_tex3d, size_tex3d, size_tex3d)
    end
    end for i = 0,size_tex3d - 1 do
    for j = 0,size_tex3d - 1 do
    box = bbox(obj) for k = 0, size_tex3d - 1 do
    set_setting_value('infill_percentage_0', density, box:min_corner(), box:max_corner()) r = math.sqrt((i - size_tex3d_half) ^ 2 + (j - size_tex3d_half) ^ 2)
    ``` d = r / size_tex3d_half -- from 0 to 100 inside out
    density:set(i,j,k, v(d,0.0,0.0)) -- y and x values are ignored
    </td> end
    </tr> end
    <tr> end
    <td>
    <img src="uploads/e6ff8f490ff96a7f1ac271f12835ae46/image.png" width="200"> box = bbox(obj)
    </td> set_setting_value('infill_percentage_0', density, box:min_corner(), box:max_corner())
    </tr> ```
    </table>
    </td>
    ### Variable caching <a name="caching"></a> </tr>
    <tr>
    It is possible to turn on/off variable caching in IceSL with the system variable ```enable_variable_cache```. Variable caching is useful when editing a script that constructs an object or preforms a calculation that is CPU intensive (i.e. consumes significant time). <td>
    <img src="uploads/e6ff8f490ff96a7f1ac271f12835ae46/image.png" width="200">
    In the following example it is possible to change the scaling of ```mesh``` without incurring in the penalty of re-calculating the result of ```to_mesh```: </td>
    </tr>
    <table> </table>
    <tr>
    <td> ### Distance field <a name="distfield"></a>
    ```lua ```texture3d_distance_field(shape)```
    enable_variable_cache = true
    s = sphere(10) Calculates a distance field based on the geometry of ```shape``` as a 3D texture where its coordinates correspond to positions in the bounding box volume of ```shape```. Each value of the computed distance field (i.e., the 3D texture) is in the range $`[0-1]`$ where `1` means the position is on the surface of ```shape``` or beyond (i.e., hollow). Positions inside ```shape``` (i.e., solid) decrease from `1` to `0` as the distance to the surface increases.
    if not mesh then * ```shape```: Shape to calculate the distance field
    mesh = to_mesh(s,1)
    end ### Variable caching <a name="caching"></a>
    emit(scale(1) * mesh)
    ``` It is possible to turn on/off variable caching in IceSL with the system variable ```enable_variable_cache```. Variable caching is useful when editing a script that constructs an object or preforms a calculation that is CPU intensive (i.e. consumes significant time).
    </td> In the following example it is possible to change the scaling of ```mesh``` without incurring in the penalty of re-calculating the result of ```to_mesh```:
    </tr>
    </table> <table>
    <tr>
    ### Tweaks <a name="tweaks"></a> <td>
    ```ui_scalar(name, default, min, max)``` ```lua
    enable_variable_cache = true
    Creates a sliding bar to interactively set a float value between ```min``` and ```max```. s = sphere(10)
    * ```name```: the tweak's name if not mesh then
    * ```default```: default value mesh = to_mesh(s,1)
    * ```min```: minimum value end
    * ```max```: maximum value emit(scale(1) * mesh)
    ```
    <table>
    <tr> </td>
    <td> </tr>
    </table>
    ```lua
    r = ui_scalar("Radius",10.0,1.0,20.0) ### Tweaks <a name="tweaks"></a>
    emit(sphere(r))
    ``` ```ui_scalar(name, default, min, max)```
    </td> Creates a sliding bar to interactively set a float value between ```min``` and ```max```.
    <td> * ```name```: the tweak's name
    <img src="uploads/e942eccb69903c2991560051674b463f/Example_tweaks.png" width="200"> * ```default```: default value
    </td> * ```min```: minimum value
    </tr> * ```max```: maximum value
    </table>
    <table>
    ```ui_scalarBox(name, default, step)``` <tr>
    <td>
    Creates a quantity (+/-) box stepped by ```step``` to interactively set a float value.
    * ```name```: the tweak's name ```lua
    * ```default```: default value r = ui_scalar("Radius",10.0,1.0,20.0)
    * ```step```: increment/decrement delta emit(sphere(r))
    ```
    ```ui_number(name, default, min, max)```
    </td>
    Creates a sliding bar to interactively set an integer value between ```min``` and ```max```. <td>
    * ```name```: the tweak's name <img src="uploads/e942eccb69903c2991560051674b463f/Example_tweaks.png" width="200">
    * ```default```: default value </td>
    * ```min```: minimum value </tr>
    * ```max```: maximum value </table>
    ```ui_numberBox(name, default)``` ```ui_scalarBox(name, default, step)```
    Creates a quantity (+/-) box to interactively set an integer value. Creates a quantity (+/-) box stepped by ```step``` to interactively set a float value.
    * ```name```: the tweak's name * ```name```: the tweak's name
    * ```default```: default value * ```default```: default value
    * ```step```: increment/decrement delta
    ```ui_bool(name, default)```
    ```ui_number(name, default, min, max)```
    Creates a checkbox to interactively set a Boolean value.
    * ```name```: the tweak's name Creates a sliding bar to interactively set an integer value between ```min``` and ```max```.
    * ```default```: default value * ```name```: the tweak's name
    * ```default```: default value
    ```ui_text(name, default)``` * ```min```: minimum value
    * ```max```: maximum value
    Creates a text input box to interactively set a string value.
    * ```name```: the tweak's name ```ui_numberBox(name, default)```
    * ```default```: default value
    Creates a quantity (+/-) box to interactively set an integer value.
    ```ui_radio(name, list)``` * ```name```: the tweak's name
    * ```default```: default value
    Creates a radio box to interactively choose an integer value from a list.
    * ```name```: the tweak's name ```ui_bool(name, default)```
    * ```list```: an array of pairs of the form ```{integer, string}``` where ```integer``` is the id associated with ```string```
    Creates a checkbox to interactively set a Boolean value.
    <table> * ```name```: the tweak's name
    <tr> * ```default```: default value
    <td>
    ```ui_text(name, default)```
    ```lua
    shape_list = { Creates a text input box to interactively set a string value.
    {0, "sphere"}, * ```name```: the tweak's name
    {1, "cylinder"}, * ```default```: default value
    {2, "cube"}
    } ```ui_radio(name, list)```
    shape = ui_radio("Shape:", shape_list)
    Creates a radio box to interactively choose an integer value from a list.
    if shape == 0 then emit(sphere(5)) * ```name```: the tweak's name
    elseif shape == 1 then emit(cylinder(5,10)) * ```list```: an array of pairs of the form ```{integer, string}``` where ```integer``` is the id associated with ```string```
    elseif shape == 2 then emit(cube(10)) end
    ``` <table>
    <tr>
    </td> <td>
    <td>
    <img src="uploads/0f6f18791297bc6e6c34cf7d2614f569/Example_tweakCombo.PNG" width="200"> ```lua
    </td> shape_list = {
    </tr> {0, "sphere"},
    </table> {1, "cylinder"},
    {2, "cube"}
    ```ui_combo(name, list)``` }
    shape = ui_radio("Shape:", shape_list)
    Creates a combo box to interactively choose a string value from a list.
    * ```name```: the tweak's name if shape == 0 then emit(sphere(5))
    * ```list```: an array of strings elseif shape == 1 then emit(cylinder(5,10))
    elseif shape == 2 then emit(cube(10)) end
    ```ui_selectFile(name)``` ```
    Creates a button to select an existing file. The return value is the file path </td>
    * ```name```: the tweak's name <td>
    <img src="uploads/0f6f18791297bc6e6c34cf7d2614f569/Example_tweakCombo.PNG" width="200">
    </td>
    ### Fields <a name="fields"></a> </tr>
    </table>
    Fields are UI objects for interactively building 3D textures. They are useful for carving, sculpting and specifying surfaces among other things.
    ```ui_combo(name, list)```
    ```ui_field(name, boxMin, boxMax)```
    Creates a combo box to interactively choose a string value from a list.
    Creates a labeled button to build a 3D texture in the box space specified by ```boxMin``` and ```boxMax```. * ```name```: the tweak's name
    * ```name```: field name * ```list```: an array of strings
    * ```boxMin```: left corner of the 3D texture
    * ```boxMax```: right corner of the 3D texture ```ui_selectFile(name)```
    ```ui_field_value_at(name, p)``` Creates a button to select an existing file. The return value is the file path
    * ```name```: the tweak's name
    Retrieves the value of the field ```name``` (created by ```ui_field```) at position ```p```.
    * ```name```: field name
    * ```p```: position to inquire ### Fields <a name="fields"></a>
    ```ui_file(fileName)``` Fields are UI objects for interactively building 3D textures. They are useful for carving, sculpting and specifying surfaces among other things.
    Creates a UI to load/save all the script's tweaks and field values from/into ```fileName```. ```ui_field(name, boxMin, boxMax)```
    * ```fileName```: file path to load/save tweaks and fields values Creates a labeled button to build a 3D texture in the box space specified by ```boxMin``` and ```boxMax```.
    * ```name```: field name
    The following example sculpts a sphere using a field named ```Sculpting``` and saves the field values into the file ```sculpt.xml``` * ```boxMin```: left corner of the 3D texture
    * ```boxMax```: right corner of the 3D texture
    <table>
    <tr> ```ui_field_value_at(name, p)```
    <td>
    Retrieves the value of the field ```name``` (created by ```ui_field```) at position ```p```.
    ```lua * ```name```: field name
    s = sphere(10) * ```p```: position to inquire
    bx = bbox(s)
    bx:enlarge(1) ```ui_file(fileName)```
    f = ui_field('Sculpting',bx:min_corner(),bx:max_corner())
    ui_file(Path..'sculpt.xml') Creates a UI to load/save all the script's tweaks and field values from/into ```fileName```.
    result = intersection(s,to_voxel_solid(f,bx:min_corner(),bx:max_corner()))
    emit(result) * ```fileName```: file path to load/save tweaks and fields values
    ```
    The following example sculpts a sphere using a field named ```Sculpting``` and saves the field values into the file ```sculpt.xml```
    </td>
    <td> <table>
    <img src="uploads/30f7f0ead3f449befc9d5fe67b5b0d96/Example_fields.png" width="200"> <tr>
    </td> <td>
    </tr>
    </table> ```lua
    s = sphere(10)
    In the next example, we use a field to avoid distributing (i.e. function ```distribute```) parts of the shape surface. bx = bbox(s)
    bx:enlarge(1)
    <table> f = ui_field('Sculpting',bx:min_corner(),bx:max_corner())
    <tr> ui_file(Path..'sculpt.xml')
    <td> result = intersection(s,to_voxel_solid(f,bx:min_corner(),bx:max_corner()))
    emit(result)
    ```lua ```
    enable_variable_cache = true
    shape = sphere(10) </td>
    if not s then <td>
    s = distribute(shape, 0.5) <img src="uploads/30f7f0ead3f449befc9d5fe67b5b0d96/Example_fields.png" width="200">
    end </td>
    bx = bbox(shape) </tr>
    bx:enlarge(1) </table>
    f = ui_field('surface', bx:min_corner(),bx:max_corner())
    cubes = {} In the next example, we use a field to avoid distributing (i.e. function ```distribute```) parts of the shape surface.
    for i = 1,#s do
    if ui_field_value_at('surface', s[i][1]) > 0.5 then <table>
    cubes[#cubes+1] = translate(s[i][1]) * frame(s[i][2]) * ccube(s[i][3]) <tr>
    end <td>
    end
    emit(union(shape,union(cubes))) ```lua
    ``` enable_variable_cache = true
    shape = sphere(10)
    </td> if not s then
    <td> s = distribute(shape, 0.5)
    <img src="uploads/3e2d7dde362967adb094ef5328aac543/Example_fields2.png" width="200"> end
    </td> bx = bbox(shape)
    </tr> bx:enlarge(1)
    </table> f = ui_field('surface', bx:min_corner(),bx:max_corner())
    cubes = {}
    ### Mesh Information <a name="meshinfo"></a> for i = 1,#s do
    if ui_field_value_at('surface', s[i][1]) > 0.5 then
    ```bbox(shape)``` cubes[#cubes+1] = translate(s[i][1]) * frame(s[i][2]) * ccube(s[i][3])
    end
    Returns the bounding box of ```shape``` as an object ```AAB```. end
    * ```shape```: Input shape emit(union(shape,union(cubes)))
    The ```AAB``` object has the following members: ```
    * ```min_corner```: Minimum corner of the bounding box _(vector)_
    * ```max_corner```: Maximum corner of the bounding box _(vector)_ </td>
    * ```center```: Center of the bounding box _(vector)_ <td>
    * ```extent```: Dimensions of the bounding box _(vector)_ <img src="uploads/3e2d7dde362967adb094ef5328aac543/Example_fields2.png" width="200">
    * ```empty```: Boolean value indicating whether the bounding box is _(bool)_ </td>
    * ```enlarge(mm)```: Enlarges the box by ```mm``` millimeters _(method)_ </tr>
    </table>
    ```mesh_vertices(mesh)```
    ### Mesh Information <a name="meshinfo"></a>
    Returns a table containing the vertices of a mesh.
    * ```mesh```: Input mesh ```bbox(shape)```
    ```mesh_normals(mesh)``` Returns the bounding box of ```shape``` as an object ```AAB```.
    * ```shape```: Input shape
    Returns a table containing the normals of a mesh. The ```AAB``` object has the following members:
    * ```mesh```: Input mesh * ```min_corner```: Minimum corner of the bounding box _(vector)_
    * ```max_corner```: Maximum corner of the bounding box _(vector)_
    ```mesh_local_edge_size(mesh)``` * ```center```: Center of the bounding box _(vector)_
    * ```extent```: Dimensions of the bounding box _(vector)_
    Returns a table containing the average connecting edge length of every vertex of a mesh. * ```empty```: Boolean value indicating whether the bounding box is _(bool)_
    * ```enlarge(mm)```: Enlarges the box by ```mm``` millimeters _(method)_
    ### Miscellaneous Functions <a name="miscfunc"></a>
    ```mesh_vertices(mesh)```
    ```print(str)```
    Returns a table containing the vertices of a mesh.
    Prints the message ```str``` * ```mesh```: Input mesh
    ```dofile(path)``` ```mesh_normals(mesh)```
    Executes the script in ```path``` Returns a table containing the normals of a mesh.
    * ```path```: input string * ```mesh```: Input mesh
    ```plugin_system_version()``` ```mesh_local_edge_size(mesh)```
    Returns the plugin system version string Returns a table containing the average connecting edge length of every vertex of a mesh.
    ```load_image(filename)``` ### Miscellaneous Functions <a name="miscfunc"></a>
    Returns a 2D table where each $`(i,j)`$ index is a vector that corresponds to the rgb pixel from the image file ```filename``` ```print(str)```
    ```set_brush_color(brush, r, g, b)``` Prints the message ```str```
    Sets the rendering color of ```brush``` to the normalized ```r```, ```g``` and ```b``` values. ```dofile(path)```
    * ```brush```: brush number
    * ```r```: normalized (i.e., $`[0,1]`$) red component value Executes the script in ```path```
    * ```g```: normalized (i.e., $`[0,1]`$) green component value * ```path```: input string
    * ```b```: normalized (i.e., $`[0,1]`$) blue component value
    ```plugin_system_version()```
    ```screenshot()```
    Returns the plugin system version string
    Saves a screenshot in the ```pictures``` folder or current script folder for the windows build.
    ```load_image(filename)```
    ```sleep(ms)```
    Returns a 2D table where each $`(i,j)`$ index is a vector that corresponds to the rgb pixel from the image file ```filename```
    Suspends execution of IceSL by ```ms``` milliseconds.
    * ```ms```: number of milliseconds ```set_brush_color(brush, r, g, b)```
    * ```path```: path to the script file
    Sets the rendering color of ```brush``` to the normalized ```r```, ```g``` and ```b``` values.
    ```dump(shape, filename)``` * ```brush```: brush number
    * ```r```: normalized (i.e., $`[0,1]`$) red component value
    Saves the shape ```shape``` in file ```filename``` * ```g```: normalized (i.e., $`[0,1]`$) green component value
    * ```shape```: shape to save * ```b```: normalized (i.e., $`[0,1]`$) blue component value
    * ```filename```: destination file to save the shape. Supports _stl_ and _obj_ extensions
    ```screenshot()```
    ## Service Mode <a name="servicemode"></a>
    Saves a screenshot in the ```pictures``` folder or current script folder for the windows build.
    IceSL offers the possibility of batch processing of its services (e.g., slicing, meshing, SVG output, etc.) without UI input. This is achievable through _Service Mode_.
    ```sleep(ms)```
    In _Service Mode_, it is mandatory to provide IceSL with a lua script via the command line. There is no user interface nor any interaction from the user. Moreover, IceSL only outputs diagnostic information of the services used in the script.
    Suspends execution of IceSL by ```ms``` milliseconds.
    ### Invoking Service Mode <a name="invokeservicemode"></a> * ```ms```: number of milliseconds
    * ```path```: path to the script file
    _Service Mode_ can only be activated in _IceSL-slicer_, it **cannot** be invoked in _IceSL-forge_. To activate _Service Mode_, execute _IceSL-slicer_ with the `-s` flag and provide a script to execute:
    ```dump(shape, filename)```
    * `IceSL-slicer.exe -s script_filename` (Windows)
    * `./IceSL-slicer -s script_filename` (Linux) Saves the shape ```shape``` in file ```filename```
    * ```shape```: shape to save
    A control string can be passed to the script while in service mode. This is done with the `-c` flag in the command line. It is subsequently set in the `control_string` global variable in the script: * ```filename```: destination file to save the shape. Supports _stl_ and _obj_ extensions
    * `IceSL-slicer.exe -c string -s script_filename` (Windows) ## Service Mode <a name="servicemode"></a>
    * `./IceSL-slicer -c string -s script_filename` (Linux)
    IceSL offers the possibility of batch processing of its services (e.g., slicing, meshing, SVG output, etc.) without UI input. This is achievable through _Service Mode_.
    ### Service Mode functions <a name="servicemodefunctions"></a> In _Service Mode_, it is mandatory to provide IceSL with a lua script via the command line. There is no user interface nor any interaction from the user. Moreover, IceSL only outputs diagnostic information of the services used in the script.
    In addition to all other documented functions, the following also become available in _Service Mode_: ### Invoking Service Mode <a name="invokeservicemode"></a>
    ```set_service(service)``` _Service Mode_ can only be activated in _IceSL-slicer_, it **cannot** be invoked in _IceSL-forge_. To activate _Service Mode_, execute _IceSL-slicer_ with the `-s` flag and provide a script to execute:
    Sets ```service``` as the current service to be used. * `IceSL-slicer.exe -s script_filename` (Windows)
    * ```service```: can be one of the following: * `./IceSL-slicer -s script_filename` (Linux)
    * ```'FilamentSlicer'```
    * ```'DLPSlicer'``` A control string can be passed to the script while in service mode. This is done with the `-c` flag in the command line. It is subsequently set in the `control_string` global variable in the script:
    * ```'LaserCutSlicer'```
    * ```'MeshExportService'``` * `IceSL-slicer.exe -c string -s script_filename` (Windows)
    * ```'SVGSlicer'``` * `./IceSL-slicer -c string -s script_filename` (Linux)
    ```run_service(filename)```
    ### Service Mode functions <a name="servicemodefunctions"></a>
    Executes the service on geometry emitted heretofore. Outputs the result to ```filename```.
    In addition to all other documented functions, the following also become available in _Service Mode_:
    ```load_settings(filename)```
    ```set_service(service)```
    Loads settings (e.g., printing settings) saved in ```filename```.
    * ```filename```: lua/xml file Sets ```service``` as the current service to be used.
    * ```service```: can be one of the following:
    ```clear_brush(brush)``` * ```'FilamentSlicer'```
    * ```'DLPSlicer'```
    Clears any emit done on ```brush``` up until this point. * ```'LaserCutSlicer'```
    * ```'MeshExportService'```
    ### Service Mode examples <a name="servicemodeexamples"></a> * ```'SVGSlicer'```
    Slicing in _Service Mode_: ```run_service(filename)```
    ```lua
    emit(scale(0.5) * load(Path..'fox.stl')) Executes the service on geometry emitted heretofore. Outputs the result to ```filename```.
    set_service('FilamentSlicer')
    load_settings(Path..'fox_printing_settings.lua') ```load_settings(filename)```
    run_service(Path..'fox.gcode')
    ``` Loads settings (e.g., printing settings) saved in ```filename```.
    * ```filename```: lua/xml file
    Meshing in _Service Mode_:
    ```lua ```clear_brush(brush)```
    emit(difference(ccube(40),sphere(25)))
    set_service('MeshExportService') Clears any emit done on ```brush``` up until this point.
    set_setting_value('meshing_method', 'Dual contouring')
    output_name = control_string..'.stl' ### Service Mode examples <a name="servicemodeexamples"></a>
    run_service('C:\\Users\\milchy\\Documents\\'..output_name)
    Slicing in _Service Mode_:
    ```lua
    emit(scale(0.5) * load(Path..'fox.stl'))
    set_service('FilamentSlicer')
    load_settings(Path..'fox_printing_settings.lua')
    run_service(Path..'fox.gcode')
    ```
    Meshing in _Service Mode_:
    ```lua
    emit(difference(ccube(40),sphere(25)))
    set_service('MeshExportService')
    set_setting_value('meshing_method', 'Dual contouring')
    output_name = control_string..'.stl'
    run_service('C:\\Users\\milchy\\Documents\\'..output_name)
    ``` ```
    \ No newline at end of file