1mkbitmap(1)                 General Commands Manual                mkbitmap(1)
2
3
4

NAME

6       mkbitmap - transform images into bitmaps with scaling and filtering
7

SYNOPSIS

9       mkbitmap [options] [filename...]
10

DESCRIPTION

12       mkbitmap reads an image, and applies one or more of the following oper‐
13       ations to it, in this order: inversion,  highpass  filtering,  scaling,
14       and  thresholding.  Each  operation  can be individually controlled and
15       turned on or off.
16
17       The principal use of mkbitmap is to convert color or  greyscale  images
18       into  a  format  suitable as input for other programs, particularly the
19       tracing program potrace(1). It is particularly  useful  for  converting
20       scanned  line  art,  such as cartoons, handwritten text, etc., to high-
21       resolution bilevel images.
22
23       Highpass filtering can be used to ensure that foreground features  such
24       as  lines  and  text are preserved, while at the same time compensating
25       for uneven background. Optional blurring can be applied to  smooth  out
26       the  image  and  remove  visual  noise.  Scaling is important because a
27       scanned greyscale image contains more  visual  detail  than  a  bilevel
28       image  at the same resolution. By scaling the image to a higher resolu‐
29       tion (using interpolation) before thresholding it, some of this  detail
30       is  preserved.  Thresholding  means  converting  a greyscale image to a
31       bilevel image using only black and white pixels. Pixels that are darker
32       than a certain threshold value are converted to black.  Optional inver‐
33       sion is useful if the input image shows bright features on  dark  back‐
34       ground, such as a picture of chalk drawings on a blackboard.
35
36       Supported  input  formats  are  PNM (PBM, PGM, PPM) and BMP. The output
37       formats are PBM for bitmaps, and PGM for greymaps.
38

OPTIONS

40   General options:
41       -h, --help     print help message and exit.
42
43       -v, --version  print version info and exit.
44
45       -l, --license  print license info and exit.
46
47   Input/output options:
48       filename       If filename arguments are given, then mkbitmap  will  by
49                      default  create  one output file for each input filename
50                      given. The name of the output file is obtained from  the
51                      input  filename  by  changing  its  suffix  to ".pbm" or
52                      ".pgm". If the name of the input file  and  output  file
53                      would  be identical, then an additional suffix "-out" is
54                      appended to the output filename. If  no  filename  argu‐
55                      ments are given, then mkbitmap acts as a filter, reading
56                      from standard input and writing to  standard  output.  A
57                      filename  of  "-"  may  be given to specify reading from
58                      standard input; the output for this argument  will  then
59                      be  written to standard output. Each input file may con‐
60                      tain one or more images.
61
62       -o filename, --output filename
63                      write output to this file. All  output  is  concatenated
64                      and  directed  to the specified file. This overrides the
65                      default behavior of creating one output  file  for  each
66                      input  file.  A  filename of "-" may be given to specify
67                      writing to standard output.
68
69   Image processing options:
70       -x, --nodefaults
71                      Turn  off  default  options.  Normally,  the   following
72                      options  are  preselected  by  default:  -f 4 -s 2 -3 -t
73                      0.45. The  -x  option  disables  these  defaults;  thus,
74                      mkbitmap -x does nothing but copy a greyscale image from
75                      the input to the output. Other  processing  options  can
76                      then be added one by one; e.g., mkbitmap -xf10 does only
77                      highpass filtering, mkbitmap -xt0.5 does only threshold‐
78                      ing, etc.
79
80       -i, --invert   Invert  the input image. If this option is chosen, it is
81                      applied to the image before any other operation.  It  is
82                      used  to deal with white-on-black images, such as photo‐
83                      graphs of chalk drawings on a blackboard. Note that  the
84                      behavior  of  this  option is not in general the same as
85                      inverting the output  bitmap,  unless  the  thresholding
86                      value is also inverted.
87
88       -f n, --filter n
89                      Apply  a  highpass  filter  to the image. This filter is
90                      approximately Gaussian and non-directional.  The  effect
91                      is to preserve small detail while compensating for back‐
92                      ground gradients. The parameter n is a radius  (in  pix‐
93                      els)  which  corresponds  approximately  to  the size of
94                      details which should be preserved. More  precisely,  the
95                      filter  is  implemented by subtracting a blurred version
96                      of the image from the original image. The parameter n is
97                      equal  to the standard deviation of the blur. The output
98                      of the filtering step is a normalized image whose  aver‐
99                      age brightness is exactly 0.5. The default filter radius
100                      is 4.
101
102       -n, --nofilter Turn off highpass filtering.
103
104       -b n, --blur n Blur the image. The effect is to smooth out fine details
105                      and to reduce visual noise in the image. The parameter n
106                      is the blurring radius, and should be chosen small (1 is
107                      a  good  value to start with). This is implemented as an
108                      approximately Gaussian, non-directional blur with  stan‐
109                      dard  deviation  proportional  to n. Blurring is applied
110                      after  the  highpass  filter,  but  before  scaling  and
111                      thresholding.   If this option is not given, the default
112                      is not to apply any blurring.
113
114       -s n, --scale n
115                      Scale the image by an integer  factor  n>0.  Scaling  is
116                      done after highpass filtering, but before the threshold‐
117                      ing step. A scaling factor of 1 indicates that no  scal‐
118                      ing  is  to be done. Otherwise, interpolation is used to
119                      fill in the in-between pixels. If the output of mkbitmap
120                      is  to  be  used  as  input to a tracing program such as
121                      potrace, a scaling factor of 2 is recommended. This pre‐
122                      served  the right amount of detail for the tracing algo‐
123                      rithm to work well. If a scaling factor of  1  is  used,
124                      too  much  detail  is  lost. If a scaling factor of 3 or
125                      higher is used,  the  interpolation  tends  to  "invent"
126                      detail which was not present in the original image, thus
127                      preventing potrace from doing a good job.
128
129       -1, --linear   Use linear interpolation when scaling to a higher  reso‐
130                      lution. This is slightly faster, but less nice, than the
131                      default cubic interpolation.
132
133       -3, --cubic    Use cubic interpolation when scaling to a higher resolu‐
134                      tion.  This  is  the  default.  It is slower than linear
135                      interpolation, but leads to better results.
136
137       -t n, --threshold n
138                      Set the threshold grey value for bilevel conversion. The
139                      parameter  n  is  a brightness value between 0 for black
140                      and 1 for white.  Any pixels below this brightness  will
141                      be  converted  to  black (thus, smaller values of n will
142                      lead to whiter output).
143
144       -g, --grey     Disable bilevel conversion. If  this  option  is  given,
145                      processing stops after the scaling step and a greymap is
146                      output.
147

EXIT STATUS

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

VERSION

153       1.16
154

AUTHOR

156       Peter Selinger <selinger at users.sourceforge.net>
157

WEB SITE AND SUPPORT

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

SEE ALSO

164       potrace(1)
165
167       Copyright (C) 2001-2019 Peter Selinger
168
169       This program is free software; you can redistribute it and/or modify it
170       under the terms of the GNU General Public License as published  by  the
171       Free  Software Foundation; either version 2 of the License, or (at your
172       option) any later version.
173
174       This program is distributed in the hope that it  will  be  useful,  but
175       WITHOUT  ANY  WARRANTY;  without  even  the  implied  warranty  of MER‐
176       CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU  General
177       Public License for more details.
178
179       You should have received a copy of the GNU General Public License along
180       with this program; if not, write to the Free Software Foundation, Inc.,
181       51  Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  See also
182       http://www.gnu.org/.
183
184
185
186Version 1.16                    September 2019                     mkbitmap(1)
Impressum