FITS.h

Go to the documentation of this file.
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 
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1