casacore
Loading...
Searching...
No Matches
ImageInfo.h
Go to the documentation of this file.
1//# ImageInfo.h: Miscellaneous information related to an image
2//# Copyright (C) 1998,1999,2000,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//#
27//# $Id$
28
29#ifndef IMAGES_IMAGEINFO_H
30#define IMAGES_IMAGEINFO_H
31
32#include <casacore/casa/aips.h>
33#include <casacore/casa/Utilities/RecordTransformable.h>
34
35#include <casacore/casa/Arrays/Vector.h>
36#include <casacore/casa/Quanta/Quantum.h>
37#include <casacore/casa/BasicSL/String.h>
38
39#include <casacore/coordinates/Coordinates/CoordinateSystem.h>
40
41#include <casacore/images/Images/ImageBeamSet.h>
42
43//# Forward declarations
44#include <casacore/casa/iosfwd.h>
45namespace casacore { //# NAMESPACE CASACORE - BEGIN
46
47class LoggerHolder;
48
49// <summary>
50// Miscellaneous information related to an image.
51// </summary>
52
53// <use visibility=export>
54
55// <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos="">
56// </reviewed>
57
58// <prerequisite>
59// <li> <linkto class=RecordTransformable>RecordTransformable</linkto>
60// </prerequisite>
61//
62// <synopsis>
63// This class is used to record information about an image.
64// At present it contains the following:
65// <ol>
66// <li> The restoring beam(s)
67// <li> A parameter describing what quantity the image holds.
68// <li> The image object name.
69// </ol>
70//
71// Support for per plane (eg channel) dependent beams have been added.
72// </synopsis>
73//
74// <example>
75// The interface is a simple get/set interface. Note that the "set" methods
76// can be chained together since each set method returns a reference to its
77// object (rather like cout).
78// <srcblock>
79// ImageInfo ii;
80// ii.setRestoringBeam(Quantity(30,"arcsec"), Quantity(10,"arcsec"),
81// Quantity(-18,"deg"));
82// ...
83// cout << "The restoring beam is : " << oi.restoringBeam() << endl;
84// </srcblock>
85// </example>
86//
87// <motivation>
88// This sort of information needed a standard place to go with a
89// standard interface so it could be moved out of MiscInfo.
90// </motivation>
91
93{
94public:
95
96 // This enum defines the actual quantity being held in an image
97 // It's really only used for descriptive information.
114
115// Default constructor
116
118
119// Destructor
121
122// Copy constructor (copy semantics)
123 ImageInfo(const ImageInfo &other);
124
125// Assignment (copy semantics)
127
128 // Set and get the Image Type.
129 // <group>
134 // </group>
135
136// Set and get the Image object name
137// <group>
140// </group>
141
142// Functions to interconvert between an ImageInfo and a record. These
143// functions are inherited from class
144// <linkto class=RecordTransformable>RecordTransformable</linkto>. As new
145// fields get added to ImageInfo these functions should be augmented. Missing
146// fields should not generate an error to in fromRecord to allow for
147// backwards compatibility - null values should be supplied instead.
148// The record field names are: "restoringbeam, imagetype, objectname".
149// <group>
150 virtual Bool toRecord(String& error, RecordInterface& outRecord) const;
151 virtual Bool fromRecord(String& error, const RecordInterface& inRecord);
152// </group>
153
154// In some circumstances it might be useful to know what the defaults for
155// the various values are so you can check if they have been set.
156// The default restoring beam is a null vector.
157// <group>
161// </group>
162
163// Functions to interconvert between an ImageInfo and FITS keywords
164// (converted to a Record). Failure of <src>fromFITS</src>
165// should probably not be regarded as fatal as the default ImageInfo
166// values are viable. For each item contained
167// in the ImageInfo, an attempt to decode it from FITS is made.
168// If any of them fail, False is returned, but it attempts to decode
169// them all. For those that fail an error message is held in <src>error</src>
170// in the order restoring beam, and image type.
171// <src>error</src> will be returned of length 0 if the return
172// value is True, else it will be length 2.
173// <group>
174 Bool toFITS(String & error, RecordInterface & outRecord) const;
175 Bool fromFITS(Vector<String>& error, const RecordInterface & inRecord);
176// </group>
177
178// This function takes an unofficial fitsValue found on the Stokes axis
179// and returns the appropriate ImageType. The idea is that you
180// detect the unofficial value, drop the Stokes axis, and store
181// the value as an ImageType in ImageInfo. Only values pertaining
182// to beam, optical depth and spectral index are handled here. All others
183// give back Undefined. See usage in Image FITS conversion classes.
185
186// It might be useful to know what FITS keyword names are used in to/from
187// FITS so we can remove them so they won't be used more than once. The
188// names are in lower case.
190
191// Convert the Miriad 'btype' strings to the ImageType. Some
192// Miriad 'btype's are dealt with in Casacore via the Stokes
193// axis (fractional_polarization, polarized_intensity, position_angle)
194// and so these will return Undefined.
196
197 // Set and get the beam.
198 // Zero-based <src>channel</src> and <src>stokes</src> are
199 // necessary and used if and only if the ImageBeamSet
200 // has multiple beams for such an axis. If just a single beam, that beam
201 // is returned. If no (or a null) beam, a null beam is returned.
202 GaussianBeam restoringBeam(Int channel=-1, Int stokes=-1) const;
203
204 // Set the single global restoring beam. An exception will be
205 // thrown if this object already has multiple beams. In that case,
206 // the caller must call removeRestoringBeam() first.
208 //#/// Added to build casarest with nrao-nov12
210 const Quantum<Double>& minor,
211 const Quantum<Double>& pa)
212 { setRestoringBeam (GaussianBeam (major, minor, pa)); }
213
214 // Remove all beams (global or per plane) associated with this object.
216
217 // Get the beam set associated with this object
218 const ImageBeamSet& getBeamSet() const;
219
220 // Set the beam for a specific plane.
221 // A value of <src>channel</src> or <src>stokes</src> of less than 0
222 // means that particular coordinate does not exist. Obviously, at least
223 // one of these must be zero or greater. The only consistency checking
224 // that is done is to ensure the values of <src>channel</src> and
225 // <src>stokes</src> are consistent with the size of the beam array.
226 // Additional consistency checks are done when this object is added via
227 // ImageInterface<T>::setImageInfo().
228 // <br>This function cannot be used if no beams have been set via set(All)Beams.
229 // <group>
230 void setBeam(Int channel, Int stokes, const Quantity& major,
231 const Quantity& minor, const Quantity& pa);
232
233 void setBeam(Int channel, Int stokes, const GaussianBeam& beam);
234 // </group>
235
236 // does this object contain multiple beams?
238 { return _beams.hasMultiBeam(); }
239
240 // does this object contain a single beam
242 { return _beams.hasSingleBeam(); }
243
244 // Does this object contain one or more beams?
245 Bool hasBeam() const
246 { return ! _beams.empty(); }
247
248 // <group>
249 // Number of channels and stokes in per hyper-plane beam array
251 { return _beams.nchan(); }
252 uInt nStokes() const
253 { return _beams.nstokes(); }
254 // </group>
255
256 // <group>
257 // Initialize all per-plane beams to the same value
259 const uInt nChannels, const uInt nStokes,
260 const GaussianBeam& beam
261 );
262
263 // Set the per plane beams array directly.
264 void setBeams(const ImageBeamSet& beams);
265 // </group>
266
267 // This method is not meant for common use. New code should not use it.
268 // Get the restoring beam from a LoggerHolder (where the history is stored)
269 // as AIPS writes the beam in the FITS history rather than the header
270 // keywords. If there is no beam, False is returned, and the internal
271 // state of the object is unchanged.
273
274 // Convert the given beam to a Record.
275 Record beamToRecord(Int channel, Int stokes) const;
276
277 // Check if the beam set matches the coordinate axes sizes.
278 void checkBeamSet (const CoordinateSystem& coords,
279 const IPosition& shape,
280 const String& imageName) const;
281
282 // Append the other beamset to this one.
283 void appendBeams (ImageInfo& infoThat,
284 Int axis, Bool relax, LogIO& os,
285 const CoordinateSystem& csysThis,
286 const CoordinateSystem& csysThat,
287 const IPosition& shapeThis,
288 const IPosition& shapeThat);
289
290 // Combine beam sets for the concatenation of images and replace
291 // the beamset in this object by the result.
292 // If channel or stokes is the concatenation axis, that beam axis
293 // is concatenated. Otherwise it is checked if both beam sets
294 // match and are merged.
295 // If relax=False, an exception is thrown if mismatching.
296 void combineBeams (const ImageInfo& infoThat,
297 const IPosition& shapeThis,
298 const IPosition& shapeThat,
299 const CoordinateSystem& csysThis,
300 const CoordinateSystem& csysThat,
301 Int axis,
302 Bool relax,
303 LogIO& os);
304
305 // Reset the info and beamset of this image with the appropriate part of
306 // the beam set of the concat image it is part of.
307 // It returns the number of channels or polarizations handled.
308 uInt setInfoSplitBeamSet (uInt ndone, const ImageInfo& concatInfo,
309 const IPosition& shape,
310 const CoordinateSystem& csys, Int concatAxis);
311
312 // Concatenate the beam sets along the frequency axis.
314 const ImageInfo& infoThat,
315 Int nchanThis,
316 Int nchanThat,
317 Bool relax,
318 LogIO& os) const;
319
320 // Concatenate the beam sets along the stokes axis.
322 const ImageInfo& infoThat,
323 Int npolThis,
324 Int npolThat,
325 Bool relax,
326 LogIO& os) const;
327
328 // Merge the beam sets and check if they match.
329 void mergeBeams (ImageBeamSet& beamsOut,
330 const ImageInfo& infoThat,
331 Bool relax,
332 LogIO& os) const;
333
334 // If relax=True, give a warning message if warn=True and set to False.
335 // Otherwise give an error showing msg1 only.
336 static void logMessage(Bool& warn, LogIO& os, Bool relax,
337 const String& msg1, const String msg2=String());
338
339 // Get the beam area in terms of pixel size of the specified
340 // DirectionCoordinate
342 const DirectionCoordinate&) const;
343
345 const GaussianBeam& beam, const DirectionCoordinate& dc
346 );
347
348private:
349 // Common copy ctor/assignment operator code.
350 void copy_other(const ImageInfo &other);
351
352 // Set the restoring beam from the record.
353 void _setRestoringBeam(const Record& inRecord);
354
355 // Check if the beam shape matches the coordinates.
356 // It sets nchan and npol to the values in the image shape.
357 void _checkBeamShape (uInt& nchan, uInt& npol,
358 const IPosition& shape,
359 const CoordinateSystem& csys) const;
360
361 //# Data members
363 mutable Bool _warnBeam; //# tell if warning is already given
366};
367
368// <summary> Global functions </summary>
369// <group name=Output>
370// Output declaration - useful for debugging.
371ostream &operator<<(ostream &os, const ImageInfo &info);
372// </group>
374
375
376} //# NAMESPACE CASACORE - END
377
378#endif
uInt nstokes() const
Get the number of stokes in the beam array.
Bool hasMultiBeam() const
Does this beam set contain multiple beams?
Bool empty() const
Is the beam set empty?
uInt nchan() const
Get the number of channels in the beam array.
Bool hasSingleBeam() const
void removeRestoringBeam()
Remove all beams (global or per plane) associated with this object.
void concatPolBeams(ImageBeamSet &beamsOut, const ImageInfo &infoThat, Int npolThis, Int npolThat, Bool relax, LogIO &os) const
Concatenate the beam sets along the stokes axis.
Bool hasSingleBeam() const
does this object contain a single beam
Definition ImageInfo.h:241
virtual Bool toRecord(String &error, RecordInterface &outRecord) const
Functions to interconvert between an ImageInfo and a record.
static ImageInfo::ImageTypes imageTypeFromFITS(Int fitsValue)
This function takes an unofficial fitsValue found on the Stokes axis and returns the appropriate Imag...
void concatFreqBeams(ImageBeamSet &beamsOut, const ImageInfo &infoThat, Int nchanThis, Int nchanThat, Bool relax, LogIO &os) const
Concatenate the beam sets along the frequency axis.
void _setRestoringBeam(const Record &inRecord)
Set the restoring beam from the record.
void setAllBeams(const uInt nChannels, const uInt nStokes, const GaussianBeam &beam)
Initialize all per-plane beams to the same value.
static ImageTypes defaultImageType()
In some circumstances it might be useful to know what the defaults for the various values are so you ...
ImageInfo(const ImageInfo &other)
Copy constructor (copy semantics)
ImageInfo()
Default constructor.
Bool hasMultipleBeams() const
does this object contain multiple beams?
Definition ImageInfo.h:237
void setBeam(Int channel, Int stokes, const Quantity &major, const Quantity &minor, const Quantity &pa)
Set the beam for a specific plane.
static String imageType(ImageInfo::ImageTypes type)
GaussianBeam restoringBeam(Int channel=-1, Int stokes=-1) const
Set and get the beam.
ImageBeamSet _beams
Definition ImageInfo.h:362
Bool toFITS(String &error, RecordInterface &outRecord) const
Functions to interconvert between an ImageInfo and FITS keywords (converted to a Record).
void _checkBeamShape(uInt &nchan, uInt &npol, const IPosition &shape, const CoordinateSystem &csys) const
Check if the beam shape matches the coordinates.
static void logMessage(Bool &warn, LogIO &os, Bool relax, const String &msg1, const String msg2=String())
If relax=True, give a warning message if warn=True and set to False.
void copy_other(const ImageInfo &other)
Common copy ctor/assignment operator code.
void setBeams(const ImageBeamSet &beams)
Set the per plane beams array directly.
uInt setInfoSplitBeamSet(uInt ndone, const ImageInfo &concatInfo, const IPosition &shape, const CoordinateSystem &csys, Int concatAxis)
Reset the info and beamset of this image with the appropriate part of the beam set of the concat imag...
~ImageInfo()
Destructor.
virtual Bool fromRecord(String &error, const RecordInterface &inRecord)
Initialise the class from a Record representation.
static String defaultObjectName()
const ImageBeamSet & getBeamSet() const
Get the beam set associated with this object.
ImageTypes
This enum defines the actual quantity being held in an image It's really only used for descriptive in...
Definition ImageInfo.h:98
void setBeam(Int channel, Int stokes, const GaussianBeam &beam)
static ImageInfo::ImageTypes MiriadImageType(const String &type)
Convert the Miriad 'btype' strings to the ImageType.
Bool getRestoringBeam(LoggerHolder &logger)
This method is not meant for common use.
uInt nChannels() const
Number of channels and stokes in per hyper-plane beam array.
Definition ImageInfo.h:250
ImageInfo::ImageTypes imageType() const
Set and get the Image Type.
void setRestoringBeam(const GaussianBeam &beam)
Set the single global restoring beam.
static ImageInfo::ImageTypes imageType(String type)
void setRestoringBeam(const Quantum< Double > &major, const Quantum< Double > &minor, const Quantum< Double > &pa)
Definition ImageInfo.h:209
void appendBeams(ImageInfo &infoThat, Int axis, Bool relax, LogIO &os, const CoordinateSystem &csysThis, const CoordinateSystem &csysThat, const IPosition &shapeThis, const IPosition &shapeThat)
Append the other beamset to this one.
ImageInfo & setImageType(ImageTypes type)
ImageTypes itsImageType
Definition ImageInfo.h:364
static Vector< String > keywordNamesFITS()
It might be useful to know what FITS keyword names are used in to/from FITS so we can remove them so ...
Bool fromFITS(Vector< String > &error, const RecordInterface &inRecord)
ImageInfo & operator=(const ImageInfo &other)
Assignment (copy semantics)
void mergeBeams(ImageBeamSet &beamsOut, const ImageInfo &infoThat, Bool relax, LogIO &os) const
Merge the beam sets and check if they match.
uInt nStokes() const
Definition ImageInfo.h:252
ImageInfo & setObjectName(const String &object)
String objectName() const
Set and get the Image object name.
void checkBeamSet(const CoordinateSystem &coords, const IPosition &shape, const String &imageName) const
Check if the beam set matches the coordinate axes sizes.
static Double getBeamAreaInPixels(const GaussianBeam &beam, const DirectionCoordinate &dc)
Double getBeamAreaInPixels(Int channel, Int stokes, const DirectionCoordinate &) const
Get the beam area in terms of pixel size of the specified DirectionCoordinate.
Record beamToRecord(Int channel, Int stokes) const
Convert the given beam to a Record.
static GaussianBeam defaultRestoringBeam()
void combineBeams(const ImageInfo &infoThat, const IPosition &shapeThis, const IPosition &shapeThat, const CoordinateSystem &csysThis, const CoordinateSystem &csysThat, Int axis, Bool relax, LogIO &os)
Combine beam sets for the concatenation of images and replace the beamset in this object by the resul...
Bool hasBeam() const
Does this object contain one or more beams?
Definition ImageInfo.h:245
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
LatticeExprNode pa(const LatticeExprNode &left, const LatticeExprNode &right)
This function finds 180/pi*atan2(left,right)/2.
ostream & operator<<(ostream &os, const IComplex &)
Show on ostream.
unsigned int uInt
Definition aipstype.h:51
TableExprNode shape(const TableExprNode &array)
Function operating on any scalar or array resulting in a Double array containing the shape.
Definition ExprNode.h:1987
int Int
Definition aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:42
double Double
Definition aipstype.h:55
ostream & operator<<(ostream &os, const ImageInfo &info)
Output declaration - useful for debugging.