Rearrange Netpbm Image Rows Safely with pamrestack

pamrestack reslices an image's raw pixel sequence into rows of whatever width you ask for.

It does not resize, rotate or resample: it is the tool you reach for when a capture or generator got the row width wrong and the pixels themselves are already fine.

Allow about fifteen minutes. You need a shell, a readable PAM, PBM, PGM, PPM or other Netpbm input, and permission to write the destination directory. No example needs sudo. This guide changes no system configuration and does not require elevated privileges. The examples use pamrestack from Netpbm 11.5.2, packaged here as Debian package version 2:11.05.02-1.1build1.

1. Check the installed command

Confirm which executable your shell will run and record the local Netpbm build:

$ command -v pamrestack
/usr/bin/pamrestack
$ pamrestack --version
pamrestack: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
pamrestack: Built from source dated 2024-03-31 09:09:47
pamrestack: Built by Debian
pamrestack: Use 'man pamrestack' for help.

The version output also prints build details and a help reminder; the part that matters for this guide is the Netpbm library version. If your output differs, keep it with your notes: image formats and diagnostics can vary between package releases.

2. Understand what is being rearranged

pamrestack does not resize, rotate or resample pixels. It reads each input image as one long first-in, first-out sequence of pixels, then emits that sequence in rows of the requested width. A 100 by 50 image therefore contains 5,000 pixels; with -width=125, the output is 125 by 40.

Output goes to standard output. If you omit the input filename, input comes from standard input, which makes pipelines useful but also makes shell redirection easy to get wrong. The source file itself is never edited in place.

With no -width, pamrestack produces one output row containing every pixel in the input image. For a small, known input you can verify that default:

$ pamseq 1 5 -min=0 -max=5 > sequence.pam
$ pamrestack sequence.pam > one-row.pam
$ pamfile one-row.pam
one-row.pam: PAM, 6 by 1 by 1 maxval 5

pamseq is only a convenient test-input generator; for a real image, replace sequence.pam with its path. Do not use an input and output name together with >: the shell truncates the output file before pamrestack can even read it.

3. Choose the output width

Pass the desired number of pixels in each output row with -width. The option accepts either an equals sign or whitespace, and long options may use two hyphens. Use the full spelling in scripts so the intended operation is obvious:

$ pamrestack -width=7 sequence.pam > seven-wide.pam
$ pamfile seven-wide.pam
seven-wide.pam: PAM, 7 by 1 by 1 maxval 5

This input has six pixels, so the result cannot contain a complete row of seven. The default is -trim=fill, which pads the final row with black pixels; here the output is seven pixels wide and the added pixel has the image's black value.

When the input is a stream, place the width after the producer and pipe its standard output into pamrestack:

$ pamseq 3 255 | pamrestack -width=4096 > square-or-near-square.pam
$ pamfile square-or-near-square.pam
square-or-near-square.pam: PAM, 4096 by 1 by 3 maxval 255

The exact height depends on the number of pixels generated. A square result needs a source whose pixel count divides evenly into the chosen width and height. Check the dimensions instead of trusting the output filename.

4. Pick a policy for an incomplete final row

If the new width does not divide the input pixel count, set -trim explicitly when the result matters. The three policies have different consequences:

• fill, the default, pads the final row with black pixels. Suitable when a rectangular output is required and padding is acceptable.
• crop discards the incomplete final row. If that would leave no output, pamrestack fails.
• abort fails as soon as it finds that the width does not divide the pixel count. The safest choice when invented pixels or silent loss would be unacceptable.

Use the strict mode for a conversion where dimensions are an integrity check:

$ pamrestack -width=7 -trim=abort sequence.pam > checked.pam
pamrestack: Abort mode specified and input image has 6 pixels which is less than specified width value 7
$ printf 'exit status: %s\n' "$?"
exit status: 1

The error wording describes this particular input and width; what matters is the non-zero status and the fact that no valid output was produced. The shell still creates or truncates the redirected destination before pamrestack starts, so use a temporary destination when preserving an existing file matters.

$ pamrestack -width=7 -trim=abort sequence.pam > checked.pam.new
$ status=$?
$ if [ "$status" -eq 0 ]; then mv checked.pam.new checked.pam; else echo "pamrestack failed: $status"; fi
pamrestack failed: 1

After a failure, inspect or remove checked.pam.new only once you have confirmed it is the disposable temporary output. The original checked.pam, if it existed, stays untouched. If the command succeeds, inspect the new file before replacing a valuable result.

5. Process streams and pipelines carefully

pamrestack supports a multi-image stream. It rearranges each image independently rather than joining the images into one pixel sequence, which matters when a producer emits several images:

$ cat first.pam second.pam | pamrestack -width=7 > restacked-stream.pam
$ pamfile restacked-stream.pam
restacked-stream.pam: PAM, 7 by 1 by 1 maxval 5

The displayed dimensions describe the test stream only; your output depends on each input image. Keep the stream in a format that preserves its image boundaries. If you need one combined image, use a tool designed to combine images before or after pamrestack, and verify the result with pamfile.

For interlacing workflows, pamrestack can follow tools such as pamcat, pamflip, pamdice or pamundice. Treat every pipeline stage as a separate contract: check its exit status and send the final stream to a new file until the dimensions and appearance are correct.

6. Use diagnostics when the result needs explanation

Add -verbose to print processing information on standard error while keeping the image on standard output:

$ pamrestack -width=7 -verbose sequence.pam > verbose.pam
pamrestack: Output image will have 1 more pixels than input image.  Incomplete final row will be padded.

If the dimensions are surprising, check the input first:

$ pamfile sequence.pam
sequence.pam: PAM, 6 by 1 by 1 maxval 5
$ pamrestack -width=7 -trim=abort sequence.pam > /tmp/restacked-check.pam
$ printf 'exit status: %s\n' "$?"
exit status: 1

A successful exit status only tells you that pamrestack completed its processing. It does not prove the chosen width matches the image's visual intent. Keep the source, verify the dimensions, and view or convert the output with a suitable Netpbm or image tool before deleting anything.