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 The values upper_left_x ... lower_right_y, that are required on the
65 command line, specify a quadrilateral in the input image. pamperspec‐
66 tive interprets the input image as a perspective projection of a three
67 dimensional scene, for example a photograph. pamperspective assumes
68 the specified quadrilateral represents a parallelogram in that scene.
69 The output image consists of this parallelogram, sheared to a rectan‐
70 gle. In this way pamperspective undoes the effect of a raytracer or
71 scanline renderer.
72 The input is from infile, or from Standard Input, if infile is not
74 specified. The output is to Standard Output.
75
79 For options of the form --name=num, You can specify the value num in
80 any of the traditional ways. Additionally, you can specify it as
81 num1/num2, where num1 and num2 are specified traditionally. This is
82 useful for specifying a width/height ratio of 4/3, without having to
83 write infinitely many digits. Where num is supposed to be a natural
84 number, pamperspective does not allow this format.
85 Quadrilateral specification options
88 --upper_left_x=num
89 --ulx=num
91 This specifies the horizontal coordinate of the upper left
94 vertex of the quadrilateral. The meaning of 'upper left' is
95 relative to the output image. The interpretation of num
96 depends on the values for --input_system and
97 --input_unit.
98 --upper_left_y=num
101 --uly=num
103 This specifies the vertical coordinate of the upper left vertex
106 of the quadrilateral. The meaning of 'upper left' is relative
107 to
108 the output image. The interpretation of num depends on the
109 values for --input_system and --input_unit.
110 --upper_right_x=num
113 --urx=num
115 This specifies the horizontal coordinate of the upper right
118 vertex of the quadrilateral. The meaning of 'upper right' is
119 relative to the output image. The interpretation of num
120 depends on the values for --input_system and
121 --input_unit.
122 --upper_right_y=num
125 --ury=num
127 This specifies the vertical coordinate of the upper right vertex
130 of the quadrilateral. The meaning of 'upper right' is rela‐
131 tive to
132 the output image. The interpretation of num depends on the
133 values for --input_system and --input_unit.
134 --lower_left_x=num
137 --llx=num
139 This specifies the horizontal coordinate of the lower left
142 vertex of the quadrilateral. The meaning of 'lower left' is
143 relative to the output image. The interpretation of num
144 depends on the values for --input_system and
145 --input_unit.
146 --lower_left_y=num
149 --lly=num
151 This specifies the vertical coordinate of the lower left vertex
154 of the quadrilateral. The meaning of 'lower left' is relative
155 to
156 the output image. The interpretation of num depends on the
157 values for --input_system and --input_unit.
158 --lower_right_x=num
161 --lrx=num
163 This specifies the horizontal coordinate of the lower right
166 vertex of the quadrilateral. The meaning of 'lower right' is
167 relative to the output image. The interpretation of num
168 depends on the values for --input_system and
169 --input_unit.
170 --lower_right_y=num
173 --lry=num
175 This specifies the vertical coordinate of the lower right vertex
178 of the quadrilateral. The meaning of 'lower right' is rela‐
179 tive to
180 the output image. The interpretation of num depends on the
181 values for --input_system and --input_unit.
182 --input_system=system
185 --input_unit=unit
187 The input image consists of pixels, which are, from the point of
190 view of a scanline renderer, solid squares. These options
191 specify
192 how the coordinates are interpreted:
193 system=lattice, unit=image
197 (0,0) refers to the upper left corner of the upper left pixel
200 and (1,1) refers to the lower right corner of the lower
201 right
202 pixel.
203 system=lattice, unit=pixel
206 (0,0) refers to the upper left corner of the upper left pixel
209 and (width,height) refers to the lower right corner
210 of the lower right pixel. Here width and height are
211 the width and height of the input image.
212 system=pixel, unit=image
215 (0,0) refers to the centre of the upper left pixel and (1,1)
218 refers to the centre of the lower right pixel.
219 system=pixel, unit=pixel
222 (0,0) refers to the centre of the upper left pixel and
225 (width-1,height-1) refers to the centre of the lower
226 right pixel. Here width and height are the width
227 and height of the input image.
228 The defaults are --input_system=lattice and
232 --input_unit=pixel. Point-and-click front ends should
233 use --input_system=pixel.
234 Frame Options
239 By default pamperspective outputs exactly the above parallelogram,
240 sheared to a rectangle. With the following options, it is possible to
241 make pamperspective output a larger or smaller portion, which we call
242 the 'visible part.' We refer to the default rectangle as the 'frame.'
243 The visible part is always a rectangle the axes of which are parallel
244 to those of the frame.
245 The frame options are additive. All the parts of the image specified
247 by either margin options, --include_frame, or --include (or their
248 defaults) are in the visible part. The visible part is the smallest
249 possible rectangle that contains the parts specified those three ways.
250 The visible part must have nonzero size. That means if you specify
252 --frame-include=no (overriding the default), you'll need to specify
253 other frame options in order to have something in the visible part.
254 [--margin=num]
258 This specifies an area surrounding the frame that is to be
261 included in the visible part. The units of num are the width
262 of the frame for the horizontal extensions and the height of
263 the
264 frame for vertical extensions.
265 For example, --margin=1 makes the visible part 9 times as large,
267 because it makes the visible part extend one frame's worth to
268 the left
269 of the frame, one frame's worth to the right, one frame's
270 worth above
271 the frame, and one frame's worth below the frame, for a total
272 of
273 3 frames' worth in both dimensions.
274 A negative value has an effect only if you specify
276 --frame_include=no. The default is no margin.
277 The individual margin options below override this common margin
279 setting.
280 [--top_margin=num]
284 [--left_margin=num]
286 [--right_margin=num]
288 [--bottom_margin=num]
290 These are like --margin, but they specify only one of
293 the 4 sides. The default value for each is the value (or
294 default) of
295 --margin.
296 [--frame_include=bool]
300 Valid values for bool are:
303 yes
307 true
309 on
311 The frame itself is in the visible part.
314 no
317 false
319 off
321 The frame itself is not necessarily in the visible part
324 (but it could be if other options cause it to be).
325 The default value is yes
330 --include=[x1,y1;x2,y2; ...]
333 The visible part is made large enough such that every point
336 (x1,y1), (x2,y2), of the input image is
337 visible. The meaning of x and y is determined by
338 --input_system and --input_unit. You can specify any
339 number of semicolon-delimited points, including zero.
340 If you're supplying these options via a Unix command shell, be
342 sure to use proper quoting, because semicolon (;) is usually
343 a shell control character.
344 The frame options were new in Netpbm 10.25 (October 2004).
350 Output Size Options
353 --width=width
354 --height=height
356 These specify the size of the output image in horizontal and
359 vertical direction. The values are numbers of pixels, so only
360 natural numbers are valid. These values override the default
361 means to determine the output size.
362 --detail=num
365 If you do not specify --width, pamperspective
368 determines the width of the output image such that moving num
369 output pixels horizontally does not change the corresponding
370 pixel
371 coordinates of the input image by more than 1.
372 pamperspective determines the height of the output image
373 analogously. The default value is 1.
374 --proportion=prop
377 --ratio=ratio
379 Valid values for prop are:
382 free
386 In this case --ratio does not have any effect.
389 fixed After the width and height are determined
392 according to --detail, one of both will be increased, in
393 order to obtain width/height=ratio.
394 The defaults are --proportion=free and
398 --ratio=1.
399 Output Options
404 --output_system=spec
405 The output image consists of pixels, which are, from the point
408 of view of a scanline renderer, solid squares. This option
409 specifies how the four vertices of the quadrilateral corre‐
410 spond to
411 the pixels of the output image. Valid values for spec are:
412 lattice
416 The upper left vertex corresponds to the upper left corner of
419 the upper left pixel and The lower right vertex corresponds
420 to the
421 lower right corner of the lower right
422 pixel.
423 pixel
426 The upper left vertex corresponds to the centre of the upper
429 left pixel and The lower right vertex corresponds to the
430 centre of
431 the lower right pixel.
432 The default value is lattice. Point-and-click front ends
436 should use pixel.
437 --interpolation=spec
440 Usually (centres of) output pixels do not exactly correspond to
443 (centres of) input pixels. This option determines how the
444 program
445 will choose the new pixels. Valid values for spec are:
446 nearest
450 The output pixel will be identical to the nearest input
453 pixel.
454 linear
457 The output pixel will be a bilinear interpolation of the four
460 surrounding input pixels.
461 The default value is nearest.
465
470 It might be tempting always to use the options --include
471 0,0;0,1;1,0;1,1 (assuming --input_system=lattice and
472 --input_unit=image), so that no part of the input image is missing in
473 the output. There are problems with that:
474 · If the threedimensional plane defined by the quadrilateral has a
478 visible horizon in the input image, then the above asks pam‐
479 perspective
480 to include points that cannot ever be part of the output.
481 · If the horizon is not visible, but close to the border of the
484 input
485 image, this may result in very large output files. Consider a
486 picture of a road. If you ask a point close to the horizon to
487 be included,
488 then this point is far away from the viewer. The output will
489 cover many
490 kilometers of road, while --detail perhaps makes a pixel equal
491 to a
492 square centimeter.
493 When working with large files pamperspective's memory usage might be an
497 issue. In order to keep it small, you should minimize each of the fol‐
498 lowing:
499 · The vertical range that the top output line consumes in the
503 input image;
504 · The vertical range that the bottom output line consumes in the
507 input image;
508 · The vertical range from the topmost (with respect to the
511 input image) quadrilateral point to the top (with respect to
512 the output
513 image) output line.
514 For this purpose you can use pamflip before and/or after pamper‐
518 spective. Example: Instead of
519 pamperspective 10 0 100 50 0 20 95 100 infile > outfile
521 you can use
523 pamflip -rotate90 infile |
525 pamperspective 50 0 100 5 0 90 20 100 |
526 pamflip -rotate270 > outfile
527
530 netpbm(1), pam(1), pnm(1), pamcut(1), pamflip(1), pnmrotate(1), pam‐
531 scale(1), pnmshear(1), pnmstitch(1)
532
535 Mark Weyer wrote pamperspective in March 2004.
536 It was new in Netpbm 10.22 (April 2004).
538
542 This documentation was written by Mark Weyer. Permission is granted to
543 copy, distribute and/or modify this document under the terms of the GNU
544 General Public License, Version 2 or any later version published by the
545 Free Software Foundation.
546netpbm documentation 2 September 2004 Pamperspective User Manual(0)