This class implements spatial distribution function for 2D geometric data. More...

Data Structures
class	Array
	This class implements a base class for data arrays. More...

class	DistanceElement
	Definition of a class holding an index and a distance. More...

class	DistributionArray
	This class implements a distribution array. More...

class	OccupancyArray
	This class implements an occupancy array. More...

Public Types
typedef std::vector< DistanceElement >	DistanceElements
	Definition of a vector holding distance elements. More...

Static Public Member Functions
static void	idealBins (const unsigned int width, const unsigned int height, const size_t numberBins, unsigned int &horizontalBins, unsigned int &verticalBins, const unsigned int minimalHorizontalBins=2u, const unsigned int minimalVerticalBins=2u)
	Calculates the ideal number of horizontal and vertical bins for an array if the overall number of bins is known. More...

static void	idealBinsNeighborhood9 (const unsigned int width, const unsigned int height, const Scalar distance, unsigned int &horizontalBins, unsigned int &verticalBins, const unsigned int minimalHorizontalBins=2u, const unsigned int minimalVerticalBins=2u, const unsigned int maximalHorizontalBins=20u, const unsigned int maximalVerticalBins=20u)
	Calculates the ideal number of horizontal and vertical bins for an array if bin elements within a certain distance should be guaranteed to be located in the 9 neighborhood of that bin This function tries to get bins with almost identical horizontal and vertical size. More...

static DistributionArray	distributeToArray (const ImagePoint *imagePoints, const size_t number, const Scalar left, const Scalar top, const Scalar width, const Scalar height, const unsigned int averagePointsPerBin, const unsigned int maxHorizontalBins, const unsigned int maxVerticalBins, unsigned int &horizontalBins, unsigned int &verticalBins)
	Distributes the given 2D image points into a spatial array. More...

static DistributionArray	distributeToArray (const ImagePoint *imagePoints, const size_t number, const Scalar left, const Scalar top, const Scalar width, const Scalar height, const unsigned int horizontalBins, const unsigned int verticalBins)
	Distributes a set of given 2D image points into a spatial array. More...

template<typename T , const Vector2 &(*)(const T &) tFunction>
static DistributionArray	distributeToArray (const T *elements, const size_t number, const Scalar left, const Scalar top, const Scalar width, const Scalar height, const unsigned int horizontalBins, const unsigned int verticalBins)
	Distributes the given elements into a spatial array. More...

template<unsigned int tMaximalBins>
static DistributionArray	distributeToArray (const ImagePoint *imagePoints, const size_t number, const Scalar left, const Scalar top, const Scalar width, const Scalar height, const Scalar searchDistance)
	Distributes the given 2D image points into a spatial array. More...

static OccupancyArray	createOccupancyArray (const ImagePoint *imagePoints, const size_t number, const Scalar left, const Scalar top, const Scalar width, const Scalar height, const unsigned int horizontalBins, const unsigned int verticalBins)
	Distributes the given 2D image points into a spatial array. More...

static Indices32	filterAccordingDistance (const ImagePoint *imagePoints, const size_t number, const unsigned int width, const unsigned int height, const Scalar distance)
	Filters the given 2D image points according to their distance to neighboring image points. More...

static void	filterCandidatePoint (const ImagePoint imagePoints, const size_t numberImagePoints, const ImagePoint candidatePoints, const size_t numberCandidatePoints, const unsigned int width, const unsigned int height, const Scalar filterDistance, const unsigned int filterSize, Indices32 filteredIndices=nullptr, ImagePoints filteredCandidates=nullptr)
	Filters the given 2D candidate points according to the distance to the given image points. More...

static DistanceElements	sortAccordingDistance (const ImagePoint *imagePoints, const size_t number, const bool minimalDistanceFirst)
	Sorts the given 2D image points according to their minimal distance to neighboring image points. More...

static DistanceElements	sortAccordingDistance (const ImagePoint *imagePoints, const size_t number, const unsigned int width, const unsigned int height, const unsigned int bins, const bool minimalDistanceFirst)
	Sorts the given 2D image points according to their minimal distance to neighboring image points. More...

static Scalar	determineMinimalSqrDistance (const ImagePoint *imagePoints, const size_t numberImagePoints, const unsigned int index, const DistributionArray &distributionImagePoints)
	Determines the minimal square distance for one given 2D image point to all other points in the same set. More...

static void	determineMinimalSqrDistances (const ImagePoint imagePoints, const size_t numberImagePoints, const unsigned int width, const unsigned int height, const unsigned int bins, Scalar sqrDistances)
	Determines the minimal square distances for each given 2D image point to all other points in the same set. More...

static void	determineMinimalSqrDistances (const ImagePoint imagePoints, const size_t numberImagePoints, const ImagePoint candidates, const size_t numberCandidates, const unsigned int width, const unsigned int height, const unsigned int bins, Scalar *sqrDistances)
	Determines the minimal square distances for each given 2D image point to another given set of 2D image points. More...

