mkbitmap(1) User Commands mkbitmap(1)

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

Version 1.16 September 2019 mkbitmap(1)