Files Class List
WeightedSampleElimination< PointType, FType, DIMENSIONS, SIZE_TYPE > Class Template Reference

Detailed Description

template<typename PointType, typename FType, int DIMENSIONS, typename SIZE_TYPE = size_t>
class cy::WeightedSampleElimination< PointType, FType, DIMENSIONS, SIZE_TYPE >

An implementation of the weighted sample elimination method.

Cem Yuksel. 2015. Sample Elimination for Generating Poisson Disk Sample Sets. Computer Graphics Forum 34, 2 (May 2015), 25-32. http://www.cemyuksel.com/research/sampleelimination/

This class keeps a number of parameters for the weighted sample elimination algorithm. The main algorithm is implemented in the Eliminate method.

#include <cySampleElim.h>

Public Member Functions

 WeightedSampleElimination ()
 
void SetTiling (bool on=true)
 
bool IsTiling () const
 
void SetWeightLimiting (bool on=true)
 
bool IsWeightLimiting () const
 
const PointType & GetBoundsMin () const
 
const PointType & GetBoundsMax () const
 
void SetBoundsMin (const PointType &bmin)
 
void SetBoundsMax (const PointType &bmax)
 
void SetParamAlpha (FType a)
 
FType GetParamAlpha () const
 
void SetParamBeta (FType b)
 
FType GetParamBeta () const
 
void SetParamGamma (FType c)
 
FType GetParamGamma () const
 
template<typename WeightFunction >
void Eliminate (const PointType *inputPoints, SIZE_TYPE inputSize, PointType *outputPoints, SIZE_TYPE outputSize, bool progressive, FType d_max, int dimensions, WeightFunction weightFunction) const
 
void Eliminate (const PointType *inputPoints, SIZE_TYPE inputSize, PointType *outputPoints, SIZE_TYPE outputSize, bool progressive=false, FType d_max=FType(0), int dimensions=DIMENSIONS) const
 
FType GetMaxPoissonDiskRadius (int dimensions, SIZE_TYPE sampleCount, FType domainSize=0) const
 

Constructor & Destructor Documentation

§ WeightedSampleElimination()

The constructor sets the default parameters.

Member Function Documentation

§ SetTiling()

void SetTiling ( bool  on = true)

Tiling determines whether the generated samples are tile-able. Tiling is off by default, but it is a good idea to turn it on for box-shaped sampling domains. Note that when tiling is off, weighted sample elimination is less likely to eliminate samples near the boundaries of the sampling domain. If you turn on tiling, make sure to set the correct boundaries for the sampling domain.

§ IsTiling()

bool IsTiling ( ) const

Returns true if the tiling parameter is turned on.

§ SetWeightLimiting()

void SetWeightLimiting ( bool  on = true)

Weight limiting is used by the default weight function and it is on by default. Using weight limiting typically leads to more pronounced blue noise characteristics; therefore, it is recommended. The beta parameter determines the amount of weight limiting. Setting the beta parameter to zero effectively turns off weight limiting.

§ IsWeightLimiting()

bool IsWeightLimiting ( ) const

Returns true if weight limiting is turned on.

§ GetBoundsMin()

const PointType& GetBoundsMin ( ) const

Returns the minimum bounds of the sampling domain. The sampling domain boundaries are used for tiling and computing the maximum possible Poisson disk radius for the sampling domain. The default boundaries are between 0 and 1.

§ GetBoundsMax()

const PointType& GetBoundsMax ( ) const

Returns the maximum bounds of the sampling domain. The sampling domain boundaries are used for tiling and computing the maximum possible Poisson disk radius for the sampling domain. The default boundaries are between 0 and 1.

§ SetBoundsMin()

void SetBoundsMin ( const PointType &  bmin)

Sets the minimum bounds of the sampling domain. The sampling domain boundaries are used for tiling and computing the maximum possible Poisson disk radius for the sampling domain. The default boundaries are between 0 and 1.

§ SetBoundsMax()

void SetBoundsMax ( const PointType &  bmax)

Sets the maximum bounds of the sampling domain. The sampling domain boundaries are used for tiling and computing the maximum possible Poisson disk radius for the sampling domain. The default boundaries are between 0 and 1.

