.\"                                      Hey, EMACS: -*- nroff -*-
.TH UNPAPER 1 "December 31, 2007"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
unpaper \- post-processing tool for scanned pages

.SH SYNOPSIS
.B unpaper
.RI [options] " input-file(s) output-file(s)

.SH DESCRIPTION

\fBunpaper\fP is a post-processing tool for scanned sheets of paper,
especially for book pages that have been 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).

.SH OPTIONS

Filenames may contain a formatting placeholder starting with \fI%\fP to insert a
page counter for multi-page processing. E.g.: \fIscan%03d.pbm\fP to process files
\fBscan001.pbm\fP, \fBscan002.pbm\fP, \fBscan003.pbm\fP etc.

.TP
.B \-l, \-\-layout \fIsingle\fP|\fIdouble\fP|\fInone\fP
Set default layout options for a sheet:
.sp 1
\fIsingle\fP: One page per sheet.
.sp 1
\fIdouble\fP: Two pages per sheet, landscape orientation (one
page on the left half, one page on the right half).
.sp 1
\fInone\fP: No auto-layout, mask-scan-points may individually be
specified.
.sp 1
Using \fIsingle\fP or \fIdouble\fP automatically sets corresponding
\fB\-\-mask\-scan\-points\fP. The default is \fIsingle\fP.

.TP
.B \-start, \-\-start\-sheet \fI<sheet>\fP
Number of first sheet to process in multi-sheet mode. (default: \fI1\fP)

.TP
.B \-end, \-\-end\-sheet \fI<sheet>\fP
Number of last sheet to process in multi-sheet mode. \fI-1\fP indicates
processing until no more input file with the corresponding page number
is available. (default: \fI-1\fP)

.TP
.B \-#, \-\-sheet \fI<sheet>\fP{\fI,<sheet>\fP[\fI-<sheet>\fP]}
Optionally specifies which sheets to process in the range between
\fBstart\-sheet\fP and \fBend\-sheet\fP.

.TP
.B \-x, \-\-exclude \fI<sheet>\fP{\fI,<sheet>\fP[\fI-<sheet>\fP]}
Excludes sheets from processing in the range between
\fBstart\-sheet\fP and \fBend-sheet\fP.

.TP
.B \-\-pre\-rotate \fI\-90\fP|\fI90\fP
Rotates the whole image clockwise (\fI90\fP) or counter-clockwise
(\fI-90\fP) before any other processing.

.TP
.B \-\-post\-rotate \fI-90\fP|\fI90\fP
Rotates the whole image clockwise (\fI90\fP) or counter-clockwise
(\fI-90\fP) after any other processing.

.TP
.B \-M, \-\-pre\-mirror [\fIv\fP[\fIertical\fP]][\fI,\fP][\fIh\fP[\fIorizontal\fP]]
Mirror the image, after possible pre-rotation. Either \fIv\fP (for
vertical mirroring), \fIh\fP (for horizontal mirroring) or \fIv,h\fP
(for both) can be specified.

.TP
.B \-\-post\-mirror [\fIv\fP[\fIertical\fP]][\fI,\fP][\fIh\fP[\fIorizontal\fP]]
Mirror the image, after any other processing except possible
post-rotation.

.TP
.B \-\-pre\-shift \fI<h>,<v>\fP
Shift the image before further processing. Values for \fIh\fP (horizontal
shift) and \fIv\fP (vertical shift) can either be positive or negative.

.TP
.B \-\-post\-shift \fI<h>,<v>\fP
Shift the image after other processing. Values for \fIh\fP (horizontal
shift) and \fIv\fP (vertical shift) can either be positive or negative.

.TP
.B \-\-pre\-wipe \fI<left>,<top>,<right>,<bottom>\fP
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.

.TP
.B \-\-post\-wipe \fI<left>,<top>,<right>,<bottom>\fP
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.

.TP
.B \-\-pre\-border \fI<left>,<top>,<right>,<bottom>\fP
Clear the border-area of the sheet before further processing. Any
pixel in the border area will be set to white.

