UNPAPER(1)

unpaper(1) — your bestie's guide to making scans look less cursed 💅

✨ NAME ✨

unpaper — unpaper. that's literally the name, bestie. the name ate and left no crumbs. 👑

🫶 SYNOPSIS 🫶

unpaper [options] (input patterns output patterns | input files output files)

🌸 OVERVIEW 🌸

okay so real talk: unpaper is a post-processing tool for scanned sheets of paper. it's especially for book pages that were scanned from previously created photocopies. the main purpose is to make scanned book pages better readable on screen after conversion to PDF. additionally, unpaper might be useful to enhance the quality of scanned pages before performing optical character recognition (OCR). 🦋

it tries to clean scanned images by removing dark edges that appeared through scanning or copying on areas outside the actual page content (e.g. dark areas between the left-hand-side and the right-hand-side of a double-sided book-page scan). it also tries to detect misaligned centering and rotation of pages and will automatically straighten each page by rotating it to the correct angle. this process is called deskewing. note that the automatic processing will sometimes fail. it is always a good idea to manually control the results of unpaper and adjust the parameter settings according to the requirements of the input. each processing step can also be disabled individually for each sheet. ✨

input and output files can be in either .pbm, .pgm or .ppm format, thus generally in .pnm format, as also used by the Linux scanning tools scanimage and scanadf. conversion to PDF can e.g. be achieved with the Linux tools pgm2tiff, tiffcp and tiff2pdf.

🎀 INPUT AND OUTPUT FILES 🎀

input and output files need to be designed either by using patterns or an ordered list of input and output files; if patterns are used, such as %04d, then they are substituted for the input and output sheet number before opening the file for input or output. 💖

if you're not using patterns, then the program expects one or two input files depending on what is passed as --input-pages and one or two output files depending on what is passed as --output-pages, in order.

missing output file names are fatal and will stop processing; missing initial input file names are fatal, and so is any missing input file if a range of sheets is defined through --sheet or --end-sheet. no cap, that's a hard stop. 💀

unpaper accepts files in PNM format, which means they might be in .pbm, .pgm, .ppm or .pnm format, which is what is produced by Linux command line scanning tools such as scanimage and scanadf.

💅 OPTIONS 💅

okay bestie, options time. every flag, every default, every little value. no skipping, periodt. 💅

• -l { single | double | none } ; --layout { single | double | none } — set default layout options for a sheet:
  • single — one page per sheet.
  • double — two pages per sheet, landscape orientation (one page on the left half, one page on the right half).
  • none — no auto-layout, mask-scan-points may individually be specified.

using single or double automatically sets corresponding --mask-scan-points. the default is single.

• -start sheet ; --start-sheet start-sheet — number of first sheet to process in multi-sheet mode. (default: 1)
• -end sheet ; --end-sheet sheet — number of last sheet to process in multi-sheet mode. -1 indicates processing until no more input file with the corresponding page number is available (default: -1)
• -# sheet-range ; --sheet sheet-range — optionally specifies which sheets to process in the range between start-sheet and end-sheet.
• -x sheet-range ; --exclude sheet-range — excludes sheets from processing in the range between start-sheet and end-sheet.
• --pre-rotate { -90 | 90 } — rotates the whole image clockwise (90) or anti-clockwise (-90) before any other processing.
• --post-rotate { -90 | 90 } — rotates the whole image clockwise (90) or anti-clockwise (-90) after any other processing.
• -M { v | h | v,h } ; --pre-mirror { v | h | v,h } — mirror the image, after possible pre-rotation. either v (for vertical mirroring), h (for horizontal mirroring) or v,h (for both) can be specified.
• --post-mirror { v | h | v,h } — mirror the image, after any other processing except possible post-rotation. either v (for vertical mirroring), h (for horizontal mirroring) or v,h (for both) can be specified.
• --pre-shift h, v — shift the image before further processing. values for h (horizontal shift) and v (vertical shift) can either be positive or negative.
• --post-shift h, v — shift the image after other processing. values for h (horizontal shift) and v (vertical shift) can either be positive or negative.
• --pre-wipe left, top, right, bottom — manually wipe out an area before further processing. any pixel in a wiped area will be set to white. multiple areas to be wiped may be specified by multiple occurrences of this options.
• --post-wipe left, top, right, bottom — manually wipe out an area after processing. any pixel in a wiped area will be set to white. multiple areas to be wiped may be specified by multiple occurrences of this options.
• --pre-border left, top, right, bottom — clear the border-area of the sheet before further processing. any pixel in the border area will be set to white.
• --post-border left, top, right, bottom — clear the border-area of the sheet after other processing. any pixel in the border area will be set to white.
• --pre-mask x1, y1, x2, y2 — specify masks to apply before any other processing. any pixel outside a mask will be set to white, unless another mask includes this pixel.

