#include <SphericalAccumulator.h>

Collaboration diagram for DGtal::SphericalAccumulator< TVector >:

Public Types
typedef TVector	Vector
typedef DGtal::int32_t	Quantity
typedef DGtal::uint32_t	Size
typedef std::vector< Quantity > ::const_iterator	ConstIterator
typedef PointVector< 3, double >	RealVector

Public Member Functions
	BOOST_STATIC_ASSERT (Vector::dimension==3)
	SphericalAccumulator (const Size aNphi)
	~SphericalAccumulator ()
void	addDirection (const Vector &aDir)
void	binCoordinates (const Vector &aDir, Size &posPhi, Size &posTheta) const
Quantity	count (const Size &posPhi, const Size &posTheta) const
Vector	representativeDirection (const Size &posPhi, const Size &posTheta) const
Vector	representativeDirection (ConstIterator &it) const
Quantity	samples () const
Quantity	binNumber () const
void	maxCountBin (Size &posPhi, Size &posTheta) const
void	clear ()
void	selfDisplay (std::ostream &out) const
bool	isValid () const
std::string	className () const
bool	isValidBin (const Size &posPhi, const Size &posTheta) const
void	getBinGeometry (const Size &posPhi, const Size &posTheta, RealVector &a, RealVector &b, RealVector &c, RealVector &d) const
ConstIterator	begin () const
ConstIterator	end () const
void	binCoordinates (ConstIterator &aDir, Size &posPhi, Size &posTheta) const

Protected Member Functions
	SphericalAccumulator ()

Private Member Functions
	SphericalAccumulator (const SphericalAccumulator &other)
SphericalAccumulator &	operator= (const SphericalAccumulator &other)

Private Attributes
Size	myNphi
Size	myNtheta
std::vector< Quantity >	myAccumulator
std::vector< Vector >	myAccumulatorDir
Quantity	myTotal
Quantity	myBinNumber
Size	myMaxBinPhi
Size	myMaxBinTheta

Detailed Description

template<typename TVector>
class DGtal::SphericalAccumulator< TVector >

Aim: implements an accumulator (as histograms for 1D scalars) adapted to spherical point samples.

Description of template class 'SphericalAccumulator'

Spherical accumulator is decomposed into 2D bins (i,j) such that:

each direction/point on the unit sphere falls in a single bin
each bin almost cover the same area on the unit sphere
each bin have a geometrical support which can be represented as a quad except for its two poles

Compared to exact geodesic covering, such spherical accumulator bins do not have the exact same area. However, it allows fast conversion between directions and bin coordinates.

Such accumulator have been demonstrated in: Borrmann, D., Elseberg, J., & Lingemann, K. (2011). The 3D Hough Transform for plane detection in point clouds: A review and a new accumulator design. 3D Research, 02003. Retrieved from http://www.springerlink.com/index/N1W040850782VR85.pdf

Usage example:

typedef Z3i::RealVector Vector;

SphericalAccumulator<Vector> accumulator(6);

  //Insert some directions
  accumulator.addDirection( Vector(0,1,0));
  accumulator.addDirection( Vector(1,-0.01,0));
  accumulator.addDirection( Vector(1,0.01,-0.01));
  accumulator.addDirection( Vector(1,-0.01,0.01));

Once the accumulator is filled up with directions, you can get the representative direction for each bin and the bin with maximal number of samples.

Furthermore, you can send the accumulator to a Viewer3D to see the bin geometry and values:

     ...
     Viewer3D viewer;
     viewer << accumulator;
     ...

See also:: testSphericalAccumulator.cpp

Template Parameters:

TVector type used to represent directions.

Definition at line 101 of file SphericalAccumulator.h.

Member Typedef Documentation

template<typename TVector>

typedef std::vector<Quantity>::const_iterator DGtal::SphericalAccumulator< TVector >::ConstIterator

Type to iterate on bin values.

