.TL
Pamtilt User Manual
.SH 1
pamtilt
.LP
Updated: 28 August 2005
.br
Table Of Contents
.SH 2
NAME
.LP
pamtilt - print the tilt angle of a PGM file
.SH 2
SYNOPSIS
.LP
\fBpamtilt\fR
[\fB-angle=\fR\fImaxangle\fR]
[\fB-fast\fR]
[\fB-quality=\fR\fIq\fR
[\fB-hstep=\fR\fIn\fR]
[\fB-vstep=\fR\fIn\fR]
.br
[\fB-dstep=\fR\fIn\fR]
[\fB-astep=\fR\fIn\fR]
[\fB-verbose\fR]
[\fIpgmfile\fR]
.SH 2
EXAMPLES
.LP
.DS L
\f(CW    scanimage --mode Gray --resolution 300 >crooked.pgm
    pnmrotate -b white `pamtilt crooked.pgm` crooked.pgm >straight.pgm
\fR    (then crop, threshold, etc.)
.DE
.SH 2
DESCRIPTION
.LP
.LP
This program is part of Netpbm.
.LP
\fBpamtilt\fR tries to find the correct angle for untilting
(de-skewing) a scanned text document.  The output is a single
floating-point number (the angle in degrees) for use as the argument
to pnmrotate.
.LP
"Document skew" is the name given to what happens when
you feed a page into an image scanner at an angle: the resulting image
is tilted.  \fBpamtilt\fR aims to correct that.
.LP
\fBpamtilt\fR makes three iterations at successively finer
increments, testing prospective rotation angles to find the best one.
\fBpamtilt\fR works best for straightening images with strong
horizontal lines and does poorly with arbitrary photos.  If
\fBpamtilt\fR has no confidence in its results, it prints the special
value 00.00; you can check for this or just pass it as a legal
argument to pnmrotate.
.LP
\fBpamtilt\fR operates on the first plane of the input image,
which is either PNM or PAM, and ignores any other planes.  Ordinarily,
the input is PGM or GRAYSCALE PAM, so there is only one plane.
.LP
\fBpamtilt\fR works on bilevel (PBM, BLACKANDWHITE PAM) images as
well as grayscale, but you will minimize artifacts if you scan and
rotate in grayscale before you apply a threshold to make a bilevel
image.
.SH 2
OPTIONS
.LP
.LP
A few options have general utility:
.RS
.IP "\fB-angle=\fR\fImaxangle\fR"
Assume a maximum tilt angle of \fImaxangle\fR (measured in degrees).
The default value is sufficient for most images, even those scanned
somewhat carelessly.
.LP
The default is 10.0.
.IP "\fB-fast\fR"
Skip the third iteration for speed at the expense of accuracy.
.IP "\fB-verbose\fR"
Show on Standard Error the measurements computed at each tested angle.
.RE
.LP
Here are some other options you can use to tune the operation of
\fBpamtilt\fR but they're seldom needed.  The default values
accommodate a wide variety of input documents.
.RS
.IP ""\fB-quality=\fR\fIq\fR
Require a signal-to-noise ratio of a least \fIq\fR on the first
iteration to report a valid result.  Larger values reduce the chances
of obtaining a bogus result at the risk of obtaining no result at all.
.LP
The default is 1.0.
.IP "\fB-hstep=\fR\fIn\fR"
Set the horizontal increment to check every \fIn\fRth column.  This
value affects both run time and memory requirements.
.LP
The default is 11.
.IP "\fB-vstep=\fR\fIn\fR"
Set the vertical increment to check every nth row.  Larger values
usually work, reducing run time, but they increase the risk of
incorrect results.
.LP
The default is 5.
.IP "\fB-dstep=\fR\fIn\fR"
Set the vertical distance used when checking pixels in a column.  The
default is intended to minimize the effect of noise along a horizontal
boundary.
.LP
The default is 2.
.IP "\fB-astep=\fR\fIn\fR"
Set the angle increment of the first iteration, in degrees.
.LP
The default is 1.0.
.RE
.SH 2
REFERENCES
.LP
.LP
\fBpamtilt\fR implements a somewhat simplified algorithm inspired
by: "Measuring Document Image Skew and Orientation", by Bloomberg,
Kopec, and Dasari.  In SPIE Volume 2422, Document Recognition II,
pages 302-316, February 1995.
.SH 2
SEE ALSO
.LP
.IP \(bu
\fBpnmrotate\fR
.IP \(bu
pgm
.LP
.SH 2
HISTORY
.LP
.LP
\fBpamtilt\fR was new in Netpbm 10.30 (October 2005).
.LP
Gregg Townsend wrote it and sent it to Bryan Henderson in August
2005.  Bryan recoded it to fit Netpbm conventions.
.br
\l'5i'
.SH 2
Table Of Contents
.LP
.IP \(bu
NAME
.IP \(bu
SYNOPSIS
.IP \(bu
EXAMPLES
.IP \(bu
DESCRIPTION
.IP \(bu
OPTIONS
.IP \(bu
SEE ALSO
.IP \(bu
HISTORY
.LP