casacore
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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>
42 
43 #ifndef WCSLIB_GETWCSTAB
44  #define WCSLIB_GETWCSTAB
45 #endif
46 
47 namespace casacore { //# NAMESPACE CASACORE - BEGIN
48 
49 //# Forward Declarations
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  // 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;
168  virtual Lattice<Bool>& pixelMask();
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,
303  FITS::ValueType& dataType,
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 
A Vector of integers, for indexing into Array&lt;T&gt; objects.
Definition: IPosition.h:118
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:50
static String className()
returns &quot;FITSImage&quot;.
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:273
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:47
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:280
ValueType
FITS I/O Error message types.
Definition: fits.h:167
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:48
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:289
DataType internalDataType() const
Return the (internal) data type.
Definition: FITSImage.h:230
Define the shape and tile shape.
Definition: TiledShape.h:96
static void registerOpenFunction()
Register the open function.
Referenced counted pointer for constant data.
Definition: CountedPtr.h:80
A base class for astronomical images.
Lattice< Bool > * pPixelMask_p
Definition: FITSImage.h:272
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:42
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:234
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:54
const ImageInfo & imageInfo() const
The ImageInfo object contains some miscellaneous information about the image which unlike that stored...
const Bool False
Definition: aipstype.h:44
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:288
virtual void setCacheSizeFromPath(const IPosition &sliceShape, const IPosition &windowStart, const IPosition &windowLength, const IPosition &axisPath)
Set the cache size as to &quot;fit&quot; the indicated path.
MaskSpecifier maskSpec_p
Definition: FITSImage.h:270
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:225
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:271
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:51
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.