path: root/upstream/opensuse-leap-15-6/man1/pamperspective.1

\
.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
.\" the corresponding HTML page on the Netpbm website, generate a patch
.\" against that, and send it to the Netpbm maintainer.
.TH "Pamperspective User Manual" 0 "2 September 2004" "netpbm documentation"

.SH NAME

pamperspective - a reverse scanline renderer for Netpbm images

.UN synopsis
.SH SYNOPSIS

.nf
\fBpamperspective\fP 
    [\fB--bottom_margin=\fP\fInum\fP]
    [\fB--detail=\fP\fInum\fP]
    [\fB--frame_include=\fP\fIbool\fP]
    [\fB--height=\fP\fInum\fP]
    [\fB--include=[\fP\fIx1\fP,\fIy1\fP;\fIx2\fP,\fIy2\fP; ...]]
    [\fB--input_system=\fP\fIspec\fP]
    [\fB--input_unit=\fP\fIspec\fP]
    [\fB--interpolation=\fP\fIspec\fP]
    [\fB--left_margin=\fP\fInum\fP]
    [\fB--margin=\fP\fInum\fP]
    [\fB--output_system=\fP\fIspec\fP]
    [\fB--proportion=\fP\fIspec\fP]
    [\fB--ratio=\fP\fInum\fP]
    [\fB--right_margin=\fP\fInum\fP]
    [\fB--top_margin=\fP\fInum\fP]
    [\fB--width=\fP\fInum\fP]
    {
      {
        \fIupper_left_x\fP \fIupper_left_y\fP \fIupper_right_x\fP \fIupper_right_y\fP
        \fIlower_left_x\fP \fIlower_left_y\fP \fIlower_right_x\fP \fIlower_right_y\fP
      }
      |
      {
        {\fB--upper_left_x\fP|\fB--ulx\fP}\fB=\fP\fIupper_left_x\fP
        {\fB--upper_left_y\fP|\fB--uly\fP}\fB=\fP\fIupper_left_y\fP
        {\fB--upper_right_x\fP|\fB--urx\fP}\fB=\fP\fIupper_right_x\fP
        {\fB--upper_right_y\fP|\fB--ury\fP}\fB=\fP\fIupper_right_y\fP
        {\fB--lower_left_x\fP|\fB--llx\fP}\fB=\fP\fIlower_left_x\fP
        {\fB--lower_left_y\fP|\fB--lly\fP}\fB=\fP\fIlower_left_y\fP
        {\fB--lower_right_x\fP|\fB--lrx\fP}\fB=\fP\fIlower_right_x\fP
        {\fB--lower_right_y\fP|\fB--lry\fP}\fB=\fP\fIlower_right_y\fP
      }
   }
   [\fIinfile\fP]

.fi

.SH OPTION USAGE
.PP
Minimum unique abbreviation of option is acceptable. (But note 
that shortest unique prefixes might be longer in future versions of 
the program.) You may use single hyphens instead of double hyphen to 
denote options. You may use white space in place of the equals sign 
to separate an option name from its value. All options starting with 
hyphens may be given in any order. 


.UN description
.SH DESCRIPTION
.PP
This program is part of
.BR "Netpbm" (1)\c
\&.
.PP
\fBpamperspective\fP reads a Netpbm image as input and produces a
Netpbm image of the same format as output.
.PP
\fBpamperspective\fP interprets the input image as a perspective
projection of another image which is in a plane oblique to that of the
input image.  For example, a photograph of a painting, taken at an
angle.  The arguments \fIupper_left_x\fP ... \fIlower_right_y\fP
specify a quadrilateral in the photograph that \fBpamperspective\fP
assumes corresponds to a parallelogram in the painting.  The output
image consists of this parallelogram, sheared to a rectangle.  In this
way \fBpamperspective\fP undoes the effect of a raytracer or scanline
renderer.
.PP
Note that if the input image is a projection of a solid scene,
rather than a plane, the result is like a different camera angle on
that scene, to the extent that the scene is shallow from the other
angle.
.PP
The input is from \fIinfile\fP, or from Standard Input, if
\fIinfile\fP is not specified.  The output is to Standard Output.


.UN options
.SH OPTIONS
.PP
For options of the form \fB--name=\fP\fInum\fP, You can specify
the value \fInum\fP in any of the traditional ways.  Additionally,
you can specify it as \fInum1\fP/\fInum2\fP, where \fInum1\fP and
\fInum2\fP are specified traditionally.  This is useful for
specifying a width/height ratio of 4/3, without having to write
infinitely many digits.  Where \fInum\fP is supposed to be a natural
number, \fBpamperspective\fP does not allow this format.

