Provided by: potrace_1.16-2_amd64 bug

NAME

       potrace - transform bitmaps into vector graphics.

SYNOPSIS

       potrace [options] [filename...]

DESCRIPTION

       potrace is a tool for tracing a bitmap, which means, transforming a bitmap into a smooth, scalable image.
       The input is a bitmap, which means, a pixel-based image composed of the two colors black and white  only.
       The  output  is  SVG,  PDF,  EPS,  or one of a number of other vector formats. A typical use is to create
       vector graphics from scanned data, such as company or  university  logos,  handwritten  notes,  etc.  The
       resulting image is not "jaggy" like a bitmap, but smooth. It can then be rendered at any resolution.

       potrace can read bitmaps in the following formats: PBM, PGM, PPM (collectively known as PNM, see pnm(5)),
       as well as BMP (Windows and OS/2 bitmap formats). The input image should only use the  two  colors  black
       and  white.  If other pixel values appear in the input, they will be converted to black and white using a
       simple threshold method.

       potrace can currently produce the following output formats: SVG, PDF, EPS, PostScript, DXF, GeoJSON, PGM,
       Gimppath, and XFig.  Additional backends might be added in the future.

OPTIONS

       The  following  options  are  supported. Dimensions (arguments of type dim) can have optional units, e.g.
       6.5in, 15cm, 100pt.  The default unit is inches (or centimeters, if this was configured at compile  time,
       see  COMPILE  TIME  CONFIGURATION  below).  For pixel-based output formats such as PGM, DXF, GeoJSON, and
       Gimppath, the default unit is pixels.

   General options:
       -h, --help     print help message and exit.

       -v, --version  print version info and exit. This also shows the defaults that  were  compiled  into  this
                      version of potrace.

       -l, --license  print license info and exit.

   Input/output options:
       filename       Each  file  can  hold  an  input image, or multiple concatenated input images. If filename
                      arguments are given, then potrace will by default create one output file  for  each  input
                      filename  given.  The  name  of  the  output  file  is obtained from the input filename by
                      changing its suffix according to the chosen backend. If changing the suffix is  impossible
                      because  the  names  of  the  input  and  output files would be identical, then the output
                      filename is created by adding the "-out" suffix to the name  of  the  input  file.  If  no
                      filename  arguments  are given, then potrace acts as a filter, reading from standard input
                      and writing to standard output. A filename of "-" may be given  to  specify  reading  from
                      standard input.

       -o filename, --output filename
                      write output to this file. All output is directed to the specified file. If this option is
                      used, then multiple input filenames are only allowed for multi-page backends (see  BACKEND
                      TYPES  below).  In this case, each input file may contain one or more bitmaps, and all the
                      bitmaps from all the input files are processed and the output concatenated into  a  single
                      file. A filename of "-" may be given to specify writing to standard output.

       --             End  of  options. Any remaining arguments are interpreted as filenames. This also disables
                      filter mode, even if no filenames are given. This is useful  for  shell  scripts,  because
                      potrace  -- $FILENAMES will behave correctly even for an empty list of filenames. However,
                      -- with an empty list of filenames is not permitted in conjunction  with  the  -o  option,
                      because this would generate a document of zero pages, which none of the backends permit.

   Backend selection:
       For general information, see also BACKEND TYPES below.

       -b name, --backend name
                      Select  backend by name, where name is one of eps, postscript, ps, pdf, pdfpage, svg, dxf,
                      geojson, pgm, gimppath, xfig. Backend names can be abbreviated by a prefix as long  as  it
                      is unambiguous. Backend names are case insensitive.

       -s, --svg, -b svg, --backend svg
                      SVG  backend. The output is a Scalable Vector Graphics (SVG) file.  This is a single-page,
                      variable-sized, dimension-based backend. Note that unless the  -r  option  is  given,  the
                      resolution of the input bitmap is assumed to be 72dpi.

       -b pdf, --backend pdf
                      PDF  backend. The output is a file in the Portable Document Format.  If the input consists
                      of multiple bitmaps, they are each rendered on a separate  page.  This  is  a  multi-page,
                      variable-sized, dimension-based backend.

       -b pdfpage, --backend pdfpage
                      The  PDFPage  backend  is  like  the  PDF  backend,  except that it is fixed-size like the
                      PostScript backend.

       -e, --eps, -b eps, --backend eps
                      EPS backend (default). The output is an encapsulated PostScript file. This  is  a  single-
                      page, variable-sized, dimension-based backend.

       -p, --postscript, -b ps, --backend ps
                      PostScript  backend.  The  output  is a PostScript file. This is a multi-page, fixed-size,
                      dimension-based backend. If the input consists of multiple bitmaps, they are each rendered
                      on a separate page.

       -b dxf, --backend dxf
                      DXF  backend.  The  output  is  a  file  in  the Drawing Interchange Format (DXF). In this
                      backend, all Bezier curves are approximated by piecewise circular arcs; this  is  suitable
                      for  processing  in  CAD software or for machining applications using CNC tools. This is a
                      single-page, variable-sized, pixel-based backend. The -u option has  no  effect  for  this
                      backend.

       -b geojson, --backend geojson
                      GeoJSON  backend.  The output is a file in the format used by some applications processing
                      geographical data. In this backend, all Bezier curves are approximated by 8 straight  line
                      segments. This is a single-page, variable-sized, pixel-based backend. The -u option has no
                      effect for this backend.

       -g, --pgm, -b pgm, --backend pgm
                      PGM backend. The output is a portable greymap (PGM) file. It is a convenient  backend  for
                      antialiasing a bitmap image. This is a multi-page, variable-sized, pixel-based backend. If
                      the input consists of more than one image, the images are concatenated in the output.

       -b gimppath, --backend gimppath
                      Gimppath backend. This backend produces output suitable to be imported as a  path  by  the
                      GNU  Image  Manipulation  Program  (Gimp)  (in the Layers, Channels & Paths dialog, select
                      Paths, then right-click and select Import Path). The output is actually an SVG  file.  The
                      differences  to  the SVG backend are: the --opaque option has no effect, the --flat option
                      is always on, and the dimensions are pixel-based. This is a  single-page,  variable-sized,
                      pixel-based backend.

       -b xfig, --backend xfig
                      XFig  backend. This is a single-page, fixed-size, dimension-based backend. The output is a
                      file in the XFig format.  Note that XFig uses X-splines instead of Bezier curves, thus  it
                      is  not  possible  to  translate  the output of potrace into the XFig format with absolute
                      accuracy. This backend does a reasonable approximation using two control points  for  each
                      Bezier curve segment. The -u option has no effect for this backend, because control points
                      are always rounded to the nearest 1/1200  of  an  inch  in  XFig.  Curve  optimization  is
                      disabled. Implies --opaque.

   Algorithm options:
       For more detailed information on these options, see TECHNICAL DOCUMENTATION below.

       -z policy, --turnpolicy policy
                      specify  how  to  resolve  ambiguities in path decomposition. Must be one of black, white,
                      right, left, minority, majority, or random. Default is  minority.  Turn  policies  can  be
                      abbreviated by an unambiguous prefix, e.g., one can specify min instead of minority.

       -t n, --turdsize n
                      suppress speckles of up to this many pixels.

       -a n, --alphamax n
                      set  the  corner  threshold parameter. The default value is 1. The smaller this value, the
                      more sharp corners will be produced. If this parameter is 0, then  no  smoothing  will  be
                      performed  and  the  output  is a polygon. If this parameter is greater than 4/3, then all
                      corners are suppressed and the output is completely smooth.

       -n, --longcurve
                      turn off curve optimization. Normally potrace tries to join adjacent Bezier curve segments
                      when  this  is  possible.  This  option disables this behavior, resulting in a larger file
                      size.

       -O n, --opttolerance n
                      set the curve optimization tolerance. The default value is 0.2. Larger values  allow  more
                      consecutive  Bezier  curve  segments  to  be  joined  together in a single segment, at the
                      expense of accuracy.

       -u n, --unit n set output quantization. Coordinates in the output  are  rounded  to  1/unit  pixels.  The
                      default  of  10  usually  gives  good results. For some of the debug modes, a value of 100
                      gives more accurate output. This option has no effect for the XFig backend,  which  always
                      rasterizes to 1/1200 inch, or for the DXF backend. For the GeoJSON backend, this option is
                      only a hint; the actual rounding may be more, but not less, accurate than specified.

       -d n, --debug n
                      produce debugging output of type n. This has different effects for different backends. For
                      the  PostScript/EPS backends, the values n=1,2,3 illustrate the intermediate stages of the
                      potrace algorithm.

   Scaling and placement options:
       -P format, --pagesize format
                      for fixed-size backends, set page size. The following formats can be  specified:  A4,  A3,
                      A5,  B5,  Letter, Legal, Tabloid, Statement, Executive, Folio, Quarto, 10x14. Format names
                      are case insensitive. Also, an argument  of  the  form  dimxdim  is  accepted  to  specify
                      arbitrary  dimensions.  The  default page size is Letter (or A4, if this was configured at
                      compile time, see COMPILE TIME CONFIGURATION below).  Page format names can be abbreviated
                      by  a  prefix  as  long as it is unambiguous. This option has no effect for variable-sized
                      backends.

       -W dim, --width dim
                      set the width of output image (before any rotation and margins). If only one of width  and
                      height  is  specified,  the  other  is  adjusted  accordingly  so that the aspect ratio is
                      preserved.

       -H dim, --height dim
                      set the height of output image. See -W for details.

       -r n[xn], --resolution n[xn]
                      for dimension-based backends, set the resolution (in dpi). One inch in  the  output  image
                      corresponds  to  this  many  pixels  in  the  input. Note that a larger value results in a
                      smaller output image.  It is possible to specify separate  resolutions  in  the  x  and  y
                      directions by giving an argument of the form nxn. For variable-sized backends, the default
                      resolution is 72dpi. For fixed-size backends, there is no default resolution; the image is
                      by  default scaled to fit on the page. This option has no effect for pixel-based backends.
                      If -W or -H are specified, they take precedence.

       -x n[xn], --scale n[xn]
                      for pixel-based backends, set the scaling factor. A value  greater  than  1  enlarges  the
                      output, a value between 0 and 1 makes the output smaller. The default is 1. It is possible
                      to specify separate scaling factors for the x and y directions by giving  an  argument  of
                      the  form  nxn.  This  option  has no effect for dimension-based backends. If -W or -H are
                      specified, they take precedence.

       -S n, --stretch n
                      set the aspect ratio. A value greater than 1 means the image will be stretched  in  the  y
                      direction. A value between 0 and 1 means the image will be compressed in the y direction.

       -A angle, --rotate angle
                      set  the  rotation angle (in degrees). The output will be rotated counterclockwise by this
                      angle. This is useful for compensating for images that were scanned not quite upright.

       -M dim, --margin dim
                      set all four margins. The effect and default value of this option depend on  the  backend.
                      For  variable-sized backends, the margins will simply be added around the output image (or
                      subtracted, in case of negative margins). The default margin for these backends is 0.  For
                      fixed-size backends, the margin settings can be used to control the placement of the image
                      on the page. If only one of the left and right margin is given, the image will  be  placed
                      this  distance  from the respective edge of the page, and similarly for top and bottom. If
                      margins are given on opposite sides, the image is scaled to  fit  between  these  margins,
                      unless  the  scaling is already determined explicitly by one or more of the -W, -H, -r, or
                      -x options. By default, fixed-size backends use a non-zero margin whose width  depends  on
                      the page size.

       -L dim, --leftmargin dim
                      set the left margin. See -M for details.

       -R dim, --rightmargin dim
                      set the right margin. See -M for details.

       -T dim, --topmargin dim
                      set the top margin. See -M for details.

       -B dim, --bottommargin dim
                      set the bottom margin. See -M for details.

       --tight        remove  whitespace around the image before scaling and margins are applied. If this option
                      is given, calculations of the width, height, and margins are based on  the  actual  vector
                      outline, rather than on the outer dimensions of the input pixmap, which is the default. In
                      particular, the --tight option can be used to remove any existing margins from  the  input
                      image. See the file placement.pdf for a more detailed illustration.

   Color options:
       These options are only supported by certain backends. The DXF and GeoJSON backends do not support color.

       -C #rrggbb, --color #rrggbb
                      set the foreground color of the output image. The default is black.

       --fillcolor #rrggbb
                      set  the  fill  color  of  the output image, i.e., the color of the "white" parts that are
                      enclosed by "black" parts. The default  is  to  leave  these  parts  transparent.  Implies
                      --opaque.   Please  note that this option sets the background color; to set the foreground
                      color, use --color instead.

       --opaque       fill in the white parts of the image opaquely, instead of leaving them  transparent.  This
                      only  applies  to  interior  white  parts,  i.e.,  those  that are enclosed inside a black
                      outline. Opaqueness is always in effect for the XFig backend.

   SVG options:
       --group        for SVG output, try to group related paths together. Each path is  grouped  together  with
                      all paths that are contained inside it, so that they can be moved around as a unit with an
                      SVG editor. This makes coloring individual components slightly more cumbersome,  and  thus
                      it is not the default.

       --flat         for SVG output, put the entire image into a single path. This makes it impossible to color
                      the components individually, and thus it is not the default. But the  resulting  SVG  file
                      can  be  more  easily  imported  by  some applications such as Gimp. In fact, the Gimppath
                      backend is a variation of the SVG backend with the --flat option and pixel-based  scaling.
                      The --flat option has no effect if --opaque has been selected.

   PostScript/EPS/PDF options:
       -c, --cleartext
                      do  not  compress  the  output. This option disables the use of compression filters in the
                      PostScript and PDF output. In the PostScript backend, if -c and -q are used together,  the
                      resulting output can be easily read by other programs or even by humans.

       -2, --level2   use  PostScript  level 2 compression (default). The resulting file size is ca. 40% smaller
                      than if the -c option is used.

       -3, --level3   use PostScript level 3 compression, if available. This gives slightly smaller  files  than
                      using  -2,  but the resulting files may not print on older PostScript level 2 printers. If
                      support for PostScript level 3 compression has been disabled at compile  time,  a  warning
                      message is printed and level 2 compression is used instead.

       -q, --longcoding
                      turn  off  optimized  numerical coding in PostScript output. Normally, potrace uses a very
                      compact numerical format to represent Bezier curves in  PostScript,  taking  advantage  of
                      existing redundancy in the curve parameters. This option disables this behavior, resulting
                      in longer, but more readable output (particularly if the -c option is also used).

   PGM options:
       -G n, --gamma n
                      set the gamma value for anti-aliasing (default is 2.2).  Most  computer  displays  do  not
                      render  shades  of  grey  linearly,  i.e.,  a  grey value of 0.5 is not displayed as being
                      exactly half-way between black and white. The  gamma  parameter  corrects  for  this,  and
                      therefore  leads to nicer looking output. The default value of 2.2 is appropriate for most
                      normal CRT displays.

   Frontend options:
       -k n, --blacklevel n
                      set the threshold level for converting input images  to  bitmaps.  The  potrace  algorithm
                      expects  a  bitmap,  thus  all  pixels of the input images are converted to black or white
                      before processing begins.  Pixels whose brightness is less than n are converted to  black,
                      all  other  pixels  to  white.  Here  n  is  a number between 0 and 1. One case is treated
                      specially: if the input is in an indexed color format with  exactly  2  colors,  then  the
                      blacklevel is ignored and the darker of the two colors is mapped to black.

                      Note:  the  method  used by potrace for converting greymaps to bitmaps is very crude; much
                      better results can be obtained if a separate program, such as  mkbitmap(1),  is  used  for
                      this  purpose.  In  particular,  mkbitmap(1),  which  is distributed with potrace, has the
                      ability to scale and interpolate the image before  thresholding,  which  results  in  much
                      better preservation of detail.

       -i, --invert   invert the input bitmap before processing.

   Progress bar options:
       --progress     display  a  progress bar for each bitmap that is processed. This is useful for interactive
                      use.  The default behavior is not to show any progress information.

       --tty mode     set the terminal mode for progress bar  rendering.  Possible  values  are  "vt100",  which
                      requires  a  vt100-compatible  terminal, and "dumb", which uses only ASCII characters. The
                      default is system dependent.