.TP
.B \-\-post\-border \fI<left>,<top>,<right>,<bottom>\fP
Clear the border-area after processing. Any pixel in the border area
will be set to white.

.TP
.B \-\-pre\-mask \fI<x1>,<y1>,<x2>,<y2>\fP
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
\fB\-\-pre\-mask\fP.

.TP
.B \-s, \-\-size \fI<width>,<height>\fP|\fI<size-name>\fP
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. Size-name can also be a
standard name as \fIa4\fP, \fIletter\fP, etc.
Possible size names are:
.sp 1
\fIa5\fP
.br
\fIa4\fP
.br
\fIa3\fP
.br
\fIletter\fP
.br
\fIlegal\fP
.sp 1
All size names can also be applied in
rotated landscape orientation, use
\fIa4\-landscape\fP, \fIletter\-landscape\fP etc.

.TP
.B \-\-post\-size \fI<width>,<height>\fP|\fI<name>\fP
Change the sheet size preserving the content's aspect ratio after
other processing steps are applied.

.TP
.B \-\-stretch \fI<width>,<height>\fP|\fI<name>\fP
Change the sheet size before other processing is applied. Content on
the sheet gets stretched to the specified size, possibly changing the
aspect ratio.

.TP
.B \-\-post\-stretch \fI<width>,<height>\fP|\fI<name>\fP
Change the sheet size after other processing is applied. Content on
the sheet gets stretched to the specified size, possibly changing the
aspect ratio.

.TP
.B \-z, \-\-zoom \fI<factor>\fP
Change the sheet size according to the given factor before other
processing is done.

.TP
.B \-\-post\-zoom \fI<factor>\fP
Change the sheet size according to the given factor after processing
is done.

.TP
.B \-bn, \-\-blackfilter\-scan\-direction [\fIv\fP[\fIertical\fP]][\fI,\fP][\fIh\fP[\fIorizontal\fP]]
Directions in which to search for solidly black areas. Either \fIv\fP
(for vertical scanning), \fIh\fP (for horizontal scanning) or
\fIv,h\fP (for both) can be specified. (default: \fIv,h\fP)

.TP
.B \-bs, \-\-blackfilter\-scan\-size \fI<size>\fP|\fI<h-size>,<v-size>\fP
Width of virtual bar used for mask detection. Two values may be
specified to individually set horizontal and vertical size. (default:
\fI20,20\fP)

.TP
.B \-bd, \-\-blackfilter\-scan\-depth \fI<depth>\fP|\fI<h-depth,v-depth>\fP
Size of virtual bar used for black area detection. (default:
\fI500,500\fP)

.TP
.B \-bp, \-\-blackfilter\-scan\-step \fI<step>\fP|\fI<h-step,v-step>\fP
Steps to move virtual bar for black area detection. (default: \fI5,5\fP)

.TP
.B \-bt, \-\-blackfilter\-scan\-threshold \fI<t>\fP
Ratio of dark pixels above which a black area gets detected. (default:
\fI0.95\fP)

.TP
.B \-bx, \-\-blackfilter\-scan\-exclude \fI<left>,<top>,<right>,<bottom>\fP
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.

.TP
.B \-bi, \-\-blackfilter-intensity \fI<i>\fP
Intensity with which to delete black areas. Larger values will leave
less noise-pixels around former black areas, but may delete page
content. (default: \fI20\fP)

.TP
.B \-ni, \-\-noisefilter\-intensity \fI<n>\fP
Intensity with which to delete individual pixels or tiny clusters of
pixels. Any cluster which only contains n dark pixels together will be
deleted. (default: \fI4\fP)

.TP
.B \-ls, \-\-blurfilter\-size \fI<size>\fP|\fI<h-size>,<v-size>\fP
Size of blurfilter area to search for 'lonely' clusters of
pixels. (default: \fI100,100\fP)

