Turn a Raw YUY2 Frame into a PAM Image with yuy2topam

You will convert one raw YUY2 frame into a PAM image, either from a file or from standard input, and 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 know. This is a conversion workflow, not a video decoder: the input carries no width or height metadata.

1. Check the installed command

Confirm which executable is being used and record the package version. These are ordinary, read-only commands and do not need 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. The width is in pixels and must be even.

2. Convert a named frame

Put the actual frame path in INPUT.yuy2. Keep the dimensions beside the command, because they are part of the interpretation of the byte stream:

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

There is no sudo in this command. You only need permission to read the input and create frame.pam in the current directory. Redirecting output with > replaces an existing file without asking, so check the destination first if it contains anything valuable.

Verify the result with Netpbm's file inspector:

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

The exact filename in the first line is yours. The important values are the requested width and height, depth 3, maximum value 255, and RGB tuple type. If pamfile is unavailable, inspect 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. This is useful when another 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 the real producer. It is a placeholder, not a command supplied by Netpbm. A successful exit status means the conversion completed; it does not prove that the producer used the right pixel format or dimensions. Compare the resulting image with a known-good frame when 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. The command below writes only under /tmp and does not need 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

The random suffix in the path will differ. The output file is RGB with depth 3, even though the input is the packed YUY2 form. This test checks the installed converter and its argument handling; it is not a substitute for checking a real camera or capture device's format.

The test directory is temporary, but the example does not delete it automatically. When 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 broad directory.

5. Diagnose dimension and input errors

An odd width is rejected before conversion because a YUY2 image 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. If one is absent, 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 a usable image 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

The final mv changes state in the current directory, but it is not privileged. If conversion fails, the old frame.pam remains in place and the temporary file can be inspected or removed.

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 the source that produced the bytes. If a source gives you several frames concatenated together, run a deliberate frame-splitting workflow or use a program that understands that stream; extra bytes are not a substitute for correct frame boundaries.

Use -quiet when normal libnetpbm messages would interfere with a script, but continue to check the exit status:

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

Do not grant elevated privileges merely because conversion fails. Missing dimensions, an odd width, a short file, and a bad source format are data or command-line problems. Use sudo only if a separate input or output path genuinely requires it, and check that path before writing.