.SS Quadrilateral specification options


.TP
\fB--upper_left_x=\fP\fInum\fP
.TP
\fB--ulx=\fP\fInum\fP

  
This specifies the horizontal coordinate of the upper left
  vertex of the quadrilateral.  The meaning of 'upper left' is
  relative to the output image.  The interpretation of \fInum\fP
  depends on the values for \fB--input_system\fP and
  \fB--input_unit\fP.

.TP
\fB--upper_left_y=\fP\fInum\fP
.TP
\fB--uly=\fP\fInum\fP

  
This specifies the vertical coordinate of the upper left vertex
  of the quadrilateral.  The meaning of 'upper left' is relative to
  the output image.  The interpretation of \fInum\fP depends on the
  values for \fB--input_system\fP and \fB--input_unit\fP.

.TP
\fB--upper_right_x=\fP\fInum\fP
.TP
\fB--urx=\fP\fInum\fP

  
This specifies the horizontal coordinate of the upper right
  vertex of the quadrilateral.  The meaning of 'upper right' is
  relative to the output image.  The interpretation of \fInum\fP
  depends on the values for \fB--input_system\fP and
  \fB--input_unit\fP.

.TP
\fB--upper_right_y=\fP\fInum\fP
.TP
\fB--ury=\fP\fInum\fP

  
This specifies the vertical coordinate of the upper right vertex
  of the quadrilateral.  The meaning of 'upper right' is relative to
  the output image.  The interpretation of \fInum\fP depends on the
  values for \fB--input_system\fP and \fB--input_unit\fP.

.TP
\fB--lower_left_x=\fP\fInum\fP
.TP
\fB--llx=\fP\fInum\fP

  
This specifies the horizontal coordinate of the lower left
  vertex of the quadrilateral.  The meaning of 'lower left' is
  relative to the output image.  The interpretation of \fInum\fP
  depends on the values for \fB--input_system\fP and
  \fB--input_unit\fP.

.TP
\fB--lower_left_y=\fP\fInum\fP
.TP
\fB--lly=\fP\fInum\fP

  
This specifies the vertical coordinate of the lower left vertex
  of the quadrilateral.  The meaning of 'lower left' is relative to
  the output image.  The interpretation of \fInum\fP depends on the
  values for \fB--input_system\fP and \fB--input_unit\fP.

.TP
\fB--lower_right_x=\fP\fInum\fP
.TP
\fB--lrx=\fP\fInum\fP

  
This specifies the horizontal coordinate of the lower right
  vertex of the quadrilateral.  The meaning of 'lower right' is
  relative to the output image.  The interpretation of \fInum\fP
  depends on the values for \fB--input_system\fP and
  \fB--input_unit\fP.

.TP
\fB--lower_right_y=\fP\fInum\fP
.TP
\fB--lry=\fP\fInum\fP

  
This specifies the vertical coordinate of the lower right vertex
  of the quadrilateral.  The meaning of 'lower right' is relative to
  the output image.  The interpretation of \fInum\fP depends on the
  values for \fB--input_system\fP and \fB--input_unit\fP.

.TP
\fB--input_system=\fP\fIsystem\fP
.TP
\fB--input_unit=\fP\fIunit\fP

  
The input image consists of pixels, which are, from the point of
  view of a scanline renderer, solid squares.  These options specify
  how the coordinates are interpreted:


.TP
\fIsystem\fP=\fBlattice\fP, \fIunit\fP=\fBimage\fP

    
(0,0) refers to the upper left corner of the upper left pixel
    and (1,1) refers to the lower right corner of the lower right
    pixel.

.TP
\fIsystem\fP=\fBlattice\fP, \fIunit\fP=\fBpixel\fP

    
(0,0) refers to the upper left corner of the upper left pixel
    and (\fIwidth\fP,\fIheight\fP) refers to the lower right corner
    of the lower right pixel.  Here \fIwidth\fP and \fIheight\fP are
    the width and height of the input image.

.TP
\fIsystem\fP=\fBpixel\fP, \fIunit\fP=\fBimage\fP

    
(0,0) refers to the center of the upper left pixel and (1,1)
    refers to the center of the lower right pixel.

