Convert PNM Images into X11 Window Dumps with pnmtoxwd

You will convert a PBM, PGM or PPM image into an X11 window dump that an X11 viewer such as xwud can display. You will also check the result without opening it and choose between the command's automatic format, a fixed PseudoColor depth and DirectColor. Allow about ten minutes if the input file already exists.

This guide uses Netpbm 11.5.2, installed here as Debian package version 2:11.05.02-1.1build1. The local manual page is dated 24 September 1991, so the examples describe the installed command and its documented interface. The conversion itself normally needs no elevated privileges. You need a readable PNM file, a writable output directory and an X11 display only if you intend to view the dump.

1. Check the installed command

Confirm that the shell will run the Netpbm program you expect:

$ command -v pnmtoxwd
/usr/bin/pnmtoxwd
$ pnmtoxwd --version
pnmtoxwd: Using libnetpbm from Netpbm Version: Netpbm 11.5.2

The version output contains build details as well as the useful library version. pnmtoxwd --help does not print a full option summary on this build; it directs you to the manual page. Do not treat that short response as evidence that an option is unavailable.

2. Convert an existing PNM file

The command reads the optional input file and writes the X11 window dump to standard output. Redirect that output to a new filename:

$ pnmtoxwd /path/to/input.ppm > /path/to/output.xwd

Replace both placeholders with real paths. PBM, PGM and PPM are the relevant PNM forms: monochrome and greyscale input normally produce a StaticGray dump, while PPM input uses PseudoColor when it has no more than 256 colours and DirectColor when it has more. The generated X11 dump uses big-endian integers.

A PPM conversion can write a normal diagnostic to standard error while it builds the colour map. For example, this is expected for a small two-colour input:

pnmtoxwd: computing colormap...

The diagnostic is progress information, not a failure report. The shell prompt returning and a non-empty output file are the first useful checks.

3. Verify the dump before displaying it

Inspect the output as a file, rather than opening an untrusted or incomplete dump immediately:

$ test -s /path/to/output.xwd && echo 'non-empty output'
non-empty output
$ file /path/to/output.xwd
/path/to/output.xwd: X-Window screen dump image data, version X11, "/path/to/input.ppm", 2x1x8, order 1, 256 colors 2 entries

The exact file wording varies with the installed file database. Check for an X-Window screen dump, the expected dimensions and a sensible colour entry count. A successful exit status only proves that the converter completed; it does not prove that the source image had the dimensions or colours you intended.

If the result is empty or file identifies it as generic data, check the input without changing it:

$ file /path/to/input.ppm
$ test -r /path/to/input.ppm && echo 'input is readable'

Malformed PNM headers, an unreadable input path or a full destination filesystem are more likely causes than a need for sudo. Elevated privileges do not repair image data.

4. Use a fixed PseudoColor depth when required

Some older viewers or test fixtures expect a particular PseudoColor depth. Set it with -pseudodepth and a value from 1 through 16:

$ pnmtoxwd -pseudodepth 4 /path/to/input.ppm > /path/to/output-depth4.xwd
$ file /path/to/output-depth4.xwd
/path/to/output-depth4.xwd: X-Window screen dump image data, version X11

The documented default is depth 8, allowing up to 256 colours. This option controls the depth of a PseudoColor dump; it is not a general resize operation and it does not turn a greyscale input into a colour image. Use a value supported by the program, not a display depth copied from an unrelated X server.

If your workflow does not require a legacy depth, leave the option out and keep the automatic choice. A smaller depth can reduce the available palette and may change how an image is represented.

5. Request DirectColor explicitly

Pass -directcolor when the consumer specifically requires an X11 DirectColor dump:

$ pnmtoxwd -directcolor /path/to/input.ppm > /path/to/output-directcolor.xwd
$ file /path/to/output-directcolor.xwd
/path/to/output-directcolor.xwd: X-Window screen dump image data, version X11

This is a format selection, not a display configuration change. It does not configure the X server, open a window or alter the source image. If a downstream program accepts the automatic PPM result, use the simpler command from step 2. Add this switch only for a known compatibility requirement.

6. Display or round-trip the result

When an X11 display and xwud are available, pass the dump to that viewer:

$ xwud -in /path/to/output.xwd

The manual lists xwud as the display program, but it is a separate tool and may not be installed. An alternative verification path is xwdtopnm, which converts the dump back to a PNM image:

$ xwdtopnm /path/to/output.xwd > /path/to/roundtrip.pnm
$ file /path/to/roundtrip.pnm
/path/to/roundtrip.pnm: Netpbm image data

Round-tripping can change the exact PNM encoding and sample depth. It is useful for checking that another Netpbm tool can read the dump, not for proving byte-for-byte preservation. If the command reports that no X display is available, use file or xwdtopnm instead; do not run an X viewer as root to bypass a display-permission problem.

7. Avoid overwriting a useful dump

Shell redirection with > truncates its destination before pnmtoxwd starts. Use a new name while testing:

$ pnmtoxwd /path/to/input.ppm > /path/to/output.xwd.new
$ test -s /path/to/output.xwd.new
$ file /path/to/output.xwd.new
$ mv /path/to/output.xwd.new /path/to/output.xwd

The final mv replaces the old dump only after the new command has returned successfully and the checks have passed. If conversion fails, leave the old output in place and remove the incomplete .new file deliberately after inspecting the error. Do not delete the original PNM until the dump has been viewed or round-tripped successfully. There is no undo for an accidental overwrite unless you have a backup or can regenerate the dump from the source.