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 For options of the form --name=num, You can specify the value num in
84 any of the traditional ways. Additionally, you can specify it as
85 num1/num2, where num1 and num2 are specified traditionally. This is
86 useful for specifying a width/height ratio of 4/3, without having to
87 write infinitely many digits. Where num is supposed to be a natural
88 number, pamperspective does not allow this format.
89 Quadrilateral specification options
92 --upper_left_x=num
93 --ulx=num
95 This specifies the horizontal coordinate of the upper left
98 vertex of the quadrilateral. The meaning of 'upper left' is
99 relative to the output image. The interpretation of num
100 depends on the values for --input_system and
101 --input_unit.
102 --upper_left_y=num
105 --uly=num
107 This specifies the vertical coordinate of the upper left vertex
110 of the quadrilateral. The meaning of 'upper left' is relative
111 to
112 the output image. The interpretation of num depends on the
113 values for --input_system and --input_unit.
114 --upper_right_x=num
117 --urx=num
119 This specifies the horizontal coordinate of the upper right
122 vertex of the quadrilateral. The meaning of 'upper right' is
123 relative to the output image. The interpretation of num
124 depends on the values for --input_system and
125 --input_unit.
126 --upper_right_y=num
129 --ury=num
131 This specifies the vertical coordinate of the upper right vertex
134 of the quadrilateral. The meaning of 'upper right' is rela‐
135 tive to
136 the output image. The interpretation of num depends on the
137 values for --input_system and --input_unit.
138 --lower_left_x=num
141 --llx=num
143 This specifies the horizontal coordinate of the lower left
146 vertex of the quadrilateral. The meaning of 'lower left' is
147 relative to the output image. The interpretation of num
148 depends on the values for --input_system and
149 --input_unit.
150 --lower_left_y=num
153 --lly=num
155 This specifies the vertical coordinate of the lower left vertex
158 of the quadrilateral. The meaning of 'lower left' is relative
159 to
160 the output image. The interpretation of num depends on the
161 values for --input_system and --input_unit.
162 --lower_right_x=num
165 --lrx=num
167 This specifies the horizontal coordinate of the lower right
170 vertex of the quadrilateral. The meaning of 'lower right' is
171 relative to the output image. The interpretation of num
172 depends on the values for --input_system and
173 --input_unit.
174 --lower_right_y=num
177 --lry=num
179 This specifies the vertical coordinate of the lower right vertex
182 of the quadrilateral. The meaning of 'lower right' is rela‐
183 tive to
184 the output image. The interpretation of num depends on the
185 values for --input_system and --input_unit.
186 --input_system=system
189 --input_unit=unit
191 The input image consists of pixels, which are, from the point of
194 view of a scanline renderer, solid squares. These options
195 specify
196 how the coordinates are interpreted:
197 system=lattice, unit=image
201 (0,0) refers to the upper left corner of the upper left pixel
204 and (1,1) refers to the lower right corner of the lower
205 right
206 pixel.
207 system=lattice, unit=pixel
210 (0,0) refers to the upper left corner of the upper left pixel
213 and (width,height) refers to the lower right corner
214 of the lower right pixel. Here width and height are
215 the width and height of the input image.
216 system=pixel, unit=image
219 (0,0) refers to the center of the upper left pixel and (1,1)
222 refers to the center of the lower right pixel.
223 system=pixel, unit=pixel
226 (0,0) refers to the center of the upper left pixel and
229 (width-1,height-1) refers to the center of the lower
230 right pixel. Here width and height are the width
231 and height of the input image.
232 The defaults are --input_system=lattice and
236 --input_unit=pixel. Point-and-click front ends should
237 use --input_system=pixel.
238 Frame Options
243 By default pamperspective outputs exactly the above parallelogram,
244 sheared to a rectangle. With the following options, it is possible to
245 make pamperspective output a larger or smaller portion, which we call
246 the 'visible part.' We refer to the default rectangle as the 'frame.'
247 The visible part is always a rectangle the axes of which are parallel
248 to those of the frame.
249 The frame options are additive. All the parts of the image specified
251 by either margin options, --frame_include, or --include (or their
252 defaults) are in the visible part. The visible part is the smallest
253 possible rectangle that contains the parts specified those three ways.
254 The visible part must have nonzero size. That means if you specify
256 --frame_include=no (overriding the default), you'll need to specify
257 other frame options in order to have something in the visible part.
258 [--margin=num]
262 This specifies an area surrounding the frame that is to be
265 included in the visible part. The units of num are the width
266 of the frame for the horizontal extensions and the height of
267 the
268 frame for vertical extensions.
269 For example, --margin=1 makes the visible part 9 times as large,
271 because it makes the visible part extend one frame's worth to
272 the left
273 of the frame, one frame's worth to the right, one frame's
274 worth above
275 the frame, and one frame's worth below the frame, for a total
276 of
277 3 frames' worth in both dimensions.
278 A negative value has an effect only if you specify
280 --frame_include=no. The default is no margin.
281 The individual margin options below override this common margin
283 setting.
284 [--top_margin=num]
288 [--left_margin=num]
290 [--right_margin=num]
292 [--bottom_margin=num]
294 These are like --margin, but they specify only one of
297 the 4 sides. The default value for each is the value (or
298 default) of
299 --margin.
300 [--frame_include=bool]
304 Valid values for bool are:
307 yes
311 true
313 on
315 The frame itself is in the visible part.
318 no
321 false
323 off
325 The frame itself is not necessarily in the visible part
328 (but it could be if other options cause it to be).
329 The default value is yes
334 --include=[x1,y1;x2,y2; ...]
337 The visible part is made large enough such that every point
340 (x1,y1), (x2,y2), of the input image is
341 visible. The meaning of x and y is determined by
342 --input_system and --input_unit. You can specify any
343 number of semicolon-delimited points, including zero.
344 If you're supplying these options via a Unix command shell, be
346 sure to use proper quoting, because semicolon (;) is usually
347 a shell control character.
348 The frame options were new in Netpbm 10.25 (October 2004).
354 Output Size Options
357 --width=width
358 --height=height
360 These specify the size of the output image in horizontal and
363 vertical direction. The values are numbers of pixels, so only
364 natural numbers are valid. These values override the default
365 means to determine the output size.
366 --detail=num
369 If you do not specify --width, pamperspective
372 determines the width of the output image such that moving num
373 output pixels horizontally does not change the corresponding
374 pixel
375 coordinates of the input image by more than 1.
376 pamperspective determines the height of the output image
377 analogously. The default value is 1.
378 --proportion=prop
381 --ratio=ratio
383 Valid values for prop are:
386 free
390 In this case --ratio does not have any effect.
393 fixed After the width and height are determined
396 according to --detail, one of both will be increased, in
397 order to obtain width/height=ratio.
398 The defaults are --proportion=free and
402 --ratio=1.
403 Output Options
408 --output_system=spec
409 The output image consists of pixels, which are, from the point
412 of view of a scanline renderer, solid squares. This option
413 specifies how the four vertices of the quadrilateral corre‐
414 spond to
415 the pixels of the output image. Valid values for spec are:
416 lattice
420 The upper left vertex corresponds to the upper left corner of
423 the upper left pixel and The lower right vertex corresponds
424 to the
425 lower right corner of the lower right
426 pixel.
427 pixel
430 The upper left vertex corresponds to the center of the upper
433 left pixel and The lower right vertex corresponds to the
434 center of
435 the lower right pixel.
436 The default value is lattice. Point-and-click front ends
440 should use pixel.
441 --interpolation=spec
444 Usually (centers of) output pixels do not exactly correspond to
447 (centers of) input pixels. This option determines how the
448 program
449 will choose the new pixels. Valid values for spec are:
450 nearest
454 The output pixel will be identical to the nearest input
457 pixel.
458 linear
461 The output pixel will be a bilinear interpolation of the four
464 surrounding input pixels.
465 The default value is nearest.
469
474 It might be tempting always to use the options --include
475 0,0;0,1;1,0;1,1 (assuming --input_system=lattice and
476 --input_unit=image), so that no part of the input image is missing in
477 the output. There are problems with that:
478 · If the three dimensional plane defined by the quadrilateral has
482 a
483 visible horizon in the input image, then the above asks pam‐
484 perspective
485 to include points that cannot ever be part of the output.
486 · If the horizon is not visible, but close to the border of the
489 input image, this may result in very large output
490 files. Consider a picture of a road. If you ask for a point
491 close to
492 the horizon to be included, then this point is far away from
493 the
494 viewer. The output will cover many kilometers of road, while
495 --detail perhaps makes a pixel represent a square centimeter.
496 When working with large files pamperspective's memory usage might be an
500 issue. In order to keep it small, you should minimize each of the fol‐
501 lowing:
502 · The vertical range that the top output line consumes in the
506 input image;
507 · The vertical range that the bottom output line consumes in the
510 input image;
511 · The vertical range from the topmost (with respect to the
514 input image) quadrilateral point to the top (with respect to
515 the output
516 image) output line.
517 For this purpose you can use pamflip before and/or after pamper‐
521 spective. Example: Instead of
522 pamperspective 10 0 100 50 0 20 95 100 infile > outfile
524 you can use
526 pamflip -rotate90 infile |
528 pamperspective 50 0 100 5 0 90 20 100 |
529 pamflip -rotate270 > outfile
530
533 netpbm(1), pam(1), pnm(1), pamcut(1), pamflip(1), pnmrotate(1), pam‐
534 scale(1), pnmshear(1), pnmstitch(1)
535
538 Mark Weyer wrote pamperspective in March 2004.
539 It was new in Netpbm 10.22 (April 2004).
541
545 This documentation was written by Mark Weyer. Permission is granted to
546 copy, distribute and/or modify this document under the terms of the GNU
547 General Public License, Version 2 or any later version published by the
548 Free Software Foundation.
549netpbm documentation 2 September 2004 Pamperspective User Manual(0)