This HTML automatically generated with rman for NEMO
Table of Contents

Name

scanfits - scan a fits file, optionally extract and convert.

Synopsis

scanfits in=fits_file [parameter=value]

Description

scanfits reads a FITS file. It scans the header for various FITS (mis)interpretations, and reports on bad behaviour. Some of it can be fixed, in which case the header and/or data can be output to a file. It is also possible to insert new card images in a header.

FITS Header-Data Unit’s (HDU) can be extracted individually by using the hdu keyword. 0 typically signifies all of the HDU’s in a file, you can select them by number, 1 being the first.

Since scanfits can only process disk FITS files, FITS files on tape have to be extracted using dd(1) or similar programs. See also notes in ccdfits(1NEMO) how to process fits files from tape.

This program was written while the author was on the first FITS panel. The cfitsio package is now also providing a FITS checker called fitsverify.

Parameters

The following parameters are recognized in order; they may be given in any order if the keyword is also given. Use --help to confirm this man page is up to date.
in=fits-infile
input file, in fits(5) format. The input fits file is allowed to have many HDU’s. [no default].
out=fits-outfile
output file, in fits(5) format. If split=t this is the basename of the output filename. The basename can contain a standard printf(3) expression (e.g. try%d.fits), in which case the HDU will be automatically encoded in the output filename(s). If no filename is given, the input fits file is only scanned, and a summary of the selected HDU’s is presented (see also print=). The header can also be fixed up (see delete=, keep=, insert= and fix= below), though the data cannot be modified, but it is guaranteed that the size of the data portion on disk will be a multiple of the logical block size (blocking * 2880, see below), even if the last did not have this. [default: none].
hdu=integer_list
List of HDU’s of the FITS file that need to be processed. ( Note: currently only one at a time can be processed) Using a value of 0 will cause all HDU’s (the whole fits file) to be read. [default: 0].
delete=pattern
A list of patterns can be given, separated by comma’s. Note that no spaces can be used: a space is considered part of the pattern. Each of these is matched against the card images. If a match is found, that particular card images is deleted by blanking the card. Blank lines can then be deleted from the FITS header using fix=BLANK, see below. The list can be empty, in which case no action is undertaken. Note that only one of keep= and delete= can be given. [default: none].
keep=pattern
A list of patterns can be given, separated by comma’s. Each of these is matched against the card images. When all the card images have been scanned, only the ones which were part of the keep patterns will not be blanked out. Blank lines can subsequently be deleted from the header by using fix=BLANK, see below. The list can be empty, in which case no action is undertaken. Note that only one of keep= and delete= can be given. Note: Be careful when using this keyword, and that the required keywords are not deleted this way. [default: none].
insert=hfile
A list of files with (currently valid FITS header format) header cards, which will be inserted *as is* just before the END keyword in the above selected HDU’s. Note that these insertions are done after any of the above mentioned optional keep, delete, fix etc. To get an example file, extract an editable ASCII header with e.g. fitshead, or see the example below. NOTE: The lines need to be exactly 80 characters wide, any lines shorter than this will be blankfilled according to the FITS rules, and any lines wider than 80 will be cut. [Default: none].
fix=options
List of fixes, separated by comma’s. Possible options are: ING, TUCSON, LF, BLANK, ZERO, DECORDER, FIRST, LAST, Y2K, UNY2K and IRAF0. For an description see the section FIXES below. The list can be empty, in which case no fixes are applied. [default: none].
print=pattern
A list of patterns with which a FITS keyword (really: the first 8 characters on a FITS card image) begins. For these keywords the value or HISTORY/COMMENT is printed on lines starting with a # symbol. Different header sections are separated with the ## symbol in the first column. Note that is either keep= or delete= has been used, the blanked header cards cannot be seen anymore via the print= keyword. Note that printout is only active in scanmode. If an output file is created, this keyword is not active. [Default: not used].
blocking=factor
Positive integer that denotes the blocking factor with which the input file was written. The second number is the blocking factor for output. If the second number if not supplied, it is taken the same as the first one. The blocking factor is the multiple of blocks of 2880 bytes with which the data is to be read/written. The FITS standard allows the blocking factor to be from 1 to 10. Be aware that datafiles that need a blocking factor larger than 1, may not need it once the data is written to disk. [default: 1,1].
select=header|data
Select data, header or both (separated by comma’s) for output. [Default: header,data].
split=t|f
Boolean (t/f) to designate that when an output file is selected (out=) AND multiple files to be copied (file=0) the output file is split into it’s ‘‘file’’ components. The fits-outfile name will then be a base filename, and the program generates its own numeric extension. [Default: false].

Fixes

