Convert PBM Images to MacPaint Files with pbmtomacp

You will convert a PBM image into a MacPaint data fork, check that the result is the expected binary file, and understand when it needs another wrapper before macOS can identify it as a PNTG file. The examples use the pbmtomacp installed by Netpbm 11.05.02-1.1build1 on this machine.

Allow about ten minutes. You need a shell, a readable PBM file, and permission to create the output in your working directory. The conversion itself is an ordinary unprivileged command. It does not alter the input, and it does not need sudo.

1. Check the installed command

Confirm the executable and package version before relying on a result. This matters because the local manual is dated 26 April 2015, while the installed package is newer:

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

The command reads PBM from a named file or from standard input when no file name is supplied. It writes the MacPaint data to standard output, so redirect that output to a new destination. Keep the input and output names visibly different while testing.

Checkpoint: if command -v prints nothing, stop and install Netpbm through your normal package-management process. Do not create a replacement script with the same name in a directory earlier in PATH.

2. Convert a PBM file

Replace the two path placeholders with real files. The input is read-only; the redirection creates or truncates the output file:

$ pbmtomacp /path/to/input.pbm > /path/to/output.pntg
$ printf 'exit status: %s\n' "$?"
exit status: 0

A status of 0 means the program completed its conversion. It does not prove that the image is visually the one you intended, so inspect the output before deleting the PBM source.

Redirection with > truncates an existing destination before pbmtomacp starts. That is the main destructive trap in this workflow. If the destination already matters, choose a fresh name or make a backup first:

$ cp --preserve=all /path/to/output.pntg /path/to/output.pntg.bak
$ pbmtomacp /path/to/input.pbm > /path/to/output.pntg.new
$ mv /path/to/output.pntg.new /path/to/output.pntg

The last command changes the old destination only after a new conversion has completed. If conversion fails, remove the incomplete output.pntg.new and restore the backup with mv if necessary. Do not run a blind rm against the backup until the replacement has been checked.

3. Verify the result as binary output

Check that the file exists and is not empty:

$ file /path/to/output.pntg
/path/to/output.pntg: data
$ test -s /path/to/output.pntg && echo 'output is non-empty'
output is non-empty

The exact wording from file can vary. The useful facts are that the destination exists, has a non-zero size, and was produced by a successful command. Do not expect file to identify every MacPaint data fork as a self-describing image: the manual says this output contains only the data fork.

For a deterministic format check, run the same conversion with -norle into a separate test file:

$ pbmtomacp -norle /path/to/input.pbm > /tmp/pbmtomacp-norle.pntg
$ stat -c '%s bytes' /tmp/pbmtomacp-norle.pntg
53072 bytes

-norle disables run-length encoding. The manual documents exactly 53072 bytes for this mode, the theoretical maximum size for a MacPaint image. It is useful for testing and experimentation, not for keeping files small. Normal output uses compression and therefore has a size that depends on the image.

4. Crop an image that is too large

MacPaint has a fixed canvas. By default, pbmtomacp converts the whole PBM, but if the image is too large it cuts it to fit from the specified top-left corner. The four options select the rectangle:

$ pbmtomacp -left 0 -top 0 -right 576 -bottom 720 \
    /path/to/large.pbm > /path/to/large-crop.pntg

Use the dimensions appropriate to your image and desired crop. The option names are -left, -right, -top and -bottom; the installed manual also permits the equivalent double-hyphen spelling. Do not guess a rectangle from the output file size. Open the PBM or inspect it with another Netpbm tool first.

These crop switches remain for backward compatibility. The manual recommends pamcut for the more flexible Netpbm workflow. Crop to a separate PBM, inspect that intermediate image, then convert it:

$ pamcut -left 0 -top 0 -right 576 -bottom 720 \
    /path/to/large.pbm > /tmp/large-crop.pbm
$ pbmtomacp /tmp/large-crop.pbm > /path/to/large-crop.pntg

This example assumes the installed pamcut accepts the same rectangle values for your image. If it reports an invalid boundary, correct the crop command rather than asking pbmtomacp to silently discard content.

5. Supply standard input when that fits the pipeline

With no PBM file argument, the command consumes standard input. This lets you connect another Netpbm producer without creating an intermediate PBM:

$ pbmmake -black 576 720 | pbmtomacp > /path/to/black.pntg
$ test -s /path/to/black.pntg && echo 'pipeline output is non-empty'
pipeline output is non-empty

Use this form only when the preceding command really emits PBM. If pbmtomacp reports that the first byte is not a Netpbm magic number, check the producer, the pipe, and the input path. An empty file, a text error message, or a different image format is not valid PBM input.

6. Package the data fork only when required

The output from pbmtomacp is not a complete MacBinary or BinHex file. The manual says that a program such as mcvert is needed to add the information that identifies the file as PNTG to classic Mac OS. Do not rename the data fork and assume that renaming supplies that metadata.

If a receiving workflow explicitly requires MacBinary or BinHex, check that mcvert is installed and follow that tool's own documentation. If the consumer accepts the raw MacPaint data fork, keep the output from pbmtomacp as it is. This is a format boundary, not a conversion error.

7. Diagnose the common failures

• An error about the first byte usually means the input is empty or is not PBM. Check it with file /path/to/input.pbm and keep the original unchanged.
• A failure to open the input points to the path or read permission. Fix the path first. Use elevated privileges only when the input directory genuinely requires them, and write the output somewhere your normal account can review.
• A surprisingly large normal output may be valid. Run a separate -norle test to distinguish the fixed test size from normal compressed output.
• A visually wrong result can still have status 0. Check PBM dimensions and crop boundaries; successful encoding is not an image review.

There is no persistent state to undo in these examples. To recover from a bad output, delete only the known output file or restore the backup, while retaining the original PBM until the MacPaint file has been accepted by its target software.