OpenScad Project – Megan, Michael, Somer

For our open scad project we chose to use an image file and convert it in OpenScad to be able to print it. To do this we would use Trace2Scad. Trace2Scad is compatible with OpenScad so it would be perfect for this project. Trace2SCAD is a shell script using sed, awk, ImageMagick convert, mkbitmap, and potrace. Thanks to convert, nearly any image file format can be used for the input, and mkbitmap is used to further enhance the image for procesing, but the bulk of the work is really done by the incredibly useful Potrace. That tool is also what does the heavy lifting for Inkscape. However, rather than letting potrace go to all the work of generating smooth curves and then converting them to straight-line segments, we simply tell potrace to output straight-line segments. The specific style of grouped SVG output by potrace is then parsed and reprocessed to create an OpenSCAD module definition.

Heres how to use Trace 2 SCAD:

Trace2SCAD is really very easy to use, essentially able to accept just about any type of 2D image file as input and directly generating an output file that contains the OpenSCAD model as a set of module definitions. The modules are always scaled to be bounded within a 1mm cube that is sitting on the Z=0 plane and is centered at X=0, Y=0. That is almost certainly too small to be used directly; for example, if lithophane() is the name of a generated module that you want to make have a maximum X or Y dimension of 100mm and Z 3mm, this can be done using scale([100, 100, 3]) lithophane();. Note that the X/Y aspect ratio of the original image is preserved by trace2scad, so the X and Y scaling components should normally be the same value.

At this writing, the command line for trace2scad has fair number of options, but most are rarely needed. The basic usage is:

trace2scad {options} inputimagefile

The command line options are:

-a

Force alignment of the model based on image bounds (also --align). Normally, the model is centered based on the bounding box computed from the generated models, but that means position of the object within the original image is lost. Thus, overlaying multiple trace2scad models from the same original image will not align them. To ensure alignment, -a is automatically set if you are generating models for more than one layer.

-c number

Set the target model complexity (also --complex). The model will be iteratively simplified until the total number of points in the polygons is no more than number.

-e number

Set the maximum line-combining error in pixels (also --pixerr). When the model is converted to line segments, very often there will be cases where a sequence of multiple line segments could be converted into a single line segment with minimal error. This option sets the maximum distance, in pixels, that a discarded point can be from the line that replaces it. The default value is a very conservative 1.0; larger values will tend to greatly simplify the model while “smoothing” minor bumps that often happen due to pixel-level aliasing of the original image. For high-resolution images, -e 2 to -e 10 can really help smooth things with minimal ill effect. This feature was added in version 20150415.

-f number

Set the highpass filter radius (also --filter). If set to 0, the image will simply be thresholded to find edges and large dark areas will be modeled as solids. If set greater than 0, the effect is to convert constant-brightness regions into outlines with an edge thickness proportional to the number. Generally, a value between 2 and 4 is appropriate for outlining.

-g number

Set the image gamma (also --gamma). This allows simple adjustment of the tonal spread of the image before filtering and thresholding.

-h

Print the command line help message to stderr and exit.

-l levelspec

Set the level threshold or thresholds (also --level). A level directly determines the cut-off between model and void. The number should be a decimal value between 0 and 1 (exclusive); for example, “-l 0.5” would set a single threshold of 0.5. However, this command line option can also be used to specify multiple levels to create a contoured 3D model by union. Such a 3D contour, for example, can be used as the model for a Lithophane. You can give a single integer value (with no “.“) to request creation of that many levels with level thresholds equally spaced between 0 and 1. For example, “-l 4” would create four levels. If you want direct control over the individual levels used, you can instead list them with “,” between the threshold values: “-l 0.875,0.625,0.375,0.125” produces the same result as “-l 4” — creating four levels. If more than one level is specified, -a is implied to ensure that the levels will align correctly.

-o file

Set the file name for the OpenSCAD output to file. Normally, the output file name is derived from the input filename by replacing any characters after “.” with “.scad” — but that can be a problem if the image is coming from a read-only directory, etc. When you specify a different name using -o, the name is used precisely as entered, without adding the suffix “.scad.”

-p prefix

Set the name prefix to use for the generated OpenSCAD model (also --prefix). By default, the name prefix is derived from the image file name by removing the portion of the name after ., but that might not result in an appropriate name. For example, files can have - in their names, but OpenSCAD modules can’t. The resulting model can be instantiated by prefix();; an individual layer of the model can be instantiated by prefix_number(); where number is the level number starting at 1.

-s number

Set the sub-pixel resolution (also --subres). This is really a potrace parameter, determining the fraction of a pixel to which analysis is performed. Larger values are more precise, but values between 2 and 10 generally suffice.

-t number

Set the “turd” size (also --turd). This is really a potrace parameter, and the name isn’t my fault. Any traced region smaller than number pixels is essentially discarded from the model.

-v

Enable verbose output to stderr (also --verbose). There are some other messages that go to stdout, but these can be isolated because they go to stderr. Enabling verbosity also has the side effect of leaving temporary files holding the intermediate stages in processing, so it would be appropriate to think of it as primarily a debugging option.

-x number

Set the maximum X axis pixel resolution of the image (also --xres). This value doesn’t have as straightforward an effect on the model as one might expect, but larger values tend to create somewhat more complex models. The iterative complexity scaling is actually implemented by reducing this value and reprocessing.

-y number

Set the maximum Y axis pixel resolution of the image (also --yres). Just like X, but for the Y axis….

inputimagefile

The inputimagefile can be in any format understood by ImageMagick convert. The portion of the name after . is stripped to create the default prefix for OpenSCAD model component names. The output file name is also generated from inputimagefile by removing the portion of the name after . and replacing it with .scad. For example, test.jpg would produce OpenSCAD code names starting with test and would place the output in a file named test.scad.

Here’s an example of how our project would look on OpenScad: