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 default output is one of several vector
11 file formats. A typical use is to create EPS 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: EPS,
17 PostScript, PDF, SVG (scalable vector graphics), DXF, GeoJSON, PGM
18 (for easy antialiasing of pixel-based images), Gimppath, and
19 XFig. Additional backends might be 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
44 See also ./configure --help.
45
46INSTALLING
47
48 If you are installing from sources, just do "make install" as root.
49 If you are installing from a binary distribution, just copy the
50 "potrace" and "mkbitmap" binaries to a place where the operating
51 system expects them, such as /usr/local/bin. Also copy the files
52 "potrace.1" and "mkbitmap.1" to a directory where the operating
53 system looks for man pages, such as /usr/local/man/man1. For
54 instructions on installing Potrace under Windows, see the file
55 README-WIN
56
57USAGE
58
59 For more detailed usage information, see the man page.
60
61 Usage: potrace [options] [filename...]
62 General options:
63 -h, --help - print this help message and exit
64 -v, --version - print version info and exit
65 -l, --license - print license info and exit
66 File selection:
67 <filename> - an input file
68 -o, --output <filename> - write all output to this file
69 -- - end of options; 0 or more input filenames follow
70 Backend selection:
71 -b, --backend <name> - select backend by name
72 -e, --eps - EPS backend (encapsulated PostScript) (default)
73 -p, --postscript - PostScript backend
74 -s, --svg - SVG backend (scalable vector graphics)
75 -g, --pgm - PGM backend (portable greymap)
76 -b pdf - PDF backend (portable document format)
77 -b pdfpage - fixed page-size PDF backend
78 -b dxf - DXF backend (drawing interchange format)
79 -b geojson - GeoJSON backend
80 -b gimppath - Gimppath backend (GNU Gimp)
81 -b xfig - XFig backend
82 Algorithm options:
83 -z, --turnpolicy <policy> - how to resolve ambiguities in path decomposition
84 -t, --turdsize <n> - suppress speckles of up to this size (default 2)
85 -a, --alphamax <n> - corner threshold parameter (default 1)
86 -n, --longcurve - turn off curve optimization
87 -O, --opttolerance <n> - curve optimization tolerance (default 0.2)
88 -u, --unit <n> - quantize output to 1/unit pixels (default 10)
89 -d, --debug <n> - produce debugging output of type n (n=1,2,3)
90 Scaling and placement options:
91 -P, --pagesize <format> - page size (default is letter)
92 -W, --width <dim> - width of output image
93 -H, --height <dim> - height of output image
94 -r, --resolution <n>[x<n>] - resolution (in dpi) (dimension-based backends)
95 -x, --scale <n>[x<n>] - scaling factor (pixel-based backends)
96 -S, --stretch <n> - yresolution/xresolution
97 -A, --rotate <angle> - rotate counterclockwise by angle
98 -M, --margin <dim> - margin
99 -L, --leftmargin <dim> - left margin
100 -R, --rightmargin <dim> - right margin
101 -T, --topmargin <dim> - top margin
102 -B, --bottommargin <dim> - bottom margin
103 --tight - remove whitespace around the input image
104 Color options, supported by some backends:
105 -C, --color #rrggbb - set foreground color (default black)
106 --fillcolor #rrggbb - set fill color (default transparent)
107 --opaque - make white shapes opaque
108 SVG options:
109 --group - group related paths together
110 --flat - whole image as a single path
111 Postscript/EPS/PDF options:
112 -c, --cleartext - do not compress the output
113 -2, --level2 - use postscript level 2 compression (default)
114 -3, --level3 - use postscript level 3 compression
115 -q, --longcoding - do not optimize for file size
116 PGM options:
117 -G, --gamma <n> - gamma value for anti-aliasing (default 2.2)
118 Frontend options:
119 -k, --blacklevel <n> - black/white cutoff in input file (default 0.5)
120 -i, --invert - invert bitmap
121 Progress bar options:
122 --progress - show progress bar
123 --tty <mode> - progress bar rendering: vt100 or dumb
124
125 Dimensions can have optional units, e.g. 6.5in, 15cm, 100pt.
126 Default is inches (or pixels for pgm, dxf, and gimppath backends).
127 Possible input file formats are: pnm (pbm, pgm, ppm), bmp.
128 Backends are: eps, postscript, ps, pdf, pdfpage, svg, dxf, geojson, pgm,
129 gimppath, xfig.
130
131POTRACE LIBRARY (FOR DEVELOPERS)
132
133 As of Potrace release 1.6, the Potrace core functionality has been
134 separated into a library libpotrace.a. This makes it easy to integrate
135 tracing functionality into other GPL programs. The API of the library
136 is defined in the header file potracelib.h, and is documented in
137 doc/potracelib.pdf. It is not by default installed, but can be
138 installed with the --with-libpotrace configuration option.
139
140DOCUMENTATION
141
142 Usage information is contained in the man page:
143 http://potrace.sourceforge.net/potrace.html
144
145 Many common questions are answered in the FAQ:
146 http://potrace.sourceforge.net/faq.html
147
148 Some examples are given on the following web pages:
149 http://potrace.sourceforge.net/samples.html
150 http://potrace.sourceforge.net/mkbitmap.html
151
152 The inner workings of the potrace algorithm are explained here:
153 http://potrace.sourceforge.net/potrace.pdf
154
155 The potrace library is documented here:
156 http://potrace.sourceforge.net/potracelib.pdf
157
158COPYRIGHT
159
160 Copyright (C) 2001-2017 Peter Selinger
161
162 This program is free software; you can redistribute it and/or modify
163 it under the terms of the GNU General Public License as published by
164 the Free Software Foundation; either version 2 of the License, or (at
165 your option) any later version.
166
167 This program is distributed in the hope that it will be useful, but
168 WITHOUT ANY WARRANTY; without even the implied warranty of
169 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
170 General Public License for more details.
171
172 You should have received a copy of the GNU General Public License
173 along with this program; if not, write to the Free Software Foundation,
174 Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
175 See also http://www.gnu.org/.
176
177 See the file COPYING for details.
178
179GPG KEY
180
181 The key fingerprint of Peter Selinger's GPG key is:
182 12A2 4B3C 3790 B688 E484 7A98 A68B CC37 CA31 696A
183 This may be useful for authenticating future versions of Potrace.
184
1
2 POTRACE - transform bitmaps into vector graphics
3
4 README for Windows
5 _________________________________________________________________
6
7This file contains instructions specific to the pre-compiled Windows
8distribution of Potrace. Please see the general README file and the
9man page for general information on usage, how to compile Potrace,
10etc.
11
12
13INSTALLATION for Windows 95/98/2000/NT/XP/Vista/7/whatever:
14===========================================================
15
16Download the file potrace-XXX.win32.zip (or potrace-XXX.win64.zip if
17you want the 64-bit version). Unpack it with your favorite unzipping
18tool, such as unzip, 7-Zip, WinZip, or just right-clicking on the
19file.
20
21If you have "tar" and "gunzip" installed, you may also get the tar.gz
22file instead of the zip file.
23
24The distribution includes the executable programs potrace.exe and
25mkbitmap.exe. You need to move these files to a place where Windows
26looks for programs, for example C:\WINDOWS. Alternatively, you can
27amend your PATH environment variable, by adding something like the
28following line to C:\AUTOEXEC.BAT:
29
30 PATH=%PATH%;C:\DIRECTORY\WHERE\FILES\ARE
31
32Note: as of version 1.6, the Potrace Windows distribution is built
33using MinGW and not Cygwin. It is no longer necessary to install a
34separate DLL file with Potrace.
35
36
37RUNNING:
38========
39
40For non-Windows specific usage information, see the file README.
41
42Potrace on Windows runs in much the same way as under Linux and other
43Unix-like operating systems. You must run Potrace from the command
44line (also known as the MSDOS Prompt). File names can be given in Unix
45style or Windows style, thus the following will both work:
46
47 potrace h:/data/file.txt
48 potrace h:\data\file.txt
49
50Wildcards can also be used, as in:
51
52 potrace h:\data\*.*
53 potrace h:/data/*.*
54
55Earlier versions of Potrace had some problems when wildcards and
56backslashes were mixed; these problems seem to have been solved by the
57switch from Cygwin to MinGW.
58
59Another problem that some users have reported is that the generated
60".ps" and ".eps" were not executable under Windows (i.e., one could
61not simply display these files by typing their name on the MSDOS
62Prompt, as should normally be the case if a default application for
63PostScript files has been configured). I was never able to replicate
64this problem, but I believe that it has also been solved by the switch
65to MinGW.
66