Convert XBM Bitmaps to PBM with xbmtopbm

You will turn an X11 or X10 bitmap into a PBM image, either from a named file or standard input. The result is written to standard output, so you can save it as a new image and check its dimensions without changing the original bitmap.

Allow about ten minutes. You need a shell, the netpbm package, a readable XBM file, and enough free space for the PBM output. The installed command used for these examples is Netpbm 11.5.2 from package version 2:11.05.02-1.1build1.

This is an ordinary user-level conversion. Do not use sudo unless your input directory or output directory is deliberately restricted. The converter does not need elevated privileges to read a normal bitmap or write in your working directory.

1. Check the installed command

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

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

The version report includes build details after the line shown above. Exact diagnostic text can differ between package builds, so use the exit status and the output file's properties as the useful checks.

2. Convert a bitmap file to PBM

Pass the XBM path as the optional argument and redirect standard output to a new destination:

$ xbmtopbm /path/to/input.xbm > converted.pbm

For a successful conversion, standard output contains the PBM image and the command returns status 0. It normally prints no progress message. Check the status immediately after the conversion:

$ printf 'exit status: %s\n' "$?"
exit status: 0

The shell creates or truncates converted.pbm before xbmtopbm starts. That can destroy an existing image. Choose a new filename, or make a backup before replacing a file you care about. If a failed conversion leaves an incomplete new file, preserve the original and choose another destination for the retry.

3. Verify the PBM header and dimensions

Use file to inspect the result rather than opening binary data in a text editor:

$ file converted.pbm
converted.pbm: Netpbm image data, size = 8 x 2, rawbits, bitmap

The wording can vary, but look for PBM or Netpbm image data and the expected width and height. A PBM file starts with the portable bitmap marker P4 for the binary form produced in this test. You can inspect just the header bytes without dumping the pixel data:

$ od -An -tc -N 8 converted.pbm
   P   4  \n   8       2  \n

This confirms the format and dimensions, not that the picture looks right. Open the result with an image viewer or pass it to a later Netpbm conversion when visual correctness matters. Keep the original XBM until that check is complete.

4. Use standard input in a pipeline

The bitmap filename is optional. Omitting it makes xbmtopbm read the XBM from standard input, which is useful when another command produces the bitmap:

$ printf '%s\n' \
    '#define icon_width 8' \
    '#define icon_height 2' \
    'static unsigned char icon_bits[] = {' \
    '  0x81, 0x42' \
    '};' \
  | xbmtopbm > sample.pbm
$ file sample.pbm
sample.pbm: Netpbm image data, size = 8 x 2, rawbits, bitmap

The input contains the width and height declarations required by the XBM format, followed by the bitmap bytes. The example creates sample.pbm in the current directory, so use a scratch directory or a fresh filename if you are testing. To undo this particular test, remove only the generated output after checking that it is not needed:

$ rm -- sample.pbm

5. Keep the option set simple

The xbmtopbm manpage defines no options specific to this converter. Its synopsis is just xbmtopbm [bitmapfile]. In practice, the important choices are the optional input filename and where you redirect the PBM output.

It does recognise options common to Netpbm programs through libnetpbm, but those are not conversion controls documented specifically for xbmtopbm. Do not invent a width, height or resize option for this command. The dimensions come from the XBM input; resize or re-encode the PBM with a separate image tool if that is the actual requirement.

Remember that a successful exit status means the command completed its conversion. It does not guarantee that the input was the bitmap you intended, that the dimensions are sensible for your application, or that a viewer will display the result as expected.

6. Diagnose the common failures

If the input path is wrong or unreadable, the command exits non-zero and reports that it could not open the file. Check the path and permissions without changing anything:

$ ls -l /path/to/input.xbm
$ xbmtopbm /path/to/input.xbm > converted.pbm
$ printf 'exit status: %s\n' "$?"

If the command reports an end-of-file or parsing error, inspect the XBM text. It should contain matching width and height definitions and a byte array. A file with a plausible name is not necessarily a valid XBM, and xbmtopbm does not infer missing dimensions from the filename.

If file reports dimensions you did not expect, stop before passing the PBM to another tool. Re-check the source XBM and repeat the conversion into a different output filename. Do not overwrite the only copy while investigating.