Slicer.h

Go to the documentation of this file.

// # Slicer.h:  specify which elements to extract from an n-dimensional array
// # Copyright (C) 1994,1995,1997,1999
// # Associated Universities, Inc. Washington DC, USA.
// #
// # This library is free software; you can redistribute it and/or modify it
// # under the terms of the GNU Library General Public License as published by
// # the Free Software Foundation; either version 2 of the License, or (at your
// # option) any later version.
// #
// # This library is distributed in the hope that it will be useful, but WITHOUT
// # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
// # FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
// # License for more details.
// #
// # You should have received a copy of the GNU Library General Public License
// # along with this library; if not, write to the Free Software Foundation,
// # Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
// #
// # Correspondence concerning AIPS++ should be addressed as follows:
// #        Internet email: casa-feedback@nrao.edu.
// #        Postal address: AIPS++ Project Office
// #                        National Radio Astronomy Observatory
// #                        520 Edgemont Road
// #                        Charlottesville, VA 22903-2475 USA
 
#ifndef CASA_SLICER_2_H
#define CASA_SLICER_2_H
 
// # Includes
#include "IPosition.h"
 
namespace casacore {  // # NAMESPACE CASACORE - BEGIN
 
// # Forward Declarations
class Slice;
 
// <summary>
// Specify which elements to extract from an n-dimensional array
// </summary>
 
// <reviewed reviewer="Paul Shannon" date="1994/07/07" tests="tSlicer">
//  The review and modification of this class were undertaken, in part,
//  with the aim of making this class header an example -- this is what
//  the Casacore project thinks a class header should look like.
// </reviewed>
 
// <prerequisite>
// You should have at least a preliminary understanding of these classes:
//   <li> <linkto class=IPosition>IPosition</linkto>
//   <li> <linkto class=Array>Array</linkto>
//   <li> <linkto class=Slice>Slice</linkto>
// </prerequisite>
 
// <etymology>
// The class name "Slicer" may be thought of as a short form
// of "n-Dimensional Slice Specifier."  Some confusion is possible
// between class "Slice" and this class.
// </etymology>
//
// <synopsis>
// If you need to extract or operate upon a portion of an array,
// the Slicer class is the best way to specify the subarray you are
// interested in.
//
// Slicer has many constructors.  Of these, some require that the
// programmer supply a full specification of the array elements he
// wants to extract;  other constructors make do with partial information.
// In the latter case, the constructor will assume sensible default values or,
// when directed, infer missing information from the array that's getting
// sliced (hereafter, the "source" array).
//
// <h4> Constructing With Full Information </h4>
//
// To fully specify a subarray, you must supply three pieces of information
// for each axis of the subarray:
//
// <ol>
//    <li> where to start
//    <li> how many elements to extract
//    <li> what stride (or "increment" or "interval") to use:  a stride of
//         "n" means pick extract only every "nth" element along an axis
// </ol>
//
// The most basic constructor for Slicer illustrates this.  To create
// an Slicer for getting selected elements from a 3D array:
//
// <srcblock>
//   IPosition start (3,0,0,0), length (3,10,10,10), stride (3,3,3,3);
//   Slicer slicer (start, length, stride);
//   // assume proper declarations, and meaningful values in the source array
//   subArray = sourceArray (slicer);
// </srcblock>
// It gets elements 0,3,6,9,12,15,18,21,24,27 for each dimension.
//
// <note role=caution> If you wish to extract elements from the array
// at intervals, these intervals must be regular.   The interval is one
// constant integer for each dimension of the array:  it cannot be a function.
// </note>
//
// <note role=caution> "length", the second parameter to the Slicer
// constructor above, may actually be used in two ways.  In normal
// (and default) use, it specifies how many elements to select from the
// source.  In the alternative use, it specifies the index of the last element
// to extract from the source array.  This ambiguity (does "end" mean
// "length" or does it mean "last index"?) is handled by a default
// fourth parameter to the constructor.  This code fragment will
// extract the same subarray as the example above:
// <srcblock>
//   IPosition start (3,0,0,0), end (3,27,27,27), stride (3,3,3,3);
//   Slicer slicer (start, end, stride, Slicer::endIsLast);
//   subArray = sourceArray (slicer);
// </srcblock>
// Note that in this example end(3,28,29,28) gives the same result.
// (We use "end" as the name of the formal parameter because it supports
// both meanings -- "last index" or "length."  You may wish to use a
// clarifying name for the actual parameter in your code, as we have
// above when we used "length".)
// </note>
// Similar to Python it is possible to address the start and/or end value
// from the end by giving a negative value (-1 means the last value).
// However, a length and stride cannot be negative.
// Unlike Python the end value is inclusive (as discussed above).
// For example,
// <srcblock>
//    Slicer slicer (IPosition(1,-4), IPosition(1,-2), Slicer::endIsLast)
//    Slicer slicer (IPosition(1,6),  IPosition(1,8),  Slicer::endIsLast)
// </srcblock>
// Both Slicers give the same result when used on a Vector with length 10.
//
// <h4> Constructing with Partial Information </h4>
//
// Some of the constructors don't require complete information:  Slicer
// either calculates sensible default values or deduces them from the
// source array.  If you do not specify a "stride" argument, for example,
// a value of 1 will be used for all dimensions.  If you specify a "start"
// but nothing else, a stride of 1, and (perhaps against expectation)
// a length of 1 will be used.
//
// Note that using a negative start or end is also partial information.
// The actual array shape is needed to derive the exact start or end value.
//
// To instruct the Slicer to get otherwise unspecified information
// from the source array, you can create an IPosition like  "end"
// as shown here:
//
// <srcblock>
//   IPosition start (3,0,0,0), stride (3,3,3,3);
//   IPosition end   (3,Slicer::MimicSource, Slicer::MimicSource,
//                    Slicer::MimicSource);
//   Slicer smartSlicer (start, end, stride);
//   // assume proper declarations...
//   subArray = sourceArray (smartSlicer)
// </srcblock>
//
// If you are a library programmer, and write a class that can be sliced
// by the Slicer class, you need to understand the mechanism for
// completing the information which the application programmer, in using
// your class, specified incompletely. (If you are an application
// programmer, who wants to slice a library class, this explanation will
// be only of academic interest.)
//
// When the source array (the library class you provide) gets the Slicer --
// which typically comes when the source array is asked to return a
// reference to a subarray -- the source does a callback to the Slicer
// object.  The source array passes its own shape as one of the arguments
// to the Slicer callback and asks the Slicer to fill in the missing
// values from that shape.
//
// In use, and with an imagined class "MyVector", code would look
// like this:
// <srcblock>
//   // first, a fragment from the application program:
//   IPosition start (1,10), end (1, Slicer::MimicSource);
//   Slicer slicer (start, end);
//   MyVector <int> v0 (100);
//   MyVector <int> v1 = v0 (slicer);
//   //....
//   // second, a fragment from a constructor of the library class "MyVector":
//   // the MyVector class will construct v1 as a reference to
//   // selected elements of v0, using (among other things) a
//   // callback to the slicer it was passed (above, in the
//   // construction of v1.
//   //
//   IPosition start, end, stride;
//   fullSliceInformation =
//      slicer.inferShapeFromSource (MyVector::shape(), start, end, stride);
//   // now the MyVector instance knows everything it needs to
//   // construct the instance.
// </srcblock>
// Please note that v1 will have a length of 90, and refer to elements
// 10-99 of v0.
//
// <note role=warning> An exception will be thrown if the positions
//  defined in the Slicer exceed the source array's shape.
// </note>
// </synopsis>
//
// <example>
// Given a large image, 4k on a side, extract (by sampling) an image
// 1k on a side, but covering the same region as the original.
//
// <srcblock>
//   Image <float>  image ("N5364.fits");   // a 4-d VLA map, 4096 x 4096 x 3 x 1
//   IPosition start (4,0,0,0,0), stride (4,4,4,1,1);
//   IPosition end   (4, Slicer::MimicSource, Slicer::MimicSource,
//                    Slicer::MimicSource, Slicer::MimicSource);
//   Slicer smartSlicer (start, end, stride);
//   // assume proper declarations...
//   Image <float> subImage = image (smartSlicer);
// </srcblock>
//
// </example>
 
// <motivation>
// Slicer is particularly convenient for designers of other library
// classes: Array and Image, for example. (In fact, this convenience
// was the original motivation for the class.)  The benefit
// is this:  the application programmer, who needs a slice of an Array,
// may provide slicing specifications in many different ways, but the
// Array class author needs to provide only one member function to
// return the slice.  The Slicer class, in effect, and with its
// many constructors, provides a way to funnel all of the variety
// into a single member function call to the array or image class.
//
// For example, imagine a 100 x 100 x 100 array from which you want to
// extract various subarrays.  Here are some of the ways you might
// specify the the subarray in the -absence- of Slicer.
//
// <srcblock>
//   // preliminaries: create a cube and assign values to all elements --
//   //  this will be "source" array
//   Cube <int> bigCube (IPosition (3, 100, 100, 100));
//   assignValues (bigCube);
//   // declare a smaller cube, the destination array.
//   Cube <int> smallCube (IPosition (3, 10, 10, 10));
//
//   //  example 1: use Slice objects to extract a subcube -- the first
//   //   ten elements along each axis
//   Slice xIndices (0,10,1), yIndices (0,10,1), zIndices (0,10,1);
//   smallCube = bigCube (xIndices, yIndices, zIndices);
//
//   // example 2: get the same subcube using three IPosition arguments
//   IPosition start (3,0,0,0), end (3,10,10,10), stride (3,1,1,1);
//   smallCube = bigCube (start, end, stride);
//
//   // example 3: use 2 IPositions, letting the 3rd (stride) default to
//   //            IPosition (3,1,1,1)
//   smallCube = bigCube (start, end);
// </srcblock>
//
// So the Cube class (together with its base class) must define three separate
// member functions for the essentially identical operation of
// extracting a subcube.  The same replication is also required of
// Image, Array, and the other Array subclasses (Matrix and Vector).
//
// The Slicer class collapses all of this into a single member
// function per class:
//
// <srcblock>
//   Slicer slicer = (call the constructor that best suits your problem)
//   smallCube = bigCube (slicer);
// </srcblock>
//
// Since there are many constructors available for Slicer, you
// can still specify the subarray that you may want in a number of
// different ways, by constructing the Slicer in the way most natural
// to your circumstances.  You then pass the Slicer to the array, and
// you will get back the slice you want.
//
// This class also offers the application programmer considerable
// flexibility by allowing the shape of the source array to determine
// some of the slice specification.  This benefit is explained and
// demonstrated above.
// </motivation>
 
// <todo asof="1994/07/01">
//   <li> This class, and the TableArray, Array and Image classes,
//   could allow for the extraction of a subarray with fewer axes than the
//   source array.  At present, for example, you cannot, directly slice
//   a matrix from a cube.
// </todo>
 
class Slicer {
 public:
  // Define the "MimicSource" value which defines the open start or end.
  // This value should be different from MIN_INT in IPosition.h.
  // It should also not be the lowest possible value, since that
  // will probably be used as an undefined value.
  // It must be a negative number.
  enum { MimicSource = -2147483646 };
 
