Ubuntu Manpage: potrace - transform bitmaps into vector graphics.

NAME

       potrace - transform bitmaps into vector graphics.

SYNOPSIS

       potrace [options] [filename...]

DESCRIPTION

       potrace  is a tool 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 output is SVG, PDF, EPS, or one of a number of other
       vector formats. A typical use is to create vector graphics  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: SVG, PDF, EPS, PostScript,
       DXF, GeoJSON, PGM, Gimppath, and XFig.  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, DXF, GeoJSON, and Gimppath, the default unit is pixels.

General options:
-h, --help print help message and exit.

-v, --version print version info and exit. This also shows the defaults that were
compiled into this version of potrace.

-l, --license print license info and exit.

Input/output options:
filename Each file can hold an input image, or multiple concatenated input images.
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 only allowed for
multi-page backends (see BACKEND TYPES below). 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.

-- End of options. Any remaining arguments are interpreted as filenames. This
also disables filter mode, even if no filenames are given. This is useful
for shell scripts, because potrace -- $FILENAMES will behave correctly even
for an empty list of filenames. However, -- with an empty list of filenames
is not permitted in conjunction with the -o option, because this would
generate a document of zero pages, which none of the backends permit.

Backend selection:
For general information, see also BACKEND TYPES below.

-b name, --backend name
Select backend by name, where name is one of eps, postscript, ps, pdf,
pdfpage, svg, dxf, geojson, pgm, gimppath, xfig. Backend names can be
abbreviated by a prefix as long as it is unambiguous. Backend names are
case insensitive.

-s, --svg, -b svg, --backend svg
SVG backend. The output is a Scalable Vector Graphics (SVG) file. This is
a single-page, variable-sized, dimension-based backend. Note that unless
the -r option is given, the resolution of the input bitmap is assumed to be
72dpi.

-b pdf, --backend pdf
PDF backend. The output is a file in the Portable Document Format. If the
input consists of multiple bitmaps, they are each rendered on a separate
page. This is a multi-page, variable-sized, dimension-based backend.

-b pdfpage, --backend pdfpage
The PDFPage backend is like the PDF backend, except that it is fixed-size
like the PostScript backend.

-e, --eps, -b eps, --backend eps
EPS backend (default). The output is an encapsulated PostScript file. This
is a single-page, variable-sized, dimension-based backend.

-p, --postscript, -b ps, --backend ps
PostScript backend. The output is a PostScript file. This is a multi-page,
fixed-size, dimension-based backend. If the input consists of multiple
bitmaps, they are each rendered on a separate page.

-b dxf, --backend dxf
DXF backend. The output is a file in the Drawing Interchange Format (DXF).
In this backend, all Bezier curves are approximated by piecewise circular
arcs; this is suitable for processing in CAD software or for machining
applications using CNC tools. This is a single-page, variable-sized, pixel-
based backend. The -u option has no effect for this backend.

-b geojson, --backend geojson
GeoJSON backend. The output is a file in the format used by some
applications processing geographical data. In this backend, all Bezier
curves are approximated by 8 straight line segments. This is a single-page,
variable-sized, pixel-based backend. The -u option has no effect for this
backend.

-g, --pgm, -b pgm, --backend pgm
PGM backend. The output is a portable greymap (PGM) file. It is a
convenient backend for antialiasing a bitmap image. This is a multi-page,
variable-sized, pixel-based backend. If the input consists of more than one
image, the images are concatenated in the output.

-b gimppath, --backend gimppath
Gimppath backend. This backend produces output suitable to be imported as a
path by the GNU Image Manipulation Program (Gimp) (in the Layers, Channels
& Paths dialog, select Paths, then right-click and select Import Path). The
output is actually an SVG file. The differences to the SVG backend are: the
--opaque option has no effect, the --flat option is always on, and the
dimensions are pixel-based. This is a single-page, variable-sized, pixel-
based backend.

-b xfig, --backend xfig
XFig backend. This is a single-page, fixed-size, dimension-based backend.
The output is a file in the XFig format. 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. The -u option has no effect for this backend, because control
points are always rounded to the nearest 1/1200 of an inch in XFig. Curve
optimization is disabled. Implies --opaque.

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 unambiguous 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
0, then no smoothing will be performed and the output is a polygon. If this
parameter is greater than 4/3, then all corners are suppressed and the
output is completely smooth.

-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. This option has no effect
for the XFig backend, which always rasterizes to 1/1200 inch, or for the
DXF backend. For the GeoJSON backend, this option is only a hint; the
actual rounding may be more, but not less, accurate than specified.

-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:
-P format, --pagesize format
for fixed-size backends, set page size. The following formats can be
specified: A4, A3, A5, B5, Letter, Legal, Tabloid, Statement, Executive,
Folio, Quarto, 10x14. Format names are case insensitive. 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 a prefix as long as it is unambiguous. This option has no
effect for variable-sized backends.

