casacore
Loading...
Searching...
No Matches
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
51namespace 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