static void	determineMinimalSqrDistances (const ImagePoint imagePoints, const size_t numberImagePoints, const ImagePoint candidates, const size_t numberCandidates, const DistributionArray &distributionCandidates, Scalar sqrDistances, unsigned int candidateIndices=nullptr)
	Determines the minimal square distances for each given image point to another given set of image points. More...

static void	determineMinimalSqrDistances (const ImagePoint imagePoints, const size_t numberImagePoints, const unsigned int interestIndices, const size_t numberInterestIndices, const unsigned int width, const unsigned int height, const unsigned int bins, Scalar *sqrDistances)
	Determines the minimal square distances for each specified image point inside their neighborhood. More...

static Indices32	determineNeighbors (const ImagePoint &imagePoint, const ImagePoint *candidatePoints, const size_t numberCandidatePoints, const Scalar radius, const DistributionArray &distributionCandidatePoints)
	Determines all candidate points for a given image point (interest point) lying inside a specified circle around the interest point. More...

static Index32	determineNearestNeighbor (const ImagePoint &interestPoint, const ImagePoint imagePoints, const size_t numberImagePoints, const Scalar radius, const DistributionArray &distributionImagePoints, Scalar sqrDistance=nullptr)
	Determines the nearest image point between an interest point and a set of given image point lying inside a specified circle around the interest point. More...

static ImagePoints	distributeAndFilter (const ImagePoint *imagePoints, const size_t numberImagePoints, const Scalar left, const Scalar top, const Scalar width, const Scalar height, const unsigned int horizontalBins, const unsigned int verticalBins)
	Distributes the given image points into an array of specified size and returns (at most) one point from each bin. More...

static ImagePoints	distributeAndFilter (const ImagePoint *imagePoints, const size_t numberImagePoints, const Scalar left, const Scalar top, const Scalar width, const Scalar height, const unsigned int horizontalBins, const unsigned int verticalBins, const size_t size)
	Distributes the given image points into an array of specified size and returns as much points as requested by first selecting the first point from each bin, then the second point from each bin, and so on. More...

template<typename TIndex >
static std::vector< TIndex >	distributeAndFilterIndices (const ImagePoint *imagePoints, const size_t numberImagePoints, const Scalar left, const Scalar top, const Scalar width, const Scalar height, const unsigned int horizontalBins, const unsigned int verticalBins)
	Distributes the given image points into an array of specified size and returns (at most) one point index from each bin. More...

template<typename T , Vector2(*)(const T &) tFunction>
static std::vector< T >	distributeAndFilter (const T *elements, const size_t numberElements, const Scalar left, const Scalar top, const Scalar width, const Scalar height, const unsigned int horizontalBins, const unsigned int verticalBins)
	Distributes the given elements into an array of specified size and returns (at most) one element from each bin. More...

template<typename T , Vector2(*)(const T &) tFunction>
static std::vector< T >	distributeAndFilter (const T elements, const size_t numberElements, const Scalar left, const Scalar top, const Scalar width, const Scalar height, const unsigned int horizontalBins, const unsigned int verticalBins, const size_t numberDesiredFilteredElements, Indices32 indices=nullptr)
	Distributes the given elements into an array of specified size but returns as much elements per bin necessary to reach the specified amount of desired elements. More...

template<typename T , typename TIndex , Vector2(*)(const T &) tFunction>
static std::vector< TIndex >	distributeAndFilterIndices (const T *elements, const size_t numberElements, const Scalar left, const Scalar top, const Scalar width, const Scalar height, const unsigned int horizontalBins, const unsigned int verticalBins)
	Distributes the given elements into an array of specified size and returns (at most) one point index from each bin. More...

Static Protected Member Functions
template<typename T >
static T	identity (const T &value)
	This function simply returns the given object (actually a copy of the object). More...

Detailed Description

This class implements spatial distribution function for 2D geometric data.

Member Typedef Documentation

◆ DistanceElements

typedef std::vector<DistanceElement> Ocean::Geometry::SpatialDistribution::DistanceElements

Definition of a vector holding distance elements.

Member Function Documentation

◆ createOccupancyArray()

static OccupancyArray Ocean::Geometry::SpatialDistribution::createOccupancyArray	(	const ImagePoint *	imagePoints,
		const size_t	number,
		const Scalar	left,
		const Scalar	top,
		const Scalar	width,
		const Scalar	height,
		const unsigned int	horizontalBins,
		const unsigned int	verticalBins
	)

static

Distributes the given 2D image points into a spatial array.

Instead of creating a 2D array a 1D array is returned with the first n elements for the top bins and the second n elements for the second top bins and so on. Image points not fitting into the array bins are discarded.

Parameters

