Commit 842ac848 authored by Ole Streicher's avatar Ole Streicher

Initial upstream files

parents
Installation of the FITSUTIL external package
--------------------------------------------------
[1] The package is distributed as a compressed tar archive.
% ftp 140.252.1.1
login: anonymous
password: [your last name]
ftp> cd iraf/extern
ftp> get fitsutil.readme
ftp> binary
ftp> get fitsutil.tar.Z
ftp> quit
% uncompress fitsutil.tar
The readme.fitsutil file contains these instructions.
[2] Create a directory to contain the FITSUTIL external package files. This
directory should be outside the IRAF directory tree and must be owned
by the IRAF account. In the following examples, this root directory
is named usr1:[fitsutil] (VMS) or /local/fitsutil/ (UNIX). Make the
appropriate file name substitutions for your site.
[3] Log in as IRAF and edit the extern.pkg file in the hlib directory to
define the package to the CL. From the IRAF account, outside the CL,
you can move to this directory with the commands:
$ set def irafhlib # VMS example
% cd $hlib # UNIX example
Define the environment variable fitsutil to be the pathname to the fitsutil
root directory. The '$' character must be escaped in the VMS pathname;
UNIX pathnames must be terminated with a '/'. Edit extern.pkg to include:
reset fitsutil = usr\$1:[fitsutil] # VMS example
reset fitsutil = /local/fitsutil/ # UNIX example
task fitsutil.pkg = fitsutil$fitsutil.cl
Near the end of the hlib$extern.pkg file, update the definition of helpdb
so it includes the fitsutil help database, copying the syntax already used
in the string. Add this line before the line containing a closing quote:
,fitsutil$lib/helpdb.mip\
[4] Log into the CL from the IRAF account and unpack the archive file. Change
directories to the FITSUTIL root directory created above and use 'rtar':
cl> cd fitsutil
cl> softools
cl> rtar -xrf <archive> where <archive> is the host name of the
archive file or the IRAF tape
device for tape distributions.
On VMS systems, an error message will appear ("Copy 'bin.generic' to
'./bin fails") which can be ignored. Also on VMS systems, the four
bin.'mach' directories created by rtar under [newimred.bin] can be
deleted. UNIX sites should leave the symbolic link 'bin' in the FITSUTIL
root directory pointing to 'bin.generic' but can delete any of the
bin.`mach' directories that won't be used. The archive file can be
deleted once the package has been successfully installed.
[5] When the archive has been unpacked, build the FITSUTIL package executable.
The compilation and linking of the FITSUTIL package is done using the
following command:
cl> mkpkg -p fitsutil update >& fitsutil.spool &
NOTE: On systems that concurrently support different architectures
(e.g., Suns, Convex), you must configure the system for the desired
architecture before issuing the above command. SUN/IRAF sites must
execute a pair of 'mkpkg' commands for each supported architecture type.
The Unix environment variable IRAFARCH must be set as well before
compiling. For example:
# Assuming IRAFARCH is set to ffpa
cl> mkpkg -p fitsutil ffpa
cl> mkpkg -p fitsutil update >& fitsutil.ffpa &
cl> mkpkg -p fitsutil f68881
# Now reset IRAFARCH to f68881 before continuing
cl> mkpkg -p fitsutil update >& fitsutil.f68881 &
The spool file(s) should be reviewed upon completion to make sure there
were no errors.
bin.generic
\ No newline at end of file
MEF INTERFACE
The Multiple Extensions FITS (MEF) interface consist of a number
of routines to mainly read a FITS Primary Data Unit or an Extension
Unit and manipulate the data at a file level. Is up to the application
to take care of any details regarding data structuring and manipulation.
For example, the MEF interface will read a BINTABLE extension and give to
the calling program a set of parameters like dimensionality, datatype, header
buffer pointer and data portion offset from the beginning of the file.
So far the routines available to an SPP program are:
mef = mef_open (fitsfile, acmode, oldp)
mef_rdhdr (mef, group, extname, extver)
mef_rdhdr_exnv (mef,extname, extver)
mef_wrhdr (mefi, mefo, in_phdu)
[irdb]val = mefget[irdb] (mef, keyword)
mefgstr (mef, keyword, outstr, maxch)
mef_app_file (mefi, mefo)
mef_copy_extn (mefi, mefo, group)
mef_dummyhdr (fd, hdrfname)
INITIALIZE
mef = mef_open (fitsfile, acmode, oldp)
Initializes the MEF interface and it should be the
first routine to be called when making operations on FITS files
using these set of routines. Returns a pointer to the mef structure.
fitsfile.
Pathname to the FITS file to be open. The general syntax is:
dir$root.extn[group]
dir: Directory name where the file resides
root: Rootname
extn: (optional) Extension name. Can be any extension string
group: Extension number to be openned.
The '[group]' string is optional and is not part of the disk
filename. It is used to specified which extension number to
open. The extension number is zero based. Zero for the primary
extension, 1 for the first extension and so on.
acmode.
The access mode of the file. The posible values are:
READ_ONLY
READ_WRITE
APPEND
NEW_FILE
oldp.
Not used. Reserve for future use.
HEADER ROUTINES
mef_rdhdr (mef, group, extname, extver)
Read the FITS header on a MEF file that matches the EXTNAME or
EXTVER keyword values or if not specified, reads the extension
number 'group'. If no extension is found an error is posted.
After reading the header the file pointer is position at the end
of the last data FITS block (2880 bytes).
mef.
The Mef pointer returned by mef_open. When the routine returns, all of
the elements of the MEF structure will have values belonging
to the header just read.
group.
The extension number to be read. Zero for the Primary data unit,
1 for the first extension and so on. If you want to find out an
extension by the value of extname and/or extver then 'group'
should be -1.
extname.
The string that will match the EXTNAME value of any extension. The
first match is the extension header returned.
extver.
The integer value that will match the EXTVER value of any extension.
If 'extname' is not null then both values need to match before
the routine returns. If there are no value to match then 'extver'
should be INDEFL.
mef_rdhdr_gn (mef,group)
Read extension number 'group'. If the extension number does not
exists, an error is posted.
mef.
The Mef pointer returned by mef_open. When the routine returns, all of
the elements of the MEF structure will have values belonging
to the header just read.
group.
The extension number to be read. Zero for the Primary data unit,
1 for the first extension and so on.
mef_rdhdr_exnv (mef,extname, extver)
Read group based on the Extname and Extver values. If the group
is not encountered, an error is posted.
mef.
The Mef pointer returned by mef_open. When the routine returns, all of
the elements of the MEF structure will have values belonging
to the header just read.
extname.
The string that will match the EXTNAME value of any extension. The
first match is the extension header returned.
extver.
The integer value that will match the EXTVER value of any extension.
If 'extname' is not null then both values need to match before
the routine returns. If there are no value to match then 'extver'
should be INDEFL.
mef_wrhdr (mefi, mefo, in_phdu)
Append the header from an input PHU or EHU to output file.
'mefi'.
The input file mef pointer returned by mef_open. The header
should have been read by now.
'mefo'.
The output file mef pointer returned by mef_open.
'in_phdu'.
Boolean value (true, false) stating whether the input header
is the primary header or not.
[irdb]val = mefget[irdb] (mef, keyword)
[irdb]: integer, real, double or boolean
Get a FITS header keyword value of the specified datatype; for
example 'imgeti (mef, "NCOMB")' will return an integer value
from the keyword 'NCOMB'.
'mef'.
The input file mef pointer returned by mef_open. The header
should have been read by now.
'keyword'
The input string (case insensitive) keyword from which to return
its value.
mefgstr (mef, keyword, outstr, maxch)
char card[ARB] #I FITS card to be decoded
char outstr[ARB] #O output string to receive parameter value
int maxch #I length of outstr
Get the string value of a FITS encoded card. Strip leading
and trailing whitespace and any quotes.
'mef'.
The input file mef pointer returned by mef_open. The header
should have been read by now.
'keyword'
The input string (case insensitive) keyword from which to return
its value.
'outstr'
The output string with the value of input keyword.
'maxch'
Lenght in chars of 'outstr'.
FILE OPERATIONS
mef_app_file (mefi, mefo)
Appends a FITS file to an output file. If the file does
not exist, a dummy Primary Header unit is first created.
'mefi'.
The input file mef pointer returned by mef_open. The header
should have been read by now.
'mefo'.
The output file mef pointer returned by mef_open.
mef_copy_extn (mefi, mefo, group)
Copy a FITS extension given by its number 'group' into an
output file. If the file does not exists, this extension becames
a Primary Header Data unit of the output FITS file. If the
output file already exists, the input extension gets appended.
'mefi'.
The input file mef pointer returned by mef_open. The header
should have been read by now.
'mefo'.
The output file mef pointer returned by mef_open.
'group'.
The input extension number to be append to the output file.
mef_dummyhdr (fd, hdrfname)
Write a dummy Primary header Unit with no data to a new file.
Optionaly a header file with user keywords can be used.
'fd'
The output file descriptor.
'hdrfname'
The header filename. This is text file with a FITS header syntax
that will be appended to the file. Each FITS card does not have to
be of 80 characters long. The routine takes care of the correct
padding.
Multiple Extension FITS files. August 1997
The MEF interface is a set of routines to manipulate single FITS files
or Multiple Extensions FITS files. This interface complies with the
FITS standard set by the NOST document.
The MEF interface is an IRAF interface intended to be used within an SPP
or Fortran program with the proper IRAF initialization routines.
The user callable routines are:
mef_open (filename, acmode, ofd)
Integer procedure returning a pointer to the MEF structure.
'filename'. Pathname to the target FITS filename. Pathname
consist of
ldir$rootname.extn[group]
ldir: Logical directory
root: Rootname of the filename
extn: (Optional) FITS filename extension.
group: (Optional) The FITS extension number. Zero correspond
to the the Primary Header Unit, 1 to the first
extension on so on. If you specify group, the '[]' are
required.
'acmode'. Access mode of the target file. It could READ_ONLY,
READ_WRITE, NEW_FILE or APPEND.
'ofd'. Not used at the moment. Reserve for future use.
mef = mef_open (filename, acmode, ofd|hsize)
The MEF structure pointed by 'mef' consists of the following
elements:
MEF_FD # File descriptor
MEF_HOFF # Header offset in chars
MEF_ACMODE # Access mode
MEF_ENUMBER # Absolute extension number
MEF_EXTVER # EXTVER keyword value
MEF_CGROUP # Current group read
MEF_HSIZE # Header size
MEF_HDRP # Header area pointer
MEF_POFF # Offset to pixel area in chars
MEF_NDIM # Unit dimensionality
MEF_NAXIS # Lenght of each exis
MEF_BITPIX # Value of BITPIX
MEF_EXTTYPE # XTENSION keyword value
MEF_FNAME # Filename
MEF_OBJECT # OBJECT keyword value
MEF_EXTNAME # EXTNAME keyword value
mef_close
mef_close (mef)
Free the memory allocated by mef_open and close the target
FITS file.
mef_query
mef_query (filename, ext_type, datatype, object)
Mefopen already does this, the difference would be for example
that mef_query would just returns its argument values. No need to
open and close.
Another approach is to open the file, and mef_query would just
return and value per request, for example
mef_stati
val = mef_stati (mef, "EXT_TYPE")
to get the value of a mef descriptor element.
mef_delete
Make a temporary copy of file and copy the rest of the
extensions. Delete the old one.
mef_delete (mef)
mef_rename
Considering that an extension is a portion of a file, renaming
would be limited to change the names of the EXTNAME and/or EXTVER
values. No extractions to a different filename would be allowed.
mef_rename (in_mef, oldname, new_name, unique(YES|NO))
Does the new_name need to be unique?
mef_extract
Make a copy of an extension into a new or existent file.
mef_extract (file.fits[4], output_file, new|append)
mef_insert
Insert an extension after an existent one. Again a temporary file
would be necessary to preserve the integrity of the target file.
mef_insert (in_mef, out_mef, out_extn)
mef_overwrite
This would equivalent to delete an insert but only one temporary
file would be necessary.
mef_overwrite (in_mef, out_mef, out_extn)
gethdkw
Get keyword value, e.g.
real = gethdkwr (mef, keyword)
val = gethdkw[bsird] (mef, keyword)
call gethdkwstring (mef, keyword, buf, max_size)
puthdkw
Put keyword value (new or update value), e.g.
call puthdkw[bsird] (mef, keyword, value, comment)
call puthdkwstring (mef, keyword, value, max_size, comment)
#{ FITSUTIL.CL -- The FITSUTIL package
print ("This is the initial release of the IRAF FITSUTIL package")
print ("to include support for FITS tile compression via 'fpack'.")
print ("Please send comments and questions to seaman@noao.edu.")
print ("")
cl < "fitsutil$/lib/zzsetenv.def"
package fitsutil, bin = fitsutilbin$
task fxheader,
fxdummyh,
fxinsert,
fxdelete,
fxextract,
fxsplit,
fxconvert,
fxplf,
fxcopy = "fitsutil$src/x_fitsutil.e"
task ricepack = "fitsutil$src/ricepack.cl"
task fpack = "fitsutil$src/fpack.cl"
task funpack = "fitsutil$src/funpack.cl"
task sum32 = "fitsutil$src/sum32.cl"
task $t_fpack = ("$" // osfn("fitsutilbin$") // "fpack")
task $t_funpack = ("$" // osfn("fitsutilbin$") // "funpack")
task $t_sum32 = ("$" // osfn("fitsutilbin$") // "sum32")
hidetask t_fpack
hidetask t_funpack
hidetask t_sum32
task fgwrite = "fitsutil$src/fgwrite.cl"
task fgread = "fitsutil$src/fgread.cl"
task $t_fgwrite = ("$" // osfn("fitsutilbin$") // "fgwrite.e $*")
task $t_fgread = ("$" // osfn("fitsutilbin$") // "fgread.e $*")
hidetask t_fgwrite
hidetask t_fgread
clbye()
;
# Help directory for the FITSUTIL package.
$doc = "fitsutil$src/doc/"
$srcdir = "fitsutil$src/"
fitsutil hlp="fitsutil$fitsutil.men"
fxcopy hlp=doc$fxcopy.hlp, src=srcdir$fxcopy.x
fxconvert hlp=doc$fxconvert.hlp, src=srcdir$fxconvert.x
fxdelete hlp=doc$fxdelete.hlp, src=srcdir$fxdelete.x
fxinsert hlp=doc$fxinsert.hlp, src=srcdir$fxinsert.x
fxheader hlp=doc$fxheader.hlp, src=srcdir$fxheader.x
fxextract hlp=doc$fxextract.hlp, src=srcdir$fxextract.x
fxsplit hlp=doc$fxsplit.hlp, src=srcdir$fxsplit.x
fxdummyh hlp=doc$fxdummyh.hlp, src=srcdir$fxdummyh.x
fxplf hlp=doc$fxplf.hlp, src=srcdir$fxplf.x
fpack hlp=doc$fpack.hlp, src=srcdir$fpack.cl
funpack hlp=doc$funpack.hlp, src=srcdir$funpack.cl
ricepack hlp=doc$ricepack.hlp, src=srcdir$ricepack.cl
sum32 hlp=doc$sum32.hlp, src=srcdir$sum32.cl
fgwrite hlp=doc$fgwrite.hlp, src=srcdir$fgwrite.c
fgread hlp=doc$fgread.hlp, src=srcdir$fgread.c
fgread - Read a MEF file with FOREIGN extensions
fgwrite - Create a MEF file with FOREIGN extensions
fpack - USE RICEPACK INSTEAD
funpack - Uncompress a FITS file
fxconvert- Convert between IRAF image types.
fxcopy - Copy FITS files or FITS extension to an output FITS file
fxdelete - Delete FITS extensions in place
fxdummyh - Create a dataless single FITS file
fxextract- Extract a FITS extension
fxheader - List one line of header description per FITS unit
fxinsert - Insert FITS files or extensions into another MEF file
fxplf - Converts a pixel list file into a BINTABLE extension
fxsplit - Split a multiple extension FITS file into single FITS files
ricepack - Rice compress a FITS file
sum32 - Compute the 32-bit FITS 1's complement checksum
The CFITSIO fpack command (http://heasarc.gsfc.nasa.gov/fitsio/fpack)
is a general purpose tool that allows varying many compression options
when creating tile compressed FITS files. It is anticipated, however,
that the great majority of astronomical usage will involve the Rice
algorithm. This release of IRAF FITSUTIL is focused on providing
streamlined access to this functionality through the RICEPACK task.
Please contact seaman@noao.edu with comments and questions.
# fitsutil package parameter file.
version,s,h,"3Jan2010"
Fitsutil. This package is under development. Any comments can be sent to
fits@noao.edu and they are appreciated.
EXT# -5.5
EXTTYPE -19.19
EXTNAME -13.13
EXTVER -5.5
DIMENS -10.10
BITPIX -5.5
INHERIT -3.3
OBJECT -12.12
EXT# -5.5
EXTTYPE -9.9
EXTNAME -11.11
EXTVER -5.5
DIMENS -10.10
BITPIX -5.5
INHERIT -3.3
HOFF -9.9
POFF -9.9
File added
../bin/libcfitsio.a
\ No newline at end of file
../bin/libmef.a
\ No newline at end of file
define LEN_CARD 80
define SZ_EXTTYPE 20
define LEN_CARDNL 81
define SZ_KEYWORD 8
define FITS_STARTVALUE 10
define FITS_ENDVALUE 30
define FITS_BLKSZ_CHAR 1440 # Number of chars per FITS block
define FITS_BLKSZ_NL 2916 # 36*81
define FITS_BLOCK_BYTES 2880
define MEF_SZVALSTR 68
define FITS_ORIGIN "NOAO-IRAF FITS MEF utility Sep99"
define LEN_MEF 271
define MEF_FD Memi[$1] # File descriptor
define MEF_HOFF Memi[$1+2] # Header offset in chars
define MEF_ACMODE Memi[$1+3] # Access mode
define MEF_ENUMBER Memi[$1+4] # Absolute extension number
define MEF_EXTVER Memi[$1+5] # Extension version
define MEF_CGROUP Memi[$1+6] # Current group read
define MEF_HFLAG Memi[$1+7] # Header update flag
define MEF_HSIZE Memi[$1+8] # Header size
define MEF_HDRP Memi[$1+9] # Header area pointer
define MEF_POFF Memi[$1+10] # Offset to pixel area (chars)
define MEF_NDIM Memi[$1+11] # Unit dimensionality
define MEF_NAXIS Memi[$1+$2+12-1] # Upto 7 axis
define MEF_BITPIX Memi[$1+18] # Unit datatype
define MEF_DATATYPE Memi[$1+19] # Unit datatype
define MEF_SKDATA Memi[$1+20] # Has data been skipped?
define MEF_PCOUNT Memi[$1+21] # Has data been skipped?
define MEF_KEEPXT Memi[$1+22] # Has data been skipped?
define MEF_EXTTYPE Memc[P2C($1+23)] # Extension type
define MEF_FNAME Memc[P2C($1+63)] # Filename
define MEF_OBJECT Memc[P2C($1+191)] # Object
define MEF_EXTNAME Memc[P2C($1+231)] # Extension name
define NEW_UNIT NEW_FILE
define SIMPLE 1
define NAXIS 2
define NAXISN 3
define EXTNAME 4
define EXTVER 5
define END 6
define BITPIX 7
define EXTEND 8
define OBJECT 9
define PCOUNT 10
define GCOUNT 11
define INHERIT 12
define FILENAME 13
define XTENSION 14
mefwrhdr.x
Previuolsy we changed the value of INHERIT to NO. Now we pass
the card to the output file unchanged with the exception when
the output file is new, then we do not pass it along. 3/4/98
mefrdhdr.x
When a kernel section is given in the input file, it is
necessary to read the entire header in memory rather
than the 1st block. An error was found trying to get EXTNAME
value when the keyword was not located in the 1st block.
nz 10/2/03
mefldhdr.x
New routine to read the entire header in memory. 10.02.03
==================================================
mefrdhdr.x
Change mef_rdhdr...() to be a function now rather than a
procedure. This way we can return and EOF value to the
calling routine.
revised. Used mef_ldhdr() now and discard rd1st and rd2end.
Took out any eprintf statement and made the code much simpler.
Jan.7.04
include <mef.h>
# MEFFAPPFILE.X -- Set of routines to append a FITS units to an FITS file.
# meff_app_file(mefi, mefo)
# mef_pakwr (out, card)
# mef_wrpgcount (out)
# mef_wrblank (out, nlines)
# MEF_APP_FILE -- Append a FITS file to an existant file. This means the
# first input unit needs to be changed from a Primary to an Extension Unit.
procedure mef_app_file (mefi, mefo)
pointer mefi #I input mef descriptor
pointer mefo #O output mef descriptor
char dname[1]
int off, status
bool in_phdu
int access(), mef_rdhdr_gn()
errchk mef_rdhdr_gn
begin
# If output file does not exist create a dummy extension
if (access(MEF_FNAME(mefo), 0,0) == NO) {
dname[1] = EOS
call mef_dummyhdr (MEF_FD(mefo),dname)
MEF_ACMODE(mefo) = APPEND
}
in_phdu = true # The input file has a PHDU
# Read the first input header unit (PHDU) and change to extension
# unit while writing to output file.
status = mef_rdhdr_gn (mefi,0)
if (status == EOF)
call error (13, "EOF encountered on input file")
call mef_wrhdr (mefi, mefo, in_phdu)
# Check for dataless unit; if so the data pointer is at the
# end of the last header block.
if (MEF_POFF(mefi) == INDEFI)
off = MEF_HOFF(mefi) + ((MEF_HSIZE(mefi)+2879)/2880)*1440
else
off = MEF_POFF(mefi)
# Now copy the data
call seek (MEF_FD(mefi), off)
call fcopyo (MEF_FD(mefi), MEF_FD(mefo))
end
# MEF_PAKWR -- Pack a character buffer and write to the output buffer.
procedure mef_pakwr (out, card)
int out #I Output file descriptor
char card[ARB] #I Input FITS card
begin
call achtcb (card, card, 80)
call write(out, card, 40)
end
# MEF_WRPGCOUNT -- Write PCOUNT and GCOUNT to the output buffer.
procedure mef_wrpgcount (out)
int out #I file descriptor
char line[80]
begin
call mef_encodei ("PCOUNT", 0, line, "No 'random' parameters")
call mef_pakwr (out, line)
call mef_encodei ("GCOUNT", 1, line, "Only one group")
call mef_pakwr (out, line)
end
# MEF_WRBLANK -- Write a number of blank lines into the output buffer.
# we reach the END card in the 1st block but we run out