This is a list of the currently supported fixes for the header. Each of them is applied in the order as they appear in the fix= keyword. Their names have to be supplied in full, separated by commas. No spaces.
ING
Isaac Newton Group (ING) uses 9 blanks in the first column, followed by the word ING, followed by a space, after which an ING specific keywords start. If you want to promote these to regular keywords, a shift of 13 characters to the left does the job. The 13 rightmost characters in the card image are set to blank.
TUCSON
Certain FITS files coming out of NRAO TUCSON have card images starting with SINGLDSH. The next 10 characters are used for another level of identification, and at position 19 the actual FITS-like keyword starts. By using this option the FITS keyword starting at position 19 is promoted to a real FITS keyword, by shifting those 18 positions to the left. The 18 rightmost characters in the card image are set to blank.
LF
Character 80 (the last one) in each header card image is patched with a linefeed (newline) (hexadecimal 0x0A). This is useful to edit the header with an ASCII editor on UNIX. It would normally be used with options=header. See also fitshead(1NEMO) if you don’t want to see trailing blanks.
BLANK
Delete all card images which are completeley blank. This is often the result of either old style FITS files, or when card images had been blanked before with delete=pattern or keep=pattern Since the fix is applied
after the blank only one run of scanfits is needed to blank out and delete certain card images, e.g. scanfits in out delete=ING fix=BLANK.
ZERO
Replace all zero’s in the header by blanks.
FIRST
Retain only the first keyword if they occur multiple times in the header. The other card images are blanked. HISTORY and COMMENT and anything that does not have an ’=’ in column 9 are not affected.
LAST
Retain only the last keyword if they occur multiple times in the header. The other card images are blanked. HISTORY and COMMENT and anything that does not have an ’=’ in column 9 are not affected.
Y2K
If a keyword DATExxxx is present, and it matches the pattern "dd/mm/yy", it will be transformed to "yyyy-mm-dd", which makes the file Y2K compliant. FYI: the unix date(1) command produces Y2K compliant with date -u +%Y-%m-%dT%H:%M:%S.%N, where the subsecond .%N portion is optional. The old style is done with date +%d/%m/%y, which does not sort lexically, and no timezone has been applied. The TIME-OBS keyword has also been used before Y2K to record the observation.
UNY2K
If a keyword DATExxxx is present, and it matches the pattern "yyyy-mm-dd", it will be transformed to "dd/mm/yy", which makes the file non-Y2K compliant. This might help you getting by some old readers. Highly discouraged of course.
DECORDER
If the keyword DECORDER is present, and it has a value T, it will replace this keyword by a COMMENT and set a flag such that of all data the bytes are byte swapped when read (or copied) according to abs(BITPIX).
IRAF0
Replace the FITS keyword HISTORY by COMMENT. This has been proven useful to be able to see al that information by the iraf program imhead.
PROMOTE
Replace the first FITS keyword XTENSION with SIMPLE = T, so an extension is promoted to become the primary HDU. Of course this only makes sense if you are extracting single HDUs, e.g. via the hdu= or split=t options.

Processing Order

With all the possible editing capabilities, it is important to know the processing order:
        select the valid HDU’s, 0=all (hdu=)
        delete header items by pattern matching (delete=)
        keep header items by pattern matching (keep=)
        insert new header items before the END card (insert=)
        fix header items (in order of individual fix= components)

Examples

To extract the header in a pleasing manner, such that more(1) can be used, one can use:
    % scanfits in=junk.fits out=junk.header fix=LF select=header
or
    % fitshead junk.fits  > junk.header
where the latter example does not contain trailing blanks anymore.

See Also

ccdfits(1NEMO) , dd(1) , fits(5NEMO) , fitshead(1NEMO) , astfits(1)


https://heasarc.gsfc.nasa.gov/fitsio/
https://fits.gsfc.nasa.gov/fits_verify.html
https://www.gnu.org/software/gnuastro/manual/html_node/Keyword-manipulation.html

Author

Peter Teuben

Files


~/src/image/fits         scanfits.c

Update History


27-mar-90    V1.0 Written                         PJT
17-jul-90    V1.1 added fix=, blank=                PJT
 7-mar-91    V1.3 added split=,keep=, and TUSCON     PJT
25-jul-91    V1.4 added the IRAF0 fix - blocking      PJT
30-jul-91    V1.4b added Jeff Hesters brilliant DECORDER fix      PJT
11-apr-92    V1.5 changed name of file= to hdu=    PJT
7-aug-92       fixed ctype/ttype bugs in fits(3NEMO)    PJT
13-jan-93        V1.7 insert= now implemented Arie!    PJT
2-dec-98    V1.8 fix=PROMOTE for lgm’s nicmos     PJT
15-oct-99    V1.8b fix=UNY2K (and Y2K)for Staguhn’s GILDAS      pjt
23-dec-21    fixed -u flag for date    PJT


Table of Contents