Convert PPM Images to Berkeley YUV with ppmtoeyuv

ppmtoeyuv turns a PPM image into raw Berkeley Encoder YUV, the format an old video pipeline expects instead of a normal picture file. This walks you through the conversion, a sanity check on the binary output, and a round trip back to PPM to prove nothing got mangled. The installed command is Netpbm 11.5.2, built from source dated 2024-03-31. Allow about ten minutes if your PPM file is ready.

You need ppmtoeyuv and, for the round-trip check, eyuvtoppm, both from the Netpbm package. The examples write new files in the current directory, need no sudo, and touch nothing else on the system.

1. Confirm the installed command

Check which executable the shell will run and record the package version. These are ordinary read-only commands:

$ command -v ppmtoeyuv
/usr/bin/ppmtoeyuv
$ ppmtoeyuv -version
ppmtoeyuv: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
...
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1

The version diagnostic contains more build details than the example shows. If the command is missing, install the Netpbm package using your distribution's normal package-management process. Do not substitute a similarly named YUV converter until you have checked its format.

Checkpoint: You should have /usr/bin/ppmtoeyuv or another deliberate path, and the command should report Netpbm 11.5.2 on this system.

2. Check the input PPM

ppmtoeyuv accepts one optional PPM filename. With no filename it reads standard input. Make sure the input is a PPM image before starting; a PGM or PNG file is not interchangeable just because it contains pixels:

$ file input.ppm
input.ppm: Netpbm image data, PPM, binary, 2 x 2

The exact file output depends on the image and the utility version. A simple PPM header should contain the magic number P3 or P6, followed by its dimensions and maximum sample value. If you need to create a harmless test image, this produces a tiny binary PPM without replacing an existing file:

$ printf 'P6\n2 2\n255\n\377\000\000\000\377\000\000\000\377\377\377\377' > sample.ppm
$ file sample.ppm
sample.ppm: Netpbm image data, PPM, binary, 2 x 2

Do not redirect this command to a path containing an input image you still need. Redirection truncates its destination before the program runs. If an output file already matters, choose a new name and compare it before any later replacement.

3. Convert the image to Berkeley YUV

Run the converter with the input filename and redirect standard output to a new file:

$ ppmtoeyuv input.ppm > output.eyuv
$ printf 'exit status: %s\n' "$?"
exit status: 0
$ file output.eyuv
output.eyuv: data

A successful run normally prints no image data or progress text to the terminal because the converted file is standard output. Keep that output separate from diagnostics. The program has no options specific to its conversion; it accepts the common libnetpbm options, including -quiet. For example, this is equivalent when you want to suppress common informational output:

$ ppmtoeyuv -quiet input.ppm > output-quiet.eyuv
$ cmp --silent output.eyuv output-quiet.eyuv
$ printf 'identical output: %s\n' "$?"
identical output: 0

Do not interpret output.eyuv as an ordinary text file. Commands such as cat may fill the terminal with control characters. Use file, wc -c, or a format-aware reader instead.

4. Verify the byte count

For a 2x2 test image, the installed converter produced six bytes. The format is binary, so the precise byte count is a useful first check but not a complete validation:

$ wc -c < output.eyuv
6

Your count will depend on the image dimensions and the Berkeley YUV representation. A zero-byte file, a shell error, or a non-zero status means the conversion did not produce a usable result. Common causes include an empty input, a truncated PPM header, a wrong input format, or a destination that the shell could not create.

When a command fails, inspect the diagnostic on standard error and rerun it with a different destination. Do not immediately retry over the original input. An empty input is rejected with an error such as Error reading first byte of what is expected to be a Netpbm magic number.

Checkpoint: The converter returned status 0, the destination is non-empty, and its byte count is stable when you run the same command again with a fresh output path.

5. Round-trip the result

The companion eyuvtoppm command needs the image dimensions as options. Both width and height must be even. Use the dimensions from the source PPM, then write the reconstructed PPM to another new file:

$ eyuvtoppm --width 2 --height 2 output.eyuv > round-trip.ppm
eyuvtoppm: Converting Frame 0
$ file round-trip.ppm
round-trip.ppm: Netpbm image data, PPM, binary, 2 x 2
$ head -3 round-trip.ppm
P6
2 2
255

The converter's frame message is a diagnostic, not part of the PPM output because it is sent to standard error. The decoded pixels can differ slightly from the source because converting through YUV can involve colour-space rounding. Check the header, dimensions and successful exit status first; use an image comparison tool if exact pixel differences matter.

If eyuvtoppm reports a size error, check that you supplied the original even dimensions. Berkeley YUV is not the same format as Abekas YUV. The related ppmtoyuv command creates Abekas YUV, so it is not a drop-in replacement for this workflow.

6. Convert a stream or several images

To use a pipeline, leave out the filename. The following sends one PPM from standard input and stores the same kind of binary output:

$ ppmtool-that-produces-ppm | ppmtoeyuv > pipeline.eyuv
$ test -s pipeline.eyuv && printf '%s\n' 'pipeline output is non-empty'
pipeline output is non-empty

Replace ppmtool-that-produces-ppm with a real command that writes PPM to standard output. The placeholder is deliberately not executable. Avoid mixing log text into the producer's standard output, or the PPM stream will be corrupted before ppmtoeyuv reads it.

The program also handles a multi-image PPM input stream and writes consecutive Berkeley YUV images. This is useful for a controlled pipeline, but it makes a single output file contain multiple frames. Keep the frame count and dimensions with your processing notes so that a later reader knows how to split or decode it.

Done means