casacore
AxesSpecifier.h
Go to the documentation of this file.
1 //# AxesSpecifier.h: Specification of axes to keep or remove
2 //# Copyright (C) 2000
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 //#
27 //# $Id$
28 
29 #ifndef CASA_AXESSPECIFIER_2_H
30 #define CASA_AXESSPECIFIER_2_H
31 
32 //# Includes
33 #include "IPosition.h"
34 #include "AxesMapping.h"
35 
36 namespace casacore { //# NAMESPACE CASACORE - BEGIN
37 
38 //# Forward Declarations
39 
40 
41 // <summary>
42 // Specification of axes to keep or remove
43 // </summary>
44 
45 // <use visibility=export>
46 
47 // <reviewed reviewer="" date="yyyy/mm/dd" tests="tAxesSpecifier.cc" demos="">
48 // </reviewed>
49 
50 // <prerequisite>
51 // <li> <linkto class="IPosition">IPosition</linkto>
52 // </prerequisite>
53 
54 // <synopsis>
55 // AxesSpecifier makes it possible to specify which axes should
56 // be used in a shape. Degenerate axes (i.e. axes with length 0)
57 // can be thrown away which makes it possible to reduce the
58 // dimensionality of an array. All degenerate axes can be thrown
59 // away, but one can also specify which ones should be kept.
60 // <p>
61 // Another option of this class is to reorder the axes, thus to
62 // make the axes of a lattice appear in a different order.
63 // This can be useful when two images with diferent axes orders
64 // have to be combined.
65 // <p>
66 // When an AxesSpecifier has to be used for a lattice, the lattice's
67 // shape has to be applied to the AxesSpecifier. The result is
68 // a <linkto class=AxesMapping>AxesMapping</linkto> object.
69 // This object is (for example) used internally in the
70 // casacore SubLattice class to know how
71 // to map the axes form the original lattice to the sublattice.
72 // <note role=caution>
73 // Reordering axes is not supported (yet) by the other Casacore classes
74 // like Lattices and Images.
75 // </note>
76 // </synopsis>
77 
78 // <example>
79 // This example tells that all degenerate axes have to be kept.
80 // The axes are reordered to 1,0,2. Thus the first and second axes are
81 // swapped.
82 // <srcblock>
83 // AxesSpecifier spec(true, IPosition(3,1,0,2));
84 // AxesMapping map = spec.apply (IPosition(3,4,1,5));
85 // AlwaysAssertExit (map.posToNew (IPosition(3,2,0,3)) == IPosition(3,0,2,3));
86 // AlwaysAssertExit (map.posToOld (IPosition(3,0,2,3)) == IPosition(3,2,0,3));
87 //
88 // The following specification would have the same effect, because the
89 // unspecified axes are kept in their natural order.
90 // AxesSpecifier spec(true, IPosition(1,1));
91 // </srcblock>
92 //
93 // The same example as above, but now degenerated axes are removed.
94 // Note that because the second axis is removed, the third axis now
95 // get the second axis, thus gets swapped with the first axis.
96 // <br>Also note the difference between the functions <src>posToOld</src>
97 // and <src>shapeToOld</src>.
98 // <srcblock>
99 // AxesSpecifier spec(false, IPosition(1,1));
100 // AxesMapping map = spec.apply (IPosition(3,4,1,5));
101 // AlwaysAssertExit (map.posToNew (IPosition(3,2,0,3)) == IPosition(2,3,2));
102 // AlwaysAssertExit (map.posToOld (IPosition(3,3,2)) == IPosition(3,2,0,3);
103 // AlwaysAssertExit (map.shapeToOld (IPosition(3,3,2)) == IPosition(3,2,1,3);
104 // </srcblock>
105 // </example>
106 
107 //# <todo asof="yyyy/mm/dd">
108 //# </todo>
109 
111 {
112 public:
113  // The default constructor keeps all axes.
115 
116  // Tell if no or all degenerate axes have to be removed.
117  explicit AxesSpecifier (bool keepDegenerate);
118 
119  // Tell if no or all degenerate axes have to be removed.
120  // <br>The argument <src>axisPath</src> makes it possible to specify in
121  // which order the KEPT axes have to be used. Unspecified axes are
122  // appended to the end. It gives a means to reorder the axes of a lattice.
123  // <br>E.g. for a 4-dim lattice axisPath [2,0] means axis order [2,0,1,3].
124  explicit AxesSpecifier (bool keepDegenerate, const IPosition& axisPath);
125 
126  // Tell which (degenerate) axes have to be kept.
127  // Non-degenerate axes will always be kept.
128  explicit AxesSpecifier (const IPosition& keepAxes);
129 
130  // The argument <src>keepAxes</src> tells which degenerate axes have
131  // to be kept. Non-degenerate axes will always be kept.
132  // <br>The argument <src>axisPath</src> makes it possible to specify in
133  // which order the KEPT axes have to be used. Unspecified axes are
134  // appended to the end. It gives a means to reorder the axes of a lattice.
135  // <br>E.g. for a 4-dim lattice axisPath [2,0] means axis order [2,0,1,3].
136  AxesSpecifier (const IPosition& keepAxes, const IPosition& axisPath);
137 
138  // Apply the specification to a shape.
139  // It returns an <linkto class=AxesMapping>AxesMapping</linkto>
140  // object which takes care of mapping old to new axes order.
142 
143  // Are we keeping all degenerate axes ?
144  bool keep() const {return itsKeep;};
145 
146 private:
149  bool itsKeep;
150 };
151 
152 
153 
154 } //# NAMESPACE CASACORE - END
155 
156 #endif
AxesMapping apply(const IPosition &shape) const
Apply the specification to a shape.
AxesSpecifier()
The default constructor keeps all axes.
bool keep() const
Are we keeping all degenerate axes ?
AxesSpecifier(const IPosition &keepAxes, const IPosition &axisPath)
The argument keepAxes tells which degenerate axes have to be kept.
AxesSpecifier(bool keepDegenerate)
Tell if no or all degenerate axes have to be removed.
AxesSpecifier(bool keepDegenerate, const IPosition &axisPath)
Tell if no or all degenerate axes have to be removed.
AxesSpecifier(const IPosition &keepAxes)
Tell which (degenerate) axes have to be kept.
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