lsst.astshim gee0fe1808a+052faf71bd
Public Member Functions | List of all members
ast::FitsChan Class Reference

#include <FitsChan.h>

Inheritance diagram for ast::FitsChan:
ast::Channel ast::Object

Public Member Functions

 FitsChan (Stream &stream, std::string const &options="")
 
virtual ~FitsChan ()
 
 FitsChan (FitsChan const &)=delete
 
 FitsChan (FitsChan &&)=default
 
FitsChanoperator= (FitsChan const &)=delete
 
FitsChanoperator= (FitsChan &&)=default
 
void delFits ()
 
void emptyFits ()
 
FoundValue< std::string > findFits (std::string const &name, bool inc)
 
FoundValue< std::complex< double > > getFitsCF (std::string const &name="", std::complex< double > defval={0, 0}) const
 
FoundValue< std::string > getFitsCN (std::string const &name="", std::string defval="") const
 
FoundValue< double > getFitsF (std::string const &name="", double defval=0) const
 
FoundValue< int > getFitsI (std::string const &name="", int defval=0) const
 
FoundValue< bool > getFitsL (std::string const &name="", bool defval=false) const
 
FoundValue< std::string > getFitsS (std::string const &name="", std::string defval="") const
 
std::vector< std::string > getAllCardNames ()
 
std::string getAllWarnings () const
 
int getCard () const
 
std::string getCardComm () const
 
std::string getCardName () const
 
CardType getCardType () const
 
bool getCarLin () const
 
bool getCDMatrix () const
 
bool getClean () const
 
bool getDefB1950 () const
 
std::string getEncoding () const
 
std::string getFitsAxisOrder () const
 
int getFitsDigits () const
 
double getFitsTol () const
 
bool getIwc () const
 
int getNCard () const
 
int getNKey () const
 
bool getSipOK () const
 
bool getSipReplace () const
 
int getTabOK () const
 
int getPolyTan () const
 
std::string getWarnings () const
 
void purgeWcs ()
 
void putCards (std::string const &cards)
 
void putFits (std::string const &card, bool overwrite)
 
void readFits ()
 
void retainFits ()
 
void setFitsCF (std::string const &name, std::complex< double > value, std::string const &comment="", bool overwrite=false)
 
void setFitsCM (std::string const &comment, bool overwrite=false)
 
void setFitsCN (std::string const &name, std::string value, std::string const &comment="", bool overwrite=false)
 
void setFitsF (std::string const &name, double value, std::string const &comment="", bool overwrite=false)
 
void setFitsI (std::string const &name, int value, std::string const &comment="", bool overwrite=false)
 
void setFitsL (std::string const &name, bool value, std::string const &comment="", bool overwrite=false)
 
void setFitsS (std::string const &name, std::string value, std::string const &comment="", bool overwrite=false)
 
void setFitsU (std::string const &name, std::string const &comment="", bool overwrite=false)
 
void setCarLin (bool cdMatrix)
 
void setCDMatrix (bool cdMatrix)
 
void setClean (bool clean)
 
void setDefB1950 (bool defB1950)
 
void setEncoding (std::string const &encoding)
 
void setFitsAxisOrder (std::string const &order)
 
void setFitsDigits (int digits)
 
void setFitsTol (double tol)
 
void setIwc (bool iwcs)
 
void setSipOK (bool sipOK)
 
void setSipReplace (bool replace)
 
void setTabOK (int tabOK)
 
void setPolyTan (int polytan)
 
void setWarnings (std::string const &warnings)
 
void showFits () const
 
FitsKeyState testFits (std::string const &name="") const
 
void writeFits ()
 
void clearCard ()
 Rewind the card index to the beginning. More...
 
void setCard (int ind)
 
std::shared_ptr< KeyMapgetTables () const
 
 FitsChan (AstFitsChan *rawFitsChan)
 
- Public Member Functions inherited from ast::Channel
 Channel (Stream &stream, std::string const &options="")
 
virtual ~Channel ()
 
 Channel (Channel const &)=delete
 
 Channel (Channel &&)=default
 
Channeloperator= (Channel const &)=delete
 
Channeloperator= (Channel &&)=default
 
std::shared_ptr< Channelcopy () const
 Return a deep copy of this object. More...
 
bool getComment () const
 Get Comment: include textual comments in output? More...
 