imagePoints	Image points to be distributed, must be valid if the specified number is not zero
number	The number of given image points, with range [0, infinity)
left	Horizontal position of the area, may be 0 for e.g. an entire image, with range (-infinity, infinity)
top	Vertical position of the area, may be 0 for e.g. an entire image, with range (-infinity, infinity)
width	The width of the area holding the points, with range (0, infinity)
height	The height of the area holding the points, with range (0, infinity)
horizontalBins	Number of horizontal bins to distribute the image points into, with range [1, width]
verticalBins	Number of vertical bins to distribute the image points into, with range [1, height]

Returns: Resulting array holding the indices of the distributed image points

◆ determineMinimalSqrDistance()

static Scalar Ocean::Geometry::SpatialDistribution::determineMinimalSqrDistance	(	const ImagePoint *	imagePoints,
		const size_t	numberImagePoints,
		const unsigned int	index,
		const DistributionArray &	distributionImagePoints
	)

static

Determines the minimal square distance for one given 2D image point to all other points in the same set.

This function uses an already create point distribution to speed up the computation.
Candidates for nearest neighbors are all points lying in the 9-bin-neighborhood of a point, thus the result technically is an approximation and not correct in any case.

Parameters

imagePoints	Image points to calculate the distances for
numberImagePoints	Number of given image points
index	The index of the image point to find the minimal square distance for, with range [0, numberImagePoints)
distributionImagePoints	Already created distribution array of the image points

Returns: Resulting square distances calculated for the given image point

◆ determineMinimalSqrDistances() [1/4]

static void Ocean::Geometry::SpatialDistribution::determineMinimalSqrDistances	(	const ImagePoint *	imagePoints,
		const size_t	numberImagePoints,
		const ImagePoint *	candidates,
		const size_t	numberCandidates,
		const DistributionArray &	distributionCandidates,
		Scalar *	sqrDistances,
		unsigned int *	candidateIndices = `nullptr`
	)

static

Determines the minimal square distances for each given image point to another given set of image points.

Candidates for nearest neighbors are all points lying in the 9-bin-neighborhood of a point, thus the result technically is an approximation and not correct in any case.

Parameters

imagePoints	Image points to calculate the distances for, may be nullptr if numberImagePoints==0
numberImagePoints	Number of given image points, with range [0, infinity)
candidates	Image points being candidates as nearest neighbors for the given image points
numberCandidates	Number of given candidates
distributionCandidates	Already created distribution array of the candidates
sqrDistances	Resulting square distances calculated for each given element, make sure that this buffer holds enough space
candidateIndices	Optional resulting indices of the candidate with minimal distance, make sure that this buffer holds enough space (if defined)

◆ determineMinimalSqrDistances() [2/4]

static void Ocean::Geometry::SpatialDistribution::determineMinimalSqrDistances	(	const ImagePoint *	imagePoints,
		const size_t	numberImagePoints,
		const ImagePoint *	candidates,
		const size_t	numberCandidates,
		const unsigned int	width,
		const unsigned int	height,
		const unsigned int	bins,
		Scalar *	sqrDistances
	)

static

Determines the minimal square distances for each given 2D image point to another given set of 2D image points.

This function first distributes all points to array bins to speed up the computation.
Candidates for nearest neighbors are all points lying in the 9-bin-neighborhood of a point, thus the result technically is an approximation and not correct in any case.

Parameters

imagePoints	Image points to calculate the distances for, may be nullptr if numberImagePoints==0
numberImagePoints	Number of given image points, with range [0, infinity)
candidates	Image points being candidates as nearest neighbors for the given image points
numberCandidates	Number of given candidates
width	The width of the area holding the image points in pixel, with range [1, infinity)
height	The height of the area holding the image points in pixel, with range [1, infinity)
bins	Number of bins in each direction used for image point distribution
sqrDistances	Resulting square distances calculated for each given image point, make sure that this buffer holds enough space

◆ determineMinimalSqrDistances() [3/4]

static void Ocean::Geometry::SpatialDistribution::determineMinimalSqrDistances	(	const ImagePoint *	imagePoints,
		const size_t	numberImagePoints,
		const unsigned int *	interestIndices,
		const size_t	numberInterestIndices,
		const unsigned int	width,
		const unsigned int	height,
		const unsigned int	bins,
		Scalar *	sqrDistances
	)

static

Determines the minimal square distances for each specified image point inside their neighborhood.

This function first distributes all image points to array bins to speed up the computation.
Candidates for nearest neighbors are all points lying in the 9-bin-neighborhood of a point, thus the result technically is an approximation and not correct in any case.

Parameters

imagePoints	Image points holding the entire set, may be nullptr if numberImagePoints==0
numberImagePoints	Number of given image points, with range [0, infinity)
interestIndices	Indices of all interest image points to calculate the minimal distance for
numberInterestIndices	Number of given interest indices
width	The width of the area holding the elements in pixel, with range [1, infinity)
height	The height of the area holding the elements in pixel, with range [1, infinity)
bins	Number of bins in each direction used for element distribution
sqrDistances	Resulting square distances calculated for each given interest index, make sure that this buffer holds enough space