only pixels inside a mask will remain. multiple masks may be specified. no deskewing will be applied to the masks specified by --pre-mask.

• -s { width, height | size-name } ; --size { width, height | size-name } — change the sheet size before other processing is applied. content on the sheet gets zoomed to fit to the appropriate size, but the aspect ratio is preserved. instead, if the sheet's aspect ratio changes, the zoomed content gets centered on the sheet.

possible values for size-name are: a5, a4, a3, letter, legal. all size names can also be applied in rotated landscape orientation, use a4-landscape, letter-landscape etc.

• --post-size { width, height | size-name } — change the sheet size preserving the content's aspect ratio after other processing steps are applied.
• --stretch { width, height | size-name } — change the sheet size before other processing is applied. content on the sheet gets stretched to the specified size, possibly changing the aspect ratio.
• --post-stretch { width, height | size-name } — change the sheet size after other processing is applied. content on the sheet gets stretched to the specified size, possibly changing the aspect ratio.
• -z factor ; --zoom factor — change the sheet size according to the given factor before other processing is done.
• --post-zoom factor — change the sheet size according to the given factor after processing is done.
• -bn { v | h | v, h } ; --blackfilter-scan-direction { v | h | v, h } — directions in which to search for solidly black areas. either v (for vertical searching), h (for horizontal searching) or v,h (for both) can be specified. the blackfilter works by moving a virtual bar across each page. the darkness inside the virtual bar is determined and if it exceeds blackfilter-scan-threshold black pixels in the area are filled. during filling the blackness of each pixel is determined by black-threshold. the bar is then moved by blackfilter-scan-step in the scanning direction. once a page border is encountered the bar is moved down (horizontal scan) or right (vertical scan) by its blackfilter-scan-size.
• -bs { size | h-size, v-size } ; --blackfilter-scan-size { size | h-size, v-size } — size of virtual bar in direction of scanning (meaning width for horizontal pass, height for vertical pass) used for black area detection. two values may be specified to individually set the size for the horizontal scanning-pass and the vertical pass. (default: 20,20)
• -bd { depth | h-depth, v-depth } ; --blackfilter-scan-depth { depth | h-depth, v-depth } — depth of virtual bar in non-scanning direction (meaning height for horizontal pass, width for vertical pass) used for black area detection. two values may be specified to individually set the depth for the horizontal scanning-pass and the vertical pass. (default: 500,500)
• -bp { step | h-step, v-step } ; --blackfilter-scan-step { step | h-step, v-step } — steps to move virtual bar for black area detection. two values may be specified to individually set the step for the horizontal scanning-pass and the vertical pass. (default: 5,5)
• -bt threshold ; --blackfilter-scan-threshold threshold — ratio of dark pixels above which a black area gets detected. (default: 0.95).
• -bx left, top, right, bottom ; --blackfilter-scan-exclude left, top, right, bottom — area on which the blackfilter should not operate. this can be useful to prevent the blackfilter from working on inner page content. may be specified multiple times to set more than one area.
• -bi intensity ; --blackfilter-intensity intensity — intensity with which to delete black areas. this deletes pixels around the virtual scan bar. larger values will leave less noise-pixels around former black areas, but may delete page content. (default: 20)
• -ni intensity ; -noisefilter-intensity intensity — intensity with which to delete individual pixels or tiny clusters of pixels. any cluster which only contains intensity dark pixels together will be deleted. (default: 4)
• -ls { size | h-size, v-size } ; --blurfilter-size { size | h-size, v-size } — size of blurfilter area to search for "lonely" clusters of pixels. (default: 100,100)
• -lp { step | h-step, v-step } ; --blurfilter-step { step | h-step, v-step } — size of "blurring" steps in each direction. (default: 50,50)
• -li ratio ; --blurfilter-intensity ratio — relative intensity with which to delete tiny clusters of pixels. any blurred area which contains at most the ratio of dark pixels will be cleared. (default: 0.01)

