How to use the command 'rawtopgm' (with examples)

The rawtopgm command is an essential utility for anyone working with raw greyscale images who needs to convert these files into a Portable Graymap Format (PGM). The PGM format is widely used in various image processing tasks because it is simple and provides compatibility with many tools. rawtopgm offers flexibility in handling different image dimensions, byte orders, and data skipping, making it a versatile tool for diverse applications in image processing.

Use case 1: Convert a raw greyscale image to a PGM image

Code:

rawtopgm width height path/to/image.raw > path/to/output.pgm

Motivation:

This command is used when you have a raw greyscale image and you want to convert it to the PGM format. PGM files are often easier to handle as they can be opened and manipulated by a variety of standard image processing tools. By specifying both the width and height, you ensure that the tool recognizes the dimensions correctly to construct the image accurately.

Explanation:

• width height: These specify the dimensions of the image. Providing these values is crucial as raw files do not contain metadata about the image dimensions, and without them, the conversion tool wouldn’t know how to structure the data.
• path/to/image.raw: This is the source raw image file you are converting.
• >: This symbol is used to direct the output of the command into a new file.
• path/to/output.pgm: This specifies the location and name of the new PGM file that will be created.

Example output:

A new PGM file will be created at the specified path, containing the greyscale image data in the PGM format. This file will be compatible with many image editing and processing tools.

Use case 2: Convert a raw greyscale image to a PGM image, assume the image to be a square

Code:

rawtopgm path/to/image.raw > path/to/output.pgm

Motivation:

This command is useful when your raw image is a square, and you prefer not to manually input width and height. The tool will attempt to infer the dimensions based on the file size, assuming a square layout.

Explanation:

• path/to/image.raw: Specifies the source raw file.
• >: Directs the conversion output to a specific file.
• path/to/output.pgm: Defines the output destination for the PGM file.

Example output:

The output will be a PGM file created at the specified location, assuming a square configuration for the original image with dimensions inferred from the raw data size.

Use case 3: Convert a raw greyscale image in which the pixels come bottom-first instead of top-first to a PGM image

Code:

rawtopgm width height -bottomfirst path/to/image.raw > path/to/output.pgm

Motivation:

This command is needed when images are stored in a format where the origin of pixel data starts at the bottom-left instead of the top-left. This is common in some raw image formats. This tool allows handling of such files seamlessly.

Explanation:

• width height: Defines the dimensions of the image.
• -bottomfirst: An option that tells the tool that the pixel data starts from the bottom. This ensures the image is correctly constructed top to bottom.
• path/to/image.raw: Indicates the source raw image file.
• >: Directs the output into a new file.
• path/to/output.pgm: The name and location of the resulting PGM file.

Example output:

A PGM file will be created where the pixel rows have been correctly reordered to start from the top of the image, reflecting the intended visual layout.

Use case 4: Ignore the first n bytes of the specified file

Code:

rawtopgm width height -headerskip n path/to/image.raw > path/to/output.pgm

Motivation:

Certain raw image files might have a header containing metadata or other non-image data that should be ignored during conversion. This command allows skipping over that unnecessary data, starting the reading process directly at the image data.

Explanation:

• width height: Dimensions of the image.
• -headerskip n: Skips the first n bytes of the file. Useful for bypassing unwanted header information.
• path/to/image.raw: The raw image file.
• >: Redirects the output.
• path/to/output.pgm: Output file for the conversion.

Example output:

A PGM file will be generated by excluding the initial n bytes of non-image data, ensuring the image data is uncorrupted and properly rendered.

Use case 5: Ignore the last m bytes of each row in the specified file

Code:

rawtopgm width height -rowskip m path/to/image.raw > path/to/output.pgm

Motivation:

In some formats, extra padding might be added at the end of each row. Ignoring these bytes ensures such padding does not interfere with the image rendering by discarding them before conversion.

Explanation:

• width height: Specifies the image dimensions.
• -rowskip m: Ignores the last m bytes of each row, ideal for removing row-specific padding.
• path/to/image.raw: The original raw file.
• >: Used for directing output.
• path/to/output.pgm: The file path for the new PGM image.

Example output:

You will get a PGM file with each row correctly converted without undesired padding, resulting in a correctly structured image.

Use case 6: Specify the maxval for the grey values in the input to be equal to N

Code:

rawtopgm width height -maxval N path/to/image.raw > path/to/output.pgm

Motivation:

Different raw files may use different ranges of grey levels. Specifying a maximum grey value ensures that the conversion scales the values properly, which helps in maintaining consistent visual quality across different displays.

Explanation:

• width height: Defines the dimensions.
• -maxval N: Tells the tool the maximum grey value in the input. It scales the image intensity based on this value to the standard 0–255 range.
• path/to/image.raw: The input file with raw data.
• >: Redirects the output.
• path/to/output.pgm: The destination and name of the PGM file.

Example output:

A PGM file will be created with grey values correctly adjusted according to the specified maximum value, ensuring uniform brightness and contrast.

Use case 7: Specify the number of bytes that represent each sample in the input and that the byte-sequence is to be interpreted as little-endian

Code:

rawtopgm width height -bpp 1|2 -littleendian path/to/image.raw > path/to/output.pgm

Motivation:

This command becomes crucial when dealing with raw images where pixels are represented by more than one byte, a common case in high-resolution images. Additionally, byte order matters, especially in systems with different endian conventions, and this option allows proper interpretation of multi-byte pixel values.

Explanation:

• width height: Specifies the image dimensions.
• -bpp 1|2: 1 or 2 indicates the number of bytes per pixel. This is important for correctly reading raw files that use more than 8 bits per pixel (e.g., 16 bits).
• -littleendian: Indicates that the byte order should be interpreted as little-endian. This is important for consistency with the source image data format.
• path/to/image.raw: The raw image file.
• >: Directs the conversion output.
• path/to/output.pgm: Path and name of the resulting PGM file.

Example output:

A correctly interpreted PGM file accounting for the possible extended bit-depth and endianess of the input, resulting in a faithful reproduction of the image.

Conclusion

The rawtopgm command is incredibly versatile, offering a robust solution for converting raw greyscale images to the PGM format. Whether dealing with non-standard image dimensions, byte ordering differences, or additional file headers and footers, rawtopgm allows for flexible and precise manipulation of raw imaging data. This makes it an essential command-line tool for scientists, photographers, and anyone working extensively with image data in technical contexts. By understanding and utilizing its various options, users can ensure compatibility and accuracy in their image processing tasks.