.TP
\fIsystem\fP=\fBpixel\fP, \fIunit\fP=\fBpixel\fP

    
(0,0) refers to the center of the upper left pixel and
    (\fIwidth\fP-1,\fIheight\fP-1) refers to the center of the lower
    right pixel.  Here \fIwidth\fP and \fIheight\fP are the width
    and height of the input image.



  The defaults are \fB--input_system\fP=\fBlattice\fP and
  \fB--input_unit\fP=\fBpixel\fP.  Point-and-click front ends should
  use \fB--input_system\fP=\fBpixel\fP.



.UN frameoptions
.SS Frame Options

By default \fBpamperspective\fP outputs exactly the above
parallelogram, sheared to a rectangle.  With the following options, it
is possible to make \fBpamperspective\fP output a larger or smaller
portion, which we call the "visible part." We refer to the
default rectangle as the "frame." The visible part is always
a rectangle the axes of which are parallel to those of the frame.
.PP
The frame options are additive.  All the parts of the image
specified by either margin options, \fB--include_frame\fP, or
\fB--include\fP (or their defaults) are in the visible part.  The
visible part is the smallest possible rectangle that contains the
parts specified those three ways.
.PP
The visible part must have nonzero size.  That means if you specify
\fB--frame_include=no\fP (overriding the default), you'll need to
specify other frame options in order to have something in the visible
part.


.TP
[\fB--margin=\fP\fInum\fP]

  
This specifies an area surrounding the frame that is to be
  included in the visible part.  The units of \fInum\fP are the width
  of the frame for the horizontal extensions and the height of the
  frame for vertical extensions.
.sp
For example, \fB--margin=1\fP makes the visible part 9 times as large,
  because it makes the visible part extend one frame's worth to the left
  of the frame, one frame's worth to the right, one frame's worth above
  the frame, and one frame's worth below the frame, for a total of
  3 frames' worth in both dimensions.
.sp
A negative value has an effect only if you specify
  \fB--frame_include=no\fP.  The default is no margin.
.sp
The individual margin options below override this common margin
  setting.


.TP
[\fB--top_margin=\fP\fInum\fP]
.TP
[\fB--left_margin=\fP\fInum\fP]
.TP
[\fB--right_margin=\fP\fInum\fP]
.TP
[\fB--bottom_margin=\fP\fInum\fP]

  
These are like \fB--margin\fP, but they specify only one of 
  the 4 sides.  The default value for each is the value (or default) of
  \fB--margin\fP.


.TP
[\fB--frame_include=\fP\fIbool\fP]

  
Valid values for \fIbool\fP are:


.TP
\fByes\fP
.TP
\fBtrue\fP
.TP
\fBon\fP

    
The frame itself is in the visible part.

.TP
\fBno\fP
.TP
\fBfalse\fP
.TP
\fBoff\fP

    
The frame itself is not necessarily in the visible part
    (but it could be if other options cause it to be).




  The default value is \fByes\fP

.TP
\fB--include=[\fP\fIx1\fP,\fIy1\fP;\fIx2\fP,\fIy2\fP; ...]

  
The visible part is made large enough such that every point
  (\fIx1\fP,\fIy1\fP), (\fIx2\fP,\fIy2\fP), of the \fIinput\fP image is 
  visible.  The meaning of \fIx\fP and \fIy\fP is determined by
  \fB--input_system\fP and \fB--input_unit\fP.  You can specify any
  number of semicolon-delimited points, including zero.
.sp
If you're supplying these options via a Unix command shell, be
  sure to use proper quoting, because semicolon (\fB;\fP) is usually
  a shell control character.



  
.PP
The frame options were new in Netpbm 10.25 (October 2004).

.UN outputsizeoptions
.SS Output Size Options


.TP
\fB--width=\fP\fIwidth\fP
.TP
\fB--height=\fP\fIheight\fP

  
These specify the size of the output image in horizontal and
  vertical direction.  The values are numbers of pixels, so only
  natural numbers are valid.  These values override the default
  means to determine the output size.

.TP
\fB--detail=\fP\fInum\fP

  
If you do not specify \fB--width\fP, \fBpamperspective\fP
  determines the width of the output image such that moving \fInum\fP
  output pixels horizontally does not change the corresponding pixel
  coordinates of the input image by more than 1.
  \fBpamperspective\fP determines the height of the output image
  analogously.  The default value is 1.

.TP
\fB--proportion=\fP\fIprop\fP
.TP
\fB--ratio=\fP\fIratio\fP

  
Valid values for \fIprop\fP are:


.TP
\fBfree\fP

    
In this case \fB--ratio\fP does not have any effect.