◆ determineMinimalSqrDistances() [4/4]

static void Ocean::Geometry::SpatialDistribution::determineMinimalSqrDistances	(	const ImagePoint *	imagePoints,
		const size_t	numberImagePoints,
		const unsigned int	width,
		const unsigned int	height,
		const unsigned int	bins,
		Scalar *	sqrDistances
	)

static

Determines the minimal square distances for each given 2D image point to all other points in the same set.

This function first distributes all points to array bins to speed up the computation.
Candidates for nearest neighbors are all points lying in the 9-bin-neighborhood of a point, thus the result technically is an approximation and not correct in any case.

Parameters

imagePoints	Image points to calculate the distances for, may be nullptr if numberImagePoints==0
numberImagePoints	Number of given image points, with range [0, infinity)
width	The width of the area holding the image points in pixel, with range [1, infinity)
height	The height of the area holding the image points in pixel, with range [1, infinity)
bins	Number of bins in each direction used for image point distribution, with range [1, infinity)
sqrDistances	Resulting square distances calculated for each given image point, make sure that this buffer holds enough space

◆ determineNearestNeighbor()

static Index32 Ocean::Geometry::SpatialDistribution::determineNearestNeighbor	(	const ImagePoint &	interestPoint,
		const ImagePoint *	imagePoints,
		const size_t	numberImagePoints,
		const Scalar	radius,
		const DistributionArray &	distributionImagePoints,
		Scalar *	sqrDistance = `nullptr`
	)

static

Determines the nearest image point between an interest point and a set of given image point lying inside a specified circle around the interest point.

Parameters

interestPoint	The interest image point for which the nearest neighbor will be determined, with range (-infinity, infinity)x(-infinity, infinity)
imagePoints	The set of image points from which the nearest neighbor will be determined
numberImagePoints	Number of given image points, with range [0, infinity)
radius	The radius specifying the circle around the interest point, with range [0, infinity)
distributionImagePoints	Already created distribution array of the image points
sqrDistance	Optional resulting square distance of the nearest image point, if any

Returns: Resulting index of the nearest neighbor image point, -1 if no image point lies within the specified radius

◆ determineNeighbors()

static Indices32 Ocean::Geometry::SpatialDistribution::determineNeighbors	(	const ImagePoint &	imagePoint,
		const ImagePoint *	candidatePoints,
		const size_t	numberCandidatePoints,
		const Scalar	radius,
		const DistributionArray &	distributionCandidatePoints
	)

static

Determines all candidate points for a given image point (interest point) lying inside a specified circle around the interest point.

Parameters

imagePoint	The interest image point to find the neighboring candidate points for, with range (-infinity, infinity)x(-infinity, infinity)
candidatePoints	Candidate points to find the neighbors in
numberCandidatePoints	Number of given candidate points
radius	The radius specifying the circle around the interest point, with range [0, infinity)
distributionCandidatePoints	Already created distribution array of the candidate points

Returns: Resulting indices of all neighbors out the candidate set lying within the specified circle.

◆ distributeAndFilter() [1/4]

ImagePoints Ocean::Geometry::SpatialDistribution::distributeAndFilter	(	const ImagePoint *	imagePoints,
		const size_t	numberImagePoints,
		const Scalar	left,
		const Scalar	top,
		const Scalar	width,
		const Scalar	height,
		const unsigned int	horizontalBins,
		const unsigned int	verticalBins
	)

inlinestatic

Distributes the given image points into an array of specified size and returns (at most) one point from each bin.

Parameters

imagePoints	Image points to be distributed and filtered, may be nullptr if numberImagePoints==0
numberImagePoints	Number of given image points, with range [0, infinity)
left	Horizontal position of the area, may be 0 for e.g. an entire image, with range (-infinity, infinity)
top	Vertical position of the area, may be 0 for e.g. an entire image, with range (-infinity, infinity)
width	The width of the area holding the elements, with range (0, infinity)
height	The height of the area holding the elements, with range (0, infinity)
horizontalBins	Number of horizontal bins to be used for distribution, with range [1, infinity)
verticalBins	Number of vertical bins to be used for distribution, with range [1, infinity)

Returns: Resulting filtered elements

◆ distributeAndFilter() [2/4]

static ImagePoints Ocean::Geometry::SpatialDistribution::distributeAndFilter	(	const ImagePoint *	imagePoints,
		const size_t	numberImagePoints,
		const Scalar	left,
		const Scalar	top,
		const Scalar	width,
		const Scalar	height,
		const unsigned int	horizontalBins,
		const unsigned int	verticalBins,
		const size_t	size
	)

static

Distributes the given image points into an array of specified size and returns as much points as requested by first selecting the first point from each bin, then the second point from each bin, and so on.

Parameters