int getFull () const
 Get Full: level of output detail; one of -1: minimum, 0: normal, 1: verbose. More...
 
int getIndent () const
 Get Indent: indentation increment between objects. More...
 
int getReportLevel () const
 Get ReportLevel: report level. More...
 
bool getSkip () const
 Get Skip: skip irrelevant data on input? More...
 
bool getStrict () const
 Get Strict: generate errors instead of warnings? More...
 
std::shared_ptr< Objectread ()
 Read an object from a channel. More...
 
void setComment (bool skip)
 Set Comment: include textual comments in output? More...
 
void setFull (int full)
 Set Full: level of output detail; one of -1: minimum, 0: normal, 1: verbose. More...
 
void setIndent (int indent)
 Set Indent: indentation increment between objects. More...
 
void setReportLevel (int level)
 
void setSkip (bool skip)
 Set Skip: skip irrelevant data on input? More...
 
void setStrict (bool strict)
 Set Strict: generate errors instead of warnings? More...
 
KeyMap warnings () const
 
int write (Object const &object)
 Write an object to a channel. More...
 
- Public Member Functions inherited from ast::Object
virtual ~Object ()
 
 Object (Object const &object)
 Copy constructor: make a deep copy. More...
 
 Object (Object &&)=default
 
Objectoperator= (Object const &)=delete
 
Objectoperator= (Object &&)=default
 
bool operator== (Object const &rhs) const
 
bool operator!= (Object const &rhs) const
 
std::shared_ptr< Objectcopy () const
 Return a deep copy of this object. More...
 
void clear (std::string const &attrib)
 
bool hasAttribute (std::string const &attrib) const
 
std::string getClassName () const
 
std::string getID () const
 Get ID: object identification string that is not copied. More...
 
std::string getIdent () const
 Get Ident: object identification string that is copied. More...
 
int getNObject () const
 
int getObjSize () const
 Get ObjSize: the in-memory size of the AST object in bytes. More...
 
int getRefCount () const
 
bool getUseDefs () const
 Get UseDefs: allow use of default values for Object attributes? More...
 
void lock (bool wait)
 
bool same (Object const &other) const
 
void setID (std::string const &id)
 Set ID: object identification string that is not copied. More...
 
void setIdent (std::string const &ident)
 Set Ident: object identification string that is copied. More...
 
void setUseDefs (bool usedefs)
 Set UseDefs: allow use of default values for Object attributes? More...
 
void show (std::ostream &os, bool showComments=true) const
 
std::string show (bool showComments=true) const
 
bool test (std::string const &attrib) const
 
void unlock (bool report=false)
 
AstObject const * getRawPtr () const
 
AstObject * getRawPtr ()
 

Additional Inherited Members

- Public Types inherited from ast::Object
using ObjectPtr = std::unique_ptr< AstObject, Deleter >
 unique pointer holding an AST raw pointer More...
 
- Static Public Member Functions inherited from ast::Object
static std::shared_ptr< ObjectfromString (std::string const &str)
 
template<typename Class >
static std::shared_ptr< Class > fromAstObject (AstObject *rawObj, bool copy)
 
- Protected Member Functions inherited from ast::Channel
virtual std::shared_ptr< ObjectcopyPolymorphic () const override
 
 Channel (AstChannel *chan, Stream &stream, bool isFits=false)
 
 Channel (AstChannel *chan)
 
- Protected Member Functions inherited from ast::Object
 Object (AstObject *object)
 
template<typename T , typename AstT >
std::shared_ptr< T > copyImpl () const
 
bool getB (std::string const &attrib) const
 
std::string const getC (std::string const &attrib) const
 
double getD (std::string const &attrib) const
 
float getF (std::string const &attrib) const
 
int getI (std::string const &attrib) const
 
long int getL (std::string const &attrib) const
 
void set (std::string const &setting)
 
void setB (std::string const &attrib, bool value)
 
void setC (std::string const &attrib, std::string const &value)
 
void setD (std::string const &attrib, double value)
 
void setF (std::string const &attrib, float value)
 
void setI (std::string const &attrib, int value)
 
void setL (std::string const &attrib, long int value)
 
- Static Protected Member Functions inherited from ast::Object
template<typename ShimT , typename AstT >
static std::shared_ptr< ShimT > makeShim (AstObject *p)
 

Detailed Description

A specialized form of Channel which reads and writes FITS header cards