.TP
.B \-lp, \-\-blurfilter\-step \fI<step>\fP|\fI<h-step>,<v-step>\fP
Size of 'blurring' steps in each direction. (default: \fI50,50\fP)

.TP
.B \-li, \-\-blurfilter\-intensity \fI<ratio>\fP
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: \fI0.01\fP)

.TP
.B \-gs, \-\-grayfilter\-size \fI<size>\fP|\fI<h-size>,<v-size>\fP
Size of grayfilter mask to search for 'gray-only' areas of
pixels. (default: \fI50,50\fP)

.TP
.B \-gp, \-\-grayfilter\-step \fI<step>\fP|\fI<h-step>,<v-step>\fP
Size of steps moving the grayfilter mask in each direction. (default:
\fI20,20\fP)

.TP
.B \-gt, \-\-grayfilter\-threshold \fI<ratio>\fP
Relative intensity of grayness which is accepted before clearing the
grayfilter mask in cases where no black pixel is found in the
mask. (default: \fI0.5\fP)

.TP
.B \-p, \-\-mask\-scan\-point \fI<x>,<y>\fP
Manually set starting point for mask-detection. Multiple
\fB\-\-mask\-scan\-point\fP options may be specified to detect
multiple masks.

.TP
.B \-m, \-\-mask \fI<x1>,<y1>,<x2>,<y2>\fP
Manually add a mask, in addition to masks automatically detected
around the \fB\-\-mask\-scan\-point\fP coordinates (unless
\fB\-\-no\-mask\-scan\fP is specified). Any pixel outside a mask will
be set to white, unless another mask covers this pixel.

.TP
.B \-mn, \-\-mask\-scan\-direction [\fIv\fP[\fIertical\fP]][\fI,\fP][\fIh\fP[\fIorizontal\fP]]
Directions in which to search for mask borders, starting from
\fB\-\-mask\-scan\-point\fP coordinates. Either \fIv\fP (for vertical
scanning), \fIh\fP (for horizontal scanning) or \fIv,h\fP (for both)
can be specified. (default: \fIh\fP (\fIv\fP may cut text-paragraphs
on single-page sheets))

.TP
.B \-ms, \-\-mask\-scan\-size \fI<size>\fP|\fI<h,v>\fP
Width of the virtual bar used for mask detection. Two values may be
specified to individually set horizontal and vertical size. (default:
\fI50,50\fP)

.TP
.B \-md, \-\-mask\-scan\-depth \fI<dep>\fP|\fI<h,v>\fP
Height of the virtual bar used for mask detection. (default:
\fI-1,-1\fP, using the total width or height of the sheet)

.TP
.B \-mp, \-\-mask\-scan\-step \fI<step>\fP|\fI<h,v>\fP
Steps to move the virtual bar for mask detection. (default: \fI5,5\fP)

.TP
.B \-mt, \-\-mask\-scan\-threshold \fI<t>\fP|\fI<h,v>\fP
Ratio of dark pixels below which an edge gets detected, relative to
max. blackness when counting from the start coordinate heading towards
one edge. (default: \fI0.1\fP)

.TP
.B \-mm, \-\-mask\-scan\-minimum \fI<w>,<h>\fP
Minimum allowed size of an auto-detected mask. Masks detected below
this size will be ignored and set to the size specified by
mask-scan-maximum. (default: \fI100,100\fP)

.TP
.B \-mM, \-\-mask\-scan\-maximum \fI<w>,<h>\fP
Maximum allowed size of an auto-detected mask. Masks detected above
this size will be shrunk to the maximum value, each direction
individually. (default: sheet size, or page size derived from
\fB\-\-layout\fP option)

.TP
.B \-mc, \-\-mask\-color \fI<color>\fP
Color value with which to wipe out pixels not covered by any
mask. Maybe useful for testing in order to visualize the effect of
masking. (Note that an RGB-value is expected: R*65536 + G*256 + B)

