Convert an X Window Dump into a Usable PNM Image

You will turn an X11 or X10 window dump into a PBM, PGM or PPM image, then check the result before handing it to another image tool. The examples use xwdtopnm from Netpbm package version 2:11.05.02-1.1build1.

Allow about ten minutes if you already have an XWD file. You need a shell, a readable dump file and enough free space for an uncompressed PNM image. No elevated privileges are normally required.

1. Check the installed converter

Confirm which executable your shell will run and record the package version:

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

Your package revision may differ. This matters when you compare output with another machine. The local manual page documents the command as accepting one optional input filename. With no filename, it reads the XWD data from standard input.

2. Capture or locate an XWD file

xwdtopnm does not capture a window itself. It consumes an X10 or X11 window dump produced by a capture tool such as xwd. If you already have a file, set a shell variable to its actual path:

$ input=/path/to/window.xwd
$ test -r "$input" && printf 'Readable: %s\n' "$input"
Readable: /path/to/window.xwd

Replace the placeholder path before running the command. A file that exists but is not an XWD dump will fail during header parsing; renaming a different image to .xwd does not convert it.

If you are capturing a window interactively, keep the dump as a separate source file. That gives you something to retry when an output choice or downstream conversion goes wrong.

3. Convert the dump without overwriting an image

The converter writes the image to standard output. Redirect it to a new destination, and use set -o noclobber if you want the shell to refuse an existing regular file:

$ output=/path/to/window.pnm
$ set -o noclobber
$ xwdtopnm "$input" > "$output"
$ set +o noclobber

set -o noclobber changes the current shell only. The redirection still creates a new file when the destination does not exist. If the destination already exists, the shell stops before xwdtopnm runs. This is a useful guard because plain > truncates an existing destination before starting the command.

Do not treat a newly created file as proof of success. A converter can create the destination and then report an input error. Check both the command status and the file:

$ test -s "$output" && file "$output"
window.pnm: Netpbm image data, ...

The exact file wording depends on the installed file utility and image type. The useful result is a non-empty Netpbm image, not a particular line of text.

4. Identify the output type

The output format follows the input display data. A black-and-white dump becomes PBM, a greyscale dump becomes PGM, and other input becomes PPM. xwdtopnm reports which type it is writing, but the reliable file-level check is the PNM magic number at the start of the output:

$ head -c 2 "$output"; printf '\n'
P6

P1 or P4 identifies PBM, P2 or P5 identifies PGM, and P3 or P6 identifies PPM. The first form in each pair is plain text and the second is raw binary. Do not use a text editor to inspect the whole file when the magic number is P4, P5 or P6.

If you want the converter's diagnostic information, run it with -verbose and keep standard output separate from standard error when you need the image stream to remain clean:

$ xwdtopnm -verbose "$input" > "$output" 2> xwdtopnm.log
$ sed -n '1,20p' xwdtopnm.log

The verbose output is for inspection. It is not part of the image and must not be mixed into the redirected PNM stream.

5. Handle high-value samples before older tools

Some pseudocolour XWD files produce a PNM maxval greater than 255. That means each sample uses two bytes rather than one. The manual warns that older programs may not understand this representation, even though it is valid Netpbm output.

Inspect the PNM header if a downstream program shows broken colours or refuses the file. The maxval is the number after the width and height in a plain header, although comments and whitespace can appear there. For a Netpbm-aware next step, reduce the sample depth with pamdepth:

$ pamdepth 255 "$output" > /path/to/window-8bit.pnm
$ test -s /path/to/window-8bit.pnm && file /path/to/window-8bit.pnm

This creates a second image and leaves the original available for comparison. Do not replace the source output until you have checked the new file. If the receiving program expects a different byte order instead, the manual identifies pamendian as the relevant Netpbm tool:

$ pamendian < "$output" > /path/to/window-native-endian.pnm

Use only the form required by the receiving application. These commands change the representation of a copy, not the XWD file.

6. Diagnose the common failures

• "couldn't read XWD file header": check that the path points to an actual X10 or X11 window dump and that it is readable. The installed command returns a non-zero status for an invalid header.
• More than 24 bits per pixel: the manual documents this as unsupported. Capture the window again at a supported display configuration or use another capture/conversion route; do not expect a flag to bypass the limit.
• The output is empty or truncated: check the exit status immediately, then remove only the failed destination if it is disposable and rerun with a new name. Never delete the original XWD while diagnosing.
• Colours look wrong in an old viewer: inspect the maxval and try pamdepth or, where appropriate, pamendian. The problem may be sample representation rather than a bad capture.

If you used a temporary log, it is safe to remove that log after reviewing it. The input XWD and successfully converted PNM are the files worth preserving.