imagePoints	Image points to be distributed and filtered, may be nullptr if numberImagePoints==0
numberImagePoints	Number of given image points, with range [0, infinity)
left	Horizontal position of the area, may be 0 for e.g. an entire image, with range (-infinity, infinity)
top	Vertical position of the area, may be 0 for e.g. an entire image, with range (-infinity, infinity)
width	The width of the area holding the elements, with range (0, infinity)
height	The height of the area holding the elements, with range (0, infinity)
horizontalBins	Number of horizontal bins to be used for distribution, with range [1, infinity)
verticalBins	Number of vertical bins to be used for distribution, with range [1, infinity)
size	The number of requested feature points, with range [0, numberImagePoints]

Returns: Resulting filtered elements

◆ distributeAndFilter() [3/4]

template<typename T , Vector2(*)(const T &) tFunction>

std::vector< T > Ocean::Geometry::SpatialDistribution::distributeAndFilter	(	const T *	elements,
		const size_t	numberElements,
		const Scalar	left,
		const Scalar	top,
		const Scalar	width,
		const Scalar	height,
		const unsigned int	horizontalBins,
		const unsigned int	verticalBins
	)

static

Distributes the given elements into an array of specified size and returns (at most) one element from each bin.

Parameters

elements	The elements to be distributed and filtered, may be nullptr if numberImagePoints==0
numberElements	Number of given elements, with range [0, infinity)
left	Horizontal position of the area, may be 0 for e.g. an entire image, with range (-infinity, infinity)
top	Vertical position of the area, may be 0 for e.g. an entire image, with range (-infinity, infinity)
width	The width of the area holding the elements, with range (0, infinity)
height	The height of the area holding the elements, with range (0, infinity)
horizontalBins	Number of horizontal bins to be used for distribution, with range [1, infinity)
verticalBins	Number of vertical bins to be used for distribution, with range [1, infinity)

Returns: Resulting filtered elements

Template Parameters

T	The data type of the elements to be distributed
tFunction	The function pointer that returns the 2D position of each element

◆ distributeAndFilter() [4/4]

template<typename T , Vector2(*)(const T &) tFunction>

std::vector< T > Ocean::Geometry::SpatialDistribution::distributeAndFilter	(	const T *	elements,
		const size_t	numberElements,
		const Scalar	left,
		const Scalar	top,
		const Scalar	width,
		const Scalar	height,
		const unsigned int	horizontalBins,
		const unsigned int	verticalBins,
		const size_t	numberDesiredFilteredElements,
		Indices32 *	indices = `nullptr`
	)

static

Distributes the given elements into an array of specified size but returns as much elements per bin necessary to reach the specified amount of desired elements.

This function should be used whenever the given elements are not distributed equally while a specified amount of feature points is desired. The function applies several filter iterations until the desired number of elements is reached.
After the first iteration each bin will contain at most one element, after the second iteration at most two elements, and so on.

Parameters

elements	The elements to be distributed and filtered, may be nullptr if numberImagePoints==0
numberElements	Number of given elements, with range [0, infinity)
left	Horizontal position of the area, may be 0 for e.g. an entire image, with range (-infinity, infinity)
top	Vertical position of the area, may be 0 for e.g. an entire image, with range (-infinity, infinity)
width	The width of the area holding the elements, with range (0, infinity)
height	The height of the area holding the elements, with range (0, infinity)
horizontalBins	Number of horizontal bins to be used for distribution, with range [1, infinity)
verticalBins	Number of vertical bins to be used for distribution, with range [1, infinity)
numberDesiredFilteredElements	The desired number of filtered elements, with range [1, numberElements]
indices	Optional resulting indices of the selected keypoints, if defined indices will be pushed at the back.

Returns: Resulting filtered elements

Template Parameters

T	The data type of the elements to be distributed
tFunction	The function pointer that returns the 2D position of each element

◆ distributeAndFilterIndices() [1/2]

template<typename TIndex >

std::vector< TIndex > Ocean::Geometry::SpatialDistribution::distributeAndFilterIndices	(	const ImagePoint *	imagePoints,
		const size_t	numberImagePoints,
		const Scalar	left,
		const Scalar	top,
		const Scalar	width,
		const Scalar	height,
		const unsigned int	horizontalBins,
		const unsigned int	verticalBins
	)

inlinestatic

Distributes the given image points into an array of specified size and returns (at most) one point index from each bin.

The resulting indices can be used to filter the actual set of image points.

Parameters

imagePoints	Image points to be distributed and filtered, may be nullptr if numberImagePoints==0
numberImagePoints	Number of given image points, with range [0, infinity)
left	Horizontal position of the area, may be 0 for e.g. an entire image, with range (-infinity, infinity)
top	Vertical position of the area, may be 0 for e.g. an entire image, with range (-infinity, infinity)
width	The width of the area holding the elements, with range (0, infinity)
height	The height of the area holding the elements, with range (0, infinity)
horizontalBins	Number of horizontal bins to be used for distribution, with range [1, infinity)
verticalBins	Number of vertical bins to be used for distribution, with range [1, infinity)

Returns: Resulting indices of the filtered elements

