stl_tools

Python code to generate STL geometry files from plain text, LaTeX code, and 2D numpy arrays (matrices).

This allows for rapid 3D printing of text, rendered equations, or simple digital images. Use them for product prototyping, art, cookie cutters, ice cube trays, chocolate molds, (see this to learn how to make a printed object food-safe) or whatever else you can think of.

Some modification may be needed to the STL or printer settings to get certain shapes to print cleanly (ie. thicker base, support structures, etc).

Besides printing, these can also be merged into other 3D meshes for many other possible uses, using programs such as Blender.

Also included is a function that can convert raw LaTeX expressions to high quality .png images, which allows for simple inclusion of LaTeX equations into non-LaTeX document editors.

A command-line script for converting images to STL (no text yet) is included in the installation for those who do not want to write Python code directly.

Requirements:

• Python 2.7 or higher (Python 3.x not yet tested, but would probably work)
• Numpy 1.7 or higher (for array manipulation)
• Scipy 0.12 or higher (for image reading and filtering functions)
• Matplotlib 1.2.1 or higher (for rendering text and LaTeX to image data)

Installation:

Run python setup.py build install to install.

This will check for the 3rd party dependencies above and install the library.

This will also install the command line script image2stl into the Python/Scripts directory.

Quickstart Examples:

Run the file examples.py to produce a few sample STL files from images included in examples/example_data.

The first example converts the commonly-used Lena test image to an STL file

from stl_tools import numpy2stl

from scipy.misc import lena, imresize
from scipy.ndimage import gaussian_filter

A = imresize(lena(), (256,256)) # load Lena image, shrink in half
A = gaussian_filter(A, 1) # smoothing

numpy2stl(A, "examples/Lena.stl", scale=0.1)

Source image vs. output geometry:

Click to view STL (view as wireframe)

The next three examples convert logos to STL, using color information to achieve appropriate 3D layering

Python code:

from scipy.misc import imread

A = imread("examples/example_data/NASA.png")
A = A[:,:,2] + 1.0*A[:,:,0] # Compose elements from RGBA channels to give depth 
A = gaussian_filter(A, 1) # smoothing

numpy2stl(A, "examples/NASA.stl", scale=0.05, mask_val = 5.)

Equivalent command-line syntax:

> image2stl NASA.png -scale 0.05 -mask_val 5. -RGBA_weights 1. 0. 1. 0. -gaussian_filter 1

Click to view STL (view as wireframe)

Python code:

A = imread("examples/example_data/openmdao.png")
A =  A[:,:,0] + 1.*A[:,:,3] # Compose elements from RGBA  channels to give depth 
A = gaussian_filter(A, 2) # smoothing

numpy2stl(A, "examples/OpenMDAO-logo.stl", scale=0.05, mask_val = 1.)

Equivalent command-line syntax:

> image2stl openmdao.png -scale 0.05 -mask_val 1. -RGBA_weights 1. 0. 0. 1. -gaussian_filter 2

Source image vs. output geometry:

Click to view STL (view as wireframe)

Finally, this example renders a LaTeX expression into a png image, then converts this image to an STL.

Note that LaTeX expressions which coincidentally contain special ASCII markers (such as \n and \r) have to be escaped with an additional slash in those positions in order to be properly rendered, unless these markers are intended.

Python code:

from stl_tools import numpy2stl, text2png, text2array

text = ("$\oint_{\Gamma} (A\, dx + B\, dy) = \iint_{U} \left(\\frac{\partial "
        "B}{\partial x} - \\frac{\partial A}{\partial y}\\right)\ dxdy$ \n\n "
        "$\\frac{\partial \\rho}{\partial t} + \\frac{\partial}{\partial x_j}"
        "\left[ \\rho u_j \\right] = 0$")
text2png(text, "examples/Greens-Theorem_Navier-Stokes", fontsize=50) #save png 

A = imread("examples/Greens-Theorem_Navier-Stokes.png") # read from rendered png
A = A.mean(axis=2) #grayscale projection
A = gaussian_filter(A.max() - A, 1.) 

numpy2stl(A, "examples/Greens-Theorem_Navier-Stokes.stl", scale=0.2, 
                                                         mask_val = 5.)