§ SetParamAlpha()

void SetParamAlpha ( FType  a)

Sets the alpha parameter that is used by the default weight function.

§ GetParamAlpha()

FType GetParamAlpha ( ) const

Returns the alpha parameter that is used by the default weight function.

§ SetParamBeta()

void SetParamBeta ( FType  b)

Sets the beta parameter that is used by weight limiting for the default weight function. Setting the beta parameter to zero effectively turns off weight limiting. If weight limiting is off, this parameter has no effect.

§ GetParamBeta()

FType GetParamBeta ( ) const

Returns the beta parameter that is used by weight limiting for the default weight function.

§ SetParamGamma()

void SetParamGamma ( FType  c)

Sets the gamma parameter that is used by weight limiting for the default weight function. The gamma parameter adjusts weight limiting based on the ratio of the input and output counts. If weight limiting is off, this parameter has no effect.

§ GetParamGamma()

FType GetParamGamma ( ) const

Returns the gamma parameter that is used by weight limiting for the default weight function.

§ Eliminate() [1/2]

void Eliminate ( const PointType *  inputPoints,
SIZE_TYPE  inputSize,
PointType *  outputPoints,
SIZE_TYPE  outputSize,
bool  progressive,
FType  d_max,
int  dimensions,
WeightFunction  weightFunction 
) const

This is the main method that uses weighted sample elimination for selecting a subset of samples with blue noise (Poisson disk) characteristics from a given input sample set (inputPoints). The selected samples are copied to outputPoints. The output size must be smaller than the input size.

If the progressive parameter is true, the output sample points are ordered for progressive sampling, such that when the samples are introduced one by one in this order, each subset in the sequence exhibits blue noise characteristics.

The d_max parameter defines radius within which the weight function is non-zero.

The dimensions parameter specifies the dimensionality of the sampling domain. This parameter would typically be equal to the dimensionality of the sampling domain (specified by DIMENSIONS). However, smaller values can be used when sampling a low-dimensional manifold in a high-dimensional space, such as a surface in 3D.

The weight function is the crucial component of weighted sample elimination. It computes the weight of a sample point based on the placement of its neighbors within d_max radius. The weight function must have the following form:

FType weightFunction( const PointType &p0, const PointType &p1, FType dist2, FType d_max )

The arguments p0 and p1 are the two neighboring points, dist2 is the square of the Euclidean distance between these two points, and d_max is the current radius for the weight function. Note that if the progressive parameter is on, the d_max value sent to the weight function can be different than the d_max value passed to this method.

§ Eliminate() [2/2]

void Eliminate ( const PointType *  inputPoints,
SIZE_TYPE  inputSize,
PointType *  outputPoints,
SIZE_TYPE  outputSize,
bool  progressive = false,
FType  d_max = FType(0),
int  dimensions = DIMENSIONS 
) const

This is the main method that uses weighted sample elimination for selecting a subset of samples with blue noise (Poisson disk) characteristics from a given input sample set (inputPoints). The selected samples are copied to outputPoints. The output size must be smaller than the input size. This method uses the default weight function.

If the progressive parameter is true, the output sample points are ordered for progressive sampling, such that when the samples are introduced one by one in this order, each subset in the sequence exhibits blue noise characteristics.

The d_max parameter defines radius within which the weight function is non-zero. If this parameter is zero (or negative), it is automatically computed using the sampling dimensions and the size of the output set.

The dimensions parameter specifies the dimensionality of the sampling domain. This parameter would typically be equal to the dimensionality of the sampling domain (specified by DIMENSIONS). However, smaller values can be used when sampling a low-dimensional manifold in a high-dimensional space, such as a surface in 3D.

§ GetMaxPoissonDiskRadius()

FType GetMaxPoissonDiskRadius ( int  dimensions,
SIZE_TYPE  sampleCount,
FType  domainSize = 0 
) const

Returns the maximum possible Poisson disk radius in the given dimensions for the given sampleCount to spread over the given domainSize. If the domainSize argument is zero or negative, it is computed as the area or N-dimensional volume of the box defined by the minimum and maximum bounds. This method is used for the default weight function.