1Pamperspective User Manual(0) Pamperspective User Manual(0)
2
6 pamperspective - a reverse scanline renderer for Netpbm images
7
10 pamperspective
11 [--bottom_margin=num]
12 [--detail=num]
13 [--frame_include=bool]
14 [--height=num]
15 [--include=[x1,y1;x2,y2; ...]]
16 [--input_system=spec]
17 [--input_unit=spec]
18 [--interpolation=spec]
19 [--left_margin=num]
20 [--margin=num]
21 [--output_system=spec]
22 [--proportion=spec]
23 [--ratio=num]
24 [--right_margin=num]
25 [--top_margin=num]
26 [--width=num]
27 {
28 {
29 upper_left_x upper_left_y upper_right_x upper_right_y
30 lower_left_x lower_left_y lower_right_x lower_right_y
31 }
32 |
33 {
34 {--upper_left_x|--ulx}=upper_left_x
35 {--upper_left_y|--uly}=upper_left_y
36 {--upper_right_x|--urx}=upper_right_x
37 {--upper_right_y|--ury}=upper_right_y
38 {--lower_left_x|--llx}=lower_left_x
39 {--lower_left_y|--lly}=lower_left_y
40 {--lower_right_x|--lrx}=lower_right_x
41 {--lower_right_y|--lry}=lower_right_y
42 }
43 }
44 [infile]
45
49 Minimum unique abbreviation of option is acceptable. (But note that
50 shortest unique prefixes might be longer in future versions of the pro‐
51 gram.) You may use single hyphens instead of double hyphen to denote
52 options. You may use white space in place of the equals sign to sepa‐
53 rate an option name from its value. All options starting with hyphens
54 may be given in any order.
55
59 This program is part of Netpbm(1).
60 pamperspective reads a Netpbm image as input and produces a Netpbm
62 image of the same format as output.
63 pamperspective interprets the input image as a perspective projection
65 of another image which is in a plane oblique to that of the input
66 image. For example, a photograph of a painting, taken at an angle.
67 The arguments upper_left_x ... lower_right_y specify a quadrilateral in
68 the photograph that pamperspective assumes corresponds to a parallelo‐
69 gram in the painting. The output image consists of this parallelogram,
70 sheared to a rectangle. In this way pamperspective undoes the effect
71 of a raytracer or scanline renderer.
72 Note that if the input image is a projection of a solid scene, rather
74 than a plane, the result is like a different camera angle on that
75 scene, to the extent that the scene is shallow from the other angle.
76 The input is from infile, or from Standard Input, if infile is not
78 specified. The output is to Standard Output.
79
83 In addition to the options common to all programs based on libnetpbm
84 (most notably -quiet, see
85 Common Options ⟨index.html#commonoptions⟩ ), pamperspective recognizes
86 the following command line options:
87 For options of the form --name=num, You can specify the value num in
89 any of the traditional ways. Additionally, you can specify it as
90 num1/num2, where num1 and num2 are specified traditionally. This is
91 useful for specifying a width/height ratio of 4/3, without having to
92 write infinitely many digits. Where num is supposed to be a natural
93 number, pamperspective does not allow this format.
94 Quadrilateral Specification Options
97 --upper_left_x=num
98 --ulx=num
100 This specifies the horizontal coordinate of the upper left
103 vertex of the quadrilateral. The meaning of 'upper left' is
104 relative to the output image. The interpretation of num
105 depends on the values for --input_system and
106 --input_unit.
107 --upper_left_y=num
110 --uly=num
112 This specifies the vertical coordinate of the upper left vertex
115 of the quadrilateral. The meaning of 'upper left' is relative
116 to
117 the output image. The interpretation of num depends on the
118 values for --input_system and --input_unit.
119 --upper_right_x=num
122 --urx=num
124 This specifies the horizontal coordinate of the upper right
127 vertex of the quadrilateral. The meaning of 'upper right' is
128 relative to the output image. The interpretation of num
129 depends on the values for --input_system and
130 --input_unit.
131 --upper_right_y=num
134 --ury=num
136 This specifies the vertical coordinate of the upper right vertex
139 of the quadrilateral. The meaning of 'upper right' is rela‐
140 tive to
141 the output image. The interpretation of num depends on the
142 values for --input_system and --input_unit.
143 --lower_left_x=num
146 --llx=num
148 This specifies the horizontal coordinate of the lower left
151 vertex of the quadrilateral. The meaning of 'lower left' is
152 relative to the output image. The interpretation of num
153 depends on the values for --input_system and
154 --input_unit.
155 --lower_left_y=num
158 --lly=num
160 This specifies the vertical coordinate of the lower left vertex
163 of the quadrilateral. The meaning of 'lower left' is relative
164 to
165 the output image. The interpretation of num depends on the
166 values for --input_system and --input_unit.
167 --lower_right_x=num
170 --lrx=num
172 This specifies the horizontal coordinate of the lower right
175 vertex of the quadrilateral. The meaning of 'lower right' is
176 relative to the output image. The interpretation of num
177 depends on the values for --input_system and
178 --input_unit.
179 --lower_right_y=num
182 --lry=num
184 This specifies the vertical coordinate of the lower right vertex
187 of the quadrilateral. The meaning of 'lower right' is rela‐
188 tive to
189 the output image. The interpretation of num depends on the
190 values for --input_system and --input_unit.
191 --input_system=system
194 --input_unit=unit
196 The input image consists of pixels, which are, from the point of
199 view of a scanline renderer, solid squares. These options
200 specify
201 how the coordinates are interpreted:
202 system=lattice, unit=image
206 (0,0) refers to the upper left corner of the upper left pixel
209 and (1,1) refers to the lower right corner of the lower
210 right
211 pixel.
212 system=lattice, unit=pixel
215 (0,0) refers to the upper left corner of the upper left pixel
218 and (width,height) refers to the lower right corner
219 of the lower right pixel. Here width and height are
220 the width and height of the input image.
221 system=pixel, unit=image
224 (0,0) refers to the center of the upper left pixel and (1,1)
227 refers to the center of the lower right pixel.
228 system=pixel, unit=pixel
231 (0,0) refers to the center of the upper left pixel and
234 (width-1,height-1) refers to the center of the lower
235 right pixel. Here width and height are the width
236 and height of the input image.
237 The defaults are --input_system=lattice and
241 --input_unit=pixel. Point-and-click front ends should
242 use --input_system=pixel.
243 Frame Options
248 By default pamperspective outputs exactly the above parallelogram,
249 sheared to a rectangle. With the following options, it is possible to
250 make pamperspective output a larger or smaller portion, which we call
251 the "visible part." We refer to the default rectangle as the "frame."
252 The visible part is always a rectangle the axes of which are parallel
253 to those of the frame.
254 The frame options are additive. All the parts of the image specified
256 by either margin options, --frame_include, or --include (or their
257 defaults) are in the visible part. The visible part is the smallest
258 possible rectangle that contains the parts specified those three ways.
259 The visible part must have nonzero size. That means if you specify
261 --frame_include=no (overriding the default), you'll need to specify
262 other frame options in order to have something in the visible part.
263 [--margin=num]
267 This specifies an area surrounding the frame that is to be
270 included in the visible part. The units of num are the width
271 of the frame for the horizontal extensions and the height of
272 the
273 frame for vertical extensions.
274 For example, --margin=1 makes the visible part 9 times as large,
276 because it makes the visible part extend one frame's worth to
277 the left
278 of the frame, one frame's worth to the right, one frame's
279 worth above
280 the frame, and one frame's worth below the frame, for a total
281 of
282 3 frames' worth in both dimensions.
283 A negative value has an effect only if you specify
285 --frame_include=no. The default is no margin.
286 The individual margin options below override this common margin
288 setting.
289 [--top_margin=num]
293 [--left_margin=num]
295 [--right_margin=num]
297 [--bottom_margin=num]
299 These are like --margin, but they specify only one of
302 the 4 sides. The default value for each is the value (or
303 default) of
304 --margin.
305 [--frame_include=bool]
309 Valid values for bool are:
312 yes
316 true
318 on
320 The frame itself is in the visible part.
323 no
326 false
328 off
330 The frame itself is not necessarily in the visible part
333 (but it could be if other options cause it to be).
334 The default value is yes
339 --include=[x1,y1;x2,y2; ...]
342 The visible part is made large enough such that every point
345 (x1,y1), (x2,y2), of the input image is
346 visible. The meaning of x and y is determined by
347 --input_system and --input_unit. You can specify any
348 number of semicolon-delimited points, including zero.
349 If you're supplying these options via a Unix command shell, be
351 sure to use proper quoting, because semicolon (;) is usually
352 a shell control character.
353 The frame options were new in Netpbm 10.25 (October 2004).
359 Output Size Options
362 --width=width
363 --height=height
365 These specify the size of the output image in horizontal and
368 vertical direction. The values are numbers of pixels, so only
369 natural numbers are valid. These values override the default
370 means to determine the output size.
371 --detail=num
374 If you do not specify --width, pamperspective
377 determines the width of the output image such that moving num
378 output pixels horizontally does not change the corresponding
379 pixel
380 coordinates of the input image by more than 1.
381 pamperspective determines the height of the output image
382 analogously. The default value is 1.
383 --proportion=prop
386 --ratio=ratio
388 Valid values for prop are:
391 free
395 In this case --ratio does not have any effect.
398 fixed After the width and height are determined
401 according to --detail, one of both will be increased, in
402 order to obtain width/height=ratio.
403 The defaults are --proportion=free and
407 --ratio=1.
408 Output Options
413 --output_system=spec
414 The output image consists of pixels, which are, from the point
417 of view of a scanline renderer, solid squares. This option
418 specifies how the four vertices of the quadrilateral corre‐
419 spond to
420 the pixels of the output image. Valid values for spec are:
421 lattice
425 The upper left vertex corresponds to the upper left corner of
428 the upper left pixel and The lower right vertex corresponds
429 to the
430 lower right corner of the lower right
431 pixel.
432 pixel
435 The upper left vertex corresponds to the center of the upper
438 left pixel and The lower right vertex corresponds to the
439 center of
440 the lower right pixel.
441 The default value is lattice. Point-and-click front ends
445 should use pixel.
446 --interpolation=spec
449 Usually (centers of) output pixels do not exactly correspond to
452 (centers of) input pixels. This option determines how the
453 program
454 will choose the new pixels. Valid values for spec are:
455 nearest
459 The output pixel will be identical to the nearest input
462 pixel.
463 linear
466 The output pixel will be a bilinear interpolation of the four
469 surrounding input pixels.
470 The default value is nearest.
474
479 It might be tempting always to use the options --include
480 0,0;0,1;1,0;1,1 (assuming --input_system=lattice and
481 --input_unit=image), so that no part of the input image is missing in
482 the output. There are problems with that:
483 · If the three dimensional plane defined by the quadrilateral has
487 a
488 visible horizon in the input image, then the above asks pam‐
489 perspective
490 to include points that cannot ever be part of the output.
491 · If the horizon is not visible, but close to the border of the
494 input image, this may result in very large output
495 files. Consider a picture of a road. If you ask for a point
496 close to
497 the horizon to be included, then this point is far away from
498 the
499 viewer. The output will cover many kilometers of road, while
500 --detail perhaps makes a pixel represent a square centimeter.
501 When working with large files pamperspective's memory usage might be an
505 issue. In order to keep it small, you should minimize each of the fol‐
506 lowing:
507 · The vertical range that the top output line consumes in the
511 input image;
512 · The vertical range that the bottom output line consumes in the
515 input image;
516 · The vertical range from the topmost (with respect to the
519 input image) quadrilateral point to the top (with respect to
520 the output
521 image) output line.
522 For this purpose you can use pamflip before and/or after pamper‐
526 spective. Example: Instead of
527 pamperspective 10 0 100 50 0 20 95 100 infile > outfile
529 you can use
531 pamflip -rotate90 infile |
533 pamperspective 50 0 100 5 0 90 20 100 |
534 pamflip -rotate270 > outfile
535
538 netpbm(1), pam(1), pnm(1), pamcut(1), pamflip(1), pnmrotate(1), pam‐
539 scale(1), pnmshear(1), pamhomography(1), pnmstitch(1)
540
543 Mark Weyer wrote pamperspective in March 2004.
544 It was new in Netpbm 10.22 (April 2004).
546
550 This documentation was written by Mark Weyer. Permission is granted to
551 copy, distribute and/or modify this document under the terms of the GNU
552 General Public License, Version 2 or any later version published by the
553 Free Software Foundation.
554
556 This manual page was generated by the Netpbm tool 'makeman' from HTML
557 source. The master documentation is at
558 http://netpbm.sourceforge.net/doc/pamperspective.html
560netpbm documentation 02 September 2004 Pamperspective User Manual(0)