Scale Netpbm Images Smoothly by Non-Integer Factors

You will use pamstretch-gen to enlarge a Netpbm image by a fractional factor, such as 2.5, and verify the resulting dimensions without guessing. The examples use ordinary user privileges and do not alter the input file. Allow about 10 minutes if Netpbm is already installed.

Before you start

You need the pamstretch-gen command and an image in a Netpbm format such as PGM, PPM or PAM. Check both before spending time on the command:

$ command -v pamstretch-gen
/usr/bin/pamstretch-gen
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1

The version shown here is the Ubuntu package installed on the reference machine. Your package revision may differ. The local manual page is dated 15 January 2019, while the installed wrapper is from Netpbm 11.05.02.

1. Create a small test image

If you already have a suitable image, skip to step 2. Otherwise create a disposable two-row PGM file so the dimensions are easy to check:

$ INPUT=/tmp/pamstretch-input.pgm
$ printf 'P2\n4 2\n255\n0 64 128 255\n255 128 64 0\n' > "$INPUT"
$ pamfile "$INPUT"
/tmp/pamstretch-input.pgm:	PGM plain, 4 by 2  maxval 255

This writes only under /tmp. To remove that test input and its output later, use rm -- /tmp/pamstretch-input.pgm /tmp/pamstretch-output.pgm. Do not substitute a path to an original image in a cleanup command.

2. Scale by a fractional factor

Pass the scale factor first, followed by the optional input filename. Redirect standard output to a new file:

$ OUTPUT=/tmp/pamstretch-output.pgm
$ pamstretch-gen 2.5 "$INPUT" > "$OUTPUT"
$ pamfile "$OUTPUT"
/tmp/pamstretch-output.pgm:	PGM raw, 10 by 5  maxval 255

The factor applies to both dimensions. A 4 by 2 input therefore becomes 10 by 5 after rounding to output pixels. pamstretch-gen combines pamstretch and pamscale; it first chooses an integer stretch internally and then scales to the requested dimensions. Its use of pamstretch -dropedge is part of that calculation, so the result is not equivalent to simply running an arbitrary integer stretch yourself.

The output goes to standard output. The input is read but not replaced, so this command is reversible by deleting the new output:

$ cmp -s "$INPUT" "$OUTPUT"; printf 'same bytes: %s\n' "$?"
same bytes: 1

A status of 1 here means the files differ, as expected. It is not an error from pamstretch-gen. Prefer a separate output path while testing.

3. Use standard input when that is clearer

With no input filename, the command reads the image from standard input. This is useful in a pipeline or when a producer already writes Netpbm data:

$ pamstretch-gen 1.5 < "$INPUT" > /tmp/pamstretch-15x.pgm
$ pamfile /tmp/pamstretch-15x.pgm
/tmp/pamstretch-15x.pgm:	PGM raw, 6 by 3  maxval 255

Do not put the output filename immediately after the factor and assume it is an output argument. The second positional argument is an input filename. Use shell redirection for output.

4. Add global options in the right place

The program has no options specific to itself. It accepts selected Netpbm global options, including -quiet, -plain and -verbose. Put these before the factor because the installed program is a shell wrapper that parses them before reading its positional arguments:

$ pamstretch-gen -quiet 2.5 "$INPUT" > /tmp/pamstretch-quiet.pgm
$ pamfile /tmp/pamstretch-quiet.pgm
/tmp/pamstretch-quiet.pgm:	PGM raw, 10 by 5  maxval 255

-plain asks Netpbm for plain output where the downstream program supports it. -verbose reports the rounded internal stretch factor on standard error; it does not turn the image into text. Keep diagnostics separate from the image if you capture output, as in the examples.

The manual records that -quiet and -plain were added in Netpbm 10.86, and that -quiet did not work until 10.91. The installed 11.05.02 package is newer than both thresholds. On an older host, check its local manual rather than assuming these options exist.

5. Diagnose a failed run

First check the exit status and preserve standard error. A failed command may leave an empty redirected file, so do not treat the presence of the output path as success:

$ pamstretch-gen 2.5 /path/that/does-not-exist > /tmp/pamstretch-failed.pgm 2> /tmp/pamstretch-error.txt
$ printf 'status: %s\n' "$?"
status: 1
$ sed -n '1,4p' /tmp/pamstretch-error.txt
pamstretch-gen: error reading file /path/that/does-not-exist

If the input is not Netpbm data, pamscale -reportonly or one of the internal stages will report a magic-number or parsing error. Check the source with pamfile before retrying. If the factor is zero, negative or otherwise unusable, expect a non-zero status and diagnostic rather than a meaningful image.

Very small images can expose edge limits in the internal pamstretch stage. For example, a one-column test image may fail with an image-too-narrow diagnostic even though the requested factor looks reasonable. Retry with the real image or a test image at least two columns wide, then verify the dimensions.

6. Keep the safety boundary clear

No elevated privileges are needed to read an image and write to a directory you own. Do not use sudo merely because scaling failed. It will not repair malformed input, a bad factor or an unwritable destination. If the destination is a protected system directory, use a user-writable temporary output first and arrange any later installation as a separate, reviewed operation.

For a large image or a high factor, the output can consume substantially more disk space and memory than the input. Check available space before a bulk operation, and scale one file first. If a command is interrupted, inspect the output with pamfile before using it; remove an incomplete file only when you have confirmed it is disposable.