ENH: Creating templateless region splitter classes

The end goal of this topic is to consolidate code, enabling re-use,
and modularization to facilitate customization and experimentation
with different splitting algorithms for multi-threading, streaming and
IO.

Creating a new virtual ImageRegionSplitterBase class which does not
have a class template. This enables the same splitter to be used for
the multi-threading, the streaming image filter, and the IO
classes. Additionally, it allows for a global default splitter to use
used and shared.

The current default algorithm of splitting along the slowest dimension
is not implemented in the ImageRegionSplittingSlowDimension class.

There are some novel to ITK design patterns used here which should be
considered.

1) Using a templatedless class with templated function which
dispatches to a function which takes the dimension and arrays. This
allow for compiled functions to be reused.

2) Multiple inheritance is used, to add common static members which
access common data between all implemented instances of the class. That
is it can provide common data and methods for all instantiations
across template instantiations.

Add GetModified IVAR accessors to ImageRegion class.

Change-Id: Ia73a69a32cf5f543540809a466223f9456a9af06

Author: blowekamp

Modules/Core/Common/include/itkImageRegion.h

@@ -140,17 +140,17 @@ class ITK_EXPORT ImageRegion:public Region
   { m_Index = index; }
 
   /** Get index defining the corner of the region. */
-  const IndexType & GetIndex() const
-  { return m_Index; }
+  const IndexType & GetIndex() const { return m_Index; }
+  IndexType & GetModifiableIndex() { return m_Index; }
 
   /** Set the size of the region. This plus the index determines the
    * rectangular shape, or extent, of the region. */
   void SetSize(const SizeType & size)
   { m_Size = size; }
 
   /** Get the size of the region. */
-  const SizeType & GetSize() const
-  { return m_Size; }
+  const SizeType & GetSize() const { return m_Size; }
+  SizeType & GetModifiableSize() { return m_Size; }
 
   /** Convenience methods to get and set the size of the particular dimension i.
     */

Modules/Core/Common/include/itkImageRegionSplitterBase.h

@@ -0,0 +1,135 @@
+/*=========================================================================
+ *
+ *  Copyright Insight Software Consortium
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0.txt
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ *=========================================================================*/
+#ifndef __itkImageRegionSplitterBase_h
+#define __itkImageRegionSplitterBase_h
+
+#include "itkImageRegion.h"
+#include "itkObjectFactory.h"
+
+namespace itk
+{
+
+/** \class ImageRegionSplitterBase
+ * \brief Divide an image region into several pieces.
+ *
+ * ImageRegionSplitterBase is an abstract interface to  divides an
+ * ImageRegion into smaller regions. ImageRegionSplitterBase is used
+ * by the ImageSource,  StreamingImageFilter, streaming ImageIO
+ * classes to divide a region into a series of smaller subregions.
+ *
+ * This object has two basic methods: \c GetNumberOfSplits() and
+ * \c GetSplit().
+ *
+ * \c GetNumberOfSplits() is used to determine how may subregions a given
+ * region can be divided.  You call GetNumberOfSplits with an argument
+ * that is the number of subregions you want.  If the image region can
+ * support that number of subregions, that number is returned.
+ * Otherwise, the maximum number of splits less then or equal to the
+ * argumen  be returned.  For example, if a region splitter class only divides
+ * a region into horizontal slabs, then the maximum number of splits
+ * will be the number of rows in the region.
+ *
+ * \c GetSplit() returns the ith of N subregions (as an ImageRegion object).
+ *
+ * \sa ImageRegionSplitterDirection
+ * \sa ImageRegionSplitterSlowDimension
+ *
+ * \ingroup ITKSystemObjects
+ * \ingroup DataProcessing
+ * \ingroup ITKCommon
+ */
+
+class ITKCommon_EXPORT ImageRegionSplitterBase
+  :public Object
+{
+public:
+  /** Standard class typedefs. */
+  typedef ImageRegionSplitterBase    Self;
+  typedef Object                     Superclass;
+  typedef SmartPointer< Self >       Pointer;
+  typedef SmartPointer< const Self > ConstPointer;
+
+  /** Run-time type information (and related methods). */
+  itkTypeMacro(ImageRegionSplitterBase, Object);
+
+  /** How many pieces can the specified region be split? A given region
+   * cannot always be divided into the requested number of pieces. For
+   * instance, if the \c numberOfPieces exceeds the number of pixels along
+   * a certain dimensions, then some splits will not be possible. This
+   * method returns a number less than or equal to the requested number
+   * of pieces. */
+  template <unsigned int VImageDimension>
+    unsigned int GetNumberOfSplits(const ImageRegion<VImageDimension> & region,
+                                   unsigned int requestedNumber) const
+  {
+    return this->GetNumberOfSplitsInternal( VImageDimension,
+                                            region.GetIndex().m_Index,
+                                            region.GetSize().m_Size,
+                                            requestedNumber);
+  }
+
+
+  /** \brief Get a region definition that represents the ith piece a
+   * specified region.
+   *
+   * The \c numberOfPieces must be equal to what \c GetNumberOfSplits()
+   * returns. The return value is the maximum number of splits
+   * available. If \c i is greater than or equal to the return value
+   * the value of the region is undefined.
+   */
+  template <unsigned int VImageDimension>
+    unsigned int GetSplit( unsigned int i,
+                           unsigned int numberOfPieces,
+                           ImageRegion<VImageDimension> & region ) const
+  {
+    return this->GetSplitInternal( VImageDimension,
+                                   i,
+                                   numberOfPieces,
+                                   region.GetModifiableIndex().m_Index,
+                                   region.GetModifiableSize().m_Size );
+  }
+
+protected:
+  ImageRegionSplitterBase();
+
+  /** Templetless method to compute the number of possible splits for
+   *  any number of dimensions. */
+  virtual unsigned int GetNumberOfSplitsInternal( unsigned int dim,
+                                                  const IndexValueType regionIndex[],
+                                                  const SizeValueType regionSize[],
+                                                  unsigned int requestedNumber ) const = 0;
+
+  /** Templetless method to compute an actual split for any number of
+   * dimensions. \c dim is the size of the \c regionIndex and \c
+   * regionSize arrays.
+   */
+  virtual unsigned int GetSplitInternal( unsigned int dim,
+                                         unsigned int i,
+                                         unsigned int numberOfPieces,
+                                         IndexValueType regionIndex[],
+                                         SizeValueType regionSize[] ) const = 0;
+
+  void PrintSelf(std::ostream & os, Indent indent) const;
+
+private:
+  ImageRegionSplitterBase(const ImageRegionSplitterBase &); //purposely not implemented
+  void operator=(const ImageRegionSplitterBase &);      //purposely not implemented
+};
+} // end namespace itk
+
+#endif

