Repair a Truncated Netpbm Image with pamfixtrunc

pamfixtrunc salvages a Netpbm image whose final rows are missing, writing a new image with a corrected height and leaving the damaged input alone. This guide covers the safe workflow, plus the replacement command to use in new scripts.

Allow about 10 minutes. You need Netpbm installed, a readable PGM, PPM or PAM file, and enough space for a second copy of the recovered image. The examples use a PGM file, but the command accepts Netpbm input rather than going by a filename extension.

1. Confirm what you are running

• Check the installed commands. This needs no elevated privileges.

command -v pamfixtrunc
command -v pamfix
dpkg-query -W -f='${Version}\n' netpbm

On the system used for this guide, the package is Netpbm 2:11.05.02-1.1build1, with both commands in /usr/bin. Your distribution may report a different package version.

The installed pamfixtrunc is a compatibility wrapper: it invokes pamfix and adds -truncate, which is why diagnostics can name pamfix even when you started pamfixtrunc. Netpbm 10.66, released in March 2014, replaced the old program with pamfix. Keep the old name when an existing script still needs it, but use pamfix -truncate for new work.

2. Test the source without changing it

• Ask pamfile whether the image is too small. Swap in the damaged file's real path. This is a read-only check.

pamfile --allimages /path/to/damaged-image.pgm

A complete image is described with its format, dimensions and maximum sample value. A file shorter than its header declares causes pamfile --allimages to fail with an error saying it could not read the whole image. A successful check does not prove the picture is visually correct; it only answers the size question.

Do not confuse a truncated file with a valid image you deliberately want to crop; for a valid image, use pamcut instead. pamfixtrunc assumes unreadable data means the bottom of the image is missing, so it can hand you a valid-looking file containing a damaged or incomplete picture when the real fault lies elsewhere.

3. Write a recovered copy

• Redirect the repaired image to a new pathname. Ordinary user privileges are enough when both files sit in a directory you can write.

pamfixtrunc /path/to/damaged-image.pgm > /path/to/recovered-image.pgm

The command reads standard input or the filename on the command line and writes the repaired Netpbm image to standard output. It does not edit the source file. The output header records only the complete rows that could be read, and any partial final row is omitted.

For a script that has already migrated to the replacement interface, use the equivalent command:

pamfix -truncate /path/to/damaged-image.pgm > /path/to/recovered-image.pgm

Both forms produce the same truncated-image repair. The replacement also has modes for other corruptions, so do not add those modes casually: -clip changes excessive pixel samples and -changemaxval changes the declared maximum sample value, solving different problems from a file that simply ends early.

4. Verify the result

• Inspect the recovered image metadata.

pamfile --allimages /path/to/recovered-image.pgm

For a two-row source with a two-by-two header but only one complete row, a successful repair reports dimensions of two by one, and should no longer complain the image is too small. Compare the reported dimensions with the number of rows you expected to survive, and open the image with a trusted viewer if visual content matters.

• Check the command status in automation. A zero exit status means the conversion command completed, not that the recovered picture is aesthetically correct.

if pamfix -truncate /path/to/damaged-image.pgm > /path/to/recovered-image.pgm; then
    pamfile --allimages /path/to/recovered-image.pgm
else
    printf '%s\n' 'Image recovery failed' >&2
    exit 1
fi

Keep the original until this verification and any downstream import have succeeded. The repair is a one-way interpretation of the remaining bytes: it cannot recreate rows that were never written, and it cannot tell you whether an interrupted writer, a storage fault or a generator bug caused the short file.

5. Fix a repair that still looks wrong

If pamfixtrunc reports an error, check permissions, available space and whether the input is actually a Netpbm image first. A file can be unreadable because it has an invalid header, not because it is merely truncated. Run pamfile --allimages before trying another repair mode.

If the image contains invalid sample values rather than missing tail data, choose the policy deliberately with pamfix: -clip limits samples to the header's maximum, -changemaxval raises that maximum, and -truncate stops at the first invalid sample when neither of those is selected. Do not overwrite the first recovered copy while comparing these results.

For a script migration, replace:

pamfixtrunc input.pgm > output.pgm

with:

pamfix -truncate input.pgm > output.pgm

Retest the script against a known complete image and a deliberately short copy. Netpbm 10.66 also changed how invalid sample values are treated while reading, so results from much older Netpbm releases are not a reliable compatibility test for current installations.