Definition at line 116 of file SphericalAccumulator.h.

template<typename TVector>

typedef DGtal::int32_t DGtal::SphericalAccumulator< TVector >::Quantity

Type to store the bin counts.

Definition at line 110 of file SphericalAccumulator.h.

template<typename TVector>

typedef PointVector<3,double> DGtal::SphericalAccumulator< TVector >::RealVector

Type to represent normalized vector (internal use).

Definition at line 119 of file SphericalAccumulator.h.

template<typename TVector>

typedef DGtal::uint32_t DGtal::SphericalAccumulator< TVector >::Size

Type to represent bin indexes.

Definition at line 113 of file SphericalAccumulator.h.

template<typename TVector>

typedef TVector DGtal::SphericalAccumulator< TVector >::Vector

Vector direction types.

Definition at line 107 of file SphericalAccumulator.h.

Constructor & Destructor Documentation

template<typename T >

DGtal::SphericalAccumulator< T >::SphericalAccumulator ( const Size aP )

inline

Constructs a spherical accumulator with aNphi slices along latitudes (phi spherial coordinate). The decomposition along the theta axis is also a function of aNphi.

Parameters:

aNphi the number of slices in the longitude polar coordinates.

Constructor.

Definition at line 46 of file SphericalAccumulator.ih.

References M_PI.

{
  myTotal = 0;
  myNphi = aP;
  myNtheta = 2*myNphi;
  myAccumulator.resize(myNphi*myNtheta,0);
  myAccumulatorDir.resize(myNphi*myNtheta, Vector::zero);
  myBinNumber = 0;
  myMaxBinTheta = 0;
  myMaxBinPhi= 0;
  for(Size posPhi=0; posPhi < myNphi; posPhi++)
    for(Size posTheta=0; posTheta < myNtheta; posTheta++)
      {
        double dphi = M_PI/((double)myNphi-1);
        double Ntheta_i = floor(2.0*((double)myNphi)*sin((double)posPhi*dphi)) ;  
        
        if (((posPhi == 0) || (posPhi == (myNphi-1))) && (posTheta==0))
          myBinNumber++;
        else
          if ((posPhi < myNphi) && (posTheta<Ntheta_i) && (posTheta< myNtheta))
            myBinNumber ++;
      }
}

template<typename T >

DGtal::SphericalAccumulator< T >::~SphericalAccumulator ( )

inline

Destructor.

Definition at line 77 of file SphericalAccumulator.ih.

{

}

template<typename TVector>

DGtal::SphericalAccumulator< TVector >::SphericalAccumulator ( )

protected

Constructor. Forbidden by default (protected to avoid g++ warnings).

template<typename TVector>

DGtal::SphericalAccumulator< TVector >::SphericalAccumulator ( const SphericalAccumulator< TVector > & other )

private

Copy constructor.

Parameters:

other the object to clone. Forbidden by default.

Member Function Documentation

template<typename T >

void DGtal::SphericalAccumulator< T >::addDirection ( const Vector & aDir )

inline

Add a new direction into the accumulator. The accumulator updates the bin coordinates with maximum count.

Parameters:

aDir	a direction

Definition at line 123 of file SphericalAccumulator.ih.

{
  Size posPhi,posTheta;
 
  binCoordinates(aDir , posPhi, posTheta);
  myAccumulator[posTheta + posPhi*myNtheta] += 1;
  myAccumulatorDir[posTheta + posPhi*myNtheta] += aDir;
  myTotal ++;
  
  //Max bin update
  if (  myAccumulator[posTheta + posPhi*myNtheta] >
        myAccumulator[ myMaxBinTheta  + myMaxBinPhi*myNtheta])
    {
      myMaxBinTheta = posTheta;
      myMaxBinPhi = posPhi;
    }
}

template<typename TVector>

ConstIterator DGtal::SphericalAccumulator< TVector >::begin ( ) const

inline