Modules/Core/Common/include/itkImageRegionSplitterSlowDimension.h

@@ -0,0 +1,83 @@
+/*=========================================================================
+ *
+ *  Copyright Insight Software Consortium
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0.txt
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ *=========================================================================*/
+#ifndef __itkImageRegionSplitterSlowDimension_h
+#define __itkImageRegionSplitterSlowDimension_h
+
+#include "itkImageRegionSplitterBase.h"
+
+namespace itk
+{
+
+/** \class ImageRegionSplitterSlowDimension
+ * \brief Divide an image region along the slowest dimension
+ *
+ * ImageRegionSplitterSlowDimension divides an ImageRegion into smaller regions.
+ * ImageRegionSplitterSlowDimension is the default splitter for many situations.
+ *
+ * This ImageRegionSplitterSlowDimension class divides a region along the
+ * outermost or slowest dimension. If the outermost dimension has size
+ * 1 (i.e. a volume with a single slice), the ImageRegionSplitter will
+ * divide the region along the next outermost dimension. If that
+ * dimension has size 1, the process continues with the next outermost
+ * dimension.
+ *
+ * \sa ImageRegionSplitterDirection
+ *
+ * \ingroup ITKSystemObjects
+ * \ingroup DataProcessing
+ * \ingroup ITKCommon
+ */
+
+class ITKCommon_EXPORT ImageRegionSplitterSlowDimension
+  :public ImageRegionSplitterBase
+{
+public:
+  /** Standard class typedefs. */
+  typedef ImageRegionSplitterSlowDimension Self;
+  typedef ImageRegionSplitterBase          Superclass;
+  typedef SmartPointer< Self >             Pointer;
+  typedef SmartPointer< const Self >       ConstPointer;
+
+  /** Method for creation through the object factory. */
+  itkNewMacro(Self);
+
+  /** Run-time type information (and related methods). */
+  itkTypeMacro(ImageRegionSplitterSlowDimension, ImageRegionSplitterBase);
+
+
+protected:
+  ImageRegionSplitterSlowDimension();
+
+  virtual unsigned int GetNumberOfSplitsInternal( unsigned int dim,
+                                                  const IndexValueType regionIndex[],
+                                                  const SizeValueType regionSize[],
+                                                  unsigned int requestedNumber ) const;
+
+  virtual unsigned int GetSplitInternal( unsigned int dim,
+                                         unsigned int i,
+                                         unsigned int numberOfPieces,
+                                         IndexValueType regionIndex[],
+                                         SizeValueType regionSize[] ) const;
+
+private:
+  ImageRegionSplitterSlowDimension(const ImageRegionSplitterSlowDimension &); //purposely not implemented
+  void operator=(const ImageRegionSplitterSlowDimension &);      //purposely not implemented
+};
+} // end namespace itk
+
+#endif

