NAME
potrace - transform bitmaps into vector graphics.
SYNOPSIS
potrace [options] [filename...]
DESCRIPTION
potrace is a utility for tracing a bitmap, which means, transforming a
bitmap into a smooth, scalable image. The input is a bitmap, which
means, a pixel-based image composed of the two colors black and white
only. The default output is an encapsulated PostScript file (EPS). A
typical use is to create EPS files from scanned data, such as company
or university logos, handwritten notes, etc. The resulting image is not
"jaggy" like a bitmap, but smooth. It can then be rendered at any
resolution.
potrace can read bitmaps in the following formats: PBM, PGM, PPM
(collectively known as PNM, see pnm(5)), as well as BMP (Windows and
OS/2 bitmap formats). The input image should only use the two colors
black and white. If other pixel values appear in the input, they will
be converted to black and white using a simple threshold method.
potrace can currently produce the following output formats: EPS,
PostScript, PDF, SVG, PGM, and XFIG. An experimental gimppath backend
is also available. Additional backends might be added in the future.
OPTIONS
The following options are supported. Dimensions (arguments of type dim)
can have optional units, e.g. 6.5in, 15cm, 100pt. The default unit is
inches (or centimeters, if this was configured at compile time, see
COMPILE TIME CONFIGURATION below). For pixel-based output formats such
as PGM and gimppath, the default unit is pixels.
General options:
-h, --help print help message and exit.
-v, --version print version info and exit.
-l, --license print license info and exit.
-V, --show-defaults
print the defaults which were compiled into this version
of potrace, and exit.
--progress display a progress bar for each bitmap that is
processed. This is useful for interactive use, and
requires a terminal. The default behavior is not to show
any progress information.
Input/output options:
filename If filename arguments are given, then potrace will by
default create one output file for each input filename
given. The name of the output file is obtained from the
input filename by changing its suffix according to the
chosen backend. If changing the suffix is impossible
because the names of the input and output files would be
identical, then the output filename is created by adding
the "-out" suffix to the name of the input file. If no
filename arguments are given, then potrace acts as a
filter, reading from standard input and writing to
standard output. A filename of "-" may be given to
specify reading from standard input.
-o filename, --output filename
write output to this file. All output is directed to the
specified file. If this option is used, then multiple
input filenames are allowed only for those backends
which can handle multiple bitmaps; these are currently
the PostScript and PGM backends. In this case, each
input file may contain one or more bitmaps, and all the
bitmaps from all the input files are processed and the
output concatenated into a single file. A filename of
"-" may be given to specify writing to standard output.
Backend selection:
-b name, --backend name
Select backend by name, where name is one of eps,
postscript, ps, pdf, svg, pgm, gimppath, xfig. Backend
names can be abbreviated by an unambiguous prefix.
-e, --eps Encapsulated PostScript backend (default). The input is
a single bitmap; the output is a stand-alone,
encapsulated PostScript file which can be included in
other documents.
-p, --postscript
PostScript backend. For this backend, the input may
consist of multiple concatenated bitmaps, which will be
turned into a multi-page PostScript document.
-b pdf, --backend pdf
PDF backend. For this backend, the input may consist of
multiple concatenated bitmaps, which will be turned into
a multi-page PDF document.
-s, --svg SVG backend. This backend produces a scalable vector
graphics (SVG) file. This backend can process one bitmap
per output file.
-g, --pgm PGM backend. This backend produces a portable greymap
(PGM) file. It is a convenient backend for antialiasing
a bitmap image. The input may consist of multiple
concatenated bitmaps, in which case multiple greymaps
will be written to the output.
-b gimppath, --backend gimppath
Experimental gimppath backend. This backend produces a
path which can be imported by the GNU Image Manipulation
Program (Gimp) (in the Layers, Channels & Paths dialog,
select Paths, then right-click and select Import Path).
Note that Gimp’s paths have some peculiar features: they
have no bounding box, they cannot be scaled, and all
control points are forced to be integers. For these
reasons, it is difficult to produce good Gimp paths at
low resolutions. The gimppath backend ignores almost all
scaling and placement options; instead, the --unit
option must be used to set the desired magnification.
The --rotate option is also recognized. Note that the
imported path can lie outside the bounds of the current
image in Gimp; in this case, one needs to move the path
(alt-click) or work with a larger image.
-b xfig, --backend xfig
XFig backend. Note that XFig uses X-splines instead of
Bezier curves, thus it is not possible to translate the
output of potrace into the XFig format with absolute
accuracy. This backend does a reasonable approximation
using two control points for each Bezier curve segment.
Note that the -u option has no effect for this backend,
as control points are always rounded to the nearest
1/1200 of an inch in XFig. Rotation and color are
implemented. Curve optimization is disabled.
Algorithm options:
For more detailed information on these options, see TECHNICAL
DOCUMENTATION below.
-z policy, --turnpolicy policy
specify how to resolve ambiguities in path
decomposition. Must be one of black, white, right, left,
minority, majority, or random. Default is minority. Turn
policies can be abbreviated by an unambigous prefix,
e.g., one can specify min instead of minority.
-t n, --turdsize n
suppress speckles of up to this many pixels.
-a n, --alphamax n
set the corner threshold parameter. The default value is
1. The smaller this value, the more sharp corners will
be produced. If this parameter is negative, then no
smoothing will be performed and the output is a polygon.
The largest useful value is 4/3 or 1.334, which
suppresses all corners and leads to completely smooth
output.
-n, --longcurve
turn off curve optimization. Normally potrace tries to
join adjacent Bezier curve segments when this is
possible. This option disables this behavior, resulting
in a larger file size.
-O n, --opttolerance n
set the curve optimization tolerance. The default value
is 0.2. Larger values allow more consecutive Bezier
curve segments to be joined together in a single
segment, at the expense of accuracy.
-u n, --unit n set output quantization. Coordinates in the output are
rounded to 1/unit pixels. The default of 10 usually
gives good results. For some of the debug modes, a value
of 100 gives more accurate output. In the case of the
gimppath backend, the -u option is used to set the
desired magnification. This option has no effect for the
XFig backend, which always rasterizes to 1/1200 inch.
-d n, --debug n
produce debugging output of type n. This has different
effects for different backends. For the PostScript/EPS
backends, the values n=1,2,3 illustrate the intermediate
stages of the potrace algorithm.
Scaling and placement options:
-W dim, --width dim
set the width of output image. If only one of width and
height is specified, the other is adjusted accordingly
so that the aspect ratio is preserved.
-H dim, --height dim
set the height of output image. See -W for details.
-r n[xn], --resolution n[xn]
set the resolution (in dpi). One inch in the output
image corresponds to this many pixels in the input. Note
that it follows that a larger value results in a smaller
output image. It is possible to specify different
resolutions in the x and y directions by giving an
argument of the form nxn. This option has no effect for
the PGM backend.
-x n[xn], --scale n[xn]
set the scaling factor (PGM backend only). A value
greater than 1 enlarges the output, a value between 0
and 1 makes the output smaller. It is possible to
specify different scaling factors in the x and y
directions by giving an argument of the form nxn.
-S n, --stretch n
set the aspect ratio. A value greater than 1 means the
image will be stretched in the y direction. A value
between 0 and 1 means the image will be stretched in the
x direction.
-A angle, --rotate angle
set the rotation angle (in degrees). The output will be
rotated counterclockwise by this angle. This is useful
for compensating for images that were scanned not quite
upright.
-M dim, --margin dim
set all four margins. The effect of this depends on the
backend. For variable-sized backends (EPS, PGM, SVG),
the margins will simply be added around the output image
(or subtracted, in case of negative margins). For fixed-
size backends (PostScript, XFig), the margins settings
can be used to control the placement of the image on the
page. If only one of the left and right margin is given,
the image will be placed this distance from the
respective edge of the page, and similarly for top and
bottom. If margins are given on opposite sides, the
image is scaled to fit between these margins, but not if
the scaling is already determined explicitly by one or
more of the -W, -H, -r, or -x options.
-L dim, --leftmargin dim
set the left margin. See -M for details.
-R dim, --rightmargin dim
set the right margin. See -M for details.
-T dim, --topmargin dim
set the top margin. See -M for details.
-B dim, --bottommargin dim
set the bottom margin. See -M for details.
Output options:
These options are only supported by certain backends.
-C #rrggbb, --color #rrggbb
set the foreground color of the output image. The
default is black. This option works for the PS/EPS, SVG,
and XFig backends.
--fillcolor #rrggbb
set the fill color of the output image, i.e., the color
of the "white" parts. The default is to leave these
parts transparent. This option works for the PS/EPS,
SVG, and XFig backends. Implies --opaque.
--opaque fill in the white parts of the image opaquely, instead
of leaving them transparent. This only applies to
interior white parts, i.e., those which are enclosed
inside a black outline. This option works for the PS/EPS
and SVG backends. Opaqueness is always in effect for the
XFig backend.
--group try to group related paths together in the SVG output.
Each path is grouped together with all paths that are
contained inside it, so that they can be moved around as
a unit with an SVG editor. This makes coloring
individual components slightly more cumbersome, and thus
it is not the default.
PostScript/EPS options:
-P format, --pagesize format
set page size. This is primarily used for the PostScript
backend. In case of the EPS backend, it may influence
the default image size. The following formats can be
specified: a4, a3, a5, b5, letter, legal, tabloid,
statement, executive, folio, quarto, 10x14. Also, an
argument of the form dimxdim is accepted to specify
arbitrary dimensions. The default page size is letter
(or a4, if this was configured at compile time, see
COMPILE TIME CONFIGURATION below). Page format names
can be abbreviated by an unambigous prefix.
-c, --cleartext
do not compress the output. This option disables the use
of compression filters in the PostScript output. If the
-q option is also used, the resulting output can be
easily read by other programs or even by humans.
-2, --level2 use PostScript level 2 compression (default). The
resulting file size is ca. 40% smaller than if the -c
option is used.
-3, --level3 use PostScript level 3 compression, if available. This
gives slightly smaller files than using -2, but the
resulting files may not print on older PostScript level
2 printers. If support for PostScript level 3
compression has been disabled at compile time, a warning
message is printed and level 2 compression is used
instead.
-q, --longcoding
turn off optimized numerical coding. Normally, potrace
uses a very compact numerical format to represent Bezier
curves in PostScript, taking advantage of some
redundancy in the curve parameters. This option disables
this behavior, resulting in longer, but more readable
output (particularly if the -c option is also used).
PGM options:
-G n, --gamma n
set the gamma value for anti-aliasing (default is 2.2).
Most computer displays do not render shades of grey
linearly, i.e., a grey value of 0.5 is not displayed as
being exactly half-way between black and white. The
gamma parameter corrects for this, and therefore leads
to nicer looking output. The default value of 2.2 is
appropriate for most normal CRT displays.
Frontend options:
-k n, --blacklevel n
set the threshold level for converting input images to
bitmaps. The potrace algorithm expects a bitmap, thus
all pixels of the input images are converted to black or
white before processing begins. Pixels whose brightness
is less than n are converted to black, all other pixels
to white. Here n is a number between 0 and 1. One case
is treated specially: if the input is in an indexed
color format with exactly 2 colors, then the blacklevel
is ignored and the darker of the two colors is mapped to
black.
Note: the method used by potrace for converting greymaps
to bitmaps is very crude; much better results can be
obtained if a separate program, such as mkbitmap(1), is
used for this purpose. In particular, mkbitmap(1), which
is distributed with potrace, has the ability to scale
and interpolate the image before thresholding, which
results in much better preservation of detail.
-i, --invert invert the input bitmap before processing.
COMPILE TIME CONFIGURATION
Certain aspects of the behavior of potrace can be configured at compile
time by passing the following options to the ./configure script.
--disable-zlib compile potrace without the zlib compression library.
This means PostScript level 3 compression will not be
available.
--enable-metric
compile potrace with centimeters as the default unit
instead of inches.
--enable-a4 compile potrace with A4 as the default page size.
EXIT STATUS
The exit status is 0 on successful completion, 1 if the command line
was invalid, and 2 on any other error.
VERSION
1.8
AUTHOR
Peter Selinger <selinger at users.sourceforge.net>
TECHNICAL DOCUMENTATION
For a detailed technical description of the potrace algorithm, see the
file potrace.pdf, which is available from the potrace web site. For
information on the Potrace library API, see potracelib.pdf.
WEB SITE AND SUPPORT
The latest version of potrace is available from
http://potrace.sourceforge.net/. This site also contains a list of
frequently asked questions, as well as information on how to obtain
support.
SEE ALSO
mkbitmap(1)
COPYRIGHT
Copyright (C) 2001-2007 Peter Selinger
This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. See also
http://www.gnu.org/.