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
50 Minimum unique abbreviation of option is acceptable. (But note that
51 shortest unique prefixes might be longer in future versions of the pro‐
52 gram.) You may use single hyphens instead of double hyphen to denote
53 options. You may use white space in place of the equals sign to sepa‐
54 rate an option name from its value. All options starting with hyphens
55 may be given in any order.
56
60 This program is part of Netpbm(1).
61 pamperspective reads a Netpbm image as input and produces a Netpbm im‐
63 age of the same format as output.
64 pamperspective interprets the input image as a perspective projection
66 of another image which is in a plane oblique to that of the input im‐
67 age. For example, a photograph of a painting, taken at an angle. The
68 arguments upper_left_x ... lower_right_y specify a quadrilateral in the
69 photograph that pamperspective assumes corresponds to a parallelogram
70 in the painting. The output image consists of this parallelogram,
71 sheared to a rectangle. In this way pamperspective undoes the effect
72 of a raytracer or scanline renderer.
73 Note that if the input image is a projection of a solid scene, rather
75 than a plane, the result is like a different camera angle on that
76 scene, to the extent that the scene is shallow from the other angle.
77 The input is from infile, or from Standard Input, if infile is not
79 specified. The output is to Standard Output.
80
84 In addition to the options common to all programs based on libnetpbm
85 (most notably -quiet, see
86 Common Options ⟨index.html#commonoptions⟩ ), pamperspective recognizes
87 the following command line options:
88 For options of the form --name=num, You can specify the value num in
90 any of the traditional ways. Additionally, you can specify it as
91 num1/num2, where num1 and num2 are specified traditionally. This is
92 useful for specifying a width/height ratio of 4/3, without having to
93 write infinitely many digits. Where num is supposed to be a natural
94 number, pamperspective does not allow this format.
95 Quadrilateral Specification Options
98 --upper_left_x=num
99 --ulx=num
101 This specifies the horizontal coordinate of the upper left
104 vertex of the quadrilateral. The meaning of 'upper left' is
105 relative to the output image. The interpretation of num
106 depends on the values for --input_system and
107 --input_unit.
108 --upper_left_y=num
111 --uly=num
113 This specifies the vertical coordinate of the upper left vertex
116 of the quadrilateral. The meaning of 'upper left' is relative
117 to
118 the output image. The interpretation of num depends on the
119 values for --input_system and --input_unit.
120 --upper_right_x=num
123 --urx=num
125 This specifies the horizontal coordinate of the upper right
128 vertex of the quadrilateral. The meaning of 'upper right' is
129 relative to the output image. The interpretation of num
130 depends on the values for --input_system and
131 --input_unit.
132 --upper_right_y=num
135 --ury=num
137 This specifies the vertical coordinate of the upper right vertex
140 of the quadrilateral. The meaning of 'upper right' is rela‐
141 tive to
142 the output image. The interpretation of num depends on the
143 values for --input_system and --input_unit.
144 --lower_left_x=num
147 --llx=num
149 This specifies the horizontal coordinate of the lower left
152 vertex of the quadrilateral. The meaning of 'lower left' is
153 relative to the output image. The interpretation of num
154 depends on the values for --input_system and
155 --input_unit.
156 --lower_left_y=num
159 --lly=num
161 This specifies the vertical coordinate of the lower left vertex
164 of the quadrilateral. The meaning of 'lower left' is relative
165 to
166 the output image. The interpretation of num depends on the
167 values for --input_system and --input_unit.
168 --lower_right_x=num
171 --lrx=num
173 This specifies the horizontal coordinate of the lower right
176 vertex of the quadrilateral. The meaning of 'lower right' is
177 relative to the output image. The interpretation of num
178 depends on the values for --input_system and
179 --input_unit.
180 --lower_right_y=num
183 --lry=num
185 This specifies the vertical coordinate of the lower right vertex
188 of the quadrilateral. The meaning of 'lower right' is rela‐
189 tive to
190 the output image. The interpretation of num depends on the
191 values for --input_system and --input_unit.
192 --input_system=system
195 --input_unit=unit
197 The input image consists of pixels, which are, from the point of
200 view of a scanline renderer, solid squares. These options
201 specify
202 how the coordinates are interpreted:
203 system=lattice, unit=image
207 (0,0) refers to the upper left corner of the upper left pixel
210 and (1,1) refers to the lower right corner of the lower
211 right
212 pixel.
213 system=lattice, unit=pixel
216 (0,0) refers to the upper left corner of the upper left pixel
219 and (width,height) refers to the lower right corner
220 of the lower right pixel. Here width and height are
221 the width and height of the input image.
222 system=pixel, unit=image
225 (0,0) refers to the center of the upper left pixel and (1,1)
228 refers to the center of the lower right pixel.
229 system=pixel, unit=pixel
232 (0,0) refers to the center of the upper left pixel and
235 (width-1,height-1) refers to the center of the lower
236 right pixel. Here width and height are the width
237 and height of the input image.
238 The defaults are --input_system=lattice and
242 --input_unit=pixel. Point-and-click front ends should
243 use --input_system=pixel.
244 Frame Options
249 By default pamperspective outputs exactly the above parallelogram,
250 sheared to a rectangle. With the following options, it is possible to
251 make pamperspective output a larger or smaller portion, which we call
252 the "visible part." We refer to the default rectangle as the "frame."
253 The visible part is always a rectangle the axes of which are parallel
254 to those of the frame.
255 The frame options are additive. All the parts of the image specified
257 by either margin options, --frame_include, or --include (or their de‐
258 faults) are in the visible part. The visible part is the smallest pos‐
259 sible rectangle that contains the parts specified those three ways.
260 The visible part must have nonzero size. That means if you specify
262 --frame_include=no (overriding the default), you'll need to specify
263 other frame options in order to have something in the visible part.
264 [--margin=num]
268 This specifies an area surrounding the frame that is to be
271 included in the visible part. The units of num are the width
272 of the frame for the horizontal extensions and the height of
273 the
274 frame for vertical extensions.
275 For example, --margin=1 makes the visible part 9 times as large,
277 because it makes the visible part extend one frame's worth to
278 the left
279 of the frame, one frame's worth to the right, one frame's
280 worth above
281 the frame, and one frame's worth below the frame, for a total
282 of
283 3 frames' worth in both dimensions.
284 A negative value has an effect only if you specify
286 --frame_include=no. The default is no margin.
287 The individual margin options below override this common margin
289 setting.
290 [--top_margin=num]
294 [--left_margin=num]
296 [--right_margin=num]
298 [--bottom_margin=num]
300 These are like --margin, but they specify only one of
303 the 4 sides. The default value for each is the value (or de‐
304 fault) of
305 --margin.
306 [--frame_include=bool]
310 Valid values for bool are:
313 yes
317 true
319 on
321 The frame itself is in the visible part.
324 no
327 false
329 off
331 The frame itself is not necessarily in the visible part
334 (but it could be if other options cause it to be).
335 The default value is yes
340 --include=[x1,y1;x2,y2; ...]
343 The visible part is made large enough such that every point
346 (x1,y1), (x2,y2), of the input image is
347 visible. The meaning of x and y is determined by
348 --input_system and --input_unit. You can specify any
349 number of semicolon-delimited points, including zero.
350 If you're supplying these options via a Unix command shell, be
352 sure to use proper quoting, because semicolon (;) is usually
353 a shell control character.
354 The frame options were new in Netpbm 10.25 (October 2004).
360 Output Size Options
363 --width=width
364 --height=height
366 These specify the size of the output image in horizontal and
369 vertical direction. The values are numbers of pixels, so only
370 natural numbers are valid. These values override the default
371 means to determine the output size.
372 --detail=num
375 If you do not specify --width, pamperspective
378 determines the width of the output image such that moving num
379 output pixels horizontally does not change the corresponding
380 pixel
381 coordinates of the input image by more than 1.
382 pamperspective determines the height of the output image
383 analogously. The default value is 1.
384 --proportion=prop
387 --ratio=ratio
389 Valid values for prop are:
392 free
396 In this case --ratio does not have any effect.
399 fixed After the width and height are determined
402 according to --detail, one of both will be increased, in
403 order to obtain width/height=ratio.
404 The defaults are --proportion=free and
408 --ratio=1.
409 Output Options
414 --output_system=spec
415 The output image consists of pixels, which are, from the point
418 of view of a scanline renderer, solid squares. This option
419 specifies how the four vertices of the quadrilateral corre‐
420 spond to
421 the pixels of the output image. Valid values for spec are:
422 lattice
426 The upper left vertex corresponds to the upper left corner of
429 the upper left pixel and The lower right vertex corresponds
430 to the
431 lower right corner of the lower right
432 pixel.
433 pixel
436 The upper left vertex corresponds to the center of the upper
439 left pixel and The lower right vertex corresponds to the
440 center of
441 the lower right pixel.
442 The default value is lattice. Point-and-click front ends
446 should use pixel.
447 --interpolation=spec
450 Usually (centers of) output pixels do not exactly correspond to
453 (centers of) input pixels. This option determines how the
454 program
455 will choose the new pixels. Valid values for spec are:
456 nearest
460 The output pixel will be identical to the nearest input
463 pixel.
464 linear
467 The output pixel will be a bilinear interpolation of the four
470 surrounding input pixels.
471 The default value is nearest.
475
480 It might be tempting always to use the options --include
481 0,0;0,1;1,0;1,1 (assuming --input_system=lattice and --input_unit=im‐
482 age), so that no part of the input image is missing in the output.
483 There are problems with that:
484 • If the three dimensional plane defined by the quadrilateral has
488 a
489 visible horizon in the input image, then the above asks pam‐
490 perspective
491 to include points that cannot ever be part of the output.
492 • If the horizon is not visible, but close to the border of the
495 input image, this may result in very large output
496 files. Consider a picture of a road. If you ask for a point
497 close to
498 the horizon to be included, then this point is far away from
499 the
500 viewer. The output will cover many kilometers of road, while
501 --detail perhaps makes a pixel represent a square centimeter.
502 When working with large files pamperspective's memory usage might be an
506 issue. In order to keep it small, you should minimize each of the fol‐
507 lowing:
508 • The vertical range that the top output line consumes in the
512 input image;
513 • The vertical range that the bottom output line consumes in the
516 input image;
517 • The vertical range from the topmost (with respect to the
520 input image) quadrilateral point to the top (with respect to
521 the output
522 image) output line.
523 For this purpose you can use pamflip before and/or after pamper‐
527 spective. Example: Instead of
528 pamperspective 10 0 100 50 0 20 95 100 infile > outfile
530 you can use
533 pamflip -rotate90 infile |
535 pamperspective 50 0 100 5 0 90 20 100 |
536 pamflip -rotate270 > outfile
537
541 netpbm(1), pam(1), pnm(1), pamcut(1), pamflip(1), pnmrotate(1), pam‐
542 scale(1), pnmshear(1), pamhomography(1), pnmstitch(1)
543
546 Mark Weyer wrote pamperspective in March 2004.
547 It was new in Netpbm 10.22 (April 2004).
549
553 This documentation was written by Mark Weyer. Permission is granted to
554 copy, distribute and/or modify this document under the terms of the GNU
555 General Public License, Version 2 or any later version published by the
556 Free Software Foundation.
557
559 This manual page was generated by the Netpbm tool 'makeman' from HTML
560 source. The master documentation is at
561 http://netpbm.sourceforge.net/doc/pamperspective.html
563netpbm documentation 02 September 2004 Pamperspective User Manual(0)