casa  5.7.0-16
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
WCBox.h
Go to the documentation of this file.
1 //# WCBox.h: Class to define a box shaped WC 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 //# $Id$
26 
27 
28 
29 #ifndef IMAGES_WCBOX_H
30 #define IMAGES_WCBOX_H
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
39 
40 namespace casacore { //# NAMESPACE CASACORE - BEGIN
41 
42 //# Forward Declarations
43 class LCRegion;
44 class TableRecord;
45 class IPosition;
46 
47 
48 // <summary>
49 // Class to define a world coordinate box region of interest in an image.
50 // </summary>
51 //
52 // <use visibility=export>
53 //
54 // <reviewed reviewer="" date="" tests="">
55 // </reviewed>
56 //
57 // <prerequisite>
58 // <li> <linkto class=WCRegion>WCRegion</linkto>
59 // <li> <linkto class=LCRegion>LCRegion</linkto>
60 // <li> <linkto class=CoordinateSystem>CoordinateSystem</linkto>
61 // </prerequisite>
62 //
63 // <synopsis>
64 // The corners of the box are specified in world coordinates, but the
65 // region enclosed by those corners is a box in lattice coordinates.
66 // Thus, the volume enclosed does not follow world coordinate contours.
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>WCBox</src> constructed with one <src>CoordinateSystem</src>
72 // to another <src>CoordinateSystem</src>. That is, you can apply a
73 // <src>WCBox</src> from this image to that image.
74 //
75 // The flexibility of the <src>CoordinateSystem</src> class should
76 // be kept in mind when using this class. Recall that a
77 // <src>CoordinateSystem</src> has world and pixel axes, and
78 // that these axes can be independently removed and independently
79 // (re)ordered.
80 //
81 // During construction, the length of the world coordinate vectors may be
82 // smaller than the number world axes in the supplied <src>CoordinateSystem</src>.
83 // It is assumed that the units of the world coordinates are the same as those
84 // encapsulated in the construction <src>CoordinateSystem</src> and in the same
85 // order as specified (either intrinsically, or by the world axes
86 // specification vectors).
87 //
88 // The following rules are followed during conversion to an <src>LCRegion</src>.
89 // <ol>
90 // <li> The number of elements in the supplied <src>latticeShape</src> must be equal
91 // to the number of pixel axes in the supplied <src>CoordinateSystem</src>.
92 // <li> The order of the pixel axes in the supplied <src>CoordinateSystem</src>
93 // is assumed to be the order of the axes in the lattice for which the
94 // supplied <src>latticeShape</src> is appropriate.
95 // <li> The <src>CoordinateSystem</src> supplied to the <src>toLCRegion</src>
96 // function does not have to be identical in structure to that from
97 // which the <src>WCBox</src> was constructed. They can consist
98 // of different numbers of world and pixel axes and be in different
99 // orders.
100 // <li> For every world axis in the supplied <src>CoordinateSystem</src>
101 // that is also present (somewhere) in the construction <src>CoordinateSystem</src>
102 // the blc/trc corresponding to that world axis will be
103 // converted to pixels appropriate to the supplied <src>CoordinateSystem</src>.
104 // The order of this pixel based blc/trc will be the order of the pixel axes of
105 // the supplied <src>CoordinateSystem</src>
106 // <li> For every world axis in the supplied <src>CoordinateSystem</src>
107 // that is not present in the construction <src>CoordinateSystem</src>,
108 // the supplied <src>latticeShape</src> value for the corresponding
109 // pixel axis is used, setting <src>blc=0</src> and <src>trc=latticeShape-1</src>
110 // for that axis.
111 // <li> Once the pixel based blc/trc has been created, then, with
112 // the supplied <src>latticeShape</src>, it is used to create the
113 // <src>LCBox</src>, which is supplied as a pointer to the base
114 // class <src>LCRegion</src>.
115 // </ol>
116 //
117 // Note that when determining whether a world axis from one
118 // <src>CoordinateSystem</src>is present on another, it is
119 // considered to not be a match if two coordinates of the
120 // same type (e.g. <src>DirectionCoordinate</src>) have different
121 // specific types (e.g. J2000 and GALACTIC, or TOPO and LSR for
122 // a <src>SpectralCoordinate</src>)
123 // </synopsis>
124 //
125 // <example>
126 // Let us give some examples with pseudo-code.
127 // cSys is the construction CoordinateSystem
128 // and cSys2 is the supplied CoordinateSystem.
129 // We list their world axes in the square brackets.
130 // The construction blc/trc values don't matter
131 // as long as there cSys.nWorldAxes() of them.
132 // Similarly, the values of shape don't matter
133 // as long as there are cSys2.nPixelAxes() of them.
134 // <srcblock>
135 // cSys = [ra, dec, freq];
136 // cSys2 = [ra, dec];
137 // blc = [,,];
138 // trc = [,,];
139 // shape = [,];
140 // WCBox box(blc, trc, cSys);
141 // LCRegion* pR = box.toLCRegion(cSys2, shape);
142 // </srcblock>
143 // The resultant LCBox will have corners converted
144 // according to
145 // <srcblock>
146 // blcLC(0) <- blc(0);
147 // blcLC(1) <- blc(1);
148 // trcLC(0) <- trc(0);
149 // trcLC(1) <- trc(1);
150 // </srcblock>
151 //
152 // </example>
153 //
154 // <example>
155 // <srcblock>
156 // cSys = [ra, dec, freq];
157 // cSys2 = [freq, stokes];
158 // blc = [,,];
159 // trc = [,,];
160 // shape = [,];
161 // WCBox box(blc, trc, cSys);
162 // LCRegion* pR = box.toLCRegion(cSys2, shape);
163 // </srcblock>
164 //
165 // The resultant LCBox will have corners converted
166 // according to
167 //
168 // <srcblock>
169 // blcLC(0) <- blc(2);
170 // blcLC(1) = 0;
171 // trcLC(0) <- trc(2);
172 // trcLC(1) = shape(1) - 1;
173 // </srcblock>
174 //
175 // </example>
176 //
177 // <example>
178 // <srcblock>
179 // cSys = [ra, dec];
180 // cSys2 = [ra, dec, freq];
181 // blc = [,];
182 // trc = [,];
183 // shape = [,,];
184 // WCBox box(blc, trc, cSys);
185 // LCRegion* pR = box.toLCRegion(cSys2, shape);
186 // </srcblock>
187 //
188 // The resultant LCBox will have corners converted
189 // according to
190 //
191 // <srcblock>
192 // blcLC(0) <- blc(0);
193 // blcLC(1) <- blc(1);
194 // blcLC(2) = 0l
195 // trcLC(0) <- trc(0);
196 // trcLC(1) <- trc(1);
197 // trcLC(2) = shape(2)-1;
198 // </srcblock>
199 //
200 // </example>
201 //
202 // <example>
203 // <srcblock>
204 // cSys = [ra, dec, freq];
205 // cSys2 = [freq, ra, dec];
206 // blc = [,,];
207 // trc = [,,];
208 // shape = [,,];
209 // WCBox box(blc, trc, cSys);
210 // LCRegion* pR = box.toLCRegion(cSys2, shape);
211 // </srcblock>
212 //
213 // The resultant LCBox will have corners converted
214 // according to
215 //
216 // <srcblock>
217 // blcLC(0) <- blc(2);
218 // blcLC(1) <- blc(0);
219 // blcLC(2) <- blc(1);
220 // trcLC(0) <- trc(2);
221 // trcLC(1) <- trc(0);
222 // trcLC(2) <- trc(1);
223 // </srcblock>
224 //
225 // </example>
226 //
227 // <example>
228 // In this example we make it a bit harder by
229 // reordering the pixel axes too. The new order
230 // of the pixel axes in terms of the original
231 // order [0,1,2] is given after the world axes
232 //
233 // <srcblock>
234 // cSys = [ra, dec, freq], [0, 1, 2];
235 // cSys2 = [freq, ra, dec, stokes], [3, 0, 2, 1];
236 // blc = [,,];
237 // trc = [,,];
238 // shape = [,,,];
239 // WCBox box(blc, trc, cSys);
240 // LCRegion* pR = box.toLCRegion(cSys2, shape);
241 // </srcblock>
242 //
243 // Take the first world axis of cSys2 as an example.
244 // First, "freq" is found as the world axis number
245 // 2 in cSys. Then, when it is converted to
246 // a pixel coordinate, it will turn up as
247 // the value on pixel axis 1. The supplied shape
248 // must be appropriate to a [stokes, freq, dec, ra] lattice.
249 // The resultant LCBox will therefore have corners
250 // converted according to
251 //
252 // <srcblock>
253 // blcLC(0) = 0
254 // blcLC(1) <- blc(2);
255 // blcLC(2) <- blc(1);
256 // blcLC(3) <- blc(0);
257 //
258 // trcLC(0) = shape(0)-1;
259 // trcLC(1) <- trc(2);
260 // trcLC(2) <- trc(1);
261 // trcLC(3) <- trc(0);
262 // </srcblock>
263 // </example>
264 //
265 // <motivation>
266 // Users must be able to specify regions in world as well as lattice
267 // coordinates.
268 // </motivation>
269 //
270 // <note>
271 // In all of the constructors, the order of the specified world
272 // coordinates is that of the *PIXEL AXES* (not world axes) in the
273 // <src>CoordinateSystem</src>. This is the natural order for a user to want
274 // to specify them in.
275 // </note>
276 //
277 // <note>
278 // For the constructors specifying the world values as simple doubles,
279 // it is *ASSUMED* that the units of those doubles are the same as
280 // the native units of the <src>CoordinateSystem</src> for each axis.
281 // </note>
282 //
283 // <note>
284 // World coordinates may be specified as absolute or offset. If the
285 // latter, they are offset with respect to the reference pixel of
286 // the <src>CoordinateSystem</src>.
287 // </note>
288 // <todo asof="1998/05/20">
289 // <li> Implement offset coordinates
290 // </todo>
291 
292 class WCBox : public WCRegion
293 {
294 public:
295  WCBox();
296 
297  // Construct from vectors of world coordinates
298  // defining the box corners. It is assumed that the
299  // order of the values is in the order of the pixel axes
300  // in the given coordinate system.
301  // <group>
302  WCBox(const Vector<Quantum<Double> >& blc,
303  const Vector<Quantum<Double> >& trc,
304  const CoordinateSystem& cSys,
305  const Vector<Int>& absRel);
306  // </group>
307 
308  // Construct from vectors of world coordinates
309  // defining the box corners. You specify the pixel
310  // axis order of the world values.
311  // <group>
312  WCBox(const Vector<Quantum<Double> >& blc,
313  const Vector<Quantum<Double> >& trc,
314  const IPosition& pixelAxes,
315  const CoordinateSystem& cSys,
316  const Vector<Int>& absRel);
317  // </group>
318 
319  // Construct from the bounding box of an <src>LCRegion</src>.
320  WCBox(const LCRegion& region,
321  const CoordinateSystem& cSys);
322 
323  // Copy constructor (reference semantics [except for <src>CoordinateSystem</src>])
324  WCBox (const WCBox& other);
325 
326  // Destructor
327  virtual ~WCBox();
328 
329  // Assignment (copy semantics)
330  WCBox& operator= (const WCBox& other);
331 
332  // Comparison
333  virtual Bool operator==(const WCRegion& other) const;
334 
335  // Clone a WCBox object.
336  virtual WCRegion* cloneRegion() const;
337 
338  // WCBox can extend a region.
339  virtual Bool canExtend() const;
340 
341  // Make a new box from the given axesin this box.
342  WCBox splitBox (const IPosition& axes) const;
343 
344  // Convert to an LCRegion using the supplied <src>CoordinateSystem</src>
345  // and shape.
346  virtual LCRegion* doToLCRegion (const CoordinateSystem& cSys,
347  const IPosition& latticeShape,
348  const IPosition& pixelAxesMap,
349  const IPosition& outOrder) const;
350 
351  // Convert the WCBox object to a record.
352  // The record can be used to make the object persistent.
353  // The <src>tableName</src> argument can be used by derived
354  // classes (e.g. LCPagedMask) to put very large objects.
355  virtual TableRecord toRecord(const String& tableName) const;
356 
357  // Convert to a WCBox from a record.
358  static WCBox* fromRecord (const TableRecord& rec,
359  const String& tableName);
360 
361  // Returns WCBox
362  static String className();
363 
364  // Return region type. Returns the class name
365  virtual String type() const;
366 
367 private:
374 
375 
376 // Check units of quanta are consistent with CoordinateSystem
377  void checkUnits (const IPosition& pixelAxes,
378  const Vector<Quantum<Double> >& values,
379  const CoordinateSystem& cSys);
380 
381 // Convert relative pixels to absolute or fill in defaults
382  void convertPixel(Double& pixel,
383  const Quantum<Double>& value,
384  const Int absRel,
385  const Double refPix,
386  const Int shape,
387  const Bool isBlc) const;
388 
389 };
390 
391 
392 
393 } //# NAMESPACE CASACORE - END
394 
395 #endif
A Vector of integers, for indexing into Array&lt;T&gt; objects.
Definition: IPosition.h:119
A 1-D Specialization of the Array class.
int Int
Definition: aipstype.h:50
virtual LCRegion * doToLCRegion(const CoordinateSystem &cSys, const IPosition &latticeShape, const IPosition &pixelAxesMap, const IPosition &outOrder) const
Convert to an LCRegion using the supplied CoordinateSystem and shape.
virtual Bool operator==(const WCRegion &other) const
Comparison.
static WCBox * fromRecord(const TableRecord &rec, const String &tableName)
Convert to a WCBox from a record.
virtual WCRegion * cloneRegion() const
Clone a WCBox object.
WCBox & operator=(const WCBox &other)
Assignment (copy semantics)
virtual String type() const
Return region type.
virtual TableRecord toRecord(const String &tableName) const
Convert the WCBox object to a record.
Bool itsNull
Definition: WCBox.h:373
Vector< Int > itsAbsRel
Definition: WCBox.h:372
Vector< Quantum< Double > > itsBlc
Definition: WCBox.h:368
IPosition itsPixelAxes
Definition: WCBox.h:370
double Double
Definition: aipstype.h:55
WCBox splitBox(const IPosition &axes) const
Make a new box from the given axesin this box.
void convertPixel(Double &pixel, const Quantum< Double > &value, const Int absRel, const Double refPix, const Int shape, const Bool isBlc) const
Convert relative pixels to absolute or fill in defaults.
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
virtual ~WCBox()
Destructor.
TableExprNode shape(const TableExprNode &array)
Function operating on any scalar or array resulting in a Double array containing the shape...
Definition: ExprNode.h:1944
A hierarchical collection of named fields of various types.
Definition: TableRecord.h:182
Vector< Quantum< Double > > itsTrc
Definition: WCBox.h:369
CoordinateSystem itsCSys
Definition: WCBox.h:371
Base class to define world coordinate regions of interest in an image.
Definition: WCRegion.h:95
String: the storage and methods of handling collections of characters.
Definition: String.h:223
Class to define a world coordinate box region of interest in an image.
Definition: WCBox.h:292
static String className()
Returns WCBox.
Interconvert pixel and world coordinates.
virtual Bool canExtend() const
WCBox can extend a region.
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.
void checkUnits(const IPosition &pixelAxes, const Vector< Quantum< Double > > &values, const CoordinateSystem &cSys)
Check units of quanta are consistent with CoordinateSystem.
Abstract base class to define a region of interest in lattice coordinates.
Definition: LCRegion.h:87
#define casacore
&lt;X11/Intrinsic.h&gt; #defines true, false, casacore::Bool, and String.
Definition: X11Intrinsic.h:42