casacore
Loading...
Searching...
No Matches
WCPolygon.h
Go to the documentation of this file.
1//# WCPolygon.h: Class to define a polygonal world coordinate region
2//# Copyright (C) 1998,1999,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
29#ifndef IMAGES_WCPOLYGON_H
30#define IMAGES_WCPOLYGON_H
31
32//# Includes
33#include <casacore/casa/aips.h>
34#include <casacore/coordinates/Coordinates/CoordinateSystem.h>
35#include <casacore/images/Regions/WCRegion.h>
36#include <casacore/lattices/LRegions/RegionType.h>
37#include <casacore/casa/Arrays/Vector.h>
38#include <casacore/casa/Quanta/Quantum.h>
39
40namespace casacore { //# NAMESPACE CASACORE - BEGIN
41
42//# Forward Declarations
43class LCRegion;
44class LCPolygon;
45class TableRecord;
46class IPosition;
47
48
49// <summary>
50// Class to define a 2-D polygonal world coordinate region in an image.
51// </summary>
52//
53// <use visibility=export>
54//
55// <reviewed reviewer="" date="" tests="">
56// </reviewed>
57//
58// <prerequisite>
59// <li> <linkto class=WCRegion>WCRegion</linkto>
60// <li> <linkto class=LCRegion>LCRegion</linkto>
61// <li> <linkto class=CoordinateSystem>CoordinateSystem</linkto>
62// </prerequisite>
63//
64// <synopsis>
65// The corners of the 2-D polygon are given by world coordinates. The
66// vertices are connected by straight lines in lattice coordinates.
67//
68// All this class does, apart from constructing itself, is know
69// how to save itself to a <src>Record</src> and how to convert itself
70// to an <src>LCRegion</src>. The conversion allows you to apply
71// a <src>WCPolygon</src> constructed with one <src>CoordinateSystem</src>
72// to another <src>CoordinateSystem</src>. That is, you can apply a
73// <src>WCPolygon</src> from this image to that image.
74//
75// At construction, it is assumed that the units of the world
76// coordinates are the same as those encapsulated in the
77// construction <src>CoordinateSystem</src>. You must tell
78// the constructor, which world axes the x and vectors
79// are associated with. Make sure you account for reordering.
80// For example, if you reordered [ra,dec] to be [dec,ra]
81// with the <src>CoordinateSystem::transpose(,)</src> fuction
82// and wished the x vector to be ra, and the y vector to
83// be dec, then <src>worldAxes=[1,0]</src>.
84//
85// The <src>CoordinateSystem</src> supplied to the <src>toLCRegion</src>
86// (which returns a pointer to an <src>LCPolygongon</src> object)
87// function does not have to be identical in structure to that with
88// which the <src>WCPolygon</src> was constructed. However, each world
89// axis given in the <src>worldAxes</src> vector at construction must be present
90// somewhere (order is unimportant) in the supplied <src>CoordinateSystem</src>.
91//
92//
93// The supplied lattice shape must be 2-D and corresponds to the
94// pixel axes of the two world axes of the supplied
95// <src>CoordinateSystem</src> which match those of the construction
96// <src>CoordinateSystem</src>.
97//
98// </synopsis>
99//
100// <example>
101// Let us give some examples with pseudo-code.
102// cSys is the construction CoordinateSystem
103// and cSys2 is the supplied CoordinateSystem.
104// We list their world axes in the square brackets.
105// The construction polygon values don't matter.
106// Similarly, the values of shape don't matter
107// as long as there are 2 of them.
108// <srcblock>
109// cSys = [ra, dec, freq];
110// cSys2 = [ra, dec];
111// axes=[0,1];
112// shape = [,];
113// WCPolygon poly(x, y, axes, cSys);
114// LCRegion* pR = poly.toLCRegion(cSys2, shape);
115// </srcblock>
116// The resultant LCPolygon will have vertices converted
117// with the [ra, dec] axes from cSys2
118// </example>
119//
120//
121// <example>
122// <srcblock>
123// cSys = [ra, dec, freq];
124// cSys2 = [ra, dec];
125// axes=[0,2];
126// shape = [,];
127// WCPolygon poly(x, y, axes, cSys);
128// LCRegion* pR = poly.toLCRegion(cSys2, shape);
129// </srcblock>
130// This will throw an exception because the [freq] axis
131// is missing in cSys2
132// </example>
133//
134// <example>
135// In this example we make it a bit harder by
136// reordering the pixel axes too. The new order
137// of the pixel axes in terms of the original
138// order [0,1,2...] is given after the world axes
139//
140// <srcblock>
141// cSys = [ra, dec, freq];
142// cSys2 = [stokes, freq, ra, dec], [3,2,1,0];
143// axes=[1,2];
144// shape = [,];
145// WCPolygon poly(x, y, axes, cSys);
146// LCRegion* pR = poly.toLCRegion(cSys2, shape);
147// </srcblock>
148// The resultant LCPolygon will have vertices converted
149// with the [ra, dec] axes from cSys2. The fact that
150// the pixel axes of cSys2 were reordered is accounted
151// for internally, but does not extrude further.
152// </example>
153//
154// <example>
155// In this example we make it a bit harder by
156// remove a pixel axis.
157//
158// <srcblock>
159// cSys = [ra, dec, freq];
160// cSys2 = [stokes, freq, ra, dec];
161// cSys2.removePixelAxis(1, cSys2.referencePixel()(1));
162// axes=[1,2];
163// shape = [,];
164// WCPolygon poly(x, y, axes, cSys);
165// LCRegion* pR = poly.toLCRegion(cSys2, shape);
166// </srcblock>
167// This will throw an exception because the removed
168// pixel axis, pixel axis number 1,
169// corresponds to the [freq] world axis
170// in cSys2, and the [freq] axis is one of those
171// specified at construction. Although the world
172// axis is still present, it is not possible to
173// convert to a pixel coordinate if the pixel axis
174// is not there.
175// </example>
176//
177// <motivation>
178// Users must be able to specify regions in world as well as lattice
179// coordinates.
180// </motivation>
181//
182// <note>
183// In all the constructors, you have to specifiy which plane
184// the polygon lies in. You do this by specifying the *PIXEL AXES*
185// (not the world axes) as this is the natural thing the user
186// will want to specify.
187// </note>
188//
189// <note>
190// For the constructors specifying the world values as simple doubles,
191// it is *ASSUMED* that the units of those doubles are the same as
192// the native units of the <src>CoordinateSystem</src> for each axis.
193// </note>
194//
195// <note>
196// World coordinates may be specified as absolute or offset. If the
197// latter, they are offset with respect to the reference pixel of
198// the <src>CoordinateSystem</src>.
199// </note>
200//
201// <todo asof="1998/05/20">
202// <li>
203// </todo>
204
205class WCPolygon : public WCRegion
206{
207public:
209
210 // Construct from two vectors of world coordinates
211 // defining the polygon vertices.
212 // <group>
214 const Quantum<Vector<Double> >& y,
215 const IPosition& pixelAxes,
216 const CoordinateSystem& cSys,
218 // </group>
219
220 // Construct from an <src>LCPolygon</src>.
221 WCPolygon(const LCPolygon& polygon,
222 const IPosition& pixelAxes,
223 const CoordinateSystem& cSys);
224
225 // Copy constructor (reference semantics).
226 WCPolygon (const WCPolygon& other);
227
228 // Destructor
229 virtual ~WCPolygon();
230
231 // Assignment (copy semantics)
233
234 // Comparison
235 virtual Bool operator==(const WCRegion& other) const;
236
237 // Clone a WCPolygon object.
238 virtual WCRegion* cloneRegion() const;
239
240 // WCPolygon cannot extend a region.
241 virtual Bool canExtend() const;
242
243 // Convert to an LCRegion using the given coordinate system.
245 const IPosition& latticeShape,
246 const IPosition& pixelAxesMap,
247 const IPosition& outOrder) const;
248
249 // Convert the WCPolygon object to a record.
250 // The record can be used to make the object persistent.
251 // The <src>tableName</src> argument can be used by derived
252 // classes (e.g. LCPagedMask) to put very large objects.
253 virtual TableRecord toRecord(const String& tableName) const;
254
255 // Convert to a WCPolygon from a record.
256 static WCPolygon* fromRecord (const TableRecord& rec,
257 const String& tableName);
258
259 // Returns "WCPolygon"
261
262 // Return region type. Returns the class name
263 virtual String type() const;
264
265
266protected:
273
274};
275
276
277
278} //# NAMESPACE CASACORE - END
279
280#endif
AbsRelType
Define if a region is absolute or relative.
Definition RegionType.h:75
String: the storage and methods of handling collections of characters.
Definition String.h:225
virtual String type() const
Return region type.
virtual Bool operator==(const WCRegion &other) const
Comparison.
WCPolygon(const WCPolygon &other)
Copy constructor (reference semantics).
WCPolygon & operator=(const WCPolygon &other)
Assignment (copy semantics)
virtual TableRecord toRecord(const String &tableName) const
Convert the WCPolygon object to a record.
WCPolygon(const Quantum< Vector< Double > > &x, const Quantum< Vector< Double > > &y, const IPosition &pixelAxes, const CoordinateSystem &cSys, const RegionType::AbsRelType absRel=RegionType::Abs)
Construct from two vectors of world coordinates defining the polygon vertices.
virtual Bool canExtend() const
WCPolygon cannot extend a region.
RegionType::AbsRelType itsAbsRel
Definition WCPolygon.h:271
static String className()
Returns "WCPolygon".
WCPolygon(const LCPolygon &polygon, const IPosition &pixelAxes, const CoordinateSystem &cSys)
Construct from an LCPolygon.
IPosition itsPixelAxes
Definition WCPolygon.h:269
Quantum< Vector< Double > > itsX
Definition WCPolygon.h:267
static WCPolygon * fromRecord(const TableRecord &rec, const String &tableName)
Convert to a WCPolygon from a record.
virtual WCRegion * cloneRegion() const
Clone a WCPolygon object.
Quantum< Vector< Double > > itsY
Definition WCPolygon.h:268
CoordinateSystem itsCSys
Definition WCPolygon.h:270
virtual LCRegion * doToLCRegion(const CoordinateSystem &cSys, const IPosition &latticeShape, const IPosition &pixelAxesMap, const IPosition &outOrder) const
Convert to an LCRegion using the given coordinate system.
virtual ~WCPolygon()
Destructor.
this file contains all the compiler specific defines
Definition mainpage.dox:28
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:42