Warning:: Be careful, some of the iterators may be attached to un-valid bins. Once you have the iterator, convert it to bin coordinates using binCoordinates and then check if the bin is valid using isValidBin method.

Returns:: an iterator on the bin value container (begin).

Definition at line 296 of file SphericalAccumulator.h.

References DGtal::SphericalAccumulator< TVector >::myAccumulator.

Referenced by DGtal::Display3DFactory::draw().

    {
      return myAccumulator.begin();
    }

template<typename T >

void DGtal::SphericalAccumulator< T >::binCoordinates	(	const Vector &	aDir,
		Size &	posPhi,
		Size &	posTheta
	)		const

inline

Given a normalized direction, this method computes the bin coordinates.

Precondition:: aDir a direction.

Parameters:

aDir	a direction represented as a unit norm vector.
posPhi	position according to the first direction.
posTheta	position according to the second direction.

Definition at line 83 of file SphericalAccumulator.ih.

References M_PI.

Referenced by DGtal::Display3DFactory::draw().

{
  double theta,phi;
  double norm = aDir.norm();
  
  ASSERT(norm != 0);
  phi = acos(NumberTraits<typename T::Component>::castToDouble(aDir[2])/norm);
  
  double dphi = M_PI/(double)(myNphi-1);
  double Nthetai;
  posPhi = static_cast<Size>(floor( (phi+dphi/2.) *(myNphi-1)/  M_PI));
  if(posPhi == 0 || posPhi== (myNphi-1))
    {
      posTheta =0;
    }
  else
    {
      theta=atan2(NumberTraits<typename T::Component>::castToDouble(aDir[1]),
                  NumberTraits<typename T::Component>::castToDouble(aDir[0]));
 
      if(aDir[1]<0)
        theta += 2.0*M_PI;
      
      Nthetai = floor(2.0*(myNphi)*sin(posPhi*dphi));
      double dtheta = 2.0*M_PI/(Nthetai);
      posTheta = static_cast<Size>(floor( (theta+dtheta/2.0)/dtheta));
      
      if (posTheta >= Nthetai)
        posTheta -= Nthetai;
    }
  
  ASSERT(posPhi < myNphi);
  ASSERT( isValidBin(posPhi,posTheta) );
}

template<typename T >

void DGtal::SphericalAccumulator< T >::binCoordinates	(	ConstIterator &	aDir,
		Size &	posPhi,
		Size &	posTheta
	)		const

inline

Given an iterator on the bin container, this method computes the bin coordinates.

Parameters:

aIt	an iterator to the bin container.
posPhi	position according to the first direction.
posTheta	position according to the second direction.

Definition at line 193 of file SphericalAccumulator.ih.

{
  Size dist = it - myAccumulator.begin();
  posPhi = dist/ myNtheta;
  posTheta = dist % myNtheta;
}

template<typename TVector>

Quantity DGtal::SphericalAccumulator< TVector >::binNumber ( ) const

inline

Returns:: returns the number of bins in the accumulator.

Definition at line 216 of file SphericalAccumulator.h.

References DGtal::SphericalAccumulator< TVector >::myBinNumber.

{ return myBinNumber;}

template<typename TVector>

DGtal::SphericalAccumulator< TVector >::BOOST_STATIC_ASSERT ( Vector::dimension = =3 )

template<typename TVector>

std::string DGtal::SphericalAccumulator< TVector >::className ( ) const

inline

Returns:: the class name.

Definition at line 251 of file SphericalAccumulator.h.

    {
      return "SphericalAccumulator";
    }

template<typename T >

void DGtal::SphericalAccumulator< T >::clear ( )

inline

Clear the current accumulator.

Definition at line 271 of file SphericalAccumulator.ih.

