yuy2topam

Convert YUY2 bytes to PAM

$ yuy2topam [[-w|-width]] [value] [[-h|-height]] [value] [path/to/file.yuy2] > [path/to/file.pam]

yuy2topam width height

width
    The exact width, in pixels, of the YUY2 image stream being provided to standard input.

height
    The exact height, in pixels, of the YUY2 image stream being provided to standard input.

The yuy2topam command is a specialized utility within the comprehensive Netpbm image manipulation toolkit. Its primary function is to convert raw YUY2 pixel data, typically streamed from a video source or file, into the Portable Arbitrary Map (PAM) format. YUY2 (also known as YUYV) is a common packed pixel format where chroma (color) information is subsampled horizontally, making it efficient for video storage and transmission.

yuy2topam reads the raw YUY2 data from standard input (stdin) and outputs the converted PAM image to standard output (stdout). This design makes it highly suitable for use in Unix-like pipelines, allowing users to chain it with other Netpbm tools for further processing, such as converting to other image formats (like PNG or JPEG), resizing, or applying various image filters.

The command requires the exact width and height of the YUY2 input image as command-line arguments to correctly interpret the incoming byte stream. It handles the necessary color space conversion from YUV to RGB as part of its process, producing a standard RGB image in PAM format.

yuy2topam expects raw YUY2 data without any header information. Providing incorrect width or height values will lead to a corrupted or unreadable output image. It assumes a continuous stream of YUY2 frames if used with video, processing only the first frame based on the specified dimensions unless further processing in a loop is managed externally. The command itself does not provide error messages for malformed input beyond what Netpbm might inherently detect during PAM creation.

This command operates strictly on standard input (stdin) for YUY2 data and standard output (stdout) for the resulting PAM image. This design facilitates its integration into shell scripts and complex data processing pipelines, where it can be combined seamlessly with other commands for data acquisition, manipulation, and storage.

YUY2 is a YCbCr (or YUV) color space format, which separates luma (brightness) from chroma (color). yuy2topam automatically performs the necessary conversion from this YCbCr color space to RGB (Red, Green, Blue) as part of its processing. The output PAM file will represent the image in an RGB format, suitable for display or further processing by tools that expect RGB data.

yuy2topam is an integral part of the Netpbm project, a long-standing and widely used toolkit for graphics file format conversion. The Netpbm suite originated from Jef Poskanzer's Pbmplus package, first released in 1988, and was later continued as Netpbm in 1993. The philosophy of Netpbm tools is to be small, single-purpose utilities that can be chained together in powerful ways through Unix pipes.

As video formats and digital imaging became more prevalent, specific converters like yuy2topam were added to handle common raw video pixel formats, extending Netpbm's capability beyond static image files to encompass streams of image data from devices or files. Its development reflects the continuous evolution of the Netpbm project to support a broader range of image and video data types.

pam(5), pnm(5), rawtoppm(1), rgbtoppm(1), anytoppm(1)