Template Parameters

TIndex The data type of the indices (e.g., may be Index32 or Index64)

◆ distributeAndFilterIndices() [2/2]

template<typename T , typename TIndex , Vector2(*)(const T &) tFunction>

std::vector< TIndex > Ocean::Geometry::SpatialDistribution::distributeAndFilterIndices	(	const T *	elements,
		const size_t	numberElements,
		const Scalar	left,
		const Scalar	top,
		const Scalar	width,
		const Scalar	height,
		const unsigned int	horizontalBins,
		const unsigned int	verticalBins
	)

static

Distributes the given elements into an array of specified size and returns (at most) one point index from each bin.

The resulting indices can be used to filter the actual set of image points.

Parameters

elements	The elements to be distributed and filtered, may be nullptr if numberImagePoints==0
numberElements	Number of given elements, with range [0, infinity)
left	Horizontal position of the area, may be 0 for e.g. an entire image, with range (-infinity, infinity)
top	Vertical position of the area, may be 0 for e.g. an entire image, with range (-infinity, infinity)
width	The width of the area holding the elements, with range (0, infinity)
height	The height of the area holding the elements, with range (0, infinity)
horizontalBins	Number of horizontal bins to be used for distribution, with range [1, infinity)
verticalBins	Number of vertical bins to be used for distribution, with range [1, infinity)

Returns: Resulting indices of the filtered elements

Template Parameters

T	The data type of the elements to be distributed
TIndex	The data type of the indices (e.g., may be Index32 or Index64)
tFunction	The function pointer that returns the 2D position of each element

◆ distributeToArray() [1/4]

template<unsigned int tMaximalBins>

SpatialDistribution::DistributionArray Ocean::Geometry::SpatialDistribution::distributeToArray	(	const ImagePoint *	imagePoints,
		const size_t	number,
		const Scalar	left,
		const Scalar	top,
		const Scalar	width,
		const Scalar	height,
		const Scalar	searchDistance
	)

inlinestatic

Distributes the given 2D image points into a spatial array.

Instead of creating a 2D array a 1D array is returned with the first n elements for the top bins and the second n elements for the second top bins and so on. Image points not fitting into the array bins are discarded.

Parameters

imagePoints	Image points to be distributed
number	The number of given image points
left	Horizontal position of the area, may be 0 for e.g. an entire image, with range (-infinity, infinity)
top	Vertical position of the area, may be 0 for e.g. an entire image, with range (-infinity, infinity)
width	The width of the area holding the points, with range (0, infinity)
height	The height of the area holding the points, with range (0, infinity)
searchDistance	Search distance that will be applied (minimal size of each bin)

Returns: Resulting array holding the indices of the distributed image points

Template Parameters

tMaximalBins Number of maximal bins in each direction (horizontal and vertical), width range [1, infinity)

◆ distributeToArray() [2/4]

SpatialDistribution::DistributionArray Ocean::Geometry::SpatialDistribution::distributeToArray	(	const ImagePoint *	imagePoints,
		const size_t	number,
		const Scalar	left,
		const Scalar	top,
		const Scalar	width,
		const Scalar	height,
		const unsigned int	averagePointsPerBin,
		const unsigned int	maxHorizontalBins,
		const unsigned int	maxVerticalBins,
		unsigned int &	horizontalBins,
		unsigned int &	verticalBins
	)

inlinestatic

Distributes the given 2D image points into a spatial array.

The number of used horizontal and vertical bins are calculated automatically. Instead of creating a 2D array a 1D array is returned with the first n elements for the top bins and the second n elements for the second top bins and so on.
Image points not fitting into the array bins are discarded.

Parameters

imagePoints	Image points to be distributed, may be nullptr if number==0
number	The number of given image points, with range [0, infinity)
left	Horizontal position of the area, may be 0 for e.g. an entire image, with range (-infinity, infinity)
top	Vertical position of the area, may be 0 for e.g. an entire image, with range (-infinity, infinity)
width	The width of the area holding the elements, with range (0, infinity)
height	The height of the area holding the elements, with range (0, infinity)
averagePointsPerBin	Average number of points per bin, with range [1, infinity)
maxHorizontalBins	Maximal number of horizontal bins, with range [1, infinity)
maxVerticalBins	Maximal number of vertical bins, with range [1, infinity)
horizontalBins	Resulting horizontal bins, with range [1, infinity)
verticalBins	Resulting vertical bins, with range [1, infinity)

Returns: Resulting array holding the indices of the distributed image points, will be cleared before usage

averagePointsPerBin * horizontalBins * verticalBins = number horizontalBins / verticalBins = width / height

◆ distributeToArray() [3/4]

static DistributionArray Ocean::Geometry::SpatialDistribution::distributeToArray	(	const ImagePoint *	imagePoints,
		const size_t	number,
		const Scalar	left,
		const Scalar	top,
		const Scalar	width,
		const Scalar	height,
		const unsigned int	horizontalBins,
		const unsigned int	verticalBins
	)

