Convert Berkeley EYUV Frames to PPM with eyuvtoppm

You will convert a Berkeley Encoder YUV file to a PPM image stream, save it safely, and verify the result. Allow about fifteen minutes if you already know the frame dimensions. You need the netpbm package, a readable EYUV input file, and enough disk space for the output.

This guide describes the installed Netpbm 11.5.2 command on this machine. The manual page is dated 22 April 2001, so its documented interface is the reliable reference here. Berkeley YUV is not the same format as Abekas YUV. Do not select this tool just because a file happens to contain the letters YUV.

1. Check the installed command

Confirm the executable and package version. Both checks are ordinary and do not need elevated privileges:

$ command -v eyuvtoppm
/usr/bin/eyuvtoppm
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1
$ eyuvtoppm --version 2>&1 | head -5
eyuvtoppm: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
eyuvtoppm: Built from source dated 2024-03-31 09:09:47

The command's help response is short and points back to the manual page. The useful contract is eyuvtoppm [--width width] [--height height] [eyuvfile]. The width and height options are mandatory, even though the synopsis presents them as optional arguments. Each value must be an even number.

2. Confirm the dimensions before converting

Find the input dimensions from the producer, recording notes or the file's format documentation. eyuvtoppm does not infer them from the file name. Replace the placeholders below with the real values:

$ INPUT='/path/to/input.eyuv'
$ WIDTH=640
$ HEIGHT=480
$ test -r "$INPUT" && echo 'input is readable'
input is readable
$ test "$((WIDTH % 2))" -eq 0 && test "$((HEIGHT % 2))" -eq 0 && echo 'dimensions are even'
dimensions are even

These shell checks only test readability and parity. They do not prove that the dimensions match the encoded frames. A wrong but even dimension can still produce an unusable image, so keep the source of your values with the conversion record.

There is no need to run the converter as root. If the input is in a protected directory, copy it to a working directory using your normal approved process, or grant the least access needed. Do not loosen permissions on an archive merely to make this check pass.

3. Convert to a new PPM file

eyuvtoppm writes PPM data to standard output. Redirect that output to a new destination, keeping the input unchanged:

$ OUTPUT='/path/to/output.ppm'
$ eyuvtoppm --width "$WIDTH" --height "$HEIGHT" "$INPUT" > "$OUTPUT"
eyuvtoppm: Converting Frame 0

The progress line is diagnostic output, while the PPM bytes go to the redirected file. A multi-frame input may produce more than one conversion message and a PPM stream containing multiple images. Do not assume that one input file always means one output frame.

Shell redirection truncates an existing file before eyuvtoppm starts. That is a destructive overwrite if the destination already contains a useful image. Use a temporary name for a replacement:

$ TEMP_OUTPUT="${OUTPUT}.new"
$ eyuvtoppm --width "$WIDTH" --height "$HEIGHT" "$INPUT" > "$TEMP_OUTPUT"
$ test -s "$TEMP_OUTPUT" && echo 'new output is non-empty'
new output is non-empty
$ mv -- "$TEMP_OUTPUT" "$OUTPUT"

Only run the final mv after checking the new file. If conversion fails, inspect the diagnostic and remove the incomplete temporary file with rm -- "$TEMP_OUTPUT". The original output remains in place. If you used the direct command and truncated a file by mistake, recovery depends on your backups or filesystem snapshots; eyuvtoppm has no undo operation.

4. Verify the PPM header and dimensions

Use a file-inspection tool to check the result rather than opening binary data in a text editor:

$ file "$OUTPUT"
/path/to/output.ppm: Netpbm image data, size 640 x 480, rawbits, pixmap
$ head -c 2 "$OUTPUT"
P6

The wording from file can vary. The useful evidence is a non-empty PPM file, the expected width and height, and the P6 magic number for the binary PPM form produced by this installed command. The first bytes are readable header data; the remaining pixel data is binary.

A successful exit status means the command completed its conversion work. It does not establish that the dimensions were correct or that every frame looks right. View the PPM with a trusted image viewer or pass it to another installed Netpbm converter after the header check. Keep the original EYUV file until the image has been inspected.

5. Diagnose the common failures

An empty input is rejected. A missing or unreadable path is a filesystem problem, so check it without changing anything:

$ ls -l -- "$INPUT"
$ test -r "$INPUT" && echo readable || echo 'not readable'
$ eyuvtoppm --width "$WIDTH" --height "$HEIGHT" "$INPUT" > "$TEMP_OUTPUT"
eyuvtoppm: Empty EYUV input file

If the command rejects a dimension, check that both values are positive even integers and that they describe Berkeley EYUV data. If the file is accepted but the output is visually corrupt, the dimensions or format are likely wrong. Stop there and confirm the producer's format instead of trying random sizes.

The options shown here are the documented long forms, --width and --height. The input filename is optional: omit it to read EYUV data from standard input, for example producer | eyuvtoppm --width 640 --height 480 > output.ppm. This is convenient for a pipeline, but it makes it easier to lose track of which program supplied malformed data, so save the source file when troubleshooting.