Editing StippleGen

Jump to: navigation, search

Warning: You are not logged in. Your IP address will be publicly visible if you make any edits. If you log in or create an account, your edits will be attributed to your username, along with other benefits.

The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.
Latest revision Your text
Line 7: Line 7:
  
  
−
One of the perennial problems that we have come across in a variety of contexts, including [http://www.evilmadscientist.com/2012/cnc-halftones-with-ascii-art/ CNC artwork] and producing artwork for the [http://shop.evilmadscientist.com/productsmenu/tinykitlist/171-egg-bot Egg-Bot], is the difficulty of creating good-quality toolpaths– i.e., vector artwork representing halftones –when starting from image files.  One of the finest solutions that we’ve ever come across is [https://web.archive.org/web/20210106025705/https://mrl.cs.nyu.edu/~ajsecord/stipples.html Adrian Secord's algorithm], which uses an iterative relaxation process to optimize a weighted  [http://en.wikipedia.org/wiki/Voronoi_diagram Voronoi diagram], mathematically producing a set of points (stipples) that can closely approach the appearance of a traditional stipple drawing.   
+
One of the perennial problems that we have come across in a variety of contexts, including [http://www.evilmadscientist.com/2012/cnc-halftones-with-ascii-art/ CNC artwork] and producing artwork for the [http://evilmadscience.com/productsmenu/tinykitlist/171-egg-bot Egg-Bot], is the difficulty of creating good-quality toolpaths– i.e., vector artwork representing halftones –when starting from image files.  One of the finest solutions that we’ve ever come across is [http://mrl.nyu.edu/~ajsecord/stipples.html Adrian Secord's algorithm], which uses an iterative relaxation process to optimize a weighted  [http://en.wikipedia.org/wiki/Voronoi_diagram Voronoi diagram], mathematically producing a set of points (stipples) that can closely approach the appearance of a traditional stipple drawing.   
  
 
Another important technique is [[TSP art]], where the image is represented by a single continuous path.  You can generate a path like this by connecting all of the dots in a stipple diagram.  Designing a route that visits each dot exactly once (and minimizing the distance travelled) is an example of the famous [http://en.wikipedia.org/wiki/Travelling_salesman_problem Travelling Salesman Problem] (or just “TSP”), and an optimal TSP path can give a surprisingly good grayscale representation of an image.    From the standpoint of toolpaths (for the Egg-bot and most other CNC machines), a TSP path is even nicer than stipples, because little or no time is spent raising and lowering the tool.
 
Another important technique is [[TSP art]], where the image is represented by a single continuous path.  You can generate a path like this by connecting all of the dots in a stipple diagram.  Designing a route that visits each dot exactly once (and minimizing the distance travelled) is an example of the famous [http://en.wikipedia.org/wiki/Travelling_salesman_problem Travelling Salesman Problem] (or just “TSP”), and an optimal TSP path can give a surprisingly good grayscale representation of an image.    From the standpoint of toolpaths (for the Egg-bot and most other CNC machines), a TSP path is even nicer than stipples, because little or no time is spent raising and lowering the tool.
Line 15: Line 15:
 
StippleGen is easy-to-use software that can generate TSP and stipple drawings from input images.  It saves its files as editable, Eggbot-ready Inkscape SVG files, which can in turn be opened by other vector graphics programs, or re-saved as PDF files for use in other contexts. It can also generate a TSP path from the stippled image, and either save that path as an SVG file or simply use that path as the order of plotting for the stipple diagram.
 
StippleGen is easy-to-use software that can generate TSP and stipple drawings from input images.  It saves its files as editable, Eggbot-ready Inkscape SVG files, which can in turn be opened by other vector graphics programs, or re-saved as PDF files for use in other contexts. It can also generate a TSP path from the stippled image, and either save that path as an SVG file or simply use that path as the order of plotting for the stipple diagram.
  
−
You can read an extended [http://www.evilmadscientist.com/article.php/stipple introduction to StippleGen] at Evil Mad Scientist Laboratories.  An introduction to StippleGen version 2 is also available [http://www.evilmadscientist.com/2012/stipplegen2/ here].
+
You can read an extended [http://www.evilmadscientist.com/article.php/stipple introduction to StippleGen] at Evil Mad Scientist Laboratories.
  
 +
== Download ==
  
−
== Download ==
+
StippleGen is free and open source software, written in the [http://processing.org/ Processing development environment].  It comes ready to run on Mac, Windows, and Linux, and it is [http://code.google.com/p/eggbotcode/downloads/list?can=2&q=stipplegen available for download here].
 +
 
 +
(StippleGen is hosted as part of the Eggbot project [http://code.google.com/p/eggbotcode/ on Google Code].)
  
−
StippleGen is free and open source software, written in the [http://processing.org/ Processing development environment].  It comes ready to run on Mac, Windows, and Linux, and it is [https://github.com/evil-mad/stipplegen/releases/latest available for download here].  The current version number is 2.31.
 
  
 +
The download includes ready-to-run platform-specific versions of StippleGen for Mac, Windows, and Linux, as well as the source code.  You will need to have a recent version of [http://java.com/ Java] installed on your computer. If the platform-specific version of the software won't run on your computer, please install Java and try again.)
  
−
The download includes ready-to-run platform-specific versions of StippleGen for Mac, Windows, and Linux, as well as the source code. Current Mac and Windows versions include Java. For linux, you will need to have a recent version of [http://java.com/ Java] installed on your computer.
 
  
 
== Quick Start ==
 
== Quick Start ==
Line 43: Line 45:
  
  
−
All of StippleGen's controls are accessed through the graphical user interface located in the lower part of the screen, in the gray bar.  In what follows, we will go over the usage of the individual controls within the interface.
+
All of Stipplegen's controls are accessed through the graphical user interface located in the lower part of the screen, in the gray bar.  In what follows, we will go over the usage of the individual controls within the interface.
  
  
Line 63: Line 65:
 
After the initial Voronoi diagram is calculated, StippleGen will display the stipple locations that it has calculated.    This "first guess" is usually quite crude— as you can see above — and will improve dramatically as you allow StippleGen to run for a while.
 
After the initial Voronoi diagram is calculated, StippleGen will display the stipple locations that it has calculated.    This "first guess" is usually quite crude— as you can see above — and will improve dramatically as you allow StippleGen to run for a while.
  
−
''Aside:'' The calculation of the stipple point locations through Secord's algorithm is an ''iterative'' process.  For any given "generation," the process begins with an initial set of points— whether that's the initial set of "sprinkled' points, or the output from the previous generation.  The Voronoi diagram of those points is then calculated, and each point is moved to the weighted centroid of its Voronoi cell.  That distribution of points then serves as the starting point for the subsequent generation.
+
''Aside:'' The calculation of the stipple point locations through Secord's algorithm is an ''iterative'' process.  For any given "generation," the process begins with an initial set of points— whether that's the initial set of "sprinkled' points, or the output from the previous generation.  The Voronoi diagram of those points is then calculated, and each point is moved to the weighted centroid of its Voronoi cell.  That distribution of points then serves as the starting point for the subsequent generation.)
  
  
Line 87: Line 89:
  
 
Two important notes about changing the number of stipples:  Using larger numbers of stipples will increase the time required per generation.
 
Two important notes about changing the number of stipples:  Using larger numbers of stipples will increase the time required per generation.
−
And, again, please note that changing the number of stipples will restart the calculation from the beginning, as though you had just loaded a new file.
+
And, again, please note that changing the number of stipples will restart  restart the calculation from the beginning, as though you had just loaded a new file.
  
  
Line 101: Line 103:
 
However, the most important reason to pick one color scheme or the other may be the intended application of the resulting drawing.  If, for example, you will be drawing with black ink on an egg, you will probably want to pick black stipples and a white background.  On the other hand, if you will be [http://www.evilmadscientist.com/2012/cnc-halftones-with-ascii-art/ carving into a black panel], you may prefer white features on a black background.
 
However, the most important reason to pick one color scheme or the other may be the intended application of the resulting drawing.  If, for example, you will be drawing with black ink on an egg, you will probably want to pick black stipples and a white background.  On the other hand, if you will be [http://www.evilmadscientist.com/2012/cnc-halftones-with-ascii-art/ carving into a black panel], you may prefer white features on a black background.
  
−
To toggle between the two color schemes, press the wide button underneath the stipple-count slider, labeled with the current color scheme (typically "BLACK STIPPLES, WHITE BACKGROUND").  Pressing this button will switch the color scheme and restart the calculation from the beginning, as though you had just loaded a new file.  Also, if you wish to restart the calculation for any reason, pressing this button twice is a good way to do that.
+
To toggle between the two color schemes, press the wide button underneath the stipple-count slider, labeled with the current color scheme (typically "BLACK STIPPLES, WHITE BACKGROUND").  Pressing this button will switch the color scheme and restart restart the calculation from the beginning, as though you had just loaded a new file.
  
  
Line 108: Line 110:
 
http://evilmadscience.s3.amazonaws.com/wiki/eggbot/stipplegen/v2docs/plant2k.png
 
http://evilmadscience.s3.amazonaws.com/wiki/eggbot/stipplegen/v2docs/plant2k.png
  
−
Shown above are two stipple drawings made from the same image of a corn plant, a sample image from [https://web.archive.org/web/20210106025705/https://mrl.cs.nyu.edu/~ajsecord/stipples.html here]. One drawing is made with black dots on a white background, and the other has white dots on a black background.  However, each drawing has 2000 dots and the parameters are otherwise identical.  In this case, as the source image was predominantly white, the image with the white background is of considerably higher quality, as the dots are concentrated in the area of interest, rather than in the background.
+
Shown above are two stipple drawings made from the same image of a corn plant, a sample image that you can download [http://mrl.nyu.edu/~ajsecord/stipples.html here]. One drawing is made with black dots on a white background, and the other has white dots on a black background.  However, each drawing has 2000 dots and the parameters are otherwise identical.  In this case, as the source image was predominantly white, the image with the white background is of considerably higher quality, as the dots are concentrated in the area of interest, rather than in the background.
  
 
   
 
   
Line 141: Line 143:
 
You can also adjust the size range to be much larger, for a different final effect.  However, it is interesting to note that human-drawn stipple drawings tend to have a size range not much above 3-4.  Also, be aware that if you are using StippleGen to create artwork for CNC tools, there ''may'' be a minimum feature size (e.g., pen width) that is not accurately represented by the tiny dots shown here.
 
You can also adjust the size range to be much larger, for a different final effect.  However, it is interesting to note that human-drawn stipple drawings tend to have a size range not much above 3-4.  Also, be aware that if you are using StippleGen to create artwork for CNC tools, there ''may'' be a minimum feature size (e.g., pen width) that is not accurately represented by the tiny dots shown here.
  
 +
 +
http://evilmadscience.s3.amazonaws.com/wiki/eggbot/stipplegen/v2docs/grace10k-dotrange1.png
  
 
http://evilmadscience.s3.amazonaws.com/wiki/eggbot/stipplegen/v2docs/grace10k-dotrange2.png
 
http://evilmadscience.s3.amazonaws.com/wiki/eggbot/stipplegen/v2docs/grace10k-dotrange2.png
Line 150: Line 154:
 
==== White Cutoff ====
 
==== White Cutoff ====
  
−
You can use the  "White Cutoff" slider can be to hide stipples in regions of very low density, for example if you find occasional black dots (correctly representing average density) to be distracting on a light-colored background.   
+
You can use the  "White Cutoff" slider can be to hide stipples in regions of very low density, for example if you find occasional black dots (correctly representing average density) to be distracting on a light-colored background.  Note that the "White Cutoff" slider will relabel itself "Black Cutoff" when working with white dots on a black background.
−
 
−
 
 
−
http://evilmadscience.s3.amazonaws.com/wiki/eggbot/stipplegen/v2docs/grace10k-dotrange4.png
 
  
−
In our demo image above, we have now adjusted the "White Cutoff" slider to 0.07, which hides much of the background.
 
  
 +
http://evilmadscience.s3.amazonaws.com/wiki/eggbot/stipplegen/v2docs/grace10k-dotrange3.png
  
−
''Note 1:'' The "White Cutoff" slider will relabel itself "Black Cutoff" when working with white dots on a black background.
+
http://evilmadscience.s3.amazonaws.com/wiki/eggbot/stipplegen/v2docs/grace10k-dotrange4.png
  
−
''Note 2:'' While changing the white cutoff value will not affect the calculation of stipple locations, it does affect which stipples will be included in the output files.  Because of this, changing the white cutoff will restart the calculation of the TSP path, if you change it while in "paused" mode.  You can read more about the [[StippleGen#TSP_Path|paused mode]] below.
+
In our demo image above, we have now adjusted the "White Cutoff" slider to hide much of the background.
  
  
Line 187: Line 188:
  
  
−
==== Pause / TSP Path ====
+
==== TSP Path ====
  
 
http://evilmadscience.s3.amazonaws.com/wiki/eggbot/stipplegen/v2docs/newgui-pausemode.png
 
http://evilmadscience.s3.amazonaws.com/wiki/eggbot/stipplegen/v2docs/newgui-pausemode.png
  
−
When you press the "Pause" button, StippleGen ceases calculation of the stipple locations, and begins calculating the "TSP" path between the points.  The lower button, "Plotting Path," can hide or show the path during this part of the calculation.  (Neither of these buttons actually affects the stipple location of the stipples, except to pause it.)
+
When you press the "Pause" button, StippleGen ceases calculation of the stipple locations, and begins calculating the "TSP" path between the points.  The TSP ("travelling salesman problem") path is an efficient route plotted between the stipple locations.    And, depending on how plan to use StippleGen's output, this part of the process may or may not be important to you.
 +
 
  
−
Additional details about the TSP path calculation process are in the next section.
 
  
  
 +
''Note:'' If you press the Pause again (to unpause/resume calculation) the TSP path will be lost, and a new one will be calculated (from scratch) when you press the pause button again.
 +
 +
 +
 +
 +
http://evilmadscience.s3.amazonaws.com/wiki/eggbot/stipplegen/v2docs/grace2k-TSP1.jpg
 +
 +
When you first press the "Pause" button, the path between the stipple locations looks like a rats nest.
  
  
Line 213: Line 222:
 
http://evilmadscience.s3.amazonaws.com/wiki/eggbot/stipplegen/v2docs/newgui-loadsave.png
 
http://evilmadscience.s3.amazonaws.com/wiki/eggbot/stipplegen/v2docs/newgui-loadsave.png
  
−
'''''Then''''', and usually after waiting for a moment, press one of the two buttons to either save the stipple drawing or the TSP path.  You will be prompted for the location to save the file.  
+
'''''Then''''', press one of the two buttons to either save the stipple drawing or the TSP path.  You will be prompted for the location to save the file.  
  
 
If you press one of the two save buttons before you have paused, StippleGen will not present you with a dialog box to save the file, but will instead go into the paused mode.  If this happens, you can press the save button again, now that it's paused.
 
If you press one of the two save buttons before you have paused, StippleGen will not present you with a dialog box to save the file, but will instead go into the paused mode.  If this happens, you can press the save button again, now that it's paused.
Line 221: Line 230:
  
  
−
 
−
==== Calculating the TSP Path ====
 
−
 
−
When you press the "Pause" button, StippleGen ceases calculation of the stipple locations, and begins calculating the "TSP" path between the points.  You can press the lower button, "Plotting Path" to hide or show the path.
 
−
 
−
 
−
The TSP ("travelling salesman problem") path is an efficient route plotted between the stipple locations.  And, depending on how you plan to use StippleGen's output, this part of the process may or may not be important to you:
 
−
 
−
* If you are creating a set of stipple points for use on the Eggbot, the order in which the points are plotted is given by their order in the file.  If you allow the TSP path to be calculated— at least until the end of the "rats nest" stage —will dramatically reduce plotting time.
 
−
* If you are creating a set of stipple points for other CNC machines, the plot order ''may or may not'' affect downstream applications, depending on whether or not there is a separate optimization stage later, when creating your toolpath.
 
−
* If you are creating a set of stipple points for a different application, the point order is usually not important at all.
 
−
* If you are creating a true "TSP path" as your primary output, this stage of the calculation is just as important as the stipple calculation. You should allow it to run until it is optimal or you run out of patience.
 
−
 
−
 
−
Notes on calculating the plotting path:
 
−
 
−
''Note 1:''  If you press the Pause again (to unpause/resume calculation), the TSP path will be lost, and a new one will be calculated (from scratch) when you press the pause button again.  If you wish to restart the path for any reason, pressing this button twice is a good way to do that.
 
−
 
−
''Note 2:''  The TSP path will also be restarted if you adjust the white cutoff parameter.
 
−
 
−
''Note 3:''  Hiding or showing the TSP path is strictly a display option; it has no effect on the calculation or output. To choose whether your output file consists of points or lines, select one of the two save buttons: A stipple file consists of points, while the TSP path file consists of a single set of joined lines.
 
−
 
−
 
−
 
−
 
−
 
−
http://evilmadscience.s3.amazonaws.com/wiki/eggbot/stipplegen/v2docs/plant10kpath_0.png
 
−
 
−
Let's begin with a nicely optimized corn plant stipple drawing, with 10,000 stipple points.  (At this stage we do not have any white cutoff.)
 
−
 
−
 
−
 
−
http://evilmadscience.s3.amazonaws.com/wiki/eggbot/stipplegen/v2docs/plant10kpath_1.jpg
 
−
 
−
When you first press the "Pause" button, the path between the stipple locations looks like a rats nest, as the program goes through the coarsest stage of finding a path between the points.  This stage may last for only a brief moment, particularly when working with relatively low numbers of stipples.
 
−
 
−
 
−
 
−
http://evilmadscience.s3.amazonaws.com/wiki/eggbot/stipplegen/v2docs/plant10kpath_2.png
 
−
 
−
After a few moments the path between the points begins to look a little more rational— the rats nest has gone away.  If your output will be a set of stipple points (as opposed to a TSP path), this is already sufficiently optimized, and you can save your file now.
 
−
 
−
If, on the other hand, your primary output is actually a TSP path, you'll want to let it run for a while longer.  (One hint: an optimal TSP path will not have any line segments that cross.)
 
−
 
−
 
−
(If you're wondering what happened to the points, we've just reduced the min. dot size and the size range here, so that you can see the path better.)
 
−
 
−
 
−
 
−
http://evilmadscience.s3.amazonaws.com/wiki/eggbot/stipplegen/v2docs/plant10kpath_3.png
 
−
 
−
For this path, we've (1) used the white cutoff to hide the background and (2) allowed it to run for a few more minutes.  This path probably won't get much better, so it's a good time to save the TSP path file.  There are some little defects, but we're probably better off opening up the file in Inkscape at this point to edit away the bad path segments by hand.
 
  
 
==== Saving a Stipple Drawing ====
 
==== Saving a Stipple Drawing ====
  
−
http://evilmadscience.s3.amazonaws.com/wiki/eggbot/stipplegen/v2docs/newgui-loadsave.png
 
  
−
Once in paused mode, press the button labeled "Save Stipple File" to save your stipple drawing as an SVG file.
 
−
 
−
 
−
 
−
http://evilmadscience.s3.amazonaws.com/wiki/eggbot/stipplegen/v2docs/fileoutplant_small.png
 
−
 
−
Here's what the corn plant drawing looks like, opened up in Inkscape.  (See below for more about the file format.)
 
−
 
−
 
−
 
−
http://evilmadscience.s3.amazonaws.com/wiki/eggbot/stipplegen/v2docs/fileout_circles.png
 
−
 
−
The drawing is made up of a very large number of small circles, whose size is determined by the dot sizes in StippleGen.
 
−
 
−
 
−
http://evilmadscience.s3.amazonaws.com/wiki/eggbot/stipplegen/v2docs/graceegg-640.jpg
 
−
 
−
The stipple drawing can be used for almost anything at this point.
 
−
 
−
This image that we've drawn on the egg was rendered with only 2000 stipples. Properly tuned for making dots rapidly, the Eggbot can plot about four stipples per second, so this kind of a plot can take as little as ten minutes, and can actually produce a remarkable likeness of a photo.
 
  
  
Line 303: Line 239:
 
==== Saving a TSP Path Drawing ====
 
==== Saving a TSP Path Drawing ====
  
−
http://evilmadscience.s3.amazonaws.com/wiki/eggbot/stipplegen/v2docs/newgui-loadsave.png
 
−
 
−
Once in paused mode, press the button labeled 'Save "TSP Path"' to save the TSP path drawing as an SVG file.
 
−
 
−
 
−
http://evilmadscience.s3.amazonaws.com/wiki/eggbot/stipplegen/v2docs/fileout_tsp_small.png
 
−
 
−
Here's what the corn plant TSP path drawing looks like, opened up in Inkscape.  (See below for more about the file format.)
 
−
 
−
 
−
 
−
http://evilmadscience.s3.amazonaws.com/wiki/eggbot/stipplegen/v2docs/fileout_tsp_large_edited.jpg
 
−
 
−
And now, we've edited the path to remove a couple of the distracting segments, using Inkscape's path editing tools.  We're now ready to plot this path.
 
−
 
−
 
−
http://evilmadscience.s3.amazonaws.com/wiki/eggbot/stipplegen/v2docs/cornplant.jpg
 
−
 
−
Because this is essentially one continuous path, with almost no pen-up/pen-down motion, the whole drawing can be plotted in a minute or two.
 
  
  
Line 345: Line 262:
 
== Source Code ==
 
== Source Code ==
  
−
The StippleGen source code is available at [https://github.com/evil-mad/stipplegen GitHub].  To run the code from source, you'll need to download [http://processing.org/ Processing], and install the [https://bitbucket.org/postspectacular/toxiclibs/wiki/Home toxiclibs library] and the [http://www.sojamo.de/libraries/controlP5/ ControlP5 library]. You don't need to download these libraries separately; install and start Processing, then go to Sketch | Import Library... | Add Library... , search for them and click Install, and it will install them in the right place automatically. (Update the "sketchbook path" in the Preferences if you don't want them installed in a "processing" subdir of your home folder.)
+
The StippleGen source code is available as part of the [http://code.google.com/p/eggbotcode/downloads/list?can=2&q=stipplegen StippleGen .zip file].  To run the code from source, you'll need to download [http://processing.org/ Processing], and install the [http://hg.postspectacular.com/toxiclibs/downloads toxiclibs library] and the [http://www.sojamo.de/libraries/controlP5/ ControlP5 library].

Please note that all contributions to Evil Mad Scientist Wiki are considered to be released under the GNU Free Documentation License 1.3 (see Evil Mad Scientist Wiki:Copyrights for details). If you do not want your writing to be edited mercilessly and redistributed at will, then do not submit it here.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource. Do not submit copyrighted work without permission!

To edit this page, please answer the question that appears below (more info):

Cancel | Editing help (opens in new window)
Retrieved from "https://wiki.evilmadscientist.com/StippleGen"