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/casa/Arrays/ArrayFwd.h>
35#include <casacore/images/Images/ImageInterface.h>
36#include <casacore/images/Images/MaskSpecifier.h>
37#include <casacore/tables/DataMan/TiledFileAccess.h>
38#include <casacore/lattices/Lattices/TiledShape.h>
39#include <casacore/fits/FITS/fits.h>
40#include <casacore/casa/BasicSL/String.h>
41#include <casacore/casa/Utilities/DataType.h>
42
43#ifndef WCSLIB_GETWCSTAB
44 #define WCSLIB_GETWCSTAB
45#endif
46
47namespace casacore { //# NAMESPACE CASACORE - BEGIN
48
49//# Forward Declarations
50template <class T> class Lattice;
51//
52class MaskSpecifier;
53class IPosition;
54class Slicer;
55class CoordinateSystem;
56class FITSMask;
57class 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
108class FITSImage: public ImageInterface<Float>
109{
110public:
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)
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).
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.
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
263protected:
264 // Set the masking of values 0.0
265 void setMaskZero(Bool filterZero);
266
267private:
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
Referenced counted pointer for constant data.
Definition: CountedPtr.h:81
virtual const Lattice< Bool > & pixelMask() const
Get access to the pixelmask.
virtual const LatticeRegion * getRegionPtr() const
Get the region used.
virtual void setMaximumCacheSize(uInt howManyPixels)
Set the maximum (allowed) cache size as indicated.
virtual String imageType() const
Get the image type (returns FITSImage).
DataType internalDataType() const
Return the (internal) data type.
Definition: FITSImage.h:230
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.
Lattice< Bool > * pPixelMask_p
Definition: FITSImage.h:272
virtual IPosition shape() const
return the shape of the FITSImage
virtual Bool doGetSlice(Array< Float > &buffer, const Slicer &theSlice)
Do the actual get of the data.
FITSImage(const FITSImage &other)
Copy constructor (reference semantics)
CountedPtr< TiledFileAccess > pTiledFile_p
Definition: FITSImage.h:271
virtual ~FITSImage()
Destructor does nothing.
TiledShape shape_p
Definition: FITSImage.h:273
FITSImage & operator=(const FITSImage &other)
Assignment (reference semantics)
virtual void clearCache()
Clears and frees up the caches, but the maximum allowed cache size is unchanged from when setCacheSiz...
virtual void resize(const TiledShape &newShape)
Function which changes the shape of the FITSImage.
MaskSpecifier maskSpec_p
Definition: FITSImage.h:270
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.
void reopenIfNeeded() const
Reopen the image if needed.
Definition: FITSImage.h:289
virtual void doPutSlice(const Array< Float > &sourceBuffer, const IPosition &where, const IPosition &stride)
The FITSImage is not writable, so this throws an exception.
virtual Bool isWritable() const
The FITSImage is not writable.
void open()
Open the image (used by setup and reopen).
uInt whichHDU() const
Return the HDU number.
Definition: FITSImage.h:234
static String className()
returns "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.
virtual uInt advisedMaxPixels() const
Returns the maximum recommended number of pixels for a cursor.
void setMaskZero(Bool filterZero)
Set the masking of values 0.0.
virtual Bool doGetMaskSlice(Array< Bool > &buffer, const Slicer &section)
Do the actual get of the mask data.
DataType dataType_p
Definition: FITSImage.h:280
static String get_fitsname(const String &fullname)
Separate any extension specification and return the pure fitsname.
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.
void setup()
Setup the object (used by constructors).
virtual Bool ok() const
Check class invariants.
virtual void reopen()
Reopen a temporarily closed image.
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...
virtual String name(Bool stripPath=False) const
Returns the name of the disk file.
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...
virtual Bool isPaged() const
The lattice is paged to disk.
virtual Bool hasPixelMask() const
FITSimage always has a pixel mask so returns True.
virtual Lattice< Bool > & pixelMask()
virtual uInt maximumCacheSize() const
Maximum size - not necessarily all used.
virtual ImageInterface< Float > * cloneII() const
Make a copy of the object with new (reference semantics).
virtual DataType dataType() const
Return the data type (TpFloat).
static LatticeBase * openFITSImage(const String &name, const MaskSpecifier &)
Function to open a FITS image (new parser)
virtual void tempClose()
Temporarily close the image.
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.
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.
static uInt get_hdunum(const String &fullname)
Get the extension index for any extension specification given in the full name.
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 Bool isPersistent() const
The lattice is persistent.
static void registerOpenFunction()
Register the open function.
virtual void showCacheStatistics(ostream &os) const
Report on cache success.
ValueType
FITS I/O Error message types.
Definition: fits.h:167
fixed-length sequential blocked FITS input
Definition: fitsio.h:156
const ImageInfo & imageInfo() const
The ImageInfo object contains some miscellaneous information about the image which unlike that stored...
const TableRecord & miscInfo() const
Often we have miscellaneous information we want to attach to an image.
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
unsigned char uChar
Definition: aipstype.h:47
const Bool False
Definition: aipstype.h:44
short Short
Definition: aipstype.h:48
unsigned int uInt
Definition: aipstype.h:51
LatticeExprNode mask(const LatticeExprNode &expr)
This function returns the mask of the given expression.
long long Int64
Define the extra non-standard types used by Casacore (like proposed uSize, Size)
Definition: aipsxtype.h:38
float Float
Definition: aipstype.h:54
int Int
Definition: aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42