Turn a Raw YUY2 Frame into a PAM Image with yuy2topam

yuy2topam converts a raw YUY2 frame into a viewable PAM image, from a file or from standard input. You will check that the result has the dimensions and RGB layout you expected. The installed command is from Netpbm 11.05.02, package version 2:11.05.02-1.1build1.

Allow about ten minutes. You need a shell, the netpbm package, and a YUY2 byte stream whose frame dimensions you already know. This is a conversion workflow, not a video decoder: the input itself carries no width or height metadata.

1. Check the installed command

Confirm which executable is being used and record the package version. Both are ordinary, read-only commands that need no elevated privileges:

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

The manpage describes yuy2topam as reading raw YUY2 bytes and writing a PAM image. It requires both -width and -height, with width in pixels and always even.

2. Convert a named frame

Put the actual frame path in INPUT.yuy2. Keep the dimensions right next to the command, since they are part of how the byte stream gets interpreted:

$ yuy2topam -width=640 -height=480 INPUT.yuy2 > frame.pam

No sudo is needed here, only permission to read the input and create frame.pam in the current directory. Redirecting with > replaces an existing file without asking, so check the destination first if it holds anything valuable.

Verify the result with Netpbm's own file inspector:

$ pamfile frame.pam
frame.pam: PAM, 640 by 480 by 3 maxval 255
    Tuple type: RGB

The filename in that first line is yours; what matters is the requested width and height, depth 3, maximum value 255, and RGB tuple type. If pamfile is unavailable, read the header directly:

$ sed -n '1,7p' frame.pam
P7
WIDTH 640
HEIGHT 480
DEPTH 3
MAXVAL 255
TUPLTYPE RGB
ENDHDR

3. Use standard input for a pipeline

Omit the filename when the bytes arrive on standard input, useful when a capture or decoding program already produces raw YUY2:

$ capture-command --raw-yuy2 | yuy2topam -width=640 -height=480 > frame.pam
$ pamfile frame.pam
frame.pam: PAM, 640 by 480 by 3 maxval 255
    Tuple type: RGB

Replace capture-command --raw-yuy2 with your real producer; it is a placeholder, not something Netpbm supplies. A successful exit status means the conversion completed, not that the producer used the right pixel format or dimensions, so compare the result with a known-good frame whenever the source settings are uncertain.

4. Make a small, reproducible test frame

For a harmless smoke test, create eight bytes representing a 4 by 1 input frame. This writes only under /tmp and needs no elevated privileges:

$ testdir=$(mktemp -d /tmp/yuy2topam-test.XXXXXX)
$ printf '\020\200\020\200\200\200\200\200' > "$testdir/input.yuy2"
$ yuy2topam -width=4 -height=1 "$testdir/input.yuy2" > "$testdir/output.pam"
$ pamfile "$testdir/output.pam"
/tmp/yuy2topam-test.XXXXXX/output.pam: PAM, 4 by 1 by 3 maxval 255
    Tuple type: RGB

Your own random suffix will differ. The output is RGB with depth 3 even though the input is packed YUY2, which checks the installed converter's argument handling but is no substitute for testing a real camera or capture device's actual format.

The test directory is temporary, but nothing here deletes it automatically. Once you have finished inspecting it, remove that specific directory and its two files with a file manager or a carefully checked command; do not turn a cleanup example into a recursive deletion of a broader directory.

5. Diagnose dimension and input errors

An odd width is rejected before conversion starts, since a YUY2 image always uses paired pixels:

$ yuy2topam -width=3 -height=1 INPUT.yuy2 > frame.pam
yuy2topam: -width 3 is odd, but YUY2 images must have an even width.

Supply an even width, then check that the producer really emitted that many pixels per row.

Both dimensions are mandatory. Leave one out and the command stops with a diagnostic such as:

$ yuy2topam -width=640 INPUT.yuy2 > frame.pam
yuy2topam: You must specify the image height with -height

A truncated input stream is also an error:

$ yuy2topam -width=640 -height=480 SHORT.yuy2 > frame.pam
yuy2topam: Unexpected end of input file

Do not treat a partially written output as usable when the command returns non-zero. Write to a temporary output and move it into place only after success, if another process consumes the file:

$ yuy2topam -width=640 -height=480 INPUT.yuy2 > frame.pam.tmp && mv frame.pam.tmp frame.pam

That final mv changes state in the current directory, but it is not privileged. If conversion fails, the old frame.pam stays put, and the temporary file remains there to inspect or remove.

6. Keep the boundaries clear

The command does not discover frame dimensions, repair a wrong byte order, or identify an input container. Set width and height from whatever actually produced the bytes. If a source hands you several frames concatenated together, run a deliberate frame-splitting step or use a program built to understand that stream; extra bytes are never a substitute for correct frame boundaries.

Use -quiet when normal libnetpbm messages would interfere with a script, but keep checking the exit status regardless:

$ yuy2topam -quiet -width=640 -height=480 INPUT.yuy2 > frame.pam
$ printf 'converter status: %s\n' "$?"
converter status: 0

Missing dimensions, an odd width, a short file and a bad source format are all data or command-line problems, not a reason to reach for elevated privileges. Use sudo only if a separate input or output path genuinely requires it, and check that path before writing.