static

Distributes a set of given 2D image points into a spatial array.

Image points not fitting into the array bins are discarded.

Parameters

imagePoints	Image points to be distributed, with range (-infinity, infinity)x(-infinity, infinity), may be nullptr if number==0
number	The number of given image points, with range [0, infinity)
left	Horizontal position of the area, may be 0 for e.g. an entire image, with range (-infinity, infinity)
top	Vertical position of the area, may be 0 for e.g. an entire image, with range (-infinity, infinity)
width	The width of the area holding the points, with range (0, infinity)
height	The height of the area holding the points, with range (0, infinity)
horizontalBins	Number of horizontal bins to distribute the image points into, with range [1, infinity)
verticalBins	Number of vertical bins to distribute the image points into, with range [1, infinity)

Returns: Resulting array holding the indices of the distributed image points

◆ distributeToArray() [4/4]

template<typename T , const Vector2 &(*)(const T &) tFunction>

SpatialDistribution::DistributionArray Ocean::Geometry::SpatialDistribution::distributeToArray	(	const T *	elements,
		const size_t	number,
		const Scalar	left,
		const Scalar	top,
		const Scalar	width,
		const Scalar	height,
		const unsigned int	horizontalBins,
		const unsigned int	verticalBins
	)

static

Distributes the given elements into a spatial array.

Elements not fitting into the array bins are discarded.

Parameters

elements	The elements (e.g. holding image points) to be distributed
number	The number of given image points
left	Horizontal position of the area, may be 0 for e.g. an entire image, with range (-infinity, infinity)
top	Vertical position of the area, may be 0 for e.g. an entire image, with range (-infinity, infinity)
width	The width of the area holding the elements, with range (0, infinity)
height	The height of the area holding the elements, with range (0, infinity)
horizontalBins	Number of horizontal bins to distribute the image points into, with range [1, width]
verticalBins	Number of vertical bins to distribute the image points into, with range [1, height]

Returns: Resulting array holding the indices of the distributed elements

Template Parameters

T	Data type of the given elements
tFunction	Function pointer type of a function returning the 2D position of any element

◆ filterAccordingDistance()

static Indices32 Ocean::Geometry::SpatialDistribution::filterAccordingDistance	(	const ImagePoint *	imagePoints,
		const size_t	number,
		const unsigned int	width,
		const unsigned int	height,
		const Scalar	distance
	)

static

Filters the given 2D image points according to their distance to neighboring image points.

Parameters

imagePoints	Image points (e.g. holding image points) to be filtered
number	The number of given image points
width	The width of the area holding the points in pixel, with range [1, infinity)
height	The height of the area holding the points in pixel, with range [1, infinity)
distance	The distance threshold to be used for filtering

Returns: Resulting vector holding the indices of the found image points

◆ filterCandidatePoint()

static void Ocean::Geometry::SpatialDistribution::filterCandidatePoint	(	const ImagePoint *	imagePoints,
		const size_t	numberImagePoints,
		const ImagePoint *	candidatePoints,
		const size_t	numberCandidatePoints,
		const unsigned int	width,
		const unsigned int	height,
		const Scalar	filterDistance,
		const unsigned int	filterSize,
		Indices32 *	filteredIndices = `nullptr`,
		ImagePoints *	filteredCandidates = `nullptr`
	)

static

Filters the given 2D candidate points according to the distance to the given image points.

Parameters

imagePoints	Image points for that the filtered candidate points have to be found
numberImagePoints	Number of image points
candidatePoints	Candidate points that will be filtered
numberCandidatePoints	Number of candidate points
width	The width of the area holding the image points, with range [1, infinity)
height	The height of the area holding the image points, with range [1, infinity)
filterDistance	Distance threshold that define whether a candidate point belongs to one image point
filterSize	Number of candidate points that can belong to one image point
filteredIndices	Resulting indices of the filtered candidate points, if defined
filteredCandidates	Resulting filtered candidate points, if defined

◆ idealBins()

static void Ocean::Geometry::SpatialDistribution::idealBins	(	const unsigned int	width,
		const unsigned int	height,
		const size_t	numberBins,
		unsigned int &	horizontalBins,
		unsigned int &	verticalBins,
		const unsigned int	minimalHorizontalBins = `2u`,
		const unsigned int	minimalVerticalBins = `2u`
	)

static

Calculates the ideal number of horizontal and vertical bins for an array if the overall number of bins is known.

This function tries to get bins with almost identical horizontal and vertical size.

Parameters

width	The width of the area the array covers, with range [1, infinity)
height	The height of the area the array covers, with range [1, infinity)
numberBins	The number of bins that would be perfect, with range [1, infinity)
horizontalBins	The resulting number of horizontal bins that fit best with the given parameters, with range [minimalHorizontalBins, width]
verticalBins	The resulting number of vertical bins that fit best with the given parameters, with range [minimalVerticalBins, height]
minimalHorizontalBins	The minimal number of horizontal bins, with range [1, width]
minimalVerticalBins	The minimal number of vertical bins, with range [1, height]

