fitshdr(1)

NAME

SYNOPSIS

DESCRIPTION

Fitshdr utility allows to display or modify FITS headers (FITS MultiExtentionsFiles included).
In 'dump' mode (see below): allows to see/dump/display FITS-headers information. In 'edit' mode: permits to modify existent FITS-file headers.
ATTENTION: "existent FITS-file headers" means, that all modifications will be done directly in the FITS-file, which was specified for editing! You can't, for example, expand existent header (You can't change size of header). And, no backups! More simple, fitshdr is some sort of binary editor. If You are looking for more "traditional" editors, check fitshdr_edit and fitshdr_expand man pages.  

OPTIONS

-F FITSFILE, --file=FITSFILE, --fits-file=FITSFILE

FITSFILE - FITS-file name to browse or modify, mandatory in 'edit' mode (see --edit and -H options).
In 'dump' mode, if FITS-file name is missed, stdin is used instead.

--edit

'Edit' mode. If You want to modify headers of FITSFILE using new FITS-header lines from HEADER file (or from stdin), You have to use this option (You can skip this option, if -H or --header option is used). Obviously, in this case FITS file name FITSFILE has to be defined (or by --file, --fits-file, -F options, or as last (free) argument of fitshdr utility). If --edit options is defined, but -H or --header is not, in this case stdin is used to read new header lines.

-H HEADER, --header=HEADER

HEADER - Header file name. This file contains header's lines, which will be included in FITS-header. This option activates 'edit' mode automaticaly (means: it is not necessary to specify --edit option in this case). See --edit option.

-h, --help

Output a brief help message.

-V, --version

Print the version number of fitshdr to standard error and exit.

-v, --verbose

Produces verbose output. Multiple -v options increase the verbosity.

-q, --silent

Produces less verbose output. Multiple -q options decrease the verbosity.

-n, --test

In 'edit' mode: do everything... but don't write nothing. Useful, to check new header lines before writing them to FITS-file. WARNING: In some cases, --test option produces internal checks' result different from "normal" one (without --test ).
In 'dump' mode: ignored.

-p, --pedantic

More internal checks. Multiple -p options increase the number of internal checks.

-f, --force

Less internal checks. Multiple -f options decrease the number of internal checks.

--empty-lines

Empty header lines are displayed (in 'dump' mode only).

--no-empty-lines

Empty header lines are not displayed (in 'dump' mode only).

--line-offsets

In 'edit' mode: the usage of lines' offsets in input header-file is mandatory.
In 'dump' mode: file offset will be displayed for each header line.

--no-line-offsets

In 'edit' mode: the usage of lines' offsets in header file is optional (means: You can use offsets, but this is not obligatory).
In 'dump' mode: file offset will not be displayed for each header line.

--header-offsets

In 'dump' mode: headers offsets informations will be added to the output.
In 'edit' mode: ignored.

--no-header-offsets

In 'dump' mode: headers offsets informations will not be included in output.
In 'edit' mode: ignored.

--block-offsets

In 'dump' mode: FITS-blocks' offsets informations will be added to the output.
In 'edit' mode: ignored.

--no-block-offsets

In 'dump' mode: FITS-blocks' offsets informations will not be included in output.
In 'edit' mode: ignored.

--data-offsets

In 'dump' mode: FITS-data blocks' offsets informations will be added to the output.
In 'edit' mode: ignored.

--no-data-offsets

In 'dump' mode: FITS-data blocks' offsets informations will not be included in output.
In 'edit' mode: ignored.

--reformat-cards

In 'edit' mode: re-format input FITS-header lines before writing. In this case You can use, for example, as input header lines in "free" format (You can skip multiple spaces, etc.). WARNING: HIERARCH "non-standard" keywords will not be re-formated!
In 'dump' mode: ignored.

--no-reformat-cards

In 'edit' mode: don't re-format input FITS-header lines (means: input lines were formated already).
In 'dump' mode: ignored.

--modify-principal-keywords

In 'edit' mode: allows to modify ``principal'' FITS-keywords, such as SIMPLE, BITPIX, NAXIS, ... DANGEROUS! Be careful: wrong ``principal'' keywords values can destroy Your data!
In 'dump' mode: ignored.

--discard-old-headers