Source image vs. output geometry:

Click to view STL (view as wireframe)

Library usage:

There are 3 principal functions (no classes) to import and use from stl_tools:

stl_tools.numpy2stl

numpy2stl(A, fn, scale=0.1, mask_val = -np.inf, ascii=False, calc_normals=False)
Reads a numpy array, and outputs an STL file

Inputs:
 A (ndarray) -  an 'm' by 'n' 2D numpy array
 fn (string) -  filename to use for STL file

Optional input:
 scale (float)  -  scales the height (surface) of the 
                   resulting STL mesh. Tune to match needs

 mask_val (float) - any element of the inputted array that is less
                    than this value will not be included in the mesh.
                    default renders all vertices (x > -inf for all float x)

 ascii (bool)  -  sets the STL format to ascii or binary (default)

 calc_normals (bool) - sets whether surface normals are calculated or not

 max_width, max_depth, max_height (floats) - maximum size of the stl
                                            object (in mm). Match this to
                                            the dimensions of a 3D printer platform 

Returns: (None)

numpy2stl() is the main function of this repository.

It takes a 2D numpy array and output filename as input, and writes an STL file.

Each element of the array is tesselated to its neighbors to produce 2 triangular faces for every 4 contiguous elements. The depth axis of any vertex is taken to be the value of the array corresponding to that point.

The scale argument scales the height of the resulting geometry. It's a similair effect to extruding or shrinking.

The mask_val argument allows you to set a threshold value for elements in the input array for exclusion in the STL file. Array elements which are less than this value will not be included as vertices. It takes a bit of trial-and-error to get these just right. Plotting the intermediate arrays with a colorbar (to show scaling) helps in finding decent values.

The max_width, max_height, and max_depth values are measurements (in mm) used to scale the final output to the largest size that can fit onto your 3D printer platform. Default values are for the MakerBot Replicator.

stl_tools.text2png

text2png(text, fn = None)
Renders inputted text to a png image using matplotlib.

Inputs:
 text (string) -  text to render

Optional input:
 fn (string)  -  filename of png to be outputted.
                 defaults to the entered text

Returns: (None)

text2png() was written as an intermediate helper function to render text to pngs, to then be imported, filtered, and meshed. However, it may be useful in it's own right. For example, it can be used alone to render LaTeX expressions into images, to be imported into WYSIWYG document editors like MS Word or LibreOffice Writer.

stl_tools.text2array

text2array(text)
Renders inputted text, and returns array representation.

Inputs:
 text (string) -  text to render

Returns: A (ndarray) - 2D numpy array of rendered text

text2array() renders inputted text using text2png(), but imports the resulting png as an ndarray and deletes the intermediate file. There may be a direct way to render the matplotlib figure as an array without using an intermediate file, but I could not seem to find a simple way in the matplotlib docs.

Command-line scripts

image2stl

image2stl is a command-line script that is installed via entry points when setup.py is run. This provides a simple command-line interface to the functions of this library, with the same arguments. See the examples above for usage.

Tips:

• Consider scaling down a digital image before generating an STL from its pixels. For images of standard sizes for modern cameras, the resulting STL filesize can be pretty large.

• Just like was shown in the examples, applying a simple filtering function to smooth sharp edges results in an STL geometry that is likely to be more easily printable. Fine tuning in a program like Photoshop or Gimp can also help prevent spikes/jagged edges in the geometry. Contrast equalization or other types of filters may also be helpful (haven't tried yet).

• To make a proper mold, scale up the edges of the source image to match the maximum pixel value of the image (or higher), to form a lip. For example:

  m, n = A.shape
  border_val = 1.1 * A.max()
  A[0::m-1, :] = border_val # make top and bottom lip
  A[:, 0::n-1] = border_val # make left and right lip
  

  In practice, the border may need to be thicker than 1 pixel.

Todo/future features:

• Photos of actual printed models.

• I'm looking into writing a utility function to refine STL meshes by removing redundant vertices (so that wide flat spaces aren't packed with dense tessellations)

• It's possible to apply various warping functions to the resulting meshes. So you could load an image, warp the result into a cylinder, and have a textured column (or something like that).