1Pamperspective User Manual(0)                    Pamperspective User Manual(0)
2
3
4

NAME

6       pamperspective - a reverse scanline renderer for Netpbm images
7
8

SYNOPSIS

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
46
47

OPTION USAGE

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
56
57

DESCRIPTION

59       This program is part of Netpbm(1).
60
61       pamperspective reads a Netpbm image as  input  and  produces  a  Netpbm
62       image of the same format as output.
63
64       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
73       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
77       The input is from infile, or from Standard  Input,  if  infile  is  not
78       specified.  The output is to Standard Output.
79
80
81

OPTIONS

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
90
91   Quadrilateral specification options
92       --upper_left_x=num
93
94       --ulx=num
95
96
97              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
103
104       --upper_left_y=num
105
106       --uly=num
107
108
109              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
115
116       --upper_right_x=num
117
118       --urx=num
119
120
121              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
127
128       --upper_right_y=num
129
130       --ury=num
131
132
133              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
139
140       --lower_left_x=num
141
142       --llx=num
143
144
145              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
151
152       --lower_left_y=num
153
154       --lly=num
155
156
157              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
163
164       --lower_right_x=num
165
166       --lrx=num
167
168
169              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
175
176       --lower_right_y=num
177
178       --lry=num
179
180
181              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
187
188       --input_system=system
189
190       --input_unit=unit
191
192
193              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
198
199
200       system=lattice, unit=image
201
202
203              (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
208
209       system=lattice, unit=pixel
210
211
212              (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
217
218       system=pixel, unit=image
219
220
221              (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
224
225       system=pixel, unit=pixel
226
227
228              (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
233
234
235                The defaults are --input_system=lattice and
236                --input_unit=pixel.  Point-and-click front ends should
237                use --input_system=pixel.
238
239
240
241
242   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
250       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
255       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
259
260
261       [--margin=num]
262
263
264              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
270              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
279              A negative value has an effect only if you specify
280                --frame_include=no.  The default is no margin.
281
282              The individual margin options below override this common margin
283                setting.
284
285
286
287       [--top_margin=num]
288
289       [--left_margin=num]
290
291       [--right_margin=num]
292
293       [--bottom_margin=num]
294
295
296              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
301
302
303       [--frame_include=bool]
304
305
306              Valid values for bool are:
307
308
309
310       yes
311
312       true
313
314       on
315
316
317              The frame itself is in the visible part.
318
319
320       no
321
322       false
323
324       off
325
326
327              The frame itself is not necessarily in the visible part
328                  (but it could be if other options cause it to be).
329
330
331
332
333                The default value is yes
334
335
336       --include=[x1,y1;x2,y2; ...]
337
338
339              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
345              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
349
350
351
352
353       The frame options were new in Netpbm 10.25 (October 2004).
354
355
356   Output Size Options
357       --width=width
358
359       --height=height
360
361
362              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
367
368       --detail=num
369
370
371              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
379
380       --proportion=prop
381
382       --ratio=ratio
383
384
385              Valid values for prop are:
386
387
388
389       free
390
391
392              In this case --ratio does not have any effect.
393
394
395       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
399
400
401                The defaults are --proportion=free and
402                --ratio=1.
403
404
405
406
407   Output Options
408       --output_system=spec
409
410
411              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
417
418
419       lattice
420
421
422              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
428
429       pixel
430
431
432              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
437
438
439                The default value is lattice.  Point-and-click front ends
440                should use pixel.
441
442
443       --interpolation=spec
444
445
446              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
451
452
453       nearest
454
455
456              The output pixel will be identical to the nearest input
457                  pixel.
458
459
460       linear
461
462
463              The output pixel will be a bilinear interpolation of the four
464                  surrounding input pixels.
465
466
467
468                The default value is nearest.
469
470
471
472

HINTS

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
479
480
481       ·      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
487
488       ·      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
497
498
499       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
503
504
505       ·      The vertical range that the top output line consumes in the
506                input image;
507
508
509       ·      The vertical range that the bottom output line consumes in the
510                input image;
511
512
513       ·      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
518
519
520              For this purpose you can use pamflip before and/or after pamper‐
521              spective. Example: Instead of
522
523              pamperspective 10 0 100 50 0 20 95 100 infile > outfile
524
525              you can use
526
527              pamflip -rotate90 infile |
528                 pamperspective 50 0 100 5 0 90 20 100 |
529                 pamflip -rotate270 > outfile
530
531

SEE ALSO

533       netpbm(1),  pam(1),  pnm(1),  pamcut(1), pamflip(1), pnmrotate(1), pam‐
534       scale(1), pnmshear(1), pnmstitch(1)
535
536

HISTORY

538       Mark Weyer wrote pamperspective in March 2004.
539
540       It was new in Netpbm 10.22 (April 2004).
541
542
543

AUTHOR

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.
549
550
551
552netpbm documentation           2 September 2004  Pamperspective User Manual(0)
Impressum