FitsChan (Starlink-UK API)

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<X>) and existing ones may be deleted (astDelFits), extracted (astGetFits<X>), or changed (astSetFits<X>).
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

Field Summary
- Fields inherited from class uk.ac.starlink.ast.AstObject
  AST__BAD, AST__TUNULL, pointer

Constructor Summary

Constructors
Constructor and Description
`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

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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

Methods inherited from class java.lang.Object
clone, getClass, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - 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.
- Method Detail
  - 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 read
    
    rval - real part of the value
    
    ival - imaginary part of the value
    
    comment - 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 read
    
    rval - real part of the value
    
    ival - imaginary part of the value
    
    comment - 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 read
    
    value - value
    
    comment - 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 read
    
    value - value
    
    comment - 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 read
    
    value - value
    
    comment - 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 read
    
    value - value
    
    comment - 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 read
    
    value - value
    
    comment - 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

Class FitsChan

Licence

Usage

Field Summary

Fields inherited from class uk.ac.starlink.ast.AstObject

Constructor Summary

Method Summary

Methods inherited from class uk.ac.starlink.ast.Channel

Methods inherited from class uk.ac.starlink.ast.AstObject

Methods inherited from class java.lang.Object

Constructor Detail

FitsChan

FitsChan

Method Detail

iterator

sink

source

finalize

close

read

write

setFits

setFits

setFits

setFits

setFits

setFits

setFitsContinue

delFits

Notes

findFits

Notes

Keyword Templates

testFits

Notes

putFits

Notes

retainFits

Notes

purgeWCS

putCards

Notes

getCard

setCard

getCarLin

setCarLin

getCDMatrix

setCDMatrix

getDefB1950

setDefB1950

getEncoding

Encodings Available

Choice of Default Encoding

The DSS Encoding

The NATIVE Encoding

setEncoding

Encodings Available

Choice of Default Encoding

The DSS Encoding

The NATIVE Encoding

getFitsDigits

setFitsDigits

getNcard

getWarnings

Notes

setWarnings

Notes

getAllWarnings

Conditions

getIwc

setIwc