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 tool 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 output is SVG, PDF, EPS, or one of a number of other vector
16 formats. A typical use is to create vector graphics from scanned data,
17 such as company or university logos, handwritten notes, etc. The
18 resulting image is not "jaggy" like a bitmap, but smooth. It can then
19 be rendered at any resolution.
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: SVG, PDF,
28 EPS, PostScript, DXF, GeoJSON, PGM, Gimppath, and XFig. Additional
29 backends 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, GeoJSON, 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, geojson, pgm, gimp‐
87 path, xfig. Backend names can be abbreviated by a prefix
88 as long as it is unambiguous. Backend names are case
89 insensitive.
90 -s, --svg, -b svg, --backend svg
92 SVG backend. The output is a Scalable Vector Graphics
93 (SVG) file. This is a single-page, variable-sized,
94 dimension-based backend. Note that unless the -r option
95 is given, the resolution of the input bitmap is assumed
96 to be 72dpi.
97 -b pdf, --backend pdf
99 PDF backend. The output is a file in the Portable Docu‐
100 ment Format. If the input consists of multiple bitmaps,
101 they are each rendered on a separate page. This is a
102 multi-page, variable-sized, dimension-based backend.
103 -b pdfpage, --backend pdfpage
105 The PDFPage backend is like the PDF backend, except that
106 it is fixed-size like the PostScript backend.
107 -e, --eps, -b eps, --backend eps
109 EPS backend (default). The output is an encapsulated
110 PostScript file. This is a single-page, variable-sized,
111 dimension-based backend.
112 -p, --postscript, -b ps, --backend ps
114 PostScript backend. The output is a PostScript file.
115 This is a multi-page, fixed-size, dimension-based back‐
116 end. If the input consists of multiple bitmaps, they are
117 each rendered on a separate page.
118 -b dxf, --backend dxf
120 DXF backend. The output is a file in the Drawing Inter‐
121 change Format (DXF). In this backend, all Bezier curves
122 are approximated by piecewise circular arcs; this is
123 suitable for processing in CAD software or for machining
124 applications using CNC tools. This is a single-page,
125 variable-sized, pixel-based backend. The -u option has
126 no effect for this backend.
127 -b geojson, --backend geojson
129 GeoJSON backend. The output is a file in the format used
130 by some applications processing geographical data. In
131 this backend, all Bezier curves are approximated by 8
132 straight line segments. This is a single-page, variable-
133 sized, pixel-based backend. The -u option has no effect
134 for this backend.
135 -g, --pgm, -b pgm, --backend pgm
137 PGM backend. The output is a portable greymap (PGM)
138 file. It is a convenient backend for antialiasing a bit‐
139 map image. This is a multi-page, variable-sized, pixel-
140 based backend. If the input consists of more than one
141 image, the images are concatenated in the output.
142 -b gimppath, --backend gimppath
144 Gimppath backend. This backend produces output suitable
145 to be imported as a path by the GNU Image Manipulation
146 Program (Gimp) (in the Layers, Channels & Paths dialog,
147 select Paths, then right-click and select Import Path).
148 The output is actually an SVG file. The differences to
149 the SVG backend are: the --opaque option has no effect,
150 the --flat option is always on, and the dimensions are
151 pixel-based. This is a single-page, variable-sized,
152 pixel-based backend.
153 -b xfig, --backend xfig
155 XFig backend. This is a single-page, fixed-size, dimen‐
156 sion-based backend. The output is a file in the XFig
157 format. Note that XFig uses X-splines instead of Bezier
158 curves, thus it is not possible to translate the output
159 of potrace into the XFig format with absolute accuracy.
160 This backend does a reasonable approximation using two
161 control points for each Bezier curve segment. The -u
162 option has no effect for this backend, because control
163 points are always rounded to the nearest 1/1200 of an
164 inch in XFig. Curve optimization is disabled. Implies
165 --opaque.
166 Algorithm options:
168 For more detailed information on these options, see TECHNICAL DOCUMEN‐
169 TATION below.
170 -z policy, --turnpolicy policy
172 specify how to resolve ambiguities in path decomposi‐
173 tion. Must be one of black, white, right, left, minor‐
174 ity, majority, or random. Default is minority. Turn
175 policies can be abbreviated by an unambiguous prefix,
176 e.g., one can specify min instead of minority.
177 -t n, --turdsize n
179 suppress speckles of up to this many pixels.
180 -a n, --alphamax n
182 set the corner threshold parameter. The default value is
183 1. The smaller this value, the more sharp corners will
184 be produced. If this parameter is 0, then no smoothing
185 will be performed and the output is a polygon. If this
186 parameter is greater than 4/3, then all corners are sup‐
187 pressed and the output is completely smooth.
188 -n, --longcurve
190 turn off curve optimization. Normally potrace tries to
191 join adjacent Bezier curve segments when this is possi‐
192 ble. This option disables this behavior, resulting in a
193 larger file size.
194 -O n, --opttolerance n
196 set the curve optimization tolerance. The default value
197 is 0.2. Larger values allow more consecutive Bezier
198 curve segments to be joined together in a single seg‐
199 ment, at the expense of accuracy.
200 -u n, --unit n set output quantization. Coordinates in the output are
202 rounded to 1/unit pixels. The default of 10 usually
203 gives good results. For some of the debug modes, a value
204 of 100 gives more accurate output. This option has no
205 effect for the XFig backend, which always rasterizes to
206 1/1200 inch, or for the DXF backend. For the GeoJSON
207 backend, this option is only a hint; the actual rounding
208 may be more, but not less, accurate than specified.
209 -d n, --debug n
211 produce debugging output of type n. This has different
212 effects for different backends. For the PostScript/EPS
213 backends, the values n=1,2,3 illustrate the intermediate
214 stages of the potrace algorithm.
215 Scaling and placement options:
217 -P format, --pagesize format
218 for fixed-size backends, set page size. The following
219 formats can be specified: A4, A3, A5, B5, Letter, Legal,
220 Tabloid, Statement, Executive, Folio, Quarto, 10x14.
221 Format names are case insensitive. Also, an argument of
222 the form dimxdim is accepted to specify arbitrary dimen‐
223 sions. The default page size is Letter (or A4, if this
224 was configured at compile time, see COMPILE TIME CONFIG‐
225 URATION below). Page format names can be abbreviated by
226 a prefix as long as it is unambiguous. This option has
227 no effect for variable-sized backends.
228 -W dim, --width dim
230 set the width of output image (before any rotation and
231 margins). If only one of width and height is specified,
232 the other is adjusted accordingly so that the aspect
233 ratio is preserved.
234 -H dim, --height dim
236 set the height of output image. See -W for details.
237 -r n[xn], --resolution n[xn]
239 for dimension-based backends, set the resolution (in
240 dpi). One inch in the output image corresponds to this
241 many pixels in the input. Note that a larger value
242 results in a smaller output image. It is possible to
243 specify separate resolutions in the x and y directions
244 by giving an argument of the form nxn. For variable-
245 sized backends, the default resolution is 72dpi. For
246 fixed-size backends, there is no default resolution; the
247 image is by default scaled to fit on the page. This
248 option has no effect for pixel-based backends. If -W or
249 -H are specified, they take precedence.
250 -x n[xn], --scale n[xn]
252 for pixel-based backends, set the scaling factor. A
253 value greater than 1 enlarges the output, a value
254 between 0 and 1 makes the output smaller. The default is
255 1. It is possible to specify separate scaling factors
256 for the x and y directions by giving an argument of the
257 form nxn. This option has no effect for dimension-based
258 backends. If -W or -H are specified, they take prece‐
259 dence.
260 -S n, --stretch n
262 set the aspect ratio. A value greater than 1 means the
263 image will be stretched in the y direction. A value
264 between 0 and 1 means the image will be compressed in
265 the y direction.
266 -A angle, --rotate angle
268 set the rotation angle (in degrees). The output will be
269 rotated counterclockwise by this angle. This is useful
270 for compensating for images that were scanned not quite
271 upright.
272 -M dim, --margin dim
274 set all four margins. The effect and default value of
275 this option depend on the backend. For variable-sized
276 backends, the margins will simply be added around the
277 output image (or subtracted, in case of negative mar‐
278 gins). The default margin for these backends is 0. For
279 fixed-size backends, the margin settings can be used to
280 control the placement of the image on the page. If only
281 one of the left and right margin is given, the image
282 will be placed this distance from the respective edge of
283 the page, and similarly for top and bottom. If margins
284 are given on opposite sides, the image is scaled to fit
285 between these margins, unless the scaling is already
286 determined explicitly by one or more of the -W, -H, -r,
287 or -x options. By default, fixed-size backends use a
288 non-zero margin whose width depends on the page size.
289 -L dim, --leftmargin dim
291 set the left margin. See -M for details.
292 -R dim, --rightmargin dim
294 set the right margin. See -M for details.
295 -T dim, --topmargin dim
297 set the top margin. See -M for details.
298 -B dim, --bottommargin dim
300 set the bottom margin. See -M for details.
301 --tight remove whitespace around the image before scaling and
303 margins are applied. If this option is given, calcula‐
304 tions of the width, height, and margins are based on the
305 actual vector outline, rather than on the outer dimen‐
306 sions of the input pixmap, which is the default. In par‐
307 ticular, the --tight option can be used to remove any
308 existing margins from the input image. See the file
309 placement.pdf for a more detailed illustration.
310 Color options:
312 These options are only supported by certain backends. The DXF and GeoJ‐
313 SON backends do not support color.
314 -C #rrggbb, --color #rrggbb
316 set the foreground color of the output image. The
317 default is black.
318 --fillcolor #rrggbb
320 set the fill color of the output image, i.e., the color
321 of the "white" parts that are enclosed by "black" parts.
322 The default is to leave these parts transparent. Implies
323 --opaque. Please note that this option sets the back‐
324 ground color; to set the foreground color, use --color
325 instead.
326 --opaque fill in the white parts of the image opaquely, instead
328 of leaving them transparent. This only applies to inte‐
329 rior white parts, i.e., those that are enclosed inside a
330 black outline. Opaqueness is always in effect for the
331 XFig backend.
332 SVG options:
334 --group for SVG output, try to group related paths together.
335 Each path is grouped together with all paths that are
336 contained inside it, so that they can be moved around as
337 a unit with an SVG editor. This makes coloring individ‐
338 ual components slightly more cumbersome, and thus it is
339 not the default.
340 --flat for SVG output, put the entire image into a single path.
342 This makes it impossible to color the components indi‐
343 vidually, and thus it is not the default. But the
344 resulting SVG file can be more easily imported by some
345 applications such as Gimp. In fact, the Gimppath backend
346 is a variation of the SVG backend with the --flat option
347 and pixel-based scaling. The --flat option has no effect
348 if --opaque has been selected.
349 PostScript/EPS/PDF options:
351 -c, --cleartext
352 do not compress the output. This option disables the use
353 of compression filters in the PostScript and PDF output.
354 In the PostScript backend, if -c and -q are used
355 together, the resulting output can be easily read by
356 other programs or even by humans.
357 -2, --level2 use PostScript level 2 compression (default). The
359 resulting file size is ca. 40% smaller than if the -c
360 option is used.
361 -3, --level3 use PostScript level 3 compression, if available. This
363 gives slightly smaller files than using -2, but the
364 resulting files may not print on older PostScript level
365 2 printers. If support for PostScript level 3 compres‐
366 sion has been disabled at compile time, a warning mes‐
367 sage is printed and level 2 compression is used instead.
368 -q, --longcoding
370 turn off optimized numerical coding in PostScript out‐
371 put. Normally, potrace uses a very compact numerical
372 format to represent Bezier curves in PostScript, taking
373 advantage of existing redundancy in the curve parame‐
374 ters. This option disables this behavior, resulting in
375 longer, but more readable output (particularly if the -c
376 option is also used).
377 PGM options:
379 -G n, --gamma n
380 set the gamma value for anti-aliasing (default is 2.2).
381 Most computer displays do not render shades of grey lin‐
382 early, i.e., a grey value of 0.5 is not displayed as
383 being exactly half-way between black and white. The
384 gamma parameter corrects for this, and therefore leads
385 to nicer looking output. The default value of 2.2 is
386 appropriate for most normal CRT displays.
387 Frontend options:
389 -k n, --blacklevel n
390 set the threshold level for converting input images to
391 bitmaps. The potrace algorithm expects a bitmap, thus
392 all pixels of the input images are converted to black or
393 white before processing begins. Pixels whose brightness
394 is less than n are converted to black, all other pixels
395 to white. Here n is a number between 0 and 1. One case
396 is treated specially: if the input is in an indexed
397 color format with exactly 2 colors, then the blacklevel
398 is ignored and the darker of the two colors is mapped to
399 black.
400 Note: the method used by potrace for converting greymaps
402 to bitmaps is very crude; much better results can be
403 obtained if a separate program, such as mkbitmap(1), is
404 used for this purpose. In particular, mkbitmap(1), which
405 is distributed with potrace, has the ability to scale
406 and interpolate the image before thresholding, which
407 results in much better preservation of detail.
408 -i, --invert invert the input bitmap before processing.
410 Progress bar options:
412 --progress display a progress bar for each bitmap that is pro‐
413 cessed. This is useful for interactive use. The default
414 behavior is not to show any progress information.
415 --tty mode set the terminal mode for progress bar rendering. Possi‐
417 ble values are "vt100", which requires a vt100-compati‐
418 ble terminal, and "dumb", which uses only ASCII charac‐
419 ters. The default is system dependent.
420
422 Backends can be classified in several ways, which affects the available
423 command line options and their behavior:
424 Fixed-size or variable-sized:
426 For fixed-size backends, the size of the page is always the same
427 (for example Letter or A4, as specified at compile time or by the
428 -P option). By default, the image will be centered and scaled to
429 fit the page size. For variable-size backends, the size of the
430 page follows the size of the image. Currently the PostScript (PS),
431 PDFPage, and XFig backends are fixed-size, and the remaining back‐
432 ends are variable-size.
433 Dimension-based or pixel-based:
435 In dimension-based backends, distances are measured in physical
436 units such as inches or centimeters. In pixel-based backends, dis‐
437 tances are measured in pixel units. The -r option only works for
438 dimension-based backends, and the -x option only works for pixel-
439 based backends. Currently, the DXF, PGM, Gimppath, and GeoJSON
440 backends are pixel-based, and the remaining backends are dimen‐
441 sion-based. Currently, all pixel-based backends are variable-
442 sized.
443 Single-page or multi-page:
445 Single-page backends can only accept a single image. Multi-page
446 backends can accept multiple images, typically one per page of
447 output. Currently, the PostScript (PS), PDF, PDFPage, and PGM
448 backends are multi-page, and the remaining backends are single-
449 page. Note that multiple input images can be read in two ways:
450 from multiple input files (with the -o option), or from a single
451 input file that holds several concatenated images.
452
454 Certain aspects of the behavior of potrace can be configured at compile
455 time by passing the following options to the ./configure script.
456 --disable-zlib
458 compile potrace without the zlib compression library. This means
459 PostScript level 3 compression will not be available.
460 --enable-metric
462 compile potrace with centimeters as the default unit instead of
463 inches.
464 --enable-a4
466 compile potrace with A4 as the default page size.
467
469 The exit status is 0 on successful completion, 1 if the command line
470 was invalid, and 2 on any other error.
471
473 1.16
474
476 Peter Selinger <selinger at users.sourceforge.net>
477 Please see the file AUTHORS for a full list of other contributors.
479
481 For a detailed technical description of the potrace algorithm, see the
482 file potrace.pdf, which is available from the potrace web site. For
483 information on the Potrace library API, see potracelib.pdf.
484
486 The latest version of potrace is available from http://potrace.source‐
487 forge.net/. This site also contains a list of frequently asked ques‐
488 tions, as well as information on how to obtain support.
489
491 mkbitmap(1)
492
494 Copyright (C) 2001-2019 Peter Selinger
495 This program is free software; you can redistribute it and/or modify it
497 under the terms of the GNU General Public License as published by the
498 Free Software Foundation; either version 2 of the License, or (at your
499 option) any later version.
500 This program is distributed in the hope that it will be useful, but
502 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
503 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
504 Public License for more details.
505 You should have received a copy of the GNU General Public License along
507 with this program; if not, write to the Free Software Foundation, Inc.,
508 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. See also
509 http://www.gnu.org/.
510Version 1.16 September 2019 potrace(1)