…and we're right back into it, bestie — the options tour keeps going 💅

• -gs, --grayfilter-size { size | h-size, v-size } — the size of the grayfilter mask it uses to hunt for "gray-only" spots of pixels. (default: 50,50)
• -gp, --grayfilter-step { step | h-step, v-step } — how big the steps are when it slides that grayfilter mask around in each direction. (default: 20,20)
• -gt, --grayfilter-threshold ratio — the relative intensity of grayness that gets accepted, and this only kicks in when no black pixel shows up inside the mask before the mask gets cleared. (default: 0.5)
• -p, --mask-scan-point x, y — you set the starting point for mask-detection by hand. You can stack multiple --mask-scan-point options to detect multiple masks, no cap. 🎯
• -m, --mask x1, y1, x2, y2 — manually add a mask, on top of whatever masks get auto-detected around the --mask-scan-point coordinates (unless --no-mask-scan is specified, ofc).

Literally any pixel outside a mask gets set to white, unless another mask covers that pixel. So masks stack, they don't fight. 🫶

• -mn, --mask-scan-direction { v | h | v,h } — the directions it searches for mask borders in, starting from the --mask-scan-point coordinates. You pick v (vertical mirroring), h (horizontal mirroring), or v,h (both, why not). (default: h, because v may cut text-paragraphs on single-page sheets — noted, bestie 🙈)
• -ms, --mask-scan-size { size | h-size, v-size } — width of the virtual bar used for mask detection. Two values let you set horizontal and vertical size separately. (default: 50,50)
• -md, --mask-scan-depth { depth | h-depth, v-depth } — height of that virtual bar for mask detection. (default: -1,-1, which uses the total width or height of the sheet)
• -mp, --mask-scan-step { step | h-step, v-step } — the steps used to move the virtual bar around while detecting masks. (default: 5,5)
• -mt, --mask-scan-threshold { threshold | h-threshold, v-threshold } — the ratio of dark pixels below which an edge gets detected, measured relative to maximum blackness while counting from the start coordinate heading towards one edge. (default: 0.1)
• -mm, --mask-scan-minimum w, h — the minimum allowed size of an auto-detected mask. Masks detected below this size get ignored and set to the size given by mask-scan-maximum. (default: 100,100)
• -mM, --mask-scan-maximum w, h — the maximum allowed size of an auto-detected mask. Masks detected above this get shrunk down to the maximum value, each direction individually. (default: sheet size, or the page size derived from --layout)
• -mc, --mask-color color — the color value used to wipe out pixels not covered by any mask. Handy for testing so you can actually visualize what the masking is doing. (Note that an RGB-value is expected: R*65536 + G*256 + B.) 🌈
• -dn, --deskew-scan-direction { left | top | right | bottom },... — which edges to scan for rotation. Each edge of a mask can be used to detect that mask's rotation. If you give multiple edges, the average value gets used — unless the statistical deviation exceeds --deskew-scan-deviation. Use left to scan from the left edge, top from the top edge, right from the right edge, bottom from the bottom. Multiple directions go comma-separated. (default: left,right)
• -ds, --deskew-scan-size pixels — size of the virtual line used for rotation detection. (default: 1500)
• -dd, --deskew-scan-depth ratio — how many dark pixels to accumulate before scanning stops, relative to the scan-bar size. (default: 0.5)
• -dr, --deskew-scan-range degrees — the range it searches for rotation in, from -degrees to +degrees. (default: 5.0)
• -dp, --deskew-scan-step degrees — the steps between single rotation-angle detections. Lower numbers = better results but slower processing, the classic tradeoff 😭 (default: 0.1)
• -dv, --deskew-scan-deviation deviation — the maximum statistical deviation allowed among results from the detected edges. If it's exceeded, no rotation happens. (default: 1.0)
• -W, --wipe left, top, right, bottom — manually wipe out an area. Every pixel in a wiped area gets set to white. Multiple --wipe areas are allowed. This is applied after deskewing and before automatic border-scan. 🧹
• -mw, --middle-wipe { size | left, right } — if --layout is set to double, this lets you specify the size of a middle area to wipe out between the two pages on the sheet. Genuinely useful when the blackfilter fails to remove some black areas — like stuff resulting from photo-copying right in the middle between two pages. (iykyk)
• -B, --border left, top, right, bottom — manually add a border. Any pixel in the border area gets set to white. Applied after deskewing and before automatic border-scan.
• -Bn, --border-scan-direction { v | h | v,h } — directions to search for the outer border in. You can specify v (vertical mirroring), h (horizontal mirroring), or v,h (both). (default: v)
• -Bs, --border-scan-size { size | h-size, v-size } — width of the virtual bar used for border detection. Two values let you set horizontal and vertical size individually. (default: 5,5)
• -Bp, --border-scan-step { step | h-step, v-step } — steps used to move the virtual bar for border detection. (default: 5,5)
• -Bt, --border-scan-threshold threshold — the absolute number of dark pixels covered by the border-scan mask above which a border gets detected. (default: 5)
• -Ba, --border-align { left | top | right | bottom } — the direction to shift the detected border-area in. Use --border-margin to specify the horizontal and vertical distances to keep from the sheet-edge. (default: none)
• -Bm, --border-margin vertical, horizontal — the distance to keep from the sheet edge when aligning a border area. Measurement suffices like cm and in are allowed. 📏
• -w, --white-threshold threshold — brightness ratio above which a pixel counts as white. (default: 0.9)
• -b, --black-threshold threshold — brightness ratio below which a pixel counts as black (non-gray). This one is used by the gray-filter and the blackfilter. It's also used when converting a grayscale image to black-and-white mode. (default: 0.33)
• -ip, --input-pages { 1 | 2 } — if you set it to 2, it reads two input images instead of one and internally combines them into a doubled-layout sheet before any further processing. Before that internal combining happens, --pre-rotation is optionally applied individually to both input images as the very first processing steps.
• -op, --output-pages { 1 | 2 } — if you set it to 2, it writes two output images instead of one, as a result of splitting a doubled-layout sheet after processing. After the sheet gets split, --post-rotation is optionally applied individually to both output images as the very last processing step. ✨
• -S, --sheet-size { width, height | size-name } — forces a fixed sheet size. Normally the sheet size comes from the input image size (if input-pages=1), or from the double size of the first page in a two-page input set (if input-pages=2). If the input image is smaller than the size you specify here, it shows up centered and surrounded with a white border on the sheet. If the input image is bigger, it gets centered and the edges get cropped. This option can also help you get regular sized output images when your input image sizes differ. Standard size-names like a4-landscape, letter, etc. may be used (see --size). (default: as in input file)
• --sheet-background { black | white } — sets a color that fills the sheet before any image is loaded and placed onto it. Great when the sheet size and the image size differ. 🎨
• --no-blackfilter sheet-range — disables black area scan. Individual sheet indices can be specified.
• --no-noisefilter sheet-range — disables the noisefilter. Individual sheet indices can be specified.
• --no-blurfilter sheet-range — disables the blurfilter. Individual sheet indices can be specified.
• --no-grayfilter sheet-range — disables the grayfilter. Individual sheet indices can be specified.
• --no-mask-scan sheet-range — disables mask-detection. Masks you set explicitly with --mask still have effect, so those don't get thrown out. Individual sheet indices can be specified.
• --no-mask-center sheet-range — disables auto-centering of each mask. Auto-centering is performed by default if the --layout option has been set. Individual sheet indices can be specified.
• --no-deskew sheet-range — disables deskewing. Individual sheet indices can be specified.
• --no-wipe sheet-range — disables explicit wipe-areas. Meaning: the effect of the --wipe parameter can be turned off individually per sheet.
• --no-border sheet-range — disables explicitly set borders. Meaning: the effect of the --border parameter can be turned off individually per sheet.
• --no-border-scan sheet-range — disables border-scanning from the edges of the sheet. Individual sheet indices can be specified.
• --no-border-align sheet-range — disables aligning of the area detected by border-scanning (see --border-align). Individual sheet indices can be specified.
• -n, --no-processing sheet-range — do not perform any processing on a sheet except pre/post rotating and mirroring, and file-depth conversions on saving. This option has the same effect as setting all the --no-xxx options together, fr fr. Individual sheet indices can be specified. 💀
• --interpolate { nearest \| linear \| cubic } — sets the interpolation function used for deskewing and stretching, bestie. cubic gives the best image quality, while nearest is the fastest. (default: cubic) ✨
• --no-multi-pages — turns off multi-page processing even if the input filename contains a % (which usually means “hey, placeholder for the page counter starts here”). 🫶
• --dpi dpi — dots per inch used when converting measured size values, like e.g. 21cm,27.9cm. Mind that this parameter should occur before specifying any size value with a measurement suffix. (default: 300) 💅
• -t { pbm \| pgm \| ppm }; --type { pbm \| pgm> \| ppm } — the output file type (and bit depth). If you don’t specify it, the one with the same, or closest, pixel format as the original input files gets used. 🎀
  • pbm — Portable Bit Map, monochrome raw image.
  • pgm — Portable Grayscale Map, 8-bit per pixel grayscale raw image.
  • ppm — Portable Pixel Map, 24-bit per pixel RGB raw image.
