casacore
FITS.h
Go to the documentation of this file.
1 //# Fits.h: The fits module -- FITS related classes.
2 //# Copyright (C) 2005
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //# $Id$
27 
28 #ifndef FITS_FITS_H
29 #define FITS_FITS_H
30 
31 #include <casacore/casa/aips.h>
32 #include <casacore/fits/FITS/BasicFITS.h>
33 #include <casacore/fits/FITS/BinTable.h>
34 #include <casacore/fits/FITS/blockio.h>
35 #include <casacore/fits/FITS/CopyRecord.h>
36 #include <casacore/fits/FITS/FITS2.h>
37 #include <casacore/fits/FITS/FITSDateUtil.h>
38 #include <casacore/fits/FITS/FITSError.h>
39 #include <casacore/fits/FITS/FITSFieldCopier.h>
40 #include <casacore/fits/FITS/FITSHistoryUtil.h>
41 #include <casacore/fits/FITS/FITSKeywordUtil.h>
42 #include <casacore/fits/FITS/FITSMultiTable.h>
43 #include <casacore/fits/FITS/FITSSpectralUtil.h>
44 #include <casacore/fits/FITS/FITSTable.h>
45 #include <casacore/fits/FITS/FITSTimedTable.h>
46 #include <casacore/fits/FITS/fits.h>
47 #include <casacore/fits/FITS/fitsio.h>
48 #include <casacore/fits/FITS/hdu.h>
49 #include <casacore/fits/FITS/SDFITSTable.h>
50 
51 namespace casacore { //# NAMESPACE CASACORE - BEGIN
52 
53 // <module>
54 //
55 // <summary>
56 // Classes and global functions for system use
57 // </summary>
58 
59 // <reviewed reviewer="" date="" demos="">
60 // </reviewed>
61 //
62 // <synopsis>
63 //
64 // This module is a bag of related fits classes and
65 // global functions.
66 //
67 // The following functionality is available:
68 // <ol>
69 // <li> Class <linkto class=FITSFieldCopier:description>
70 // FITSFieldCopier</linkto>
71 // A FITSFieldCopier for copying Array RecordFields to FitsFields.
72 // <li> Class <linkto class=AsciiTableExtension:description>
73 // AsciiTableExtension</linkto>
74 // (ascii) TABLE extension.
75 // <li> Class <linkto class=BinaryTable:description>
76 // BinaryTable</linkto>
77 // BinaryTable is used to translate a FITS binary table to a Casacore Table.
78 // BinaryTable inherits from the FITS BinaryTableExtension class and its
79 // primary use is to convert that class to a Casacore Table.
80 // The class starts with an already existing FitsInput object, which should
81 // be set at a BinaryTableExtension HDU. Member functions provide a TableDesc
82 // appropriate for the FITS data (to help in constructing a Casacore Table
83 // compatible with the BinaryTableExtension), a Table containing the
84 // current row of FITS data and a Table containing the next row of FITS data
85 // (which can be used to step through the FitsInput, copying each row
86 // using the RowCopier class), and a Table containin the entire FITS binary
87 // table from the current row to the end of the table.
88 // <motivation>
89 // We need a way to get FITS data into Casacore Tables.
90 // </motivation>
91 // <li> Class <linkto class=BinaryTableExtension:description>
92 // BinaryTableExtension</linkto>
93 // BINTABLE extension.
94 // <li> Class <linkto class=BlockInput:description>
95 // BlockInput</linkto>
96 // fixed-length blocked sequential input base class.
97 // <li> Class <linkto class=BlockIO:description>
98 // BlockIO</linkto>
99 // fixed-length blocked sequentual I/O base class.
100 // BlockIO is a low level base class that implements fixed-length
101 // blocked sequential I/O. Its derived classes, BlockInput and BlockOutput
102 // are used by the FitsInput and FitsOutput classes. Users will hardly ever
103 // need to use this class directly.
104 // <li> Class <linkto class=BlockOutput:description>
105 // BlockOutput</linkto>
106 // fixed-length blocked sequential output base class.
107 // <li> Class <linkto class=ConstFitsKeywordList:description>
108 // ConstFitsKeywordList</linkto>
109 // list of read-only FITS keywords.
110 // <li> Class <linkto class=CopyRecordToRecord:description>
111 // CopyRecordToRecord</linkto>
112 // Copies fields between Records, possibly to fields with another name.
113 // <li> Class <linkto class=CopyRecordToTable:description>
114 // CopyRecordToTable</linkto>
115 // Copies fields from a Record to columns of a Table.
116 // This class should be generalized, and made better. It is the analog of
117 // RowCopier, i.e. it copies all the fields from some Record to certain
118 // columns of a table. The mapping from fields to columns occurs at
119 // construction of the CopyRecordToTable object.
120 // <motivation>
121 // This class should be generalized, and made better. It is the analog of
122 // RowCopier, i.e. it copies all the fields from some Record to certain
123 // columns of a table. The mapping from fields to columns occurs at
124 // construction of the CopyRecordToTable object.
125 // </motivation>
126 // <li> Class <linkto class=ExtensionHeaderDataUnit:description>
127 // ExtensionHeaderDataUnit</linkto>
128 // Base class for generalized exentensions HDU.
129 // <li> Class <linkto class=FITS:description>
130 // FITS</linkto>
131 // Static functions and enumerations.
132 // Many of the static functions are utility functions used internally in the
133 // implementation of the member functions of the FITS classes. They are placed
134 // in a single class to encapsulate them and to avoid adding many names to the
135 // global name space. More important, from the user's perspective, are the
136 // enumerations. They form the basic vocabulary of a FITS application. For example,
137 // instead of referring to the FITS <src>NAXIS</src> keyword,
138 // <src>FITS::NAXIS</src> should be used.
139 // <li> Class <linkto class=FITSDateUtil:description>
140 // FITSDateUtil</linkto>
141 // A class with static functions to help deal with FITS dates
142 // This is a collection of static utility functions for creating and
143 // interpreting FITS date keywords (e.g. DATE-OBS).
144 // Its never necessary to construct a FITSDateUtil, just use the
145 // static functions to help handle FITS dates.
146 // <motivation>
147 // The strings that make up the value of FITS dates have a
148 // precise format. This class encompasses knowlege of the formats
149 // used and hopefully simplifies their creation and conversion
150 // to and from Casacore MVTimes.
151 // </motivation>
152 // <li> Class <linkto class=FITSError:description>
153 // FITSError</linkto>
154 // Default FITS error handling function, typdef, and enumeration.
155 // FITSError contains the enumeration specifying the possible error
156 // message levels. It also contains the default error handling function
157 // for the FITS classes.
158 // <motivation>
159 // Originally, FITS error message were simply sent to an ostream. In
160 // order to have these error messages go to the Casacore logger by default,
161 // this class was added. This was made a separate class because both
162 // BlockIo and FITS need to use this class. The anticipated replacements
163 // for the current FITS classes use a somewhat similar scheme.
164 // </motivation>
165 // <li> Class <linkto class=FITSFieldCopier:description>
166 // FITSFieldCopier</linkto>
167 // Virtual base class for copying RORecordFields to FitsFields.
168 // <li> Class <linkto class=FITSGroupWriter:description>
169 // FITSGroupWriter</linkto>
170 // Simplified interface to create and write to FITS random groups.
171 // Like FITSTableWriter except that this must be the first HDU and
172 // all "columns" in the description must have the same type, i.e. float.
173 // <li> Class <linkto class=FITSHistoryUtil:description>
174 // FITSHistoryUtil</linkto>
175 // A class with static functions to help deal with FITS History cards.
176 // This is a collection of static utility functions for use with FITS
177 // HISTORY keywords.
178 // Manipulate HISTORY information. FITS HISTORY cards are interconverted with
179 // String as follows:
180 // <ul>
181 // <li> 'HISTORY ' and trailing blanks are removed from each card.
182 // <li> Continuation cards are CARDS that have '>' in the first line.
183 // <li> A string is made by concatenating the leading card and all continuation
184 // cards.
185 // </ul>
186 // <motivation>
187 // The FitsKeywordList class can be somewhat tedious to use, as it deals with,
188 // e.g., char* pointers rather than Strings. This class makes it easy to
189 // interconvert between the HISTORY keywords and a Vector of related history
190 // information.
191 // </motivation>
192 // <li> Class <linkto class=FITSKeywordUtil:description>
193 // FITSKeywordUtil</linkto>
194 // A class with static functions to help deal with FITS Keywords.
195 // This class provides functions to conveniently interconvert between Casacore
196 // types and a FitsKeywordList which is needed by the native FITS classes.
197 // It is more convenient to maintain the list within Casacore
198 // as a Record, so we only need methods to turn a FitsKeywordList into a
199 // Record, and vice versa.
200 // Note that it is not necessary to construct a FITSKeywordUtil object
201 // since you can use its static functions directly.
202 // <motivation>
203 // The FitsKeywordList class can be somewhat tedious to use, as it deals with,
204 // e.g., char* pointers rather than Strings. This class makes it easy to
205 // interconvert between FITS keywords and Casacore types.
206 // </motivation>
207 // <li> Class <linkto class=FITSMultiTable:description>
208 // FITSMultiTable</linkto>
209 // View multiple FITS files as a single table.
210 // A FITSMultiTable is used to view a collection of FITS files on disk as a
211 // single Table. That is, when next() is called, when one Table ends the next
212 // is reopened until all files are exhausted. The FITS files must all have the
213 // same description. Something clever should be done about the keywords.
214 // <li> Class <linkto class=FITSSpectralUtil:description>
215 // FITSSpectralUtil</linkto>
216 // A class with static functions to help deal with FITS spectral axes.
217 // This class provides functions to extract information from a FITS
218 // header about the spectral axis, to setup a FITS header with
219 // appropriate information for the spectral axis, and to translate
220 // to and from the MFrequency refrence frame codes and their FITS
221 // equivalents.
222 // It is never necessary to construct a FITSSpectralUtil, just use the
223 // static functions to help handle FITS Spectral axes.
224 // <motivation>
225 // This is designed to be used after the keywords have been extracted from
226 // the FITS file using the <linkto class=FITSKeywordUtil>FITSKeywordUtil</linkto>
227 // class. Extracting spectral axis and related information requires detailed
228 // knowledge of FITS conventions that this class strives to encapsulize.
229 // </motivation>
230 // <li> Class <linkto class=FITSTable:description>
231 // FITSTable</linkto>
232 // Attach a FITSTabular to a binary or ASCII table.
233 // FITSTable is a FITSTabular which is attached to a FITS table (on disk only
234 // presently), either Binary or ASCII.
235 // <li> Class <linkto class=FITSTableWriter:description>
236 // FITSTableWriter</linkto>
237 // Simplified interface to create and write to a FITS Binary Table.
238 // <li> Class <linkto class=FITSTabular:description>
239 // FITSTabular</linkto>
240 // Simplified interface to FITS tables with Casacore Look and Feel.
241 // FITSTablular is an obstract base class which is used for read-only access to
242 // tabular FITS-like data structures.
243 // <li> Class <linkto class=FITSTimedTable:description>
244 // FITSTimedTable</linkto>
245 // FITSTimedTable is used to look at FITS tables which have a time column. In
246 // particular, it peeks ahead, and knows the time of the currentRow and of the
247 // nextRow.
248 // It is constructed with a pointer to any FITSTabular. Presently, no memory
249 // management is imposed to ensure that the pointer remains valid.
250 // <li> Class <linkto class=FitsArray:description>
251 // FitsArray</linkto>
252 // FITS array of given type.
253 // <li> Class <linkto class=FitsArray:description>
254 // <src>FitsArray<FitsBit></src></linkto>
255 // FITS array of FitsBit type.
256 // <li> Class <linkto class=FitsBase:description>
257 // FitsBase</linkto>
258 // Base class fore FitsField.
259 // <li> Class <linkto class=FitsBit:description>
260 // FitsBit</linkto>
261 // Helper class for FITS Binary Tables.
262 // This class is not intended for general use. It only has meaning
263 // in the context of FITS Binary tables. There its use is incorporated
264 // into the concept of a FitsField, where FitsBit is given a specialized
265 // interpretation.
266 // <li> Class <linkto class=FitsDiskInput:description>
267 // FitsDiskInput</linkto>
268 // FITS input from disk.
269 // <li> Class <linkto class=FitsDiskOutput:description>
270 // FitsDiskOutput</linkto>
271 // FITS output to disk.
272 // <li> Class <linkto class=FitsField:description>
273 // FitsField</linkto>
274 // Helper class.
275 // <li> Class <linkto class=FitsField:description>
276 // <src>FitsField<FitsBit></src></linkto>
277 // Helper class.
278 // <li> Class <linkto class=FitsFPUtil:description>
279 // FitsFPUtil</linkto>
280 // Utility functions for floating point values.
281 // <li> Class <linkto class=FitsInput:description>
282 // FitsInput</linkto>
283 // Fixed-length sequential blocked FITS input.
284 // <li> Class <linkto class=FitsIO:description>
285 // FitsIO</linkto>
286 // sequential FITS I/O.
287 // FitsIO is a base class that handles all the sequential blocked
288 // FITS I/O. Special derived classes do the input and output.
289 // No interpretation of the data is attempted here, there are
290 // special FITS classes that handle syntax and interpretation.
291 // <li> Class <linkto class=FitsKeyCardTranslator:description>
292 // FitsKeyCardTranslator</linkto>
293 // Translator between Keyword lists and fixed FITS cars.
294 // <li> Class <linkto class=FitsKeyword:description>
295 // FitsKeyword</linkto>
296 // A FITS keyword contains a name, a value and a comment..
297 // <li> Class <linkto class=FitsKeywordList:description>
298 // FitsKeywordList</linkto>
299 // Linked list of FITS keywords.
300 // <li> Class <linkto class=FitsLogical:description>
301 // FitsLogical</linkto>
302 // FitsLogical is a helper class that is not intended for general use.
303 // <li> Class <linkto class=FitsNameResult:description>
304 // FitsNameResult</linkto>
305 // Analyse the name of a header card.
306 // <li> Class <linkto class=FitsOutput:description>
307 // FitsOutput</linkto>
308 // Fixed-length sequential blocked FITS output.
309 // <li> Class <linkto class=FitsParse:description>
310 // FitsParse</linkto>
311 // Parse a header card.
312 // <li> Class <linkto class=FitsStdInput:description>
313 // FitsStdInput</linkto>
314 // FITS input from standard input.
315 // <li> Class <linkto class=FitsStdOutput:description>
316 // FitsStdOutput</linkto>
317 // FITS output to standard output.
318 // <li> Class <linkto class=FitsTape9Input:description>
319 // FitsTape9Input</linkto>
320 // FITS input from 9-track tape.
321 // <li> Class <linkto class=FitsTape9Output:description>
322 // FitsTape9Output</linkto>
323 // FITS output to 9-track tape.
324 // <li> Class <linkto class=FitsVADesc:description>
325 // FitsVADesc</linkto>
326 // Variable Length Array Descriptor.
327 // <li> Class <linkto class=FitsValueResult:description>
328 // FitsValueResult</linkto>
329 // Analyse the value of a header card.
330 // <li> Class <linkto class=HeaderDataUnit:description>
331 // HeaderDataUnit</linkto>
332 // Base class that defines a HDU.
333 // The class HeaderDataUnit contains what is common to all
334 // header-data-units, including the collection of keywords.
335 // From this class a number of FITS header-data-units are
336 // derived, each of them with their own rich assortment of
337 // functions for accessing and manipulating data of specific types.
338 // <li> Class <linkto class=ImageExtension:description>
339 // ImageExtension</linkto>
340 // IMAGE extension of given type.
341 // <li> Class <linkto class=NoConvert:description>
342 // NoConvert</linkto>
343 // FITS templated helper class.
344 // NoConvert is a template class that is not intended for
345 // general use, it is used internally.
346 // <li> Class <linkto class=PrimaryArray:description>
347 // PrimaryArray</linkto>
348 // Templated primary array base class of given type.
349 // A Primary Data Array is represented by the following:
350 // <srcblock>
351 // <Type> data_array [NAXIS1][NAXIS2]...[NAXISN]
352 // </srcblock>
353 // For a PrimaryArray, dims() gives the number of dimensions
354 // and dim(i) gives the value of the i-th dimension
355 // WARNING! Multi-dimensional arrays are stored in FORTRAN order,
356 // NOT in C order. Options on the store, copy, and move functions exist
357 // to convert from one order to the other, if that is necessary.
358 //
359 // It is important to understand the proper sequence of operations with
360 // respect to I/O and data access. For input, the `read()' functions
361 // allocate an internal buffer of the appropriate size, if not already
362 // allocated, as well as reading and converting data; a `read()' function
363 // must be performed prior to accessing the data, i. e. before executing
364 // any `()', `data()', `copy()', or `move()' function. For output, the
365 // `store()' function similarly allocates an internal buffer before
366 // transfering data, and must be executed prior to any data access or
367 // `write()' function. Note: If you call any version of store(), do not
368 // call set_next().
369 //
370 // Writing portions of an array at a time, rather than the entire array,
371 // is a special case. The `set_next()' function is provided for this
372 // purpose. It declares the intention to write out the next N elements and
373 // must be executed prior to any `data()' function. It allocates a buffer
374 // of appropriate size, if not already allocated. Again, via the `data()'
375 // functions, one accesses the array as if the entire array were in
376 // memory. The `write()' function always writes the number of current
377 // elements in the internal buffer. The sequence of operations for each
378 // portion of the array written would be:
379 // <ul>
380 // <li> `set_next(N)',
381 // <li> fill the array using `data(N)' or other `data()' functions
382 // <li> `write(fout)'.
383 // </ul>
384 // The `set_next()' function must NOT be used with
385 // `read()' or `store()' functions; unpredictable results will occur.
386 // <li> Class <linkto class=PrimaryGroup:description>
387 // PrimaryGroup</linkto>
388 // Random Group datastructure.
389 // <note role=warning>
390 // Please note that the NOST has deprecated the Random Group
391 // datastructure, it has been replaced by the much more powerfull
392 // BINTABLE extension.
393 // </note>
394 // <li> Class <linkto class=ReservedFitsKeyword:description>
395 // ReservedFitsKeyword</linkto>
396 // Reserved FITS keyword.
397 // <li> Class <linkto class=ReservedFitsKeywordCollection:description>
398 // ReservedFitsKeywordCollection</linkto>
399 // Collection of reserved FITS keywords.
400 // <li> Class <linkto class=ScalarFITSFieldCopier:description>
401 // ScalarFITSFieldCopier</linkto>
402 // A FITSFieldCopier for copying scalar non-string RecordFields to FitsFields.
403 // <li> Class <linkto class=SDFITSTable:description>
404 // SDFITSTable</linkto>
405 // SDFITSTable is derived from FITSTable. It contains additional
406 // checks and behaviour appropriate to the Single Dish FITS Convention
407 // hence this is a Single Dish FITS Table, or SDFITSTable.
408 // This class behaves much like FITSTable. It additionally verifies
409 // that the indicated HDU in the input FITS file follows the SDFITS
410 // convention (it has all of the required columns) and it treats
411 // keywords as virtual columns when appropriate. These virtual
412 // columns will appear as fields in the currentRecord and description
413 // and will NOT appear in the keywords.
414 // <motivation>
415 // It was useful to encapsulate this behaviour in a class so that
416 // the checks on a valid SDFITS table and the treatment of keywords
417 // as virtual columns would not need to appear everywhere it might
418 // be used.
419 // </motivation>
420 // <li> Class <linkto class=StringFITSFieldCopier:description>
421 // StringFITSFieldCopier</linkto>
422 // A FITSFieldCopier for copying String RecordFields to FitsFields.
423 // <li> Class <linkto class=VariableArrayFITSFieldCopier:description>
424 // VariableArrayFITSFieldCopier</linkto>
425 // Copy the current contents of the input RORecordFieldPtr to the output FitsField.
426 // </ol>
427 //
428 // <note role=tip> You may want to look at the individual header files
429 // to see whether you might not prefer to include only the header
430 // files you really need; it may be more efficient to do so.
431 // </note>
432 //
433 // </synopsis>
434 //
435 //# <todo asof="2005/06/20">
436 //# <li>
437 //# </todo>
438 //
439 // </module>
440 
441 
442 } //# NAMESPACE CASACORE - END
443 
444 #endif
445 
this file contains all the compiler specific defines
Definition: mainpage.dox:28