casacore
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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>
38 #include <casacore/fits/FITS/hdu.h>
40 #include <casacore/casa/iosfwd.h>
41 
42 namespace casacore { //# NAMESPACE CASACORE - BEGIN
43 
44 class String;
45 class FITSFieldCopier;
46 class 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 {
82 public:
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 
200 class FITSTable : public FITSTabular
201 {
202 public:
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;}
252 protected:
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).
265  Bool virtualColumns(const Vector<String>& keyNames);
266 private:
267  // Undefined and inaccessible. An alternative would be to use reference
268  // semantics like Table.
269  FITSTable(const FITSTable &);
270  FITSTable &operator=(const FITSTable &);
271 
272  void fill_row();
273  void clear_self();
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>
304  char *theheap_p;
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.
314  void reopenAtFirstHDU(const String &name);
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 {
348 public:
349  enum {DefaultMaxStringSize = 16};
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
387  RecordInterface &row() {return row_p;}
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);
398 private:
399  // Undefined and inaccessible
400  FITSTableWriter();
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 {
445 public:
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
463  RecordInterface &row() {return row_p;}
464 
465  // Write the current group (row()).
466  void write();
467 
468  // Don't delete this out from under us!
470 private:
471  // Undefined and inaccessible
472  FITSGroupWriter();
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
RecordInterface & row()
use this to set the value of the current row to be written
Definition: FITSTable.h:387
virtual Bool pastEnd() const
Returns True if we have advanced past the end of data.
BinaryTableExtension * raw_table_p
Definition: FITSTable.h:282
A 1-D Specialization of the Array class.
Definition: ArrayFwd.h:9
VADescFitsField * va_p
I had trouble making a Block&lt;VADescFitsField&gt;
Definition: FITSTable.h:303
int Int
Definition: aipstype.h:50
static Record subStringShapeFromHDU(BinaryTableExtension &hdu)
Help function for retrieving any shape information from String columns using the SubString convention...
virtual const Record & units() const =0
Returns any TUNITnnn associated with a column (the field names are the column names, each field value is the TUNITnnn value for that field).
static Record unitsFromHDU(BinaryTableExtension &hdu)
Helper function for retrieving the TUNITnnn from a native-FITS hdu.
Block< Int > tdims_p
Definition: FITSTable.h:298
FITSTable(uInt whichHDU=1, Bool allKeywords=False)
this creates an invalid (isValid() return False) FITSTable Its primary purpose is so that FITSTables ...
virtual const Record & nulls() const =0
Returns any TNULLnnn associated with a column (the field names are the column names, each field value is the TNULLnnn value for that field).
static Record displayFormatsFromHDU(BinaryTableExtension &hdu)
Helper function for retrieving the TDISPnnn from a native-FITS hdu.
BINTABLE extension.
Definition: hdu.h:1035
virtual const String & name() const
return the name
Definition: FITSTable.h:221
static Record nullsFromHDU(BinaryTableExtension &hdu)
Helper function for retrieving the TNULLnnn from a native-FITS hdu.
PtrBlock< FITSFieldCopier * > copiers_p
Definition: FITSTable.h:409
Block< Int > vatypes_p
these are used by VADESC columns
Definition: FITSTable.h:300
Simplified interface to create and write to a FITS Binary Table.
Definition: FITSTable.h:346
virtual Int rownr() const
these tables should also know where they are
Definition: FITSTable.h:241
Block< void * > row_fields_p
Definition: FITSTable.h:295
virtual const TableRecord & keywords() const
Returns keywords which are associated with the underlying FITS files.
Definition: FITSTable.h:225
PrimaryGroup< Float > * group_p
Definition: FITSTable.h:479
TableRecord primaryKeys_p
Definition: FITSTable.h:285
FITSTable & operator=(const FITSTable &)
Int nrows() const
return basic elements of a table
Definition: hdu.h:1049
static TableDesc tableDesc(const FITSTabular &fitstabular)
Get a TableDesc appropriate to hold a FITSTabular the keywords, description, units, displayFormats, and nulls are all used.
virtual Bool isValid() const
isValid() returns False if this object isn&#39;t a valid Tabular data structure.
Definition: FITSTable.h:223
virtual Bool reopen(const String &fileName)
Attach this FITSTable to a new file name, same HDU# as at open time.
base class that defines a HDU
Definition: hdu.h:71
FITSTableWriter & operator=(const FITSTableWriter &)
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
RecordInterface & row()
Set the values for the current group.
Definition: FITSTable.h:463
virtual Bool hasChanged() const
Has the description changed since construction, default is False.
Definition: FITSTable.h:124
virtual const TableRecord & keywords() const =0
Returns keywords which are associated with the underlying FITS files.
static FitsOutput * makeWriter(const String &fileName)
Returns a writer, with the first HDU filled in (set to null).
virtual const Record & currentRow() const =0
Return the currentRow.
void write()
Write the current row()
Block< Bool > promoted_p
Definition: FITSTable.h:297
virtual const RecordDesc & description() const =0
Returns the description of the underlying FITS table.
virtual void next()
Advance the row if possible (guaranteed harmless if pastEnd() is True.
Simplified interface to create and write to FITS random groups.
Definition: FITSTable.h:443
virtual const Record & displayFormats() const
Returns any TDISPnnn associated with a column (the field names are the column names, each field value is the TDISPnnn value for that field).
Definition: FITSTable.h:228
FitsInput * io_p
Definition: FITSTable.h:283
Description of the fields in a record object.
Definition: RecordDesc.h:105
FITSTableWriter()
Undefined and inaccessible.
void check_error(const char *extra_info=0)
Checks error status of writer_p and group_p.
FITSGroupWriter & operator=(const FITSGroupWriter &)
virtual const RecordDesc & description() const
Returns the description of the underlying FITS table.
Definition: FITSTable.h:226
virtual const TableRecord & primaryKeywords() const
the keywords from the Primary HDU
Definition: FITSTable.h:251
uInt nfields_p
One per field in row_p, of the right type.
Definition: FITSTable.h:294
virtual const Record & displayFormats() const =0
Returns any TDISPnnn associated with a column (the field names are the column names, each field value is the TDISPnnn value for that field).
A hierarchical collection of named fields of various types.
Definition: Record.h:180
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
FITSGroupWriter()
Undefined and inaccessible.
static TableRecord keywordsFromHDU(HeaderDataUnit &hdu, Bool allKeywords=False)
Helper function for retrieving keywords from a native-FITS hdu.
FitsOutput * writer()
Don&#39;t delete this out from under us!
Definition: FITSTable.h:469
FitsOutput * writer()
Don&#39;t delete this out from under us!
Definition: FITSTable.h:393
Attach a FITSTabular to a binary or ASCII table.
Definition: FITSTable.h:200
const Bool False
Definition: aipstype.h:44
A drop-in replacement for Block&lt;T*&gt;.
Definition: Block.h:814
BinaryTableExtension * bintable_p
Definition: FITSTable.h:407
A hierarchical collection of named fields of various types.
Definition: TableRecord.h:185
Block< void * > vaptr_p
Definition: FITSTable.h:301
virtual Bool isValid() const =0
isValid() returns False if this object isn&#39;t a valid Tabular data structure.
virtual const Record & units() const
Returns any TUNITnnn associated with a column (the field names are the column names, each field value is the TUNITnnn value for that field).
Definition: FITSTable.h:227
virtual const String & name() const =0
return the name
fixed-length sequential blocked FITS output
Definition: fitsio.h:228
fixed-length sequential blocked FITS input
Definition: fitsio.h:156
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...
static RecordDesc descriptionFromHDU(BinaryTableExtension &hdu)
Helper function for retrieving a description from a native-FITS hdu.
virtual Bool pastEnd() const =0
Returns True if we have advanced past the end of data.
void write()
Write the current group (row()).
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, each field value is the TNULLnnn value for that field).
Definition: FITSTable.h:229
RecordDesc description_p
Definition: FITSTable.h:286
virtual void resetChangedFlag()
reset the changed flag, default do nothing
Definition: FITSTable.h:126
String: the storage and methods of handling collections of characters.
Definition: String.h:225
void reopenAtFirstHDU(const String &name)
It is necessary to read the PDA to get the primary keywords.
Block< Int > field_types_p
Definition: FITSTable.h:296
Bool virtualColumns(const Vector< String > &keyNames)
SDFITSTable needs to make some keywords appear as columns, this requires access to description_p...
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
Define the structure of a Casacore table.
Definition: TableDesc.h:190
virtual Bool eof() const
Has the end of file been reached yet.
Definition: FITSTable.h:217
virtual void next()=0
Advance the row if possible (guaranteed harmless if pastEnd() is True.
virtual const Record & currentRow() const
Return the currentRow.
Abstract base class for Record classes.
const Bool True
Definition: aipstype.h:43
unsigned int uInt
Definition: aipstype.h:51
virtual Bool reopen(const String &)
Reopen the table, default behavior is to do nothing, return False.
Definition: FITSTable.h:118
Simplified interface to FITS tables with Casacore Look and Feel.
Definition: FITSTable.h:80