Frequently Asked Questions


1. General questions

Question: Why is it called Potrace, and how is it pronounced?

Answer: My first name for this program was "pbm2eps", which was very lame and also inaccurate, because both the input and output file formats were likely to evolve over time. So I started looking for a cooler name. Since this program does tracing, I wanted a name with the word "trace" in it. I did a Google seach for each combination "atrace"..."ztrace" of a single letter plus "trace". Believe it or check for yourself: every single one of them was already taken by some other software!

Most of them were something boring, like a function in some obscure statistics package written in Fortran. If I remember correctly, the only exception was "ytrace", which brought up a foreign language porn site called "sexo con perros". I am not sure what "ytrace" might mean in some foreign language, but I have a pretty good idea what "sexo con perros" means, and so I didn't want to take the risk of giving this name to my program.

So I started looking for 2-letter combinations. It so happens that "potrace" didn't yield any hits on Google, except a few sites that had misspelled the word "podrace" (as in pod-racing) from Star Wars Episode I. This was okay, I thought, and would be unlikely to attract any trademark infringement suits. So I settled for the name Potrace. I particularly like this name because it can also mean "polygon-based tracer", which actually describes quite accurately what Potrace does.

By the way, it is pronounced "po-trace", not "pot-race". If it conjurs up mental images of people running around a track with cooking pots, then you are not pronouncing it correctly.

Question: And how do you spell it?

Answer: The name of this software is "Potrace". Please don't bicapitalize it ("PoTrace"), because that is an abomination.

Question: Is there a mailing list? How can I be notified of new releases?

Answer: There is currently no Potrace mailing list. However, Potrace has a project page at Sourceforge.net. This page provides a discussion forum, as well as a mechanism for reporting bugs. To be automatically notified of new Potrace releases, go to the Potrace project page on Sourceforge.net, find the section on "Latest File Releases" and click on the little envelope icon under "Notes/Monitor".

2. Basic usage and errors

Question: Can you show me the options used to generate the examples pictures on the Potrace website? I tried to do it myself, but failed.

Answer: All the examples were generated with the default settings. The EPS files were generated by the following command:

        cat file.pbm | potrace > file.eps
but the following also works:
        potrace file.pbm
The input to Potrace in each of these examples was a PBM file. But since most browsers can't display PBM, I posted the images in PNG format on the website, and I also scaled them. You need to shift-click on the left-hand side image to download each original PBM file.

The greymaps were generated by this command:

        cat file.pbm | potrace -gx2
This generates a PGM file. Again, for posting on the web, I have further translated this to the PNG format by piping the output through pnmtopng.

For experts only: If you want to know exactly how I processed these files, you can look at the Makefile that I used.

Question: I installed and ran Potrace, and it did not work. I got the error message: sh: line 1: compress: command not found. What am I doing wrong?

Answer: This error occurs only with Potrace version 1.3 or earlier. When this happens, you should either install the newest version of Potrace, or else run your existing version with the -c option, and everything should work fine.

Question: How can I improve the quality of the output of Potrace?

Answer: The most effective way to do so is to improve the quality of the input! This seems obvious, but not everybody thinks of this. Scan your image at a higher resolution. Scan your image in greyscale, and use a program such as mkbitmap to generate a high-resolution bitmap to trace.

In some cases, it also helps to decrease the resolution of the input image. If the resolution of your input file is incredibly high, the output generated by Potrace might be larger than necessary. This also sometimes happens if the input is speckly or noisy. Rather than trying to simplify the vector image, it often helps to just downscale the input bitmap.

Question: How can I reduce the number of nodes in the output of Potrace?

Answer: Potrace already makes an attempt to reduce the number of nodes, and this behavior is controlled by the --opttolerance parameter (or can be turned off entirely with --longcurve). However, I have decided not to sacrifice quality for quantity, and Potrace will not reduce the number of nodes beyond what it considers tolerable.

For many applications, the problem of reducing output file size can be solved by reducing the resolution of the input image. This sounds too simple to be true, but can give surprisingly good results. One of the most common "beginner's mistakes" when using Potrace is to start with an image that contains too much detail or noise. Blurring the input image can also help, particularly with grey-scale images.

3. File formats

Question: Why can Potrace not read/write PNG files? It is such a popular file format.

