How to use PVSqueeze.mm

The purpose of PVSqueeze is to correct vertical bowing at the top and bottom of images in Pannini projection, which can spoil the natural look of architectural images in particular.  It does this by shifting pixels in upper and lower "vees" defined by two pairs of lines radiating from a vanishing point.  The shifts are purely vertical near the center and radially inward toward the vanishing point farther out; the locations and widths of the transitition zones are adjustable with enough range so that the shift can be made all vertical or all radial.

The pixel shift, which is calculated to straighten the images of horizontal lines, depends on the the assumed parameters of the Pannini image (horizontal field of view and viewpoint distance) which are also adjustable. Of course the shift also depend on the positions of the radial lines, since it must be zero along those lines.

To use PVSqueeze you need version 1.3 of the Mathmap Gimp plugin, which is only available on Linux so far as I know.  To make the script accessible to the plugin you can either put it in the same directory as other Mathmap scripts, or paste it into the Mathmap script window and save it.

Step 1: generate a Panini projection showing a nice 1-point perspective view with the vanishing point within 15 degrees of image center.  You can do that with Panini, or a stitcher if you want higher resolution.  If you use Panini, PTGui or PTAssembler you can vary the horizontal compression (eye distance, in Panini) to suit.  In Hugin the eye distance is fixed at 1.  Try to estimate the horizontal field of view.

Step 2: Load it into Gimp and open filter/Generic/MathMap/Mathmap (not one of the preset script names).  LoadPVSqueeze and click Preview if necessary to see the low-res live image.  Then go to the User Values tab.  Set the hfov and eyeDist sliders roughly right for your Pannini.

Step 3: Adjust the vanishing point position (VPX, VPY), and the slopes of the 4 perspective edges (XXangl) to put them in the  appropriate places in your image.  The important thing is that they are parallel to the images of the top and bottom edges of the walls, if your image is a room.  There aren't any drawn lines, but the change of image shape is pretty easy to see as you move the sliders.  NOTE you have to set he projection center Y identical to the VP Y by hand, or you get a black triangle in the middle (bug; but misaligning them can help you see just where the VP is).

Step 4: Adjust the shift transition zone controls for the upper and lower Vees to suit.  Basically you need vertical shift where you have vertical features like columns or chair legs that must stay straight, while radial shift better preserves patterns on the floor or ceiling.   The shift direction varies with vertical position, from vertical at the VP to radial farther out.  xVlim controls the vertical level at which this transition starts, and xTwid the width of the transition zone.  You can set them for pure vertical or pure radial shift, or some blend.

Step 5: Hit OK, review the full size result in the Gimp window; save or go back and adjust some more.