In 'edit' mode: really DANGEROUS! This option allows to change completely structure of FITS-file... and as result: You can damage important data. Don't use, if You are not the author of fitshdr utility.
In 'dump' mode: it makes no sense to use... but safe :)

INPUT AND OUTPUT

        NNNN:HEADER_LINE

where NNNN - file offset for this header line, HEADER_LINE - header line string. Offset specification could be omitted (skipped). As offset positive integer (NNNN%80 == 0) is expected. Special (relative) offsets +NNNN and -NNNN are supported. Two input header's lines

        +0:HEADER_LINE
and
        HEADER_LINE

``END'' FITS-header card.
The ``END'' FITS-header card has special meaning.

The processing of the ``normal'' FITS-card does the following:

- 80 bites will be written to the file (started from NNNN
  offset).

- The file pointer will be pointed to the next FITS-card.

In contract, the processing of the input FITS-card ``NNNN:END'' does:

- 80 bites will be written to the file (started from NNNN
  offset).

- The tail of current FITS-block will be filled by spaces.

- The file pointer will be pointed to the beginning of the
  next FITS-header, if exists.

ATTENTION: FITS-header line (card) "END" (without offset) does last action only! Means: the only file offset will be changed after processing input FITS-header line "END" without offset! If You want to avoid such behavior, use "+0:END" header line instead.

Comment lines.
Input header lines with ";" symbol in first position are ignored by fitshdr in 'edit' mode.  

EXAMPLES

Simplest example. To display FITS-headers information:

   fitshdr file.fits

where file.fits - existent FITS-file name. As the result, You'll see something like:

;;; 0: HEADER No.0
;;; 0: BLOCK No.0
SIMPLE  =                    T
BITPIX  =                   32
NAXIS   =                    0
AUTHOR  = 'Name of author'     / comment here
CRDELT1 =                 10.0
CRDELT2 =                 21.0 / this is an example
HISTORY  header No.0: 1st history line 123456789012345678901234567
COMMENT  Sat Sep 25 21:17:34 CEST 2004 / by fitshdr_edit
;;; 2880: BLOCK No.1

Next step. We want to add lines offsets for each header line and suppress blocks' offsets output. In this case:

   fitshdr --line-offsets --no-block-offsets file.fits

In this case we'll have:

;;; 0: HEADER No.0
0:SIMPLE  =                    T
80:BITPIX  =                   32
160:NAXIS   =                    0
400:AUTHOR  = 'Name of author'     / comment here
480:CRDELT1 =                 10.0
560:CRDELT2 =                 21.0 / this is example
720:HISTORY  header No.0: 1st history line 123456789012345678901234567
880:COMMENT  Sat Sep 25 21:17:34 CEST 2004 / by fitshdr_edit

Another useful example. How to display headers' information in case if FITS-file was gzip-ed:

   gunzip < file.fits.gz | fitshdr

Now, about editing... Again, simplest example. We want to change header line with offset 720. In this case:

   echo "720:CRPIX1 = 10. / comment" | fitshdr --edit file.fits

The line (see previous example)

HISTORY  header No.0: 1st history line 123456789012345678901234567

was substituted by

CRPIX1  =                 10.0 / comment

As You can see, input line was formated before writing.

Now more complex example. We want to edit interactively FITS-headers.

   fitshdr --line-offsets file.fits > tmp.hdr
   emacs tmp.hdr
   fitshdr --line-offsets --header=tmp.hdr --edit file.fits

First, header was written in file tmp.hdr. After this temporary file was changed in emacs editor. And after this new header was written back to FITS-file.
NOTE: This is just an example. Better for such purposes use fitshdr_edit script.

More useful/"realistic" example. We want (by some reason) change in headers name of keyword.

   fitshdr --empty-lines file.fits | \
   sed "s/^FILTER /FILTER1/" | \
   fitshdr --edit file.fits

In this example, the FILTER keyword was substituted by FILTER1. Keyword's value was not changed (only name of keyword was changed).

DIAGNOSTICS

On success, zero is returned and non-zero, if an error occurred.  

SEE ALSO

fitshdr_edit(1), fitshdr_expand(1)  

BUGS

Email bug reports to fitshdr@sai.msu.ru. Be sure to include the word ``fitshdr'' somewhere in the ``Subject:'' field.

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

INPUT AND OUTPUT

EXAMPLES

DIAGNOSTICS

SEE ALSO

BUGS