casacore
FITSTable.h
Go to the documentation of this file.
1//# FITSTable.h: Simplified interface to FITS tables with Casacore Look and Feel.
2//# Copyright (C) 1995,1996,1997,1999,2000,2001
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//#
27//# $Id$
28
29#ifndef FITS_FITSTABLE_H
30#define FITS_FITSTABLE_H
31
32
33#include <casacore/casa/aips.h>
34#include <casacore/casa/Arrays/ArrayFwd.h>
35#include <casacore/casa/Containers/Record.h>
36#include <casacore/tables/Tables/TableRecord.h>
37#include <casacore/casa/Containers/Block.h>
38#include <casacore/fits/FITS/hdu.h>
39#include <casacore/fits/FITS/fitsio.h>
40#include <casacore/casa/iosfwd.h>
41
42namespace casacore { //# NAMESPACE CASACORE - BEGIN
43
44class String;
45class FITSFieldCopier;
46class TableDesc;
47
48// <summary>
49// Simplified interface to FITS tables with Casacore Look and Feel.
50// </summary>
51//
52// <use visibility=export>
53//
54// <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos="">
55// </reviewed>
56//
57// <prerequisite>
58// <li> General knowledge of FITS binary and ASCII tables.
59// </prerequisite>
60//
61// <etymology>
62// </etymology>
63//
64// <synopsis>
65// FITSTablular is an obstract base class which is used for read-only access to
66// tabular FITS-like data structures.
67// </synopsis>
68//
69// <example>
70// </example>
71//
72// <motivation>
73// </motivation>
74//
75// <todo asof="1995/06/01">
76// <li> Eventually we'd like to be able to write the tables as well as read
77// them.
78// </todo>
79
81{
82public:
83 virtual ~FITSTabular();
84 // isValid() returns False if this object isn't a valid Tabular data
85 // structure.
86 virtual Bool isValid() const = 0;
87 // Returns keywords which are associated with the underlying FITS files.
88 virtual const TableRecord &keywords() const = 0;
89 // Returns the description of the underlying FITS table.
90 virtual const RecordDesc &description() const = 0;
91 // Returns any TUNITnnn associated with a column (the field names
92 // are the column names, each field value is the TUNITnnn value for
93 // that field). Note that only those columns with a non-empty
94 // TUNITnnn have an entry in the units() Record.
95 virtual const Record &units() const = 0;
96 // Returns any TDISPnnn associated with a column (the field names
97 // are the column names, each field value is the TDISPnnn value for
98 // that field). Note that only those columns with a non-empty
99 // TDISPnnn have an entry in the displayFormats() Record.
100 virtual const Record &displayFormats() const = 0;
101 // Returns any TNULLnnn associated with a column (the field names
102 // are the column names, each field value is the TNULLnnn value for
103 // that field). Note that only those columns with a specific entry for
104 // TNULLnnn and which have not been promoted to doubles due TSCAL
105 // and TZERO values will have an entry in the nulls() Record.
106 // The meaning of TNULL is only defined for integer and byte columns.
107 // When a column is promoted to a double because of scaling,
108 // any TNULL values will be assigned a value of NaN.
109 virtual const Record &nulls() const = 0;
110
111 // Returns True if we have advanced past the end of data.
112 virtual Bool pastEnd() const = 0;
113
114 // Advance the row if possible (guaranteed harmless if pastEnd() is True.
115 virtual void next() = 0;
116
117 // Reopen the table, default behavior is to do nothing, return False
118 virtual Bool reopen(const String&) { return False; }
119
120 // return the name
121 virtual const String &name() const = 0;
122
123 // Has the description changed since construction, default is False
124 virtual Bool hasChanged() const { return False;}
125 // reset the changed flag, default do nothing
126 virtual void resetChangedFlag() {;}
127
128 // Return the currentRow. This is guaranteed to be valid so long as only
129 // member functions of this base class are called (so you can safely attach
130 // RecordFieldPtr objects to it. The result is undefined if pastEnd() is True.
131 virtual const Record &currentRow() const = 0;
132
133 // Helper function for retrieving keywords from a native-FITS hdu.
134 // If allKeywords is not True, some keywords will be excluded
135 // from the list. Currently the list of excluded keywords
136 // includes TTYPEnnn, TFORMnnn, and TUNITnnn
138 Bool allKeywords = False);
139
140 // Helper function for retrieving a description from a native-FITS hdu.
142
143 // Help function for retrieving any shape information from String columns
144 // using the SubString convention.
145 // Information is returned in a Record having named fields = all String
146 // columns following those convention. Each of these fields is, in turn,
147 // a sub-record having these three fields: NCHAR, NELEM, DELIM.
148 // If NELEM == -1 then there must have been a DELIM specified and
149 // this field is a variable shaped string array where each element has
150 // at most NCHAR and they are separated by DELIM (which is a String field here).
151 // Otherwise, DELIM is not used and there are NCHAR per element for each
152 // of NELEM in each cell for this column.
154
155 // Helper function for retrieving the TUNITnnn from a native-FITS hdu.
157
158 // Helper function for retrieving the TDISPnnn from a native-FITS hdu.
160
161 // Helper function for retrieving the TNULLnnn from a native-FITS hdu.
163
164 // Get a TableDesc appropriate to hold a FITSTabular
165 // the keywords, description, units, displayFormats, and nulls are all used
166 static TableDesc tableDesc(const FITSTabular &fitstabular);
167};
168
169// <summary>
170// Attach a FITSTabular to a binary or ASCII table
171// </summary>
172//
173// <use visibility=export>
174//
175// <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos="">
176// </reviewed>
177//
178// <prerequisite>
179// <li> General knowledge of FITS binary and ASCII tables.
180// </prerequisite>
181//
182// <etymology>
183// </etymology>
184//
185// <synopsis>
186// FITSTable is a FITSTabular which is attached to a FITS table (on disk only
187// presently), either Binary or ASCII.
188// </synopsis>
189//
190// <example>
191// </example>
192//
193// <motivation>
194// </motivation>
195//
196// <todo asof="1995/06/01">
197// <li>
198// </todo>
199
200class FITSTable : public FITSTabular
201{
202public:
203 // this creates an invalid (isValid() return False) FITSTable
204 // Its primary purpose is so that FITSTables can be created before
205 // the file name is known. reopen() is then used to open the file.
206 FITSTable(uInt whichHDU=1, Bool allKeywords=False);
207
208 // 0-relative HDU. It can never be zero by the FITS rules.
209 // allKeywords is passed to FITSTabular::keywordsFromHDU
210 // See the documentation for that function for a list of
211 // excluded keywords when allKeywords is False.
212 FITSTable(const String &fileName, uInt whichHDU=1,
213 Bool allKeywords = False);
215
216 // Has the end of file been reached yet
217 virtual Bool eof() const {return io_p->eof();}
218
219 // Attach this FITSTable to a new file name, same HDU# as at open time
220 virtual Bool reopen(const String &fileName);
221 virtual const String& name() const { return name_p;}
222
223 virtual Bool isValid() const {return isValid_p;}
224
225 virtual const TableRecord &keywords() const {return keywords_p;}
226 virtual const RecordDesc &description() const {return description_p;}
227 virtual const Record &units() const {return units_p;}
228 virtual const Record &displayFormats() const {return disps_p;}
229 virtual const Record &nulls() const {return nulls_p;}
230
231 virtual Bool pastEnd() const;
232 virtual void next();
233 virtual const Record &currentRow() const;
234
235 // single FITS tables know how many rows there are
236 // unlike general FITSTabulars, which may not know
237 // (e.g. if it is a FITSMultiTable)
238 virtual uInt nrow() const {return raw_table_p->nrows();}
239
240 // these tables should also know where they are
241 virtual Int rownr() const {return row_nr_p;}
242
243 // and it should be possible to move to a desired row
244 // the rownr() member can be used to verify that a move
245 // was successful - this will happen if the requested row
246 // was < rownr() or >= nrow() - i.e. movements backwards or
247 // beyond the end of the file are not possible.
248 virtual void move(Int torow);
249
250 // the keywords from the Primary HDU
251 virtual const TableRecord &primaryKeywords() const {return primaryKeys_p;}
252protected:
253 // SDFITSTable needs to make some keywords appear as
254 // columns, this requires access to description_p, keywords_p, and
255 // row_p. However, its not something that typical FITSTable
256 // users will want. Therefore, I've provided this protected
257 // function for SDFITSTable to use so as to not have to provide
258 // direct access to those data members at the public level.
259 // The named keywords and values are appended to the end of
260 // row_p and removed from keywords_p, description_p is modified
261 // appropriately. The returned value is False if any named
262 // keyword did not appear in keywords_p (however, all named
263 // keywords that DO appear in keywords_p will have been correctly
264 // moved).
266private:
267 // Undefined and inaccessible. An alternative would be to use reference
268 // semantics like Table.
271
272 void fill_row();
274
276
278
280
293 // One per field in row_p, of the right type. i.e. casting required.
299 // these are used by VADESC columns
302 // I had trouble making a Block<VADescFitsField>
305
306 // It is necessary to read the PDA to get the primary keywords.
307 // If there is any data there, the FITS classes do not provide any way to
308 // just skip over them to get to the next HDU. The only way to do that is
309 // to actually read all of the data. If there is no data, this step is
310 // unnecessary and so this subroutine need only be called after the primary
311 // keywords have been read AND the PDA has some data in it. Closing the
312 // FitsInput and reopening it is faster in most cases than reading in each
313 // data value.
315};
316
317// <summary>
318// Simplified interface to create and write to a FITS Binary Table
319// </summary>
320//
321// <use visibility=export>
322//
323// <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos="">
324// </reviewed>
325//
326// <prerequisite>
327// <li> General knowledge of FITS binary and ASCII tables.
328// </prerequisite>
329//
330// <etymology>
331// </etymology>
332//
333// <synopsis>
334// </synopsis>
335//
336// <example>
337// </example>
338//
339// <motivation>
340// </motivation>
341//
342// <todo asof="1995/06/01">
343// <li> probably much
344// </todo>
345
347{
348public:
350
351 // You MUST have already written a first HDU to FitsOutput.
352 // description contains the names and types of the table columns to be written.
353 // The row is not rearranged (i.e. they are used in order) for alignment purposes.
354 // Array columns must have fixed shape unless tdimColumns is used. Use the
355 // maxLengths record to indicate any string columns which should have a length other
356 // than the default value by providing an int field of the same name as the string
357 // field in this record.
358 // The size of the table (nrows) must be given at creation. Use extraKeywords to
359 // indicate any keywords not automatically created. The units record is used to
360 // indicate the units for any column. Provide a string field with the same name as
361 // the column field in description. If freeOutput is True, file must come from new
362 // since it will be deleted upon destruction. You might not want this to happen if
363 // you are going to write many tables to the same fits file. Use variableShapes to
364 // signal which array columns have variable shape and use maxLengths to indicate
365 // the maximum size of those variable shaped columns. The variableShapes record
366 // should contain a String corresponding to the longest TDIM value appropriate for
367 // each variable shaped column. The maxLengths record should contain an int field
368 // for each variable shaped column which indicates the maximum number of elements
369 // to be found in that column. Unused values in any cell in the variable shaped
370 // columns will be filled with zero. These columns will use the SDFITS TDIM convention
371 // where for column nnn there is a corresponding TDIMnnn column where
372 // the values in each row are the true shape of the data in column nnn.
373 // variableShapes appears as the last argument for backwards compatibility with
374 // existing code.
376 const RecordDesc &description,
377 const Record &maxLengths,
378 uInt nrows,
379 const Record &extraKeywords,
380 const Record &units,
381 Bool freeOutput = True,
382 const Record &variableShapes = Record());
383
385
386 // use this to set the value of the current row to be written
388
389 // Write the current row()
390 void write();
391
392 // Don't delete this out from under us!
394
395 // Returns a writer, with the first HDU filled in (set to null). The caller
396 // is responsible for deleting the pointer returned from makeWriter.
397 static FitsOutput *makeWriter(const String &fileName);
398private:
399 // Undefined and inaccessible
403
410};
411
412// <summary>
413// Simplified interface to create and write to FITS random groups
414// </summary>
415//
416// <use visibility=export>
417//
418// <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos="">
419// </reviewed>
420//
421// <prerequisite>
422// <li> General knowledge of FITS binary and ASCII tables.
423// </prerequisite>
424//
425// <etymology>
426// </etymology>
427//
428// <synopsis>
429// Like FITSTableWriter except that this must be the first HDU and
430// all "columns" in the description must have the same type, i.e. float.
431// </synopsis>
432//
433// <example>
434// </example>
435//
436// <motivation>
437// </motivation>
438//
439// <todo asof="1995/06/01">
440// <li> probably much
441// </todo>
442
444{
445public:
446 // Since this must always be the first HDU, there is no point in constructing it
447 // with a FitsOutput. description indicates the names of the random groups parameters.
448 // nrows is a synonym for ngroups. Use extraKeywords to
449 // indicate any keywords not automatically created (SIMPLE, BITPIX, NAXIS*, EXTEND,
450 // BLOCKED, GROUPS, PCOUNT, GOUNT, ORIGIN, END). If freeOutput is True, file will be
451 // deleted by the destructor. You might not want this to happen if
452 // you are going to write any extensions to the same fits file. You can get the
453 // FitsOutput used here from write()
454 FITSGroupWriter(const String &fileName,
455 const RecordDesc &description,
456 uInt nrows,
457 const Record &extraKeywords,
458 Bool freeOutput = True);
459
461
462 // Set the values for the current group
464
465 // Write the current group (row()).
466 void write();
467
468 // Don't delete this out from under us!
470private:
471 // Undefined and inaccessible
475
482
483 // Checks error status of writer_p and group_p. Cleans up and throws an exception if bad.
484 void check_error(const char *extra_info = 0);
485};
486
487} //# NAMESPACE CASACORE - END
488
489#endif
BINTABLE extension
Definition: hdu.h:1035
Int nrows() const
return basic elements of a table
Definition: hdu.h:1049
Simplified interface to create and write to FITS random groups.
Definition: FITSTable.h:444
RecordInterface & row()
Set the values for the current group.
Definition: FITSTable.h:463
void write()
Write the current group (row()).
FITSGroupWriter(const FITSGroupWriter &)
PrimaryGroup< Float > * group_p
Definition: FITSTable.h:479
FitsOutput * writer()
Don't delete this out from under us!
Definition: FITSTable.h:469
FITSGroupWriter(const String &fileName, const RecordDesc &description, uInt nrows, const Record &extraKeywords, Bool freeOutput=True)
Since this must always be the first HDU, there is no point in constructing it with a FitsOutput.
FITSGroupWriter & operator=(const FITSGroupWriter &)
void check_error(const char *extra_info=0)
Checks error status of writer_p and group_p.
FITSGroupWriter()
Undefined and inaccessible.
Simplified interface to create and write to a FITS Binary Table.
Definition: FITSTable.h:347
RecordInterface & row()
use this to set the value of the current row to be written
Definition: FITSTable.h:387
void write()
Write the current row()
FITSTableWriter & operator=(const FITSTableWriter &)
static FitsOutput * makeWriter(const String &fileName)
Returns a writer, with the first HDU filled in (set to null).
FITSTableWriter(FitsOutput *file, const RecordDesc &description, const Record &maxLengths, uInt nrows, const Record &extraKeywords, const Record &units, Bool freeOutput=True, const Record &variableShapes=Record())
You MUST have already written a first HDU to FitsOutput.
PtrBlock< FITSFieldCopier * > copiers_p
Definition: FITSTable.h:409
FitsOutput * writer()
Don't delete this out from under us!
Definition: FITSTable.h:393
FITSTableWriter()
Undefined and inaccessible.
FITSTableWriter(const FITSTableWriter &)
BinaryTableExtension * bintable_p
Definition: FITSTable.h:407
Attach a FITSTabular to a binary or ASCII table.
Definition: FITSTable.h:201
TableRecord primaryKeys_p
Definition: FITSTable.h:285
Block< void * > row_fields_p
Definition: FITSTable.h:295
virtual void move(Int torow)
and it should be possible to move to a desired row the rownr() member can be used to verify that a mo...
virtual Bool pastEnd() const
Returns True if we have advanced past the end of data.
VADescFitsField * va_p
I had trouble making a Block<VADescFitsField>
Definition: FITSTable.h:303
void reopenAtFirstHDU(const String &name)
It is necessary to read the PDA to get the primary keywords.
BinaryTableExtension * raw_table_p
Definition: FITSTable.h:282
virtual const Record & currentRow() const
Return the currentRow.
virtual Bool reopen(const String &fileName)
Attach this FITSTable to a new file name, same HDU# as at open time.
virtual const RecordDesc & description() const
Returns the description of the underlying FITS table.
Definition: FITSTable.h:226
virtual void next()
Advance the row if possible (guaranteed harmless if pastEnd() is True.
virtual Bool eof() const
Has the end of file been reached yet.
Definition: FITSTable.h:217
virtual Int rownr() const
these tables should also know where they are
Definition: FITSTable.h:241
FITSTable(uInt whichHDU=1, Bool allKeywords=False)
this creates an invalid (isValid() return False) FITSTable Its primary purpose is so that FITSTables ...
RecordDesc description_p
Definition: FITSTable.h:286
FITSTable(const FITSTable &)
Undefined and inaccessible.
Bool virtualColumns(const Vector< String > &keyNames)
SDFITSTable needs to make some keywords appear as columns, this requires access to description_p,...
virtual const TableRecord & keywords() const
Returns keywords which are associated with the underlying FITS files.
Definition: FITSTable.h:225
Block< Int > field_types_p
Definition: FITSTable.h:296
virtual const TableRecord & primaryKeywords() const
the keywords from the Primary HDU
Definition: FITSTable.h:251
virtual const String & name() const
return the name
Definition: FITSTable.h:221
Block< Int > tdims_p
Definition: FITSTable.h:298
virtual Bool isValid() const
isValid() returns False if this object isn't a valid Tabular data structure.
Definition: FITSTable.h:223
FitsInput * io_p
Definition: FITSTable.h:283
Block< void * > vaptr_p
Definition: FITSTable.h:301
Block< Bool > promoted_p
Definition: FITSTable.h:297
FITSTable(const String &fileName, uInt whichHDU=1, Bool allKeywords=False)
0-relative HDU.
TableRecord keywords_p
Definition: FITSTable.h:284
virtual const Record & nulls() const
Returns any TNULLnnn associated with a column (the field names are the column names,...
Definition: FITSTable.h:229
FITSTable & operator=(const FITSTable &)
virtual const Record & units() const
Returns any TUNITnnn associated with a column (the field names are the column names,...
Definition: FITSTable.h:227
uInt nfields_p
One per field in row_p, of the right type.
Definition: FITSTable.h:294
virtual const Record & displayFormats() const
Returns any TDISPnnn associated with a column (the field names are the column names,...
Definition: FITSTable.h:228
virtual uInt nrow() const
single FITS tables know how many rows there are unlike general FITSTabulars, which may not know (e....
Definition: FITSTable.h:238
Block< Int > vatypes_p
these are used by VADESC columns
Definition: FITSTable.h:300
virtual Bool hasChanged() const
Has the description changed since construction, default is False.
Definition: FITSTable.h:124
virtual const Record & currentRow() const =0
Return the currentRow.
virtual Bool pastEnd() const =0
Returns True if we have advanced past the end of data.
virtual const TableRecord & keywords() const =0
Returns keywords which are associated with the underlying FITS files.
static Record displayFormatsFromHDU(BinaryTableExtension &hdu)
Helper function for retrieving the TDISPnnn from a native-FITS hdu.
virtual Bool isValid() const =0
isValid() returns False if this object isn't a valid Tabular data structure.
virtual const Record & nulls() const =0
Returns any TNULLnnn associated with a column (the field names are the column names,...
static Record nullsFromHDU(BinaryTableExtension &hdu)
Helper function for retrieving the TNULLnnn from a native-FITS hdu.
static RecordDesc descriptionFromHDU(BinaryTableExtension &hdu)
Helper function for retrieving a description from a native-FITS hdu.
virtual const RecordDesc & description() const =0
Returns the description of the underlying FITS table.
virtual const String & name() const =0
return the name
virtual const Record & units() const =0
Returns any TUNITnnn associated with a column (the field names are the column names,...
virtual void next()=0
Advance the row if possible (guaranteed harmless if pastEnd() is True.
virtual Bool reopen(const String &)
Reopen the table, default behavior is to do nothing, return False.
Definition: FITSTable.h:118
static TableRecord keywordsFromHDU(HeaderDataUnit &hdu, Bool allKeywords=False)
Helper function for retrieving keywords from a native-FITS hdu.
virtual void resetChangedFlag()
reset the changed flag, default do nothing
Definition: FITSTable.h:126
static Record unitsFromHDU(BinaryTableExtension &hdu)
Helper function for retrieving the TUNITnnn from a native-FITS hdu.
static TableDesc tableDesc(const FITSTabular &fitstabular)
Get a TableDesc appropriate to hold a FITSTabular the keywords, description, units,...
static Record subStringShapeFromHDU(BinaryTableExtension &hdu)
Help function for retrieving any shape information from String columns using the SubString convention...
virtual const Record & displayFormats() const =0
Returns any TDISPnnn associated with a column (the field names are the column names,...
helper class Note: Note that FitsField does not allocate space for the data; Space is external to Fi...
Definition: hdu.h:882
Bool eof() const
test if end of file has been reached
Definition: fitsio.h:95
fixed-length sequential blocked FITS input
Definition: fitsio.h:156
fixed-length sequential blocked FITS output
Definition: fitsio.h:228
A drop-in replacement for Block<T*>.
Definition: Block.h:814
String: the storage and methods of handling collections of characters.
Definition: String.h:225
this file contains all the compiler specific defines
Definition: mainpage.dox:28
const Bool False
Definition: aipstype.h:44
unsigned int uInt
Definition: aipstype.h:51
int Int
Definition: aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
const Bool True
Definition: aipstype.h:43