pnmtofits

View documentation for the current command

$ tldr pamtofits

pnmtofits [-type] [-input ] [-output ] [-header ] [-comment ] [-history ] [-bzero ] [-bscale ] [-bitpix ] [-naxis ] [-naxis1 ] [-naxis2 ] []

-type
    Specifies the desired output FITS data type. Options include -int8, -int16, -int32 for integer data, and -float32, -float64 for floating-point data. This option overrides the default BITPIX calculation.

-input
    Designates the path to the input PNM file. If this option is omitted, pnmtofits reads the PNM data from standard input (stdin).

-output
    Specifies the path for the output FITS file. If not provided, the resulting FITS data is written to standard output (stdout).

-header
    Adds a raw FITS header card directly into the output FITS file. The should be a valid FITS header line, e.g., 'KEYWORD = VALUE / Comment text'.

-comment
    Inserts a COMMENT keyword entry into the FITS header with the provided string. This is useful for general descriptive text.

-history
    Adds a HISTORY keyword entry to the FITS header with the specified string. Typically used to log processing steps or significant events related to the data.

-bzero
    Sets the BZERO keyword in the FITS header. This value acts as an offset when converting scaled FITS pixel values to their true physical values (true_value = BZERO + BSCALE * pixel_value).

-bscale
    Sets the BSCALE keyword in the FITS header. This value acts as a scaling factor when converting scaled FITS pixel values to their true physical values (true_value = BZERO + BSCALE * pixel_value).

-bitpix
    Explicitly sets the BITPIX keyword in the FITS header, which indicates the number of bits per data pixel (e.g., 8, 16, 32 for signed integers; -32, -64 for floating point). This overrides the command's default detection.

-naxis
    Sets the NAXIS keyword, specifying the number of axes (dimensions) in the data array. For 2D images, this value is typically 2.

-naxis1
    Sets the NAXIS1 keyword, representing the length or size of the first axis of the image data (e.g., the width in pixels).

-naxis2
    Sets the NAXIS2 keyword, representing the length or size of the second axis of the image data (e.g., the height in pixels).


    A positional argument for the input PNM file. This serves as an alternative to using the -input option.

The pnmtofits command is a specialized utility from the Netpbm suite designed to convert image files in the Portable Anymap (PNM) format (which includes PBM for bitmaps, PGM for graymaps, and PPM for pixmaps) into the Flexible Image Transport System (FITS) format. FITS is a widely adopted standard for data exchange in astronomy, astrophysics, and other scientific fields, primarily used for storing images, tables, and multidimensional data.

This command acts as a bridge between general-purpose image manipulation (offered by Netpbm) and scientific data processing. It reads a 2D PNM image from standard input or a specified file and outputs a FITS file to standard output or a specified file. pnmtofits intelligently determines an appropriate FITS data type (BITPIX) based on the input PNM's maximum value, but it also allows users to explicitly override this for specific FITS encoding requirements. Furthermore, it provides options to embed crucial metadata such as custom header keywords, comments, and history entries, which are essential for documenting scientific datasets and their provenance.

pnmtofits is designed specifically for converting 2-dimensional images. It does not support multi-extension FITS (MEF) files, FITS tables (binary or ASCII), or multi-dimensional data beyond two axes directly from PNM. While it attempts to choose an appropriate BITPIX value by default, explicit setting via -bitpix or -type might be necessary to avoid data precision loss during conversion, especially with higher bit-depth PNM inputs, or to meet specific FITS standard requirements for certain datasets.

FITS files are unique in that they store not only the primary image or data array but also extensive descriptive metadata within a structured header section. Key header keywords, many of which pnmtofits can manage, include:
BITPIX: Defines the data type and bit depth of the individual pixels (e.g., 8, 16, 32 for integers; -32, -64 for floats).
NAXIS: The number of dimensions in the data array.
NAXIS1, NAXIS2, ...: The size or length of each respective dimension.
BZERO, BSCALE: Used for linear scaling of pixel values to their true physical units using the formula: true_value = BZERO + BSCALE * pixel_value.
pnmtofits automatically generates a basic FITS header containing essential information from the PNM input, but users can add custom information vital for scientific analysis, data provenance, and inter-instrument compatibility.

When the -bitpix option is not explicitly specified, pnmtofits applies a default logic to determine the most appropriate BITPIX value for the output FITS file, based on the characteristics of the input PNM image:
- For PBM (Portable Bitmap) input, where pixel values are binary (0 or 1), BITPIX typically defaults to 8.
- For PGM (Portable Graymap) or PPM (Portable Pixmap) input:
- If the maximum pixel value (maxval) within the PNM header is 255 or less, BITPIX defaults to 16.
- If the maximum pixel value (maxval) is greater than 255 (indicating a wider dynamic range), BITPIX defaults to -32 (representing single-precision floating-point numbers) to preserve higher precision values and avoid truncation.

The pnmtofits command is an integral part of the Netpbm project, which originated from the `pbmplus` package created by Jef Poskanzer in the late 1980s. Netpbm rapidly evolved into a versatile toolkit for converting and manipulating a wide array of image formats. Concurrently, the FITS (Flexible Image Transport System) standard was developed in the late 1970s and early 1980s, specifically to facilitate the reliable exchange of astronomical data between disparate institutions and software systems. The inclusion of pnmtofits within the Netpbm suite allowed users to seamlessly integrate general image processing workflows with the specialized FITS data format, bridging common image utilities with the critical data archiving and analysis needs of the scientific community.

pnm(5), fits(5), netpbm(1), anytopnm(1), fitscopy(1) (from cfitsio), fv (FITS viewer)