about summary refs log tree commit diff
path: root/pamtilt.html
blob: 7b51a679ce2880201165aaa95cfe194729960d3a (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML><HEAD><TITLE>Pamtilt User Manual</TITLE></HEAD>
<BODY>
<H1>pamtilt</H1>
Updated: 28 August 2005
<BR>
<A HREF="#index">Table Of Contents</A>

<H2>NAME</H2>
pamtilt - print the tilt angle of a PGM file

<H2 id="synopsis">SYNOPSIS</H2>

<b>pamtilt</b>
[<b>-angle=</b><i>maxangle</i>]
[<b>-fast</b>]
[<b>-quality=</b><i>q</i>]
[<b>-hstep=</b><i>n</i>]
[<b>-vstep=</b><i>n</i>]
<br>
[<b>-dstep=</b><i>n</i>]
[<b>-astep=</b><i>n</i>]
[<b>-verbose</b>]
[<i>pgmfile</i>]

<h2 id="examples">EXAMPLES</h2>

<pre>
<kbd>
    scanimage --mode Gray --resolution 300 >crooked.pgm
    pnmrotate -b white `pamtilt crooked.pgm` crooked.pgm >straight.pgm
</kbd>
    (then crop, threshold, etc.)
</pre>

<H2 id="description">DESCRIPTION</H2>

<p>This program is part of <a href="index.html">Netpbm</a>.

<p><b>pamtilt</b> 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.

<p>"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.  <b>pamtilt</b> aims to help correct that.

<p><b>pamtilt</b> makes three iterations at successively finer
increments, testing prospective rotation angles to find the best one.
<b>pamtilt</b> works best for straightening images with strong
horizontal lines and does poorly with arbitrary photos.  If
<b>pamtilt</b> 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.

<p><b>pamtilt</b> 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.

<p><b>pamtilt</b> 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.
        
<H2 id="options">OPTIONS</H2>

<p>A few options have general utility:

<DL COMPACT>

<dt><b>-angle=</b><i>maxangle</i>

<dd>
Assume a maximum tilt angle of <i>maxangle</i> (measured in degrees).
The default value is sufficient for most images, even those scanned
somewhat carelessly.

<p>The default is 10.0.

<dt><b>-fast</b>

<dd>
Skip the third iteration for speed at the expense of accuracy.

<dt><b>-verbose</b>
<dd>
Show on Standard Error the measurements computed at each tested angle.

</dl>

<p>Here are some other options you can use to tune the operation of
<b>pamtilt</b> but they're seldom needed.  The default values
accommodate a wide variety of input documents.

<dl>
<DT>
<B>-quality=</B><i>q</i>

<dd>Require a signal-to-noise ratio of a least <i>q</i> 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.

<p>The default is 1.0.

<dt><b>-hstep=</b><i>n</i>
<dd>
Set the horizontal increment to check every <i>n</i>th column.  This
value affects both run time and memory requirements.

<p>The default is 11.

<dt><b>-vstep=</b><i>n</i>

<dd>
Set the vertical increment to check every nth row.  Larger values
usually work, reducing run time, but they increase the risk of
incorrect results.

<p>The default is 5.

<dt><b>-dstep=</b><i>n</i>

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

<p>The default is 2.

<dt><b>-astep=</b><i>n</i>

<dd>
Set the angle increment of the first iteration, in degrees.

<p>The default is 1.0.

</dl>


<h2 id="references">REFERENCES</h2>

<p><B>pamtilt</B> 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.

<h2 id="seealso">SEE ALSO</h2>

<ul>
<li><a href="pnmrotate.html"><b>pnmrotate</b></a>
<li><a href="pgm.html">pgm</a>
</ul>

<h2 id="history">HISTORY</h2>

<p><b>pamtilt</b> was new in Netpbm 10.30 (October 2005).

<p>Gregg Townsend wrote it and sent it to Bryan Henderson in August
2005.  Bryan recoded it to fit Netpbm conventions.

<HR>
<H2 id="index">Table Of Contents</H2>
<UL>
<LI><A HREF="#synopsis">SYNOPSIS</A>
<LI><A HREF="#examples">EXAMPLES</A>
<LI><A HREF="#description">DESCRIPTION</A>
<LI><A HREF="#options">OPTIONS</A>
<LI><A HREF="#seealso">SEE ALSO</A>
<LI><A HREF="#history">HISTORY</A>
</UL>
</BODY>
</HTML>