fitstopnm

Convert a FITS file to a PNM image

$ fitstopnm [path/to/file.fits] > [path/to/output.pnm]

$ fitstopnm [[-i|-image]] [z_position] [path/to/file.fits] > [path/to/output.pnm]

fitstopnm [-forceplain] [-stretch | -linear | -log | -histeq] [-minval=V | -maxval=V] [-range=R] [-null=N] [-nullout=N] [-noaxes] [-hdr=H] [-hdrlist=L] [-hdrfile=F] [-debug] [fitsfile]

-forceplain
    Outputs plain (ASCII) PGM/PPM format instead of raw (binary) format.

-stretch
    Uses a default stretching algorithm to scale pixel values for better visual representation.

-linear
    Applies a linear stretch to map pixel values to the output range, useful for even distribution.

-log
    Applies a logarithmic stretch, ideal for images with a very high dynamic range to emphasize faint features.

-histeq
    Performs histogram equalization, a contrast enhancement technique that spreads out the most frequent intensity values.

-minval=V
    Sets the minimum input FITS value 'V' that will be scaled to 0 in the output image.

-maxval=V
    Sets the maximum input FITS value 'V' that will be scaled to the maximum possible value (e.g., 255 or 65535) in the output image.

-range=R
    A shorthand for setting both -minval=0 and -maxval=R, scaling input values from 0 to R.

-null=N
    Specifies the FITS 'NULL' data value 'N' to be recognized by the command.

-nullout=N
    Specifies the output pixel value 'N' that will be used for FITS 'NULL' data.

-noaxes
    Omits the creation of a FITS axes file, which typically describes the image's coordinate system.

-hdr=H
    Prints the value of the specified FITS header keyword 'H' to standard error.

-hdrlist=L
    Prints the values of a comma-separated list of FITS header keywords 'L' to standard error.

-hdrfile=F
    Writes all FITS header information into the specified file 'F'.

-debug
    Enables debug output, providing more verbose information about the command's execution.

fitsfile
    The path to the input FITS file. If omitted, fitstopnm reads from standard input.

fitstopnm is a utility from the Netpbm project designed to convert astronomical Flexible Image Transport System (FITS) files into portable anymap formats, specifically PGM (Portable GreyMap) for grayscale images or PPM (Portable PixMap) for color images.

FITS files are a standard format in astronomy for storing scientific data, often including image data along with metadata. The command handles various FITS image types, including byte, integer, floating-point, and double-precision data, automatically scaling the pixel values to fit the 0-maxval range of the Netpbm output format. It offers several stretching methods (e.g., linear, logarithmic, histogram equalization) to enhance visibility of features in images with high dynamic ranges.

By default, fitstopnm processes the first image extension found within a FITS file. It also provides options for handling NULL data values and extracting header information, making it a crucial tool for astronomers to visualize and further process their observational data.

The command by default only processes the first image extension found in a FITS file. If a FITS file contains multiple image extensions, subsequent extensions will be ignored. Users needing to process multiple extensions must typically chain commands or use other tools capable of multi-extension FITS handling.

Output image types (PGM/PPM) are limited to 2D representations, meaning 3D or 4D FITS data will be collapsed or require specific handling outside the scope of direct fitstopnm output for full data representation.

fitstopnm automatically scales the pixel values from the FITS file's native range to the 0-maxval range (typically 255 or 65535, depending on the data type) of the Netpbm output. For images with a very wide dynamic range, such as those from astronomical instruments, the -stretch, -linear, -log, and -histeq options are crucial. These allow users to apply different mapping functions to enhance the contrast and visibility of features that might otherwise be indistinguishable due to the vast difference between the brightest and darkest parts of the image. The default stretching aims for a reasonable visual representation, but specific scientific analysis often requires one of the explicit stretching methods.

The command can read FITS files containing various numeric data types, including 8-bit unsigned integers, 16-bit and 32-bit signed integers, 32-bit single-precision floating-point numbers, and 64-bit double-precision floating-point numbers. It intelligently converts these to the appropriate PGM or PPM format, which typically uses 8-bit or 16-bit samples per pixel. This conversion involves careful scaling to preserve dynamic range as much as possible, guided by the chosen stretch method or specified min/max values.

fitstopnm is part of the Netpbm project, a comprehensive toolkit for manipulating graphic images. The Netpbm project itself has a long history, evolving from the original PBMplus package created by Jef Poskanzer in the late 1980s. fitstopnm was developed to provide a straightforward method for astronomers and researchers to convert FITS data, commonly used in fields like astronomy and remote sensing, into more universally viewable and manipulable image formats compatible with the vast Netpbm ecosystem. Its development reflects the ongoing need for flexible data interchange between specialized scientific formats and general-purpose image processing tools.

pnmtopng(1), pnmtops(1), pgm(5), ppm(5), netpbm(1)