.TP
.B \-dn, \-\-deskew\-scan\-direction \fI<left>,<top>,<right>,<bottom>\fP
Edges from which to scan for rotation. Each edge of a mask can be used
to detect the mask's rotation. If multiple edges are specified, the
average value will be used, unless the statistical deviation exceeds
\fB\-\-deskew\-scan\-deviation\fP. Use \fIleft\fP for scanning from
the left edge, \fItop\fP for scanning from the top edge, \fIright\fP
for scanning from the right edge, \fIbottom\fP for scanning from the
bottom. Multiple directions can be separated by commas. (default:
\fIleft,right\fP)

.TP
.B \-ds, \-\-deskew\-scan\-size \fI<pixels>\fP
Size of virtual line for rotation detection. (default: \fI1500\fP)

.TP
.B \-dd, \-\-deskew\-scan\-depth \fI<ratio>\fP
Amount of dark pixels to accumulate until scanning is stopped,
relative to scan-bar size. (default: \fI0.5\fP)

.TP
.B \-dr, \-\-deskew\-scan\-range \fI<degrees>\fP
Range in which to search for rotation, from \fI-degrees\fP to
\fI+degrees\fP rotation. (default: \fI5.0\fP)

.TP
.B \-dp, \-\-deskew\-scan\-step \fI<degrees>\fP
Steps between single rotation-angle detections. Lower numbers lead to
better results but slow down processing. (default: \fI0.1\fP)

.TP
.B \-dv, \-\-deskew\-scan\-deviation \fI<dev>\fP
Maximum statistical deviation allowed among the results from detected
edges. No rotation if exceeded. (default: \fI1.0\fP)

.TP
.B \-W, \-\-wipe \fI<left>,<top>,<right>,<bottom>\fP
Manually wipe out an area. Any pixel in a wiped area will be set to
white. Multiple \fB\-\-wipe\fP areas may be specified. This is applied
after deskewing and before automatic border-scan.

.TP
.B \-mw, \-\-middle\-wipe \fI<size>\fP|\fI<left>,<right>\fP
If \fB\-\-layout\fP is set to \fIdouble\fP, this may specify the size
of a middle area to wipe out between the two pages on the sheet. This
may be useful if the blackfilter fails to remove some black areas
(e.g. resulting from photo-copying in the middle between two pages).

.TP
.B \-B, \-\-border \fI<left>,<top>,<right>,<bottom>\fP
Manually add a border. Any pixel in the border area will be set to white. This is
applied after deskewing and before automatic border-scan.

.TP
.B \-Bn, \-\-border\-scan\-direction [\fIv\fP[\fIertical\fP]][,][\fIh\fP[\fIorizontal\fP]]
Directions in which to search for outer border. Either \fIv\fP (for
vertical scanning), \fIh\fP (for horizontal scanning) or \fIv,h\fP
(for both) can be specified. (default: \fIv\fP)

.TP
.B \-Bs, \-\-border\-scan\-size \fI<size>\fP|\fI<h,v>\fP
Width of virtual bar used for border detection. Two values may be
specified to individually set horizontal and vertical size. (default:
\fI5,5\fP)

.TP
.B \-Bp, \-\-border\-scan\-step \fI<step>\fP|\fI<h,v>\fP
Steps to move virtual bar for border detection. (default: \fI5,5\fP)

.TP
.B \-Bt, \-\-border\-scan\-threshold \fI<t>\fP
Absolute number of dark pixels covered by the border-scan mask above
which a border is detected. (default: \fI5\fP)

.TP
.B \-Ba, \-\-border\-align \fI<left>,<top>,<right>,<bottom>\fP
Direction where to shift the detected border-area. Use
\fB\-\-border\-margin to specify horizontal and vertical distances to
be kept from the sheet-edge. (default: \fInone\fP)

.TP
.B \-Bm, \-\-border\-margin \fI<vertical>,<horizontal>\fP
Distance to keep from the sheet edge when aligning a border area. May
use measurement suffices such as \fIcm\fP, \fIin\fP.