  // Define the possible interpretations of the end-value.
  enum LengthOrLast {
    // The end-values given in the constructor define the lengths.
    endIsLength,
    // The end-values given in the constructor define the trc.
    endIsLast
  };
 
  // Construct a 1-dimensional Slicer.
  // Start and end are inferred from the source; stride=1.
  // "endIsLength" and "endIsLast" are identical here, so there's
  // no need to discriminate between them by using a default parameter.
  Slicer();
 
  // The member function <src>inferShapeFromSource</src>
  // (invoked as a callback by the
  // source array) will use the shape of the source array for the
  // unspecified values:  IPosition elements with the value
  //  Slicer::MimicSource
  // <thrown>
  //    <li> ArraySlicerError
  // </thrown>
  // Create a Slicer with a given start, end (or length), and stride.
  // An exception will be thrown if a negative length or non-positive
  // stride is given or if the IPositions start, end, and stride
  // do not have the same dimensionality.
  // If length or stride is not given, they default to 1.
  // <br> It is possible to leave values in start and end undefined
  // by giving the value <src>MimicSource</src>. They can be filled
  // in later with the actual array shape using function
  // <src>inferShapeFromSource</src>.
  // <group>
  Slicer(const IPosition& start, const IPosition& end, const IPosition& stride,
         LengthOrLast endInterpretation = endIsLength);
  Slicer(const IPosition& start, const IPosition& end,
         LengthOrLast endInterpretation = endIsLength);
  explicit Slicer(const IPosition& start);
  // </group>
 
