Loading...
Searching...
No Matches
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 - END
#endif
IPosition.h
casacore::IPosition
Definition IPosition.h:117
casacore::Slice
Definition Slice.h:89
casacore::Slicer
Definition Slicer.h:287
casacore::Slicer::length
const IPosition & length() const
Report the length of the resulting axes.
Definition Slicer.h:459
casacore::Slicer::setEnd
void setEnd(const IPosition &end)
Definition Slicer.h:406
casacore::Slicer::end
const IPosition & end() const
Report the defined ending position.
Definition Slicer.h:453
casacore::Slicer::Slicer
Slicer(const IPosition &start, const IPosition &end, LengthOrLast endInterpretation=endIsLength)
casacore::Slicer::Slicer
Slicer(const Slice &x, const Slice &y, const Slice &z, LengthOrLast endInterpretation=endIsLength)
Create a Slicer for a 3-dim array.
casacore::Slicer::Slicer
Slicer(const Slice &x, LengthOrLast endInterpretation=endIsLength)
Create a Slicer object from Slice objects.
casacore::Slicer::stride_p
IPosition stride_p
Definition Slicer.h:415
casacore::Slicer::stride
const IPosition & stride() const
Report the defined stride.
Definition Slicer.h:456
casacore::Slicer::MimicSource
@ MimicSource
Definition Slicer.h:295
casacore::Slicer::Slicer
Slicer(const Slice &x, const Slice &y, LengthOrLast endInterpretation=endIsLength)
Create a Slicer for a 2-dim array.
casacore::Slicer::fillSlice
void fillSlice(const Slice &, ssize_t &start, ssize_t &length, ssize_t &stride)
Fill in start, len and stride from a Slice.
casacore::Slicer::fillEndLen
void fillEndLen()
Define a private constructor taking an ssize_t.
casacore::Slicer::asEnd_p
LengthOrLast asEnd_p
Definition Slicer.h:412
casacore::Slicer::Slicer
Slicer(const IPosition &start, const IPosition &end, const IPosition &stride, LengthOrLast endInterpretation=endIsLength)
The member function inferShapeFromSource (invoked as a callback by the source array) will use the sha...
casacore::Slicer::start_p
IPosition start_p
Definition Slicer.h:413
casacore::Slicer::start
const IPosition & start() const
Report the defined starting position.
Definition Slicer.h:450
casacore::Slicer::fillFixed
void fillFixed()
Fill the fixed flag.
casacore::Slicer::Slicer
Slicer(const IPosition &start)
casacore::Slicer::isFixed
bool isFixed() const
Are all values fixed (i.e., no MimicSource given)?
Definition Slicer.h:462
casacore::Slicer::len_p
IPosition len_p
Definition Slicer.h:416
casacore::Slicer::Slicer
Slicer()
Construct a 1-dimensional Slicer.
casacore::Slicer::LengthOrLast
LengthOrLast
Define the possible interpretations of the end-value.
Definition Slicer.h:298
casacore::Slicer::endIsLast
@ endIsLast
The end-values given in the constructor define the trc.
Definition Slicer.h:302
casacore::Slicer::endIsLength
@ endIsLength
The end-values given in the constructor define the lengths.
Definition Slicer.h:300
casacore::Slicer::operator==
bool operator==(const Slicer &) const
Equality.
casacore::Slicer::fixed_p
bool fixed_p
Definition Slicer.h:417
casacore::Slicer::end_p
IPosition end_p
Definition Slicer.h:414
casacore::Slicer::ndim
size_t ndim() const
Return the number of dimensions of the Slicer.
Definition Slicer.h:447
casacore::Slicer::inferShapeFromSource
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...
casacore::Slicer::setStart
void setStart(const IPosition &start)
Set the start and end positions.
Definition Slicer.h:404
casacore
this file contains all the compiler specific defines
Definition mainpage.dox:28
casacore::operator<<
ostream & operator<<(ostream &os, const IComplex &)
Show on ostream.
casacore::shape
IPosition shape(const RecordFieldId &) const
Get the actual shape of this field.
casacore::to_string
std::string to_string(const IPosition &ip)
casacore::Slicer_global_functions_Slicer_IO
IO functions for Slicer's .
Definition Slicer.h:442
casacore::Slicer_global_functions_Slicer_IO::operator<<
std::ostream & operator<<(std::ostream &stream, const Slicer &slicer)
Print the contents of the specified Slicer to the specified stream.