About

This page describes libraries, data structures and render parameters relevant to writing design scripts in kokopelli. It is not appropriate as a general introduction to script-based design; for that, we recommend the (slightly outdated) tutorials found here.

Libraries and the MathTree data structure

Three standard libraries are included:

• koko.lib.shapes2d defines 2D shapes and transforms.
• koko.lib.shapes3d defines 3D shapes and transforms.
• koko.lib.text defines a font and text generation function.

For convenience, we also provide koko.lib.shapes, which combines the first two libraries.

The functions in these libraries return Python objects of class MathTree.

A MathTree object contains the following member variables:

• ptr: a pointer to a C data structure
• shape: a boolean that modifies the meaning of certain operations (e.g. A+B changes from numerical addition to logical combination if shape is True in A or B)
• color: a 3-item tuple containing an RGB color value (on a 0-255 range)
• bounds: an array of three Interval objects, containing bounds on X, Y, and Z axes.

Color

The color parameter can be set by designers. It accepts either a three-item tuple or a string from a set of pre-defined colors.

The pre-defined colors are red, blue, green, white, grey, black, yellow, cyan, and magenta; each of is tranformed into the appropriate RGB values when set.

from koko.lib.shapes import * c = circle(0, 0, 1) - circle(0, 0, 0.5) c.color = 'red' print c.color # This will print "(255, 0, 0)" cad.function = c

Object bounds

Each MathTree stores its own bounds (which may be None if appropriate bounds are not known). These bounds are used when exporting and when creating meshes for shaded rendering.

If Z bounds are unknown (e.g. in 2D design work), the height-map renderer will use (0,0). All three axes must be bounded to use the shaded renderer.

Individual bounds should be accessed using the properties xmin, xmax, ymin, ymax, zmin, and zmax. These properties safely access the bounds array, returning None if the bounds are not defined on that axis.

If you are using the standard libraries, bounds will automatically be created and propagated using interval arithmetic.

The automatically propagated bounds may not be as tight as possible. This is most noticeable when performing coordinate transforms that substantially distort the shapes.

Compare the following two examples. In the first example, the auto-propagated bounds are not optimal, because they are bounding the largest possible output (shown in the second example).

from koko.lib.shapes import * c = circle(0, 0, 0.5) c = taper_x_y(c, 0, -1, 1, -1, 2) cad.function = c

from koko.lib.shapes import * c = rectangle(-0.5, 0.5, -0.5, 0.5) c = taper_x_y(c, 0, -1, 1, -1, 2) cad.function = c

Bounds can be displayed with the option "Show bounds" in the View menu.

Rendering parameters

In the examples above, we select what to render by assigning it to cad.function. At evaluation-time, cad is an instance of the FabVars class, with the following member variables:

• shapes: list of MathTree objects to render
• render_mode: either None, 'height', or 'shaded'; defaults to None
• mm_per_unit: a floating-point value; defaults to 25.4 (i.e. 1 inch per unit)

The aforementioned function is a property that accesses the first item in shapes.

The parameter render_mode allows a script to dictate whether we render as a height map or as a shaded solid. When it is set to a value other than None, it will disable the corresponding options in the View menu.

Multi-object rendering

The parameter shapes takes a list of MathTree objects. Each shape is rendered separately, with its own bounds and coloring.

from koko.lib.shapes import * c1 = circle(0, 0, 0.5) c1.color = 'red' c2 = circle(0.7,0,0.2) c2.color = 'blue' cad.shapes = c1, c2

When multiple objects overlap, they are culled based on height.

from koko.lib.shapes import * c1 = sphere(0, 0, 0, 0.5) c1.color = 'red' c2 = sphere(0.5, 0.5, 0, 0.5) c2.color = 'blue' cad.shapes = c1, c2

When objects of the same height overlap (as is the case in many 2D designs), the first object listed takes priority in the height-map rendering. Compare the following two designs:

from koko.lib.shapes import * c1 = circle(0, 0, 0.5) c1.color = 'red' c2 = circle(0.5, 0.5, 0.5) c2.color = 'blue' cad.shapes = c1, c2

from koko.lib.shapes import * c1 = circle(0, 0, 0.5) c1.color = 'red' c2 = circle(0.5, 0.5, 0.5) c2.color = 'blue' cad.shapes = c2, c1

These features are especially useful when visualizing 3D press-fit structures. Per-object meshing prevents meshes from merging together and per-object coloring makes it easier to distinguish between different parts of a complete model

from koko.lib.shapes import * r1 = extrusion( rectangle(0, 1, 0, 1) + rectangle(0.25, 0.75, 0.5, 1.1), 0, 0.1) r1.color = 'red' r2 = extrusion( rectangle(0, 1, 0, 1) - rectangle(0.25, 0.75, 0.9, 1.5), 0, 0.1) r2.color = 'blue' cad.shapes = r1, move(rotate_x(r2, -90), 0, 1, 1)