{
  myTotal = 0;
  for(Size i=0; i < myNphi; i++)
    for(Size j=0; j < myNtheta; j++)
      if (isValidBin(i,j))
        myAccumulator[j + i*myNtheta]=0;
      else
        myAccumulator[j+ i*myNtheta]=-1;
      
  std::fill(myAccumulatorDir.begin(), myAccumulatorDir.end(), Vector::zero);
}

template<typename T >

DGtal::SphericalAccumulator< T >::Quantity DGtal::SphericalAccumulator< T >::count	(	const Size &	posPhi,
		const Size &	posTheta
	)		const

inline

Returns the current number of samples in the bin (posPhi,posTheta).

Parameters:

posPhi	position according to the first direction
posTheta	position according to the second direction

Returns:: the number of accumulated samples

Definition at line 161 of file SphericalAccumulator.ih.

Referenced by DGtal::Display3DFactory::draw().

{
  ASSERT( isValidBin(posPhi,posTheta) );
  return myAccumulator[posTheta + posPhi*myNtheta];
}

template<typename TVector>

ConstIterator DGtal::SphericalAccumulator< TVector >::end ( ) const

inline

Returns:: an iterator on the bin value container (end).

Definition at line 304 of file SphericalAccumulator.h.

References DGtal::SphericalAccumulator< TVector >::myAccumulator.

Referenced by DGtal::Display3DFactory::draw().

    {
      return myAccumulator.end();
    }

template<typename T >

void DGtal::SphericalAccumulator< T >::getBinGeometry	(	const Size &	posPhi,
		const Size &	posTheta,
		RealVector &	a,
		RealVector &	b,
		RealVector &	c,
		RealVector &	d
	)		const

inline

From the bin index(posPhi,posTheta), we compute the associated spherical quad (a,b,c,d) counterclockwise on the unit sphere.

Parameters:

posPhi	bin index along the first direction.
posTheta	bin index along the second direction.
a	vertex position.
b	vertex position.
c	vertex position.
d	vertex position.

Definition at line 220 of file SphericalAccumulator.ih.

References M_PI.

Referenced by DGtal::Display3DFactory::draw().

{
  ASSERT( isValidBin(posPhi,posTheta) );
  double dphi = M_PI/(double)((double)myNphi-1);
  double phi= (double)posPhi*dphi;
  double dtheta;
  double Nthetai = floor(2.0*(myNphi)*sin(phi) ); 
  
  dtheta = 2.0*M_PI/(Nthetai);
  
  double theta=posTheta*dtheta;
  a[0]=cos(theta-dtheta/2.0)*sin(phi -dphi/2.0);
  a[1]=sin(theta-dtheta/2.0)*sin(phi -dphi/2.0);
  a[2]=cos(phi -dphi/2.0);
  
  
  if ((double)posTheta -1 >= Nthetai)
    {
      b[0]=cos(-dtheta/2.0)*sin(phi -dphi/2.0);
      b[1]=sin(-dtheta/2.0)*sin(phi -dphi/2.0);
      b[2]=cos(phi -dphi/2.0);
      
      c[0]=cos(- dtheta/2.0)*sin(phi+dphi/2.0);
      c[1]=sin( - dtheta/2.0)*sin(phi+dphi/2.0);
      c[2]=cos(phi+dphi/2.0);      
    }
  else
    {
      b[0]=cos(theta+dtheta/2.0)*sin(phi -dphi/2.0);
      b[1]=sin(theta+dtheta/2.0)*sin(phi -dphi/2.0);
      b[2]=cos(phi -dphi/2.0);
      
      c[0]=cos(theta+dtheta/2.0)*sin(phi+dphi/2.0);
      c[1]=sin(theta+dtheta/2.0)*sin(phi+dphi/2.0);
      c[2]=cos(phi+dphi/2.0);      
    }
  
  d[0]=cos(theta-dtheta/2.0)*sin(phi+dphi/2.0);
  d[1]=sin(theta-dtheta/2.0)*sin(phi+dphi/2.0);
  d[2]=cos(phi+dphi/2.0);      
}