BACKEND TYPES

       Backends can be classified in several ways, which affects the available command line  options  and  their
       behavior:

       Fixed-size or variable-sized:
            For  fixed-size  backends,  the  size  of  the page is always the same (for example Letter or A4, as
            specified at compile time or by the -P option). By default, the image will be centered and scaled to
            fit  the  page size. For variable-size backends, the size of the page follows the size of the image.
            Currently the PostScript (PS), PDFPage, and XFig backends are fixed-size, and the remaining backends
            are variable-size.

       Dimension-based or pixel-based:
            In dimension-based backends, distances are measured in physical units such as inches or centimeters.
            In pixel-based backends, distances are measured in  pixel  units.  The  -r  option  only  works  for
            dimension-based backends, and the -x option only works for pixel-based backends. Currently, the DXF,
            PGM, Gimppath, and GeoJSON backends are pixel-based, and the remaining backends are dimension-based.
            Currently, all pixel-based backends are variable-sized.

       Single-page or multi-page:
            Single-page backends can only accept a single image. Multi-page backends can accept multiple images,
            typically one per page of output. Currently, the PostScript (PS), PDF, PDFPage, and PGM backends are
            multi-page,  and the remaining backends are single-page. Note that multiple input images can be read
            in two ways: from multiple input files (with the -o option), or from a single input file that  holds
            several concatenated images.