.TP
.B \-w, \-\-white\-threshold \fI<threshold>\fP
Brightness ratio above which a pixel is considered white. (default:
\fI0.9\fP)

.TP
.B \-b, \-\-black\-threshold \fI<threshold\fP>
Brightness ratio below which a pixel is considered black
(non-gray). This is used by the gray-filter. This value is also used
when converting a grayscale image to black-and-white mode (default:
\fI0.33\fP)

.TP
.B \-ip, \-\-input\-pages \fI1\fP|\fI2\fP
If \fI2\fP is specified, read two input images instead of one and
internally combine them to a doubled-layout sheet before further
processing. Before internally combining, \fB\-\-pre\-rotation\fP is
optionally applied individually to both input images as the very first
processing steps.

.TP
.B \-op, \-\-output\-pages \fI1\fP|\fI2\fP
If \fI2\fP is specified, write two output images instead of one, as a
result of splitting a doubled-layout sheet after processing. After
splitting the sheet, \fB\-\-post\-rotation\fP is optionally applied
individually to both output images as the very last processing step.

.TP
.B \-S, \-\-sheet\-size \fI<width>,<height>\fP|\fI<size-name>\fP
Force a fix sheet size. Usually, the sheet size is determined by the
input image size (if \fBinput\-pages\fP=\fI1\fP), or by the double
size of the first page in a two-page input set (if
\fBinput\-pages\fP=\fI2\fP). If the input image is smaller than the
size specified here, it will appear centered and surrounded with a
white border on the sheet. If the input image is bigger, it will be
centered and the edges will be cropped. This option may also be
helpful to get regular sized output images if the input image sizes
differ. Standard size-names like \fIa4\-landscape\fP, \fIletter\fP,
etc. may be used (see \fB\-\-size\fP). (default: as in input file)

.TP
.B \-\-sheet\-background \fIblack\fP|\fIwhite\fP
Sets a color with which the sheet is filled before any image is loaded
and placed onto it. This can be useful when the sheet size and the
image size differ.

.TP
.B \-\-no\-blackfilter \fI<sheet>\fP{\fI,<sheet>\fP[\fI\-<sheet>\fP]}
Disables black area scan. Individual sheet indices can be specified.

.TP
.B \-\-no\-noisefilter \fI<sheet>\fP{\fI,<sheet>\fP[\fI\-<sheet>\fP]}
Disables the noise filter. Individual sheet indices can be specified.

.TP
.B \-\-no\-blurfilter \fI<sheet>\fP{\fI,<sheet>\fP[\fI\-<sheet>\fP]}
Disables the blur filter. Individual sheet indices can be specified.

.TP
.B \-\-no\-grayfilter \fI<sheet>\fP{\fI,<sheet>\fP[\fI\-<sheet>\fP]}
Disables the gray filter. Individual sheet indices can be specified.

.TP
.B \-\-no\-mask\-scan \fI<sheet>\fP{\fI,<sheet>\fP[\fI\-<sheet>\fP]}
Disables mask-detection. Masks explicitly set by \fB\-\-mask\fP will
still have effect. Individual sheet indices can be specified.

.TP
.B \-\-no\-mask\-center \fI<sheet>\fP{\fI,<sheet>\fP[\fI\-<sheet>\fP]}
Disables auto-centering of each mask. Auto-centering is performed by
default if the \fB\-\-layout\fP option has been set. Individual sheet
indices can be specified.

.TP
.B \-\-no\-deskew \fI<sheet>\fP{\fI,<sheet>\fP[\fI\-<sheet>\fP]}
Disables deskewing. Individual sheet indices can be specified.

.TP
.B \-\-no\-wipe \fI<sheet>\fP{\fI,<sheet>\fP[\fI\-<sheet>\fP]}
Disables explicit wipe-areas. This means the effect of parameter
\fB\-\-wipe\fP can be disabled individually per sheet.