◆ idealBinsNeighborhood9()

static void Ocean::Geometry::SpatialDistribution::idealBinsNeighborhood9	(	const unsigned int	width,
		const unsigned int	height,
		const Scalar	distance,
		unsigned int &	horizontalBins,
		unsigned int &	verticalBins,
		const unsigned int	minimalHorizontalBins = `2u`,
		const unsigned int	minimalVerticalBins = `2u`,
		const unsigned int	maximalHorizontalBins = `20u`,
		const unsigned int	maximalVerticalBins = `20u`
	)

static

Calculates the ideal number of horizontal and vertical bins for an array if bin elements within a certain distance should be guaranteed to be located in the 9 neighborhood of that bin This function tries to get bins with almost identical horizontal and vertical size.

Parameters

width	The width of the area the array covers, with range [1, infinity)
height	The height of the area the array covers, with range [1, infinity)
distance	The distance to other bin elements that should be guaranteed to be located in the 9 neighborhood, with range [1, infinity)
horizontalBins	The resulting number of horizontal bins that fit best with the given parameters, with range [minimalHorizontalBins, width]
verticalBins	The resulting number of vertical bins that fit best with the given parameters, with range [minimalVerticalBins, height]
minimalHorizontalBins	The minimal number of horizontal bins, with range [1, maximalHorizontalBins]
minimalVerticalBins	The minimal number of vertical bins, with range [1, maximalVerticalBins]
maximalHorizontalBins	The maximal number of horizontal bins, with range [minimalHorizontalBins, width]
maximalVerticalBins	The maximal number of vertical bins, with range [minimalVerticalBins, height]

◆ identity()

template<typename T >

T Ocean::Geometry::SpatialDistribution::identity ( const T & value )

inlinestaticprotected

This function simply returns the given object (actually a copy of the object).

Parameters

value The value to be returned

Returns: The given value

Template Parameters

T	The data type of the value

◆ sortAccordingDistance() [1/2]

static DistanceElements Ocean::Geometry::SpatialDistribution::sortAccordingDistance	(	const ImagePoint *	imagePoints,
		const size_t	number,
		const bool	minimalDistanceFirst
	)

static

Sorts the given 2D image points according to their minimal distance to neighboring image points.

Points with higher distances will be returned before points with lower distances.

Parameters

imagePoints	Image points (e.g. holding image points) to be sorted
number	The number of given image points
minimalDistanceFirst	True, to sort minimal distance to the front

Returns: Resulting vector holding the indices and distances of the sorted image points

◆ sortAccordingDistance() [2/2]

static DistanceElements Ocean::Geometry::SpatialDistribution::sortAccordingDistance	(	const ImagePoint *	imagePoints,
		const size_t	number,
		const unsigned int	width,
		const unsigned int	height,
		const unsigned int	bins,
		const bool	minimalDistanceFirst
	)

static

Sorts the given 2D image points according to their minimal distance to neighboring image points.

Points with higher distances will be returned before points with lower distances. This function first distributes all points to array bins to speed up the computation.

Parameters

imagePoints	Image points (e.g. holding image points) to be sorted
number	The number of given image points
width	The width of the area holding the image points in pixel, with range [1, infinity)
height	The height of the area holding the image points in pixel, with range [1, infinity)
bins	Number of bins in each direction used for image point distribution
minimalDistanceFirst	True, to sort minimal distance to the front

Returns: Resulting vector holding the indices and distances of the sorted image points

The documentation for this class was generated from the following file:

SpatialDistribution.h

Data Structures

Public Types

Static Public Member Functions

Static Protected Member Functions

Detailed Description

Member Typedef Documentation

◆ DistanceElements

Member Function Documentation

◆ createOccupancyArray()

◆ determineMinimalSqrDistance()

◆ determineMinimalSqrDistances() [1/4]

◆ determineMinimalSqrDistances() [2/4]

◆ determineMinimalSqrDistances() [3/4]

◆ determineMinimalSqrDistances() [4/4]

◆ determineNearestNeighbor()

◆ determineNeighbors()

◆ distributeAndFilter() [1/4]

◆ distributeAndFilter() [2/4]

◆ distributeAndFilter() [3/4]

◆ distributeAndFilter() [4/4]

◆ distributeAndFilterIndices() [1/2]

◆ distributeAndFilterIndices() [2/2]

◆ distributeToArray() [1/4]

◆ distributeToArray() [2/4]

◆ distributeToArray() [3/4]

◆ distributeToArray() [4/4]

◆ filterAccordingDistance()

◆ filterCandidatePoint()

◆ idealBins()

◆ idealBinsNeighborhood9()

◆ identity()

◆ sortAccordingDistance() [1/2]

◆ sortAccordingDistance() [2/2]