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       In  addition  to  the options common to all programs based on libnetpbm
84       (most notably -quiet, see
85        Common Options ⟨index.html#commonoptions⟩ ), pamperspective recognizes
86       the following command line options:
87
88       For  options  of  the form --name=num, You can specify the value num in
89       any of the traditional ways.   Additionally,  you  can  specify  it  as
90       num1/num2,  where  num1  and num2 are specified traditionally.  This is
91       useful for specifying a width/height ratio of 4/3,  without  having  to
92       write  infinitely  many  digits.  Where num is supposed to be a natural
93       number, pamperspective does not allow this format.
94
95
96   Quadrilateral Specification Options
97       --upper_left_x=num
98
99       --ulx=num
100
101
102              This specifies the horizontal coordinate of the upper left
103                vertex of the quadrilateral.  The meaning of 'upper left' is
104                relative to the output image.  The interpretation of num
105                depends on the values for --input_system and
106                --input_unit.
107
108
109       --upper_left_y=num
110
111       --uly=num
112
113
114              This specifies the vertical coordinate of the upper left vertex
115                of the quadrilateral.  The meaning of 'upper left' is relative
116              to
117                the output image.  The interpretation of num depends on the
118                values for --input_system and --input_unit.
119
120
121       --upper_right_x=num
122
123       --urx=num
124
125
126              This specifies the horizontal coordinate of the upper right
127                vertex of the quadrilateral.  The meaning of 'upper right' is
128                relative to the output image.  The interpretation of num
129                depends on the values for --input_system and
130                --input_unit.
131
132
133       --upper_right_y=num
134
135       --ury=num
136
137
138              This specifies the vertical coordinate of the upper right vertex
139                of  the  quadrilateral.  The meaning of 'upper right' is rela‐
140              tive to
141                the output image.  The interpretation of num depends on the
142                values for --input_system and --input_unit.
143
144
145       --lower_left_x=num
146
147       --llx=num
148
149
150              This specifies the horizontal coordinate of the lower left
151                vertex of the quadrilateral.  The meaning of 'lower left' is
152                relative to the output image.  The interpretation of num
153                depends on the values for --input_system and
154                --input_unit.
155
156
157       --lower_left_y=num
158
159       --lly=num
160
161
162              This specifies the vertical coordinate of the lower left vertex
163                of the quadrilateral.  The meaning of 'lower left' is relative
164              to
165                the output image.  The interpretation of num depends on the
166                values for --input_system and --input_unit.
167
168
169       --lower_right_x=num
170
171       --lrx=num
172
173
174              This specifies the horizontal coordinate of the lower right
175                vertex of the quadrilateral.  The meaning of 'lower right' is
176                relative to the output image.  The interpretation of num
177                depends on the values for --input_system and
178                --input_unit.
179
180
181       --lower_right_y=num
182
183       --lry=num
184
185
186              This specifies the vertical coordinate of the lower right vertex
187                of  the  quadrilateral.  The meaning of 'lower right' is rela‐
188              tive to
189                the output image.  The interpretation of num depends on the
190                values for --input_system and --input_unit.
191
192
193       --input_system=system
194
195       --input_unit=unit
196
197
198              The input image consists of pixels, which are, from the point of
199                view of a scanline renderer,  solid  squares.   These  options
200              specify
201                how the coordinates are interpreted:
202
203
204
205       system=lattice, unit=image
206
207
208              (0,0) refers to the upper left corner of the upper left pixel
209                  and  (1,1)  refers  to  the  lower right corner of the lower
210              right
211                  pixel.
212
213
214       system=lattice, unit=pixel
215
216
217              (0,0) refers to the upper left corner of the upper left pixel
218                  and (width,height) refers to the lower right corner
219                  of the lower right pixel.  Here width and height are
220                  the width and height of the input image.
221
222
223       system=pixel, unit=image
224
225
226              (0,0) refers to the center of the upper left pixel and (1,1)
227                  refers to the center of the lower right pixel.
228
229
230       system=pixel, unit=pixel
231
232
233              (0,0) refers to the center of the upper left pixel and
234                  (width-1,height-1) refers to the center of the lower
235                  right pixel.  Here width and height are the width
236                  and height of the input image.
237
238
239
240                The defaults are --input_system=lattice and
241                --input_unit=pixel.  Point-and-click front ends should
242                use --input_system=pixel.
243
244
245
246
247   Frame Options
248       By default pamperspective  outputs  exactly  the  above  parallelogram,
249       sheared  to a rectangle.  With the following options, it is possible to
250       make pamperspective output a larger or smaller portion, which  we  call
251       the  "visible  part." We refer to the default rectangle as the "frame."
252       The visible part is always a rectangle the axes of which  are  parallel
253       to those of the frame.
254
255       The  frame  options are additive.  All the parts of the image specified
256       by either margin  options,  --frame_include,  or  --include  (or  their
257       defaults)  are  in  the visible part.  The visible part is the smallest
258       possible rectangle that contains the parts specified those three ways.
259
260       The visible part must have nonzero size.  That  means  if  you  specify
261       --frame_include=no  (overriding  the  default),  you'll need to specify
262       other frame options in order to have something in the visible part.
263
264
265
266       [--margin=num]
267
268
269              This specifies an area surrounding the frame that is to be
270                included in the visible part.  The units of num are the width
271                of the frame for the horizontal extensions and the  height  of
272              the
273                frame for vertical extensions.
274
275              For example, --margin=1 makes the visible part 9 times as large,
276                because  it makes the visible part extend one frame's worth to
277              the left
278                of the frame, one frame's worth  to  the  right,  one  frame's
279              worth above
280                the  frame, and one frame's worth below the frame, for a total
281              of
282                3 frames' worth in both dimensions.
283
284              A negative value has an effect only if you specify
285                --frame_include=no.  The default is no margin.
286
287              The individual margin options below override this common margin
288                setting.
289
290
291
292       [--top_margin=num]
293
294       [--left_margin=num]
295
296       [--right_margin=num]
297
298       [--bottom_margin=num]
299
300
301              These are like --margin, but they specify only one of
302                the 4 sides.  The default value for  each  is  the  value  (or
303              default) of
304                --margin.
305
306
307
308       [--frame_include=bool]
309
310
311              Valid values for bool are:
312
313
314
315       yes
316
317       true
318
319       on
320
321
322              The frame itself is in the visible part.
323
324
325       no
326
327       false
328
329       off
330
331
332              The frame itself is not necessarily in the visible part
333                  (but it could be if other options cause it to be).
334
335
336
337
338                The default value is yes
339
340
341       --include=[x1,y1;x2,y2; ...]
342
343
344              The visible part is made large enough such that every point
345                (x1,y1), (x2,y2), of the input image is
346                visible.  The meaning of x and y is determined by
347                --input_system and --input_unit.  You can specify any
348                number of semicolon-delimited points, including zero.
349
350              If you're supplying these options via a Unix command shell, be
351                sure to use proper quoting, because semicolon (;) is usually
352                a shell control character.
353
354
355
356
357
358       The frame options were new in Netpbm 10.25 (October 2004).
359
360
361   Output Size Options
362       --width=width
363
364       --height=height
365
366
367              These specify the size of the output image in horizontal and
368                vertical direction.  The values are numbers of pixels, so only
369                natural numbers are valid.  These values override the default
370                means to determine the output size.
371
372
373       --detail=num
374
375
376              If you do not specify --width, pamperspective
377                determines the width of the output image such that moving num
378                output  pixels  horizontally does not change the corresponding
379              pixel
380                coordinates of the input image by more than 1.
381                pamperspective determines the height of the output image
382                analogously.  The default value is 1.
383
384
385       --proportion=prop
386
387       --ratio=ratio
388
389
390              Valid values for prop are:
391
392
393
394       free
395
396
397              In this case --ratio does not have any effect.
398
399
400       fixed  After the width and height are determined
401                  according to --detail, one of both will be increased, in
402                  order to obtain width/height=ratio.
403
404
405
406                The defaults are --proportion=free and
407                --ratio=1.
408
409
410
411
412   Output Options
413       --output_system=spec
414
415
416              The output image consists of pixels, which are, from the point
417                of view of a scanline renderer, solid squares.  This option
418                specifies how the four vertices of  the  quadrilateral  corre‐
419              spond to
420                the pixels of the output image.  Valid values for spec are:
421
422
423
424       lattice
425
426
427              The upper left vertex corresponds to the upper left corner of
428                  the  upper left pixel and The lower right vertex corresponds
429              to the
430                  lower right corner of the lower right
431                  pixel.
432
433
434       pixel
435
436
437              The upper left vertex corresponds to the center of the upper
438                  left pixel and The lower right  vertex  corresponds  to  the
439              center of
440                  the lower right pixel.
441
442
443
444                The default value is lattice.  Point-and-click front ends
445                should use pixel.
446
447
448       --interpolation=spec
449
450
451              Usually (centers of) output pixels do not exactly correspond to
452                (centers  of)  input  pixels.   This option determines how the
453              program
454                will choose the new pixels.  Valid values for spec are:
455
456
457
458       nearest
459
460
461              The output pixel will be identical to the nearest input
462                  pixel.
463
464
465       linear
466
467
468              The output pixel will be a bilinear interpolation of the four
469                  surrounding input pixels.
470
471
472
473                The default value is nearest.
474
475
476
477

HINTS

479       It  might  be  tempting   always   to   use   the   options   --include
480       0,0;0,1;1,0;1,1        (assuming       --input_system=lattice       and
481       --input_unit=image), so that no part of the input image is  missing  in
482       the output.  There are problems with that:
483
484
485
486       ·      If  the three dimensional plane defined by the quadrilateral has
487              a
488                visible horizon in the input image, then the above  asks  pam‐
489              perspective
490                to include points that cannot ever be part of the output.
491
492
493       ·      If the horizon is not visible, but close to the border of the
494                input image, this may result in very large output
495                files.  Consider  a  picture of a road. If you ask for a point
496              close to
497                the horizon to be included, then this point is far  away  from
498              the
499                viewer. The output will cover many kilometers of road, while
500                --detail perhaps makes a pixel represent a square centimeter.
501
502
503
504       When working with large files pamperspective's memory usage might be an
505       issue.  In order to keep it small, you should minimize each of the fol‐
506       lowing:
507
508
509
510       ·      The vertical range that the top output line consumes in the
511                input image;
512
513
514       ·      The vertical range that the bottom output line consumes in the
515                input image;
516
517
518       ·      The vertical range from the topmost (with respect to the
519                input  image)  quadrilateral point to the top (with respect to
520              the output
521                image) output line.
522
523
524
525              For this purpose you can use pamflip before and/or after pamper‐
526              spective. Example: Instead of
527
528              pamperspective 10 0 100 50 0 20 95 100 infile > outfile
529
530              you can use
531
532              pamflip -rotate90 infile |
533                 pamperspective 50 0 100 5 0 90 20 100 |
534                 pamflip -rotate270 > outfile
535
536

SEE ALSO

538       netpbm(1),  pam(1),  pnm(1),  pamcut(1), pamflip(1), pnmrotate(1), pam‐
539       scale(1), pnmshear(1), pamhomography(1), pnmstitch(1)
540
541

HISTORY

543       Mark Weyer wrote pamperspective in March 2004.
544
545       It was new in Netpbm 10.22 (April 2004).
546
547
548

AUTHOR

550       This documentation was written by Mark Weyer.  Permission is granted to
551       copy, distribute and/or modify this document under the terms of the GNU
552       General Public License, Version 2 or any later version published by the
553       Free Software Foundation.
554

DOCUMENT SOURCE

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