• -T; --test-only — do not write any output. May be useful in combination with --verbose to get information about the input. 👀
• -si nr; --start-input nr — set the first page number to substitute for %d in input filenames. Every time the input file sequence is repeated, this number gets increased by 1. (default: (startsheet-1)*inputpages+1) 🌸
• -so nr; --start-output nr — set the first page number to substitute for %d in output filenames. Every time the output file sequence is repeated, this number gets increased by 1. (default: (startsheet-1)*outputpages+1) 🌈
• --insert-blank nr [,nr...] — use blank input instead of an input file from the input file sequence at the specified index-positions. The input file sequence will be interrupted temporarily and will continue with the next input file afterwards. This can be useful to insert blank content into a sequence of input images. 🦋
• --replace-blank nr [,nr...] — like --insert-blank, but the input images at the specified index positions get replaced with blank content and thus will be ignored. 💀
• --overwrite — allow overwriting existing files. Otherwise the program terminates with an error if an output file to be written already exists. 😭
• -q; --quiet — quiet mode, no output at all. 🤫
• -v; --verbose — verbose output, more info messages. 🗣️
• -vv — even more verbose output, show parameter settings before processing. 🔍
• -V; --version — output version and build information. 👑

---

👑 AUTHOR 👑

The unpaper authors. 🫶

💖 COPYRIGHT 💖

2020, The unpaper Authors 🌸

---

okay bestie, that’s the whole UNPAPER(1) page — source/version UNPAPER(1), dated May 05, 2022 — go forth and unpaper slay 💅✨🎀