PAMPERSPECTIVE(1)

📦
version 11.13.03 · 4 versions
, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

👑 Pamperspec…ser Manual, section 1 — General Commands

okay so bestie, welcome to pamperspective</pam> — sorry, pamperspective — straight out of the general commands manual and it is literally the moment. 💅

✨ 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 💫

okay so the rules of the game, bestie:

  • You can totally abbreviate an option to its minimum unique abbreviation and that's fine. ⭐ But heads up — shortest unique prefixes might get longer in future versions of the program, so don't get too comfy.
  • Single hyphens are valid instead of the double hyphen to denote options. She's flexible like that. 🙈
  • White space can stand in for the equals sign when you're separating an option name from its value. no cap.
  • All options starting with hyphens may be given in any order. chaos-friendly. we love to see it. 💜

🎀 DESCRIPTION 🎀

This program is part of Netpbm(1). it's giving legacy, it's giving iconic. ✨

pamperspective reads a Netpbm image as input and produces a Netpbm image of the same format as output. same vibe in, same vibe out. 🔥

Here's the tea ☕: pamperspective interprets the input image as a perspective projection of another image which is in a plane oblique to that of the input image. Think: a photograph of a painting, taken at an angle. 😭 we've all been there.

The arguments upper_left_x … lower_right_y specify a quadrilateral in the photograph that pamperspective assumes corresponds to a parallelogram in the painting. The output image consists of this parallelogram, sheared to a rectangle. In this way pamperspective undoes the effect of a raytracer or scanline renderer. un-rendering the render, main character energy honestly. 👑

Note: 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 — but only to the extent that the scene is shallow from the other angle. 🦋 keeping it real.

The input is from infile, or from Standard Input, if infile is not specified. The output is to Standard Output. 💖

more parts coming bestie, don't go anywhere 🫶

✨ OPTIONS ✨

Okay bestie, so first things first: pamperspective gets all the options that every libnetpbm program has — most importantly -quiet, peek at Common Options for the whole tea. 💅 On top of those, it recognizes the following command line options.

For options shaped like --name=num, you can hand over the value num in any of the traditional ways, no stress. ✨ AND — extra slay — you can write it as num1/num2, where num1 and num2 are each specified the traditional way. This is iconic for stuff like a width/height ratio of 4/3 without having to type out infinitely many digits. 🎀 One lil exception though: where num is supposed to be a natural number, pamperspective does not allow this format. noted. 💀

🌸 Quadrilateral Specification Options 🌸

  • --upper_left_x=num
  • --ulx=num

This one sets the horizontal coordinate of the upper left vertex of the quadrilateral. "Upper left" is relative to the output image, bestie. How num gets interpreted depends on your values for --input_system and --input_unit. 🦋

  • --upper_left_y=num
  • --uly=num

Sets the vertical coordinate of the upper left vertex. Again, "upper left" is relative to the output image, and num's meaning depends on --input_system and --input_unit. 💜

  • --upper_right_x=num
  • --urx=num

Sets the horizontal coordinate of the upper right vertex. "Upper right" = relative to the output image. num depends on --input_system and --input_unit. ✨

  • --upper_right_y=num
  • --ury=num

Sets the vertical coordinate of the upper right vertex. Relative to the output image, and num depends on --input_system and --input_unit. 🌈

  • --lower_left_x=num
  • --llx=num

Sets the horizontal coordinate of the lower left vertex. Relative to the output image, num depends on --input_system and --input_unit. 🎀

  • --lower_left_y=num
  • --lly=num

Sets the vertical coordinate of the lower left vertex. Relative to the output image, num depends on --input_system and --input_unit. 🫶

  • --lower_right_x=num
  • --lrx=num

Sets the horizontal coordinate of the lower right vertex. Relative to the output image, num depends on --input_system and --input_unit. 👑

  • --lower_right_y=num
  • --lry=num

Sets the vertical coordinate of the lower right vertex. Relative to the output image, num depends on --input_system and --input_unit. 💖

  • --input_system=system
  • --input_unit=unit

A lil context drop before we go in: the input image is made of pixels, and from a scanline renderer's point of view those pixels are solid squares. 🟪 These two options decide how the coordinates get 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 center of the upper left pixel and (1,1) refers to the center of the lower right pixel.
  • system=pixel, unit=pixel — (0,0) refers to the center of the upper left pixel and (width-1,height-1) refers to the center 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. 💅 And heads up — point-and-click front ends should use --input_system=pixel. 😌

🖼️ Frame Options 🖼️

By default, pamperspective outputs exactly that parallelogram from before, sheared to a rectangle. But with these next options you can make it output a bigger or smaller portion — we call that the "visible part." 🦋 The default rectangle is the "frame." And the visible part is always a rectangle whose axes are parallel to the frame's axes. lowkey elegant.

