casacore
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 
40 namespace casacore { //# NAMESPACE CASACORE - BEGIN
41 
42 //# Forward Declarations
43 class LCRegion;
44 class LCPolygon;
45 class TableRecord;
46 class 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 
205 class WCPolygon : public WCRegion
206 {
207 public:
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.
244  virtual LCRegion* doToLCRegion (const CoordinateSystem& cSys,
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"
260  static String className();
261 
262  // Return region type. Returns the class name
263  virtual String type() const;
264 
265 
266 protected:
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.
static WCPolygon * fromRecord(const TableRecord &rec, const String &tableName)
Convert to a WCPolygon from a record.
WCPolygon(const WCPolygon &other)
Copy constructor (reference 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.
WCPolygon & operator=(const WCPolygon &other)
Assignment (copy semantics)
RegionType::AbsRelType itsAbsRel
Definition: WCPolygon.h:271
virtual WCRegion * cloneRegion() const
Clone a WCPolygon object.
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
Quantum< Vector< Double > > itsY
Definition: WCPolygon.h:268
CoordinateSystem itsCSys
Definition: WCPolygon.h:270
virtual ~WCPolygon()
Destructor.
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.
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