casacore
FITSImage.h
Go to the documentation of this file.
1 //# FITSImage.h: Class providing native access to FITS images
2 //# Copyright (C) 2001,2002
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 IMAGES_FITSIMAGE_H
29 #define IMAGES_FITSIMAGE_H
30 
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <casacore/images/Images/ImageInterface.h>
35 #include <casacore/images/Images/MaskSpecifier.h>
36 #include <casacore/tables/DataMan/TiledFileAccess.h>
37 #include <casacore/lattices/Lattices/TiledShape.h>
38 #include <casacore/fits/FITS/fits.h>
39 #include <casacore/casa/BasicSL/String.h>
40 #include <casacore/casa/Utilities/DataType.h>
41 
42 #ifndef WCSLIB_GETWCSTAB
43  #define WCSLIB_GETWCSTAB
44 #endif
45 
46 namespace casacore { //# NAMESPACE CASACORE - BEGIN
47 
48 //# Forward Declarations
49 template <class T> class Array;
50 template <class T> class Lattice;
51 //
52 class MaskSpecifier;
53 class IPosition;
54 class Slicer;
55 class CoordinateSystem;
56 class FITSMask;
57 class FitsInput;
58 
59 
60 // <summary>
61 // Class providing native access to FITS images.
62 // </summary>
63 
64 // <use visibility=export>
65 
66 // <reviewed reviewer="" date="" tests="tFITSImage.cc">
67 // </reviewed>
68 
69 // <prerequisite>
70 // <li> <linkto class=ImageInterface>ImageInterface</linkto>
71 // <li> <linkto class=FITSMask>FITSMask</linkto>
72 // </prerequisite>
73 
74 // <etymology>
75 // This class provides native access to FITS images.
76 // 64bit, 32bit floating point, 32 bit and 16bit integer FITS images are
77 // presently supported.
78 // </etymology>
79 
80 // <synopsis>
81 // A FITSImage provides native access to FITS images by accessing them
82 // with the TiledFileAccess class. The FITSImage is read only.
83 // We could implement a writable FITSImage but putting the mask
84 // would lose data values (uses magic blanking) and FITS is really
85 // meant as an interchange medium, not an internal format.
86 //
87 // Because FITS uses magic value blanking, the mask is generated
88 // on the fly as needed.
89 // </synopsis>
90 
91 // <example>
92 // <srcblock>
93 // FITSImage im("in.fits");
94 // LogIO logger(or);
95 // ImageStatistics<Float> stats(im, logger);
96 // Bool ok = stats.display(); // Display statistics
97 // </srcblock>
98 // </example>
99 
100 // <motivation>
101 // This provides native access to FITS images.
102 // </motivation>
103 
104 //# <todo asof="2001/02/09">
105 //# </todo>
106 
107 
108 class FITSImage: public ImageInterface<Float>
109 {
110 public:
111  // Construct a FITSImage from the disk FITS file name and extension and apply mask.
112  explicit FITSImage(const String& name, uInt whichRep=0, uInt whichHDU=0);
113 
114  // Construct a FITSImage from the disk FITS file name and extension and apply mask or not.
115  FITSImage(const String& name, const MaskSpecifier& mask, uInt whichRep=0, uInt whichHDU=0);
116 
117  // Copy constructor (reference semantics)
118  FITSImage(const FITSImage& other);
119 
120  // Destructor does nothing
121  virtual ~FITSImage();
122 
123  // Assignment (reference semantics)
124  FITSImage& operator=(const FITSImage& other);
125 
126  // Function to open a FITS image (new parser)
127  static LatticeBase* openFITSImage (const String& name,
128  const MaskSpecifier&);
129 
130  // Register the open function.
131  static void registerOpenFunction();
132 
133  // Separate any extension specification and return the pure fitsname
134  static String get_fitsname(const String &fullname);
135 
136  // Get the extension index for any extension specification given in the full name
137  static uInt get_hdunum(const String &fullname);
138 
139  //# ImageInterface virtual functions
140 
141  // Make a copy of the object with new (reference semantics).
142  virtual ImageInterface<Float>* cloneII() const;
143 
144  // Get the image type (returns FITSImage).
145  virtual String imageType() const;
146 
147  // Function which changes the shape of the FITSImage.
148  // Throws an exception as FITSImage is not writable.
149  virtual void resize(const TiledShape& newShape);
150 
151  //# MaskedLattice virtual functions
152 
153  // Has the object really a mask? The FITSImage always
154  // has a pixel mask and never has a region mask so this
155  // always returns True
156  virtual Bool isMasked() const;
157 
158  // FITSimage always has a pixel mask so returns True
159  virtual Bool hasPixelMask() const;
160 
161  // Get access to the pixelmask. FITSImage always has a pixel mask.
162  // <group>
163  virtual const Lattice<Bool>& pixelMask() const;
164  virtual Lattice<Bool>& pixelMask();
165  // </group>
166 
167  // Do the actual get of the mask data. The return value is always
168  // False, thus the buffer does not reference another array.
169  virtual Bool doGetMaskSlice (Array<Bool>& buffer, const Slicer& section);
170 
171  // Get the region used. There is no region.
172  // Always returns 0.
173  virtual const LatticeRegion* getRegionPtr() const;
174 
175 
176  //# Lattice virtual functions
177 
178  // Do the actual get of the data.
179  // Returns False as the data do not reference another Array
180  virtual Bool doGetSlice (Array<Float>& buffer, const Slicer& theSlice);
181 
182  // The FITSImage is not writable, so this throws an exception.
183  virtual void doPutSlice (const Array<Float>& sourceBuffer,
184  const IPosition& where,
185  const IPosition& stride);
186 
187  //# LatticeBase virtual functions
188 
189  // The lattice is paged to disk.
190  virtual Bool isPaged() const;
191 
192  // The lattice is persistent.
193  virtual Bool isPersistent() const;
194 
195  // The FITSImage is not writable.
196  virtual Bool isWritable() const;
197 
198  // Returns the name of the disk file.
199  virtual String name (Bool stripPath=False) const;
200 
201  // return the shape of the FITSImage
202  virtual IPosition shape() const;
203 
204  // Returns the maximum recommended number of pixels for a cursor. This is
205  // the number of pixels in a tile.
206  virtual uInt advisedMaxPixels() const;
207 
208  // Help the user pick a cursor for most efficient access if they only want
209  // pixel values and don't care about the order or dimension of the
210  // cursor.
211  virtual IPosition doNiceCursorShape (uInt maxPixels) const;
212 
213  // Temporarily close the image.
214  virtual void tempClose();
215 
216  // Reopen a temporarily closed image.
217  virtual void reopen();
218 
219  // Check class invariants.
220  virtual Bool ok() const;
221 
222  // Return the data type (TpFloat).
223  virtual DataType dataType() const;
224 
225  // Return the (internal) data type.
226  DataType internalDataType() const
227  { return dataType_p; }
228 
229  // Return the HDU number
230  uInt whichHDU () const
231  { return whichHDU_p; }
232 
233  // Maximum size - not necessarily all used. In pixels.
234  virtual uInt maximumCacheSize() const;
235 
236  // Set the maximum (allowed) cache size as indicated.
237  virtual void setMaximumCacheSize (uInt howManyPixels);
238 
239  // Set the cache size as to "fit" the indicated path.
240  virtual void setCacheSizeFromPath (const IPosition& sliceShape,
241  const IPosition& windowStart,
242  const IPosition& windowLength,
243  const IPosition& axisPath);
244 
245  // Set the actual cache size for this Array to be be big enough for the
246  // indicated number of tiles. This cache is not shared with PagedArrays
247  // in other rows and is always clipped to be less than the maximum value
248  // set using the setMaximumCacheSize member function.
249  // tiles. Tiles are cached using a first in first out algorithm.
250  virtual void setCacheSizeInTiles (uInt howManyTiles);
251 
252  // Clears and frees up the caches, but the maximum allowed cache size is
253  // unchanged from when setCacheSize was called
254  virtual void clearCache();
255 
256  // Report on cache success.
257  virtual void showCacheStatistics (ostream& os) const;
258 
259 protected:
260  // Set the masking of values 0.0
261  void setMaskZero(Bool filterZero);
262 
263 private:
276  DataType dataType_p;
283 
284 // Reopen the image if needed.
285  void reopenIfNeeded() const
286  { if (isClosed_p) const_cast<FITSImage*>(this)->reopen(); }
287 
288 // Setup the object (used by constructors).
289  void setup();
290 
291 // Open the image (used by setup and reopen).
292  void open();
293 
294 // Fish things out of the FITS file
296  IPosition& shape, ImageInfo& info,
297  Unit& brightnessUnit, RecordInterface& miscInfo,
298  Int& recsize, Int& recno,
299  FITS::ValueType& dataType,
300  Float& scale, Float& offset,
301  uChar& uCharMagic, Short& shortMagic,
302  Int& longMagic, Bool& hasBlanks, const String& name,
303  uInt whichRep, uInt whichHDU);
304 
305 // Crack a primary header
306  template <typename T>
308  Unit& brightnessUnit, RecordInterface& miscInfo,
309  Float& scale, Float& offset, uChar& magicUChar, Short& magicShort,
310  Int& magicLong, Bool& hasBlanks, LogIO& os, FitsInput& infile,
311  uInt whichRep);
312 
313 // Crack an image extension header
314  template <typename T>
315  void crackExtHeader (CoordinateSystem& cSys, IPosition& shape, ImageInfo& imageInfo,
316  Unit& brightnessUnit, RecordInterface& miscInfo,
317  Float& scale, Float& offset, uChar& uCharMagic,
318  Short& magicShort,
319  Int& magicLong, Bool& hasBlanks, LogIO& os, FitsInput& infile,
320  uInt whichRep);
321 
322 };
323 
324 
325 
326 } //# NAMESPACE CASACORE - END
327 
328 #ifndef CASACORE_NO_AUTO_TEMPLATES
329 #include <casacore/images/Images/FITS2Image.tcc>
330 #endif //# CASACORE_NO_AUTO_TEMPLATES
331 
332 #endif
333 
334 
A Vector of integers, for indexing into Array<T> objects.
Definition: IPosition.h:119
virtual const Lattice< Bool > & pixelMask() const
Get access to the pixelmask.
long long Int64
Define the extra non-standard types used by Casacore (like proposed uSize, Size)
Definition: aipsxtype.h:38
virtual Bool hasPixelMask() const
FITSimage always has a pixel mask so returns True.
int Int
Definition: aipstype.h:47
void setMaskZero(Bool filterZero)
Set the masking of values 0.0.
LatticeExprNode mask(const LatticeExprNode &expr)
This function returns the mask of the given expression.
virtual ImageInterface< Float > * cloneII() const
Make a copy of the object with new (reference semantics).
static LatticeBase * openFITSImage(const String &name, const MaskSpecifier &)
Function to open a FITS image (new parser)
virtual void reopen()
Reopen a temporarily closed image.
virtual uInt maximumCacheSize() const
Maximum size - not necessarily all used.
TiledShape shape_p
Definition: FITSImage.h:269
void setup()
Setup the object (used by constructors).
virtual Bool ok() const
Check class invariants.
void open()
Open the image (used by setup and reopen).
unsigned char uChar
Definition: aipstype.h:44
virtual IPosition shape() const
return the shape of the FITSImage
virtual void clearCache()
Clears and frees up the caches, but the maximum allowed cache size is unchanged from when setCacheSiz...
A non-templated, abstract base class for array-like objects.
Definition: LatticeBase.h:80
ostream-like interface to creating log messages.
Definition: LogIO.h:167
FITSImage & operator=(const FITSImage &other)
Assignment (reference semantics)
DataType dataType_p
Definition: FITSImage.h:276
ValueType
FITS I/O Error message types.
Definition: fits.h:176
virtual IPosition doNiceCursorShape(uInt maxPixels) const
Help the user pick a cursor for most efficient access if they only want pixel values and don&#39;t care a...
short Short
Definition: aipstype.h:45
void crackHeader(CoordinateSystem &cSys, IPosition &shape, ImageInfo &imageInfo, Unit &brightnessUnit, RecordInterface &miscInfo, Float &scale, Float &offset, uChar &magicUChar, Short &magicShort, Int &magicLong, Bool &hasBlanks, LogIO &os, FitsInput &infile, uInt whichRep)
Crack a primary header.
defines physical units
Definition: Unit.h:189
FITSImage(const String &name, uInt whichRep=0, uInt whichHDU=0)
Construct a FITSImage from the disk FITS file name and extension and apply mask.
virtual ~FITSImage()
Destructor does nothing.
void reopenIfNeeded() const
Reopen the image if needed.
Definition: FITSImage.h:285
DataType internalDataType() const
Return the (internal) data type.
Definition: FITSImage.h:226
Define the shape and tile shape.
Definition: TiledShape.h:99
static void registerOpenFunction()
Register the open function.
Referenced counted pointer for constant data.
Definition: CountedPtr.h:86
A base class for astronomical images.
Lattice< Bool > * pPixelMask_p
Definition: FITSImage.h:268
Class to specify which mask to use in an image.
Definition: MaskSpecifier.h:69
virtual void resize(const TiledShape &newShape)
Function which changes the shape of the FITSImage.
virtual Bool isPersistent() const
The lattice is persistent.
virtual String name(Bool stripPath=False) const
Returns the name of the disk file.
virtual Bool doGetSlice(Array< Float > &buffer, const Slicer &theSlice)
Do the actual get of the data.
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:39
static String get_fitsname(const String &fullname)
Separate any extension specification and return the pure fitsname.
uInt whichHDU() const
Return the HDU number.
Definition: FITSImage.h:230
static uInt get_hdunum(const String &fullname)
Get the extension index for any extension specification given in the full name.
virtual void doPutSlice(const Array< Float > &sourceBuffer, const IPosition &where, const IPosition &stride)
The FITSImage is not writable, so this throws an exception.
void crackExtHeader(CoordinateSystem &cSys, IPosition &shape, ImageInfo &imageInfo, Unit &brightnessUnit, RecordInterface &miscInfo, Float &scale, Float &offset, uChar &uCharMagic, Short &magicShort, Int &magicLong, Bool &hasBlanks, LogIO &os, FitsInput &infile, uInt whichRep)
Crack an image extension header.
float Float
Definition: aipstype.h:51
const ImageInfo & imageInfo() const
The ImageInfo object contains some miscellaneous information about the image which unlike that stored...
const Bool False
Definition: aipstype.h:41
Class providing native access to FITS images.
Definition: FITSImage.h:108
void getImageAttributes(CoordinateSystem &cSys, IPosition &shape, ImageInfo &info, Unit &brightnessUnit, RecordInterface &miscInfo, Int &recsize, Int &recno, FITS::ValueType &dataType, Float &scale, Float &offset, uChar &uCharMagic, Short &shortMagic, Int &longMagic, Bool &hasBlanks, const String &name, uInt whichRep, uInt whichHDU)
Fish things out of the FITS file.
const TableRecord & miscInfo() const
Often we have miscellaneous information we want to attach to an image.
virtual const LatticeRegion * getRegionPtr() const
Get the region used.
Specify which elements to extract from an n-dimensional array.
Definition: Slicer.h:275
virtual void setCacheSizeFromPath(const IPosition &sliceShape, const IPosition &windowStart, const IPosition &windowLength, const IPosition &axisPath)
Set the cache size as to "fit" the indicated path.
MaskSpecifier maskSpec_p
Definition: FITSImage.h:266
virtual String imageType() const
Get the image type (returns FITSImage).
fixed-length sequential blocked FITS input
Definition: fitsio.h:156
virtual Bool isPaged() const
The lattice is paged to disk.
String: the storage and methods of handling collections of characters.
Definition: String.h:223
An optionally strided region in a Lattice.
Definition: LatticeRegion.h:74
virtual Bool isMasked() const
Has the object really a mask? The FITSImage always has a pixel mask and never has a region mask so th...
Abstract base class for Record classes.
virtual void showCacheStatistics(ostream &os) const
Report on cache success.
Miscellaneous information related to an image.
Definition: ImageInfo.h:92
CountedPtr< TiledFileAccess > pTiledFile_p
Definition: FITSImage.h:267
this file contains all the compiler specific defines
Definition: mainpage.dox:28
virtual uInt advisedMaxPixels() const
Returns the maximum recommended number of pixels for a cursor.
Interconvert pixel and world coordinates.
virtual Bool isWritable() const
The FITSImage is not writable.
virtual DataType dataType() const
Return the data type (TpFloat).
unsigned int uInt
Definition: aipstype.h:48
virtual void tempClose()
Temporarily close the image.
virtual void setCacheSizeInTiles(uInt howManyTiles)
Set the actual cache size for this Array to be be big enough for the indicated number of tiles...
virtual void setMaximumCacheSize(uInt howManyPixels)
Set the maximum (allowed) cache size as indicated.
virtual Bool doGetMaskSlice(Array< Bool > &buffer, const Slicer &section)
Do the actual get of the mask data.