Answer: In keeping with the old unix philosophy "write programs that do only one thing and do it well", I am trying to avoid writing a frontend for every possible graphics file format known to mankind. Instead, I provide support for a small number of generic formats which are easy to convert to and from. The PNG format is relatively complex to implement, and there already exist many excellent programs for converting between PNG and the PNM format which Potrace can read. See the next question.

Question: What programs can read/write PBM files on Linux? Gimp does not seem to help me... How can I convert PNG to the formats that Potrace can read?

Answer: Gimp, unfortunately, cannot write PBM files (although it can read them). However, Gimp can write PNM files, as well as BMP files. Both file formats are understood by Potrace version 1.1 or later. Note that the files have to be bitmaps, i.e., they should only use two colors black and white. All other colors or grey values will be converted to black and white before Potrace begins its processing.

A good program for converting anything to PBM is the convert command line tool of ImageMagick. It is invoked simply as "convert inputfile outputfile". It is pre-installed on many systems, and can otherwise be obtained from www.imagemagick.org. The output format is determined by the filename extension, so for converting to pbm, you simply type:

        convert image.png image.pbm

Another very useful such set of command line utilities for converting different image formats are the "netpbm" utilities, see netpbm.sourceforge.net. Again, these tools are preinstalled on many popular systems. They allow you to convert between file formats on the command line. Particularly useful are pngtopnm and pnmtopng, but you can also convert to and from other formats using e.g. giftopnm, anytopnm and so forth. You can use these commands in a pipeline, for instance

        cat file.png | pngtopnm | potrace > file.eps

Question: I am working to add Potrace support to another program, but the output of Potrace leaves me a little stumped. How can I parse the output of Potrace into some format which my program can use?

Answer: To get parseable output from Potrace, I suggest using the -q and -c options. The default output is optimized for size, not readability. With 'potrace -qc', you should get exactly what you need.

If you use the output from Potrace for processing by another program, I also recommend increasing the output resolution, e.g., -u=100 or -u=1000, to reduce the effect of roundoff errors. Note that the output coordinates correspond to input (bitmap) coordinates, multiplied by the unit length, then rounded to integers.

4. Features

Question: Can Potrace handle color images?

Answer: The short answer is "no". Potrace can only handle 2-valued images at the moment. It does not matter whether the two colors are called "black" and "white" or "on" and "off" - however, there can be only two of them.

Question: Will color support be added to Potrace in the future?

Answer: Maybe.

Question: How can I work around the lack of color support?

Answer: There are many ways in which Potrace can be useful in processing color images, with some extra work. For example, you can trace an image to SVG format using the --svg and --opaque options, and then use e.g. Inkscape to color it manually.

Or you can extract individual color components from your image using the Gimp or ppmcolormask (part of the netpbm package), trace them separately, and then overlay the pieces to get a multicolored image. You can get pretty good results for posterized images. I have used a command line similar to this:

cat img.gif | giftopnm | ppmcolormask #641b1b | potrace

Recent versions of Inkscape have a built-in Potrace engine that can handle color images via color quantization or multiple scanning, thanks to the great work of Bob Jamison and the Inkscape team.

Another interesting application of Potrace to color images is described in the fascinating article Automatic Generation of Stained Glass from Scanned Photos by C. Scott Ananian.

Question: Does Potrace provide centerline tracing? Instead of tracing the contour of my image, I just want a single line in the center of each stroke.

Answer: No, Potrace is not designed to do centerline tracing, and for technical reasons, it is unlikely that this will change in the near future. Algorithms used for centerline tracing are quite different than those used for outline tracing; it might be more useful to write a separate program for this purpose. You could try Autotrace, which has such a feature.

5. Graphical user interface

Question: I don't like command line utilities. Is there a graphical user interface for Potrace?

Answer: Yes, there are now several graphical user interfaces (GUI's) for Potrace, contributed by various other people. There are GUI's for Linux and for Mac OSX. I have not tried them myself, so I cannot say if they work or if they have all the features you want. I suggest to try them out. Please look under GUI's and related software on the main Potrace web site.

Back to Potrace home.

Peter Selinger / Department of Mathematics and Statistics / Dalhousie University
selinger@users.sourceforge.net / PGP key