COMPILE TIME CONFIGURATION

       Certain  aspects  of  the  behavior of potrace can be configured at compile time by passing the following
       options to the ./configure script.

       --disable-zlib
            compile potrace without the zlib compression library. This means PostScript level 3 compression will
            not be available.

       --enable-metric
            compile potrace with centimeters as the default unit instead of inches.

       --enable-a4
            compile potrace with A4 as the default page size.

EXIT STATUS

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

VERSION

       1.16

AUTHOR

       Peter Selinger <selinger at users.sourceforge.net>

       Please see the file AUTHORS for a full list of other contributors.

TECHNICAL DOCUMENTATION

       For a detailed technical description of the  potrace  algorithm,  see  the  file  potrace.pdf,  which  is
       available from the potrace web site. For information on the Potrace library API, see potracelib.pdf.

WEB SITE AND SUPPORT

       The  latest version of potrace is available from http://potrace.sourceforge.net/. This site also contains
       a list of frequently asked questions, as well as information on how to obtain support.

SEE ALSO

       mkbitmap(1)

COPYRIGHT

       Copyright (C) 2001-2019 Peter Selinger

       This program is free software; you can redistribute it and/or modify  it  under  the  terms  of  the  GNU
       General  Public License as published by the Free Software Foundation; either version 2 of the License, or
       (at your option) any later version.

       This program is distributed in the hope that it will be useful, but WITHOUT ANY  WARRANTY;  without  even
       the  implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public
       License for more details.

       You should have received a copy of the GNU General Public License along with this program; if not,  write
       to  the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  See
       also http://www.gnu.org/.