-W dim, --width dim
set the width of output image (before any rotation and margins). 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]
for dimension-based backends, set the resolution (in dpi). One inch in the
output image corresponds to this many pixels in the input. Note that a
larger value results in a smaller output image. It is possible to specify
separate resolutions in the x and y directions by giving an argument of the
form nxn. For variable-sized backends, the default resolution is 72dpi. For
fixed-size backends, there is no default resolution; the image is by
default scaled to fit on the page. This option has no effect for pixel-
based backends. If -W or -H are specified, they take precedence.

-x n[xn], --scale n[xn]
for pixel-based backends, set the scaling factor. A value greater than 1
enlarges the output, a value between 0 and 1 makes the output smaller. The
default is 1. It is possible to specify separate scaling factors for the x
and y directions by giving an argument of the form nxn. This option has no
effect for dimension-based backends. If -W or -H are specified, they take
precedence.

-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 compressed in the y 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 and default value of this option depend on
the backend. For variable-sized backends, the margins will simply be added
around the output image (or subtracted, in case of negative margins). The
default margin for these backends is 0. For fixed-size backends, the
margin 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, unless the scaling is already
determined explicitly by one or more of the -W, -H, -r, or -x options. By
default, fixed-size backends use a non-zero margin whose width depends on
the page size.

-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.

--tight remove whitespace around the image before scaling and margins are applied.
If this option is given, calculations of the width, height, and margins are
based on the actual vector outline, rather than on the outer dimensions of
the input pixmap, which is the default. In particular, the --tight option
can be used to remove any existing margins from the input image. See the
file placement.pdf for a more detailed illustration.

Color options:
These options are only supported by certain backends. The DXF and GeoJSON backends do not
support color.

-C #rrggbb, --color #rrggbb
set the foreground color of the output image. The default is black.

--fillcolor #rrggbb
set the fill color of the output image, i.e., the color of the "white"
parts that are enclosed by "black" parts. The default is to leave these
parts transparent. Implies --opaque. Please note that this option sets the
background color; to set the foreground color, use --color instead.

--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 that
are enclosed inside a black outline. Opaqueness is always in effect for the
XFig backend.

SVG options:
--group for SVG output, try to group related paths together. 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.

--flat for SVG output, put the entire image into a single path. This makes it
impossible to color the components individually, and thus it is not the
default. But the resulting SVG file can be more easily imported by some
applications such as Gimp. In fact, the Gimppath backend is a variation of
the SVG backend with the --flat option and pixel-based scaling. The --flat
option has no effect if --opaque has been selected.

PostScript/EPS/PDF options:
-c, --cleartext
do not compress the output. This option disables the use of compression
filters in the PostScript and PDF output. In the PostScript backend, if -c
and -q are used together, 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 in PostScript output. Normally, potrace
uses a very compact numerical format to represent Bezier curves in
PostScript, taking advantage of existing 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.

Progress bar options:
--progress display a progress bar for each bitmap that is processed. This is useful
for interactive use. The default behavior is not to show any progress
information.

--tty mode set the terminal mode for progress bar rendering. Possible values are
"vt100", which requires a vt100-compatible terminal, and "dumb", which uses
only ASCII characters. The default is system dependent.

BACKEND TYPES

Backends can be classified in several ways, which affects the available command line
options and their behavior:

Fixed-size or variable-sized:
For fixed-size backends, the size of the page is always the same (for example Letter
or A4, as specified at compile time or by the -P option). By default, the image will
be centered and scaled to fit the page size. For variable-size backends, the size of
the page follows the size of the image. Currently the PostScript (PS), PDFPage, and
XFig backends are fixed-size, and the remaining backends are variable-size.

Dimension-based or pixel-based:
In dimension-based backends, distances are measured in physical units such as inches
or centimeters. In pixel-based backends, distances are measured in pixel units. The
-r option only works for dimension-based backends, and the -x option only works for
pixel-based backends. Currently, the DXF, PGM, Gimppath, and GeoJSON backends are
pixel-based, and the remaining backends are dimension-based. Currently, all pixel-
based backends are variable-sized.

Single-page or multi-page:
Single-page backends can only accept a single image. Multi-page backends can accept
multiple images, typically one per page of output. Currently, the PostScript (PS),
PDF, PDFPage, and PGM backends are multi-page, and the remaining backends are single-
page. Note that multiple input images can be read in two ways: from multiple input
files (with the -o option), or from a single input file that holds several
concatenated images.

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.16

AUTHOR

       Peter Selinger <selinger at users.sourceforge.net>

       Please see the file AUTHORS for a full list of other contributors.

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.

COPYRIGHT

       Copyright (C) 2001-2019 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.,  51  Franklin  Street,  Fifth  Floor,
       Boston, MA 02110-1301, USA.  See also http://www.gnu.org/.