casacore
Slicer.h
Go to the documentation of this file.
1 //# Slicer.h: specify which elements to extract from an n-dimensional array
2 //# Copyright (C) 1994,1995,1997,1999
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 CASA_SLICER_H
29 #define CASA_SLICER_H
30 
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <casacore/casa/Arrays/IPosition.h>
35 
36 namespace casacore { //# NAMESPACE CASACORE - BEGIN
37 
38 //# Forward Declarations
39 class Slice;
40 
41 
42 // <summary>
43 // Specify which elements to extract from an n-dimensional array
44 // </summary>
45 
46 // <reviewed reviewer="Paul Shannon" date="1994/07/07" tests="tSlicer">
47 // The review and modification of this class were undertaken, in part,
48 // with the aim of making this class header an example -- this is what
49 // the Casacore project thinks a class header should look like.
50 // </reviewed>
51 
52 // <prerequisite>
53 // You should have at least a preliminary understanding of these classes:
54 // <li> <linkto class=IPosition>IPosition</linkto>
55 // <li> <linkto class=Array>Array</linkto>
56 // <li> <linkto class=Slice>Slice</linkto>
57 // </prerequisite>
58 
59 // <etymology>
60 // The class name "Slicer" may be thought of as a short form
61 // of "n-Dimensional Slice Specifier." Some confusion is possible
62 // between class "Slice" and this class.
63 // </etymology>
64 //
65 // <synopsis>
66 // If you need to extract or operate upon a portion of an array,
67 // the Slicer class is the best way to specify the subarray you are
68 // interested in.
69 //
70 // Slicer has many constructors. Of these, some require that the
71 // programmer supply a full specification of the array elements he
72 // wants to extract; other constructors make do with partial information.
73 // In the latter case, the constructor will assume sensible default values or,
74 // when directed, infer missing information from the array that's getting
75 // sliced (hereafter, the "source" array).
76 //
77 // <h4> Constructing With Full Information </h4>
78 //
79 // To fully specify a subarray, you must supply three pieces of information
80 // for each axis of the subarray:
81 //
82 // <ol>
83 // <li> where to start
84 // <li> how many elements to extract
85 // <li> what stride (or "increment" or "interval") to use: a stride of
86 // "n" means pick extract only every "nth" element along an axis
87 // </ol>
88 //
89 // The most basic constructor for Slicer illustrates this. To create
90 // an Slicer for getting selected elements from a 3D array:
91 //
92 // <srcblock>
93 // IPosition start (3,0,0,0), length (3,10,10,10), stride (3,3,3,3);
94 // Slicer slicer (start, length, stride);
95 // // assume proper declarations, and meaningful values in the source array
96 // subArray = sourceArray (slicer);
97 // </srcblock>
98 //
99 // <note role=caution> If you wish to extract elements from the array
100 // at intervals, these intervals must be regular. The interval is one
101 // constant integer for each dimension of the array: it cannot be a function.
102 // </note>
103 //
104 // <note role=caution> "length", the second parameter to the Slicer
105 // constructor above, may actually be used in two ways. In normal
106 // (and default) use, it specifies how many elements to select from the
107 // source. In the alternative use, it specifies the index of the last element
108 // to extract from the source array. This ambiguity (does "end" mean
109 // "length" or does it mean "last index"?) is handled by a default
110 // fourth parameter to the constructor. This code fragment will
111 // extract the same subarray as the example above:
112 // <srcblock>
113 // IPosition start (3,0,0,0), end (3,27,27,27), stride (3,3,3,3);
114 // Slicer slicer (start, end, stride, Slicer::endIsLast);
115 // subArray = sourceArray (slicer);
116 // </srcblock>
117 // (We use "end" as the name of the formal parameter because it supports
118 // both meanings -- "last index" or "length." You may wish to use a
119 // clarifying name for the actual parameter in your code, as we have
120 // above when we used "length".)
121 // </note>
122 //
123 // <h4> Constructing with Partial Information </h4>
124 //
125 // Some of the constructors don't require complete information: Slicer
126 // either calculates sensible default values or deduces them from the
127 // source array. If you do not specify a "stride" argument, for example,
128 // a value of 1 will be used for all dimensions. If you specify a "start"
129 // but nothing else, a stride of 1, and (perhaps against expectation)
130 // a length of 1 will be used.
131 //
132 //
133 // To instruct the Slicer to get otherwise unspecified information
134 // from the source array, you can create an IPosition like "end"
135 // as shown here:
136 //
137 // <srcblock>
138 // IPosition start (3,0,0,0), stride (3,3,3,3);
139 // IPosition end (3,Slicer::MimicSource, Slicer::MimicSource,
140 // Slicer::MimicSource);
141 // Slicer smartSlicer (start, end, stride);
142 // // assume proper declarations...
143 // subArray = sourceArray (smartSlicer)
144 // </srcblock>
145 //
146 // If you are a library programmer, and write a class that can be sliced
147 // by the Slicer class, you need to understand the mechanism for
148 // completing the information which the application programmer, in using
149 // your class, specified incompletely. (If you are an application
150 // programmer, who wants to slice a library class, this explanation will
151 // be only of academic interest.)
152 //
153 // When the source array (the library class you provide) gets the Slicer --
154 // which typically comes when the source array is asked to return a
155 // reference to a subarray -- the source does a callback to the Slicer
156 // object. The source array passes its own shape as one of the arguments
157 // to the Slicer callback and asks the Slicer to fill in the missing
158 // values from that shape.
159 //
160 // In use, and with an imagined class "MyVector", code would look
161 // like this:
162 // <srcblock>
163 // // first, a fragment from the application program:
164 // IPosition start (1,10), end (1, Slicer::MimicSource);
165 // Slicer slicer (start, end);
166 // MyVector <Int> v0 (100);
167 // MyVector <Int> v1 = v0 (slicer);
168 // //....
169 // // second, a fragment from a constructor of the library class "MyVector":
170 // // the MyVector class will construct v1 as a reference to
171 // // selected elements of v0, using (among other things) a
172 // // callback to the slicer it was passed (above, in the
173 // // construction of v1.
174 // //
175 // IPosition start, end, stride;
176 // fullSliceInformation =
177 // slicer.inferShapeFromSource (MyVector::shape(), start, end, stride);
178 // // now the MyVector instance knows everything it needs to
179 // // construct the instance.
180 // </srcblock>
181 // Please note that v1 will have a length of 90, and refer to elements
182 // 10-99 of v0.
183 //
184 // <note role=warning> An exception will be thrown if the positions
185 // defined in the Slicer exceed the source array's shape.
186 // </note>
187 // </synopsis>
188 //
189 // <example>
190 // Given a large image, 4k on a side, extract (by sampling) an image
191 // 1k on a side, but covering the same region as the original.
192 //
193 // <srcblock>
194 // Image <Float> image ("N5364.fits"); // a 4-d VLA map, 4096 x 4096 x 3 x 1
195 // IPosition start (4,0,0,0,0), stride (4,4,4,1,1);
196 // IPosition end (4, Slicer::MimicSource, Slicer::MimicSource,
197 // Slicer::MimicSource, Slicer::MimicSource);
198 // Slicer smartSlicer (start, end, stride);
199 // // assume proper declarations...
200 // Image <Float> subImage = image (smartSlicer);
201 // </srcblock>
202 //
203 // </example>
204 
205 // <motivation>
206 // Slicer is particularly convenient for designers of other library
207 // classes: Array and Image, for example. (In fact, this convenience
208 // was the original motivation for the class.) The benefit
209 // is this: the application programmer, who needs a slice of an Array,
210 // may provide slicing specifications in many different ways, but the
211 // Array class author needs to provide only one member function to
212 // return the slice. The Slicer class, in effect, and with its
213 // many constructors, provides a way to funnel all of the variety
214 // into a single member function call to the array or image class.
215 //
216 // For example, imagine a 100 x 100 x 100 array from which you want to
217 // extract various subarrays. Here are some of the ways you might
218 // specify the the subarray in the -absence- of Slicer.
219 //
220 // <srcblock>
221 // // preliminaries: create a cube and assign values to all elements --
222 // // this will be "source" array
223 // Cube <Int> bigCube (IPosition (3, 100, 100, 100));
224 // assignValues (bigCube);
225 // // declare a smaller cube, the destination array.
226 // Cube <Int> smallCube (IPosition (3, 10, 10, 10));
227 //
228 // // example 1: use Slice objects to extract a subcube -- the first
229 // // ten elements along each axis
230 // Slice xIndices (0,10,1), yIndices (0,10,1), zIndices (0,10,1);
231 // smallCube = bigCube (xIndices, yIndices, zIndices);
232 //
233 // // example 2: get the same subcube using three IPosition arguments
234 // IPosition start (3,0,0,0), end (3,10,10,10), stride (3,1,1,1);
235 // smallCube = bigCube (start, end, stride);
236 //
237 // // example 3: use 2 IPositions, letting the 3rd (stride) default to
238 // // IPosition (3,1,1,1)
239 // smallCube = bigCube (start, end);
240 // </srcblock>
241 //
242 // So the Cube class (together with its base class) must define three separate
243 // member functions for the essentially identical operation of
244 // extracting a subcube. The same replication is also required of
245 // Image, Array, and the other Array subclasses (Matrix and Vector).
246 //
247 // The Slicer class collapses all of this into a single member
248 // function per class:
249 //
250 // <srcblock>
251 // Slicer slicer = (call the constructor that best suits your problem)
252 // smallCube = bigCube (slicer);
253 // </srcblock>
254 //
255 // Since there are many constructors available for Slicer, you
256 // can still specify the subarray that you may want in a number of
257 // different ways, by constructing the Slicer in the way most natural
258 // to your circumstances. You then pass the Slicer to the array, and
259 // you will get back the slice you want.
260 //
261 // This class also offers the application programmer considerable
262 // flexibility by allowing the shape of the source array to determine
263 // some of the slice specification. This benefit is explained and
264 // demonstrated above.
265 // </motivation>
266 
267 // <todo asof="1994/07/01">
268 // <li> This class, and the TableArray, Array and Image classes,
269 // could allow for the extraction of a subarray with fewer axes than the
270 // source array. At present, for example, you cannot, directly slice
271 // a matrix from a cube.
272 // </todo>
273 
274 
275 class Slicer
276 {
277 public:
278 
279  // Define the "MimicSource" value which defines the open start or end.
280  // This value should be different from MIN_INT in IPosition.h.
281  // It should also not be the lowest possible value, since that
282  // will probably be used as an undefined value.
283  enum {MimicSource= -2147483646};
284 
285  // Define the possible interpretations of the end-value.
287  // The end-values given in the constructor define the lengths.
289  // The end-values given in the constructor define the trc.
291  };
292 
293  // Construct a 1-dimensional Slicer.
294  // Start and end are inferred from the source; stride=1.
295  // "endIsLength" and "endIsLast" are identical here, so there's
296  // no need to discriminate between them by using a default parameter.
297  Slicer();
298 
299  // The member function <src>inferShapeFromSource</src>
300  // (invoked as a callback by the
301  // source array) will use the shape of the source array for the
302  // unspecified values: IPosition elements with the value
303  // Slicer::MimicSource
304  // <thrown>
305  // <li> ArraySlicerError
306  // </thrown>
307  // Create a Slicer with a given start, end (or length), and stride.
308  // An exception will be thrown if a negative length or non-positive
309  // stride is given or if the IPositions start, end, and stride
310  // do not have the same dimensionality.
311  // If length or stride is not given, they default to 1.
312  // <br> It is possible to leave values in start and end undefined
313  // by giving the value <src>MimicSource</src>. They can be filled
314  // in later with the actual array shape using function
315  // <src>inferShapeFromSource</src>.
316  // <group>
317  Slicer (const IPosition& start, const IPosition& end,
318  const IPosition& stride,
319  LengthOrLast endInterpretation = endIsLength);
320  Slicer (const IPosition& start, const IPosition& end,
321  LengthOrLast endInterpretation = endIsLength);
322  explicit Slicer (const IPosition& start);
323  // </group>
324 
325  // Create a Slicer object from Slice objects.
326  // In a Slice object one defines the start, length, and stride for
327  // one axis.
328  // The default Slice constructor (called with no arguments) creates
329  // a Slice with start and length equal to zero, and an undefined stride.
330  // <group>
331  // Create a Slicer for a 1-dimensional array.
332  Slicer (const Slice& x, LengthOrLast endInterpretation = endIsLength);
333 
334  // Create a Slicer for a 2-dim array.
335  Slicer (const Slice& x, const Slice& y,
336  LengthOrLast endInterpretation = endIsLength);
337 
338  // Create a Slicer for a 3-dim array.
339  Slicer (const Slice& x, const Slice& y, const Slice& z,
340  LengthOrLast endInterpretation = endIsLength);
341  // </group>
342 
343  // Copy constructor (copy semantics).
344  Slicer (const Slicer&);
345 
346  // Assignment (copy semantics).
347  Slicer& operator= (const Slicer&);
348 
349  // Equality
350  Bool operator==(const Slicer&) const;
351 
352  // Return the number of dimensions of the Slicer.
353  uInt ndim() const;
354 
355  // This function checks all of the start, length (or end),
356  // and stride IPositions, and fills in missing values by
357  // getting the corresponding values from the shape of the
358  // source array.
359  // These will first be resized, if necessary.
360  // If, for a given axis, (end < start) , it means that a
361  // length of zero was specified.
362  // An exception is thrown if the
363  // start, end, or length exceeds the array shape or if the
364  // dimensionality of the array and Slicer do not conform.
365  // <thrown>
366  // <li> ArraySlicerError
367  // </thrown>
368  // <group>
369  // Infer the slicer's shape from an array, using a zero origin.
371  (const IPosition& shape, IPosition& startResult,
372  IPosition& endResult, IPosition& strideResult) const;
373 
374  // Infer the slicer shape from an array, with the given origin.
375  // The returned values are based on a zero origin.
377  (const IPosition& shape, const IPosition& origin,
378  IPosition& startResult, IPosition& endResult,
379  IPosition& strideResult) const;
380  // </group>
381 
382  // Report the defined starting position.
383  const IPosition& start() const;
384 
385  // Report the defined ending position.
386  const IPosition& end() const;
387 
388  // Report the defined stride.
389  const IPosition& stride() const;
390 
391  // Report the length of the resulting axes.
392  const IPosition& length() const;
393 
394  // Are all values fixed (i.e., no MimicSource given)?
395  Bool isFixed() const;
396 
397  // Set the start and end positions. No explicit checking is done that
398  // the input parameters make sense, so you must be certain if you
399  // call these. These are useful if you have a loop with many iterations
400  // and you do not wish the overhead of creating a new Slicer object
401  // for each iteration if the only thing you are doing is adjusting
402  // the start and end positions. Other than for performance reasons,
403  // these methods should not be called and you should prefer the
404  // error checking provided by constructing a new Slicer object.
405  // Note that the length is not updated, so in principle care should
406  // be taken that the length does not change.
407  // <group>
408  void setStart (const IPosition& start)
409  { start_p = start; }
410  void setEnd (const IPosition& end)
411  { end_p = end; }
412  // </group>
413 
414 
415 private:
420  IPosition len_p; // Length of input
421  Bool fixed_p; // no MimicSource used
422 
423  // Define a private constructor taking an ssize_t.
424  // This is to prevent the user from the unexpected and meaningless
425  // Slicer that would result when the ssize_t argument is promoted to
426  // an IPosition.
427  Slicer (ssize_t);
428 
429  // Check the given start, end/length and stride.
430  // Fill in the length or end.
431  // It also calls <src>fillFixed</src> to fill the fixed flag.
432  void fillEndLen();
433 
434  // Fill in start, len and stride from a Slice.
435  void fillSlice (const Slice&, ssize_t& start, ssize_t& length,
436  ssize_t& stride);
437 
438  // Fill the fixed flag.
439  void fillFixed();
440 };
441 
442 
443 // <summary>IO functions for Slicer's</summary>
444 // <group name="Slicer IO">
445 // Print the contents of the specified Slicer to the specified stream.
446 std::ostream& operator << (std::ostream& stream, const Slicer& slicer);
447 // </group>
448 
449 
450 
451 inline uInt Slicer::ndim() const
452  { return start_p.nelements(); }
453 
454 inline const IPosition& Slicer::start() const
455  { return start_p; }
456 
457 inline const IPosition& Slicer::end() const
458  { return end_p; }
459 
460 inline const IPosition& Slicer::stride() const
461  { return stride_p; }
462 
463 inline const IPosition& Slicer::length() const
464  { return len_p; }
465 
466 inline Bool Slicer::isFixed() const
467  { return fixed_p; }
468 
469 
470 
471 } //# NAMESPACE CASACORE - END
472 
473 #endif
474 
A Vector of integers, for indexing into Array<T> objects.
Definition: IPosition.h:119
IPosition len_p
Definition: Slicer.h:420
IPosition stride_p
Definition: Slicer.h:419
IPosition inferShapeFromSource(const IPosition &shape, IPosition &startResult, IPosition &endResult, IPosition &strideResult) const
This function checks all of the start, length (or end), and stride IPositions, and fills in missing v...
void fillEndLen()
Check the given start, end/length and stride.
Bool isFixed() const
Are all values fixed (i.e., no MimicSource given)?
Definition: Slicer.h:466
IPosition start_p
Definition: Slicer.h:417
ostream & operator<<(ostream &os, const IComplex &)
Show on ostream.
The end-values given in the constructor define the lengths.
Definition: Slicer.h:288
const IPosition & end() const
Report the defined ending position.
Definition: Slicer.h:457
void setEnd(const IPosition &end)
Definition: Slicer.h:410
uInt nelements() const
The number of elements in this IPosition.
Definition: IPosition.h:532
void setStart(const IPosition &start)
Set the start and end positions.
Definition: Slicer.h:408
Bool operator==(const Slicer &) const
Equality.
define a (start,length,increment) along an axis
Definition: Slice.h:93
void fillFixed()
Fill the fixed flag.
Slicer & operator=(const Slicer &)
Assignment (copy semantics).
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:39
LengthOrLast
Define the possible interpretations of the end-value.
Definition: Slicer.h:286
TableExprNode shape(const TableExprNode &array)
Function operating on any scalar or array resulting in a Double array containing the shape...
Definition: ExprNode.h:2015
LengthOrLast asEnd_p
Definition: Slicer.h:416
Specify which elements to extract from an n-dimensional array.
Definition: Slicer.h:275
IPosition end_p
Definition: Slicer.h:418
const IPosition & length() const
Report the length of the resulting axes.
Definition: Slicer.h:463
uInt ndim() const
Return the number of dimensions of the Slicer.
Definition: Slicer.h:451
Slicer()
Construct a 1-dimensional Slicer.
const IPosition & start() const
Report the defined starting position.
Definition: Slicer.h:454
this file contains all the compiler specific defines
Definition: mainpage.dox:28
The end-values given in the constructor define the trc.
Definition: Slicer.h:290
unsigned int uInt
Definition: aipstype.h:48
void fillSlice(const Slice &, ssize_t &start, ssize_t &length, ssize_t &stride)
Fill in start, len and stride from a Slice.
const IPosition & stride() const
Report the defined stride.
Definition: Slicer.h:460