Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
potrace(1)		    General Commands Manual		    potrace(1)

       potrace - transform bitmaps into	vector graphics.

       potrace [options] [filename...]

       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  re-
       sulting	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.

       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  de-
		      faults 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 in-
		      put 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 in-

       -s, --svg, -b svg, --backend svg
		      SVG  backend.  The  output is a Scalable Vector Graphics
		      (SVG) file.  This	is a single-page, variable-sized,  di-
		      mension-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 op-
		      tion 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

   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 ra-
		      tio 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 re-
		      sults 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 op-
		      tion 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  be-
		      tween  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-

       -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 be-
		      tween 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

       -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 de-
		      termined 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  de-
		      fault 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

       --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 re-
		      sulting SVG file can be more easily imported by some ap-
		      plications  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  to-
		      gether, the resulting output can be easily read by other
		      programs or even by humans.

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

       -3, --level3   use PostScript level 3 compression, if  available.  This
		      gives  slightly smaller files than using -2, but the re-
		      sulting 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 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 be-
		      ing 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	appro-
		      priate 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

		      Note: the	method used by potrace for converting greymaps
		      to bitmaps is very crude;	much better results can	be ob-
		      tained 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 re-
		      sults 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.

       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-

       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.

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

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

	    compile  potrace  with  centimeters	as the default unit instead of

	    compile potrace with A4 as the default page	size.

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


       Peter Selinger <selinger	at>

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

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

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


       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 MER-
       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

Version	1.16			September 2019			    potrace(1)


Want to link to this manual page? Use this URL:

home | help