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 ()
 The constructor sets the default parameters.
 
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.
 
bool IsTiling () const
 Returns true if the tiling parameter is turned on.
 
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.
 
bool IsWeightLimiting () const
 Returns true if weight limiting is turned on.
 
PointType const & 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.
 
PointType const & 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.
 
void SetBoundsMin (PointType const &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.
 
void SetBoundsMax (PointType const &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.
 
void SetParamAlpha (FType a)
 Sets the alpha parameter that is used by the default weight function.
 
FType GetParamAlpha () const
 Returns the alpha parameter that is used by the default weight function.
 
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.
 
FType GetParamBeta () const
 Returns the beta parameter that is used by weight limiting for the default weight function.
 
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.
 
FType GetParamGamma () const
 Returns the gamma parameter that is used by weight limiting for the default weight function.
 
template<typename WeightFunction >
void Eliminate (PointType const *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. More...
 
void Eliminate (PointType const *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. More...
 
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.
 

Member Function Documentation

◆ Eliminate() [1/2]

void Eliminate ( PointType const *  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( PointType const &p0, PointType const &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 ( PointType const *  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.