CloudPrepare simplifies dense point clouds and helps prevent memory usage peaks during data transfer. More...

#include <CloudPrepare.h>

Public Member Functions
size_t	adaptiveSimplify (double maxDiffZ, SumStrategy sms, ConvexHullStrategy chs, bool bDryRun=false)
	Simplifies the point cloud based on a tolerance threshold for the z-values. More...

void	add (const std::vector< Point2 > &vPoints)
	Add a set of points to the CloudPrepare object (vector version) More...

void	add (double x, double y, double z, int customIndex=-1)
	Add a point to the CloudPrepare object. More...

void	add (size_t numPoints, double *aCoordinates)
	Add points to the CloudPrepare object (array-version) More...

void	clear ()
	Clear all stored data.

bool	computeConvexHull (bool bAllPoints, std::vector< Point2 > &vConvexHull)
	Compute the Convex Hull. More...

void	getBounds (double &minX, double &minY, double &minZ, double &maxX, double &maxY, double &maxZ)
	Get the minimum and maximum bounds of the point cloud. More...

size_t	getNumPoints () const
	Get the total number of points in the CloudPrepare object. More...

void	getPoints (std::vector< Point2 > &vPointsOut) const
	Retrieve the point cloud. More...

double	getRangeX ()
	Get the range of the x-coordinates. More...

double	getRangeY ()
	Get the range of the y-coordinates. More...

double	getRangeZ ()
	Get the range of the z-coordinates. More...

size_t	uniformSimplifyGrid (double gridLength, SumStrategy sms, ConvexHullStrategy chs, bool bDryRun=false)
	Simplify the point cloud according to grid resolution. More...

size_t	uniformSimplifyNum (int approxNumPoints, SumStrategy sms, ConvexHullStrategy chs)
	Simplify the point cloud using a grid resolution determined by the desired number of output points. More...

Detailed Description

Point Cloud Reduction: Left original, right reduced

This class serves two main purposes:

Point cloud simplification: The reduction of dense point clouds can be performed either by applying a tolerance threshold for vertical error, which adapts the output density to the local level of detail, or using a grid-based approach. For the latter, four aggregation strategies are available to group similar points:
- SMS_MINIMUM: Corresponds to ground filtering by prioritizing the lower ground points over those in vegetation.
- SMS_MAXIMUM: Keeps the highest points.
- SMS_MEDIAN: Reduces outliers and stabilizes the cloud by taking the median height of similar points
- SMS_AVERAGE: Averages similar points, reducing noise in the point cloud.
Avoiding memory peaks during triangulation: This is important when working with large point clouds. The point cloud is stored in your own data structures. If you directly insert it into Fade_2D, the point data is copied and triangles are created immediately, leading to a temporary memory peak.
To avoid this, you can pass the points to CloudPrepare first, remove them from your own data structures, and only then call Fade_2D::insert(&CloudPrepare). This two-step approach prevents the temporary memory peak caused by duplicating the point cloud data.

See also: Example with CloudPrepare for practical C++ usage.

Member Function Documentation

◆ adaptiveSimplify()

size_t GEOM_FADE25D::CloudPrepare::adaptiveSimplify	(	double	maxDiffZ,
		SumStrategy	sms,
		ConvexHullStrategy	chs,
		bool	bDryRun = `false`
	)

This method simplifies the point cloud adaptively according to the height values. This means that adjoining points with similar z-values (within the given tolerance maxDiffZ) are combined into one.

Parameters

[in]	maxDiffZ	The maximum difference in height (z-coordinate) between points. Points with a difference up to this value will be combined into one.
[in]	sms	The strategy used to aggregate similar points into one. Possible values are SMS_MINIMUM, SMS_MAXIMUM, SMS_MEDIAN, and SMS_AVERAGE.
[in]	chs	The ConvexHullStrategy: Use CHS_MAXHULL to preserve all convex hull points. Use CHS_MINHULL to preserve only the convex corner points of the convex hull, excluding any points lying in the middle of straight line segments that form the hull. Use CHS_NOHULL to treat convex hull points like all other points.
[in]	bDryRun	If set to true, the method will simulate the simplification process without modifying the point cloud. This can be used to determine the number of points that would result from the simplification with the given parameters. The default value is false.

Returns: The resulting number of points after simplification.

◆ add() [1/3]

void GEOM_FADE25D::CloudPrepare::add ( const std::vector< Point2 > & vPoints )

This method allows you to add multiple points to the CloudPrepare object at once, using a vector of Point2 objects.

Parameters

[in] vPoints A vector containing the points to be added.

◆ add() [2/3]

void GEOM_FADE25D::CloudPrepare::add	(	double	x,
		double	y,
		double	z,
		int	customIndex = `-1`
	)

This method adds a single point to the CloudPrepare object, specified by its 3D coordinates (x, y, z). An optional customIndex can be provided to link the point to your own data structures.

Parameters

[in]	x,y,z	The coordinates of the point.
[in]	customIndex	An optional index that can be used to link the point with your own data structures. If you later call `Point2::getCustomIndex()` on this point, the same custom index will be returned.

◆ add() [3/3]

void GEOM_FADE25D::CloudPrepare::add	(	size_t	numPoints,
		double *	aCoordinates
	)

This method adds multiple points to the CloudPrepare object. The points are provided as an array of coordinates, where each group of three consecutive values represents the x, y, and z coordinates of a point.

Parameters

[in]	numPoints	The number of points to be added.
[in]	aCoordinates	An array containing the coordinates of the points. The array holds `3*numPoints` elements, where each set of three consecutive values represents the x, y, and z coordinates of a point (e.g., x0, y0, z0, x1, y1, z1, ...).

