pamperspective
Pamperspective User Manual(0) Pamperspective User Manual(0)
NAME
pamperspective - a reverse scanline renderer for Netpbm images
SYNOPSIS
pamperspective
[--bottom_margin=num]
[--detail=num]
[--frame_include=bool]
[--height=num]
[--include=[x1,y1;x2,y2; ...]]
[--input_system=spec]
[--input_unit=spec]
[--interpolation=spec]
[--left_margin=num]
[--margin=num]
[--output_system=spec]
[--proportion=spec]
[--ratio=num]
[--right_margin=num]
[--top_margin=num]
[--width=num]
{
{
upper_left_x upper_left_y upper_right_x upper_right_y
lower_left_x lower_left_y lower_right_x lower_right_y
}
|
{
{--upper_left_x|--ulx}=upper_left_x
{--upper_left_y|--uly}=upper_left_y
{--upper_right_x|--urx}=upper_right_x
{--upper_right_y|--ury}=upper_right_y
{--lower_left_x|--llx}=lower_left_x
{--lower_left_y|--lly}=lower_left_y
{--lower_right_x|--lrx}=lower_right_x
{--lower_right_y|--lry}=lower_right_y
}
}
[infile]
OPTION USAGE
Minimum unique abbreviation of option is acceptable. (But note that
shortest unique prefixes might be longer in future versions of the pro-
gram.) You may use single hyphens instead of double hyphen to denote
options. You may use white space in place of the equals sign to sepa-
rate an option name from its value. All options starting with hyphens
may be given in any order.
DESCRIPTION
This program is part of Netpbm(1).
pamperspective reads a Netpbm image as input and produces a Netpbm
image of the same format as output.
The values upper_left_x ... lower_right_y, that are required on the
command line, specify a quadrilateral in the input image. pamperspec-
tive interprets the input image as a perspective projection of a three
dimensional scene, for example a photograph. pamperspective assumes
the specified quadrilateral represents a parallelogram in that scene.
The output image consists of this parallelogram, sheared to a rectan-
gle. In this way pamperspective undoes the effect of a raytracer or
scanline renderer.
The input is from infile, or from Standard Input, if infile is not
specified. The output is to Standard Output.
OPTIONS
For options of the form --name=num, You can specify the value num in
any of the traditional ways. Additionally, you can specify it as
num1/num2, where num1 and num2 are specified traditionally. This is
useful for specifying a width/height ratio of 4/3, without having to
write infinitely many digits. Where num is supposed to be a natural
number, pamperspective does not allow this format.
Quadrilateral specification options
--upper_left_x=num
--ulx=num
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 num
depends on the values for --input_system and
--input_unit.
--upper_left_y=num
--uly=num
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 num depends on the
values for --input_system and --input_unit.
--upper_right_x=num
--urx=num
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 num
depends on the values for --input_system and
--input_unit.
--upper_right_y=num
--ury=num
This specifies the vertical coordinate of the upper right vertex
of the quadrilateral. The meaning of 'upper right' is rela-
tive to
the output image. The interpretation of num depends on the
values for --input_system and --input_unit.
--lower_left_x=num
--llx=num
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 num
depends on the values for --input_system and
--input_unit.
--lower_left_y=num
--lly=num
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 num depends on the
values for --input_system and --input_unit.
--lower_right_x=num
--lrx=num
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 num
depends on the values for --input_system and
--input_unit.
--lower_right_y=num
--lry=num
This specifies the vertical coordinate of the lower right vertex
of the quadrilateral. The meaning of 'lower right' is rela-
tive to
the output image. The interpretation of num depends on the
values for --input_system and --input_unit.
--input_system=system
--input_unit=unit
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:
system=lattice, unit=image
(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.
system=lattice, unit=pixel
(0,0) refers to the upper left corner of the upper left pixel
and (width,height) refers to the lower right corner
of the lower right pixel. Here width and height are
the width and height of the input image.
system=pixel, unit=image
(0,0) refers to the centre of the upper left pixel and (1,1)
refers to the centre of the lower right pixel.
system=pixel, unit=pixel
(0,0) refers to the centre of the upper left pixel and
(width-1,height-1) refers to the centre of the lower
right pixel. Here width and height are the width
and height of the input image.
The defaults are --input_system=lattice and
--input_unit=pixel. Point-and-click front ends should
use --input_system=pixel.
Frame options
By default pamperspective outputs exactly the above parallelogram,
sheared to a rectangle. With the following options, it is possible to
make pamperspective 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.
The frame options are additive. All the parts of the image specified
by either margin options, --include_frame, or --include (or their
defaults) are in the visible part. The visible part is the smallest
possible rectangle that contains the parts specified those three ways.
The visible part must have nonzero size. That means if you specify
--frame-include=no (overriding the default), you'll need to specify
other frame options in order to have something in the visible part.
[--margin=num]
This specifies an area surrounding the frame that is to be
included in the visible part. The units of num are the width
of the frame for the horizontal extensions and the height of
the
frame for vertical extensions.
For example, --margin=1 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.
A negative value has an effect only if you specify
--frame_include=no. The default is no margin.
The individual margin options below override this common margin
setting.
[--top_margin=num]
[--left_margin=num]
[--right_margin=num]
[--bottom_margin=num]
These are like --margin, but they specify only one of
the 4 sides. The default value for each is the value (or
default) of
--margin.
[--frame_include=bool]
Valid values for bool are:
yes
true
on
The frame itself is in the visible part.
no
false
off
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 yes
--include=[x1,y1;x2,y2; ...]
The visible part is made large enough such that every point
(x1,y1), (x2,y2), of the input image is
visible. The meaning of x and y is determined by
--input_system and --input_unit. You can specify any
number of semicolon-delimited points, including zero.
If you're supplying these options via a Unix command shell, be
sure to use proper quoting, because semicolon (;) is usually
a shell control character.
The frame options were new in Netpbm 10.25 (October 2004).
Output size options
--width=width
--height=height
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.
--detail=num
If you do not specify --width, pamperspective
determines the width of the output image such that moving num
output pixels horizontally does not change the corresponding
pixel
coordinates of the input image by more than 1.
pamperspective determines the height of the output image
analogously. The default value is 1.
--proportion=prop
--ratio=ratio
Valid values for prop are:
free
In this case --ratio does not have any effect.
fixed After the width and height are determined
according to --detail, one of both will be increased, in
order to obtain width/height=ratio.
The defaults are --proportion=free and
--ratio=1.
Output options
--output_system=spec
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 corre-
spond to
the pixels of the output image. Valid values for spec are:
lattice
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.
pixel
The upper left vertex corresponds to the centre of the upper
left pixel and The lower right vertex corresponds to the
centre of
the lower right pixel.
The default value is lattice. Point-and-click front ends
should use pixel.
--interpolation=spec
Usually (centres of) output pixels do not exactly correspond to
(centres of) input pixels. This option determines how the
program
will choose the new pixels. Valid values for spec are:
nearest
The output pixel will be identical to the nearest input
pixel.
linear
The output pixel will be a bilinear interpolation of the four
surrounding input pixels.
The default value is nearest.
HINTS
It might be tempting always to use the options --include
0,0;0,1;1,0;1,1 (assuming --input_system=lattice and
--input_unit=image), so that no part of the input image is missing in
the output. There are problems with that:
· If the threedimensional plane defined by the quadrilateral has a
visible horizon in the input image, then the above asks pam-
perspective
to include points that cannot ever be part of the output.
· If the horizon is not visible, but close to the border of the
input
image, this may result in very large output files. Consider a
picture of a road. If you ask 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 --detail perhaps makes a pixel equal
to a
square centimeter.
When working with large files pamperspective's memory usage might be an
issue. In order to keep it small, you should minimize each of the fol-
lowing:
· The vertical range that the top output line consumes in the
input image;
· The vertical range that the bottom output line consumes in the
input image;
· 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 pamflip before and/or after pamper-
spective. Example: Instead of
pamperspective 10 0 100 50 0 20 95 100 infile > outfile
you can use
pamflip -rotate90 infile |
pamperspective 50 0 100 5 0 90 20 100 |
pamflip -rotate270 > outfile
SEE ALSO
netpbm(1), pam(1), pnm(1), pamcut(1), pamflip(1), pnmrotate(1), pam-
scale(1), pnmshear(1), pnmstitch(1)
HISTORY
Mark Weyer wrote pamperspective in March 2004.
It was new in Netpbm 10.22 (April 2004).
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.
Table Of Contents
· NAME
· SYNOPSIS
· DESCRIPTION
· OPTIONS
· HINTS
· SEE ALSO
· HISTORY
· AUTHOR
netpbm documentation 2 September 2004 Pamperspective User Manual(0)