casacore
WCRegion.h
Go to the documentation of this file.
1//# WCRegion.h: Class to define a region of interest in an image
2//# Copyright (C) 1998,2000,2001
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_WCREGION_H
29#define IMAGES_WCREGION_H
30
31//# Includes
32#include <casacore/casa/aips.h>
33#include <casacore/casa/Containers/Record.h>
34#include <casacore/coordinates/Coordinates/CoordinateSystem.h>
35#include <casacore/tables/Tables/TableRecord.h>
36
37namespace casacore { //# NAMESPACE CASACORE - BEGIN
38
39//# Forward Declarations
40class LCRegion;
41class RecordInterface;
42class IPosition;
43class String;
44
45
46// <summary>
47// Base class to define world coordinate regions of interest in an image.
48// </summary>
49
50// <use visibility=export>
51
52// <reviewed reviewer="" date="" tests="">
53// </reviewed>
54//
55// <prerequisite>
56// <li> <linkto class=LCRegion>LCRegion</linkto>
57// </prerequisite>
58//
59// <synopsis>
60// WCRegion is the base class for world coordinate regions.
61// The axes in a WCRegion have names (e.g. RA, DEC, FREQ) and
62// carry sometimes an associated reference frame with it.
63// An WCRegion object is converted to the appropriate
64// <linkto class=LCRegion>LCRegion</linkto> object when they
65// are used to take a subset from an image.
66// LCRegion's are pixel based and are
67// used to access the correct pixels in the image.
68// The conversion has the following rules:
69// <ol>
70// <li> All axes of the region must be axes in the image.
71// <li> An image axis does not have to be an axis in the region.
72// Thus the image can have a higher dimensionality than the region.
73// If that is the case, the region is auto-extended to the image's
74// dimensionality by using the full range for those axes.
75// <li> The order of the axes in region and image do not have to
76// be the same. They get reordered as needed.
77// </ol>
78// </synopsis>
79//
80// <example>
81// <srcblock>
82// </srcblock>
83// </example>
84//
85// <motivation>
86// User should be able to specify their regions in world coordinates
87// as well as lattice coordinates.
88// </motivation>
89//
90//# <todo asof="1997/11/11">
91//# <li>
92//# </todo>
93
94
96{
97public:
99
100 // Copy constructor (copy semantics).
101 WCRegion (const WCRegion& other);
102
103 // Destructor
104 virtual ~WCRegion();
105
106 // Comparison
107 // <group>
108 virtual Bool operator==(const WCRegion& other) const;
109 Bool operator!=(const WCRegion& other) const;
110 // </group>
111
112 // Clone a WCRegion object.
113 virtual WCRegion* cloneRegion() const = 0;
114
115 // Return region type.
116 // Just returns the class name of the derived class.
117 virtual String type() const = 0;
118
119 // Get the dimensionality (i.e. the number of axes).
120 // Note that usually all axes have a description, but in some cases
121 // (e.g. WCLELMask) that may not be the case.
122 // The default implementation returns the number of axes in the
123 // axes description.
124 virtual uInt ndim() const;
125
126 // Get the description of all axes.
127 const Record& getAxesDesc() const;
128
129 // Get the description of the given axis.
130 // It is a record containing some fields describing the axis.
131 const Record& getAxisDesc (uInt axis) const;
132
133 // Return the axis number of the description of an axis in the full
134 // axes description.
135 // -1 is returned if not found.
136 Int axisNr (const Record& desc, const Record& axesDesc) const;
137
138 // Are both axis descriptions equal?
139 Bool isAxisDescEqual (const Record& desc1, const Record& desc2) const;
140
141 // Can the region extend itself?
142 // By default it cannot.
143 virtual Bool canExtend() const;
144
145 // Get or set the comment.
146 // <group>
147 const String& comment() const;
148 void setComment (const String& comment);
149 // </group>
150
151 // Convert to an LCRegion using the given new coordinate system and shape.
152 // An exception is thrown if the region's dimensionality is more
153 // than the length of the shape vector or if an axis in the region
154 // is unknown in the new coordinate system..
155 // When less, the default implementation extends the region over the
156 // remaining axes.
157 // <br>If the region does not need to have coordinates (like WCLELMask)
158 // the function has to be overridden.
159 virtual LCRegion* toLCRegion (const CoordinateSystem& cSys,
160 const IPosition& shape) const;
161
162 // Convert to an LCRegion using the given coordinate system and shape.
163 // This function is meant for internal use by WCCompound objects.
164 // <br>pixelAxesMap(i) is the axis in cSys and shape for region axis i.
165 // <br>outOrder(i) is the axis in the output LCRegion for region axis i.
166 // <br>The length of pixelAxesMap and outOrder is the dimensionality of
167 // the output LCRegion. It can be more than the dimensionality of this
168 // WCRegion object. In that case the region gets extended along the
169 // latter axes. If the region cannot extend itself, this function
170 // will create an LCExtension object to extend the region.
171 // <br>Note that initially pixelAxisMap and outOrder are the same,
172 // but when called for regions in compound regions they may start
173 // to differ.
175 const IPosition& shape,
176 const IPosition& pixelAxesMap,
177 const IPosition& outOrder) const;
178
179 // Convert the (derived) object to a record.
180 // The record can be used to make the object persistent.
181 // The <src>tableName</src> argument can be used by derived
182 // classes (e.g. LCPagedMask) to put very large objects.
183 virtual TableRecord toRecord(const String& tableName) const = 0;
184
185 // Convert correct object from a record.
186 static WCRegion* fromRecord (const TableRecord& rec,
187 const String& tableName);
188
189 // Define the type and class name in the record.
191 const String& className) const;
192
193protected:
194 // Assignment (copy semantics) makes only sense for a derived class.
196
197 // Add an axis with its description.
198 // An exception is thrown if the axis already exists in this region.
199 void addAxisDesc (const Record& axisDesc);
200
201 // Make a description of a pixel axis in the coordinate system.
202 Record makeAxisDesc (const CoordinateSystem& cSys, uInt pixelAxis) const;
203
204 // Make a description of all pixel axes in the coordinate system
205 // (in pixel axes order).
207
208 // Convert to an LCRegion using the given coordinate system and shape.
209 // <br>pixelAxesMap(i) is the axis in cSys and shape for region axis i.
210 // <br>outOrder(i) is the axis in the output LCRegion for region axis i.
211 // <br>They always have the same length.
212 // If the region can extend itself, the length of pixelAxesMap and
213 // outOrder can be more than the dimensionality of the region.
214 // The latter axes in them are the extension axes.
216 const IPosition& shape,
217 const IPosition& pixelAxesMap,
218 const IPosition& extendAxes) const = 0;
219
220// Convert relative to absolute world as needed
222 const Vector<Int>& absRel,
223 const CoordinateSystem& cSys,
224 const IPosition& shape) const;
225
226 static void unitInit();
227
229 const IPosition& pixelAxes,
230 const CoordinateSystem& cSys,
231 const Vector<String>& quantityUnits
232 ) const;
233
234 static void convertPixel(
235 Double& pixel,
236 const Double& value,
237 const String& unit,
238 const Int absRel,
239 const Double refPix,
240 const Int shape
241 );
242private:
245};
246
247
248inline Bool WCRegion::operator!= (const WCRegion& other) const
249{
250 return (!operator==(other));
251}
252inline const String& WCRegion::comment() const
253{
254 return itsComment;
255}
256inline void WCRegion::setComment (const String& comment)
257{
259}
260inline const Record& WCRegion::getAxesDesc() const
261{
262 return itsAxesDesc;
263}
264
265
266
267} //# NAMESPACE CASACORE - END
268
269#endif
String: the storage and methods of handling collections of characters.
Definition: String.h:225
Bool isAxisDescEqual(const Record &desc1, const Record &desc2) const
Are both axis descriptions equal?
const String & comment() const
Get or set the comment.
Definition: WCRegion.h:252
virtual TableRecord toRecord(const String &tableName) const =0
Convert the (derived) object to a record.
WCRegion(const WCRegion &other)
Copy constructor (copy semantics).
Int axisNr(const Record &desc, const Record &axesDesc) const
Return the axis number of the description of an axis in the full axes description.
static void unitInit()
static void convertPixel(Double &pixel, const Double &value, const String &unit, const Int absRel, const Double refPix, const Int shape)
void setComment(const String &comment)
Definition: WCRegion.h:256
Record makeAxesDesc(const CoordinateSystem &cSys) const
Make a description of all pixel axes in the coordinate system (in pixel axes order).
virtual Bool operator==(const WCRegion &other) const
Comparison.
virtual String type() const =0
Return region type.
const Record & getAxesDesc() const
Get the description of all axes.
Definition: WCRegion.h:260
void defineRecordFields(RecordInterface &record, const String &className) const
Define the type and class name in the record.
virtual ~WCRegion()
Destructor.
void addAxisDesc(const Record &axisDesc)
Add an axis with its description.
Record makeAxisDesc(const CoordinateSystem &cSys, uInt pixelAxis) const
Make a description of a pixel axis in the coordinate system.
virtual WCRegion * cloneRegion() const =0
Clone a WCRegion object.
virtual LCRegion * doToLCRegion(const CoordinateSystem &cSys, const IPosition &shape, const IPosition &pixelAxesMap, const IPosition &extendAxes) const =0
Convert to an LCRegion using the given coordinate system and shape.
Bool operator!=(const WCRegion &other) const
Definition: WCRegion.h:248
const Record & getAxisDesc(uInt axis) const
Get the description of the given axis.
LCRegion * toLCRegionAxes(const CoordinateSystem &cSys, const IPosition &shape, const IPosition &pixelAxesMap, const IPosition &outOrder) const
Convert to an LCRegion using the given coordinate system and shape.
static WCRegion * fromRecord(const TableRecord &rec, const String &tableName)
Convert correct object from a record.
virtual Bool canExtend() const
Can the region extend itself? By default it cannot.
WCRegion & operator=(const WCRegion &other)
Assignment (copy semantics) makes only sense for a derived class.
virtual LCRegion * toLCRegion(const CoordinateSystem &cSys, const IPosition &shape) const
Convert to an LCRegion using the given new coordinate system and shape.
void makeWorldAbsolute(Vector< Double > &world, const Vector< Int > &absRel, const CoordinateSystem &cSys, const IPosition &shape) const
Convert relative to absolute world as needed.
Record itsAxesDesc
Definition: WCRegion.h:244
virtual uInt ndim() const
Get the dimensionality (i.e.
void checkAxes(const IPosition &pixelAxes, const CoordinateSystem &cSys, const Vector< String > &quantityUnits) const
this file contains all the compiler specific defines
Definition: mainpage.dox:28
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
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.
double Double
Definition: aipstype.h:55