mkbitmap - transform images into bitmaps with scaling and filtering
mkbitmap [options] [filename...]
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
The principal use of mkbitmap
is to convert color or greyscale images
into a format suitable as input for other programs, particularly the tracing
(1). It is particularly useful for converting scanned
line art, such as cartoons, handwritten text, etc., to high-resolution bilevel
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.
- -h, --help
- print help message and exit.
- -v, --version
- print version info and exit.
- -l, --license
- print license info and exit.
- 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
- -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.
- -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
- -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
- -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.
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 users.sourceforge.net>
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.
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
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