mkbitmap(1)

✨ mkbitmap — the glow-up your images have been waiting for ✨

okay so bestie, this is mkbitmap(1) from the General Commands Manual section, and it is literally the makeover artist for your pictures. 💖

🌸 NAME 🌸

mkbitmap — transform images into bitmaps with scaling and filtering 🦋

🌈 SYNOPSIS 🌈

mkbitmap [options] [filename...]

💅 DESCRIPTION 💅

so here's the tea: mkbitmap reads an image and then applies one or more of the following operations to it, in this exact order: inversion, highpass filtering, scaling, and thresholding. every single one of these can be individually controlled and turned on or off. no cap. 🔥

the main character use of mkbitmap is converting color or greyscale images into a format that's suitable as input for other programs — especially the tracing program potrace(1). it's particularly iconic for converting scanned line art (cartoons, handwritten text, etc.) into high-resolution bilevel images. it's giving scan-to-slay. ✨

highpass filtering can be used to make sure foreground features like lines and text are preserved, while also compensating for uneven background. optional blurring can be applied to smooth out the image and remove visual noise. scaling matters 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 get converted to black. optional inversion is useful if the input image shows bright features on dark background, like 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. periodt. 💅

✨ OPTIONS ✨

🫶 General options:

• -h, --help — print help message and exit. your lil helper bestie.
• -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. it's giving build-your-own-pipeline. 🔧
• -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. ⚠️ lowkey important, don't skip that note.
• -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. bye filter 💀
• -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. 👑 goldilocks energy fr fr
• -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. main character energy 💅
• -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. slay when it's 0, sad when it's not. 😭

⭐ 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. go say hi bestie 🫶

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

okay that's the whole page bestie, go forth and bitmapify 💖✨

Version 1.16 · September 2019 · General Commands Manual — mwah, love u, see u in the group chat 🎀🦋💅