1potrace(1) General Commands Manual potrace(1)
2
6 potrace - transform bitmaps into vector graphics.
7
9 potrace [options] [filename...]
10
12 potrace is a utility for tracing a bitmap, which means, transforming a
13 bitmap into a smooth, scalable image. The input is a bitmap, which
14 means, a pixel-based image composed of the two colors black and white
15 only. The default output is an encapsulated PostScript file (EPS). A
16 typical use is to create EPS files from scanned data, such as company
17 or university logos, handwritten notes, etc. The resulting image is not
18 "jaggy" like a bitmap, but smooth. It can then be rendered at any reso‐
19 lution.
20 potrace can read bitmaps in the following formats: PBM, PGM, PPM (col‐
22 lectively known as PNM, see pnm(5)), as well as BMP (Windows and OS/2
23 bitmap formats). The input image should only use the two colors black
24 and white. If other pixel values appear in the input, they will be con‐
25 verted to black and white using a simple threshold method.
26 potrace can currently produce the following output formats: EPS, Post‐
28 Script, PDF, SVG, DXF, PGM, Gimppath, and XFig. Additional backends
29 might be added in the future.
30
32 The following options are supported. Dimensions (arguments of type dim)
33 can have optional units, e.g. 6.5in, 15cm, 100pt. The default unit is
34 inches (or centimeters, if this was configured at compile time, see
35 COMPILE TIME CONFIGURATION below). For pixel-based output formats such
36 as PGM, DXF, and Gimppath, the default unit is pixels.
37 General options:
39 -h, --help print help message and exit.
40 -v, --version print version info and exit. This also shows the
42 defaults that were compiled into this version of
43 potrace.
44 -l, --license print license info and exit.
46 Input/output options:
48 filename Each file can hold an input image, or multiple concate‐
49 nated input images. If filename arguments are given,
50 then potrace will by default create one output file for
51 each input filename given. The name of the output file
52 is obtained from the input filename by changing its suf‐
53 fix according to the chosen backend. If changing the
54 suffix is impossible because the names of the input and
55 output files would be identical, then the output file‐
56 name is created by adding the "-out" suffix to the name
57 of the input file. If no filename arguments are given,
58 then potrace acts as a filter, reading from standard
59 input and writing to standard output. A filename of "-"
60 may be given to specify reading from standard input.
61 -o filename, --output filename
63 write output to this file. All output is directed to the
64 specified file. If this option is used, then multiple
65 input filenames are only allowed for multi-page backends
66 (see BACKEND TYPES below). In this case, each input file
67 may contain one or more bitmaps, and all the bitmaps
68 from all the input files are processed and the output
69 concatenated into a single file. A filename of "-" may
70 be given to specify writing to standard output.
71 -- End of options. Any remaining arguments are interpreted
73 as filenames. This also disables filter mode, even if no
74 filenames are given. This is useful for shell scripts,
75 because potrace -- $FILENAMES will behave correctly even
76 for an empty list of filenames. However, -- with an
77 empty list of filenames is not permitted in conjunction
78 with the -o option, because this would generate a docu‐
79 ment of zero pages, which none of the backends permit.
80 Backend selection:
82 For general information, see also BACKEND TYPES below.
83 -b name, --backend name
85 Select backend by name, where name is one of eps, post‐
86 script, ps, pdf, pdfpage, svg, dxf, pgm, gimppath, xfig.
87 Backend names can be abbreviated by a prefix as long as
88 it is unambiguous. Backend names are case insensitive.
89 -e, --eps, -b eps, --backend eps
91 EPS backend (default). The output is an encapsulated
92 PostScript file. This is a single-page, variable-sized
93 backend.
94 -p, --postscript, -b ps, --backend ps
96 PostScript backend. The output is a PostScript file.
97 This is a multi-page, fixed-size backend. If the input
98 consists of multiple bitmaps, they are each rendered on
99 a separate page.
100 -b pdf, --backend pdf
102 PDF backend. The output is a file in the Portable Docu‐
103 ment Format. If the input consists of multiple bitmaps,
104 they are each rendered on a separate page. This is a
105 multi-page, variable-sized, backend.
106 -b pdfpage, --backend pdfpage
108 The PDFPage backend is like the PDF backend, except that
109 it is fixed-size like the PostScript backend.
110 -s, --svg, -b svg, --backend svg
112 SVG backend. The output is a Scalable Vector Graphics
113 (SVG) file. This is a single-page, variable-sized back‐
114 end.
115 -b dxf, --backend dxf
117 DXF backend. The output is a file in the Drawing Inter‐
118 change Format (DXF). In this backend, all Bezier curves
119 are approximated by piecewise circular arcs; this is
120 suitable for processing in CAD software or for machining
121 applications using CNC tools. This is a single-page,
122 variable-sized, pixel-based backend. The -u option has
123 no effect for this backend.
124 -g, --pgm, -b pgm, --backend pgm
126 PGM backend. The output is a portable greymap (PGM)
127 file. It is a convenient backend for antialiasing a bit‐
128 map image. This is a multi-page, variable-sized, pixel-
129 based backend. If the input consists of more than one
130 image, the images are concatenated in the output.
131 -b gimppath, --backend gimppath
133 Gimppath backend. This backend produces output suitable
134 to be imported as a path by the GNU Image Manipulation
135 Program (Gimp) (in the Layers, Channels & Paths dialog,
136 select Paths, then right-click and select Import Path).
137 The output is actually an SVG file. The differences to
138 the SVG backend are: the --opaque option has no effect,
139 the --flat option is always on, and the dimensions are
140 pixel-based. This is a single-page, variable-sized,
141 pixel-based backend.
142 -b xfig, --backend xfig
144 XFig backend. The output is a file in the XFig format.
145 Note that XFig uses X-splines instead of Bezier curves,
146 thus it is not possible to translate the output of
147 potrace into the XFig format with absolute accuracy.
148 This backend does a reasonable approximation using two
149 control points for each Bezier curve segment. The -u
150 option has no effect for this backend, because control
151 points are always rounded to the nearest 1/1200 of an
152 inch in XFig. Curve optimization is disabled. Implies
153 --opaque.
154 Algorithm options:
156 For more detailed information on these options, see TECHNICAL DOCUMEN‐
157 TATION below.
158 -z policy, --turnpolicy policy
160 specify how to resolve ambiguities in path decomposi‐
161 tion. Must be one of black, white, right, left, minor‐
162 ity, majority, or random. Default is minority. Turn
163 policies can be abbreviated by an unambigous prefix,
164 e.g., one can specify min instead of minority.
165 -t n, --turdsize n
167 suppress speckles of up to this many pixels.
168 -a n, --alphamax n
170 set the corner threshold parameter. The default value is
171 1. The smaller this value, the more sharp corners will
172 be produced. If this parameter is negative, then no
173 smoothing will be performed and the output is a polygon.
174 The largest useful value is 4/3 or 1.334, which sup‐
175 presses all corners and leads to completely smooth out‐
176 put.
177 -n, --longcurve
179 turn off curve optimization. Normally potrace tries to
180 join adjacent Bezier curve segments when this is possi‐
181 ble. This option disables this behavior, resulting in a
182 larger file size.
183 -O n, --opttolerance n
185 set the curve optimization tolerance. The default value
186 is 0.2. Larger values allow more consecutive Bezier
187 curve segments to be joined together in a single seg‐
188 ment, at the expense of accuracy.
189 -u n, --unit n set output quantization. Coordinates in the output are
191 rounded to 1/unit pixels. The default of 10 usually
192 gives good results. For some of the debug modes, a value
193 of 100 gives more accurate output. This option has no
194 effect for the XFig backend, which always rasterizes to
195 1/1200 inch, or for the DXF backend.
196 -d n, --debug n
198 produce debugging output of type n. This has different
199 effects for different backends. For the PostScript/EPS
200 backends, the values n=1,2,3 illustrate the intermediate
201 stages of the potrace algorithm.
202 Scaling and placement options:
204 -P format, --pagesize format
205 for fixed-size backends, set page size. The following
206 formats can be specified: A4, A3, A5, B5, Letter, Legal,
207 Tabloid, Statement, Executive, Folio, Quarto, 10x14.
208 Format names are case insensitive. Also, an argument of
209 the form dimxdim is accepted to specify arbitrary dimen‐
210 sions. The default page size is Letter (or A4, if this
211 was configured at compile time, see COMPILE TIME CONFIG‐
212 URATION below). Page format names can be abbreviated by
213 a prefix as long as it is unambiguous. This option has
214 no effect for variable-sized backends.
215 -W dim, --width dim
217 set the width of output image (before any rotation and
218 margins). If only one of width and height is specified,
219 the other is adjusted accordingly so that the aspect
220 ratio is preserved.
221 -H dim, --height dim
223 set the height of output image. See -W for details.
224 -r n[xn], --resolution n[xn]
226 for dimension-based backends, set the resolution (in
227 dpi). One inch in the output image corresponds to this
228 many pixels in the input. Note that a larger value
229 results in a smaller output image. It is possible to
230 specify separate resolutions in the x and y directions
231 by giving an argument of the form nxn. For variable-
232 sized backends, the default resolution is 72dpi. For
233 fixed-size backends, there is no default resolution; the
234 image is by default scaled to fit on the page. This
235 option has no effect for pixel-based backends. If -W or
236 -H are specified, they take precedence.
237 -x n[xn], --scale n[xn]
239 for pixel-based backends, set the scaling factor. A
240 value greater than 1 enlarges the output, a value
241 between 0 and 1 makes the output smaller. The default is
242 1. It is possible to specify separate scaling factors
243 for the x and y directions by giving an argument of the
244 form nxn. This option has no effect for dimension-based
245 backends. If -W or -H are specified, they take prece‐
246 dence.
247 -S n, --stretch n
249 set the aspect ratio. A value greater than 1 means the
250 image will be stretched in the y direction. A value
251 between 0 and 1 means the image will be compressed in
252 the y direction.
253 -A angle, --rotate angle
255 set the rotation angle (in degrees). The output will be
256 rotated counterclockwise by this angle. This is useful
257 for compensating for images that were scanned not quite
258 upright.
259 -M dim, --margin dim
261 set all four margins. The effect and default value of
262 this option depend on the backend. For variable-sized
263 backends, the margins will simply be added around the
264 output image (or subtracted, in case of negative mar‐
265 gins). The default margin for these backends is 0. For
266 fixed-size backends, the margin settings can be used to
267 control the placement of the image on the page. If only
268 one of the left and right margin is given, the image
269 will be placed this distance from the respective edge of
270 the page, and similarly for top and bottom. If margins
271 are given on opposite sides, the image is scaled to fit
272 between these margins, unless the scaling is already
273 determined explicitly by one or more of the -W, -H, -r,
274 or -x options. By default, fixed-size backends use a
275 non-zero margin whose width depends on the page size.
276 -L dim, --leftmargin dim
278 set the left margin. See -M for details.
279 -R dim, --rightmargin dim
281 set the right margin. See -M for details.
282 -T dim, --topmargin dim
284 set the top margin. See -M for details.
285 -B dim, --bottommargin dim
287 set the bottom margin. See -M for details.
288 --tight remove whitespace around the image before scaling and
290 margins are applied. If this option is given, calcula‐
291 tions of the width, height, and margins are based on the
292 actual vector outline, rather than on the outer dimen‐
293 sions of the input pixmap, which is the default. In par‐
294 ticular, the --tight option can be used to remove any
295 existing margins from the input image. See the file
296 placement.pdf for a more detailed illustration.
297 Color options:
299 These options are only supported by certain backends. The DXF backend
300 does not support color.
301 -C #rrggbb, --color #rrggbb
303 set the foreground color of the output image. The
304 default is black.
305 --fillcolor #rrggbb
307 set the fill color of the output image, i.e., the color
308 of the "white" parts. The default is to leave these
309 parts transparent. Implies --opaque.
310 --opaque fill in the white parts of the image opaquely, instead
312 of leaving them transparent. This only applies to inte‐
313 rior white parts, i.e., those that are enclosed inside a
314 black outline. Opaqueness is always in effect for the
315 XFig backend.
316 SVG options:
318 --group for SVG output, try to group related paths together.
319 Each path is grouped together with all paths that are
320 contained inside it, so that they can be moved around as
321 a unit with an SVG editor. This makes coloring individ‐
322 ual components slightly more cumbersome, and thus it is
323 not the default.
324 --flat for SVG output, put the entire image into a single path.
326 This makes it impossible to color the components indi‐
327 vidually, and thus it is not the default. But the
328 resulting SVG file can be more easily imported by some
329 applications such as Gimp. In fact, the Gimppath backend
330 is a variation of the SVG backend with the --flat option
331 and pixel-based scaling. The --flat option has no effect
332 if --opaque has been selected.
333 PostScript/EPS/PDF options:
335 -c, --cleartext
336 do not compress the output. This option disables the use
337 of compression filters in the PostScript and PDF output.
338 In the PostScript backend, if -c and -q are used
339 together, the resulting output can be easily read by
340 other programs or even by humans.
341 -2, --level2 use PostScript level 2 compression (default). The
343 resulting file size is ca. 40% smaller than if the -c
344 option is used.
345 -3, --level3 use PostScript level 3 compression, if available. This
347 gives slightly smaller files than using -2, but the
348 resulting files may not print on older PostScript level
349 2 printers. If support for PostScript level 3 compres‐
350 sion has been disabled at compile time, a warning mes‐
351 sage is printed and level 2 compression is used instead.
352 -q, --longcoding
354 turn off optimized numerical coding in PostScript out‐
355 put. Normally, potrace uses a very compact numerical
356 format to represent Bezier curves in PostScript, taking
357 advantage of existing redundancy in the curve parame‐
358 ters. This option disables this behavior, resulting in
359 longer, but more readable output (particularly if the -c
360 option is also used).
361 PGM options:
363 -G n, --gamma n
364 set the gamma value for anti-aliasing (default is 2.2).
365 Most computer displays do not render shades of grey lin‐
366 early, i.e., a grey value of 0.5 is not displayed as
367 being exactly half-way between black and white. The
368 gamma parameter corrects for this, and therefore leads
369 to nicer looking output. The default value of 2.2 is
370 appropriate for most normal CRT displays.
371 Frontend options:
373 -k n, --blacklevel n
374 set the threshold level for converting input images to
375 bitmaps. The potrace algorithm expects a bitmap, thus
376 all pixels of the input images are converted to black or
377 white before processing begins. Pixels whose brightness
378 is less than n are converted to black, all other pixels
379 to white. Here n is a number between 0 and 1. One case
380 is treated specially: if the input is in an indexed
381 color format with exactly 2 colors, then the blacklevel
382 is ignored and the darker of the two colors is mapped to
383 black.
384 Note: the method used by potrace for converting greymaps
386 to bitmaps is very crude; much better results can be
387 obtained if a separate program, such as mkbitmap(1), is
388 used for this purpose. In particular, mkbitmap(1), which
389 is distributed with potrace, has the ability to scale
390 and interpolate the image before thresholding, which
391 results in much better preservation of detail.
392 -i, --invert invert the input bitmap before processing.
394 Progress bar options:
396 --progress display a progress bar for each bitmap that is pro‐
397 cessed. This is useful for interactive use. The default
398 behavior is not to show any progress information.
399 --tty mode set the terminal mode for progress bar rendering. Possi‐
401 ble values are "vt100", which requires a vt100-compati‐
402 ble terminal, and "dumb", which uses only ASCII charac‐
403 ters. The default is system dependent.
404
406 Backends can be classified in several ways, which affects the available
407 command line options and their behavior:
408 Fixed-size or variable-sized:
410 For fixed-size backends, the size of the page is always the same
411 (for example Letter or A4, as specified at compile time or by the
412 -P option). By default, the image will be centered and scaled to
413 fit the page size. For variable-size backends, the size of the
414 page follows the size of the image. Currently the PostScript (PS),
415 PDFPage, and XFig backends are fixed-size, and the remaining back‐
416 ends are variable-size.
417 Dimension-based or pixel-based:
419 In dimension-based backends, distances are measured in physical
420 units such as inches or centimeters. In pixel-based backends, dis‐
421 tances are measured in pixel units. The -r option only works for
422 dimension-based backends, and the -x option only works for pixel-
423 based backends. Currently, the DXF, PGM, and Gimppath backends are
424 pixel-based, and the remaining backends are dimension-based. Cur‐
425 rently, all pixel-based backends are variable-sized.
426 Single-page or multi-page:
428 Single-page backends can only accept a single image. Multi-page
429 backends can accept multiple images, typically one per page of
430 output. Currently, the PostScript (PS), PDF, PDFPage, and PGM
431 backends are multi-page, and the remaining backends are single-
432 page. Note that multiple input images can be read in two ways:
433 from multiple input files (with the -o option), or from a single
434 input file that holds several concatenated images.
435
437 Certain aspects of the behavior of potrace can be configured at compile
438 time by passing the following options to the ./configure script.
439 --disable-zlib
441 compile potrace without the zlib compression library. This means
442 PostScript level 3 compression will not be available.
443 --enable-metric
445 compile potrace with centimeters as the default unit instead of
446 inches.
447 --enable-a4
449 compile potrace with A4 as the default page size.
450
452 The exit status is 0 on successful completion, 1 if the command line
453 was invalid, and 2 on any other error.
454
456 1.10
457
459 Peter Selinger <selinger at users.sourceforge.net>
460
462 For a detailed technical description of the potrace algorithm, see the
463 file potrace.pdf, which is available from the potrace web site. For
464 information on the Potrace library API, see potracelib.pdf.
465
467 The latest version of potrace is available from http://potrace.source‐
468 forge.net/. This site also contains a list of frequently asked ques‐
469 tions, as well as information on how to obtain support.
470
472 mkbitmap(1)
473
475 Copyright (C) 2001-2011 Peter Selinger
476 This program is free software; you can redistribute it and/or modify it
478 under the terms of the GNU General Public License as published by the
479 Free Software Foundation; either version 2 of the License, or (at your
480 option) any later version.
481 This program is distributed in the hope that it will be useful, but
483 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
484 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
485 Public License for more details.
486 You should have received a copy of the GNU General Public License along
488 with this program; if not, write to the Free Software Foundation, Inc.,
489 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. See also
490 http://www.gnu.org/.
491Version 1.10 August 2011 potrace(1)