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)
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  // returns "FITSImage". Added so callers don't require an object to get
148  // the image type.
149  static String className();
150 
151  // Function which changes the shape of the FITSImage.
152  // Throws an exception as FITSImage is not writable.
153  virtual void resize(const TiledShape& newShape);
154 
155  //# MaskedLattice virtual functions
156 
157  // Has the object really a mask? The FITSImage always
158  // has a pixel mask and never has a region mask so this
159  // always returns True
160  virtual Bool isMasked() const;
161 
162  // FITSimage always has a pixel mask so returns True
163  virtual Bool hasPixelMask() const;
164 
165  // Get access to the pixelmask. FITSImage always has a pixel mask.
166  // <group>
167  virtual const Lattice<Bool>& pixelMask() const;
169  // </group>
170 
171  // Do the actual get of the mask data. The return value is always
172  // False, thus the buffer does not reference another array.
173  virtual Bool doGetMaskSlice (Array<Bool>& buffer, const Slicer& section);
174 
175  // Get the region used. There is no region.
176  // Always returns 0.
177  virtual const LatticeRegion* getRegionPtr() const;
178 
179 
180  //# Lattice virtual functions
181 
182  // Do the actual get of the data.
183  // Returns False as the data do not reference another Array
184  virtual Bool doGetSlice (Array<Float>& buffer, const Slicer& theSlice);
185 
186  // The FITSImage is not writable, so this throws an exception.
187  virtual void doPutSlice (const Array<Float>& sourceBuffer,
188  const IPosition& where,
189  const IPosition& stride);
190 
191  //# LatticeBase virtual functions
192 
193  // The lattice is paged to disk.
194  virtual Bool isPaged() const;
195 
196  // The lattice is persistent.
197  virtual Bool isPersistent() const;
198 
199  // The FITSImage is not writable.
200  virtual Bool isWritable() const;
201 
202  // Returns the name of the disk file.
203  virtual String name (Bool stripPath=False) const;
204 
205  // return the shape of the FITSImage
206  virtual IPosition shape() const;
207 
208  // Returns the maximum recommended number of pixels for a cursor. This is
209  // the number of pixels in a tile.
210  virtual uInt advisedMaxPixels() const;
211 
212  // Help the user pick a cursor for most efficient access if they only want
213  // pixel values and don't care about the order or dimension of the
214  // cursor.
215  virtual IPosition doNiceCursorShape (uInt maxPixels) const;
216 
217  // Temporarily close the image.
218  virtual void tempClose();
219 
220  // Reopen a temporarily closed image.
221  virtual void reopen();
222 
223  // Check class invariants.
224  virtual Bool ok() const;
225 
226  // Return the data type (TpFloat).
227  virtual DataType dataType() const;
228 
229  // Return the (internal) data type.
230  DataType internalDataType() const
231  { return dataType_p; }
232 
233  // Return the HDU number
234  uInt whichHDU () const
235  { return whichHDU_p; }
236 
237  // Maximum size - not necessarily all used. In pixels.
238  virtual uInt maximumCacheSize() const;
239 
240  // Set the maximum (allowed) cache size as indicated.
241  virtual void setMaximumCacheSize (uInt howManyPixels);
242 
243  // Set the cache size as to "fit" the indicated path.
244  virtual void setCacheSizeFromPath (const IPosition& sliceShape,
245  const IPosition& windowStart,
246  const IPosition& windowLength,
247  const IPosition& axisPath);
248 
249  // Set the actual cache size for this Array to be be big enough for the
250  // indicated number of tiles. This cache is not shared with PagedArrays
251  // in other rows and is always clipped to be less than the maximum value
252  // set using the setMaximumCacheSize member function.
253  // tiles. Tiles are cached using a first in first out algorithm.
254  virtual void setCacheSizeInTiles (uInt howManyTiles);
255 
256  // Clears and frees up the caches, but the maximum allowed cache size is
257  // unchanged from when setCacheSize was called
258  virtual void clearCache();
259 
260  // Report on cache success.
261  virtual void showCacheStatistics (ostream& os) const;
262 
263 protected:
264  // Set the masking of values 0.0
265  void setMaskZero(Bool filterZero);
266 
267 private:
280  DataType dataType_p;
287 
288 // Reopen the image if needed.
289  void reopenIfNeeded() const
290  { if (isClosed_p) const_cast<FITSImage*>(this)->reopen(); }
291 
292 // Setup the object (used by constructors).
293  void setup();
294 
295 // Open the image (used by setup and reopen).
296  void open();
297 
298 // Fish things out of the FITS file
300  IPosition& shape, ImageInfo& info,
301  Unit& brightnessUnit, RecordInterface& miscInfo,
302  Int& recsize, Int& recno,
304  Float& scale, Float& offset,
305  uChar& uCharMagic, Short& shortMagic,
306  Int& longMagic, Bool& hasBlanks, const String& name,
307  uInt whichRep, uInt whichHDU);
308 
309 // Crack a primary header
310  template <typename T>
312  Unit& brightnessUnit, RecordInterface& miscInfo,
313  Float& scale, Float& offset, uChar& magicUChar, Short& magicShort,
314  Int& magicLong, Bool& hasBlanks, LogIO& os, FitsInput& infile,
315  uInt whichRep);
316 
317 // Crack an image extension header
318  template <typename T>
320  Unit& brightnessUnit, RecordInterface& miscInfo,
321  Float& scale, Float& offset, uChar& uCharMagic,
322  Short& magicShort,
323  Int& magicLong, Bool& hasBlanks, LogIO& os, FitsInput& infile,
324  uInt whichRep);
325 
326 };
327 
328 
329 
330 } //# NAMESPACE CASACORE - END
331 
332 #ifndef CASACORE_NO_AUTO_TEMPLATES
333 #include <casacore/images/Images/FITS2Image.tcc>
334 #endif //# CASACORE_NO_AUTO_TEMPLATES
335 
336 #endif
337 
338 
casacore::FITSImage::doNiceCursorShape
virtual IPosition doNiceCursorShape(uInt maxPixels) const
Help the user pick a cursor for most efficient access if they only want pixel values and don't care a...
casacore::CoordinateSystem
Definition: CoordinateSystem.h:218
casacore::ImageInterface
Definition: ImageInterface.h:147
casacore::Slicer
Definition: Slicer.h:290
casacore::FITSImage::isWritable
virtual Bool isWritable() const
The FITSImage is not writable.
casacore::FITSImage::whichRep_p
uInt whichRep_p
Definition: FITSImage.h:284
casacore::FITSImage::filterZeroMask_p
Bool filterZeroMask_p
Definition: FITSImage.h:283
casacore::FITSImage::isPersistent
virtual Bool isPersistent() const
The lattice is persistent.
casacore::FITSImage::get_fitsname
static String get_fitsname(const String &fullname)
Separate any extension specification and return the pure fitsname.
casacore::IPosition
Definition: IPosition.h:120
casacore::FITSImage::resize
virtual void resize(const TiledShape &newShape)
Function which changes the shape of the FITSImage.
casacore::FITSImage::longMagic_p
Int longMagic_p
Definition: FITSImage.h:278
casacore::FITSImage::maximumCacheSize
virtual uInt maximumCacheSize() const
Maximum size - not necessarily all used.
casacore::FITSImage::doGetSlice
virtual Bool doGetSlice(Array< Float > &buffer, const Slicer &theSlice)
Do the actual get of the data.
casacore::FITSImage::setMaximumCacheSize
virtual void setMaximumCacheSize(uInt howManyPixels)
Set the maximum (allowed) cache size as indicated.
casacore::FITSImage::doGetMaskSlice
virtual Bool doGetMaskSlice(Array< Bool > &buffer, const Slicer &section)
Do the actual get of the mask data.
casacore::ImageInterface< Float >::miscInfo
const TableRecord & miscInfo() const
Often we have miscellaneous information we want to attach to an image.
Definition: ImageInterface.h:228
casacore::FITSImage::pixelMask
virtual const Lattice< Bool > & pixelMask() const
Get access to the pixelmask.
casacore::FITSImage::pPixelMask_p
Lattice< Bool > * pPixelMask_p
Definition: FITSImage.h:272
casacore::FITSImage::hasPixelMask
virtual Bool hasPixelMask() const
FITSimage always has a pixel mask so returns True.
casacore::CountedPtr
Referenced counted pointer for constant data.
Definition: CountedPtr.h:81
casacore::uChar
unsigned char uChar
Definition: aipstype.h:47
casacore::FITSImage::offset_p
Float offset_p
Definition: FITSImage.h:275
casacore::FITSImage::whichHDU
uInt whichHDU() const
Return the HDU number.
Definition: FITSImage.h:234
casacore::FITSImage::imageType
virtual String imageType() const
Get the image type (returns FITSImage).
casacore::FITSImage::pTiledFile_p
CountedPtr< TiledFileAccess > pTiledFile_p
Definition: FITSImage.h:271
casacore::FITSImage::setCacheSizeInTiles
virtual void setCacheSizeInTiles(uInt howManyTiles)
Set the actual cache size for this Array to be be big enough for the indicated number of tiles.
casacore::FITSImage::maskSpec_p
MaskSpecifier maskSpec_p
Definition: FITSImage.h:270
casacore::FITSImage::name_p
String name_p
Definition: FITSImage.h:268
casacore::FITSImage::className
static String className()
returns "FITSImage".
casacore::LatticeRegion
Definition: LatticeRegion.h:75
casacore::FITSImage::cloneII
virtual ImageInterface< Float > * cloneII() const
Make a copy of the object with new (reference semantics).
casacore::FITSImage::clearCache
virtual void clearCache()
Clears and frees up the caches, but the maximum allowed cache size is unchanged from when setCacheSiz...
casacore::FITSImage::hasBlanks_p
Bool hasBlanks_p
Definition: FITSImage.h:279
casacore::FITSImage::showCacheStatistics
virtual void showCacheStatistics(ostream &os) const
Report on cache success.
casacore::FITSImage::shortMagic_p
Short shortMagic_p
Definition: FITSImage.h:276
casacore::FITSImage::ok
virtual Bool ok() const
Check class invariants.
casacore::FITSImage::FITSImage
FITSImage(const FITSImage &other)
Copy constructor (reference semantics)
casacore::LogIO
Definition: LogIO.h:168
casacore::Float
float Float
Definition: aipstype.h:54
casacore::FITSImage::setMaskZero
void setMaskZero(Bool filterZero)
Set the masking of values 0.0.
casacore::FITSImage::name
virtual String name(Bool stripPath=False) const
Returns the name of the disk file.
casacore::FITSImage::isPaged
virtual Bool isPaged() const
The lattice is paged to disk.
casacore::False
const Bool False
Definition: aipstype.h:44
casacore::FITSImage::fullname_p
String fullname_p
Definition: FITSImage.h:269
casacore::FITSImage::get_hdunum
static uInt get_hdunum(const String &fullname)
Get the extension index for any extension specification given in the full name.
casacore::uInt
unsigned int uInt
Definition: aipstype.h:51
casacore::FITS::ValueType
ValueType
FITS I/O Error message types.
Definition: fits.h:171
casacore::FITSImage::fileOffset_p
Int64 fileOffset_p
Definition: FITSImage.h:281
casacore::FITSImage::dataType_p
DataType dataType_p
Definition: FITSImage.h:280
casacore::LatticeBase
Definition: LatticeBase.h:81
casacore::MaskSpecifier
Definition: MaskSpecifier.h:70
casacore::FITSImage::openFITSImage
static LatticeBase * openFITSImage(const String &name, const MaskSpecifier &)
Function to open a FITS image (new parser)
casacore::FITSImage::pixelMask
virtual Lattice< Bool > & pixelMask()
casacore::Int
int Int
Definition: aipstype.h:50
casacore
this file contains all the compiler specific defines
Definition: mainpage.dox:28
casacore::FITSImage::crackHeader
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.
casacore::FITSImage::FITSImage
FITSImage(const String &name, const MaskSpecifier &mask, uInt whichRep=0, uInt whichHDU=0)
Construct a FITSImage from the disk FITS file name and extension and apply mask or not.
casacore::FITSImage::reopenIfNeeded
void reopenIfNeeded() const
Reopen the image if needed.
Definition: FITSImage.h:289
casacore::FITSImage::getRegionPtr
virtual const LatticeRegion * getRegionPtr() const
Get the region used.
casacore::FITSImage::internalDataType
DataType internalDataType() const
Return the (internal) data type.
Definition: FITSImage.h:230
casacore::FITSImage::registerOpenFunction
static void registerOpenFunction()
Register the open function.
casacore::FITSImage
Definition: FITSImage.h:109
casacore::FitsInput
fixed-length sequential blocked FITS input
Definition: fitsio.h:156
casacore::FITSImage::_hasBeamsTable
Bool _hasBeamsTable
Definition: FITSImage.h:286
casacore::RecordInterface
Definition: RecordInterface.h:145
casacore::ImageInterface< Float >::imageInfo
const ImageInfo & imageInfo() const
The ImageInfo object contains some miscellaneous information about the image which unlike that stored...
Definition: ImageInterface.h:240
casacore::Int64
long long Int64
Define the extra non-standard types used by Casacore (like proposed uSize, Size)
Definition: aipsxtype.h:38
casacore::FITSImage::crackExtHeader
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.
casacore::mask
LatticeExprNode mask(const LatticeExprNode &expr)
This function returns the mask of the given expression.
casacore::Lattice< Bool >
casacore::FITSImage::shape
virtual IPosition shape() const
return the shape of the FITSImage
casacore::Array< Bool >
casacore::String
String: the storage and methods of handling collections of characters.
Definition: String.h:223
casacore::FITSImage::dataType
virtual DataType dataType() const
Return the data type (TpFloat).
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
casacore::FITSImage::shape_p
TiledShape shape_p
Definition: FITSImage.h:273
casacore::FITSImage::operator=
FITSImage & operator=(const FITSImage &other)
Assignment (reference semantics)
casacore::FITSImage::isClosed_p
Bool isClosed_p
Definition: FITSImage.h:282
casacore::FITSImage::FITSImage
FITSImage(const String &name, uInt whichRep=0, uInt whichHDU=0)
Construct a FITSImage from the disk FITS file name and extension and apply mask.
casacore::Short
short Short
Definition: aipstype.h:48
casacore::Unit
Definition: Unit.h:189
casacore::FITSImage::tempClose
virtual void tempClose()
Temporarily close the image.
casacore::FITSImage::scale_p
Float scale_p
Definition: FITSImage.h:274
casacore::FITSImage::reopen
virtual void reopen()
Reopen a temporarily closed image.
casacore::FITSImage::open
void open()
Open the image (used by setup and reopen).
casacore::FITSImage::advisedMaxPixels
virtual uInt advisedMaxPixels() const
Returns the maximum recommended number of pixels for a cursor.
casacore::FITSImage::setup
void setup()
Setup the object (used by constructors).
casacore::FITSImage::isMasked
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...
casacore::FITSImage::uCharMagic_p
uChar uCharMagic_p
Definition: FITSImage.h:277
casacore::FITSImage::doPutSlice
virtual void doPutSlice(const Array< Float > &sourceBuffer, const IPosition &where, const IPosition &stride)
The FITSImage is not writable, so this throws an exception.
casacore::FITSImage::getImageAttributes
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.
casacore::TiledShape
Definition: TiledShape.h:100
casacore::FITSImage::~FITSImage
virtual ~FITSImage()
Destructor does nothing.
casacore::FITSImage::setCacheSizeFromPath
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.
casacore::ImageInfo
Definition: ImageInfo.h:93
casacore::FITSImage::whichHDU_p
uInt whichHDU_p
Definition: FITSImage.h:285