Remove Page Shadows from Scanned PGM Images with pgmdeshadow

pgmdeshadow flattens the smooth grey shadow a scanner leaves down a book's binding. It reads a scanned PGM and writes a checked, separate output, which suits pages with a darker band near the spine or along an outer edge.

Allow about ten minutes for one image. You need the Netpbm package, a readable PGM file, and enough free space for another copy of the image. The examples use Netpbm 11.5.2, provided here by Debian package netpbm version 2:11.05.02-1.1build1. Your release may behave differently in details this guide does not cover, so check its local manual page with man 1 pgmdeshadow.

1. Check the input and installed version

Confirm the executable is available and the source is readable. None of these commands change the image:

$ command -v pgmdeshadow
/usr/bin/pgmdeshadow
$ pgmdeshadow --version
pgmdeshadow: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
...
$ file /path/to/page.pgm
/path/to/page.pgm: Netpbm image data, size 2480 x 3508, rawbits, greymap

The version probe prints build information and exits; ask the installed program for help and it just points you at its manual page instead. file should identify a Netpbm greymap. Quote the path in every command if it contains spaces.

2. Preserve the original before processing

pgmdeshadow reads a PGM image and writes the processed result to standard output. Keep the source where it is and pick a new destination: never redirect straight back onto the input path, because the shell truncates that file before the program has read a single byte of it.

$ cp --preserve=all /path/to/page.pgm /path/to/page.pgm.bak
$ pgmdeshadow /path/to/page.pgm > /path/to/page-deshadowed.pgm

The extra copy is a precaution, not something the command requires. The conversion itself needs no elevated privileges as long as both files sit in a directory you can write to. Do not reach for sudo just because a path is unclear.

$ test -s /path/to/page-deshadowed.pgm && echo 'output is non-empty'
output is non-empty
$ file /path/to/page-deshadowed.pgm
/path/to/page-deshadowed.pgm: Netpbm image data, size 2480 x 3508, rawbits, greymap

3. Use standard input when that fits a pipeline

The input filename is optional. Leave it out and the program reads a PGM stream from standard input, handy when another tool already produces one:

$ cat /path/to/page.pgm | pgmdeshadow > /path/to/page-deshadowed.pgm

For a plain file, naming it directly is easier to review and gives clearer errors. Either way the source is left alone. Hold off on chaining in extra filters until the direct conversion has been checked; a pipeline hides which stage failed unless you set up shell pipeline error handling.

4. Understand what the filter actually corrects

The program targets grey shadows that fade smoothly in from an outside edge, the kind you get beside a book crease. It estimates a local shadow level and corrects each pixel against it. It is not a general image editor: it will not touch arbitrary marks, text bleed, stains or sharply defined objects.

There are no pgmdeshadow-specific command-line options, only the common libnetpbm ones the manual mentions in passing, so this guide will not invent width or height switches that do not exist. The input image itself supplies the dimensions, and the test above kept 2480 by 3508 pixels intact.

PGM is a greyscale format. A PNG, JPEG or colour PPM scan needs converting to greyscale PGM with a suitable Netpbm or image tool first. Keep that conversion as its own step so each file format gets verified on its own.

5. Verify the result before replacing anything

A clean exit status only proves the command ran, not that the page looks right. Check format and dimensions, then look at the result or hand it to a trusted converter:

$ file /path/to/page-deshadowed.pgm
/path/to/page-deshadowed.pgm: Netpbm image data, size 2480 x 3508, rawbits, greymap
$ cmp --silent /path/to/page.pgm /path/to/page-deshadowed.pgm
$ printf '%s\n' "$?"
1

A cmp status of 1 is expected for an image that actually changed; it is not a quality score. A 0 means the two files are byte-for-byte identical and the shadow correction did nothing to this input. To eyeball the page after converting it to something a viewer likes, use a separate installed command such as pnmtopng if you have it:

$ pnmtopng /path/to/page-deshadowed.pgm > /path/to/page-deshadowed.png
$ file /path/to/page-deshadowed.png
/path/to/page-deshadowed.png: PNG image data, 2480 x 3508, 8-bit grayscale, non-interlaced

6. Handle failures without losing the source

If the command cannot open the input, check its path and permissions without changing either:

$ ls -l /path/to/page.pgm
$ test -r /path/to/page.pgm && echo readable

A missing or zero-size output means stop and keep the original. A failed redirection can leave a half-written destination behind, so quarantine or remove only that newly named file after checking its path; never delete the source or its backup as part of recovery.