The frame options are additive — they stack, bestie. Every part of the image specified by either the margin options, --include_frame, or --include (or their defaults) ends up in the visible part. The visible part is the smallest possible rectangle that contains everything specified those three ways. periodt.

The visible part must have nonzero size. ⚠️ So if you specify --frame_include=no (overriding the default), you're gonna need other frame options to actually have something in the visible part.

  • [--margin=num]

This specifies an area surrounding the frame to be included in the visible part. The units of num are the width of the frame for horizontal extensions and the height of the frame for vertical extensions. 📐

Example time, because numbers: --margin=1 makes the visible part 9 times as large — it extends one frame's worth to the left, one frame's worth to the right, one frame's worth above, and one frame's worth below, for a total of 3 frames' worth in both dimensions. slay. ✨

A negative value only does something if you specify --frame_include=no. The default is no margin. 😌

And the individual margin options below override this common margin setting.

  • [--top_margin=num]
  • [--left_margin=num]
  • [--right_margin=num]
  • [--bottom_margin=num]

These are just like --margin, except each one specifies 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; ...]

This makes the visible part large enough that every point (x1,y1), (x2,y2), ... of the input image is visible. 👀 The meaning of x and y is decided by --input_system and --input_unit. You can specify any number of semicolon-delimited points, including zero.

Pro tip, bestie: if you're supplying these options through a Unix command shell, use proper quoting! Because the semicolon (;) is usually a shell control character and it WILL ruin your day. 😭 Use quotes.

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 the horizontal and vertical direction. The values are numbers of pixels, so only natural numbers are valid, okurrr. These values override the default means of determining the output size. 💅

  • --detail=num

If you don't specify --width, pamperspective picks the width of the output image such that moving num output pixels horizontally doesn't change the corresponding pixel coordinates of the input image by more than 1. 🦋 And it works out the height analogously. The default value is 1.

  • --proportion=prop
  • --ratio=ratio

Valid values for prop are:

  • free — In this case --ratio doesn't have any effect at all. 🍓
  • fixed — After the width and height are determined according to --detail, one of the two gets increased, so that width/height=ratio. ✨

The defaults are --proportion=free and --ratio=1.

🎨 Output Options 🎨

  • --output_system=spec

The output image is made of pixels, which — from a scanline renderer's POV — are solid squares. 🟪 This option says how the four vertices of the quadrilateral correspond 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 center of the upper left pixel, and the lower right vertex corresponds to the center of the lower right pixel.

The default value is lattice. 💜 And point-and-click front ends should use pixel. 😌

  • --interpolation=spec

Usually the (centers of) output pixels don't exactly line up with the (centers of) input pixels — that's just how it is bestie. 😭 This option decides how the program picks 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 💭

ok bestie so listen, there is a temptation here and it is so real. You'll look at --include 0,0;0,1;1,0;1,1 (with --input_system=lattice and --input_unit=image, obvs) and you'll be like "omg perfect, nothing from my input image gets left out, slay" 🎀

But bestie. No. There are problems with that:

  • If the three dimensional plane that the quadrilateral defines has a visible horizon in the input image, then asking for that means you're telling pamperspective to include points that literally can never be part of the output. Like, they do not exist. Not a thing. 💀
  • If the horizon isn't visible but it's close to the border of the input image, you can end up with very large output files. Picture this: a photo of a road 🛣️. You ask it to include a point close to the horizon, and that point is so far away from the viewer. The output will now cover many kilometers of road, while --detail over here is out here making a single pixel represent a square centimeter. Unhinged behavior. 😭

When you're working with large files, pamperspective's memory usage might become a whole issue. To keep it small, you want to minimize each of these lil guys:

  • 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 pamperspective. 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

same energy, smaller memory footprint. iconique. ✨

👀 SEE ALSO 👀

netpbm(1), pam(1), pnm(1), pamcut(1), pamflip(1), pnmrotate(1), pamscale(1), pnmshear(1), pamhomography(1), pnmstitch(1)

go read those too, they're the rest of the friend group 🫶

📜 HISTORY 📜

Mark Weyer wrote pamperspective in March 2004. queen behavior fr fr 👑

It was new in Netpbm 10.22 (April 2004). so it's been serving looks for a minute 💅

✍️ 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.

(the legal said what it said, and we respect it 🫡)

🌸 DOCUMENT SOURCE 🌸

This manual page was generated by the Netpbm tool makeman from HTML source. The master documentation is at

http://netpbm.sourceforge.net/doc/pamperspective.html

okay that's the whole page bestie, you're officially pamperspective-pilled 💜 it's netpbm documentation from 02 September 2004, and yeah the footer says Pamperspec...ser Manual(1) — the man page renderer really said "not me truncating the title" 🙈 anyway, stan a perspective transform, go make something gorgeous, ily, bye! 🌈💖🎀🦋

📦 where this page comes from