rawtoppm

Convert a raw RGB stream to a PPM image

$ rawtoppm [width] [height] [path/to/image.raw] > [path/to/output.ppm]

$ rawtoppm [width] [height] [path/to/image.raw] | pamflip [[-tb|-topbottom]] > [path/to/output.ppm]

$ rawtoppm [width] [height] [[-h|-headerskip]] [n] [path/to/image.raw] > [path/to/output.ppm]

$ rawtoppm [width] [height] [[-ro|-rowskip]] [m] [path/to/image.raw] > [path/to/output.ppm]

$ rawtoppm [width] [height] -[rgb|rbg|grb|gbr|brg|bgr] [path/to/image.raw] > [path/to/output.ppm]

rawtoppm [-force] [-rows] [-r | -g | -b | -rgb] [-interleave | -nodynamicrange] [-output output_file] width height

width
    The width of the image in pixels. This is a mandatory argument that defines the horizontal dimension of the output image.

height
    The height of the image in pixels. This is a mandatory argument that defines the vertical dimension of the output image.

-force
    Do not check for end-of-file after reading all expected data. This can be useful when dealing with potentially truncated or continuously streaming inputs.

-rows
    Process the input data in row-major order. This option is often implicitly understood or may align with the default data output format of many raw sources.

-r | -g | -b
    Extracts and converts only the specified color channel (red, green, or blue) into a grayscale PPM image. The data from the other channels is ignored.

-rgb
    Processes all three color channels (Red, Green, Blue) in the default RGB order. This is the default behavior if no specific channel extraction option is provided.

-interleave
    Assumes that the color components for each pixel are interleaved (e.g., R-G-B-R-G-B...). This is a common arrangement for many raw data outputs from hardware devices.

-nodynamicrange
    Disables the default dynamic range adjustment that rawtoppm might perform to optimize output. Use this to preserve exact original pixel values without scaling.

-output output_file
    Specifies the name of the output file for the PPM image. If this option is not provided, rawtoppm writes the image to standard output (stdout).

The rawtoppm command is a specialized utility within the Netpbm suite, designed to convert raw RGB (Red, Green, Blue) byte streams into a standard Portable Pixmap (PPM) image format.

It's particularly useful for processing data directly from hardware sources such as frame grabbers, scanners, or embedded systems that output unprocessed pixel data. Unlike image processing tools that handle complex file formats with headers or compression, rawtoppm expects a continuous stream of raw pixel data, where each byte or group of bytes represents a color component for a specific pixel.

Users must specify the image's width and height, as this information is not present in the raw data stream. The command reads the raw bytes from standard input by default, or from a specified file, and then outputs the resulting PPM image to standard output, which can be redirected to a file or piped to another Netpbm tool for further manipulation.

It's a foundational tool for integrating raw hardware output into a standard image processing workflow, leveraging the simplicity and interoperability of the Netpbm formats.

rawtoppm is strictly for truly raw, uncompressed byte streams. It does not handle any form of image headers, metadata, or complex raw camera formats (like those from DSLRs, e.g., CR2, NEF). For such files, a pre-processor like dcraw or specialized conversion tools are required before using rawtoppm.

The command assumes 8-bit samples per color component, producing a PPM with a maximum pixel value of 255. The exact order of input bytes (e.g., RGB vs. BGR) is crucial and must match the implicit or explicit assumptions of the command, or the output image colors will be incorrect.

By default, rawtoppm reads raw byte data from standard input (stdin) and writes the resulting PPM image to standard output (stdout). This allows for easy piping with other commands, such as `cat raw_data.bin | rawtoppm 640 480 > image.ppm` for converting a file, or processing a live stream.

The output PPM image will always have a `MAXVAL` of 255, meaning it's an 8-bit per channel image. This characteristic aligns with common raw hardware outputs. If higher bit depths are needed, the output PPM can be further processed by other Netpbm tools, such as `pnmdepth`, to adjust the depth.

rawtoppm is an integral part of the Netpbm project, which originated from the PBMPlus package created by Jef Poskanzer in the late 1980s. PBMPlus was designed to provide a set of simple, composable tools for manipulating bitmap images on Unix-like systems. The utility rawtoppm was developed early in this lineage to fulfill the fundamental need of converting raw, unformatted pixel data from hardware devices (like early video digitizers or scanners) into a universally readable image format. Its design reflects the Unix philosophy of small, single-purpose utilities that can be chained together, making it a robust and enduring component for basic image stream processing.

ppm(5), netpbm(1), rawtopgm(1), rawtopbm(1), anytopnm(1), pnmdepth(1)