  // Create a Slicer object from Slice objects.
  // In a Slice object one defines the start, length, and stride for
  // one axis.
  // The default Slice constructor (called with no arguments) creates
  // a Slice with start and length equal to zero, and an undefined stride.
  // <group>
  // Create a Slicer for a 1-dimensional array.
  Slicer(const Slice& x, LengthOrLast endInterpretation = endIsLength);
 
  // Create a Slicer for a 2-dim array.
  Slicer(const Slice& x, const Slice& y, LengthOrLast endInterpretation = endIsLength);
 
  // Create a Slicer for a 3-dim array.
  Slicer(const Slice& x, const Slice& y, const Slice& z,
         LengthOrLast endInterpretation = endIsLength);
  // </group>
 
  // Equality
  bool operator==(const Slicer&) const;
 
  // Return the number of dimensions of the Slicer.
  size_t ndim() const;
 
  // This function checks all of the start, length (or end),
  // and stride IPositions, and fills in missing values by
  // getting the corresponding values from the shape of the
  // source array.
  // These will first be resized, if necessary.
  // If, for a given axis, (end < start) , it means that a
  // length of zero was specified.
  // An exception is thrown if the
  // start, end, or length exceeds the array shape or if the
  // dimensionality of the array and Slicer do not conform.
  // <thrown>
  //   <li> ArraySlicerError
  // </thrown>
  IPosition inferShapeFromSource(const IPosition& shape, IPosition& startResult,
                                 IPosition& endResult, IPosition& strideResult) const;
 
