casacore
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>
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 TableRecord;
45class 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
292class WCBox : public WCRegion
293{
294public:
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>
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>
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.
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
363
364 // Return region type. Returns the class name
365 virtual String type() const;
366
367private:
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
String: the storage and methods of handling collections of characters.
Definition: String.h:225
virtual Bool canExtend() const
WCBox can extend a region.
WCBox splitBox(const IPosition &axes) const
Make a new box from the given axesin this box.
IPosition itsPixelAxes
Definition: WCBox.h:370
virtual Bool operator==(const WCRegion &other) const
Comparison.
CoordinateSystem itsCSys
Definition: WCBox.h:371
virtual TableRecord toRecord(const String &tableName) const
Convert the WCBox object to a record.
Vector< Quantum< Double > > itsBlc
Definition: WCBox.h:368
static WCBox * fromRecord(const TableRecord &rec, const String &tableName)
Convert to a WCBox from a record.
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.
void checkUnits(const IPosition &pixelAxes, const Vector< Quantum< Double > > &values, const CoordinateSystem &cSys)
Check units of quanta are consistent with CoordinateSystem.
WCBox(const LCRegion &region, const CoordinateSystem &cSys)
Construct from the bounding box of an LCRegion.
WCBox(const Vector< Quantum< Double > > &blc, const Vector< Quantum< Double > > &trc, const CoordinateSystem &cSys, const Vector< Int > &absRel)
Construct from vectors of world coordinates defining the box corners.
virtual WCRegion * cloneRegion() const
Clone a WCBox object.
virtual ~WCBox()
Destructor.
WCBox(const WCBox &other)
Copy constructor (reference semantics [except for CoordinateSystem])
Bool itsNull
Definition: WCBox.h:373
WCBox(const Vector< Quantum< Double > > &blc, const Vector< Quantum< Double > > &trc, const IPosition &pixelAxes, const CoordinateSystem &cSys, const Vector< Int > &absRel)
Construct from vectors of world coordinates defining the box corners.
Vector< Int > itsAbsRel
Definition: WCBox.h:372
virtual String type() const
Return region type.
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.
Vector< Quantum< Double > > itsTrc
Definition: WCBox.h:369
static String className()
Returns WCBox.
WCBox & operator=(const WCBox &other)
Assignment (copy semantics)
this file contains all the compiler specific defines
Definition: mainpage.dox:28
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