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

FreeBSD Manual Pages


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

       mkbitmap	- transform images into	bitmaps	with scaling and filtering

       mkbitmap	[options] [filename...]

       mkbitmap	reads an image,	and applies one	or more	of the following oper-
       ations to it, in	this order: inversion,	highpass  filtering,  scaling,
       and  thresholding.  Each	 operation  can	be individually	controlled and
       turned on or off.

       The principal use of mkbitmap is	to convert color or  greyscale	images
       into  a	format	suitable as input for other programs, particularly the
       tracing program potrace(1). It is particularly  useful  for  converting
       scanned	line  art,  such as cartoons, handwritten text,	etc., to high-
       resolution bilevel images.

       Highpass	filtering can be used to ensure	that foreground	features  such
       as  lines  and  text are	preserved, while at the	same time compensating
       for uneven background. Optional blurring	can be applied to  smooth  out
       the  image  and	remove	visual	noise.	Scaling	is important because a
       scanned greyscale image contains	more visual detail than	a bilevel  im-
       age at the same resolution. By scaling the image	to a higher resolution
       (using interpolation) before thresholding it, some of  this  detail  is
       preserved. Thresholding means converting	a greyscale image to a bilevel
       image using only	black and white	pixels.	Pixels that are	darker than  a
       certain	threshold value	are converted to black.	 Optional inversion is
       useful if the input image shows bright  features	 on  dark  background,
       such as a picture of chalk drawings on a	blackboard.

       Supported  input	 formats  are  PNM (PBM, PGM, PPM) and BMP. The	output
       formats are PBM for bitmaps, and	PGM for	greymaps.

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

       -v, --version  print version info and exit.

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

   Input/output	options:
       filename	      If filename arguments are	given, then mkbitmap  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  to ".pbm" or
		      ".pgm". If the name of the input file  and  output  file
		      would  be	identical, then	an additional suffix "-out" is
		      appended to the output filename. If  no  filename	 argu-
		      ments are	given, then mkbitmap 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; the output for this argument  will  then
		      be  written to standard output. Each input file may con-
		      tain one or more images.

       -o filename, --output filename
		      write output to this file. All  output  is  concatenated
		      and  directed  to	the specified file. This overrides the
		      default behavior of creating one output  file  for  each
		      input  file.  A  filename	of "-" may be given to specify
		      writing to standard output.

   Image processing options:
       -x, --nodefaults
		      Turn off default options.	Normally,  the	following  op-
		      tions  are preselected by	default: -f 4 -s 2 -3 -t 0.45.
		      The -x option disables these defaults; thus, mkbitmap -x
		      does  nothing  but copy a	greyscale image	from the input
		      to the output. Other  processing	options	 can  then  be
		      added  one  by one; e.g.,	mkbitmap -xf10 does only high-
		      pass filtering, mkbitmap -xt0.5 does only	 thresholding,

       -i, --invert   Invert  the input	image. If this option is chosen, it is
		      applied to the image before any other operation.	It  is
		      used  to deal with white-on-black	images,	such as	photo-
		      graphs of	chalk drawings on a blackboard.	Note that  the
		      behavior	of  this  option is not	in general the same as
		      inverting	the output  bitmap,  unless  the  thresholding
		      value is also inverted.

       -f n, --filter n
		      Apply a highpass filter to the image. This filter	is ap-
		      proximately Gaussian and non-directional.	The effect  is
		      to  preserve  small  detail while	compensating for back-
		      ground gradients.	The parameter n	is a radius  (in  pix-
		      els)  which corresponds approximately to the size	of de-
		      tails which should be  preserved.	 More  precisely,  the
		      filter  is  implemented by subtracting a blurred version
		      of the image from	the original image. The	parameter n is
		      equal  to	the standard deviation of the blur. The	output
		      of the filtering step is a normalized image whose	 aver-
		      age brightness is	exactly	0.5. The default filter	radius
		      is 4.

       -n, --nofilter Turn off highpass	filtering.

       -b n, --blur n Blur the image. The effect is to smooth out fine details
		      and to reduce visual noise in the	image. The parameter n
		      is the blurring radius, and should be chosen small (1 is
		      a	 good  value to	start with). This is implemented as an
		      approximately Gaussian, non-directional blur with	 stan-
		      dard  deviation  proportional  to	n. Blurring is applied
		      after  the  highpass  filter,  but  before  scaling  and
		      thresholding.   If this option is	not given, the default
		      is not to	apply any blurring.

       -s n, --scale n
		      Scale the	image by an integer  factor  n>0.  Scaling  is
		      done after highpass filtering, but before	the threshold-
		      ing step.	A scaling factor of 1 indicates	that no	 scal-
		      ing  is  to be done. Otherwise, interpolation is used to
		      fill in the in-between pixels. If	the output of mkbitmap
		      is  to be	used as	input to a tracing program such	as po-
		      trace, a scaling factor of 2 is recommended.  This  pre-
		      served  the right	amount of detail for the tracing algo-
		      rithm to work well. If a scaling factor of  1  is	 used,
		      too  much	 detail	 is  lost. If a	scaling	factor of 3 or
		      higher is	used, the interpolation	tends to "invent"  de-
		      tail  which  was not present in the original image, thus
		      preventing potrace from doing a good job.

       -1, --linear   Use linear interpolation when scaling to a higher	 reso-
		      lution. This is slightly faster, but less	nice, than the
		      default cubic interpolation.

       -3, --cubic    Use cubic	interpolation when scaling to a	higher resolu-
		      tion.  This is the default. It is	slower than linear in-
		      terpolation, but leads to	better results.

       -t n, --threshold n
		      Set the threshold	grey value for bilevel conversion. The
		      parameter	 n  is	a brightness value between 0 for black
		      and 1 for	white.	Any pixels below this brightness  will
		      be  converted  to	 black (thus, smaller values of	n will
		      lead to whiter output).

       -g, --grey     Disable bilevel conversion. If  this  option  is	given,
		      processing stops after the scaling step and a greymap is

       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>

       mkbitmap	 is distributed	as part	of the potrace package,	and the	latest
       version is available from   This  site
       also contains documentation and 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			   mkbitmap(1)


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

home | help