1
2 POTRACE - transform bitmaps into vector graphics
3
4 * * *
5
6DESCRIPTION
7
8 Potrace is a tool for tracing a bitmap, which means, transforming a
9 bitmap into a smooth, scalable image. The input is a bitmap (PBM,
10 PGM, PPM, or BMP), and the output is one of several vector file
11 formats. A typical use is to create SVG or PDF files from scanned
12 data, such as company or university logos, handwritten notes, etc.
13 The resulting image is not "jaggy" like a bitmap, but smooth. It can
14 then be rendered at any resolution.
15
16 Potrace can currently produce the following output formats: SVG, PDF,
17 EPS, PostScript, DXF, GeoJSON, PGM (for easy antialiasing of
18 pixel-based images), Gimppath, and XFig. Additional backends might be
19 added in the future.
20
21 A separate program, mkbitmap, is also provided. This program can act
22 as a pre-processor for Potrace, applying scaling and various filters
23 to an image before converting it to a bitmap. This is useful for
24 potracing greyscale and color images.
25
26DEPENDENCIES
27
28 Potrace relies on the zlib library for PostScript level 3
29 compression. This library is pre-installed on most modern systems.
30 If not present, it can be obtained from http://www.gzip.org/zlib/.
31
32COMPILATION
33
34 For generic compilation instructions, see the file INSTALL. In
35 addition, the following compile time options (options to ./configure)
36 are supported.
37
38 --with-libpotrace install Potrace library and headers (default: no)
39 --disable-zlib disable PostScript level 3 compression
40 --enable-metric use metric units (centimeters) as default
41 --enable-a4 use a4 as the default papersize
42 --enable-dumb-tty use simplified ASCII-only progress bar
43 --with-included-getopt avoid using the system-wide getopt library
44
45 See also ./configure --help.
46
47INSTALLING
48
49 If you are installing from sources, just do "make install" as root.
50 If you are installing from a binary distribution, just copy the
51 "potrace" and "mkbitmap" binaries to a place where the operating
52 system expects them, such as /usr/local/bin. Also copy the files
53 "potrace.1" and "mkbitmap.1" to a directory where the operating
54 system looks for man pages, such as /usr/local/man/man1. For
55 instructions on installing Potrace under Windows, see the file
56 README-WIN
57
58USAGE
59
60 For more detailed usage information, see the man page.
61
62 Usage: potrace [options] [filename...]
63 General options:
64 -h, --help - print this help message and exit
65 -v, --version - print version info and exit
66 -l, --license - print license info and exit
67 File selection:
68 <filename> - an input file
69 -o, --output <filename> - write all output to this file
70 -- - end of options; 0 or more input filenames follow
71 Backend selection:
72 -b, --backend <name> - select backend by name
73 -b svg, -s, --svg - SVG backend (scalable vector graphics)
74 -b pdf - PDF backend (portable document format)
75 -b pdfpage - fixed page-size PDF backend
76 -b eps, -e, --eps - EPS backend (encapsulated PostScript) (default)
77 -b ps, -p, --postscript - PostScript backend
78 -b pgm, -g, --pgm - PGM backend (portable greymap)
79 -b dxf - DXF backend (drawing interchange format)
80 -b geojson - GeoJSON backend
81 -b gimppath - Gimppath backend (GNU Gimp)
82 -b xfig - XFig backend
83 Algorithm options:
84 -z, --turnpolicy <policy> - how to resolve ambiguities in path decomposition
85 -t, --turdsize <n> - suppress speckles of up to this size (default 2)
86 -a, --alphamax <n> - corner threshold parameter (default 1)
87 -n, --longcurve - turn off curve optimization
88 -O, --opttolerance <n> - curve optimization tolerance (default 0.2)
89 -u, --unit <n> - quantize output to 1/unit pixels (default 10)
90 -d, --debug <n> - produce debugging output of type n (n=1,2,3)
91 Scaling and placement options:
92 -P, --pagesize <format> - page size (default is letter)
93 -W, --width <dim> - width of output image
94 -H, --height <dim> - height of output image
95 -r, --resolution <n>[x<n>] - resolution (in dpi) (dimension-based backends)
96 -x, --scale <n>[x<n>] - scaling factor (pixel-based backends)
97 -S, --stretch <n> - yresolution/xresolution
98 -A, --rotate <angle> - rotate counterclockwise by angle
99 -M, --margin <dim> - margin
100 -L, --leftmargin <dim> - left margin
101 -R, --rightmargin <dim> - right margin
102 -T, --topmargin <dim> - top margin
103 -B, --bottommargin <dim> - bottom margin
104 --tight - remove whitespace around the input image
105 Color options, supported by some backends:
106 -C, --color #rrggbb - set foreground color (default black)
107 --fillcolor #rrggbb - set fill color (default transparent)
108 --opaque - make white shapes opaque
109 SVG options:
110 --group - group related paths together
111 --flat - whole image as a single path
112 Postscript/EPS/PDF options:
113 -c, --cleartext - do not compress the output
114 -2, --level2 - use postscript level 2 compression (default)
115 -3, --level3 - use postscript level 3 compression
116 -q, --longcoding - do not optimize for file size
117 PGM options:
118 -G, --gamma <n> - gamma value for anti-aliasing (default 2.2)
119 Frontend options:
120 -k, --blacklevel <n> - black/white cutoff in input file (default 0.5)
121 -i, --invert - invert bitmap
122 Progress bar options:
123 --progress - show progress bar
124 --tty <mode> - progress bar rendering: vt100 or dumb
125
126 Dimensions can have optional units, e.g. 6.5in, 15cm, 100pt.
127 Default is inches (or pixels for pgm, dxf, and gimppath backends).
128 Possible input file formats are: pnm (pbm, pgm, ppm), bmp.
129 Backends are: svg, pdf, pdfpage, eps, postscript, ps, dxf, geojson, pgm,
130 gimppath, xfig.
131
132POTRACE LIBRARY (FOR DEVELOPERS)
133
134 As of Potrace release 1.6, the Potrace core functionality has been
135 separated into a library libpotrace.a. This makes it easy to integrate
136 tracing functionality into other GPL programs. The API of the library
137 is defined in the header file potracelib.h, and is documented in
138 doc/potracelib.pdf. It is not by default installed, but can be
139 installed with the --with-libpotrace configuration option.
140
141DOCUMENTATION
142
143 Usage information is contained in the man page:
144 http://potrace.sourceforge.net/potrace.html
145
146 Many common questions are answered in the FAQ:
147 http://potrace.sourceforge.net/faq.html
148
149 Some examples are given on the following web pages:
150 http://potrace.sourceforge.net/samples.html
151 http://potrace.sourceforge.net/mkbitmap.html
152
153 The inner workings of the potrace algorithm are explained here:
154 http://potrace.sourceforge.net/potrace.pdf
155
156 The potrace library is documented here:
157 http://potrace.sourceforge.net/potracelib.pdf
158
159COPYRIGHT
160
161 Copyright (C) 2001-2019 Peter Selinger
162
163 The use of the name "Potrace" is governed by a separate policy, see
164 TRADEMARKS below.
165
166 This program is free software; you can redistribute it and/or modify
167 it under the terms of the GNU General Public License as published by
168 the Free Software Foundation; either version 2 of the License, or (at
169 your option) any later version.
170
171 This program is distributed in the hope that it will be useful, but
172 WITHOUT ANY WARRANTY; without even the implied warranty of
173 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
174 General Public License for more details.
175
176 You should have received a copy of the GNU General Public License
177 along with this program; if not, write to the Free Software Foundation,
178 Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
179 See also http://www.gnu.org/.
180
181 See the file COPYING for details.
182
183TRADEMARKS
184
185 "Potrace" is a trademark of Peter Selinger.
186
187 Policy on using the name "Potrace". If you are planning to modify
188 Potrace, including making a port of Potrace to another programming
189 language, please be aware of the following. While the source code of
190 Potrace is licensed under the GNU General Public License, the name
191 "Potrace" is my trademark, and may only be used with my permission.
192
193 In practice, I will permit the use of the name "Potrace" in
194 connection with a port of Potrace to another programming language,
195 provided that the port complies with the term of the GNU General
196 Public License and produces the same high quality vectorized output
197 as the original Potrace. Ports that are buggy or do not produce high
198 quality output are not permitted to use the name "Potrace". To ensure
199 compliance with this policy, please run your port by me before making
200 it public. Also, if you use the "Potrace" name (or any derivative,
201 such as "MyPotrace"), you must provide a name and email address where
202 I can reach you. Derivatives of Potrace that are posted anonymously
203 or where the authors cannot be reached or do not reply to email or
204 bug reports are not permitted to use the name "Potrace".
205
206 The purpose of this policy is to allow people to port Potrace to as
207 many programming languages as possible, while also ensuring that all
208 such ports are of the same high quality that has come to be
209 associated with the name "Potrace".
210
211GPG KEY
212
213 The key fingerprint of Peter Selinger's GPG key is:
214 12A2 4B3C 3790 B688 E484 7A98 A68B CC37 CA31 696A
215 This may be useful for authenticating future versions of Potrace.
216