casacore
fits
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
casacore
this file contains all the compiler specific defines
Definition:
mainpage.dox:28
Generated by
1.8.20