casacore
LCRegion.h
Go to the documentation of this file.
1 //# LCRegion.h: Abstract base class to define a region of interest in lattice coordinates
2 //# Copyright (C) 1998,1999,2000,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 #ifndef LATTICES_LCREGION_H
29 #define LATTICES_LCREGION_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
33 #include <casacore/lattices/Lattices/Lattice.h>
34 #include <casacore/casa/Arrays/IPosition.h>
35 #include <casacore/casa/Arrays/Slicer.h>
36 
37 namespace casacore { //# NAMESPACE CASACORE - BEGIN
38 
39 //# Forward Declarations
40 class TableRecord;
41 class RecordInterface;
42 
43 
44 // <summary>
45 // Abstract base class to define a region of interest in lattice coordinates.
46 // </summary>
47 
48 // <use visibility=export>
49 
50 // <reviewed reviewer="" date="" tests="">
51 // </reviewed>
52 
53 // <prerequisite>
54 // <li> <linkto class=Slicer>Slicer</linkto>
55 // </prerequisite>
56 
57 // <synopsis>
58 // The LCRegion class is the abstract base class for various types
59 // of LCRegion's (e.g. <linkto class=LCEllipsoid>LCEllipsoid</linkto>,
60 // <linkto class=LCBox>LCBox</linkto>).
61 // It contains the minimal bounding box of the region and, if needed,
62 // a mask with the same shape as the bounding box. A mask element
63 // is true if the element is inside the box.
64 // <p>
65 // Each LCRegion object must be able to convert itself to and from a record.
66 // In that way they can be made persistent (in for example a Table).
67 // <p>
68 // The LCRegion can be used in several Lattices and Images classes and
69 // functions to limit the area to operate on.
70 // </synopsis>
71 
72 // <example>
73 // <srcblock>
74 // </srcblock>
75 // </example>
76 
77 // <motivation>
78 // The Slicer class is too limited as a region, because it can only
79 // describe a rectangular region. Specialized classes are needed to
80 // describe arbitrary regions. They need a base class to combine them.
81 // </motivation>
82 
83 //# <todo asof="1997/11/11">
84 //# <li>
85 //# </todo>
86 
87 class LCRegion : public Lattice<Bool>
88 {
89 public:
91 
92  // Construct with the lattice shape only.
94 
95  // Copy constructor (copy semantics).
96  LCRegion (const LCRegion& other);
97 
98  virtual ~LCRegion();
99 
100  // Equality
101  virtual Bool operator== (const LCRegion& other) const;
102 
103  // Non-equality. Be careful, do not use this anywhere in the derived
104  // class structure. You must use, e.g.,
105  // <src>if (! LCRegion::operator== (...))</src>
106  // rather than <src>if (LCRegion::operator!= (...))</src> as the
107  // latter will invoke an infinite loop. It is ok to use when applying
108  // to a concrete class object.
109  Bool operator!= (const LCRegion& other) const;
110 
111  // Make a copy of the derived object.
112  // <group>
113  virtual Lattice<Bool>* clone() const;
114  virtual LCRegion* cloneRegion() const = 0;
115  // </group>
116 
117  // Handle deletion of the region by deleting possible tables.
118  // The default implementation does nothing.
119  virtual void handleDelete();
120 
121  // Handle renaming the region by renaming possible tables.
122  // The default implementation does nothing.
123  virtual void handleRename (const String& newName, Bool overwrite);
124 
125  // Region type. Returns className() of derived class.
126  virtual String type() const = 0;
127 
128  // Get or set the comment.
129  // <group>
130  const String& comment() const;
131  void setComment (const String& comment);
132  // </group>
133 
134  // Does the region have a mask?
135  virtual Bool hasMask() const = 0;
136 
137  // Construct another LCRegion (for e.g. another lattice) by moving
138  // this one. It recalculates the bounding box and mask.
139  // A positive translation value indicates "to right".
140  // <group>
141  LCRegion* translate (const IPosition& translateVector) const;
142  LCRegion* translate (const IPosition& translateVector,
143  const IPosition& newLatticeShape) const;
144  LCRegion* translate (const Vector<Float>& translateVector) const;
145  LCRegion* translate (const Vector<Float>& translateVector,
146  const IPosition& newLatticeShape) const;
147  // </group>
148 
149  // Give the full lattice shape.
150  const IPosition& latticeShape() const;
151 
152  // Give the bounding box.
153  const Slicer& boundingBox() const;
154 
155  // Expand a slicer or position in the region to the full lattice.
156  // This converts the positions in the region to positions
157  // in the entire lattice.
158  // <group>
159  Slicer expand (const Slicer& slicer) const;
160  IPosition expand (const IPosition& index) const;
161  // </group>
162 
163  // Convert the (derived) object to a record.
164  // The record can be used to make the object persistent.
165  // The <src>tableName</src> argument can be used by derived
166  // classes (e.g. LCPagedMask) to put very large objects.
167  virtual TableRecord toRecord (const String& tableName) const = 0;
168 
169  // Convert correct object from a record.
170  static LCRegion* fromRecord (const TableRecord&,
171  const String& tableName);
172 
173  // Return the dimensionality of the region.
174  virtual uInt ndim() const;
175 
176  // Return the shape of the region (i.e. of its bounding box).
177  virtual IPosition shape() const;
178 
179  // Usually the lattice (i.e. the region mask) is not writable.
180  virtual Bool isWritable() const;
181 
182  // Regions can usually not be put; i.e. no putSlice, etc. can be
183  // done on their masks.
184  // Hence LCRegion throws by default an exception for the
185  // following functions.
186  // <group>
187  virtual void doPutSlice (const Array<Bool>& sourceBuffer,
188  const IPosition& where,
189  const IPosition& stride);
190  virtual void set (const Bool& value);
191  virtual void apply (Bool (*function)(Bool));
192  virtual void apply (Bool (*function)(const Bool&));
193  virtual void apply (const Functional<Bool,Bool>& function);
194  virtual void putAt (const Bool& value, const IPosition& where);
195  virtual void copyData (const Lattice<Bool>& from);
196  // </group>
197 
198 protected:
199  // Assignment (copy semantics) is only useful for derived classes.
200  LCRegion& operator= (const LCRegion& other);
201 
202  // Sometimes it is inconvenient for a derived class to set the bounding
203  // box in the constructor. So it can be set explicitly.
204  // It fills in the possibly undefined Slicer values.
205  // It may even be needed to set the lattice shape.
206  // <group>
209  const Slicer& boundingBox);
210  // </group>
211 
212  // Do the actual translate in a derived class.
213  virtual LCRegion* doTranslate (const Vector<Float>& translateVector,
214  const IPosition& newLatticeShape) const = 0;
215 
216  // Define the type and class name in the record.
218  const String& className) const;
219 
220 private:
224 };
225 
226 
227 inline const Slicer& LCRegion::boundingBox() const
228 {
229  return itsBoundingBox;
230 }
231 inline const IPosition& LCRegion::latticeShape() const
232 {
233  return itsShape;
234 }
235 inline LCRegion* LCRegion::translate (const IPosition& translateVector) const
236 {
237  return translate (translateVector, itsShape);
238 }
239 inline LCRegion* LCRegion::translate (const Vector<Float>& translateVector)
240  const
241 {
242  return translate (translateVector, itsShape);
243 }
244 inline const String& LCRegion::comment() const
245 {
246  return itsComment;
247 }
248 inline void LCRegion::setComment (const String& comment)
249 {
251 }
252 
253 inline Bool LCRegion::operator!= (const LCRegion& other) const
254 //
255 // Watch out ! You must not, in the derived class structure,
256 // invoke LCRegion::operator!= If you do, you will be stuck
257 // in a time warp, as this will just fetch the
258 // operator== of the concrete class and you start all over again.
259 // You must use always use !LCRegion::operator==. It is ok in application
260 // code using the concrete class to say
261 // if (x != y) where x and y are, say, LCBoxes.
262 {
263  return (!operator==(other));
264 }
265 
266 
267 
268 
269 } //# NAMESPACE CASACORE - END
270 
271 #endif
virtual Bool operator==(const LCRegion &other) const
Equality
Slicer itsBoundingBox
Definition: LCRegion.h:222
virtual Bool isWritable() const
Usually the lattice (i.e.
LCRegion(const LCRegion &other)
Copy constructor (copy semantics).
void setComment(const String &comment)
Definition: LCRegion.h:248
static LCRegion * fromRecord(const TableRecord &, const String &tableName)
Convert correct object from a record.
virtual String type() const =0
Region type.
LCRegion * translate(const IPosition &translateVector) const
Construct another LCRegion (for e.g.
Definition: LCRegion.h:235
void setShapeAndBoundingBox(const IPosition &latticeShape, const Slicer &boundingBox)
void defineRecordFields(RecordInterface &record, const String &className) const
Define the type and class name in the record.
virtual void copyData(const Lattice< Bool > &from)
Copy the data from the given lattice to this one.
LCRegion & operator=(const LCRegion &other)
Assignment (copy semantics) is only useful for derived classes.
const String & comment() const
Get or set the comment.
Definition: LCRegion.h:244
Slicer expand(const Slicer &slicer) const
Expand a slicer or position in the region to the full lattice.
virtual void apply(Bool(*function)(const Bool &))
IPosition itsShape
Definition: LCRegion.h:221
virtual uInt ndim() const
Return the dimensionality of the region.
virtual void apply(const Functional< Bool, Bool > &function)
Bool operator!=(const LCRegion &other) const
Non-equality.
Definition: LCRegion.h:253
virtual void doPutSlice(const Array< Bool > &sourceBuffer, const IPosition &where, const IPosition &stride)
Regions can usually not be put; i.e.
virtual TableRecord toRecord(const String &tableName) const =0
Convert the (derived) object to a record.
virtual void handleRename(const String &newName, Bool overwrite)
Handle renaming the region by renaming possible tables.
const Slicer & boundingBox() const
Give the bounding box.
Definition: LCRegion.h:227
IPosition expand(const IPosition &index) const
const IPosition & latticeShape() const
Give the full lattice shape.
Definition: LCRegion.h:231
LCRegion * translate(const IPosition &translateVector, const IPosition &newLatticeShape) const
virtual void apply(Bool(*function)(Bool))
Replace every element, x, of the Lattice with the result of f(x).
LCRegion(const IPosition &latticeShape)
Construct with the lattice shape only.
virtual void handleDelete()
Handle deletion of the region by deleting possible tables.
virtual Lattice< Bool > * clone() const
Make a copy of the derived object.
virtual IPosition shape() const
Return the shape of the region (i.e.
virtual LCRegion * doTranslate(const Vector< Float > &translateVector, const IPosition &newLatticeShape) const =0
Do the actual translate in a derived class.
virtual void set(const Bool &value)
Set all elements in the Lattice to the given value.
void setBoundingBox(const Slicer &boundingBox)
Sometimes it is inconvenient for a derived class to set the bounding box in the constructor.
virtual Bool hasMask() const =0
Does the region have a mask?
virtual void putAt(const Bool &value, const IPosition &where)
Put the value of a single element.
LCRegion * translate(const Vector< Float > &translateVector, const IPosition &newLatticeShape) const
virtual LCRegion * cloneRegion() const =0
String: the storage and methods of handling collections of characters.
Definition: String.h:225
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned int uInt
Definition: aipstype.h:51
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.