template<typename T >

bool DGtal::SphericalAccumulator< T >::isValid ( ) const

inline

Checks the validity/consistency of the object.

Returns:: 'true' if the object is valid, 'false' otherwise.

Definition at line 309 of file SphericalAccumulator.ih.

{
    return true;
}

template<typename T >

bool DGtal::SphericalAccumulator< T >::isValidBin	(	const Size &	posPhi,
		const Size &	posTheta
	)		const

inline

Returns true if is bin (posPhi,posTheta) is valid.

Parameters:

posPhi
posTheta

Returns:: true if (posPhi,posTheta) is valid.

Definition at line 205 of file SphericalAccumulator.ih.

References M_PI.

Referenced by DGtal::Display3DFactory::draw().

{
  double dphi = M_PI/((double)myNphi-1.0);
  double Ntheta_i = floor(2.0*((double)myNphi)*sin((double)posPhi*dphi));  
  
  if ((posPhi == 0) || (posPhi == (myNphi-1)))
    return (posTheta==0);
  else
    return (posPhi < myNphi) && (posTheta<Ntheta_i) && (posTheta< myNtheta);
}

template<typename T >

void DGtal::SphericalAccumulator< T >::maxCountBin	(	Size &	posPhi,
		Size &	posTheta
	)		const

inline

Returns the coordinates of the bin containing the maximum number of samples.

Parameters:

posPhi	coordinate along the phi axis.
posTheta	coordinate along the theta axis.

Definition at line 152 of file SphericalAccumulator.ih.

{
  phi = myMaxBinPhi;
  theta = myMaxBinTheta;
}

template<typename TVector>

SphericalAccumulator& DGtal::SphericalAccumulator< TVector >::operator= ( const SphericalAccumulator< TVector > & other )

private

Assignment.

Parameters:

other the object to copy.

Returns:: a reference on 'this'. Forbidden by default.

template<typename T >

T DGtal::SphericalAccumulator< T >::representativeDirection	(	const Size &	posPhi,
		const Size &	posTheta
	)		const

inline

Returns the representative direction associated with the bin (posPhi,posTheta). If the bin does not contain any sample, a null vector is returned ( Vector::ZERO ).

Otherwise, it returns the (unnormalized) sum of directions added to the bin.

Parameters:

posPhi	position according to the first direction
posTheta	position according to the second direction

Returns:: the representative direction.

Definition at line 171 of file SphericalAccumulator.ih.

{
  ASSERT( isValidBin(posPhi,posTheta) );
  Vector p=myAccumulatorDir[posTheta + posPhi*myNtheta] ;
  return p;
}

template<typename T >

T DGtal::SphericalAccumulator< T >::representativeDirection ( ConstIterator & it ) const

inline

Get the representative direction of a bin specified by a ConstIterator.

Parameters:

it	the iterator on the bin to get the direction

Returns:: the representative direction of bin it.

Definition at line 182 of file SphericalAccumulator.ih.

{
  Size dist = it - myAccumulator.begin();
  Vector p = *(myAccumulatorDir.begin() + dist);
  return p;
}

template<typename T >

DGtal::SphericalAccumulator< T >::Quantity DGtal::SphericalAccumulator< T >::samples ( ) const

inline

Returns:: returns the number of directions in the current accumulator.

Definition at line 144 of file SphericalAccumulator.ih.

{
  return myTotal;
}

template<typename T >

void DGtal::SphericalAccumulator< T >::selfDisplay ( std::ostream & out ) const

inline

Writes/Displays the object on an output stream.

Parameters:

out	the output stream where the object is written.

Definition at line 295 of file SphericalAccumulator.ih.

{
  out << "[SphericalAccumulator] Nphi="<<myNphi<<"  Ntheta=" <<myNtheta
      <<"  Number of samples="<<myTotal
      <<"  Number of bins="<<myBinNumber;
}