itkHistogram.h

Go to the documentation of this file.

/*=========================================================================
 *
 *  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 __itkHistogram_h
#define __itkHistogram_h

#include <vector>

#include "itkArray.h"
#include "itkSample.h"
#include "itkDenseFrequencyContainer2.h"
#include "itkSparseFrequencyContainer2.h"

namespace itk
{
namespace Statistics
{
template< typename THistogram >
struct GetHistogramDimension {
  itkStaticConstMacro(HistogramDimension, unsigned int, THistogram::MeasurementVectorSize);
};

template< class TMeasurement = float,
          class TFrequencyContainer = DenseFrequencyContainer2 >
class ITK_EXPORT Histogram:
  public Sample< Array< TMeasurement > >
{
public:

  // This type serves as the indirect definition of MeasurementVectorType
  typedef Array< TMeasurement > ArrayType;

  typedef Histogram                  Self;
  typedef Sample< ArrayType  >       Superclass;
  typedef SmartPointer< Self >       Pointer;
  typedef SmartPointer< const Self > ConstPointer;

  itkTypeMacro(Histogram, Sample);

  itkNewMacro(Self);

  typedef TMeasurement MeasurementType;

  typedef typename Superclass::MeasurementVectorType      MeasurementVectorType;
  typedef typename Superclass::InstanceIdentifier         InstanceIdentifier;
  typedef typename Superclass::MeasurementVectorSizeType  MeasurementVectorSizeType;

  typedef MeasurementVectorType ValueType;

  typedef TFrequencyContainer                      FrequencyContainerType;
  typedef typename FrequencyContainerType::Pointer FrequencyContainerPointer;

  typedef typename FrequencyContainerType::AbsoluteFrequencyType      AbsoluteFrequencyType;
  typedef typename FrequencyContainerType::TotalAbsoluteFrequencyType TotalAbsoluteFrequencyType;
  typedef typename FrequencyContainerType::RelativeFrequencyType      RelativeFrequencyType;
  typedef typename FrequencyContainerType::TotalRelativeFrequencyType TotalRelativeFrequencyType;

  typedef Array< ::itk::IndexValueType > IndexType;
  typedef typename IndexType::ValueType  IndexValueType;

  typedef Array< ::itk::SizeValueType > SizeType;
  typedef typename SizeType::ValueType  SizeValueType;

  typedef std::vector< MeasurementType >  BinMinVectorType;
  typedef std::vector< MeasurementType >  BinMaxVectorType;
  typedef std::vector< BinMinVectorType > BinMinContainerType;
  typedef std::vector< BinMaxVectorType > BinMaxContainerType;

  void Initialize(const SizeType & size);

  void Initialize(const SizeType & size, MeasurementVectorType & lowerBound,
                  MeasurementVectorType & upperBound);

  void SetToZero();

  itkLegacyMacro(const IndexType & GetIndex(const MeasurementVectorType & measurement) const);

  bool GetIndex(const MeasurementVectorType & measurement,
                IndexType & index) const;

  const IndexType & GetIndex(InstanceIdentifier id) const;

  itkGetConstMacro(ClipBinsAtEnds, bool);

  itkSetMacro(ClipBinsAtEnds, bool);

  bool IsIndexOutOfBounds(const IndexType & index) const;

  InstanceIdentifier GetInstanceIdentifier(const IndexType & index) const;

  InstanceIdentifier Size() const;

  const SizeType & GetSize() const;

  SizeValueType GetSize(unsigned int dimension) const;

  const MeasurementType & GetBinMin(unsigned int dimension,
                                    InstanceIdentifier nbin) const;

  const MeasurementType & GetBinMax(unsigned int dimension,
                                    InstanceIdentifier nbin) const;

  void SetBinMin(unsigned int dimension, InstanceIdentifier nbin,
                 MeasurementType min);

  void SetBinMax(unsigned int dimension,
                 InstanceIdentifier nbin, MeasurementType max);

  const MeasurementType & GetBinMinFromValue(unsigned int dimension,
                                             float value) const;

  const MeasurementType & GetBinMaxFromValue(unsigned int dimension,
                                             float value) const;

  const BinMinVectorType & GetDimensionMins(unsigned int dimension) const;

  const BinMaxVectorType & GetDimensionMaxs(unsigned int dimension) const;

  const BinMinContainerType & GetMins() const;

  const BinMaxContainerType & GetMaxs() const;

  const MeasurementVectorType & GetHistogramMinFromIndex(const IndexType & index) const;

  const MeasurementVectorType & GetHistogramMaxFromIndex(const IndexType & index) const;

  AbsoluteFrequencyType GetFrequency(InstanceIdentifier id) const;

  AbsoluteFrequencyType GetFrequency(const IndexType & index) const;

  void SetFrequency(AbsoluteFrequencyType value);

  bool SetFrequency(InstanceIdentifier id, AbsoluteFrequencyType value);

  bool SetFrequencyOfIndex(const IndexType & index,
                    AbsoluteFrequencyType value);

  bool SetFrequencyOfMeasurement(const MeasurementVectorType & measurement,
                                  AbsoluteFrequencyType value);

  bool IncreaseFrequency(InstanceIdentifier id, AbsoluteFrequencyType value);

  bool IncreaseFrequencyOfIndex(const IndexType & index,
                                 AbsoluteFrequencyType value);

  bool IncreaseFrequencyOfMeasurement(
         const MeasurementVectorType & measurement,
         AbsoluteFrequencyType value);
#ifdef ITKV3_COMPATIBILITY
  //In ITKv4 the member functions are given unique names to dis-ambiguate
  //the intended behavior.  Make aliases of the overloaded calls
  //for ITKv3 backwards compatibility.
  bool IncreaseFrequency(const IndexType & index,
                                 AbsoluteFrequencyType value)
    {
    return IncreaseFrequencyOfIndex(index,value);
    }

  bool IncreaseFrequency(
         const MeasurementVectorType & measurement,
         AbsoluteFrequencyType value)
    {
    return IncreaseFrequencyOfMeasurement(measurement,value);
    }

#endif

  const MeasurementVectorType & GetMeasurementVector(InstanceIdentifier id) const;

  const MeasurementVectorType & GetMeasurementVector(const IndexType & index) const;

  MeasurementType GetMeasurement(InstanceIdentifier n,
                                 unsigned int dimension) const;

  TotalAbsoluteFrequencyType GetTotalFrequency() const;

  AbsoluteFrequencyType GetFrequency(InstanceIdentifier n,
                                     unsigned int dimension) const;

  double Quantile(unsigned int dimension, double p) const;

  double Mean(unsigned int dimension) const;

  virtual void Graft(const DataObject *);

protected:
  void PrintSelf(std::ostream & os, Indent indent) const;

public:

  class ConstIterator
  {
public:

    friend class Histogram;

    ConstIterator(const Self *histogram)
    {
      m_Id = 0;
      m_Histogram = histogram;
    }

    ConstIterator(const ConstIterator & it)
    {
      m_Id        = it.m_Id;
      m_Histogram = it.m_Histogram;
    }

    ConstIterator & operator=(const ConstIterator & it)
    {
      m_Id  = it.m_Id;
      m_Histogram = it.m_Histogram;
      return *this;
    }

    AbsoluteFrequencyType GetFrequency() const
    {
      return m_Histogram->GetFrequency(m_Id);
    }

    InstanceIdentifier GetInstanceIdentifier() const
    {
      return m_Id;
    }

    const MeasurementVectorType & GetMeasurementVector() const
    {
      return m_Histogram->GetMeasurementVector(m_Id);
    }

    const IndexType & GetIndex() const
    {
      return m_Histogram->GetIndex(m_Id);
    }

    ConstIterator & operator++()
    {
      ++m_Id;
      return *this;
    }

    bool operator!=(const ConstIterator & it)
    {
      return ( m_Id != it.m_Id );
    }

    bool operator==(const ConstIterator & it)
    {
      return ( m_Id == it.m_Id );
    }

protected:
    // This method is purposely not implemented
    ConstIterator();

    ConstIterator(InstanceIdentifier id, const Self *histogram):
      m_Id(id), m_Histogram(histogram)
    {}

    // ConstIterator pointing DenseFrequencyContainer
    InstanceIdentifier m_Id;

    // Pointer of DenseFrequencyContainer
    const Self *m_Histogram;
  };   // end of iterator class

  class Iterator:public ConstIterator
  {
public:

    Iterator(Self *histogram):ConstIterator(histogram)
    {}

    Iterator(InstanceIdentifier id, Self *histogram):
      ConstIterator(id, histogram)
    {}

    Iterator(const Iterator & it):ConstIterator(it)
    {}

    Iterator & operator=(const Iterator & it)
    {
      this->ConstIterator::operator=(it);
      return *this;
    }

    bool SetFrequency(const AbsoluteFrequencyType value)
    {
      Self *histogram = const_cast< Self * >( this->m_Histogram );

      return histogram->SetFrequency(this->m_Id, value);
    }

protected:
    // To ensure const-correctness these method must not be in the public API.
    // The are purposly not implemented, since they should never be called.
    Iterator();
    Iterator(const Self *histogram);
    Iterator(InstanceIdentifier id, const Self *histogram);
    Iterator(const ConstIterator & it);
    ConstIterator & operator=(const ConstIterator & it);

private:
  };   // end of iterator class

  Iterator  Begin()
  {
    Iterator iter(0, this);

    return iter;
  }

  Iterator  End()
  {
    return Iterator(m_OffsetTable[this->GetMeasurementVectorSize()], this);
  }

  ConstIterator  Begin() const
  {
    ConstIterator iter(0, this);

    return iter;
  }

  ConstIterator End() const
  {
    return ConstIterator(m_OffsetTable[this->GetMeasurementVectorSize()], this);
  }

protected:
  Histogram();
  virtual ~Histogram() {}

  // The number of bins for each dimension
  SizeType m_Size;
private:
  Histogram(const Self &);      //purposely not implemented
  void operator=(const Self &); //purposely not implemented

  typedef std::vector< InstanceIdentifier > OffsetTableType;
  OffsetTableType           m_OffsetTable;
  FrequencyContainerPointer m_FrequencyContainer;
  unsigned int              m_NumberOfInstances;

  // This method is provided here just to avoid a "hidden" warning
  // related to the virtual method available in DataObject.
  virtual void Initialize() {}

  // lower bound of each bin
  std::vector< std::vector< MeasurementType > > m_Min;

  // upper bound of each bin
  std::vector< std::vector< MeasurementType > > m_Max;

  mutable MeasurementVectorType m_TempMeasurementVector;
  mutable IndexType             m_TempIndex;

  bool m_ClipBinsAtEnds;
};
} // end of namespace Statistics
} // end of namespace itk

#ifndef ITK_MANUAL_INSTANTIATION
#include "itkHistogram.hxx"
#endif

#endif