00001 //# Fits.h: The fits module -- FITS related classes. 00002 //# Copyright (C) 2005 00003 //# Associated Universities, Inc. Washington DC, USA. 00004 //# 00005 //# This library is free software; you can redistribute it and/or modify it 00006 //# under the terms of the GNU Library General Public License as published by 00007 //# the Free Software Foundation; either version 2 of the License, or (at your 00008 //# option) any later version. 00009 //# 00010 //# This library is distributed in the hope that it will be useful, but WITHOUT 00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 00012 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public 00013 //# License for more details. 00014 //# 00015 //# You should have received a copy of the GNU Library General Public License 00016 //# along with this library; if not, write to the Free Software Foundation, 00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA. 00018 //# 00019 //# Correspondence concerning AIPS++ should be addressed as follows: 00020 //# Internet email: aips2-request@nrao.edu. 00021 //# Postal address: AIPS++ Project Office 00022 //# National Radio Astronomy Observatory 00023 //# 520 Edgemont Road 00024 //# Charlottesville, VA 22903-2475 USA 00025 //# 00026 //# $Id$ 00027 00028 #ifndef FITS_FITS_H 00029 #define FITS_FITS_H 00030 00031 #include <casacore/casa/aips.h> 00032 #include <casacore/fits/FITS/BasicFITS.h> 00033 #include <casacore/fits/FITS/BinTable.h> 00034 #include <casacore/fits/FITS/blockio.h> 00035 #include <casacore/fits/FITS/CopyRecord.h> 00036 #include <casacore/fits/FITS/FITS2.h> 00037 #include <casacore/fits/FITS/FITSDateUtil.h> 00038 #include <casacore/fits/FITS/FITSError.h> 00039 #include <casacore/fits/FITS/FITSFieldCopier.h> 00040 #include <casacore/fits/FITS/FITSHistoryUtil.h> 00041 #include <casacore/fits/FITS/FITSKeywordUtil.h> 00042 #include <casacore/fits/FITS/FITSMultiTable.h> 00043 #include <casacore/fits/FITS/FITSSpectralUtil.h> 00044 #include <casacore/fits/FITS/FITSTable.h> 00045 #include <casacore/fits/FITS/FITSTimedTable.h> 00046 #include <casacore/fits/FITS/fits.h> 00047 #include <casacore/fits/FITS/fitsio.h> 00048 #include <casacore/fits/FITS/hdu.h> 00049 #include <casacore/fits/FITS/SDFITSTable.h> 00050 00051 namespace casacore { //# NAMESPACE CASACORE - BEGIN 00052 00053 // <module> 00054 // 00055 // <summary> 00056 // Classes and global functions for system use 00057 // </summary> 00058 00059 // <reviewed reviewer="" date="" demos=""> 00060 // </reviewed> 00061 // 00062 // <synopsis> 00063 // 00064 // This module is a bag of related fits classes and 00065 // global functions. 00066 // 00067 // The following functionality is available: 00068 // <ol> 00069 // <li> Class <linkto class=FITSFieldCopier:description> 00070 // FITSFieldCopier</linkto> 00071 // A FITSFieldCopier for copying Array RecordFields to FitsFields. 00072 // <li> Class <linkto class=AsciiTableExtension:description> 00073 // AsciiTableExtension</linkto> 00074 // (ascii) TABLE extension. 00075 // <li> Class <linkto class=BinaryTable:description> 00076 // BinaryTable</linkto> 00077 // BinaryTable is used to translate a FITS binary table to a Casacore Table. 00078 // BinaryTable inherits from the FITS BinaryTableExtension class and its 00079 // primary use is to convert that class to a Casacore Table. 00080 // The class starts with an already existing FitsInput object, which should 00081 // be set at a BinaryTableExtension HDU. Member functions provide a TableDesc 00082 // appropriate for the FITS data (to help in constructing a Casacore Table 00083 // compatible with the BinaryTableExtension), a Table containing the 00084 // current row of FITS data and a Table containing the next row of FITS data 00085 // (which can be used to step through the FitsInput, copying each row 00086 // using the RowCopier class), and a Table containin the entire FITS binary 00087 // table from the current row to the end of the table. 00088 // <motivation> 00089 // We need a way to get FITS data into Casacore Tables. 00090 // </motivation> 00091 // <li> Class <linkto class=BinaryTableExtension:description> 00092 // BinaryTableExtension</linkto> 00093 // BINTABLE extension. 00094 // <li> Class <linkto class=BlockInput:description> 00095 // BlockInput</linkto> 00096 // fixed-length blocked sequential input base class. 00097 // <li> Class <linkto class=BlockIO:description> 00098 // BlockIO</linkto> 00099 // fixed-length blocked sequentual I/O base class. 00100 // BlockIO is a low level base class that implements fixed-length 00101 // blocked sequential I/O. Its derived classes, BlockInput and BlockOutput 00102 // are used by the FitsInput and FitsOutput classes. Users will hardly ever 00103 // need to use this class directly. 00104 // <li> Class <linkto class=BlockOutput:description> 00105 // BlockOutput</linkto> 00106 // fixed-length blocked sequential output base class. 00107 // <li> Class <linkto class=ConstFitsKeywordList:description> 00108 // ConstFitsKeywordList</linkto> 00109 // list of read-only FITS keywords. 00110 // <li> Class <linkto class=CopyRecordToRecord:description> 00111 // CopyRecordToRecord</linkto> 00112 // Copies fields between Records, possibly to fields with another name. 00113 // <li> Class <linkto class=CopyRecordToTable:description> 00114 // CopyRecordToTable</linkto> 00115 // Copies fields from a Record to columns of a Table. 00116 // This class should be generalized, and made better. It is the analog of 00117 // RowCopier, i.e. it copies all the fields from some Record to certain 00118 // columns of a table. The mapping from fields to columns occurs at 00119 // construction of the CopyRecordToTable object. 00120 // <motivation> 00121 // This class should be generalized, and made better. It is the analog of 00122 // RowCopier, i.e. it copies all the fields from some Record to certain 00123 // columns of a table. The mapping from fields to columns occurs at 00124 // construction of the CopyRecordToTable object. 00125 // </motivation> 00126 // <li> Class <linkto class=ExtensionHeaderDataUnit:description> 00127 // ExtensionHeaderDataUnit</linkto> 00128 // Base class for generalized exentensions HDU. 00129 // <li> Class <linkto class=FITS:description> 00130 // FITS</linkto> 00131 // Static functions and enumerations. 00132 // Many of the static functions are utility functions used internally in the 00133 // implementation of the member functions of the FITS classes. They are placed 00134 // in a single class to encapsulate them and to avoid adding many names to the 00135 // global name space. More important, from the user's perspective, are the 00136 // enumerations. They form the basic vocabulary of a FITS application. For example, 00137 // instead of referring to the FITS <src>NAXIS</src> keyword, 00138 // <src>FITS::NAXIS</src> should be used. 00139 // <li> Class <linkto class=FITSDateUtil:description> 00140 // FITSDateUtil</linkto> 00141 // A class with static functions to help deal with FITS dates 00142 // This is a collection of static utility functions for creating and 00143 // interpreting FITS date keywords (e.g. DATE-OBS). 00144 // Its never necessary to construct a FITSDateUtil, just use the 00145 // static functions to help handle FITS dates. 00146 // <motivation> 00147 // The strings that make up the value of FITS dates have a 00148 // precise format. This class encompasses knowlege of the formats 00149 // used and hopefully simplifies their creation and conversion 00150 // to and from Casacore MVTimes. 00151 // </motivation> 00152 // <li> Class <linkto class=FITSError:description> 00153 // FITSError</linkto> 00154 // Default FITS error handling function, typdef, and enumeration. 00155 // FITSError contains the enumeration specifying the possible error 00156 // message levels. It also contains the default error handling function 00157 // for the FITS classes. 00158 // <motivation> 00159 // Originally, FITS error message were simply sent to an ostream. In 00160 // order to have these error messages go to the Casacore logger by default, 00161 // this class was added. This was made a separate class because both 00162 // BlockIo and FITS need to use this class. The anticipated replacements 00163 // for the current FITS classes use a somewhat similar scheme. 00164 // </motivation> 00165 // <li> Class <linkto class=FITSFieldCopier:description> 00166 // FITSFieldCopier</linkto> 00167 // Virtual base class for copying RORecordFields to FitsFields. 00168 // <li> Class <linkto class=FITSGroupWriter:description> 00169 // FITSGroupWriter</linkto> 00170 // Simplified interface to create and write to FITS random groups. 00171 // Like FITSTableWriter except that this must be the first HDU and 00172 // all "columns" in the description must have the same type, i.e. float. 00173 // <li> Class <linkto class=FITSHistoryUtil:description> 00174 // FITSHistoryUtil</linkto> 00175 // A class with static functions to help deal with FITS History cards. 00176 // This is a collection of static utility functions for use with FITS 00177 // HISTORY keywords. 00178 // Manipulate HISTORY information. FITS HISTORY cards are interconverted with 00179 // String as follows: 00180 // <ul> 00181 // <li> 'HISTORY ' and trailing blanks are removed from each card. 00182 // <li> Continuation cards are CARDS that have '>' in the first line. 00183 // <li> A string is made by concatenating the leading card and all continuation 00184 // cards. 00185 // </ul> 00186 // <motivation> 00187 // The FitsKeywordList class can be somewhat tedious to use, as it deals with, 00188 // e.g., char* pointers rather than Strings. This class makes it easy to 00189 // interconvert between the HISTORY keywords and a Vector of related history 00190 // information. 00191 // </motivation> 00192 // <li> Class <linkto class=FITSKeywordUtil:description> 00193 // FITSKeywordUtil</linkto> 00194 // A class with static functions to help deal with FITS Keywords. 00195 // This class provides functions to conveniently interconvert between Casacore 00196 // types and a FitsKeywordList which is needed by the native FITS classes. 00197 // It is more convenient to maintain the list within Casacore 00198 // as a Record, so we only need methods to turn a FitsKeywordList into a 00199 // Record, and vice versa. 00200 // Note that it is not necessary to construct a FITSKeywordUtil object 00201 // since you can use its static functions directly. 00202 // <motivation> 00203 // The FitsKeywordList class can be somewhat tedious to use, as it deals with, 00204 // e.g., char* pointers rather than Strings. This class makes it easy to 00205 // interconvert between FITS keywords and Casacore types. 00206 // </motivation> 00207 // <li> Class <linkto class=FITSMultiTable:description> 00208 // FITSMultiTable</linkto> 00209 // View multiple FITS files as a single table. 00210 // A FITSMultiTable is used to view a collection of FITS files on disk as a 00211 // single Table. That is, when next() is called, when one Table ends the next 00212 // is reopened until all files are exhausted. The FITS files must all have the 00213 // same description. Something clever should be done about the keywords. 00214 // <li> Class <linkto class=FITSSpectralUtil:description> 00215 // FITSSpectralUtil</linkto> 00216 // A class with static functions to help deal with FITS spectral axes. 00217 // This class provides functions to extract information from a FITS 00218 // header about the spectral axis, to setup a FITS header with 00219 // appropriate information for the spectral axis, and to translate 00220 // to and from the MFrequency refrence frame codes and their FITS 00221 // equivalents. 00222 // It is never necessary to construct a FITSSpectralUtil, just use the 00223 // static functions to help handle FITS Spectral axes. 00224 // <motivation> 00225 // This is designed to be used after the keywords have been extracted from 00226 // the FITS file using the <linkto class=FITSKeywordUtil>FITSKeywordUtil</linkto> 00227 // class. Extracting spectral axis and related information requires detailed 00228 // knowledge of FITS conventions that this class strives to encapsulize. 00229 // </motivation> 00230 // <li> Class <linkto class=FITSTable:description> 00231 // FITSTable</linkto> 00232 // Attach a FITSTabular to a binary or ASCII table. 00233 // FITSTable is a FITSTabular which is attached to a FITS table (on disk only 00234 // presently), either Binary or ASCII. 00235 // <li> Class <linkto class=FITSTableWriter:description> 00236 // FITSTableWriter</linkto> 00237 // Simplified interface to create and write to a FITS Binary Table. 00238 // <li> Class <linkto class=FITSTabular:description> 00239 // FITSTabular</linkto> 00240 // Simplified interface to FITS tables with Casacore Look and Feel. 00241 // FITSTablular is an obstract base class which is used for read-only access to 00242 // tabular FITS-like data structures. 00243 // <li> Class <linkto class=FITSTimedTable:description> 00244 // FITSTimedTable</linkto> 00245 // FITSTimedTable is used to look at FITS tables which have a time column. In 00246 // particular, it peeks ahead, and knows the time of the currentRow and of the 00247 // nextRow. 00248 // It is constructed with a pointer to any FITSTabular. Presently, no memory 00249 // management is imposed to ensure that the pointer remains valid. 00250 // <li> Class <linkto class=FitsArray:description> 00251 // FitsArray</linkto> 00252 // FITS array of given type. 00253 // <li> Class <linkto class=FitsArray:description> 00254 // <src>FitsArray<FitsBit></src></linkto> 00255 // FITS array of FitsBit type. 00256 // <li> Class <linkto class=FitsBase:description> 00257 // FitsBase</linkto> 00258 // Base class fore FitsField. 00259 // <li> Class <linkto class=FitsBit:description> 00260 // FitsBit</linkto> 00261 // Helper class for FITS Binary Tables. 00262 // This class is not intended for general use. It only has meaning 00263 // in the context of FITS Binary tables. There its use is incorporated 00264 // into the concept of a FitsField, where FitsBit is given a specialized 00265 // interpretation. 00266 // <li> Class <linkto class=FitsDiskInput:description> 00267 // FitsDiskInput</linkto> 00268 // FITS input from disk. 00269 // <li> Class <linkto class=FitsDiskOutput:description> 00270 // FitsDiskOutput</linkto> 00271 // FITS output to disk. 00272 // <li> Class <linkto class=FitsField:description> 00273 // FitsField</linkto> 00274 // Helper class. 00275 // <li> Class <linkto class=FitsField:description> 00276 // <src>FitsField<FitsBit></src></linkto> 00277 // Helper class. 00278 // <li> Class <linkto class=FitsFPUtil:description> 00279 // FitsFPUtil</linkto> 00280 // Utility functions for floating point values. 00281 // <li> Class <linkto class=FitsInput:description> 00282 // FitsInput</linkto> 00283 // Fixed-length sequential blocked FITS input. 00284 // <li> Class <linkto class=FitsIO:description> 00285 // FitsIO</linkto> 00286 // sequential FITS I/O. 00287 // FitsIO is a base class that handles all the sequential blocked 00288 // FITS I/O. Special derived classes do the input and output. 00289 // No interpretation of the data is attempted here, there are 00290 // special FITS classes that handle syntax and interpretation. 00291 // <li> Class <linkto class=FitsKeyCardTranslator:description> 00292 // FitsKeyCardTranslator</linkto> 00293 // Translator between Keyword lists and fixed FITS cars. 00294 // <li> Class <linkto class=FitsKeyword:description> 00295 // FitsKeyword</linkto> 00296 // A FITS keyword contains a name, a value and a comment.. 00297 // <li> Class <linkto class=FitsKeywordList:description> 00298 // FitsKeywordList</linkto> 00299 // Linked list of FITS keywords. 00300 // <li> Class <linkto class=FitsLogical:description> 00301 // FitsLogical</linkto> 00302 // FitsLogical is a helper class that is not intended for general use. 00303 // <li> Class <linkto class=FitsNameResult:description> 00304 // FitsNameResult</linkto> 00305 // Analyse the name of a header card. 00306 // <li> Class <linkto class=FitsOutput:description> 00307 // FitsOutput</linkto> 00308 // Fixed-length sequential blocked FITS output. 00309 // <li> Class <linkto class=FitsParse:description> 00310 // FitsParse</linkto> 00311 // Parse a header card. 00312 // <li> Class <linkto class=FitsStdInput:description> 00313 // FitsStdInput</linkto> 00314 // FITS input from standard input. 00315 // <li> Class <linkto class=FitsStdOutput:description> 00316 // FitsStdOutput</linkto> 00317 // FITS output to standard output. 00318 // <li> Class <linkto class=FitsTape9Input:description> 00319 // FitsTape9Input</linkto> 00320 // FITS input from 9-track tape. 00321 // <li> Class <linkto class=FitsTape9Output:description> 00322 // FitsTape9Output</linkto> 00323 // FITS output to 9-track tape. 00324 // <li> Class <linkto class=FitsVADesc:description> 00325 // FitsVADesc</linkto> 00326 // Variable Length Array Descriptor. 00327 // <li> Class <linkto class=FitsValueResult:description> 00328 // FitsValueResult</linkto> 00329 // Analyse the value of a header card. 00330 // <li> Class <linkto class=HeaderDataUnit:description> 00331 // HeaderDataUnit</linkto> 00332 // Base class that defines a HDU. 00333 // The class HeaderDataUnit contains what is common to all 00334 // header-data-units, including the collection of keywords. 00335 // From this class a number of FITS header-data-units are 00336 // derived, each of them with their own rich assortment of 00337 // functions for accessing and manipulating data of specific types. 00338 // <li> Class <linkto class=ImageExtension:description> 00339 // ImageExtension</linkto> 00340 // IMAGE extension of given type. 00341 // <li> Class <linkto class=NoConvert:description> 00342 // NoConvert</linkto> 00343 // FITS templated helper class. 00344 // NoConvert is a template class that is not intended for 00345 // general use, it is used internally. 00346 // <li> Class <linkto class=PrimaryArray:description> 00347 // PrimaryArray</linkto> 00348 // Templated primary array base class of given type. 00349 // A Primary Data Array is represented by the following: 00350 // <srcblock> 00351 // <Type> data_array [NAXIS1][NAXIS2]...[NAXISN] 00352 // </srcblock> 00353 // For a PrimaryArray, dims() gives the number of dimensions 00354 // and dim(i) gives the value of the i-th dimension 00355 // WARNING! Multi-dimensional arrays are stored in FORTRAN order, 00356 // NOT in C order. Options on the store, copy, and move functions exist 00357 // to convert from one order to the other, if that is necessary. 00358 // 00359 // It is important to understand the proper sequence of operations with 00360 // respect to I/O and data access. For input, the `read()' functions 00361 // allocate an internal buffer of the appropriate size, if not already 00362 // allocated, as well as reading and converting data; a `read()' function 00363 // must be performed prior to accessing the data, i. e. before executing 00364 // any `()', `data()', `copy()', or `move()' function. For output, the 00365 // `store()' function similarly allocates an internal buffer before 00366 // transfering data, and must be executed prior to any data access or 00367 // `write()' function. Note: If you call any version of store(), do not 00368 // call set_next(). 00369 // 00370 // Writing portions of an array at a time, rather than the entire array, 00371 // is a special case. The `set_next()' function is provided for this 00372 // purpose. It declares the intention to write out the next N elements and 00373 // must be executed prior to any `data()' function. It allocates a buffer 00374 // of appropriate size, if not already allocated. Again, via the `data()' 00375 // functions, one accesses the array as if the entire array were in 00376 // memory. The `write()' function always writes the number of current 00377 // elements in the internal buffer. The sequence of operations for each 00378 // portion of the array written would be: 00379 // <ul> 00380 // <li> `set_next(N)', 00381 // <li> fill the array using `data(N)' or other `data()' functions 00382 // <li> `write(fout)'. 00383 // </ul> 00384 // The `set_next()' function must NOT be used with 00385 // `read()' or `store()' functions; unpredictable results will occur. 00386 // <li> Class <linkto class=PrimaryGroup:description> 00387 // PrimaryGroup</linkto> 00388 // Random Group datastructure. 00389 // <note role=warning> 00390 // Please note that the NOST has deprecated the Random Group 00391 // datastructure, it has been replaced by the much more powerfull 00392 // BINTABLE extension. 00393 // </note> 00394 // <li> Class <linkto class=ReservedFitsKeyword:description> 00395 // ReservedFitsKeyword</linkto> 00396 // Reserved FITS keyword. 00397 // <li> Class <linkto class=ReservedFitsKeywordCollection:description> 00398 // ReservedFitsKeywordCollection</linkto> 00399 // Collection of reserved FITS keywords. 00400 // <li> Class <linkto class=ScalarFITSFieldCopier:description> 00401 // ScalarFITSFieldCopier</linkto> 00402 // A FITSFieldCopier for copying scalar non-string RecordFields to FitsFields. 00403 // <li> Class <linkto class=SDFITSTable:description> 00404 // SDFITSTable</linkto> 00405 // SDFITSTable is derived from FITSTable. It contains additional 00406 // checks and behaviour appropriate to the Single Dish FITS Convention 00407 // hence this is a Single Dish FITS Table, or SDFITSTable. 00408 // This class behaves much like FITSTable. It additionally verifies 00409 // that the indicated HDU in the input FITS file follows the SDFITS 00410 // convention (it has all of the required columns) and it treats 00411 // keywords as virtual columns when appropriate. These virtual 00412 // columns will appear as fields in the currentRecord and description 00413 // and will NOT appear in the keywords. 00414 // <motivation> 00415 // It was useful to encapsulate this behaviour in a class so that 00416 // the checks on a valid SDFITS table and the treatment of keywords 00417 // as virtual columns would not need to appear everywhere it might 00418 // be used. 00419 // </motivation> 00420 // <li> Class <linkto class=StringFITSFieldCopier:description> 00421 // StringFITSFieldCopier</linkto> 00422 // A FITSFieldCopier for copying String RecordFields to FitsFields. 00423 // <li> Class <linkto class=VariableArrayFITSFieldCopier:description> 00424 // VariableArrayFITSFieldCopier</linkto> 00425 // Copy the current contents of the input RORecordFieldPtr to the output FitsField. 00426 // </ol> 00427 // 00428 // <note role=tip> You may want to look at the individual header files 00429 // to see whether you might not prefer to include only the header 00430 // files you really need; it may be more efficient to do so. 00431 // </note> 00432 // 00433 // </synopsis> 00434 // 00435 //# <todo asof="2005/06/20"> 00436 //# <li> 00437 //# </todo> 00438 // 00439 // </module> 00440 00441 00442 } //# NAMESPACE CASACORE - END 00443 00444 #endif 00445