Convert a PBM Bitmap to MRF Without Losing the Original

You will finish with an MRF file made from a monochrome PBM image, plus a quick check that its format, dimensions and conversion status are sensible. The examples use the Netpbm package installed here, version 2:11.05.02-1.1build1.

Allow about ten minutes. You need a shell, a readable PBM file, and enough space for a temporary output file. This workflow is unprivileged: do not use sudo unless your input or destination directory genuinely requires access you do not have.

1. Check the installed command

Confirm which executable will run and record the package version. Both checks are read-only:

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

The command has one positional argument, the input PBM file. If you leave it out, it reads PBM data from standard input. It always writes the MRF result to standard output. There are no pbmtomrf-specific options; it accepts the common options provided by libnetpbm.

2. Confirm that the input is really PBM

Inspect the file before converting it. The file command does not modify it:

$ file /path/to/input.pbm
/path/to/input.pbm: Netpbm image data, size = 128 x 64, rawbits, bitmap

Replace the path with your own file. PBM is a bilevel format: each pixel is black or white. It is not a greyscale PGM or a colour PPM, and changing the filename suffix does not change the file format. If file reports another Netpbm format, convert it to PBM first with an appropriate Netpbm tool.

For a harmless test file, make a 128 by 64 dithered bitmap in a temporary directory:

$ workdir=$(mktemp -d /tmp/pbmtomrf-check.XXXXXX)
$ pbmmake -gray 128 64 > "$workdir/input.pbm"
$ file "$workdir/input.pbm"
/tmp/pbmtomrf-check.XXXXXX/input.pbm: Netpbm image data, size = 128 x 64, rawbits, bitmap

The random-looking directory suffix in the output varies. Keep the value of workdir in the current shell; the later commands use it.

3. Convert into a new file

Redirect standard output to a new destination. The converter itself does not alter the PBM input:

$ pbmtomrf "$workdir/input.pbm" > "$workdir/output.mrf"
$ printf 'exit status: %s\n' "$?"
exit status: 0
$ test -s "$workdir/output.mrf" && echo 'MRF output is non-empty'
MRF output is non-empty

A zero status means the conversion completed. It does not, by itself, prove that you chose the intended input or that a later MRF reader will accept the file, so keep the verification steps below.

$ cp --preserve=all /path/to/result.mrf /path/to/result.mrf.backup
$ pbmtomrf /path/to/input.pbm > /path/to/result.mrf.new
$ mv /path/to/result.mrf.new /path/to/result.mrf

The final mv replaces the old result only after conversion has succeeded. If conversion fails, inspect the error, remove the incomplete .new file when you are ready, and retain the original or restore it with mv /path/to/result.mrf.backup /path/to/result.mrf. Removing the backup is irreversible, so do not automate that cleanup until the replacement has been checked.

4. Verify the MRF header

MRF files begin with the ASCII magic number MRF1, followed by a big-endian 32-bit width, a big-endian 32-bit height, and a reserved zero byte. Inspect those first 13 bytes without trying to edit the file:

$ od -An -tx1 -N 16 "$workdir/output.mrf"
 4d 52 46 31 00 00 00 80 00 00 00 40 00 ...

Here, 4d 52 46 31 is MRF1, 00 00 00 80 is 128, and 00 00 00 40 is 64. The final byte shown before the compressed data is the reserved zero. Your compressed bytes will differ for another image, so compare the magic number and dimensions rather than the entire line.

5. Test a round trip when correctness matters

Use mrftopbm to decode a copy of the MRF back to PBM. This is a verification step and does not change the MRF:

$ mrftopbm "$workdir/output.mrf" > "$workdir/roundtrip.pbm"
$ file "$workdir/roundtrip.pbm"
/tmp/pbmtomrf-check.XXXXXX/roundtrip.pbm: Netpbm image data, size = 128 x 64, rawbits, bitmap

For an exact pixel comparison, normalise both files through a PBM reader instead of comparing their bytes. PBM headers, comments and plain versus raw encoding may legitimately differ. For example, if pnmfile is installed, compare the reported dimensions and inspect the round-tripped image with a trusted viewer or a later image conversion.

MRF is monochrome only. It cannot retain colour or greyscale information, and its compressed data has no end-of-file marker beyond the end of the file itself. The format works on a grid of 64 by 64 squares. Images whose width or height is not a multiple of 64 can therefore have less-than-optimal edge compression; that is an efficiency limitation, not a reason to pad the visible image without checking what the consumer expects.

6. Handle failures without guessing

If the command says the magic number is invalid, the input is not a readable PBM in the form this Netpbm build expects. Check the path and file type first:

$ test -r /path/to/input.pbm && echo readable
readable
$ file /path/to/input.pbm

A missing or unreadable file is a path or permission problem. A PGM, PPM or arbitrary binary is a format problem. Do not solve either by running the converter as root. If the input is supplied by a pipeline, remember that an upstream failure can leave no useful PBM for pbmtomrf to process:

$ pbmmake -white 128 64 | pbmtomrf > "$workdir/piped.mrf"
$ test -s "$workdir/piped.mrf" && echo 'pipeline produced MRF'
pipeline produced MRF

Keep the pipeline's stages simple while diagnosing it. Once the input and output have been checked, pass the MRF file to the program or device that requires it. pbmtomrf does not display the bitmap, install an MRF consumer, or make persistent system changes.