mkbitmap - transform images into bitmaps with scaling and filtering
mkbitmap [options] [filename...]
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 features such as
lines and text are preserved, while at the same time compensating for
uneven background. 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
Supported input formats are PNM (PBM, PGM, PPM) and BMP. The output
formats are PBM for bitmaps, and PGM for greymaps.
print help message and exit.
print version info and exit.
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. Each input file may contain one or more
-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:
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,
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 unevenness in the background. 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.
Turn off highpass filtering.
-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.
Use linear interpolation when scaling to a higher resolution. This is
slightly faster, but less nice, than the default cubic interpolation.
Use cubic interpolation when scaling to a higher resolution. This is
the default. It is slower than linear interpolation, but leads to
-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).
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>
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.
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., 59 Temple Place, Suite 330, Boston, MA 02111-1307,
USA. See also http://www.gnu.org/.