Writing an Object to a FitsChan 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 Card attribute, which identifies a "current" card, to which subsequent operations apply. Searches based on keyword may be performed (using findFits), new cards may be inserted (putFits, putCards, setFitsS and similar) and existing ones may be deleted with delFits, extracted with getFitsS and similar, or changed with setFitsS and similar.

Missing Methods

Tables are not yet supported, so the following AST functions are not wrapped as methods:

Attributes

FitsChan has the following attributes, in addition to those provided by Channel and Object

Notes

As for any Channel, when you create a FitsChan, you specify a Stream which sources and sinks data by reading and writing FITS header cards. If you provide a source, 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, the FitsChan remains empty until you explicitly enter data into it (e.g. using putFits, putCards, write 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 will be written to the sink.

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 read and write, when used with a FitsChan, depends on the encoding in use. In general, however, all successful use of read 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 retainFits function). An unsuccessful call of read (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 write 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.

Constructor & Destructor Documentation

◆ FitsChan() [1/4]

ast::FitsChan::FitsChan ( Stream stream,
std::string const &  options = "" 
)
explicit

Construct a channel that uses a provided Stream

Parameters
[in]streamStream for channel I/O:
  • For file I/O: provide a FileStream
  • For string I/O (e.g. unit tests): provide a StringStream
  • For standard I/O provide Stream(&std::cin, &std::cout)) where either stream can be nullptr if not wanted
[in]optionsComma-separated list of attribute assignments.

◆ ~FitsChan()

ast::FitsChan::~FitsChan ( )
virtual

◆ FitsChan() [2/4]

ast::FitsChan::FitsChan ( FitsChan const &  )
delete

◆ FitsChan() [3/4]

ast::FitsChan::FitsChan ( FitsChan &&  )
default

◆ FitsChan() [4/4]

ast::FitsChan::FitsChan ( AstFitsChan *  rawFitsChan)
inlineexplicit

Construct a FitsChan from a raw AstFitsChan

Member Function Documentation

◆ clearCard()

void ast::FitsChan::clearCard ( )
inline

Rewind the card index to the beginning.

◆ delFits()

void ast::FitsChan::delFits ( )
inline

Delete the current FITS card.

The current card may be selected using the Card attribute (if its index is known) or by using findFits (if only the FITS keyword is known). After deletion, the following card becomes the current card.

◆ emptyFits()

void ast::FitsChan::emptyFits ( )
inline

Delete all cards and associated information from a FitsChan

Notes

  • This method simply deletes the cards currently in the FitsChan. Unlike astWriteFits, they are not first written out.
  • Any Tables or warnings stored in the FitsChan are also deleted.

◆ findFits()

FoundValue< std::string > ast::FitsChan::findFits ( std::string const &  name,
bool  inc 
)

Search 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.

Warning
this is very different than the getFitsX methods such as getFitsS, whose search wraps around. In order to search all keys using findFits you must first call clearCard.

If the search is successful (i.e. a card is found which matches the template), the contents of the card are returned and the Card attribute is adjusted to identify the card found (if inc false) or the one following it (if inc is true).

If the search is not successful, the Card attribute is set to the "end-of-file".

Parameters
[in]nameThe 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".
[in]incIf false (and the search is successful), the FitsChan's Card attribute will be set to the index of the card that was found. If true, however, the Card attribute will be incremented to identify the card which follows the one found.
Returns
data as a FoundValue

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).

Examples

auto foundvalue = fitschan.findFits("%f", true)

Return the current FITS card and advance the @ref FitsChan_Card "Card" attribute
to the card that follows (the "%f" template matches any keyword).

