casa  5.7.0-16
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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>
34 
38 
40 
42 
43 //# Forward declarations
44 #include <casacore/casa/iosfwd.h>
45 namespace casacore { //# NAMESPACE CASACORE - BEGIN
46 
47 class 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 {
94 public:
95 
96  // This enum defines the actual quantity being held in an image
97  // It's really only used for descriptive information.
98  enum ImageTypes {
113  };
114 
115 // Default constructor
116 
117  ImageInfo();
118 
119 // Destructor
120  ~ImageInfo();
121 
122 // Copy constructor (copy semantics)
123  ImageInfo(const ImageInfo &other);
124 
125 // Assignment (copy semantics)
126  ImageInfo &operator=(const ImageInfo &other);
127 
128  // Set and get the Image Type.
129  // <group>
134  // </group>
135 
136 // Set and get the Image object name
137 // <group>
138  String objectName () const;
139  ImageInfo& setObjectName (const String& object);
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>
158  static ImageTypes defaultImageType();
159  static String defaultObjectName();
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.
184  static ImageInfo::ImageTypes imageTypeFromFITS(Int fitsValue);
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.
207  void setRestoringBeam(const GaussianBeam& beam);
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.
215  void removeRestoringBeam();
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
250  uInt nChannels() const
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
258  void setAllBeams(
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.
313  void concatFreqBeams (ImageBeamSet& beamsOut,
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.
321  void concatPolBeams (ImageBeamSet& beamsOut,
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
341  Double getBeamAreaInPixels(Int channel, Int stokes,
342  const DirectionCoordinate&) const;
343 
345  const GaussianBeam& beam, const DirectionCoordinate& dc
346  );
347 
348 private:
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.
371 ostream &operator<<(ostream &os, const ImageInfo &info);
372 // </group>
373 
374 
375 
376 } //# NAMESPACE CASACORE - END
377 
378 #endif
A Vector of integers, for indexing into Array&lt;T&gt; objects.
Definition: IPosition.h:119
uInt nStokes() const
Definition: ImageInfo.h:252
A 1-D Specialization of the Array class.
int Int
Definition: aipstype.h:50
Bool fromFITS(Vector< String > &error, const RecordInterface &inRecord)
uInt nstokes() const
Get the number of stokes in the beam array.
Definition: ImageBeamSet.h:162
void setBeams(const ImageBeamSet &beams)
Set the per plane beams array directly.
Bool hasMultipleBeams() const
does this object contain multiple beams?
Definition: ImageInfo.h:237
void concatFreqBeams(ImageBeamSet &beamsOut, const ImageInfo &infoThat, Int nchanThis, Int nchanThat, Bool relax, LogIO &os) const
Concatenate the beam sets along the frequency axis.
Bool toFITS(String &error, RecordInterface &outRecord) const
Functions to interconvert between an ImageInfo and FITS keywords (converted to a Record).
ImageInfo & setObjectName(const String &object)
Interface class for converting to/from records.
void setRestoringBeam(const GaussianBeam &beam)
Set the single global restoring beam.
static String defaultObjectName()
virtual casacore::String type() const
Implements RegionShape::type.
Definition: RegionShapes.h:548
ostream-like interface to creating log messages.
Definition: LogIO.h:167
ostream & operator<<(ostream &os, const std::pair< T, U > &p)
Record beamToRecord(Int channel, Int stokes) const
Convert the given beam to a Record.
Bool getRestoringBeam(LoggerHolder &logger)
This method is not meant for common use.
Represents a Gaussian restoring beam associated with an image.
Definition: GaussianBeam.h:68
Bool empty() const
Is the beam set empty?
Definition: ImageBeamSet.h:147
const ImageBeamSet & getBeamSet() const
Get the beam set associated with this object.
void checkBeamSet(const CoordinateSystem &coords, const IPosition &shape, const String &imageName) const
Check if the beam set matches the coordinate axes sizes.
void setBeam(Int channel, Int stokes, const Quantity &major, const Quantity &minor, const Quantity &pa)
Set the beam for a specific plane.
Bool hasSingleBeam() const
Definition: ImageBeamSet.h:139
Bool hasBeam() const
Does this object contain one or more beams?
Definition: ImageInfo.h:245
void removeRestoringBeam()
Remove all beams (global or per plane) associated with this object.
LatticeExprNode pa(const LatticeExprNode &left, const LatticeExprNode &right)
This function finds 180/pi*atan2(left,right)/2.
String objectName() const
Set and get the Image object name.
Interconvert pixel positions and directions (e.g. RA/DEC).
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 ...
void setAllBeams(const uInt nChannels, const uInt nStokes, const GaussianBeam &beam)
Initialize all per-plane beams to the same value.
Represents a set of restoring beams associated with an image.
Definition: ImageBeamSet.h:88
double Double
Definition: aipstype.h:55
ImageInfo & setImageType(ImageTypes type)
~ImageInfo()
Destructor.
A hierarchical collection of named fields of various types.
Definition: Record.h:180
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
void setRestoringBeam(const Quantum< Double > &major, const Quantum< Double > &minor, const Quantum< Double > &pa)
Definition: ImageInfo.h:209
static ImageInfo::ImageTypes imageTypeFromFITS(Int fitsValue)
This function takes an unofficial fitsValue found on the Stokes axis and returns the appropriate Imag...
TableExprNode shape(const TableExprNode &array)
Function operating on any scalar or array resulting in a Double array containing the shape...
Definition: ExprNode.h:1944
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.
void concatPolBeams(ImageBeamSet &beamsOut, const ImageInfo &infoThat, Int npolThis, Int npolThat, Bool relax, LogIO &os) const
Concatenate the beam sets along the stokes axis.
static ImageTypes defaultImageType()
In some circumstances it might be useful to know what the defaults for the various values are so you ...
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.
static GaussianBeam defaultRestoringBeam()
ImageTypes
This enum defines the actual quantity being held in an image It&#39;s really only used for descriptive in...
Definition: ImageInfo.h:98
ImageInfo()
Default constructor.
void _checkBeamShape(uInt &nchan, uInt &npol, const IPosition &shape, const CoordinateSystem &csys) const
Check if the beam shape matches the coordinates.
Bool hasMultiBeam() const
Does this beam set contain multiple beams?
Definition: ImageBeamSet.h:143
virtual Bool toRecord(String &error, RecordInterface &outRecord) const
Functions to interconvert between an ImageInfo and a record.
void mergeBeams(ImageBeamSet &beamsOut, const ImageInfo &infoThat, Bool relax, LogIO &os) const
Merge the beam sets and check if they match.
ImageTypes itsImageType
Definition: ImageInfo.h:364
String: the storage and methods of handling collections of characters.
Definition: String.h:223
static ImageInfo::ImageTypes MiriadImageType(const String &type)
Convert the Miriad &#39;btype&#39; strings to the ImageType.
void copy_other(const ImageInfo &other)
Common copy ctor/assignment operator code.
ImageInfo::ImageTypes imageType() const
Set and get the Image Type.
Double getBeamAreaInPixels(Int channel, Int stokes, const DirectionCoordinate &) const
Get the beam area in terms of pixel size of the specified DirectionCoordinate.
GaussianBeam restoringBeam(Int channel=-1, Int stokes=-1) const
Set and get the beam.
void _setRestoringBeam(const Record &inRecord)
Set the restoring beam from the record.
Abstract base class for Record classes.
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...
Class holding a hierarchy of loggers.
Definition: LoggerHolder.h:120
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...
ImageInfo & operator=(const ImageInfo &other)
Assignment (copy semantics)
Miscellaneous information related to an image.
Definition: ImageInfo.h:92
uInt nChannels() const
Number of channels and stokes in per hyper-plane beam array.
Definition: ImageInfo.h:250
virtual Bool fromRecord(String &error, const RecordInterface &inRecord)
Initialise the class from a Record representation.
Interconvert pixel and world coordinates.
unsigned int uInt
Definition: aipstype.h:51
Bool hasSingleBeam() const
does this object contain a single beam
Definition: ImageInfo.h:241
uInt nchan() const
Get the number of channels in the beam array.
Definition: ImageBeamSet.h:157
ImageBeamSet _beams
Definition: ImageInfo.h:362
#define casacore
&lt;X11/Intrinsic.h&gt; #defines true, false, casacore::Bool, and String.
Definition: X11Intrinsic.h:42