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
48

OPTION USAGE

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

DESCRIPTION

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

OPTIONS

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
89       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
96
97   Quadrilateral Specification Options
98       --upper_left_x=num
99
100       --ulx=num
101
102
103              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
109
110       --upper_left_y=num
111
112       --uly=num
113
114
115              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
121
122       --upper_right_x=num
123
124       --urx=num
125
126
127              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
133
134       --upper_right_y=num
135
136       --ury=num
137
138
139              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
145
146       --lower_left_x=num
147
148       --llx=num
149
150
151              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
157
158       --lower_left_y=num
159
160       --lly=num
161
162
163              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
169
170       --lower_right_x=num
171
172       --lrx=num
173
174
175              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
181
182       --lower_right_y=num
183
184       --lry=num
185
186
187              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
193
194       --input_system=system
195
196       --input_unit=unit
197
198
199              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
204
205
206       system=lattice, unit=image
207
208
209              (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
214
215       system=lattice, unit=pixel
216
217
218              (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
223
224       system=pixel, unit=image
225
226
227              (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
230
231       system=pixel, unit=pixel
232
233
234              (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
239
240
241                The defaults are --input_system=lattice and
242                --input_unit=pixel.  Point-and-click front ends should
243                use --input_system=pixel.
244
245
246
247
248   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
256       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
261       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
265
266
267       [--margin=num]
268
269
270              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
276              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
285              A negative value has an effect only if you specify
286                --frame_include=no.  The default is no margin.
287
288              The individual margin options below override this common margin
289                setting.
290
291
292
293       [--top_margin=num]
294
295       [--left_margin=num]
296
297       [--right_margin=num]
298
299       [--bottom_margin=num]
300
301
302              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
307
308
309       [--frame_include=bool]
310
311
312              Valid values for bool are:
313
314
315
316       yes
317
318       true
319
320       on
321
322
323              The frame itself is in the visible part.
324
325
326       no
327
328       false
329
330       off
331
332
333              The frame itself is not necessarily in the visible part
334                  (but it could be if other options cause it to be).
335
336
337
338
339                The default value is yes
340
341
342       --include=[x1,y1;x2,y2; ...]
343
344
345              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
351              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
355
356
357
358
359       The frame options were new in Netpbm 10.25 (October 2004).
360
361
362   Output Size Options
363       --width=width
364
365       --height=height
366
367
368              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
373
374       --detail=num
375
376
377              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
385
386       --proportion=prop
387
388       --ratio=ratio
389
390
391              Valid values for prop are:
392
393
394
395       free
396
397
398              In this case --ratio does not have any effect.
399
400
401       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
405
406
407                The defaults are --proportion=free and
408                --ratio=1.
409
410
411
412
413   Output Options
414       --output_system=spec
415
416
417              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
423
424
425       lattice
426
427
428              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
434
435       pixel
436
437
438              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
443
444
445                The default value is lattice.  Point-and-click front ends
446                should use pixel.
447
448
449       --interpolation=spec
450
451
452              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
457
458
459       nearest
460
461
462              The output pixel will be identical to the nearest input
463                  pixel.
464
465
466       linear
467
468
469              The output pixel will be a bilinear interpolation of the four
470                  surrounding input pixels.
471
472
473
474                The default value is nearest.
475
476
477
478

HINTS

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
485
486
487       •      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
493
494       •      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
503
504
505       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
509
510
511       •      The vertical range that the top output line consumes in the
512                input image;
513
514
515       •      The vertical range that the bottom output line consumes in the
516                input image;
517
518
519       •      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
524
525
526              For this purpose you can use pamflip before and/or after pamper‐
527              spective. Example: Instead of
528
529              pamperspective 10 0 100 50 0 20 95 100 infile > outfile
530
531
532              you can use
533
534              pamflip -rotate90 infile |
535                 pamperspective 50 0 100 5 0 90 20 100 |
536                 pamflip -rotate270 > outfile
537
538
539

SEE ALSO

541       netpbm(1),  pam(1),  pnm(1),  pamcut(1), pamflip(1), pnmrotate(1), pam‐
542       scale(1), pnmshear(1), pamhomography(1), pnmstitch(1)
543
544

HISTORY

546       Mark Weyer wrote pamperspective in March 2004.
547
548       It was new in Netpbm 10.22 (April 2004).
549
550
551

AUTHOR

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

DOCUMENT SOURCE

559       This  manual  page was generated by the Netpbm tool 'makeman' from HTML
560       source.  The master documentation is at
561
562              http://netpbm.sourceforge.net/doc/pamperspective.html
563
564netpbm documentation           02 September 2004 Pamperspective User Manual(0)
Impressum