Scripting Tutorial

Shape Rendering

PrinterKit allows scripting of core app features using the Lua programming language.

Here's an example of a simple script that generates a cube and displays it on the screen:

shape = Cube(3)
render(shape)

First, the built-in Cube function creates a 3d cube with edge size 3. After that the render function is called on the generated shape, telling the application to show the 3D shape on screen.

Multiple 3D shapes can be shown on screen at once:

shape1 = Cube(3)
render(shape1)

shape2 = Sphere(1.5,24)
shape2.translateX = 4
render(shape2)

The cube is generated the same way as the previous example. Then a sphere shape is created with the Sphere function. The first value is the sphere's radius. The second is how many points to use around the sphere's circumference.

The sphere is moved 4 units in the X direction using translateX. All built-in 3d functions generate shapes centered around the origin (0,0). One of the shapes must be moved, otherwise they would bouth be drawn on top of each other.

3D Shape Primatives

2D Shape Extrusion

In addition to the built-in 3D shapes, you can also generate 3D shapes via extrusion. To do this, first define a 2D shape and then extrude it a certain length. You can find the full listing at 2D Shape Functions Listing

hex = Hexagon(3)
length =  3.0
shape= extrude(hex, length)
render(shape)

2D shapes can also have interior cutouts. You can remove a section of a 2d shape by using the punch function

hex = Hexagon(3)
circ = Circle(0.5,  16)
hex:punch(circ, Vec2(-1,0))
hex:punch(circ, Vec2(1,0))
length =  3.0
shape = extrude(hex, length)
render(shape)

In the previous script two small circles are punched out of a larger hexagon shape. The punch function accepts a 2D shape as the first parameter, and the X,Y offset as the second parameter.

Extrusions do not happen immediately at the function call. It is only setting up configuration that will happen during model rendering. Because of this, you can supply other settings that happen during shape extrusion.

hex = Hexagon(3)
circ = Circle(0.5,  16)
hex:punch(circ, Vec2(-1,0))
hex:punch(circ, Vec2(1,0))
length =  6.0
shape = extrude(hex, length)
shape.rotateZ = Range(0,HALF_PI,0,1)
render(shape)

In this example the shape is rotated a quarter rotation over the duration of the extrusion. This is done with the Range function Range(float startValue, float endValue, float startPosition, float length).

The function instructs the shape to change from 0 rotation to HALF_PI. This will start at the beginning of the extrusion (0) and will be applied for the full length of the extrusion(1).

hex = Hexagon(3)
circ = Circle(0.5, 16)
hex:punch(circ, Vec2(-1,0))
hex:punch(circ, Vec2(1,0))
length = 6.0
shape = extrude(hex, length)
shape.rotateZ = Range(0,HALF_PI,0.25,0.5)
render(shape)

In this example the rotation is only applied to half the extrusion (0.5), and starts at a quarter of the duration of the extrusion (0.25)

hex = Hexagon(3)
circ = Circle(0.5, 16)
hex:punch(circ, Vec2(-1,0))
hex:punch(circ, Vec2(1,0))
length = 6.0
shape = extrude(hex, length)
shape.rotateZ = Range(0,HALF_PI,0.25,0.5)
shape.scaleXY = Range(1,0.5,0,1)
render(shape)

There are also helper settings that allow applying more than one setting at once. In this instance, both X and Y scaling go from full size to half size during the extrusion.

hex = Hexagon(3)
circ = Circle(0.5, 16)
hex:punch(circ, Vec2(-1,0))
hex:punch(circ, Vec2(1,0))
length = 6.0
shape = extrude(hex, length)
shape.scaleXY = RangeEase(1,0.5,Easing.QUINTIC,Direction.OUT)
render(shape)

A Range function does not have to be linear. Use different easing values to scale between values in a curved line.