itkImageBufferRange.h

Go to the documentation of this file.

/*=========================================================================
 *
 *  Copyright NumFOCUS
 *
 *  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
 *
 *         https://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 itkImageBufferRange_h
#define itkImageBufferRange_h
 
#include <cassert>
#include <cstddef>  // For ptrdiff_t.
#include <iterator> // For random_access_iterator_tag.
#include <limits>
#include <type_traits> // For conditional, enable_if, is_same, and is_const.
 
#include "itkMacro.h" // For itkNotUsed.
#include "itkDefaultPixelAccessor.h"
#include "itkDefaultPixelAccessorFunctor.h"
#include "itkDefaultVectorPixelAccessor.h"
#include "itkDefaultVectorPixelAccessorFunctor.h"
#include "itkImageRegion.h"
 
namespace itk
{

template <typename TImage>
class ImageBufferRange final
{
private:
  using PixelType = typename TImage::PixelType;
  using InternalPixelType = typename TImage::InternalPixelType;
  using AccessorFunctorType = typename TImage::AccessorFunctorType;
 
  // Tells whether the specified template argument is a template specialization of itk::DefaultPixelAccessorFunctor.
  template <typename TAccessorFunctor>
  struct IsDefaultPixelAccessorFunctor : std::false_type
  {};
 
  template <typename TAccessorFunctorImage>
  struct IsDefaultPixelAccessorFunctor<DefaultPixelAccessorFunctor<TAccessorFunctorImage>> : std::true_type
  {};
 
  // Tells whether or not this range supports direct pixel access. If it does,
  // iterator::operator*() returns a reference to the internally stored pixel,
  // otherwise iterator::operator*() returns a proxy, which internally uses the
  // AccessorFunctor of the image to access the pixel indirectly.
  static constexpr bool SupportsDirectPixelAccess =
    std::is_same_v<PixelType, InternalPixelType> &&
    std::is_same_v<typename TImage::AccessorType, DefaultPixelAccessor<PixelType>> &&
    IsDefaultPixelAccessorFunctor<AccessorFunctorType>::value;
 
  // Tells whether or not this range is using a pointer as iterator.
  static constexpr bool UsingPointerAsIterator = SupportsDirectPixelAccess;
 
  struct EmptyAccessorFunctor
  {};
 
  using OptionalAccessorFunctorType =
    std::conditional_t<SupportsDirectPixelAccess, EmptyAccessorFunctor, AccessorFunctorType>;
 
  // PixelProxy: internal class that aims to act like a reference to a pixel:
  // It acts either like 'PixelType &' or like 'const PixelType &', depending
  // on its boolean template argument, VIsConst.
  // The proxy retrieves the pixel value using the AccessorFunctor from the image.
  // Note: the extra TDummy argument aims to fix AppleClang 6.0.0.6000056 error
  // "explicit specialization of 'PixelProxy'"and GCC 5.4.0 error "explicit
  // specialization in non-namespace scope".
  template <bool VIsConst, typename TDummy = void>
  class PixelProxy
  {};
 
  // PixelProxy specialization for const pixel types:
  // acts like 'const PixelType &'
  template <typename TDummy>
  class PixelProxy<true, TDummy> final
  {
  private:
    // Reference to the internal representation of the pixel, located in the image buffer.
    const InternalPixelType & m_InternalPixel;
 
    // The accessor functor of the image.
    const AccessorFunctorType m_AccessorFunctor;
 
  public:
    // Deleted member functions:
    PixelProxy() = delete;
    PixelProxy &
    operator=(const PixelProxy &) = delete;
 
    // Explicitly-defaulted member functions:
    PixelProxy(const PixelProxy &) noexcept = default;
    ~PixelProxy() = default;
 
    // Constructor, called directly by operator*() of the iterator class.
    PixelProxy(const InternalPixelType & internalPixel, const AccessorFunctorType & accessorFunctor) noexcept
      : m_InternalPixel{ internalPixel }
      , m_AccessorFunctor(accessorFunctor)
    {}
 
    // Allows implicit conversion from non-const to const proxy.
    PixelProxy(const PixelProxy<false> & pixelProxy) noexcept
      : m_InternalPixel{ pixelProxy.m_InternalPixel }
      , m_AccessorFunctor{ pixelProxy.m_AccessorFunctor }
    {}
 
    // Conversion operator.
    operator PixelType() const noexcept { return m_AccessorFunctor.Get(m_InternalPixel); }
  };
 
 
  // PixelProxy specialization for non-const pixel types:
  // acts like 'PixelType &'.
  template <typename TDummy>
  class PixelProxy<false, TDummy> final
  {
  private:
    // The const proxy is a friend, to ease implementing conversion from
    // a non-const proxy to a const proxy.
    friend class PixelProxy<true>;
 
    // Reference to the internal representation of the pixel, located in the image buffer.
    InternalPixelType & m_InternalPixel;
 
    // The accessor functor of the image.
    const AccessorFunctorType m_AccessorFunctor;
 
  public:
    // Deleted member functions:
    PixelProxy() = delete;
 
    // Explicitly-defaulted member functions:
    ~PixelProxy() = default;
    PixelProxy(const PixelProxy &) noexcept = default;
 
    // Constructor, called directly by operator*() of the iterator class.
    explicit PixelProxy(InternalPixelType & internalPixel, const AccessorFunctorType & accessorFunctor) noexcept
      : m_InternalPixel{ internalPixel }
      , m_AccessorFunctor(accessorFunctor)
    {}
 
    // Conversion operator.
    operator PixelType() const noexcept { return m_AccessorFunctor.Get(m_InternalPixel); }
 
    // Operator to assign a pixel value to the proxy.
    PixelProxy &
    operator=(const PixelType & pixelValue) noexcept
    {
      m_AccessorFunctor.Set(m_InternalPixel, pixelValue);
      return *this;
    }
 
    // Copy-assignment operator.
    PixelProxy &
    operator=(const PixelProxy & pixelProxy) noexcept
    {
      // Note that this assignment operator only copies the pixel value.
      // That is the normal behavior when a reference is assigned to another.
      const PixelType pixelValue = pixelProxy;
      *this = pixelValue;
      return *this;
    }
 
 
    friend void
    swap(PixelProxy lhs, PixelProxy rhs) noexcept
    {
      const auto lhsPixelValue = lhs.m_AccessorFunctor.Get(lhs.m_InternalPixel);
      const auto rhsPixelValue = rhs.m_AccessorFunctor.Get(rhs.m_InternalPixel);
 
      // Swap only the pixel values, not the image buffer pointers!
      lhs.m_AccessorFunctor.Set(lhs.m_InternalPixel, rhsPixelValue);
      rhs.m_AccessorFunctor.Set(rhs.m_InternalPixel, lhsPixelValue);
    }
  };
 

  template <bool VIsConst>
  class QualifiedIterator final
  {
  private:
    // Const and non-const iterators are friends, in order to implement the
    // constructor that allow conversion from non-const to const iterator.
    friend class QualifiedIterator<!VIsConst>;
 
    // ImageBufferRange is a friend, as it should be the only one that can
    // directly use the private constructor of the iterator.
    friend class ImageBufferRange;
 
    // Image type class that is either 'const' or non-const qualified, depending on QualifiedIterator and TImage.
    using QualifiedImageType = std::conditional_t<VIsConst, const TImage, TImage>;
 
    static constexpr bool IsImageTypeConst = std::is_const_v<QualifiedImageType>;
 
    using QualifiedInternalPixelType = std::conditional_t<IsImageTypeConst, const InternalPixelType, InternalPixelType>;
 
    // Pixel type class that is either 'const' or non-const qualified, depending on QualifiedImageType.
    using QualifiedPixelType = std::conditional_t<IsImageTypeConst, const PixelType, PixelType>;
 
 
    // Wraps a reference to a pixel.
    class PixelReferenceWrapper final
    {
    public:
      // Wraps the pixel reference that is specified by the first argument.
      // Note: the second parameter is unused, but it is there just to support
      // the use case of iterator::operator*(), which uses either
      // PixelReferenceWrapper or PixelProxy, interchangeable, in a generic way.
      // (PixelProxy has an explicit constructor for which the second parameter
      // is its essential AccessorFunctor parameter!)
      explicit PixelReferenceWrapper(QualifiedPixelType & pixel,
                                     EmptyAccessorFunctor itkNotUsed(accessorFunctor)) noexcept
        : m_Pixel(pixel)
      {}
 
      // Converts implicitly to a reference to the pixel.
      operator QualifiedPixelType &() const noexcept { return m_Pixel; }
 
    private:
      QualifiedPixelType & m_Pixel;
    };
 
 
    // QualifiedIterator data members (strictly private):
 
    // The accessor functor of the image.
    OptionalAccessorFunctorType m_OptionalAccessorFunctor;
 
    // Pointer to the current pixel.
    QualifiedInternalPixelType * m_InternalPixelPointer = nullptr;
 
    // Private constructor, used to create the begin and the end iterator of a range.
    // Only used by its friend class ImageBufferRange.
    QualifiedIterator(const OptionalAccessorFunctorType & accessorFunctor,
                      QualifiedInternalPixelType * const  internalPixelPointer) noexcept
      : // Note: Use parentheses instead of curly braces to initialize data members,
        // to avoid AppleClang 6.0.0.6000056 compilation error, "no viable conversion..."
      m_OptionalAccessorFunctor(accessorFunctor)
      , m_InternalPixelPointer{ internalPixelPointer }
    {}
 
  public:
    // Types conforming the iterator requirements of the C++ standard library:
    using difference_type = ptrdiff_t;
    using value_type = PixelType;
    using reference = std::conditional_t<SupportsDirectPixelAccess, QualifiedPixelType &, PixelProxy<IsImageTypeConst>>;
    using pointer = QualifiedPixelType *;
    using iterator_category = std::random_access_iterator_tag;
 

    QualifiedIterator() = default;

    template <bool VIsArgumentConst, typename = std::enable_if_t<VIsConst && !VIsArgumentConst>>
    QualifiedIterator(const QualifiedIterator<VIsArgumentConst> & arg) noexcept
      : // Note: Use parentheses instead of curly braces to initialize data members,
        // to avoid AppleClang 6.0.0.6000056 compilation error, "no viable conversion..."
      m_OptionalAccessorFunctor(arg.m_OptionalAccessorFunctor)
      , m_InternalPixelPointer{ arg.m_InternalPixelPointer }
    {}
 

    reference
    operator*() const noexcept
    {
      assert(m_InternalPixelPointer != nullptr);
 
      using PixelWrapper = std::conditional_t<SupportsDirectPixelAccess, PixelReferenceWrapper, reference>;
 
      return PixelWrapper{ *m_InternalPixelPointer, m_OptionalAccessorFunctor };
    }
 

    QualifiedIterator &
    operator++() noexcept
    {
      assert(m_InternalPixelPointer != nullptr);
      ++m_InternalPixelPointer;
      return *this;
    }
 

    QualifiedIterator
    operator++(int) noexcept
    {
      auto result = *this;
      ++(*this);
      return result;
    }
 

    QualifiedIterator &
    operator--() noexcept
    {
      assert(m_InternalPixelPointer != nullptr);
      --m_InternalPixelPointer;
      return *this;
    }
 

    QualifiedIterator
    operator--(int) noexcept
    {
      auto result = *this;
      --(*this);
      return result;
    }
 

    friend bool
    operator==(const QualifiedIterator & lhs, const QualifiedIterator & rhs) noexcept
    {
      return lhs.m_InternalPixelPointer == rhs.m_InternalPixelPointer;
    }
 

    friend bool
    operator!=(const QualifiedIterator & lhs, const QualifiedIterator & rhs) noexcept
    {
      // Implemented just like the corresponding std::rel_ops operator.
      return !(lhs == rhs);
    }
 

    friend bool
    operator<(const QualifiedIterator & lhs, const QualifiedIterator & rhs) noexcept
    {
      return lhs.m_InternalPixelPointer < rhs.m_InternalPixelPointer;
    }
 

    friend bool
    operator>(const QualifiedIterator & lhs, const QualifiedIterator & rhs) noexcept
    {
      // Implemented just like the corresponding std::rel_ops operator.
      return rhs < lhs;
    }
 

    friend bool
    operator<=(const QualifiedIterator & lhs, const QualifiedIterator & rhs) noexcept
    {
      // Implemented just like the corresponding std::rel_ops operator.
      return !(rhs < lhs);
    }
 

    friend bool
    operator>=(const QualifiedIterator & lhs, const QualifiedIterator & rhs) noexcept
    {
      // Implemented just like the corresponding std::rel_ops operator.
      return !(lhs < rhs);
    }
 

    friend QualifiedIterator &
    operator+=(QualifiedIterator & it, const difference_type n) noexcept
    {
      it.m_InternalPixelPointer += n;
      return it;
    }

    friend QualifiedIterator &
    operator-=(QualifiedIterator & it, const difference_type n) noexcept
    {
      it += (-n);
      return it;
    }

    friend difference_type
    operator-(const QualifiedIterator & lhs, const QualifiedIterator & rhs) noexcept
    {
      return lhs.m_InternalPixelPointer - rhs.m_InternalPixelPointer;
    }
 

    friend QualifiedIterator
    operator+(QualifiedIterator it, const difference_type n) noexcept
    {
      return it += n;
    }
 

    friend QualifiedIterator
    operator+(const difference_type n, QualifiedIterator it) noexcept
    {
      return it += n;
    }
 

    friend QualifiedIterator
    operator-(QualifiedIterator it, const difference_type n) noexcept
    {
      return it += (-n);
    }
 

    reference
    operator[](const difference_type n) const noexcept
    {
      return *(*this + n);
    }
  };
 
  static constexpr bool IsImageTypeConst = std::is_const_v<TImage>;
 
  using QualifiedInternalPixelType = std::conditional_t<IsImageTypeConst, const InternalPixelType, InternalPixelType>;
 
  class AccessorFunctorInitializer final
  {
  private:
    TImage & m_Image;
 
  public:
    explicit AccessorFunctorInitializer(TImage & image) noexcept
      : m_Image(image)
    {}
 
    operator EmptyAccessorFunctor() const noexcept { return {}; }
 
    operator AccessorFunctorType() const noexcept
    {
      AccessorFunctorType result = {};
      result.SetPixelAccessor(m_Image.GetPixelAccessor());
      result.SetBegin(m_Image.TImage::GetBufferPointer());
      return result;
    }
  };
 
 
  // Helper class for begin() and end(), to ease proper initialization of an
  // ImageBufferRange iterator (either a 'QualifiedIterator' or a raw pixel pointer).
  class IteratorInitializer final
  {
  private:
    OptionalAccessorFunctorType  m_OptionalAccessorFunctor;
    QualifiedInternalPixelType * m_InternalPixelPointer;
 
  public:
    explicit IteratorInitializer(OptionalAccessorFunctorType  optionalAccessorFunctor,
                                 QualifiedInternalPixelType * internalPixelPointer) noexcept
      : m_OptionalAccessorFunctor(optionalAccessorFunctor)
      , m_InternalPixelPointer(internalPixelPointer)
    {}
 
    // Converts to a 'QualifiedIterator' object.
    template <bool VIsConst>
    operator QualifiedIterator<VIsConst>() const noexcept
    {
      return QualifiedIterator<VIsConst>{ m_OptionalAccessorFunctor, m_InternalPixelPointer };
    }
 
    // Converts to a raw pixel pointer.
    operator QualifiedInternalPixelType *() const noexcept { return m_InternalPixelPointer; }
  };
 
 
  // ImageBufferRange data members (strictly private):
 
  // The accessor functor of the image.
  OptionalAccessorFunctorType m_OptionalAccessorFunctor;
 
  // Pointer to the buffer of the image.
  QualifiedInternalPixelType * m_ImageBufferPointer = nullptr;
 
  // Image size.
  SizeValueType m_NumberOfPixels = 0;
 
public:
  using const_iterator = std::conditional_t<UsingPointerAsIterator, const InternalPixelType *, QualifiedIterator<true>>;
  using iterator =
    std::conditional_t<UsingPointerAsIterator, QualifiedInternalPixelType *, QualifiedIterator<IsImageTypeConst>>;
  using reverse_iterator = std::reverse_iterator<iterator>;
  using const_reverse_iterator = std::reverse_iterator<const_iterator>;
 

  ImageBufferRange() = default;
 

  explicit ImageBufferRange(TImage & image)
    : // Note: Use parentheses instead of curly braces to initialize data members,
      // to avoid AppleClang 6.0.0.6000056 compile errors, "no viable conversion..."
    m_OptionalAccessorFunctor(AccessorFunctorInitializer{ image })
    , m_ImageBufferPointer{ image.TImage::GetBufferPointer() }
    , m_NumberOfPixels{ image.TImage::GetBufferedRegion().GetNumberOfPixels() }
  {}
 

  [[nodiscard]] iterator
  begin() const noexcept
  {
    return IteratorInitializer{ m_OptionalAccessorFunctor, m_ImageBufferPointer };
  }

  [[nodiscard]] iterator
  end() const noexcept
  {
    return IteratorInitializer{
      m_OptionalAccessorFunctor,
      m_ImageBufferPointer + m_NumberOfPixels,
    };
  }

  [[nodiscard]] const_iterator
  cbegin() const noexcept
  {
    return this->begin();
  }

  [[nodiscard]] const_iterator
  cend() const noexcept
  {
    return this->end();
  }

  [[nodiscard]] reverse_iterator
  rbegin() const noexcept
  {
    return reverse_iterator(this->end());
  }

  [[nodiscard]] reverse_iterator
  rend() const noexcept
  {
    return reverse_iterator(this->begin());
  }

  [[nodiscard]] const_reverse_iterator
  crbegin() const noexcept
  {
    return this->rbegin();
  }

  [[nodiscard]] const_reverse_iterator
  crend() const noexcept
  {
    return this->rend();
  }
 

  [[nodiscard]] size_t
  size() const noexcept
  {
    return m_NumberOfPixels;
  }
 

  [[nodiscard]] bool
  empty() const noexcept
  {
    return m_NumberOfPixels == 0;
  }
 

  typename QualifiedIterator<false>::reference
  operator[](const size_t n) const noexcept
  {
    assert(n < this->size());
    assert(n <= static_cast<size_t>(std::numeric_limits<ptrdiff_t>::max()));
 
    return this->begin()[static_cast<ptrdiff_t>(n)];
  }
};
 
 
// Deduction guide to avoid compiler warnings (-wctad-maybe-unsupported) when using class template argument deduction.
template <typename TImage>
ImageBufferRange(TImage &) -> ImageBufferRange<TImage>;
 

template <typename TImage>
ImageBufferRange<TImage>
MakeImageBufferRange(TImage * const image)
{
  if (image == nullptr)
  {
    return {};
  }
 
  return ImageBufferRange<TImage>{ *image };
}
 
 
} // namespace itk
#endif