  // Report the defined starting position.
  const IPosition& start() const;
 
  // Report the defined ending position.
  const IPosition& end() const;
 
  // Report the defined stride.
  const IPosition& stride() const;
 
  // Report the length of the resulting axes.
  const IPosition& length() const;
 
  // Are all values fixed (i.e., no MimicSource given)?
  bool isFixed() const;
 
  // Set the start and end positions. No explicit checking is done that
  // the input parameters make sense, so you must be certain if you
  // call these. These are useful if you have a loop with many iterations
  // and you do not wish the overhead of creating a new Slicer object
  // for each iteration if the only thing you are doing is adjusting
  // the start and end positions. Other than for performance reasons,
  // these methods should not be called and you should prefer the
  // error checking provided by constructing a new Slicer object.
  // Note that the length is not updated, so in principle care should
  // be taken that the length does not change.
  // <group>
  void setStart(const IPosition& start) { start_p = start; }
  void setEnd(const IPosition& end) { end_p = end; }
  // </group>
 
 private:
  LengthOrLast asEnd_p;
  IPosition start_p;
  IPosition end_p;
  IPosition stride_p;
  IPosition len_p;  // Length of input
  bool fixed_p;     // no MimicSource used
 
  // Define a private constructor taking an ssize_t.
  // This is to prevent the user from the unexpected and meaningless
  // Slicer that would result when the ssize_t argument is promoted to
  // an IPosition.
  // Slicer (ssize_t);
 
  // Check the given start, end/length and stride.
  // Fill in the length or end.
  // It also calls <src>fillFixed</src> to fill the fixed flag.
  void fillEndLen();
 
  // Fill in start, len and stride from a Slice.
  void fillSlice(const Slice&, ssize_t& start, ssize_t& length, ssize_t& stride);
 
  // Fill the fixed flag.
  void fillFixed();
};
 
// <summary>IO functions for Slicer's</summary>
// <group name="Slicer IO">
// Print the contents of the specified Slicer to the specified stream.
std::ostream& operator<<(std::ostream& stream, const Slicer& slicer);
// </group>
std::string to_string(const Slicer& slicer);
 
inline size_t Slicer::ndim() const { return start_p.nelements(); }
 
inline const IPosition& Slicer::start() const { return start_p; }
 
inline const IPosition& Slicer::end() const { return end_p; }
 
inline const IPosition& Slicer::stride() const { return stride_p; }
 
inline const IPosition& Slicer::length() const { return len_p; }
 
inline bool Slicer::isFixed() const { return fixed_p; }
 
}  // namespace casacore
 
#endif