.TP
.B \-\-no\-border \fI<sheet>\fP{\fI,<sheet>\fP[\fI\-<sheet>\fP]}
Disables explicitly set borders. This means the effect of parameter
\fB\-\-border\fP can be disabled individually per sheet.

.TP
.B \-\-no\-border\-scan \fI<sheet>\fP{\fI,<sheet>\fP[\fI\-<sheet>\fP]}
Disables border-scanning from the edges of the sheet. Individual sheet
indices can be specified.

.TP
.B \-\-no\-border\-align \fI<sheet>\fP{\fI,<sheet>\fP[\fI\-<sheet>\fP]}
Disables aligning of the area detected by border-scanning (see
\fB\-\-border\-align\fP). Individual sheet indices can be specified.

.TP
.B \-n, \-\-no\-processing \fI<sheet>\fP{\fI,<sheet>\fP[\fI\-<sheet>\fP]}
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 \fB\-\-no\-xxx\fP options
together. Individual sheet indices can be specified.

.TP
.B \-\-no\-qpixels
Disable qpixel-mode for deskewing (do not internally use a 4x bigger
image when rotating).

.TP
.B \-\-no\-multi\-pages
Disable multi-page processing even if the input filename contains a
'%' (usually indicating the start of a placeholder for the page
counter).

.TP
.B \-\-dpi \fI<dpi>\fP
Dots per inch used for conversion of measured size values, like
e.g. \fI21cm,27.9cm\fP. Note that this parameter should occur before
specifying any size value with measurement suffix. (default:
\fI300\fP)

.TP
.B \-t, \-\-type \fIpbm\fP|\fIpgm\fP
Output file type. (default: as input)

.TP
.B \-d, \-\-depth \fI<bits>\fP
Output pixel depth. (default: as input)

.TP
.B \-T, \-\-test\-only
Do not write any output. May be useful in combination with
\fB\-\-verbose\fP to get information about the input.

.TP
.B \-in, \-\-input\-file\-sequence \fI<file-patterns>\fP
Sequence of input filename patterns which is repeatedly traversed
while resolving input filenames. Specifying a single entry is
equivalent to the first filename argument after the options-list.

.TP
.B \-out, \-\-output\-file\-sequence \fI<file-patterns>\fP
Sequence of output filename patterns which is repeatedly traversed
while resolving output filenames. Specifying a single entry is
equivalent to the second filename argument after the options-list.

.TP
.B \-si, \-\-start\-input \fI<nr>\fP
Set the first page number to substitute for \fI%d\fP in input
filenames. Every time the input file sequence is repeated, this number
gets increased by 1. (default: (startsheet-1)*inputpages+1)

.TP
.B \-so, \-\-start\-output \fI<nr>\fP
Set the first page number to substitute for \fI%d\fP in output
filenames. Every time the output file sequence is repeated, this
number gets increased by 1. (default: (startsheet-1)*outputpages+1)

.TP
.B \-\-insert\-blank \fI<nr>\fP{\fI,<nr>\fP[\fI-<nr>\fP]}
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.

.TP
.B \-\-replace\-blank \fI<nr>\fP{\fI,<nr>\fP[\fI-<nr>\fP]}
Like \fB\-\-insert\-blank\fP, but the input images at the specified
index positions get replaced with blank content and thus will be
ignored.

.TP
.B \-\-overwrite
Allow overwriting existing files. Otherwise the program terminates
with an error if an output-file to be written already exists.

.TP
.B \-q, \-\-quiet
Quiet mode, no output at all.

.TP
.B \-v, \-\-verbose
Verbose output, more info messages.

.TP
.B \-vv
Even more verbose output, show parameter settings before processing.

.TP
.B \-\-time
Output processing time consumed.

.TP
.B \-V, \-\-version
Output version and build information.


.SH AUTHOR
unpaper was written by Jens Gulden <unpaper@jensgulden.de>.
.PP
This manual page was written by Julien BLACHE <jblache@debian.org>,
for the Debian project (but may be used by others).