manpagez: man pages & more
man potrace(1)
Home | html | info | man
potrace(1)                                                          potrace(1)




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  (col-
       lectively  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 con-
       verted 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  concate-
                      nated  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 suf-
                      fix  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 file-
                      name 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 docu-
                      ment 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,  post-
                      script,  ps, pdf, pdfpage, svg, dxf, geojson, pgm, gimp-
                      path, 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  Docu-
                      ment 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 back-
                      end. 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 Inter-
                      change 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 bit-
                      map 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,  dimen-
                      sion-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  DOCUMEN-
       TATION below.

       -z policy, --turnpolicy policy
                      specify  how  to  resolve ambiguities in path decomposi-
                      tion. Must be one of black, white, right,  left,  minor-
                      ity,  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 sup-
                      pressed and the output is completely smooth.

       -n, --longcurve
                      turn off curve optimization. Normally potrace  tries  to
                      join  adjacent Bezier curve segments when this is possi-
                      ble. 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 seg-
                      ment, 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 dimen-
                      sions.  The  default page size is Letter (or A4, if this
                      was configured at compile time, see COMPILE TIME CONFIG-
                      URATION 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  prece-
                      dence.

       -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  mar-
                      gins).  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,  calcula-
                      tions of the width, height, and margins are based on the
                      actual vector outline, rather than on the  outer  dimen-
                      sions of the input pixmap, which is the default. In par-
                      ticular, 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 GeoJ-
       SON 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 back-
                      ground 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  inte-
                      rior 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  individ-
                      ual  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 indi-
                      vidually, 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  compres-
                      sion  has  been disabled at compile time, a warning mes-
                      sage is printed and level 2 compression is used instead.

       -q, --longcoding
                      turn  off  optimized numerical coding in PostScript out-
                      put. Normally, potrace uses  a  very  compact  numerical
                      format  to represent Bezier curves in PostScript, taking
                      advantage of existing redundancy in  the  curve  parame-
                      ters.  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 lin-
                      early,  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  pro-
                      cessed. 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. Possi-
                      ble  values are "vt100", which requires a vt100-compati-
                      ble terminal, and "dumb", which uses only ASCII  charac-
                      ters. 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 back-
            ends 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, dis-
            tances 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 dimen-
            sion-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.15


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.source-
       forge.net/. This site also contains a list of  frequently  asked  ques-
       tions, as well as information on how to obtain support.


SEE ALSO

       mkbitmap(1)


COPYRIGHT

       Copyright (C) 2001-2017 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 MER-
       CHANTABILITY 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/.



Version 1.15                      August 2017                       potrace(1)

potrace 1.15 - Generated Thu Aug 10 11:20:30 CDT 2017
© manpagez.com 2000-2021
Individual documents may contain additional copyright information.