◆ computeConvexHull()

bool GEOM_FADE25D::CloudPrepare::computeConvexHull	(	bool	bAllPoints,
		std::vector< Point2 > &	vConvexHull
	)

This method computes the convex hull for a point cloud.

Parameters

[in]	bAllPoints	If set to `true`, all points on the convex hull are returned, including those that do not contribute to the minimal convex shape. If set to `false`, only the essential convex points are returned, excluding those that lie on straight line segments between convex hull points.
[out]	vConvexHull	A vector that will be filled with the points forming the convex hull.

◆ getBounds()

void GEOM_FADE25D::CloudPrepare::getBounds	(	double &	minX,
		double &	minY,
		double &	minZ,
		double &	maxX,
		double &	maxY,
		double &	maxZ
	)

This method retrieves the minimum and maximum coordinates of all points in the point cloud.

Parameters

[out] minX,minY,minZ,maxX,maxY,maxZ

◆ getNumPoints()

size_t GEOM_FADE25D::CloudPrepare::getNumPoints ( ) const

This method returns the number of points currently stored in the CloudPrepare object.

Returns: The total number of points in the CloudPrepare object.

◆ getPoints()

void GEOM_FADE25D::CloudPrepare::getPoints ( std::vector< Point2 > & vPointsOut ) const

This method retrieves the current point cloud and stores them in the provided vector.

Parameters

[out] vPointsOut The vector where the simplified points will be stored.

Note: For better memory efficiency, it is recommended to insert the points from the CloudPrepare object using Fade_2D::insert(CloudPrepare). This avoids the need to copy the points first, reducing memory overhead.

◆ getRangeX()

double GEOM_FADE25D::CloudPrepare::getRangeX ( )

This method returns the range (maximum - minimum) of the x-coordinates in the point cloud.

Returns: The x-range.

◆ getRangeY()

double GEOM_FADE25D::CloudPrepare::getRangeY ( )

This method returns the range (maximum - minimum) of the y-coordinates in the point cloud.

Returns: The y-range.

◆ getRangeZ()

double GEOM_FADE25D::CloudPrepare::getRangeZ ( )

This method returns the range (maximum - minimum) of the z-coordinates in the point cloud.

Returns: The z-range.

◆ uniformSimplifyGrid()

size_t GEOM_FADE25D::CloudPrepare::uniformSimplifyGrid	(	double	gridLength,
		SumStrategy	sms,
		ConvexHullStrategy	chs,
		bool	bDryRun = `false`
	)

This method simplifies the point cloud by dividing the xy-plane into a grid and combining all points within each grid cell into a single point. The resulting point's position is determined according to the specified aggregation strategy.

Parameters

[in]	gridLength	The grid resolution, which defines the cell spacing. Points within each cell are aggregated into a single point.
[in]	sms	The aggregation strategy used to combine the points within each cell. Possible values are: SMS_MINIMUM: Uses the minimum value in each cell. SMS_MAXIMUM: Uses the maximum value in each cell. SMS_MEDIAN: Uses the median value of points in each cell. SMS_AVERAGE: Uses the average of points in each cell.
[in]	chs	The ConvexHullStrategy that determines how to handle convex hull points: CHS_MAXHULL: Keeps all points on the convex hull unchanged. CHS_MINHULL: Preserves only the convex corner points of the convex hull, excluding any points lying in the middle of straight line segments that form the hull. CHS_NOHULL: Treats all points, including convex hull points, the same.
[in]	bDryRun	If set to `true`, the point cloud simplification is not performed. This option is used to calculate how many points would result from the simplification with the specified parameters without actually modifying the point cloud.

Returns: The number of points in the simplified point cloud after the operation.

◆ uniformSimplifyNum()

size_t GEOM_FADE25D::CloudPrepare::uniformSimplifyNum	(	int	approxNumPoints,
		SumStrategy	sms,
		ConvexHullStrategy	chs
	)

This method simplifies the point cloud by dividing the xy-plane into a grid and combining all points within each grid cell into a single point. The resolution of the grid is automatically adjusted to achieve the desired number of output points. The resulting point's position is determined according to the specified aggregation strategy.

Parameters

approxNumPoints	[in] The desired number of points in the simplified point cloud. The algorithm will adjust the grid resolution to reduce the point cloud to approximately this number of points.
sms	[in] The aggregation strategy used to combine the points within each cell. Possible values are: SMS_MINIMUM: Uses the minimum value of the points in each cell. SMS_MAXIMUM: Uses the maximum value of the points in each cell. SMS_MEDIAN: Uses the median value of the points in each cell. SMS_AVERAGE: Uses the average value of the points in each cell.
chs	[in] The ConvexHullStrategy that determines how to handle convex hull points: CHS_MAXHULL: Keeps all points on the convex hull unchanged. CHS_MINHULL: Preserves only the convex corner points of the convex hull, excluding points lying within straight line segments that form the convex hull. CHS_NOHULL: Treats all points, including convex hull points, equally.

Returns: The number of points in the simplified point cloud after the operation.

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

CloudPrepare.h

Public Member Functions

Detailed Description

Member Function Documentation

◆ adaptiveSimplify()

◆ add() [1/3]

◆ add() [2/3]

◆ add() [3/3]

◆ computeConvexHull()

◆ getBounds()

◆ getNumPoints()

◆ getPoints()

◆ getRangeX()

◆ getRangeY()

◆ getRangeZ()

◆ uniformSimplifyGrid()

◆ uniformSimplifyNum()