pamstretch

Scale up a PAM image by an integer factor

$ pamstretch [n] [path/to/image.pam] > [path/to/output.pam]

$ pamstretch [[-x|-xscale]] [xn] [[-y|-yscale]] [yn] [path/to/image.pam] > [path/to/output.pam]

pamstretch [-x x_factor] [-y y_factor] [-width width] [-height height] [-xwidth x_width] [-yheight y_height] [-linear | -bilinear | -cubic | -quadratic | -catrom] [-fill color] [-nomaxgray] [-time] [-verbose]

-x x_factor
    Stretches the image horizontally by the specified x_factor. For example, a factor of 2.0 doubles the width; 0.5 halves it.

-y y_factor
    Stretches the image vertically by the specified y_factor. For example, a factor of 2.0 doubles the height; 0.5 halves it.

-width width
    Sets the target width of the output image in pixels. The height will be scaled proportionally to maintain the aspect ratio unless -height is also specified.

-height height
    Sets the target height of the output image in pixels. The width will be scaled proportionally to maintain the aspect ratio unless -width is also specified.

-xwidth x_width
    Specifies the horizontal extent (radius) of the resampling filter in input pixels. Defaults vary by filter type (e.g., 3 for cubic, 2 for others). This is an advanced option for fine-tuning filter behavior.

-yheight y_height
    Specifies the vertical extent (radius) of the resampling filter in input pixels. Similar to -xwidth, this is an advanced option for filter customization.

-linear
    Uses linear interpolation for resampling. This is the fastest filter but generally produces the lowest quality output, often leading to pixelated results when enlarging.

-bilinear
    Uses bilinear interpolation for resampling. This is the default filter and offers a good balance between processing speed and output quality for most common resizing tasks.

-cubic
    Uses cubic interpolation for resampling. This filter is slower than linear or bilinear but typically yields better quality, often resulting in sharper images with smoother transitions.

-quadratic
    Uses quadratic interpolation for resampling. Another advanced filter option, similar to cubic, providing varying quality characteristics for specific resizing needs.

-catrom
    Uses Catmull-Rom interpolation for resampling. This filter is known for producing sharper images, making it ideal when preserving crisp details is a priority, though it can sometimes introduce minor artifacts.

-fill color
    Specifies a color to fill any new areas that become exposed due to stretching or when the filter extends beyond the original image boundaries. The color can be a recognized color name (e.g., "red") or a hexadecimal RGB value (e.g., "#FF0000").

-nomaxgray
    Prevents pamstretch from scaling the maxval (maximum pixel value) of the output image. This option is typically for backward compatibility with older Netpbm tools and is rarely needed for modern usage.

-time
    Reports the total time taken for the command execution to standard error, useful for performance monitoring.

-verbose
    Prints verbose information about the processing steps and progress to standard error, aiding in debugging or understanding command execution.

pamstretch is a powerful command-line utility from the Netpbm suite, specifically engineered for the precise resizing and resampling of images. It functions as a filter, reading a Netpbm image (supporting PAM, PGM, PPM, and PNM formats) from standard input and subsequently writing the processed, resized image to standard output.

What distinguishes pamstretch from more basic scaling tools is its advanced suite of interpolation algorithms. Users can choose from methods such as linear, bilinear (the default), cubic, quadratic, and Catmull-Rom. Each algorithm offers a unique trade-off between processing speed and the visual quality of the output, allowing for fine control over how pixels are interpolated during the resizing process. Whether the goal is to scale an image by a specific factor or to target exact pixel dimensions, pamstretch provides the necessary versatility for a wide range of image manipulation tasks, ensuring quality while adapting to different scaling requirements.

The default filter extents (values for -xwidth, -yheight) for certain filters might have changed across different versions of pamstretch or Netpbm. Always refer to the specific man page for your installed version if encountering unexpected results.

For very simple integer scaling operations, pamscale(1) might offer faster performance, although pamstretch generally provides superior image quality due to its advanced resampling algorithms for non-integer or significant resizing.

pamstretch is designed to operate as a filter program within a pipeline. This means it reads image data from its standard input (stdin) and writes the processed image data to its standard output (stdout). To use it effectively, you typically pipe image data to it from another command or redirect from a file, and then redirect its output to a new file or another command.

Example usage:
convert input.png pam:- | pamstretch -x 0.5 -y 0.5 > output.pam
or
cat input.pam | pamstretch -width 100 -height 100 > output_small.pam

The choice of resampling filter (e.g., -linear, -bilinear, -cubic, -catrom) significantly impacts the output image quality and processing speed:

-linear: Fastest, lowest quality, often leads to pixelated or blocky results, especially when enlarging.
-bilinear (default): A good balance between speed and quality, commonly used for general resizing. Offers smoother results than linear.
-cubic / -quadratic: Slower than bilinear, but generally produce better quality, often resulting in sharper details and smoother gradients.
-catrom: Tends to be the sharpest filter, ideal when preserving crispness is a priority, but it can sometimes introduce minor ringing artifacts.

pamstretch was developed as an integral part of the Netpbm project, a comprehensive suite of graphics utilities with a long-standing history in Unix-like environments. It was specifically introduced to expand upon Netpbm's existing image manipulation capabilities by providing more advanced image resampling options, particularly through the inclusion of various interpolation algorithms. Its development addressed the need for greater control over image quality during resizing, augmenting Netpbm's already robust set of tools for processing graphic files.

pamscale(1), pnm(5), pam(5)