Provided by: potrace_1.16-2_amd64 bug

NAME

       mkbitmap - transform images into bitmaps with scaling and filtering

SYNOPSIS

       mkbitmap [options] [filename...]

DESCRIPTION

       mkbitmap  reads  an  image,  and applies one or more of the following operations 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
       image 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.

OPTIONS

   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  arguments 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 contain 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 options  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 highpass  filtering,  mkbitmap  -xt0.5  does  only
                      thresholding, etc.

       -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  photographs 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 approximately Gaussian
                      and  non-directional.  The  effect  is  to  preserve  small  detail   while
                      compensating  for  background  gradients.  The  parameter n is a radius (in
                      pixels) which corresponds approximately to the size of details 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 average 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
                      standard  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  thresholding  step.  A  scaling  factor  of  1
                      indicates  that  no scaling 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 potrace, a scaling factor of 2 is
                      recommended. This preserved the right amount  of  detail  for  the  tracing
                      algorithm  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" detail 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  resolution.  This  is
                      slightly faster, but less nice, than the default cubic interpolation.

       -3, --cubic    Use  cubic  interpolation  when scaling to a higher resolution. This is the
                      default. It is slower  than  linear  interpolation,  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 output.

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>

WEB SITE AND SUPPORT

       mkbitmap is distributed as part  of  the  potrace  package,  and  the  latest  version  is
       available from http://potrace.sourceforge.net/.  This site also contains documentation and
       information on how to obtain support.

SEE ALSO

       potrace(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/.