Debian Codegraph @

upstream/debian-unstable/man1/pamperspective.1

raw
1 \
2 .\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
3 .\" Do not hand-hack it! If you have bug fixes or improvements, please find
4 .\" the corresponding HTML page on the Netpbm website, generate a patch
5 .\" against that, and send it to the Netpbm maintainer.
6 .TH "Pamperspective User Manual" 1 "02 September 2004" "netpbm documentation"
7
8 .SH NAME
9
10 pamperspective - a reverse scanline renderer for Netpbm images
11
12 .UN synopsis
13 .SH SYNOPSIS
14
15 .nf
16 \fBpamperspective\fP
17 [\fB--bottom_margin=\fP\fInum\fP]
18 [\fB--detail=\fP\fInum\fP]
19 [\fB--frame_include=\fP\fIbool\fP]
20 [\fB--height=\fP\fInum\fP]
21 [\fB--include=[\fP\fIx1\fP,\fIy1\fP;\fIx2\fP,\fIy2\fP; ...]]
22 [\fB--input_system=\fP\fIspec\fP]
23 [\fB--input_unit=\fP\fIspec\fP]
24 [\fB--interpolation=\fP\fIspec\fP]
25 [\fB--left_margin=\fP\fInum\fP]
26 [\fB--margin=\fP\fInum\fP]
27 [\fB--output_system=\fP\fIspec\fP]
28 [\fB--proportion=\fP\fIspec\fP]
29 [\fB--ratio=\fP\fInum\fP]
30 [\fB--right_margin=\fP\fInum\fP]
31 [\fB--top_margin=\fP\fInum\fP]
32 [\fB--width=\fP\fInum\fP]
33 {
34 {
35 \fIupper_left_x\fP \fIupper_left_y\fP \fIupper_right_x\fP \fIupper_right_y\fP
36 \fIlower_left_x\fP \fIlower_left_y\fP \fIlower_right_x\fP \fIlower_right_y\fP
37 }
38 |
39 {
40 {\fB--upper_left_x\fP|\fB--ulx\fP}\fB=\fP\fIupper_left_x\fP
41 {\fB--upper_left_y\fP|\fB--uly\fP}\fB=\fP\fIupper_left_y\fP
42 {\fB--upper_right_x\fP|\fB--urx\fP}\fB=\fP\fIupper_right_x\fP
43 {\fB--upper_right_y\fP|\fB--ury\fP}\fB=\fP\fIupper_right_y\fP
44 {\fB--lower_left_x\fP|\fB--llx\fP}\fB=\fP\fIlower_left_x\fP
45 {\fB--lower_left_y\fP|\fB--lly\fP}\fB=\fP\fIlower_left_y\fP
46 {\fB--lower_right_x\fP|\fB--lrx\fP}\fB=\fP\fIlower_right_x\fP
47 {\fB--lower_right_y\fP|\fB--lry\fP}\fB=\fP\fIlower_right_y\fP
48 }
49 }
50 [\fIinfile\fP]
51
52
53 .fi
54
55 .SH OPTION USAGE
56 .PP
57 Minimum unique abbreviation of option is acceptable. (But note
58 that shortest unique prefixes might be longer in future versions of
59 the program.) You may use single hyphens instead of double hyphen to
60 denote options. You may use white space in place of the equals sign
61 to separate an option name from its value. All options starting with
62 hyphens may be given in any order.
63
64
65 .UN description
66 .SH DESCRIPTION
67 .PP
68 This program is part of
69 .BR "Netpbm" (1)\c
70 \&.
71 .PP
72 \fBpamperspective\fP reads a Netpbm image as input and produces a
73 Netpbm image of the same format as output.
74 .PP
75 \fBpamperspective\fP interprets the input image as a perspective
76 projection of another image which is in a plane oblique to that of the
77 input image. For example, a photograph of a painting, taken at an
78 angle. The arguments \fIupper_left_x\fP ... \fIlower_right_y\fP
79 specify a quadrilateral in the photograph that \fBpamperspective\fP
80 assumes corresponds to a parallelogram in the painting. The output
81 image consists of this parallelogram, sheared to a rectangle. In this
82 way \fBpamperspective\fP undoes the effect of a raytracer or scanline
83 renderer.
84 .PP
85 Note that if the input image is a projection of a solid scene,
86 rather than a plane, the result is like a different camera angle on
87 that scene, to the extent that the scene is shallow from the other
88 angle.
89 .PP
90 The input is from \fIinfile\fP, or from Standard Input, if
91 \fIinfile\fP is not specified. The output is to Standard Output.
92
93
94 .UN options
95 .SH OPTIONS
96 .PP
97 In addition to the options common to all programs based on libnetpbm
98 (most notably \fB-quiet\fP, see
99 .UR index.html#commonoptions
100 Common Options
101 .UE
102 \&), \fBpamperspective\fP recognizes the following
103 command line options:
104 .PP
105 For options of the form \fB--name=\fP\fInum\fP, You can specify
106 the value \fInum\fP in any of the traditional ways. Additionally,
107 you can specify it as \fInum1\fP/\fInum2\fP, where \fInum1\fP and
108 \fInum2\fP are specified traditionally. This is useful for
109 specifying a width/height ratio of 4/3, without having to write
110 infinitely many digits. Where \fInum\fP is supposed to be a natural
111 number, \fBpamperspective\fP does not allow this format.
112
113 .UN quadspecoptions
114 .SS Quadrilateral Specification Options
115
116
117 .TP
118 \fB--upper_left_x=\fP\fInum\fP
119 .TP
120 \fB--ulx=\fP\fInum\fP
121
122
123 This specifies the horizontal coordinate of the upper left
124 vertex of the quadrilateral. The meaning of 'upper left' is
125 relative to the output image. The interpretation of \fInum\fP
126 depends on the values for \fB--input_system\fP and
127 \fB--input_unit\fP.
128
129 .TP
130 \fB--upper_left_y=\fP\fInum\fP
131 .TP
132 \fB--uly=\fP\fInum\fP
133
134
135 This specifies the vertical coordinate of the upper left vertex
136 of the quadrilateral. The meaning of 'upper left' is relative to
137 the output image. The interpretation of \fInum\fP depends on the
138 values for \fB--input_system\fP and \fB--input_unit\fP.
139
140 .TP
141 \fB--upper_right_x=\fP\fInum\fP
142 .TP
143 \fB--urx=\fP\fInum\fP
144
145
146 This specifies the horizontal coordinate of the upper right
147 vertex of the quadrilateral. The meaning of 'upper right' is
148 relative to the output image. The interpretation of \fInum\fP
149 depends on the values for \fB--input_system\fP and
150 \fB--input_unit\fP.
151
152 .TP
153 \fB--upper_right_y=\fP\fInum\fP
154 .TP
155 \fB--ury=\fP\fInum\fP
156
157
158 This specifies the vertical coordinate of the upper right vertex
159 of the quadrilateral. The meaning of 'upper right' is relative to
160 the output image. The interpretation of \fInum\fP depends on the
161 values for \fB--input_system\fP and \fB--input_unit\fP.
162
163 .TP
164 \fB--lower_left_x=\fP\fInum\fP
165 .TP
166 \fB--llx=\fP\fInum\fP
167
168
169 This specifies the horizontal coordinate of the lower left
170 vertex of the quadrilateral. The meaning of 'lower left' is
171 relative to the output image. The interpretation of \fInum\fP
172 depends on the values for \fB--input_system\fP and
173 \fB--input_unit\fP.
174
175 .TP
176 \fB--lower_left_y=\fP\fInum\fP
177 .TP
178 \fB--lly=\fP\fInum\fP
179
180
181 This specifies the vertical coordinate of the lower left vertex
182 of the quadrilateral. The meaning of 'lower left' is relative to
183 the output image. The interpretation of \fInum\fP depends on the
184 values for \fB--input_system\fP and \fB--input_unit\fP.
185
186 .TP
187 \fB--lower_right_x=\fP\fInum\fP
188 .TP
189 \fB--lrx=\fP\fInum\fP
190
191
192 This specifies the horizontal coordinate of the lower right
193 vertex of the quadrilateral. The meaning of 'lower right' is
194 relative to the output image. The interpretation of \fInum\fP
195 depends on the values for \fB--input_system\fP and
196 \fB--input_unit\fP.
197
198 .TP
199 \fB--lower_right_y=\fP\fInum\fP
200 .TP
201 \fB--lry=\fP\fInum\fP
202
203
204 This specifies the vertical coordinate of the lower right vertex
205 of the quadrilateral. The meaning of 'lower right' is relative to
206 the output image. The interpretation of \fInum\fP depends on the
207 values for \fB--input_system\fP and \fB--input_unit\fP.
208
209 .TP
210 \fB--input_system=\fP\fIsystem\fP
211 .TP
212 \fB--input_unit=\fP\fIunit\fP
213
214
215 The input image consists of pixels, which are, from the point of
216 view of a scanline renderer, solid squares. These options specify
217 how the coordinates are interpreted:
218
219
220 .TP
221 \fIsystem\fP=\fBlattice\fP, \fIunit\fP=\fBimage\fP
222
223
224 (0,0) refers to the upper left corner of the upper left pixel
225 and (1,1) refers to the lower right corner of the lower right
226 pixel.
227
228 .TP
229 \fIsystem\fP=\fBlattice\fP, \fIunit\fP=\fBpixel\fP
230
231
232 (0,0) refers to the upper left corner of the upper left pixel
233 and (\fIwidth\fP,\fIheight\fP) refers to the lower right corner
234 of the lower right pixel. Here \fIwidth\fP and \fIheight\fP are
235 the width and height of the input image.
236
237 .TP
238 \fIsystem\fP=\fBpixel\fP, \fIunit\fP=\fBimage\fP
239
240
241 (0,0) refers to the center of the upper left pixel and (1,1)
242 refers to the center of the lower right pixel.
243
244 .TP
245 \fIsystem\fP=\fBpixel\fP, \fIunit\fP=\fBpixel\fP
246
247
248 (0,0) refers to the center of the upper left pixel and
249 (\fIwidth\fP-1,\fIheight\fP-1) refers to the center of the lower
250 right pixel. Here \fIwidth\fP and \fIheight\fP are the width
251 and height of the input image.
252
253
254
255 The defaults are \fB--input_system\fP=\fBlattice\fP and
256 \fB--input_unit\fP=\fBpixel\fP. Point-and-click front ends should
257 use \fB--input_system\fP=\fBpixel\fP.
258
259
260
261 .UN frameoptions
262 .SS Frame Options
263
264 By default \fBpamperspective\fP outputs exactly the above
265 parallelogram, sheared to a rectangle. With the following options, it
266 is possible to make \fBpamperspective\fP output a larger or smaller
267 portion, which we call the "visible part." We refer to the
268 default rectangle as the "frame." The visible part is always
269 a rectangle the axes of which are parallel to those of the frame.
270 .PP
271 The frame options are additive. All the parts of the image
272 specified by either margin options, \fB--include_frame\fP, or
273 \fB--include\fP (or their defaults) are in the visible part. The
274 visible part is the smallest possible rectangle that contains the
275 parts specified those three ways.
276 .PP
277 The visible part must have nonzero size. That means if you specify
278 \fB--frame_include=no\fP (overriding the default), you'll need to
279 specify other frame options in order to have something in the visible
280 part.
281
282
283 .TP
284 [\fB--margin=\fP\fInum\fP]
285
286
287 This specifies an area surrounding the frame that is to be
288 included in the visible part. The units of \fInum\fP are the width
289 of the frame for the horizontal extensions and the height of the
290 frame for vertical extensions.
291 .sp
292 For example, \fB--margin=1\fP makes the visible part 9 times as large,
293 because it makes the visible part extend one frame's worth to the left
294 of the frame, one frame's worth to the right, one frame's worth above
295 the frame, and one frame's worth below the frame, for a total of
296 3 frames' worth in both dimensions.
297 .sp
298 A negative value has an effect only if you specify
299 \fB--frame_include=no\fP. The default is no margin.
300 .sp
301 The individual margin options below override this common margin
302 setting.
303
304
305 .TP
306 [\fB--top_margin=\fP\fInum\fP]
307 .TP
308 [\fB--left_margin=\fP\fInum\fP]
309 .TP
310 [\fB--right_margin=\fP\fInum\fP]
311 .TP
312 [\fB--bottom_margin=\fP\fInum\fP]
313
314
315 These are like \fB--margin\fP, but they specify only one of
316 the 4 sides. The default value for each is the value (or default) of
317 \fB--margin\fP.
318
319
320 .TP
321 [\fB--frame_include=\fP\fIbool\fP]
322
323
324 Valid values for \fIbool\fP are:
325
326
327 .TP
328 \fByes\fP
329 .TP
330 \fBtrue\fP
331 .TP
332 \fBon\fP
333
334
335 The frame itself is in the visible part.
336
337 .TP
338 \fBno\fP
339 .TP
340 \fBfalse\fP
341 .TP
342 \fBoff\fP
343
344
345 The frame itself is not necessarily in the visible part
346 (but it could be if other options cause it to be).
347
348
349
350
351 The default value is \fByes\fP
352
353 .TP
354 \fB--include=[\fP\fIx1\fP,\fIy1\fP;\fIx2\fP,\fIy2\fP; ...]
355
356
357 The visible part is made large enough such that every point
358 (\fIx1\fP,\fIy1\fP), (\fIx2\fP,\fIy2\fP), of the \fIinput\fP image is
359 visible. The meaning of \fIx\fP and \fIy\fP is determined by
360 \fB--input_system\fP and \fB--input_unit\fP. You can specify any
361 number of semicolon-delimited points, including zero.
362 .sp
363 If you're supplying these options via a Unix command shell, be
364 sure to use proper quoting, because semicolon (\fB;\fP) is usually
365 a shell control character.
366
367
368
369
370 .PP
371 The frame options were new in Netpbm 10.25 (October 2004).
372
373 .UN outputsizeoptions
374 .SS Output Size Options
375
376
377 .TP
378 \fB--width=\fP\fIwidth\fP
379 .TP
380 \fB--height=\fP\fIheight\fP
381
382
383 These specify the size of the output image in horizontal and
384 vertical direction. The values are numbers of pixels, so only
385 natural numbers are valid. These values override the default
386 means to determine the output size.
387
388 .TP
389 \fB--detail=\fP\fInum\fP
390
391
392 If you do not specify \fB--width\fP, \fBpamperspective\fP
393 determines the width of the output image such that moving \fInum\fP
394 output pixels horizontally does not change the corresponding pixel
395 coordinates of the input image by more than 1.
396 \fBpamperspective\fP determines the height of the output image
397 analogously. The default value is 1.
398
399 .TP
400 \fB--proportion=\fP\fIprop\fP
401 .TP
402 \fB--ratio=\fP\fIratio\fP
403
404
405 Valid values for \fIprop\fP are:
406
407
408 .TP
409 \fBfree\fP
410
411
412 In this case \fB--ratio\fP does not have any effect.
413
414 .TP
415 \fBfixed\fP
416 After the width and height are determined
417 according to \fB--detail\fP, one of both will be increased, in
418 order to obtain width/height=\fIratio\fP.
419
420
421
422 The defaults are \fB--proportion\fP=\fBfree\fP and
423 \fB--ratio\fP=1.
424
425
426
427 .UN outputoptions
428 .SS Output Options
429
430
431 .TP
432 \fB--output_system=\fP\fIspec\fP
433
434
435 The output image consists of pixels, which are, from the point
436 of view of a scanline renderer, solid squares. This option
437 specifies how the four vertices of the quadrilateral correspond to
438 the pixels of the output image. Valid values for \fIspec\fP are:
439
440
441 .TP
442 \fBlattice\fP
443
444
445 The upper left vertex corresponds to the upper left corner of
446 the upper left pixel and The lower right vertex corresponds to the
447 lower right corner of the lower right
448 pixel.
449
450 .TP
451 \fBpixel\fP
452
453
454 The upper left vertex corresponds to the center of the upper
455 left pixel and The lower right vertex corresponds to the center of
456 the lower right pixel.
457
458
459
460 The default value is \fBlattice\fP. Point-and-click front ends
461 should use \fBpixel\fP.
462
463 .TP
464 \fB--interpolation=\fP\fIspec\fP
465
466
467 Usually (centers of) output pixels do not exactly correspond to
468 (centers of) input pixels. This option determines how the program
469 will choose the new pixels. Valid values for \fIspec\fP are:
470
471
472 .TP
473 \fBnearest\fP
474
475
476 The output pixel will be identical to the nearest input
477 pixel.
478
479 .TP
480 \fBlinear\fP
481
482
483 The output pixel will be a bilinear interpolation of the four
484 surrounding input pixels.
485
486
487
488 The default value is \fBnearest\fP.
489
490
491
492 .UN hints
493 .SH HINTS
494 .PP
495 It might be tempting always to use the options
496 \fB--include 0,0;0,1;1,0;1,1\fP
497 (assuming \fB--input_system=lattice\fP and \fB--input_unit=image\fP),
498 so that no part of the input image is missing in the output.
499 There are problems with that:
500
501
502 .IP \(bu
503 If the three dimensional plane defined by the quadrilateral has a
504 visible horizon in the input image, then the above asks \fBpamperspective\fP
505 to include points that cannot ever be part of the output.
506
507 .IP \(bu
508 If the horizon is not visible, but close to the border of the
509 input image, this may result in \fIvery\fP large output
510 files. Consider a picture of a road. If you ask for a point close to
511 the horizon to be included, then this point is far away from the
512 viewer. The output will cover many kilometers of road, while
513 \fB--detail\fP perhaps makes a pixel represent a square centimeter.
514
515
516 .PP
517 When working with large files \fBpamperspective\fP's memory usage
518 might be an issue. In order to keep it small, you should minimize each
519 of the following:
520
521
522 .IP \(bu
523 The vertical range that the top output line consumes in the
524 input image;
525
526 .IP \(bu
527 The vertical range that the bottom output line consumes in the
528 input image;
529
530 .IP \(bu
531 The vertical range from the topmost (with respect to the
532 input image) quadrilateral point to the top (with respect to the output
533 image) output line.
534
535
536
537 For this purpose you can use \fBpamflip\fP before and/or after
538 \fBpamperspective\fP. Example: Instead of
539
540 .nf
541 \fBpamperspective 10 0 100 50 0 20 95 100 infile > outfile\fP
542
543 .fi
544
545 you can use
546
547 .nf
548 \fB
549 pamflip -rotate90 infile |
550 pamperspective 50 0 100 5 0 90 20 100 |
551 pamflip -rotate270 > outfile
552 \fP
553
554 .fi
555
556 .UN seealso
557 .SH SEE ALSO
558 .BR "\fBnetpbm\fP" (1)\c
559 \&,
560 .BR "\fBpam\fP" (1)\c
561 \&,
562 .BR "\fBpnm\fP" (1)\c
563 \&,
564 .BR "\fBpamcut\fP" (1)\c
565 \&,
566 .BR "\fBpamflip\fP" (1)\c
567 \&,
568 .BR "\fBpnmrotate\fP" (1)\c
569 \&,
570 .BR "\fBpamscale\fP" (1)\c
571 \&,
572 .BR "\fBpnmshear\fP" (1)\c
573 \&,
574 .BR "\fBpamhomography\fP" (1)\c
575 \&,
576 .BR "\fBpnmstitch\fP" (1)\c
577 \&
578
579 .UN history
580 .SH HISTORY
581 .PP
582 Mark Weyer wrote \fBpamperspective\fP in March 2004.
583 .PP
584 It was new in Netpbm 10.22 (April 2004).
585
586
587 .UN author
588 .SH AUTHOR
589
590 This documentation was written by Mark Weyer. Permission is granted
591 to copy, distribute and/or modify this document under the terms of the
592 GNU General Public License, Version 2 or any later version published
593 by the Free Software Foundation.
594 .SH DOCUMENT SOURCE
595 This manual page was generated by the Netpbm tool 'makeman' from HTML
596 source. The master documentation is at
597 .IP
598 .B http://netpbm.sourceforge.net/doc/pamperspective.html
599 .PP