LinuxCommandLibrary

rawtopgm

Convert raw image data to PGM format

TLDR

Convert a raw greyscale image to a PGM image

$ rawtopgm [width] [height] [path/to/image.raw] > [path/to/output.pgm]
copy

Convert a raw greyscale image to a PGM image, assume the image to be a square
$ rawtopgm [path/to/image.raw] > [path/to/output.pgm]
copy

Convert a raw greyscale image in which the pixels come bottom-first instead of top-first to a PGM image
$ rawtopgm [width] [height] [[-bt|-bottomfirst]] [path/to/image.raw] > [path/to/output.pgm]
copy

Ignore the first n bytes of the specified file
$ rawtopgm [width] [height] [[-h|-headerskip]] [n] [path/to/image.raw] > [path/to/output.pgm]
copy

Ignore the last m bytes of each row in the specified file
$ rawtopgm [width] [height] [[-r|-rowskip]] [m] [path/to/image.raw] > [path/to/output.pgm]
copy

Specify the maxval for the grey values in the input to be equal to n
$ rawtopgm [width] [height] [[-m|-maxval]] [n] [path/to/image.raw] > [path/to/output.pgm]
copy

Specify the number of bytes that represent each sample in the input and that the byte-sequence is to be interpreted as little-endian
$ rawtopgm [width] [height] -bpp [1|2] [[-l|-littleendian]] [path/to/image.raw] > [path/to/output.pgm]
copy

SYNOPSIS

rawtopgm
[ -width cols ]
[ -height rows ]
[ -maxval maxval ]
[ -bytes bytes_per_sample ]
[ -msbfirst | -lsbfirst ]
[ -rowstride bytes_per_row ]
[ -headerbytes bytes ]
[ rawfile ]

PARAMETERS

-width cols
    Specifies the width of the image in pixels. This is a mandatory parameter as rawtopgm cannot guess the image width from raw data.

-height rows
    Specifies the height of the image in pixels. This is a mandatory parameter as rawtopgm cannot guess the image height from raw data.

-maxval maxval
    Sets the maximum grayscale value for pixels. This determines the dynamic range of the image. Common values are 255 for 8-bit images or 65535 for 16-bit images. Defaults to 255 if not specified.

-bytes bytes_per_sample
    Specifies the number of bytes per pixel sample. Use 1 for 8-bit images, 2 for 16-bit images, etc. Defaults to 1 if not specified.

-msbfirst
    Specifies that multi-byte samples (e.g., 16-bit pixels) are stored with the most significant byte first (big-endian). This is the default if neither -msbfirst nor -lsbfirst is given.

-lsbfirst
    Specifies that multi-byte samples are stored with the least significant byte first (little-endian).

-rowstride bytes_per_row
    Specifies the number of bytes between the start of one row and the start of the next. Useful when rows are padded. If not specified, it defaults to width * bytes_per_sample.

-headerbytes bytes
    Specifies the number of bytes to skip at the beginning of the input file before reading image data. Useful for files with a small header.

DESCRIPTION

rawtopgm is a utility from the Netpbm project designed to convert raw, unformatted grayscale pixel data into the Portable Graymap (PGM) image format. It is particularly useful for processing data directly from imaging sensors, scanners, or scientific instruments that output raw pixel streams without any embedded header or structural information.

The command requires the user to specify crucial image parameters such as width, height, maximum pixel value, and the number of bytes per sample, as this information is not present in the raw data itself. It also handles byte order (MSB first or LSB first) for multi-byte samples. rawtopgm typically reads raw data from standard input or a specified file and writes the resulting PGM image to standard output, making it easy to pipe its output to other Netpbm tools for further manipulation, such as scaling, cropping, or conversion to other image formats.

CAVEATS

rawtopgm relies entirely on user-provided metadata (width, height, maxval, bytes per sample) as raw data contains no self-describing information. Incorrect parameters will lead to a garbled or corrupted image. It only generates PGM (grayscale) images; for color raw data, other tools or custom scripts are needed. It does not handle any form of image compression.

STANDARD INPUT/OUTPUT

rawtopgm typically reads raw image data from standard input if no rawfile argument is provided, and writes the resulting PGM image to standard output. This behavior makes it ideal for use in shell pipelines, allowing it to easily integrate with other commands. For example, cat raw_data.bin | rawtopgm -width 640 -height 480 -maxval 255 > image.pgm is a common usage pattern. This flexibility is a core design principle of Netpbm tools.

HISTORY

rawtopgm is part of the Netpbm package, a comprehensive set of graphics utilities that evolved from the Pbmplus project in the early 1990s. The Netpbm tools are known for their simplicity, flexibility, and ability to be chained together in shell pipelines. rawtopgm was developed to handle the common task of converting raw sensor output directly into a standard image format, making it accessible for further processing within the Netpbm ecosystem.

SEE ALSO

pgm(5), pnm(5), pamtopnm(1), anytopnm(1), pnmtoplainpnm(1)

Copied to clipboard