.TP
\fBfixed\fP
After the width and height are determined
    according to \fB--detail\fP, one of both will be increased, in
    order to obtain width/height=\fIratio\fP.



  The defaults are \fB--proportion\fP=\fBfree\fP and
  \fB--ratio\fP=1.



.UN outputoptions
.SS Output Options


.TP
\fB--output_system=\fP\fIspec\fP

  
The output image consists of pixels, which are, from the point
  of view of a scanline renderer, solid squares.  This option
  specifies how the four vertices of the quadrilateral correspond to
  the pixels of the output image.  Valid values for \fIspec\fP are:


.TP
\fBlattice\fP

    
The upper left vertex corresponds to the upper left corner of
    the upper left pixel and The lower right vertex corresponds to the
    lower right corner of the lower right
    pixel.

.TP
\fBpixel\fP

    
The upper left vertex corresponds to the center of the upper
    left pixel and The lower right vertex corresponds to the center of
    the lower right pixel.



  The default value is \fBlattice\fP.  Point-and-click front ends
  should use \fBpixel\fP.

.TP
\fB--interpolation=\fP\fIspec\fP

  
Usually (centers of) output pixels do not exactly correspond to
  (centers of) input pixels.  This option determines how the program
  will choose the new pixels.  Valid values for \fIspec\fP are:


.TP
\fBnearest\fP

    
The output pixel will be identical to the nearest input
    pixel.

.TP
\fBlinear\fP

    
The output pixel will be a bilinear interpolation of the four
    surrounding input pixels.



  The default value is \fBnearest\fP.



.UN hints
.SH HINTS
.PP
It might be tempting always to use the options
\fB--include 0,0;0,1;1,0;1,1\fP 
(assuming \fB--input_system=lattice\fP and \fB--input_unit=image\fP), 
so that no part of the input image is missing in the output. 
There are problems with that:


.IP \(bu
If the three dimensional plane defined by the quadrilateral has a
  visible horizon in the input image, then the above asks \fBpamperspective\fP
  to include points that cannot ever be part of the output.

.IP \(bu
If the horizon is not visible, but close to the border of the
  input image, this may result in \fIvery\fP large output
  files. Consider a picture of a road. If you ask for a point close to
  the horizon to be included, then this point is far away from the
  viewer. The output will cover many kilometers of road, while
  \fB--detail\fP perhaps makes a pixel represent a square centimeter.

  
.PP
When working with large files \fBpamperspective\fP's memory usage
might be an issue.  In order to keep it small, you should minimize each
of the following:


.IP \(bu
The vertical range that the top output line consumes in the
  input image;

.IP \(bu
The vertical range that the bottom output line consumes in the
  input image;

.IP \(bu
The vertical range from the topmost (with respect to the 
  input image) quadrilateral point to the top (with respect to the output 
  image) output line.

  

For this purpose you can use \fBpamflip\fP before and/or after
\fBpamperspective\fP. Example: Instead of

.nf
\fBpamperspective 10 0 100 50 0 20 95 100 infile > outfile\fP
.fi

you can use

.nf
\fB
pamflip -rotate90 infile | 
   pamperspective 50 0 100 5 0 90 20 100 | 
   pamflip -rotate270 > outfile
\fP
.fi
  
.UN seealso
.SH SEE ALSO
.BR "\fBnetpbm\fP" (1)\c
\&,
.BR "\fBpam\fP" (1)\c
\&,
.BR "\fBpnm\fP" (1)\c
\&,
.BR "\fBpamcut\fP" (1)\c
\&,
.BR "\fBpamflip\fP" (1)\c
\&,
.BR "\fBpnmrotate\fP" (1)\c
\&,
.BR "\fBpamscale\fP" (1)\c
\&,
.BR "\fBpnmshear\fP" (1)\c
\&,
.BR "\fBpnmstitch\fP" (1)\c
\&

.UN history
.SH HISTORY
.PP
Mark Weyer wrote \fBpamperspective\fP in March 2004.
.PP
It was new in Netpbm 10.22 (April 2004).


.UN author
.SH AUTHOR

This documentation was written by Mark Weyer.  Permission is granted
to copy, distribute and/or modify this document under the terms of the
GNU General Public License, Version 2 or any later version published
by the Free Software Foundation.
.SH DOCUMENT SOURCE
This manual page was generated by the Netpbm tool 'makeman' from HTML
source.  The master documentation is at
.IP
.B http://netpbm.sourceforge.net/doc/pamperspective.html
.PP