1potrace(1)                  General Commands Manual                 potrace(1)
2
3
4

NAME

6       potrace - transform bitmaps into vector graphics.
7

SYNOPSIS

9       potrace [options] [filename...]
10

DESCRIPTION

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
21       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
27       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

OPTIONS

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
38   General options:
39       -h, --help     print help message and exit.
40
41       -v, --version  print  version  info  and  exit.  This  also  shows  the
42                      defaults   that  were  compiled  into  this  version  of
43                      potrace.
44
45       -l, --license  print license info and exit.
46
47   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
62       -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
72       --             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
81   Backend selection:
82       For general information, see also BACKEND TYPES below.
83
84       -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
91       -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
98       -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
104       -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
108       -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
113       -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
119       -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
128       -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
136       -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
143       -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
154       -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
167   Algorithm options:
168       For more detailed information on these options, see TECHNICAL  DOCUMEN‐
169       TATION below.
170
171       -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
178       -t n, --turdsize n
179                      suppress speckles of up to this many pixels.
180
181       -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
189       -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
195       -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
201       -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
210       -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
216   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
229       -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
235       -H dim, --height dim
236                      set the height of output image. See -W for details.
237
238       -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
251       -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
261       -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
267       -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
273       -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
290       -L dim, --leftmargin dim
291                      set the left margin. See -M for details.
292
293       -R dim, --rightmargin dim
294                      set the right margin. See -M for details.
295
296       -T dim, --topmargin dim
297                      set the top margin. See -M for details.
298
299       -B dim, --bottommargin dim
300                      set the bottom margin. See -M for details.
301
302       --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
311   Color options:
312       These options are only supported by certain backends. The DXF and GeoJ‐
313       SON backends do not support color.
314
315       -C #rrggbb, --color #rrggbb
316                      set  the  foreground  color  of  the  output  image. The
317                      default is black.
318
319       --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
327       --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
333   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
341       --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
350   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
358       -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
362       -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
369       -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
378   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
388   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
401                      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
409       -i, --invert   invert the input bitmap before processing.
410
411   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
416       --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

BACKEND TYPES

422       Backends can be classified in several ways, which affects the available
423       command line options and their behavior:
424
425       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
434       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
444       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

COMPILE TIME CONFIGURATION

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
457       --disable-zlib
458            compile  potrace  without the zlib compression library. This means
459            PostScript level 3 compression will not be available.
460
461       --enable-metric
462            compile potrace with centimeters as the default  unit  instead  of
463            inches.
464
465       --enable-a4
466            compile potrace with A4 as the default page size.
467

EXIT STATUS

469       The  exit  status  is 0 on successful completion, 1 if the command line
470       was invalid, and 2 on any other error.
471

VERSION

473       1.15
474

AUTHOR

476       Peter Selinger <selinger at users.sourceforge.net>
477
478       Please see the file AUTHORS for a full list of other contributors.
479

TECHNICAL DOCUMENTATION

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

WEB SITE AND SUPPORT

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

SEE ALSO

491       mkbitmap(1)
492
494       Copyright (C) 2001-2017 Peter Selinger
495
496       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
501       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
506       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/.
510
511
512
513Version 1.15                      August 2017                       potrace(1)
Impressum