uk.ac.starlink.ast
Class FitsChan
java.lang.Object
uk.ac.starlink.ast.AstObject
uk.ac.starlink.ast.Channel
uk.ac.starlink.ast.FitsChan
public class FitsChan
- extends Channel
Java interface to the AST FitsChan class
- I/O Channel using FITS header cards to represent Objects.
A FitsChan is a specialised form of Channel which supports I/O
operations involving the use of FITS (Flexible Image Transport
System) header cards. Writing an Object to a FitsChan (using
astWrite) will, if the Object is suitable, generate a
description of that Object composed of FITS header cards, and
reading from a FitsChan will create a new Object from its FITS
header card description.
While a FitsChan is active, it represents a buffer which may
contain zero or more 80-character "header cards" conforming to
FITS conventions. Any sequence of FITS-conforming header cards
may be stored, apart from the "END" card whose existence is
merely implied. The cards may be accessed in any order by using
the FitsChan's integer Card attribute, which identifies a "current"
card, to which subsequent operations apply. Searches
based on keyword may be performed (using astFindFits), new
cards may be inserted (astPutFits, astPutCards, astSetFits) and
existing ones may be deleted (astDelFits), extracted (astGetFits),
or changed (astSetFits).
When you create a FitsChan, you have the option of specifying
"source" and "sink" functions which connect it to external data
stores by reading and writing FITS header cards. If you provide
a source function, it is used to fill the FitsChan with header cards
when it is accessed for the first time. If you do not provide a
source function, the FitsChan remains empty until you explicitly enter
data into it (e.g. using astPutFits, astPutCards, astWrite
or by using the SourceFile attribute to specifying a text file from
which headers should be read). When the FitsChan is deleted, any
remaining header cards in the FitsChan can be saved in either of
two ways: 1) by specifying a value for the SinkFile attribute (the
name of a text file to which header cards should be written), or 2)
by providing a sink function (used to to deliver header cards to an
external data store). If you do not provide a sink function or a
value for SinkFile, any header cards remaining when the FitsChan
is deleted will be lost, so you should arrange to extract them
first if necessary
(e.g. using astFindFits or astRead).
Coordinate system information may be described using FITS header
cards using several different conventions, termed
"encodings". When an AST Object is written to (or read from) a
FitsChan, the value of the FitsChan's Encoding attribute
determines how the Object is converted to (or from) a
description involving FITS header cards. In general, different
encodings will result in different sets of header cards to
describe the same Object. Examples of encodings include the DSS
encoding (based on conventions used by the STScI Digitised Sky
Survey data), the FITS-WCS encoding (based on a proposed FITS
standard) and the NATIVE encoding (a near loss-less way of
storing AST Objects in FITS headers).
The available encodings differ in the range of Objects they can
represent, in the number of Object descriptions that can coexist
in the same FitsChan, and in their accessibility to other
(external) astronomy applications (see the Encoding attribute
for details). Encodings are not necessarily mutually exclusive
and it may sometimes be possible to describe the same Object in
several ways within a particular set of FITS header cards by
using several different encodings.
The detailed behaviour of astRead and astWrite, when used with
a FitsChan, depends on the encoding in use. In general, however,
all successful use of astRead is destructive, so that FITS header cards
are consumed in the process of reading an Object, and are
removed from the FitsChan (this deletion can be prevented for
specific cards by calling the
astRetainFits function).
An unsuccessful call of
astRead
(for instance, caused by the FitsChan not containing the necessary
FITS headers cards needed to create an Object) results in the
contents of the FitsChan being left unchanged.
If the encoding in use allows only a single Object description
to be stored in a FitsChan (e.g. the DSS, FITS-WCS and FITS-IRAF
encodings), then write operations using astWrite will
over-write any existing Object description using that
encoding. Otherwise (e.g. the NATIVE encoding), multiple Object
descriptions are written sequentially and may later be read
back in the same sequence.
Licence
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public Licence as
published by the Free Software Foundation; either version 2 of
the Licence, or (at your option) any later version.
This program is distributed in the hope that it will be
useful,but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE. See the GNU General Public Licence for more details.
You should have received a copy of the GNU General Public Licence
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street,Fifth Floor, Boston, MA
02110-1301, USA
Usage
The FitsChan implemented by this class can be used as a buffer for
FITS header cards, but it neither reads from nor writes to an
external source. To make a more useful object, subclass this
class and override the source
and/or sink
methods. Note that output is only guaranteed to get written
if the close
method is explicitly called.
The close
method should be explicitly called to ensure
cleanup, but the finalizer will call it if it has not previously been
called at finalization time.
- See Also:
- AST FitsChan
Constructor Summary |
FitsChan()
Creates a new FitsChan which can be used as a buffer for
FITS objects, but will not read or write header cards. |
FitsChan(Iterator cardIt)
Creates a new FitsChan whose initial contents will be a sequence of
FITS header cards obtained from an Iterator. |
Method Summary |
void |
close()
Must be called to dispose of the object and ensure that any
writes are performed. |
void |
delFits()
Delete the current FITS card in a FitsChan. |
protected void |
finalize()
Finalizes the object. |
String |
findFits(String name,
boolean inc)
Find a FITS card in a FitsChan by keyword. |
String |
getAllWarnings()
Get
a list of all currently available condition names. |
int |
getCard()
Get
index of current FITS card in a FitsChan. |
boolean |
getCarLin()
Get
ignore spherical rotations on CAR projections. |
boolean |
getCDMatrix()
Get
use CDi_j keywords to represent pixel scaling, rotation, etc. |
boolean |
getDefB1950()
Get
use FK4 B1950 as defaults. |
String |
getEncoding()
Get
system for encoding Objects as FITS headers. |
int |
getFitsDigits()
Get
digits of precision for floating point FITS values. |
boolean |
getIwc()
Get
include a Frame representing FITS-WCS intermediate world coordinates. |
int |
getNcard()
Get
number of FITS header cards in a FitsChan. |
String |
getWarnings()
Get
controls the issuing of warnings about various conditions. |
Iterator |
iterator()
Returns an iterator over the header cards currently in this FitsChan. |
void |
purgeWCS()
Delete all cards in the FitsChan describing WCS information. |
void |
putCards(String cards)
Store a set of FITS header cards in a FitsChan. |
void |
putFits(String card,
boolean overwrite)
Store a FITS header card in a FitsChan. |
AstObject |
read()
Reads an AST object from this FitsChan. |
void |
retainFits()
Indicate that the current card in a FitsChan should be retained. |
void |
setCard(int card)
Set
index of current FITS card in a FitsChan. |
void |
setCarLin(boolean carLin)
Set
ignore spherical rotations on CAR projections. |
void |
setCDMatrix(boolean CDMatrix)
Set
use CDi_j keywords to represent pixel scaling, rotation, etc. |
void |
setDefB1950(boolean defB1950)
Set
use FK4 B1950 as defaults. |
void |
setEncoding(String encoding)
Set
system for encoding Objects as FITS headers. |
void |
setFits(String name,
boolean value,
String comment,
boolean overwrite)
Stores a boolean value for a named keyword within this
FitsChan at the current card position. |
void |
setFits(String name,
double rval,
double ival,
String comment,
boolean overwrite)
Stores a double complex value for a named keyword within this
FitsChan at the current card position. |
void |
setFits(String name,
double value,
String comment,
boolean overwrite)
Stores a double value for a named keyword within this
FitsChan at the current card position. |
void |
setFits(String name,
int rval,
int ival,
String comment,
boolean overwrite)
Stores an integer complex value for a named keyword within this
FitsChan at the current card position. |
void |
setFits(String name,
int value,
String comment,
boolean overwrite)
Stores an integer value for a named keyword within this
FitsChan at the current card position. |
void |
setFits(String name,
String value,
String comment,
boolean overwrite)
Stores a String value for a named keyword within this
FitsChan at the current card position. |
void |
setFitsContinue(String name,
String value,
String comment,
boolean overwrite)
Stores a CONTINUE type value for a named keyword
FitsChan at the current card position. |
void |
setFitsDigits(int fitsDigits)
Set
digits of precision for floating point FITS values. |
void |
setIwc(boolean iwc)
Set
include a Frame representing FITS-WCS intermediate world coordinates. |
void |
setWarnings(String warnings)
Set
controls the issuing of warnings about various conditions. |
protected void |
sink(String line)
Disposes of a line of output. |
protected String |
source()
Obtains a line of input. |
boolean |
testFits(String name)
See if a named keyword has a defined value in a FitsChan. |
int |
write(AstObject obj)
Writes an AST object to this channel. |
Methods inherited from class uk.ac.starlink.ast.Channel |
copy, getComment, getFull, getReportLevel, getSkip, getStrict, setComment, setFull, setReportLevel, setSkip, setStrict, warnings |
Methods inherited from class uk.ac.starlink.ast.AstObject |
annul, clear, delete, equals, getAstConstantI, getB, getC, getD, getF, getI, getID, getIdent, getL, getNobject, getObjSize, getRefCount, hashCode, isThreaded, reportVersions, sameObject, set, setB, setC, setD, setF, setI, setID, setIdent, setL, show, test, tune |
FitsChan
public FitsChan(Iterator cardIt)
- Creates a new FitsChan whose initial contents will be a sequence of
FITS header cards obtained from an Iterator.
- Parameters:
cardIt
- an Iterator which should supply Strings giving the
channel's initial content. Only the first 80
characters of each supplied string are significant.
This parameter may be supplied null in the case of
no initial content.
FitsChan
public FitsChan()
- Creates a new FitsChan which can be used as a buffer for
FITS objects, but will not read or write header cards.
iterator
public Iterator iterator()
- Returns an iterator over the header cards currently in this FitsChan.
Each object returned from the Iterator's
next
method
will be an 80-character String. The Iterator's remove
method can be used to delete cards from the underlying channel.
The iterator should not be used while the FitsChan is being
written to.
This method is a convenience wrapper which uses findFits
and delFits
to do the work.
- Returns:
- an Iterator which retrieves each line from the FitsChan in turn
sink
protected void sink(String line)
throws IOException
- Disposes of a line of output. This method is invoked repeatedly
when the
close
method of this FitsChan is called
(either explicitly or under control of the garbage collector)
to dispose of each FITS header card currently in the channel.
The FitsChan
implementation simply discards each
line, but it may be overridden by subclasses to output the header
cards in a useful way. The method may throw an IOException in case
of error.
- Overrides:
sink
in class Channel
- Parameters:
line
- an 80-character string giving the contents of one
FITS header card. This method discards it.
- Throws:
IOException
- if a write error is encountered
source
protected final String source()
- Obtains a line of input. This method is invoked repeatedly during
construction of this FitsChan to obtain its initial contents.
On each call it returns the text of the next FITS header card
if there is one, and
null
if there are no more.
The FitsChan
implementation uses the Iterator
supplied in the constructor to obtain the lines of text.
It is declared final to prevent subclasses overriding it -
algthough in principle it could work, this practice would be
fraught with difficulty since the method is called by the
FitsChan constructor before the subclassed object has been
properly constucted, so it is likely to be in an inconsistent state.
- Overrides:
source
in class Channel
- Returns:
- a line of text read from the input stream, as a
String
. If the end of the stream has been
reached, null
is returned.
finalize
protected void finalize()
throws Throwable
- Description copied from class:
Channel
- Finalizes the object. Certain resources allocated by the native
code are freed, and the finalizer of the superclass is called.
- Overrides:
finalize
in class Channel
- Throws:
Throwable
close
public void close()
- Must be called to dispose of the object and ensure that any
writes are performed.
When this method is called, either explicitly
or by the finalizer, the
sink
method will be invoked to write out any content of this
FitsChan
.
read
public AstObject read()
- Reads an AST object from this FitsChan.
- Overrides:
read
in class Channel
- Returns:
- the
AstObject
which has been read.
null
is returned, without error, if no
further objects remain to be read on the stream
- Throws:
AstException
- if an error occurs in the AST library
write
public int write(AstObject obj)
- Writes an AST object to this channel.
- Overrides:
write
in class Channel
- Parameters:
obj
- an AstObject
to be written
- Returns:
- number of objects written (1 on success)
- Throws:
AstException
- if an error occurs in the AST library
setFits
public void setFits(String name,
double rval,
double ival,
String comment,
boolean overwrite)
- Stores a double complex value for a named keyword within this
FitsChan at the current card position.
The supplied keyword can either over-write an existing keyword
value, or can be inserted as a new header card.
- Parameters:
name
- FITS keyword name - may be a complete FITS header card,
in which case the keyword is extracted from it.
No more than 80 characters are readrval
- real part of the valueival
- imaginary part of the valuecomment
- comment associated with the keyword.
If null or a blank string is supplied,
then any comment present in name is used.
If name
contains no comment, then
any existing coment in the card being overwritten
is retained. Otherwise, no comment is stored.overwrite
- If true, the new card overwrites the current card,
and the Card
attribute is incremented.
If false, then new card is inserted in front of the
current card, and the current card is left unchanged.
In either case, if the current card on entry
points to end-of-file, the new card is appended
to the end of the list.
setFits
public void setFits(String name,
int rval,
int ival,
String comment,
boolean overwrite)
- Stores an integer complex value for a named keyword within this
FitsChan at the current card position.
The supplied keyword can either over-write an existing keyword
value, or can be inserted as a new header card.
- Parameters:
name
- FITS keyword name - may be a complete FITS header card,
in which case the keyword is extracted from it.
No more than 80 characters are readrval
- real part of the valueival
- imaginary part of the valuecomment
- comment associated with the keyword.
If null or a blank string is supplied,
then any comment present in name is used.
If name
contains no comment, then
any existing coment in the card being overwritten
is retained. Otherwise, no comment is stored.overwrite
- If true, the new card overwrites the current card,
and the Card
attribute is incremented.
If false, then new card is inserted in front of the
current card, and the current card is left unchanged.
In either case, if the current card on entry
points to end-of-file, the new card is appended
to the end of the list.
setFits
public void setFits(String name,
double value,
String comment,
boolean overwrite)
- Stores a double value for a named keyword within this
FitsChan at the current card position.
The supplied keyword can either over-write an existing keyword
value, or can be inserted as a new header card.
- Parameters:
name
- FITS keyword name - may be a complete FITS header card,
in which case the keyword is extracted from it.
No more than 80 characters are readvalue
- valuecomment
- comment associated with the keyword.
If null or a blank string is supplied,
then any comment present in name is used.
If name
contains no comment, then
any existing coment in the card being overwritten
is retained. Otherwise, no comment is stored.overwrite
- If true, the new card overwrites the current card,
and the Card
attribute is incremented.
If false, then new card is inserted in front of the
current card, and the current card is left unchanged.
In either case, if the current card on entry
points to end-of-file, the new card is appended
to the end of the list.
setFits
public void setFits(String name,
int value,
String comment,
boolean overwrite)
- Stores an integer value for a named keyword within this
FitsChan at the current card position.
The supplied keyword can either over-write an existing keyword
value, or can be inserted as a new header card.
- Parameters:
name
- FITS keyword name - may be a complete FITS header card,
in which case the keyword is extracted from it.
No more than 80 characters are readvalue
- valuecomment
- comment associated with the keyword.
If null or a blank string is supplied,
then any comment present in name is used.
If name
contains no comment, then
any existing coment in the card being overwritten
is retained. Otherwise, no comment is stored.overwrite
- If true, the new card overwrites the current card,
and the Card
attribute is incremented.
If false, then new card is inserted in front of the
current card, and the current card is left unchanged.
In either case, if the current card on entry
points to end-of-file, the new card is appended
to the end of the list.
setFits
public void setFits(String name,
boolean value,
String comment,
boolean overwrite)
- Stores a boolean value for a named keyword within this
FitsChan at the current card position.
The supplied keyword can either over-write an existing keyword
value, or can be inserted as a new header card.
- Parameters:
name
- FITS keyword name - may be a complete FITS header card,
in which case the keyword is extracted from it.
No more than 80 characters are readvalue
- valuecomment
- comment associated with the keyword.
If null or a blank string is supplied,
then any comment present in name is used.
If name
contains no comment, then
any existing coment in the card being overwritten
is retained. Otherwise, no comment is stored.overwrite
- If true, the new card overwrites the current card,
and the Card
attribute is incremented.
If false, then new card is inserted in front of the
current card, and the current card is left unchanged.
In either case, if the current card on entry
points to end-of-file, the new card is appended
to the end of the list.
setFits
public void setFits(String name,
String value,
String comment,
boolean overwrite)
- Stores a String value for a named keyword within this
FitsChan at the current card position.
The supplied keyword can either over-write an existing keyword
value, or can be inserted as a new header card.
- Parameters:
name
- FITS keyword name - may be a complete FITS header card,
in which case the keyword is extracted from it.
No more than 80 characters are readvalue
- valuecomment
- comment associated with the keyword.
If null or a blank string is supplied,
then any comment present in name is used.
If name
contains no comment, then
any existing coment in the card being overwritten
is retained. Otherwise, no comment is stored.overwrite
- If true, the new card overwrites the current card,
and the Card
attribute is incremented.
If false, then new card is inserted in front of the
current card, and the current card is left unchanged.
In either case, if the current card on entry
points to end-of-file, the new card is appended
to the end of the list.
setFitsContinue
public void setFitsContinue(String name,
String value,
String comment,
boolean overwrite)
- Stores a CONTINUE type value for a named keyword
FitsChan at the current card position.
These are treated like string values, but are encoded without
an equals sign.
The supplied keyword can either over-write an existing keyword
value, or can be inserted as a new header card.
- Parameters:
name
- FITS keyword name - may be a complete FITS header card,
in which case the keyword is extracted from it.
No more than 80 characters are readvalue
- valuecomment
- comment associated with the keyword.
If null or a blank string is supplied,
then any comment present in name is used.
If name
contains no comment, then
any existing coment in the card being overwritten
is retained. Otherwise, no comment is stored.overwrite
- If true, the new card overwrites the current card,
and the Card
attribute is incremented.
If false, then new card is inserted in front of the
current card, and the current card is left unchanged.
In either case, if the current card on entry
points to end-of-file, the new card is appended
to the end of the list.
delFits
public void delFits()
- Delete the current FITS card in a FitsChan.
This function deletes the current FITS card from a FitsChan. The
current card may be selected using the Card attribute (if its index
is known) or by using astFindFits (if only the FITS keyword is
known).
After deletion, the following card becomes the current card.
Notes
- This function returns without action if the FitsChan is
initially positioned at the "end-of-file" (i.e. if the Card
attribute exceeds the number of cards in the FitsChan).
- If there are no subsequent cards in the FitsChan, then the
Card attribute is left pointing at the "end-of-file" after
deletion (i.e. is set to one more than the number of cards in
the FitsChan).
- Throws:
AstException
- if an error occurred in the AST library
findFits
public String findFits(String name,
boolean inc)
- Find a FITS card in a FitsChan by keyword.
This function searches for a card in a FitsChan by keyword. The
search commences at the current card (identified by the Card
attribute) and ends when a card is found whose FITS keyword
matches the template supplied, or when the last card in the
FitsChan has been searched.
If the search is successful (i.e. a card is found which matches
the template), the contents of the card are (optionally)
returned and the Card attribute is adjusted to identify the card
found or, if required, the one following it. If the search is
not successful, the function returns zero and the Card attribute
is set to the "end-of-file".
Notes
- The search always starts with the current card, as identified
by the Card attribute. To ensure you search the entire contents
of a FitsChan, you should first clear the Card attribute (using
astClear). This effectively "rewinds" the FitsChan.
- If a search is unsuccessful, the Card attribute is set to the
"end-of-file" (i.e. to one more than the number of cards in the
FitsChan). No error occurs.
- A value of zero will be returned if this function is invoked
with the AST error status set, or if it should fail for any
reason.
Keyword Templates
The templates used to match FITS keywords are normally composed
of literal characters, which must match the keyword exactly
(apart from case). However, a template may also contain "field
specifiers" which can match a range of possible characters. This
allows you to search for keywords that contain (for example)
numbers, where the digits comprising the number are not known in
advance.
A field specifier starts with a "%" character. This is followed
by an optional single digit (0 to 9) specifying a field
width. Finally, there is a single character which specifies the
type of character to be matched, as follows:
- "c": matches all upper case letters,
- "d": matches all decimal digits,
- "f": matches all characters which are permitted within a FITS
keyword (upper case letters, digits, underscores and hyphens).
If the field width is omitted, the field specifier matches one
or more characters. If the field width is zero, it matches zero
or more characters. Otherwise, it matches exactly the number of
characters specified. In addition to this:
- The template "%f" will match a blank FITS keyword consisting
of 8 spaces (as well as matching all other keywords).
- A template consisting of 8 spaces will match a blank keyword
(only).
For example:
- The template "BitPix" will match the keyword "BITPIX" only.
- The template "crpix%1d" will match keywords consisting of
"CRPIX" followed by one decimal digit.
- The template "P%c" will match any keyword starting with "P"
and followed by one or more letters.
- The template "E%0f" will match any keyword beginning with "E".
- The template "%f" will match any keyword at all (including a
blank one).
- Parameters:
name
- Pointer to a null-terminated character string containing a
template for the keyword to be found. In the simplest case,
this should simply be the keyword name (the search is case
insensitive and trailing spaces are ignored). However, this
template may also contain "field specifiers" which are
capable of matching a range of characters (see the "Keyword
Templates" section for details). In this case, the first card
with a keyword which matches the template will be found. To
find the next FITS card regardless of its keyword, you should
use the template "%f".inc
- If this value is zero (and the search is successful), the
FitsChan's Card attribute will be set to the index of the card
that was found. If it is non-zero, however, the Card
attribute will be incremented to identify the card which
follows the one found.
- Returns:
- An array of at least 81 characters (to allow room for a
terminating null)
in which the FITS card which is found will be returned. If
the search is not successful (or a NULL pointer is given), a
card will not be returned.
- Throws:
AstException
- if an error occurred in the AST library
testFits
public boolean testFits(String name)
- See if a named keyword has a defined value in a FitsChan.
This function serches for a named keyword in a FitsChan. If found,
and if the keyword has a value associated with it, a
non-zero
value is returned. If the keyword is not found, or if it does not
have an associated value, a
zero
value is returned.
Notes
- The current card is left unchanged by this function.
- The card following the current card is checked first. If this is
not the required card, then the rest of the FitsChan is searched,
starting with the first card added to the FitsChan. Therefore cards
should be accessed in the order they are stored in the FitsChan (if
possible) as this will minimise the time spent searching for cards.
- An error will be reported if the keyword name does not conform
to FITS requirements.
- Zero
is returned as the function value if an error has already occurred,
or if this function should fail for any reason.
- Parameters:
name
- Pointer to a null-terminated character string
containing the FITS keyword name. This may be a complete FITS
header card, in which case the keyword to use is extracted from
it. No more than 80 characters are read from this string.
- Returns:
- A value of zero
is returned if the keyword was not found in the FitsChan or has
no associated value. Otherwise, a value of
one
is returned.
- Throws:
AstException
- if an error occurred in the AST library
putFits
public void putFits(String card,
boolean overwrite)
- Store a FITS header card in a FitsChan.
This function stores a FITS header card in a FitsChan. The card
is either inserted before the current card (identified by the
Card attribute), or over-writes the current card, as required.
Notes
- If the Card attribute initially points at the "end-of-file"
(i.e. exceeds the number of cards in the FitsChan), then the new
card is appended as the last card in the FitsChan.
- An error will result if the supplied string cannot be interpreted
as a FITS header card.
- Parameters:
card
- Pointer to a possibly null-terminated character string
containing the FITS card to be stored. No more than 80
characters will be used from this string (or fewer if a null
occurs earlier).overwrite
- If this value is zero, the new card is inserted in front of
the current card in the FitsChan (as identified by the
initial value of the Card attribute). If it is non-zero, the
new card replaces the current card. In either case, the Card
attribute is then incremented by one so that it subsequently
identifies the card following the one stored.
- Throws:
AstException
- if an error occurred in the AST library
retainFits
public void retainFits()
- Indicate that the current card in a FitsChan should be retained.
This function
stores a flag with the current card in the FitsChan indicating that
the card should not be removed from the FitsChan when an Object is
read from the FitsChan using
astRead.
Cards that have not been flagged in this way are removed when a
read operation completes succesfully, but only if the card was used
in the process of creating the returned AST Object. Any cards that
are irrelevant to the creation of the AST Object are retained whether
or not they are flagged.
Notes
- This function returns without action if the FitsChan is
initially positioned at the "end-of-file" (i.e. if the Card
attribute exceeds the number of cards in the FitsChan).
- The current card is not changed by this function.
- Throws:
AstException
- if an error occurred in the AST library
purgeWCS
public void purgeWCS()
- Delete all cards in the FitsChan describing WCS information.
This function
deletes all cards in a FitsChan that relate to any of the recognised
WCS encodings. On exit, the current card is the first remaining card
in the FitsChan.
- Throws:
AstException
- if an error occurred in the AST library
putCards
public void putCards(String cards)
- Store a set of FITS header cards in a FitsChan.
This function
stores a set of FITS header cards in a FitsChan. The cards are
supplied concatenated together into a single character string.
Any existing cards in the FitsChan are removed before the new cards
are added. The FitsChan is "re-wound" on exit by clearing its Card
attribute. This means that a subsequent invocation of
astRead
can be made immediately without the need to re-wind the FitsChan
first.
Notes
- An error will result if the supplied string contains any cards
which cannot be interpreted.
- Parameters:
cards
- Pointer to a null-terminated character string
containing the FITS cards to be stored. Each individual card
should occupy 80 characters in this string, and there should be
no delimiters, new lines, etc, between adjacent cards. The final
card may be less than 80 characters long.
This is the format produced by the fits_hdr2str function in the
CFITSIO library.
- Throws:
AstException
- if an error occurred in the AST library
getCard
public int getCard()
- Get
index of current FITS card in a FitsChan.
This attribute gives the index of the "current" FITS header card
within a FitsChan, the first card having an index of 1. The
choice of current card affects the behaviour of functions that
access the contents of the FitsChan, such as astDelFits,
astFindFits and astPutFits.
A value assigned to Card will position the FitsChan at any
desired point, so that a particular card within it can be
accessed. Alternatively, the value of Card may be enquired in
order to determine the current position of a FitsChan.
The default value of Card is 1. This means that clearing
this attribute (using astClear) effectively "rewinds" the
FitsChan, so that the first card is accessed next. If Card is
set to a value which exceeds the total number of cards in the
FitsChan (as given by its Ncard attribute), it is regarded as
pointing at the "end-of-file". In this case, the value returned
in response to an enquiry is always one more than the number of
cards in the FitsChan.
- Returns:
- this object's Card attribute
setCard
public void setCard(int card)
- Set
index of current FITS card in a FitsChan.
This attribute gives the index of the "current" FITS header card
within a FitsChan, the first card having an index of 1. The
choice of current card affects the behaviour of functions that
access the contents of the FitsChan, such as astDelFits,
astFindFits and astPutFits.
A value assigned to Card will position the FitsChan at any
desired point, so that a particular card within it can be
accessed. Alternatively, the value of Card may be enquired in
order to determine the current position of a FitsChan.
The default value of Card is 1. This means that clearing
this attribute (using astClear) effectively "rewinds" the
FitsChan, so that the first card is accessed next. If Card is
set to a value which exceeds the total number of cards in the
FitsChan (as given by its Ncard attribute), it is regarded as
pointing at the "end-of-file". In this case, the value returned
in response to an enquiry is always one more than the number of
cards in the FitsChan.
- Parameters:
card
- the Card attribute of this object
getCarLin
public boolean getCarLin()
- Get
ignore spherical rotations on CAR projections.
This attribute is a boolean value which specifies how FITS "CAR"
(plate carree, or "Cartesian") projections should be treated when
reading a FrameSet from a foreign encoded FITS header. If zero (the
default), it is assumed that the CAR projection conforms to the
conventions described in the FITS world coordinate system (FITS-WCS)
paper II "Representation of Celestial Coordinates in FITS" by
M. Calabretta & E.W. Greisen. If CarLin is non-zero, then these
conventions are ignored, and it is assumed that the mapping from pixel
coordinates to celestial coordinates is a simple linear transformation
(hence the attribute name "CarLin"). This is appropriate for some older
FITS data which claims to have a "CAR" projection, but which in fact do
not conform to the conventions of the FITS-WCS paper. Furthermore, if
CarLin is non-zero, it is assumed that CDELT and CD keywords are
in units of degrees rather than radians (as required by the
FITS-WCS papers).
The FITS-WCS paper specifies that headers which include a CAR projection
represent a linear mapping from pixel coordinates to "native spherical
coordinates", NOT celestial coordinates. An extra mapping is then
required from native spherical to celestial. This mapping is a 3D
rotation and so the overall Mapping from pixel to celestial coordinates
is NOT linear. See the FITS-WCS papers for further details.
- Returns:
- this object's CarLin attribute
setCarLin
public void setCarLin(boolean carLin)
- Set
ignore spherical rotations on CAR projections.
This attribute is a boolean value which specifies how FITS "CAR"
(plate carree, or "Cartesian") projections should be treated when
reading a FrameSet from a foreign encoded FITS header. If zero (the
default), it is assumed that the CAR projection conforms to the
conventions described in the FITS world coordinate system (FITS-WCS)
paper II "Representation of Celestial Coordinates in FITS" by
M. Calabretta & E.W. Greisen. If CarLin is non-zero, then these
conventions are ignored, and it is assumed that the mapping from pixel
coordinates to celestial coordinates is a simple linear transformation
(hence the attribute name "CarLin"). This is appropriate for some older
FITS data which claims to have a "CAR" projection, but which in fact do
not conform to the conventions of the FITS-WCS paper. Furthermore, if
CarLin is non-zero, it is assumed that CDELT and CD keywords are
in units of degrees rather than radians (as required by the
FITS-WCS papers).
The FITS-WCS paper specifies that headers which include a CAR projection
represent a linear mapping from pixel coordinates to "native spherical
coordinates", NOT celestial coordinates. An extra mapping is then
required from native spherical to celestial. This mapping is a 3D
rotation and so the overall Mapping from pixel to celestial coordinates
is NOT linear. See the FITS-WCS papers for further details.
- Parameters:
carLin
- the CarLin attribute of this object
getCDMatrix
public boolean getCDMatrix()
- Get
use CDi_j keywords to represent pixel scaling, rotation, etc.
This attribute is a boolean value which specifies how the linear
transformation from pixel coordinates to intermediate world
coordinates should be represented within a FitsChan when using
FITS-WCS encoding. This transformation describes the scaling,
rotation, shear, etc., of the pixel axes.
If the attribute has a non-zero value then the transformation is
represented by a set of CDi_j keywords representing a square matrix
(where "i" is the index of an intermediate world coordinate axis
and "j" is the index of a pixel axis). If the attribute has a zero
value the transformation is represented by a set of PCi_j keywords
(which also represent a square matrix) together with a corresponding
set of CDELTi keywords representing the axis scalings. See FITS-WCS
paper II "Representation of Celestial Coordinates in FITS" by
M. Calabretta & E.W. Greisen, for a complete description of these two
schemes.
The default value of the CDMatrix attribute is determined by the
contents of the FitsChan at the time the attribute is accessed. If
the FitsChan contains any CDi_j keywords then the default value is
non-zero. Otherwise it is zero. Note, reading a FrameSet from a
FitsChan will in general consume any CDi_j keywords present in the
FitsChan. Thus the default value for CDMatrix following a read will
usually be zero, even if the FitsChan originally contained some
CDi_j keywords. This behaviour is similar to that of the Encoding
attribute, the default value for which is determined by the contents
of the FitsChan at the time the attribute is accessed. If you wish
to retain the original value of the CDMatrix attribute (that is,
the value before reading the FrameSet) then you should enquire the
default value before doing the read, and then set that value
explicitly.
- Returns:
- this object's CDMatrix attribute
setCDMatrix
public void setCDMatrix(boolean CDMatrix)
- Set
use CDi_j keywords to represent pixel scaling, rotation, etc.
This attribute is a boolean value which specifies how the linear
transformation from pixel coordinates to intermediate world
coordinates should be represented within a FitsChan when using
FITS-WCS encoding. This transformation describes the scaling,
rotation, shear, etc., of the pixel axes.
If the attribute has a non-zero value then the transformation is
represented by a set of CDi_j keywords representing a square matrix
(where "i" is the index of an intermediate world coordinate axis
and "j" is the index of a pixel axis). If the attribute has a zero
value the transformation is represented by a set of PCi_j keywords
(which also represent a square matrix) together with a corresponding
set of CDELTi keywords representing the axis scalings. See FITS-WCS
paper II "Representation of Celestial Coordinates in FITS" by
M. Calabretta & E.W. Greisen, for a complete description of these two
schemes.
The default value of the CDMatrix attribute is determined by the
contents of the FitsChan at the time the attribute is accessed. If
the FitsChan contains any CDi_j keywords then the default value is
non-zero. Otherwise it is zero. Note, reading a FrameSet from a
FitsChan will in general consume any CDi_j keywords present in the
FitsChan. Thus the default value for CDMatrix following a read will
usually be zero, even if the FitsChan originally contained some
CDi_j keywords. This behaviour is similar to that of the Encoding
attribute, the default value for which is determined by the contents
of the FitsChan at the time the attribute is accessed. If you wish
to retain the original value of the CDMatrix attribute (that is,
the value before reading the FrameSet) then you should enquire the
default value before doing the read, and then set that value
explicitly.
- Parameters:
CDMatrix
- the CDMatrix attribute of this object
getDefB1950
public boolean getDefB1950()
- Get
use FK4 B1950 as defaults.
This attribute is a boolean value which specifies a default equinox
and reference frame to use when reading a FrameSet from a FitsChan
with a foreign (i.e. non-native) encoding. It is only used if the FITS
header contains RA and DEC axes but contains no information about the
reference frame or equinox. If this is the case, then values of FK4 and
B1950 are assumed if the DefB1950 attribute has a non-zero value and
ICRS is assumed if DefB1950 is zero. The default value for DefB1950
depends on the value of the Encoding attribute: for FITS-WCS encoding
the default is zero, and for all other encodings it is one.
- Returns:
- this object's DefB1950 attribute
setDefB1950
public void setDefB1950(boolean defB1950)
- Set
use FK4 B1950 as defaults.
This attribute is a boolean value which specifies a default equinox
and reference frame to use when reading a FrameSet from a FitsChan
with a foreign (i.e. non-native) encoding. It is only used if the FITS
header contains RA and DEC axes but contains no information about the
reference frame or equinox. If this is the case, then values of FK4 and
B1950 are assumed if the DefB1950 attribute has a non-zero value and
ICRS is assumed if DefB1950 is zero. The default value for DefB1950
depends on the value of the Encoding attribute: for FITS-WCS encoding
the default is zero, and for all other encodings it is one.
- Parameters:
defB1950
- the DefB1950 attribute of this object
getEncoding
public String getEncoding()
- Get
system for encoding Objects as FITS headers.
This attribute specifies the encoding system to use when AST
Objects are stored as FITS header cards in a FitsChan. It
affects the behaviour of the astWrite and astRead functions when
they are used to transfer any AST Object to or from an external
representation consisting of FITS header cards (i.e. whenever a
write or read operation is performed using a FitsChan as the I/O
Channel).
There are several ways (conventions) by which coordinate system
information may be represented in the form of FITS headers and
the Encoding attribute is used to specify which of these should
be used. The encoding options available are outlined in the
"Encodings Available" section below, and in more detail in the
sections which follow.
Encoding systems differ in the range of possible Objects
(e.g. classes) they can represent, in the restrictions they
place on these Objects (e.g. compatibility with some
externally-defined coordinate system model) and in the number of
Objects that can be stored together in any particular set of
FITS header cards (e.g. multiple Objects, or only a single
Object). The choice of encoding also affects the range of
external applications which can potentially read and interpret
the FITS header cards produced.
The encoding options available are not necessarily mutually
exclusive, and it may sometimes be possible to store multiple
Objects (or the same Object several times) using different
encodings within the same set of FITS header cards. This
possibility increases the likelihood of other applications being
able to read and interpret the information.
By default, a FitsChan will attempt to determine which encoding
system is already in use, and will set the default Encoding
value accordingly (so that subsequent I/O operations adopt the
same conventions). It does this by looking for certain critical
FITS keywords which only occur in particular encodings. For
details of how this works, see the "Choice of Default Encoding"
section below. If you wish to ensure that a particular encoding
system is used, independently of any FITS cards already present,
you should set an explicit Encoding value yourself.
Encodings Available
The Encoding attribute can take any of the following (case
insensitive) string values to select the corresponding encoding
system:
- "DSS": Encodes coordinate system information in FITS header
cards using the convention developed at the Space Telescope
Science Institute (STScI) for the Digitised Sky Survey (DSS)
astrometric plate calibrations. The main advantages of this
encoding are that FITS images which use it are widely available
and it is understood by a number of important and
well-established astronomy applications. For further details,
see the section "The DSS Encoding" below.
- "FITS-WCS": Encodes coordinate system information in FITS
header cards using the conventions described in the FITS
world coordinate system (FITS-WCS) papers by E.W. Greisen,
M. Calabretta, et al. The main advantages of this encoding are that
it should be understood by any FITS-WCS compliant application and
is likely to be adopted widely for FITS data in future. For further
details, see the section "The FITS-WCS Encoding" below.
- "FITS-PC": Encodes coordinate system information in FITS
header cards using the conventions described in an earlier draft
of the FITS world coordinate system papers by E.W. Greisen and
M. Calabretta. This encoding uses a combination of CDELTi and
PCiiijjj keywords to describe the scale and rotation of the pixel
axes. This encoding is included to support existing data and
software which uses these now superceded conventions. In general,
the "FITS-WCS" encoding (which uses CDi_j or PCi_j keywords to
describe the scale and rotation) should be used in preference to
"FITS-PC".
- "FITS-IRAF": Encodes coordinate system information in FITS
header cards using the conventions described in the document
"World Coordinate Systems Representations Within the FITS
Format" by R.J. Hanisch and D.G. Wells, 1988. This encoding is
currently employed by the IRAF data analysis facility, so its
use will facilitate data exchange with IRAF. Its main advantages
are that it is a stable convention which approximates to a
subset of the propsed FITS-WCS encoding (above). This makes it
suitable as an interim method for storing coordinate system
information in FITS headers until the FITS-WCS encoding becomes
stable. Since many datasets currently use the FITS-IRAF
encoding, conversion of data from FITS-IRAF to the final form of
FITS-WCS is likely to be well supported.
- "FITS-AIPS": Encodes coordinate system information in FITS
header cards using the conventions originally introduced by the
AIPS data analysis facility. This is base on the use of CDELTi and
CROTAi keuwords to desribe the scale and rotation of each axis.
These conventions have been superceded but are still widely used.
- "FITS-AIPS++": Encodes coordinate system information in FITS
header cards using the conventions used by the AIPS++ project.
This is an extension of FITS-AIPS which includes some of the
features of FITS-IRAF and FITS-PC.
- "FITS-CLASS": Encodes coordinate system information in FITS
header cards using the conventions used by the CLASS project.
CLASS is a software package for reducing single-dish radio and
sub-mm spectroscopic data. See the section "CLASS FITS format" at
http://www.iram.fr/IRAMFR/GILDAS/doc/html/class-html/.
- "NATIVE": Encodes AST Objects in FITS header cards using a
convention which is private to the AST library (but adheres to
the general FITS standard) and which uses FITS keywords that
will not clash with other encoding systems. The main advantages
of this are that any class of AST Object may be encoded, and any
(reasonable) number of Objects may be stored sequentially in the
same FITS header. This makes FITS headers an almost loss-less
communication path for passing AST Objects between applications
(although all such applications must, of course, make use of the
AST library to interpret the information). For further details,
see the section "The NATIVE Encoding" below.
Choice of Default Encoding
If the Encoding attribute of a FitsChan is not set, the default
value it takes is determined by the presence of certain critical
FITS keywords within the FitsChan. The sequence of decisions
used to arrive at the default value is as follows:
- If the FitsChan contains any keywords beginning with the
string "BEGAST", then NATIVE encoding is used,
- Otherwise, FITS-CLASS is used if the FitsChan contains a DELTAV
keyword and a keyword of the form VELO-xxx, where xxx indicates one
of the rest frames used by class (e.g. "VELO-LSR").
- Otherwise, if the FitsChan contains a CTYPE keyword which
represents a spectral axis using the conventions of the AIPS and
AIPS++ projects (e.g. "FELO-LSR", etc), then one of FITS-AIPS or
FITS-AIPS++ encoding is used. FITS-AIPS++ is used if any of the
keywords CDi_j, PROJP, LONPOLE or LATPOLE are
found in the FitsChan. Otherwise FITS-AIPS is used.
- Otherwise, if the FitsChan contains a keyword of the form
"PCiiijjj", where "i" and "j" are single digits, then
FITS-PC encoding is used,
- Otherwise, if the FitsChan contains a keyword of the form
"CDiiijjj", where "i" and "j" are single digits, then
FITS-IRAF encoding is used,
- Otherwise, if the FitsChan contains a keyword of the form
"CDi_j", and at least one of RADECSYS, PROJPi, or CjVALi
where "i" and "j" are single digits, then FITS-IRAF encoding is
used.
- Otherwise, if the FitsChan contains any keywords of the form
PROJPi, CjVALi or RADECSYS, where "i" and "j" are single digits,
then FITS-PC encoding is used.
- Otherwise, if the FitsChan contains a keyword of the form
CROTAi, where "i" is a single digit, then FITS-AIPS encoding is
used.
- Otherwise, if the FitsChan contains a keyword of the form
CRVALi, where "i" is a single digit, then FITS-WCS encoding is
used.
- Otherwise, if the FitsChan contains the "PLTRAH" keyword, then
DSS encoding is used,
- Otherwise, if none of these conditions is met (as would be the
case when using an empty FitsChan), then NATIVE encoding is
used.
Except for the NATIVE and DSS encodings, all the above checks
also require that the header contains at least one CTYPE, CRPIX and
CRVAL keyword (otherwise the checking process continues to the next
case).
Setting an explicit value for the Encoding attribute always
over-rides this default behaviour.
Note that when writing information to a FitsChan, the choice of
encoding will depend greatly on the type of application you
expect to be reading the information in future. If you do not
know this, there may sometimes be an advantage in writing the
information several times, using a different encoding on each
occasion.
The DSS Encoding
The DSS encoding uses FITS header cards to store a multi-term
polynomial which relates pixel positions on a digitised
photographic plate to celestial coordinates (right ascension and
declination). This encoding may only be used to store a single
AST Object in any set of FITS header cards, and that Object must
be a FrameSet which conforms to the STScI/DSS coordinate system
model (this means the Mapping which relates its base and current
Frames must include either a DssMap or a WcsMap with type
AST__TAN or AST__TPN).
When reading a DSS encoded Object (using astRead), the FitsChan
concerned must initially be positioned at the first card (its
Card attribute must equal 1) and the result of the read, if
successful, will always be a pointer to a FrameSet. The base
Frame of this FrameSet represents DSS pixel coordinates, and the
current Frame represents DSS celestial coordinates. Such a read
is always destructive and causes the FITS header cards required
for the construction of the FrameSet to be removed from the
FitsChan, which is then left positioned at the "end-of-file". A
subsequent read using the same encoding will therefore not
return another FrameSet, even if the FitsChan is rewound.
When astWrite is used to store a FrameSet using DSS encoding,
an attempt is first made to simplify the FrameSet to see if it
conforms to the DSS model. Specifically, the current Frame must
be a FK5 SkyFrame; the projection must be a tangent plane
(gnomonic) projection with polynomial corrections conforming to
DSS requirements, and north must be parallel to the second base
Frame axis.
If the simplification process succeeds, a description of the
FrameSet is written to the FitsChan using appropriate DSS FITS
header cards. The base Frame of the FrameSet is used to form the
DSS pixel coordinate system and the current Frame gives the DSS
celestial coordinate system. A successful write operation will
over-write any existing DSS encoded data in the FitsChan, but
will not affect other (non-DSS) header cards. If a destructive
read of a DSS encoded Object has previously occurred, then an
attempt will be made to store the FITS header cards back in
their original locations.
If an attempt to simplify a FrameSet to conform to the DSS model
fails (or if the Object supplied is not a FrameSet), then no
data will be written to the FitsChan and astWrite will return
zero. No error will result.
The NATIVE Encoding
The NATIVE encoding may be used to store a description of any
class of AST Object in the form of FITS header cards, and (for
most practical purposes) any number of these Object descriptions
may be stored within a single set of FITS cards. If multiple
Object descriptions are stored, they are written and read
sequentially. The NATIVE encoding makes use of unique FITS
keywords which are designed not to clash with keywords that have
already been used for other purposes (if a potential clash is
detected, an alternative keyword is constructed to avoid the
clash).
When reading a NATIVE encoded object from a FitsChan (using
astRead), FITS header cards are read, starting at the current
card (as determined by the Card attribute), until the start of
the next Object description is found. This description is then
read and converted into an AST Object, for which a pointer is
returned. Such a read is always destructive and causes all the
FITS header cards involved in the Object description to be
removed from the FitsChan, which is left positioned at the
following card.
The Object returned may be of any class, depending on the
description that was read, and other AST routines may be used to
validate it (for example, by examining its Class or ID attribute
using astGetC). If further NATIVE encoded Object descriptions
exist in the FitsChan, subsequent calls to astRead will return
the Objects they describe in sequence (and destroy their
descriptions) until no more remain between the current card and
the "end-of-file".
When astWrite is used to write an Object using NATIVE encoding,
a description of the Object is inserted immediately before the
current card (as determined by the Card attribute). Multiple
Object descriptions may be written in this way and are stored
separately (and sequentially if the Card attribute is not
modified between the writes). A write operation using the NATIVE
encoding does not over-write previously written Object
descriptions. Note, however, that subsequent behaviour is
undefined if an Object description is written inside a
previously-written description, so this should be avoided.
When an Object is written to a FitsChan using NATIVE encoding,
astWrite should (barring errors) always transfer data and
return a value of 1.
- Returns:
- this object's Encoding attribute
setEncoding
public void setEncoding(String encoding)
- Set
system for encoding Objects as FITS headers.
This attribute specifies the encoding system to use when AST
Objects are stored as FITS header cards in a FitsChan. It
affects the behaviour of the astWrite and astRead functions when
they are used to transfer any AST Object to or from an external
representation consisting of FITS header cards (i.e. whenever a
write or read operation is performed using a FitsChan as the I/O
Channel).
There are several ways (conventions) by which coordinate system
information may be represented in the form of FITS headers and
the Encoding attribute is used to specify which of these should
be used. The encoding options available are outlined in the
"Encodings Available" section below, and in more detail in the
sections which follow.
Encoding systems differ in the range of possible Objects
(e.g. classes) they can represent, in the restrictions they
place on these Objects (e.g. compatibility with some
externally-defined coordinate system model) and in the number of
Objects that can be stored together in any particular set of
FITS header cards (e.g. multiple Objects, or only a single
Object). The choice of encoding also affects the range of
external applications which can potentially read and interpret
the FITS header cards produced.
The encoding options available are not necessarily mutually
exclusive, and it may sometimes be possible to store multiple
Objects (or the same Object several times) using different
encodings within the same set of FITS header cards. This
possibility increases the likelihood of other applications being
able to read and interpret the information.
By default, a FitsChan will attempt to determine which encoding
system is already in use, and will set the default Encoding
value accordingly (so that subsequent I/O operations adopt the
same conventions). It does this by looking for certain critical
FITS keywords which only occur in particular encodings. For
details of how this works, see the "Choice of Default Encoding"
section below. If you wish to ensure that a particular encoding
system is used, independently of any FITS cards already present,
you should set an explicit Encoding value yourself.
Encodings Available
The Encoding attribute can take any of the following (case
insensitive) string values to select the corresponding encoding
system:
- "DSS": Encodes coordinate system information in FITS header
cards using the convention developed at the Space Telescope
Science Institute (STScI) for the Digitised Sky Survey (DSS)
astrometric plate calibrations. The main advantages of this
encoding are that FITS images which use it are widely available
and it is understood by a number of important and
well-established astronomy applications. For further details,
see the section "The DSS Encoding" below.
- "FITS-WCS": Encodes coordinate system information in FITS
header cards using the conventions described in the FITS
world coordinate system (FITS-WCS) papers by E.W. Greisen,
M. Calabretta, et al. The main advantages of this encoding are that
it should be understood by any FITS-WCS compliant application and
is likely to be adopted widely for FITS data in future. For further
details, see the section "The FITS-WCS Encoding" below.
- "FITS-PC": Encodes coordinate system information in FITS
header cards using the conventions described in an earlier draft
of the FITS world coordinate system papers by E.W. Greisen and
M. Calabretta. This encoding uses a combination of CDELTi and
PCiiijjj keywords to describe the scale and rotation of the pixel
axes. This encoding is included to support existing data and
software which uses these now superceded conventions. In general,
the "FITS-WCS" encoding (which uses CDi_j or PCi_j keywords to
describe the scale and rotation) should be used in preference to
"FITS-PC".
- "FITS-IRAF": Encodes coordinate system information in FITS
header cards using the conventions described in the document
"World Coordinate Systems Representations Within the FITS
Format" by R.J. Hanisch and D.G. Wells, 1988. This encoding is
currently employed by the IRAF data analysis facility, so its
use will facilitate data exchange with IRAF. Its main advantages
are that it is a stable convention which approximates to a
subset of the propsed FITS-WCS encoding (above). This makes it
suitable as an interim method for storing coordinate system
information in FITS headers until the FITS-WCS encoding becomes
stable. Since many datasets currently use the FITS-IRAF
encoding, conversion of data from FITS-IRAF to the final form of
FITS-WCS is likely to be well supported.
- "FITS-AIPS": Encodes coordinate system information in FITS
header cards using the conventions originally introduced by the
AIPS data analysis facility. This is base on the use of CDELTi and
CROTAi keuwords to desribe the scale and rotation of each axis.
These conventions have been superceded but are still widely used.
- "FITS-AIPS++": Encodes coordinate system information in FITS
header cards using the conventions used by the AIPS++ project.
This is an extension of FITS-AIPS which includes some of the
features of FITS-IRAF and FITS-PC.
- "FITS-CLASS": Encodes coordinate system information in FITS
header cards using the conventions used by the CLASS project.
CLASS is a software package for reducing single-dish radio and
sub-mm spectroscopic data. See the section "CLASS FITS format" at
http://www.iram.fr/IRAMFR/GILDAS/doc/html/class-html/.
- "NATIVE": Encodes AST Objects in FITS header cards using a
convention which is private to the AST library (but adheres to
the general FITS standard) and which uses FITS keywords that
will not clash with other encoding systems. The main advantages
of this are that any class of AST Object may be encoded, and any
(reasonable) number of Objects may be stored sequentially in the
same FITS header. This makes FITS headers an almost loss-less
communication path for passing AST Objects between applications
(although all such applications must, of course, make use of the
AST library to interpret the information). For further details,
see the section "The NATIVE Encoding" below.
Choice of Default Encoding
If the Encoding attribute of a FitsChan is not set, the default
value it takes is determined by the presence of certain critical
FITS keywords within the FitsChan. The sequence of decisions
used to arrive at the default value is as follows:
- If the FitsChan contains any keywords beginning with the
string "BEGAST", then NATIVE encoding is used,
- Otherwise, FITS-CLASS is used if the FitsChan contains a DELTAV
keyword and a keyword of the form VELO-xxx, where xxx indicates one
of the rest frames used by class (e.g. "VELO-LSR").
- Otherwise, if the FitsChan contains a CTYPE keyword which
represents a spectral axis using the conventions of the AIPS and
AIPS++ projects (e.g. "FELO-LSR", etc), then one of FITS-AIPS or
FITS-AIPS++ encoding is used. FITS-AIPS++ is used if any of the
keywords CDi_j, PROJP, LONPOLE or LATPOLE are
found in the FitsChan. Otherwise FITS-AIPS is used.
- Otherwise, if the FitsChan contains a keyword of the form
"PCiiijjj", where "i" and "j" are single digits, then
FITS-PC encoding is used,
- Otherwise, if the FitsChan contains a keyword of the form
"CDiiijjj", where "i" and "j" are single digits, then
FITS-IRAF encoding is used,
- Otherwise, if the FitsChan contains a keyword of the form
"CDi_j", and at least one of RADECSYS, PROJPi, or CjVALi
where "i" and "j" are single digits, then FITS-IRAF encoding is
used.
- Otherwise, if the FitsChan contains any keywords of the form
PROJPi, CjVALi or RADECSYS, where "i" and "j" are single digits,
then FITS-PC encoding is used.
- Otherwise, if the FitsChan contains a keyword of the form
CROTAi, where "i" is a single digit, then FITS-AIPS encoding is
used.
- Otherwise, if the FitsChan contains a keyword of the form
CRVALi, where "i" is a single digit, then FITS-WCS encoding is
used.
- Otherwise, if the FitsChan contains the "PLTRAH" keyword, then
DSS encoding is used,
- Otherwise, if none of these conditions is met (as would be the
case when using an empty FitsChan), then NATIVE encoding is
used.
Except for the NATIVE and DSS encodings, all the above checks
also require that the header contains at least one CTYPE, CRPIX and
CRVAL keyword (otherwise the checking process continues to the next
case).
Setting an explicit value for the Encoding attribute always
over-rides this default behaviour.
Note that when writing information to a FitsChan, the choice of
encoding will depend greatly on the type of application you
expect to be reading the information in future. If you do not
know this, there may sometimes be an advantage in writing the
information several times, using a different encoding on each
occasion.
The DSS Encoding
The DSS encoding uses FITS header cards to store a multi-term
polynomial which relates pixel positions on a digitised
photographic plate to celestial coordinates (right ascension and
declination). This encoding may only be used to store a single
AST Object in any set of FITS header cards, and that Object must
be a FrameSet which conforms to the STScI/DSS coordinate system
model (this means the Mapping which relates its base and current
Frames must include either a DssMap or a WcsMap with type
AST__TAN or AST__TPN).
When reading a DSS encoded Object (using astRead), the FitsChan
concerned must initially be positioned at the first card (its
Card attribute must equal 1) and the result of the read, if
successful, will always be a pointer to a FrameSet. The base
Frame of this FrameSet represents DSS pixel coordinates, and the
current Frame represents DSS celestial coordinates. Such a read
is always destructive and causes the FITS header cards required
for the construction of the FrameSet to be removed from the
FitsChan, which is then left positioned at the "end-of-file". A
subsequent read using the same encoding will therefore not
return another FrameSet, even if the FitsChan is rewound.
When astWrite is used to store a FrameSet using DSS encoding,
an attempt is first made to simplify the FrameSet to see if it
conforms to the DSS model. Specifically, the current Frame must
be a FK5 SkyFrame; the projection must be a tangent plane
(gnomonic) projection with polynomial corrections conforming to
DSS requirements, and north must be parallel to the second base
Frame axis.
If the simplification process succeeds, a description of the
FrameSet is written to the FitsChan using appropriate DSS FITS
header cards. The base Frame of the FrameSet is used to form the
DSS pixel coordinate system and the current Frame gives the DSS
celestial coordinate system. A successful write operation will
over-write any existing DSS encoded data in the FitsChan, but
will not affect other (non-DSS) header cards. If a destructive
read of a DSS encoded Object has previously occurred, then an
attempt will be made to store the FITS header cards back in
their original locations.
If an attempt to simplify a FrameSet to conform to the DSS model
fails (or if the Object supplied is not a FrameSet), then no
data will be written to the FitsChan and astWrite will return
zero. No error will result.
The NATIVE Encoding
The NATIVE encoding may be used to store a description of any
class of AST Object in the form of FITS header cards, and (for
most practical purposes) any number of these Object descriptions
may be stored within a single set of FITS cards. If multiple
Object descriptions are stored, they are written and read
sequentially. The NATIVE encoding makes use of unique FITS
keywords which are designed not to clash with keywords that have
already been used for other purposes (if a potential clash is
detected, an alternative keyword is constructed to avoid the
clash).
When reading a NATIVE encoded object from a FitsChan (using
astRead), FITS header cards are read, starting at the current
card (as determined by the Card attribute), until the start of
the next Object description is found. This description is then
read and converted into an AST Object, for which a pointer is
returned. Such a read is always destructive and causes all the
FITS header cards involved in the Object description to be
removed from the FitsChan, which is left positioned at the
following card.
The Object returned may be of any class, depending on the
description that was read, and other AST routines may be used to
validate it (for example, by examining its Class or ID attribute
using astGetC). If further NATIVE encoded Object descriptions
exist in the FitsChan, subsequent calls to astRead will return
the Objects they describe in sequence (and destroy their
descriptions) until no more remain between the current card and
the "end-of-file".
When astWrite is used to write an Object using NATIVE encoding,
a description of the Object is inserted immediately before the
current card (as determined by the Card attribute). Multiple
Object descriptions may be written in this way and are stored
separately (and sequentially if the Card attribute is not
modified between the writes). A write operation using the NATIVE
encoding does not over-write previously written Object
descriptions. Note, however, that subsequent behaviour is
undefined if an Object description is written inside a
previously-written description, so this should be avoided.
When an Object is written to a FitsChan using NATIVE encoding,
astWrite should (barring errors) always transfer data and
return a value of 1.
- Parameters:
encoding
- the Encoding attribute of this object
getFitsDigits
public int getFitsDigits()
- Get
digits of precision for floating point FITS values.
This attribute gives the number of significant decimal digits to
use when formatting floating point values for inclusion in the
FITS header cards within a FitsChan.
By default, a positive value is used which results in no loss of
information, assuming that the value's precision is double.
Usually, this causes no problems.
However, to adhere strictly to the recommendations of the FITS
standard, the width of the formatted value (including sign,
decimal point and exponent) ought not to be more than 20
characters. If you are concerned about this, you should set
FitsDigits to a negative value, such as -15. In this case, the
absolute value (+15) indicates the maximum number of significant
digits to use, but the actual number used may be fewer than this
to ensure that the FITS recommendations are satisfied. When
using this approach, the resulting number of significant digits
may depend on the value being formatted and on the presence of
any sign, decimal point or exponent.
The value of this attribute is effective when FITS header cards
are output, either using
astFindFits or by the action of the FitsChan's sink function
when it is finally deleted.
- Returns:
- this object's FitsDigits attribute
setFitsDigits
public void setFitsDigits(int fitsDigits)
- Set
digits of precision for floating point FITS values.
This attribute gives the number of significant decimal digits to
use when formatting floating point values for inclusion in the
FITS header cards within a FitsChan.
By default, a positive value is used which results in no loss of
information, assuming that the value's precision is double.
Usually, this causes no problems.
However, to adhere strictly to the recommendations of the FITS
standard, the width of the formatted value (including sign,
decimal point and exponent) ought not to be more than 20
characters. If you are concerned about this, you should set
FitsDigits to a negative value, such as -15. In this case, the
absolute value (+15) indicates the maximum number of significant
digits to use, but the actual number used may be fewer than this
to ensure that the FITS recommendations are satisfied. When
using this approach, the resulting number of significant digits
may depend on the value being formatted and on the presence of
any sign, decimal point or exponent.
The value of this attribute is effective when FITS header cards
are output, either using
astFindFits or by the action of the FitsChan's sink function
when it is finally deleted.
- Parameters:
fitsDigits
- the FitsDigits attribute of this object
getNcard
public int getNcard()
- Get
number of FITS header cards in a FitsChan.
This attribute gives the total number of FITS header cards
stored in a FitsChan. It is updated as cards are added or
deleted.
- Returns:
- this object's Ncard attribute
getWarnings
public String getWarnings()
- Get
controls the issuing of warnings about various conditions.
This attribute controls the issuing of warnings about selected
conditions when an Object or keyword is read from or written to a
FitsChan. The value supplied for the Warnings attribute should
consist of a space separated list of condition names (see the
AllWarnings attribute for a list of the currently defined names).
Each name indicates a condition which should be reported. The default
value for Warnings is the string "Tnx Zpx BadCel BadMat BadPV BadCTYPE".
The text of any warning will be stored within the FitsChan in the
form of one or more new header cards with keyword ASTWARN. If
required, applications can check the FitsChan for ASTWARN cards
(using astFindFits) after the call to astRead or astWrite has been
performed, and report the text of any such cards to the user. ASTWARN
cards will be propagated to any output header unless they are
deleted from the FitsChan using astDelFits.
Notes
This attribute only controls the warnings that are to be stored as
a set of header cards in the FitsChan as described above. It has no
effect on the storage of warnings in the parent Channel structure.
All warnings are stored in the parent Channel structure, from where
they can be retrieved using the
astWarnings
function.
- Returns:
- this object's Warnings attribute
setWarnings
public void setWarnings(String warnings)
- Set
controls the issuing of warnings about various conditions.
This attribute controls the issuing of warnings about selected
conditions when an Object or keyword is read from or written to a
FitsChan. The value supplied for the Warnings attribute should
consist of a space separated list of condition names (see the
AllWarnings attribute for a list of the currently defined names).
Each name indicates a condition which should be reported. The default
value for Warnings is the string "Tnx Zpx BadCel BadMat BadPV BadCTYPE".
The text of any warning will be stored within the FitsChan in the
form of one or more new header cards with keyword ASTWARN. If
required, applications can check the FitsChan for ASTWARN cards
(using astFindFits) after the call to astRead or astWrite has been
performed, and report the text of any such cards to the user. ASTWARN
cards will be propagated to any output header unless they are
deleted from the FitsChan using astDelFits.
Notes
This attribute only controls the warnings that are to be stored as
a set of header cards in the FitsChan as described above. It has no
effect on the storage of warnings in the parent Channel structure.
All warnings are stored in the parent Channel structure, from where
they can be retrieved using the
astWarnings
function.
- Parameters:
warnings
- the Warnings attribute of this object
getAllWarnings
public String getAllWarnings()
- Get
a list of all currently available condition names.
This read-only attribute is a space separated list of all the conditions
names recognized by the Warnings attribute. The names are listed
below.
Conditions
The following conditions are currently recognised (all are
case-insensitive):
- "BadCel": This condition arises when reading a FrameSet from a
non-Native encoded FitsChan if an unknown celestial co-ordinate
system is specified by the CTYPE keywords.
- "BadCTYPE": This condition arises when reading a FrameSet from a
non-Native encoded FitsChan if an illegal algorithm code is specified
by a CTYPE keyword, and the illegal code can be converted to an
equivalent legal code.
- "BadLat": This condition arises when reading a FrameSet from a
non-Native encoded FitsChan if the latitude of the reference point
has an absolute value greater than 90 degrees. The actual absolute
value used is set to exactly 90 degrees in these cases.
- "BadMat": This condition arises if the matrix describing the
transformation from pixel offsets to intermediate world coordinates
cannot be inverted. This matrix describes the scaling, rotation, shear,
etc., applied to the pixel axes, and is specified by keywords such as
PCi_j, CDi_j, CROTA, etc. For example, the matrix will not be invertable
if any rows or columns consist entirely of zeros. The FITS-WCS Paper I
"Representation of World Coordinates in FITS" by Greisen & Calabretta
requires that this matrix be invertable. Many operations (such as
grid plotting) will not be possible if the matrix cannot be inverted.
- "BadPV": This condition arises when reading a FrameSet from a
non-Native encoded FitsChan. It is issued if a PVi_m header is found
that refers to a projection parameter that is not used by the
projection type specified by CTYPE.
- "BadVal": This condition arises when reading a FrameSet from a
non-Native encoded FitsChan if it is not possible to convert the
value of a FITS keywords to the expected type. For instance, this
can occur if the FITS header contains a string value for a keyword
which should have a floating point value, or if the keyword has no
value at all (i.e. is a comment card).
- "Distortion": This condition arises when reading a FrameSet from a
non-Native encoded FitsChan if any of the CTYPE keywords specify an
unsupported distortion code using the "4-3-3" format specified in
FITS-WCS paper IV. Such distortion codes are ignored.
- "NoCTYPE": This condition arises if a default CTYPE value is used
within astRead, due to no value being present in the supplied FitsChan.
This condition is only tested for when using non-Native encodings.
- "NoEquinox": This condition arises if a default equinox value is used
within astRead, due to no value being present in the supplied FitsChan.
This condition is only tested for when using non-Native encodings.
- "NoRadesys": This condition arises if a default reference frame is
used for an equatorial co-ordinate system within astRead, due to no
value being present in the supplied FitsChan. This condition is only
tested for when using non-Native encodings.
- "NoLonpole": This condition arises if a default value is used for
the LONPOLE keyword within astRead, due to no value being present
in the supplied FitsChan. This condition is only tested for when
using non-Native encodings.
- "NoLatpole": This condition arises if a default value is used for
the LATPOLE keyword within astRead, due to no value being present
in the supplied FitsChan. This condition is only tested for when
using non-Native encodings.
- "NoMjd-obs": This condition arises if a default value is used for
the date of observation within astRead, due to no value being present
in the supplied FitsChan. This condition is only tested for when using
non-Native encodings.
- "Tnx": This condition arises if a FrameSet is read from a FITS
header containing an IRAF "TNX" projection which includes terms
not supproted by AST. Such terms are ignored and so the resulting
FrameSet may be inaccurate.
- "Zpx": This condition arises if a FrameSet is read from a FITS
header containing an IRAF "ZPX" projection which includes "lngcor"
or "latcor" correction terms. These terms are not supported by AST
and are ignored. The resulting FrameSet may therefore be inaccurate.
- Returns:
- this object's AllWarnings attribute
getIwc
public boolean getIwc()
- Get
include a Frame representing FITS-WCS intermediate world coordinates.
This attribute is a boolean value which is used when a FrameSet is
read from a FitsChan with a foreign FITS encoding (e.g. FITS-WCS) using
astRead.
If it has a non-zero value then the returned FrameSet will include
Frames representing "intermediate world coordinates" (IWC). These
Frames will have Domain name "IWC" for primary axis descriptions, and
"IWCa" for secondary axis descriptions, where "a" is replaced by
the single alternate axis description character, as used in the
FITS-WCS header. The default value for "Iwc" is zero.
FITS-WCS paper 1 defines IWC as a Cartesian coordinate system with one
axis for each WCS axis, and is the coordinate system produced by the
rotation matrix (represented by FITS keyword PCi_j, CDi_j, etc).
For instance, for a 2-D FITS-WCS header describing projected
celestial longitude and latitude, the intermediate world
coordinates represent offsets in degrees from the reference point
within the plane of projection.
- Returns:
- this object's Iwc attribute
setIwc
public void setIwc(boolean iwc)
- Set
include a Frame representing FITS-WCS intermediate world coordinates.
This attribute is a boolean value which is used when a FrameSet is
read from a FitsChan with a foreign FITS encoding (e.g. FITS-WCS) using
astRead.
If it has a non-zero value then the returned FrameSet will include
Frames representing "intermediate world coordinates" (IWC). These
Frames will have Domain name "IWC" for primary axis descriptions, and
"IWCa" for secondary axis descriptions, where "a" is replaced by
the single alternate axis description character, as used in the
FITS-WCS header. The default value for "Iwc" is zero.
FITS-WCS paper 1 defines IWC as a Cartesian coordinate system with one
axis for each WCS axis, and is the coordinate system produced by the
rotation matrix (represented by FITS keyword PCi_j, CDi_j, etc).
For instance, for a 2-D FITS-WCS header describing projected
celestial longitude and latitude, the intermediate world
coordinates represent offsets in degrees from the reference point
within the plane of projection.
- Parameters:
iwc
- the Iwc attribute of this object
Copyright © 2015 Central Laboratory of the Research Councils. All Rights Reserved.