Modules/Core/Common/include/itkImageSource.h

@@ -30,9 +30,31 @@
 
 #include "itkProcessObject.h"
 #include "itkImage.h"
+#include "itkImageRegionSplitterBase.h"
 
 namespace itk
 {
+
+/** \class ImageSourceCommon
+ * \brief Secondary bass class of ImageSource common between templates
+ *
+ * This class provides common non-templated code which can be compiled
+ * and used by all templated versions of ImageSource.
+ *
+ * This class must be inherited privately, and light-weight adapting
+ * of methods is required for virtual methods or non-private methods
+ * for the ImageSource interface.
+ *
+ * \ingroup ITKCommon
+ */
+struct ITKCommon_EXPORT ImageSourceCommon
+{
+  /**
+   * Provide access to a common static object for image region splitting
+   */
+  static  const ImageRegionSplitterBase*  GetGlobalDefaultSplitter(void);
+};
+
 /** \class ImageSource
  *  \brief Base class for all process objects that output image data.
  *
@@ -61,7 +83,8 @@ namespace itk
  * \endwiki
  */
 template< class TOutputImage >
-class ITK_EXPORT ImageSource:public ProcessObject
+class ITK_EXPORT ImageSource
+  : public ProcessObject, private ImageSourceCommon
 {
 public:
   /** Standard class typedefs. */
@@ -232,7 +255,7 @@ class ITK_EXPORT ImageSource:public ProcessObject
 
   /** If an imaging filter can be implemented as a multithreaded
    * algorithm, the filter will provide an implementation of
-   * ThreadedGenerateData().  This superclass will automatically split
+   * ThreadedGenerateData(). This superclass will automatically split
    * the output image into a number of pieces, spawn multiple threads,
    * and call ThreadedGenerateData() in each thread. Prior to spawning
    * threads, the BeforeThreadedGenerateData() method is called. After
@@ -287,11 +310,42 @@ class ITK_EXPORT ImageSource:public ProcessObject
    * a ThreadedGenerateData() method and NOT a GenerateData() method. */
   virtual void AfterThreadedGenerateData() {}
 
+  /** \brief Returns the default image region splitter
+   *
+   * This is an adapter function from the private common base class to
+   * the interface of this class.
+   */
+  static const ImageRegionSplitterBase* GetGlobalDefaultSplitter()
+  {
+    return ImageSourceCommon::GetGlobalDefaultSplitter();
+  }
+
+  /** \brief Get the image splitter to split the image for multi-threading.
+   *
+   * The Splitter object divides the image into regions for threading
+   * or streaming. The algorithms on how to split an images are
+   * separated into class so that they can be easily be reused. When
+   * deriving from this class to write a filter consideration to the
+   * algorithm used to divide the image should be made. If a change is
+   * desired this method should be overridden to return the
+   * appropriate object.
+   */
+  virtual const ImageRegionSplitterBase* GetImageRegionSplitter(void) const;
+
   /** Split the output's RequestedRegion into "num" pieces, returning
-   * region "i" as "splitRegion". This method is called "num" times. The
-   * regions must not overlap. The method returns the number of pieces that
+   * region "i" as "splitRegion". This method is called concurrently
+   * "num" times. The  regions must not overlap. The method returns the number of pieces that
    * the routine is capable of splitting the output RequestedRegion,
-   * i.e. return value is less than or equal to "num". */
+   * i.e. return value is less than or equal to "num".
+   *
+   * To override the algorithm used split the image this method should
+   * no longer be overridden. It stead the algorithm should be
+   * implemented in a ImageRegionSplitter class, and the
+   * GetImageRegionSplitter should overridden to return the splitter
+   * object with the desired algorithm.
+   *
+   * \sa GetImageRegionSplitter
+   **/
   virtual
   unsigned int SplitRequestedRegion(unsigned int i, unsigned int num, OutputImageRegionType & splitRegion);