diff options
Diffstat (limited to '')
| -rw-r--r-- | upstream/opensuse-leap-15-6/man1/pamperspective.1 | 585 |
1 files changed, 585 insertions, 0 deletions
diff --git a/upstream/opensuse-leap-15-6/man1/pamperspective.1 b/upstream/opensuse-leap-15-6/man1/pamperspective.1 new file mode 100644 index 00000000..fce28d2c --- /dev/null +++ b/upstream/opensuse-leap-15-6/man1/pamperspective.1 @@ -0,0 +1,585 @@ +\ +.\" 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
\ No newline at end of file |