Convert a 12-Row PPM to an Apple Volume Label

Building a bootable Apple volume needs a very specific label image, and ppmtoapplevol makes it from a PPM. The command writes to standard output, so the result should go to a named file or another program, never straight to your terminal.

Allow about fifteen minutes. You need Netpbm, a PPM image, and a shell. This guide uses Netpbm 11.5.2 from the installed Ubuntu package netpbm 2:11.05.02-1.1build1; the command was added in Netpbm 10.54, so older installs may not have it at all.

1. Check the installed command

Start with read-only checks; nothing here needs elevated privileges:

$ command -v ppmtoapplevol
/usr/bin/ppmtoapplevol
$ ppmtoapplevol -version
ppmtoapplevol: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
ppmtoapplevol: Built from source dated 2024-03-31 09:09:47
ppmtoapplevol: Built by Debian

Exact build details can differ, the line that matters is the Netpbm library version. -version is a common Netpbm option rather than something unique to this program, and there are no command-line options specific to ppmtoapplevol at all.

2. Check the PPM dimensions

The input has to be exactly 12 rows tall and no more than 255 columns wide, not 11 rows, not 13, and 256 columns is already too wide. Inspect the file before converting:

$ pamfile volume-label.ppm
volume-label.ppm: PPM raw, 160 by 12  maxval 255

Your format description might say PPM plain instead of PPM raw, both are valid PPM input. It is the dimensions that matter here, a file that looks like a narrow banner can still fail on row count alone.

If pamfile reports more than 255 columns, reduce the width. If it reports the wrong height, make it 12 rows. The manpage points to pamscale and pamcut for this, but which one is right depends on whether you need to preserve the whole image or you are happy to crop it.

This scales an input to exactly 12 rows while keeping its aspect ratio; the resulting width is whatever pamscale calculates, so check it afterwards:

$ pamscale -ysize 12 source.ppm > scaled.ppm
$ pamfile scaled.ppm
scaled.ppm: PPM raw, 213 by 12  maxval 255

Scaling can make text or small detail harder to read, and it might push the width past 255. If so, pick a smaller width or crop deliberately. The redirect above creates a separate file, so the original stays safe while you experiment.

3. Convert the image to a named output file

Pass the PPM path as the optional argument and redirect standard output to a new file:

$ ppmtoapplevol scaled.ppm > volume-label.applevol
$ printf 'exit status: %s\n' "$?"
exit status: 0
$ wc -c volume-label.applevol
536 volume-label.applevol

The byte count depends on the source width. This is not a text file, do not open it in a terminal or edit it in a text editor. A successful exit status means the conversion completed, not that the label suits a particular Apple boot screen visually.

For a valid input, the output begins with a small binary header followed by image data. On a 4 by 12 test image, this installed program produced 54 bytes including the header, treat that as an observed detail rather than a documented file-format contract; let the Apple consumer interpret the result.

To keep informational Netpbm messages off standard error in scripts, add the common -quiet option:

$ ppmtoapplevol -quiet scaled.ppm > volume-label.applevol
$ test -s volume-label.applevol
$ printf 'non-empty output: %s\n' "$?"
non-empty output: 0

-quiet does not make an invalid image valid, and it does not turn the binary output into text. Keep the redirect in place regardless.

4. Use standard input in a pipeline

The optional filename can be dropped entirely. In that form, the command reads PPM from standard input, handy when another Netpbm command is preparing it:

$ pamscale -ysize 12 source.ppm | ppmtoapplevol -quiet > volume-label.applevol
$ test -s volume-label.applevol
$ printf 'pipeline output is present: %s\n' "$?"
pipeline output is present: 0

There is a practical trap here: pamscale -ysize 12 controls the height but not the maximum width. Inspect the intermediate result whenever source dimensions are uncertain, or give pamscale a width constraint too and verify the final dimensions from a saved intermediate.

For a script, use a temporary file so you can check dimensions before committing to a result:

$ tmp_ppm=$(mktemp --suffix=.ppm)
$ trap 'rm -f "$tmp_ppm"' EXIT
$ pamscale -ysize 12 source.ppm > "$tmp_ppm"
$ pamfile "$tmp_ppm"
$ ppmtoapplevol -quiet "$tmp_ppm" > volume-label.applevol

This removes only the temporary intermediate when the shell exits; the output file remains. Keep a copy of the intermediate somewhere intentional first if you need it for diagnosis later.

5. Diagnose a rejected image

A wrong height or width is an ordinary input error. The converter exits non-zero and names the dimension it measured:

$ ppmtoapplevol image-11-rows.ppm > volume-label.applevol
ppmtoapplevol: Input image must be 12 rows tall.  Yours is 11
$ printf 'exit status: %s\n' "$?"
exit status: 1

Because shell redirection opens the destination before the program runs, do not point a valuable existing output path at a test you expect to fail. Prefer a new path, or write to a temporary file and move it into place only after a zero exit status; a failed run can leave an empty or partial destination depending on where it failed.

An oversized image gives a similar diagnostic:

$ ppmtoapplevol image-256-columns.ppm > /tmp/volume-label.applevol
ppmtoapplevol: Input image must not be more than 255 columns wide.  Yours is 256
$ printf 'exit status: %s\n' "$?"
exit status: 1

Use pamcut to crop a known region when that is the intended result, or pamscale to shrink the whole image. Neither needs sudo. If a file is owned by another account, fix the input or output permissions through your normal change process instead of granting the converter privileges it does not need.

6. Keep the format boundary clear

ppmtoapplevol converts in one direction only: PPM in, Apple volume label image out. Netpbm provides no reverse converter, so keep the original PPM if you might need to revise the label later, the generated file is not a convenient editable source.

The command does not mount a volume, change firmware settings, write to an EFI system partition, or install a label. Those are separate, system-specific steps. This guide stops at producing the output file; before copying it into a boot-related location, confirm the destination, keep a backup, and follow the documentation for the Apple system that will consume it.

Nothing shown here needs elevated privilege. Only a later copy into a protected system location might, and that is deliberately outside the scope of these examples.