HTML automatically generated with rman
Table of Contents
scanfits - scan a fits file, optionally extract and convert.
scanfits
in=fits_file [parameter=value]
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 suite is now also providing a FITS checker
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].
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.
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)
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.
ccdfits(1NEMO)
,
dd(1)
, fits(5NEMO)
, fitshead(1NEMO)
https://heasarc.gsfc.nasa.gov/fitsio/
https://fits.gsfc.nasa.gov/fits_verify.html
Peter Teuben
~/src/image/fits scanfits.c
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