`auto foundvalue = fitschan.findFits("BITPIX", false)

Return the next FITS card with the "BITPIX" keyword
and leave the @ref FitsChan_Card "Card" attribute pointing to it.
You might wish to then call `setFitsI(...)` to modify its value.

auto foundvalue = fitscan.findFits("COMMENT", true)

Return the next COMMENT card and advance the @ref FitsChan_Card "Card" attribute
to the card that follows.

auto foundvalue = fitschan.findFits("CRVAL%1d", true)

Return the next keyword of the form "CRVALi" (for example,
any of the keywords "CRVAL1", "CRVAL2" or "CRVAL3" would be matched).
Advance the @ref FitsChan_Card "Card" attribute to the card that follows.

◆ getAllCardNames()

std::vector< std::string > ast::FitsChan::getAllCardNames ( )

Get the name of all cards, in order, starting from the first card

Not "const" because the code changes the index of the current card while operating (but restores the original index when done).

◆ getAllWarnings()

std::string ast::FitsChan::getAllWarnings ( ) const
inline

Get AllWarnings: a space separated list of all the conditions names recognized by the Warnings attribute.

◆ getCard()

int ast::FitsChan::getCard ( ) const
inline

Get Card: the index of the current card, where 1 is the first card.

◆ getCardComm()

std::string ast::FitsChan::getCardComm ( ) const
inline

Get CardComm: the comment of the current card

◆ getCardName()

std::string ast::FitsChan::getCardName ( ) const
inline

Get CardName: the keyword name of the current card

◆ getCardType()

CardType ast::FitsChan::getCardType ( ) const
inline

Get CardType: data type of the current FITS card

◆ getCarLin()

bool ast::FitsChan::getCarLin ( ) const
inline

Get CarLin: ignore spherical rotations on CAR projections?

◆ getCDMatrix()

bool ast::FitsChan::getCDMatrix ( ) const
inline

Get CDMatrix: use CDi_j keywords to represent pixel scaling, rotation, etc?

◆ getClean()

bool ast::FitsChan::getClean ( ) const
inline

Get Clean: remove cards used whilst reading even if an error occurs?

◆ getDefB1950()

bool ast::FitsChan::getDefB1950 ( ) const
inline

Get DefB1950: use FK4 B1950 as default equatorial coordinates?

◆ getEncoding()

std::string ast::FitsChan::getEncoding ( ) const
inline

Get Encoding: the encoding system to use when AST Objects are stored as FITS header cards in a FitsChan.

◆ getFitsAxisOrder()

std::string ast::FitsChan::getFitsAxisOrder ( ) const
inline

Get FitsAxisOrder: the order for the WCS axes in any new FITS-WCS headers created using Channel::write.

◆ getFitsCF()

FoundValue< std::complex< double > > ast::FitsChan::getFitsCF ( std::string const &  name = "",
std::complex< double >  defval = {0, 0} 
) const

Get the value of a complex double card

Parameters
[in]nameName of keyword, or empty for the current card
[in]defvalValue to return if keyword not found
Returns
value as a FoundValue, where found is false if the keyword was not found

Notes

  • If the requested card is found, it becomes the current card; otherwise the current card is left pointing at the end-of-file
  • If the stored keyword values is not of the requested type, it is converted (if possible) into the requested type
  • If the keyword is found but has no associated value, an error is reported. If necessary, the testFits function can be used to determine if the keyword has a defined value, prior to calling this function.

◆ getFitsCN()

FoundValue< std::string > ast::FitsChan::getFitsCN ( std::string const &  name = "",
std::string  defval = "" 
) const

Get the value of a CONTINUE card

CONTINUE cards are treated like string values, but are encoded without an equals sign.

Parameters
[in]nameName of keyword, or empty for the current card
[in]defvalvalue to return if keyword not found
Returns
value as a FoundValue, where found is false if the keyword was not found

Notes

  • If the requested card is found, it becomes the current card; otherwise the current card is left pointing at the end-of-file
  • If the stored keyword values is not of the requested type, it is converted (if possible) into the requested type
  • If the keyword is found but has no associated value, an error is reported. If necessary, the testFits function can be used to determine if the keyword has a defined value, prior to calling this function.

◆ getFitsDigits()

int ast::FitsChan::getFitsDigits ( ) const
inline

Get FitsDigits: digits of precision for floating-point FITS values.

◆ getFitsF()

FoundValue< double > ast::FitsChan::getFitsF ( std::string const &  name = "",
double  defval = 0 
) const

Get the value of a double card

Parameters
[in]nameName of keyword, or empty for the current card
[in]defvalvalue to return if keyword not found
Returns
value as a FoundValue, where found is false if the keyword was not found

Notes

  • If the requested card is found, it becomes the current card; otherwise the current card is left pointing at the end-of-file
  • If the stored keyword values is not of the requested type, it is converted (if possible) into the requested type
  • If the keyword is found but has no associated value, an error is reported. If necessary, the testFits function can be used to determine if the keyword has a defined value, prior to calling this function.

◆ getFitsI()

FoundValue< int > ast::FitsChan::getFitsI ( std::string const &  name = "",
int  defval = 0 
) const

Get the value of a int card

Parameters
[in]nameName of keyword, or empty for the current card
[in]defvalvalue to return if keyword not found
Returns
value as a FoundValue, where found is false if the keyword was not found

Notes

  • If the requested card is found, it becomes the current card; otherwise the current card is left pointing at the end-of-file
  • If the stored keyword values is not of the requested type, it is converted (if possible) into the requested type
  • If the keyword is found but has no associated value, an error is reported. If necessary, the testFits function can be used to determine if the keyword has a defined value, prior to calling this function.

◆ getFitsL()

FoundValue< bool > ast::FitsChan::getFitsL ( std::string const &  name = "",
bool  defval = false 
) const

Get the value of a bool card

Parameters
[in]nameName of keyword, or empty for the current card
[in]defvalValue to return if keyword not found
Returns
value as a FoundValue, where found is false if the keyword was not found

Notes

  • If the requested card is found, it becomes the current card; otherwise the current card is left pointing at the end-of-file
  • If the stored keyword values is not of the requested type, it is converted (if possible) into the requested type
  • If the keyword is found but has no associated value, an error is reported. If necessary, the testFits function can be used to determine if the keyword has a defined value, prior to calling this function.

◆ getFitsS()

FoundValue< std::string > ast::FitsChan::getFitsS ( std::string const &  name = "",
std::string  defval = "" 
) const

Get the value of a string card

Parameters
[in]nameName of keyword, or empty for the current card
[in]defvalValue to return if keyword not found
Returns
value as a FoundValue, where found is false if the keyword was not found

Notes

  • The FITS standard says that string keyword values should be padded with trailing spaces if they are shorter than 8 characters. For this reason, trailing spaces are removed from the returned string if the original string (including any trailing spaces) contains 8 or fewer characters. Trailing spaces are not removed from longer strings.
  • If the requested card is found, it becomes the current card; otherwise the current card is left pointing at the end-of-file
  • If the stored keyword values is not of the requested type, it is converted (if possible) into the requested type
  • If the keyword is found but has no associated value, an error is reported. If necessary, the testFits function can be used to determine if the keyword has a defined value, prior to calling this function.

◆ getFitsTol()

double ast::FitsChan::getFitsTol ( ) const
inline

Get FitsTol: Tolerance used for writing a FrameSet using a foreign encoding

◆ getIwc()

bool ast::FitsChan::getIwc ( ) const
inline

Get Iwc: add a Frame describing Intermediate World Coords?

◆ getNCard()

int ast::FitsChan::getNCard ( ) const
inline

Get NCard: the number of cards

◆ getNKey()

int ast::FitsChan::getNKey ( ) const
inline

Get Nkey: the number of unique keywords

◆ getPolyTan()

int ast::FitsChan::getPolyTan ( ) const
inline

Get PolyTan: use PVi_m keywords to define distorted TAN projection?

◆ getSipOK()

bool ast::FitsChan::getSipOK ( ) const
inline

Get SipOK: use Spitzer Space Telescope keywords to define distortion?

◆ getSipReplace()

bool ast::FitsChan::getSipReplace ( ) const
inline

Get SipReplace: ignore inverse SIP coefficients (replacing them with fit coefficients or an iterative inverse)?

◆ getTables()

std::shared_ptr< KeyMap > ast::FitsChan::getTables ( ) const
inline

◆ getTabOK()

int ast::FitsChan::getTabOK ( ) const
inline

Get TabOK: should the FITS "-TAB" algorithm be recognised?

◆ getWarnings()

std::string ast::FitsChan::getWarnings ( ) const
inline

Get Warnings attribute, which controls the issuing of warnings about selected conditions when an Object or keyword is read from or written to a FitsChan.

◆ operator=() [1/2]

FitsChan & ast::FitsChan::operator= ( FitsChan &&  )
default

◆ operator=() [2/2]

FitsChan & ast::FitsChan::operator= ( FitsChan const &  )
delete

◆ purgeWcs()

void ast::FitsChan::purgeWcs ( )
inline

Delete 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.

◆ putCards()

void ast::FitsChan::putCards ( std::string const &  cards)
inline

Replace all FITS header cards.

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. This means that a subsequent invocation of read can be made immediately without the need to re-wind the FitsChan first.

Parameters
[in]cardsA 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.

◆ putFits()

void ast::FitsChan::putFits ( std::string const &  card,
bool  overwrite 
)
inline

Store a FITS header card in a FitsChan.

The card is either inserted before the current card or over-writes the current card, depending on overwrite.

Parameters
[in]cardA 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.
[in]overwriteif false, the new card is inserted in before the current card. If true 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.

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.

◆ readFits()

void ast::FitsChan::readFits ( )
inline

Read cards from the source and store them in the FitsChan.

This normally happens once-only, when the FitsChan is accessed for the first time. This function provides a means of forcing a re-read of the external source, and may be useful if (say) new cards have been deposited into the external source. Any new cards read from the source are appended to the end of the current contents of the FitsChan.

Notes

  • This is a no-op if the Stream has no source.

◆ retainFits()

void ast::FitsChan::retainFits ( )
inline

Keep the current card when an Object is read that uses the card.

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 Object. Any cards that are irrelevant to the creation of the Object are retained whether or not they are flagged.

◆ setCard()

void ast::FitsChan::setCard ( int  ind)
inline

Set Card: the index of the current card, where 1 is the first card.

◆ setCarLin()

void ast::FitsChan::setCarLin ( bool  cdMatrix)
inline

Set CarLin: ignore spherical rotations on CAR projections?

◆ setCDMatrix()

void ast::FitsChan::setCDMatrix ( bool  cdMatrix)
inline

Get CDMatrix: Use CDi_j keywords to represent pixel scaling, rotation, etc?

◆ setClean()

void ast::FitsChan::setClean ( bool  clean)
inline

Set Clean: remove cards used whilst reading even if an error occurs?

◆ setDefB1950()

void ast::FitsChan::setDefB1950 ( bool  defB1950)
inline

Set DefB1950: use FK4 B1950 as default equatorial coordinates?

◆ setEncoding()

void ast::FitsChan::setEncoding ( std::string const &  encoding)
inline

Set Encoding: the encoding system to use when AST Objects are stored as FITS header cards in a FitsChan.

◆ setFitsAxisOrder()

void ast::FitsChan::setFitsAxisOrder ( std::string const &  order)
inline

Set FitsAxisOrder: the order for the WCS axes in any new FITS-WCS headers created using Channel::write.

◆ setFitsCF()

void ast::FitsChan::setFitsCF ( std::string const &  name,
std::complex< double >  value,
std::string const &  comment = "",
bool  overwrite = false 
)
inline

Create a new card of type std::complex<double>, possibly overwriting the current card

Parameters
[in]nameName of keyword for the new card. This may be a complete FITS header card, in which case the keyword to use is extracted from it.
[in]valuethe value of the card.
[in]commentComment to associated with the keyword. If blank, then any comment included in the string supplied for the name parameter is used instead. If name contains no comment, then any existing comment in the card being over-written is retained. Otherwise, no comment is stored with the card.
[in]overwriteif true the new card formed from the supplied keyword name, value and comment over-writes the current card, and the current card is incremented to refer to the next card (see the Card attribute). If false, the new card is inserted before the current card and the current card is left unchanged. In either case, if the current card on entry points to the "end-of-file", the new card is appended to the end of the list.

◆ setFitsCM()

void ast::FitsChan::setFitsCM ( std::string const &  comment,
bool  overwrite = false 
)
inline

Create a new comment card, possibly overwriting the current card

The card will have a name of " " (eight spaces) and no equals sign. There is presently no way to generate a card with name HISTORY or COMMENT, but FITS treats those essentially the same as cards with blank names.

Parameters
[in]commentComment to associated with the keyword.
[in]overwriteif true the new card formed from the supplied keyword name, value and comment over-writes the current card, and the current card is incremented to refer to the next card (see the Card attribute). If false, the new card is inserted before the current card and the current card is left unchanged. In either case, if the current card on entry points to the "end-of-file", the new card is appended to the end of the list.

Notes

  • If, on exit, there are no cards following the card written by this function, then the current card is left pointing at the "end-of-file" .
  • An error will be reported if the keyword name does not conform to FITS requirements.

◆ setFitsCN()

void ast::FitsChan::setFitsCN ( std::string const &  name,
std::string  value,
std::string const &  comment = "",
bool  overwrite = false 
)
inline

Create a new "CONTINUE" card, possibly overwriting the current card

"CONTINUE" cards are treated like string values, but are encoded without an equals sign.

Parameters
[in]nameName of keyword for the new card. This may be a complete FITS header card, in which case the keyword to use is extracted from it.
[in]valuethe value of the card.
[in]commentComment to associated with the keyword. If blank, then any comment included in the string supplied for the name parameter is used instead. If name contains no comment, then any existing comment in the card being over-written is retained. Otherwise, no comment is stored with the card.
[in]overwriteif true the new card formed from the supplied keyword name, value and comment over-writes the current card, and the current card is incremented to refer to the next card (see the Card attribute). If false, the new card is inserted before the current card and the current card is left unchanged. In either case, if the current card on entry points to the "end-of-file", the new card is appended to the end of the list.

Notes

  • If, on exit, there are no cards following the card written by this function, then the current card is left pointing at the "end-of-file" .
  • An error will be reported if the keyword name does not conform to FITS requirements.

◆ setFitsDigits()

void ast::FitsChan::setFitsDigits ( int  digits)
inline

Set FitsDigits: digits of precision for floating-point FITS values

◆ setFitsF()

void ast::FitsChan::setFitsF ( std::string const &  name,
double  value,
std::string const &  comment = "",
bool  overwrite = false 
)
inline

Create a new card of type double, possibly overwriting the current card

Parameters
[in]nameName of keyword for the new card. This may be a complete FITS header card, in which case the keyword to use is extracted from it.
[in]valuethe value of the card.
[in]commentComment to associated with the keyword. If blank, then any comment included in the string supplied for the name parameter is used instead. If name contains no comment, then any existing comment in the card being over-written is retained. Otherwise, no comment is stored with the card.
[in]overwriteif true the new card formed from the supplied keyword name, value and comment over-writes the current card, and the current card is incremented to refer to the next card (see the Card attribute). If false, the new card is inserted before the current card and the current card is left unchanged. In either case, if the current card on entry points to the "end-of-file", the new card is appended to the end of the list.

Notes

  • If, on exit, there are no cards following the card written by this function, then the current card is left pointing at the "end-of-file" .
  • An error will be reported if the keyword name does not conform to FITS requirements.

◆ setFitsI()

void ast::FitsChan::setFitsI ( std::string const &  name,
int  value,
std::string const &  comment = "",
bool  overwrite = false 
)
inline

Create a new card of type int, possibly overwriting the current card

Parameters
[in]nameName of keyword for the new card. This may be a complete FITS header card, in which case the keyword to use is extracted from it.
[in]valuethe value of the card.
[in]commentComment to associated with the keyword. If blank, then any comment included in the string supplied for the name parameter is used instead. If name contains no comment, then any existing comment in the card being over-written is retained. Otherwise, no comment is stored with the card.
[in]overwriteif true the new card formed from the supplied keyword name, value and comment over-writes the current card, and the current card is incremented to refer to the next card (see the Card attribute). If false, the new card is inserted before the current card and the current card is left unchanged. In either case, if the current card on entry points to the "end-of-file", the new card is appended to the end of the list.

Notes

  • If, on exit, there are no cards following the card written by this function, then the current card is left pointing at the "end-of-file" .
  • An error will be reported if the keyword name does not conform to FITS requirements.

◆ setFitsL()

void ast::FitsChan::setFitsL ( std::string const &  name,
bool  value,
std::string const &  comment = "",
bool  overwrite = false 
)
inline

Create a new card of type bool, possibly overwriting the current card

Parameters
[in]nameName of keyword for the new card. This may be a complete FITS header card, in which case the keyword to use is extracted from it.
[in]valuethe value of the card.
[in]commentComment to associated with the keyword. If blank, then any comment included in the string supplied for the name parameter is used instead. If name contains no comment, then any existing comment in the card being over-written is retained. Otherwise, no comment is stored with the card.
[in]overwriteif true the new card formed from the supplied keyword name, value and comment over-writes the current card, and the current card is incremented to refer to the next card (see the Card attribute). If false, the new card is inserted before the current card and the current card is left unchanged. In either case, if the current card on entry points to the "end-of-file", the new card is appended to the end of the list.

Notes

  • If, on exit, there are no cards following the card written by this function, then the current card is left pointing at the "end-of-file" .
  • An error will be reported if the keyword name does not conform to FITS requirements.

◆ setFitsS()

void ast::FitsChan::setFitsS ( std::string const &  name,
std::string  value,
std::string const &  comment = "",
bool  overwrite = false 
)
inline

Create a new card of type string, possibly overwriting the current card

Parameters
[in]nameName of keyword for the new card. This may be a complete FITS header card, in which case the keyword to use is extracted from it.
[in]valuethe value of the card.
[in]commentComment to associated with the keyword. If blank, then any comment included in the string supplied for the name parameter is used instead. If name contains no comment, then any existing comment in the card being over-written is retained. Otherwise, no comment is stored with the card.
[in]overwriteif true the new card formed from the supplied keyword name, value and comment over-writes the current card, and the current card is incremented to refer to the next card (see the Card attribute). If false, the new card is inserted before the current card and the current card is left unchanged. In either case, if the current card on entry points to the "end-of-file", the new card is appended to the end of the list.

Notes

  • The FITS standard says that string keyword values should be padded with trailing spaces if they are shorter than 8 characters. For this reason, trailing spaces are removed from the returned string if the original string (including any trailing spaces) contains 8 or fewer characters. Trailing spaces are not removed from longer strings.
  • If the requested card is found, it becomes the current card; otherwise the current card is left pointing at the end-of-file
  • If the stored keyword values is not of the requested type, it is converted (if possible) into the requested type
  • If the keyword is found but has no associated value, an error is reported. If necessary, the testFits function can be used to determine if the keyword has a defined value, prior to calling this function.

◆ setFitsTol()

void ast::FitsChan::setFitsTol ( double  tol)
inline

Set FitsTol: Tolerance used for writing a FrameSet using a foreign encoding

◆ setFitsU()

void ast::FitsChan::setFitsU ( std::string const &  name,
std::string const &  comment = "",
bool  overwrite = false 
)
inline

Create a new card with an undefined value, possibly overwriting the current card

Parameters
[in]nameName of keyword for the new card. This may be a complete FITS header card, in which case the keyword to use is extracted from it.
[in]commentComment to associated with the keyword. If blank, then any comment included in the string supplied for the name parameter is used instead. If name contains no comment, then any existing comment in the card being over-written is retained. Otherwise, no comment is stored with the card.
[in]overwriteif true the new card formed from the supplied keyword name, value and comment over-writes the current card, and the current card is incremented to refer to the next card (see the Card attribute). If false, the new card is inserted before the current card and the current card is left unchanged. In either case, if the current card on entry points to the "end-of-file", the new card is appended to the end of the list.

Notes

  • To assign a new value for an existing keyword, first find the card describing the keyword using findFits, and then use the appropriate setFits function to over-write the old value.
  • If, on exit, there are no cards following the card written by this function, then the current card is left pointing at the "end-of-file" .
  • An error will be reported if the keyword name does not conform to FITS requirements.

◆ setIwc()

void ast::FitsChan::setIwc ( bool  iwcs)
inline

Set Iwc: add a Frame describing Intermediate World Coords?

◆ setPolyTan()

void ast::FitsChan::setPolyTan ( int  polytan)
inline

Set PolyTan: use PVi_m keywords to define distorted TAN projection?

◆ setSipOK()

void ast::FitsChan::setSipOK ( bool  sipOK)
inline

Set SipOK: use Spitzer Space Telescope keywords to define distortion?

◆ setSipReplace()

void ast::FitsChan::setSipReplace ( bool  replace)
inline

Set SipReplace: ignore inverse SIP coefficients (replacing them with fit coefficients or an iterative inverse)?

◆ setTabOK()

void ast::FitsChan::setTabOK ( int  tabOK)
inline

Set TabOK: should the FITS "-TAB" algorithm be recognised?

◆ setWarnings()

void ast::FitsChan::setWarnings ( std::string const &  warnings)
inline

Set Warnings attribute, which controls the issuing of warnings about selected conditions when an Object or keyword is read from or written to a FitsChan.

◆ showFits()

void ast::FitsChan::showFits ( ) const
inline

Write all the cards in the channel to standard output

◆ testFits()

FitsKeyState ast::FitsChan::testFits ( std::string const &  name = "") const

Determine if a card is present, and if so, whether it has a value.

Parameters
[in]nameName of keyword, or empty for the current card

Notes

  • This function does not change the current card.
  • If name is not empty then 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.

◆ writeFits()

void ast::FitsChan::writeFits ( )
inline

Write out all cards currently in the channel and clear the channel.


The documentation for this class was generated from the following files: