hmap::Cloud Class Reference

Represents a collection of unordered points in 2D space. More...

#include <cloud.hpp>

Inheritance diagram for hmap::Cloud:

Collaboration diagram for hmap::Cloud:

Public Member Functions
	Cloud ()
	Default constructor for the Cloud class.
virtual	~Cloud ()=default
	Cloud (int npoints, uint seed, glm::vec4 bbox={0.f, 1.f, 0.f, 1.f})
	Constructs a new Cloud object with random positions and values.
	Cloud (const std::vector< Point > &points)
	Constructs a new Cloud object based on a list of existing points.
	Cloud (const std::vector< float > &x, const std::vector< float > &y, float default_value=0.f)
	Constructs a new Cloud object from lists of x and y coordinates.
	Cloud (const std::vector< float > &x, const std::vector< float > &y, const std::vector< float > &v)
	Constructs a new Cloud object from lists of x and y coordinates with assigned values.
	Cloud (const std::vector< glm::ivec2 > &indices, const glm::ivec2 &shape, const glm::vec4 &bbox={0.f, 1.f, 0.f, 1.f})
	Construct a point cloud from grid indices mapped to a bounding box.
	Cloud (const std::vector< glm::vec3 > &xyv)
	Constructs a new Cloud object from lists of xyz data as glm::vec3.
void	add_point (const Point &p)
	Add a new point to the cloud.
void	remove_point (int point_idx)
	Remove a point from the cloud.
glm::vec4	get_bbox () const
	Get the bounding box of the cloud.
Point	get_center () const
	Calculates the centroid of a set of points.
std::vector< int >	get_convex_hull () const
	Computes the indices of the points that form the convex hull of a set of points.
std::vector< float >	get_values () const
	Get the values assigned to the points in the cloud.
float	get_values_max () const
	Get the maximum value among the points in the cloud.
float	get_values_min () const
	Get the minimum value among the points in the cloud.
std::vector< float >	get_x () const
	Get the x coordinates of the points in the cloud.
std::vector< float >	get_xy () const
	Get the concatenated x and y coordinates of the points in the cloud.
std::vector< float >	get_y () const
	Get the y coordinates of the points in the cloud.
size_t	nearest_point (const glm::vec2 &xy) const
	Find the index of the nearest point in the cloud.
void	set_points (const std::vector< float > &x, const std::vector< float > &y)
	Set points of the using x, y coordinates.
void	set_values (const std::vector< float > &new_values)
	Set new values for the cloud points.
void	set_values (float new_value)
	Set a single value for all cloud points.
void	set_values_from_array (const Array &array, const glm::vec4 &bbox={0.f, 1.f, 0.f, 1.f})
	Set the values of the cloud points using values from an underlying array.
void	set_values_from_border_distance (const glm::vec4 &bbox={0.f, 1.f, 0.f, 1.f})
	Sets point values based on their distance to the bounding box border.
void	set_values_from_chull_distance ()
	Set the values of the cloud points based on the distance to the convex hull of the cloud.
void	set_values_from_min_distance ()
	Sets point values based on the distance to their nearest neighbor.
size_t	size () const
	Get the number of points in the cloud.
void	clear ()
	Clear all data from the cloud.
void	print ()
	Print information about the cloud's points.
void	randomize (uint seed, glm::vec4 bbox={0.f, 1.f, 0.f, 1.f})
	Randomize the positions and values of the cloud points.
void	remap_values (float vmin, float vmax)
	Remap the values of the cloud points to a target range.
void	shuffle (float dx, float dy, uint seed, float dv=0.f)
	Randomly perturbs the positions and values of all points in the cloud.
void	snap_points_to_bounding_box (const glm::vec4 &bbox={0.f, 1.f, 0.f, 1.f}, float tolerance_ratio=1.f)
	Snap points to the bounding box edges and corners.
bool	from_csv (const std::string &fname)
	Loads point data from a CSV file into the Cloud object.
void	to_array (Array &array, glm::vec4 bbox={0.f, 1.f, 0.f, 1.f}) const
	Project the cloud points onto an array.
Array	to_array (glm::ivec2 shape, glm::vec4 bbox) const
	See hmap::to_array.
void	to_array_interp (Array &array, glm::vec4 bbox={0.f, 1.f, 0.f, 1.f}, InterpolationMethod2D interpolation_method=InterpolationMethod2D::ITP2D_DELAUNAY, Array *p_noise_x=nullptr, Array *p_noise_y=nullptr, glm::vec4 bbox_array={0.f, 1.f, 0.f, 1.f}) const
	Interpolate the values of an array using the cloud points.
void	to_csv (const std::string &fname) const
	Export the cloud data to a CSV file.
Graph	to_graph_delaunay ()
	Convert the cloud to a graph using Delaunay triangulation.
void	to_png (const std::string &fname, int cmap, glm::vec4 bbox={0.f, 1.f, 0.f, 1.f}, int depth=CV_8U, glm::ivec2 shape={512, 512})
	Saves the current data as a PNG image file.
std::vector< glm::vec3 >	to_vec3 () const
	Convert path points to a vector of 3D positions.

Public Attributes
std::vector< Point >	points = {}
	Points of the cloud.

Detailed Description

Represents a collection of unordered points in 2D space.

The Cloud class provides functionality to manage and manipulate an unordered set of points in a 2D space. It supports various operations such as adding points, calculating the centroid, merging with other point clouds, and more. This class is useful for applications involving point cloud processing, geometric computations, and spatial analysis.

See unit tests: test_cloud.cpp

Constructor & Destructor Documentation

Cloud() [1/7]

hmap::Cloud::Cloud ( )

inline

Default constructor for the Cloud class.

Initializes an empty cloud with no points.

~Cloud()

virtual hmap::Cloud::~Cloud ( )

virtualdefault

Cloud() [2/7]

hmap::Cloud::Cloud	(	int	npoints,
		uint	seed,
		glm::vec4	bbox = {0.f, 1.f, 0.f, 1.f}
	)

Constructs a new Cloud object with random positions and values.

Parameters

npoints	Number of points to generate.
seed	Random seed used to generate the points. Using the same seed will produce the same set of points.
bbox	Bounding box within which the points will be generated. The bounding box is defined as {xmin, xmax, ymin, ymax}.

Cloud() [3/7]

hmap::Cloud::Cloud ( const std::vector< Point > &  points )

inline

Constructs a new Cloud object based on a list of existing points.

Parameters

points

A vector of Point objects representing the cloud's points.

Cloud() [4/7]

hmap::Cloud::Cloud	(	const std::vector< float > &	x,
		const std::vector< float > &	y,
		float	default_value = 0.f
	)

Constructs a new Cloud object from lists of x and y coordinates.

Parameters

x	A vector of x coordinates for the points.
y	A vector of y coordinates for the points.
default_value	The default value assigned to each point. Defaults to 0 if not specified.

Cloud() [5/7]

hmap::Cloud::Cloud	(	const std::vector< float > &	x,
		const std::vector< float > &	y,
		const std::vector< float > &	v
	)

Constructs a new Cloud object from lists of x and y coordinates with assigned values.

Parameters

x	A vector of x coordinates for the points.
y	A vector of y coordinates for the points.
v	A vector of values associated with each point.

Cloud() [6/7]

hmap::Cloud::Cloud	(	const std::vector< glm::ivec2 > &	indices,
		const glm::ivec2 &	shape,
		const glm::vec4 &	bbox = {0.f, 1.f, 0.f, 1.f}
	)

Construct a point cloud from grid indices mapped to a bounding box.

Each index is normalized by the grid shape and remapped to the given bounding box. The resulting points are stored as 3D positions (z = 1).

Parameters

indices	Input grid indices.
shape	Grid dimensions.
bbox	Bounding box (xmin, xmax, ymin, ymax).

Cloud() [7/7]

hmap::Cloud::Cloud

(

const std::vector< glm::vec3 > &

xyv

)

Constructs a new Cloud object from lists of xyz data as glm::vec3.

Member Function Documentation

add_point()

void hmap::Cloud::add_point

(

const Point &

p

)

Add a new point to the cloud.

Parameters

p	The point to be added to the cloud.

remove_point()

void hmap::Cloud::remove_point

(

int

point_idx

)

Remove a point from the cloud.

Parameters

point_idx

Index of the point to be removed.

get_bbox()

glm::vec4 hmap::Cloud::get_bbox

(

)

const

Get the bounding box of the cloud.

Returns

glm::vec4 The bounding box of the cloud in the format [xmin, xmax, ymin, ymax].

get_center()

Point hmap::Cloud::get_center

(

)

const

Calculates the centroid of a set of points.

This function computes the center (or centroid) of a collection of points by averaging their coordinates. It sums up all the point coordinates and then divides the result by the total number of points to obtain the average position. The centroid represents the geometric center of the point cloud.

Returns

Point The computed center, represented as a Point object, which contains the average (x, y) coordinates of the points.

get_convex_hull()

std::vector< int > hmap::Cloud::get_convex_hull

(

)

const

Computes the indices of the points that form the convex hull of a set of points.

Returns

std::vector<int> A vector containing the indices of the points that make up the convex hull, listed in order.

Example

#include "highmap.hpp"
 
int main(void)
{
  glm::ivec2 shape = {256, 256};
  int        seed = 1;
 
  glm::vec4 bbox = {-1.f, 0.f, 0.5f, 1.5f};
 
  hmap::Cloud cloud = hmap::Cloud(10, seed, bbox);
 
  cloud.print();
 
  hmap::Array z0 = hmap::Array(shape);
  cloud.to_array(z0, bbox);
 
  std::vector<int> idx = cloud.get_convex_hull();
 
  // create a polyline to display the chull
  std::vector<float> x, y, v;
 
  for (int k : idx)
  {
    x.push_back(cloud.points[k].x);
    y.push_back(cloud.points[k].y);
    v.push_back(cloud.points[k].v);
  }
  hmap::Path path_chull = hmap::Path(x, y, v);
  path_chull.set_closed(true);
 
  hmap::Array z1 = z0;
  path_chull.to_array(z1, bbox);
 
  hmap::export_banner_png("ex_cloud_get_convex_hull.png",
                          {z0, z1},
                          hmap::Cmap::INFERNO);
}

Result

get_values()

std::vector< float > hmap::Cloud::get_values

(

)

const

Get the values assigned to the points in the cloud.

Returns

std::vector<float> A vector containing the values of all points in the cloud.

get_values_max()

float hmap::Cloud::get_values_max

(

)

const

Get the maximum value among the points in the cloud.

Returns

float The maximum value among the points.

get_values_min()

float hmap::Cloud::get_values_min

(

)

const

Get the minimum value among the points in the cloud.

Returns

float The minimum value among the points.

get_x()

std::vector< float > hmap::Cloud::get_x

(

)

const

Get the x coordinates of the points in the cloud.

Returns

std::vector<float> A vector containing the x coordinates of the points.

get_xy()

std::vector< float > hmap::Cloud::get_xy

(

)

const

Get the concatenated x and y coordinates of the points in the cloud.

This method returns a vector containing the x and y coordinates of all points in the cloud, arranged in the form [x0, y0, x1, y1, ...].

Returns

std::vector<float> A vector containing the concatenated x and y coordinates of the points.

get_y()

std::vector< float > hmap::Cloud::get_y

(

)

const

Get the y coordinates of the points in the cloud.

Returns

std::vector<float> A vector containing the y coordinates of the points.

nearest_point()

size_t hmap::Cloud::nearest_point

(

const glm::vec2 &

xy

)

const

Find the index of the nearest point in the cloud.

Computes the point whose (x,y) position is closest to xy using squared Euclidean distance.

Note

This implementation is not optimized and is intended for occasional single queries. It performs a linear search and is not suitable for large-scale or repeated nearest-neighbor queries.

Parameters

xy	Query position

Returns

Index of the nearest point

set_points()

void hmap::Cloud::set_points	(	const std::vector< float > &	x,
		const std::vector< float > &	y
	)

Set points of the using x, y coordinates.

Parameters

x	A vector containing the x coordinates of the points.
y	A vector containing the y coordinates of the points.

set_values() [1/2]

void hmap::Cloud::set_values

(

const std::vector< float > &

new_values

)

Set new values for the cloud points.

Parameters

new_values

A vector of new values to assign to the points.

set_values() [2/2]

void hmap::Cloud::set_values

(

float

new_value

)

Set a single value for all cloud points.

This method assigns the same value to all points in the cloud.

Parameters

new_value

The value to assign to all points.

set_values_from_array()

void hmap::Cloud::set_values_from_array	(	const Array &	array,
		const glm::vec4 &	bbox = {0.f, 1.f, 0.f, 1.f}
	)

Set the values of the cloud points using values from an underlying array.

This method assigns values to the cloud points by interpolating values from an input array. The positions of the cloud points are mapped to the array using the specified bounding box.

Parameters

array	The input array from which to derive the values.
bbox	The bounding box that defines the mapping from the cloud points' coordinates to the array's coordinates.

set_values_from_border_distance()

void hmap::Cloud::set_values_from_border_distance

(

const glm::vec4 &

bbox = {0.f, 1.f, 0.f, 1.f}

)

Sets point values based on their distance to the bounding box border.

For each point in the cloud, this method computes the shortest distance to the edges of the given bounding box and stores it as the point's value.

Parameters

bbox	Bounding box in the format {xmin, xmax, ymin, ymax}.

set_values_from_chull_distance()

void hmap::Cloud::set_values_from_chull_distance

(

)

Set the values of the cloud points based on the distance to the convex hull of the cloud.

This method assigns values to the cloud points based on their distance to the convex hull of the cloud. The convex hull must be initialized using to_graph_delaunay() before this method is called to ensure the correct indices of the convex hull points are available.

set_values_from_min_distance()

void hmap::Cloud::set_values_from_min_distance

(

)

Sets point values based on the distance to their nearest neighbor.

size()

size_t hmap::Cloud::size

(

)

const

Get the number of points in the cloud.

Returns

size_t The number of points in the cloud.

clear()

void hmap::Cloud::clear

(

)

Clear all data from the cloud.

print()

void hmap::Cloud::print

(

)

Print information about the cloud's points.

randomize()

void hmap::Cloud::randomize	(	uint	seed,
		glm::vec4	bbox = {0.f, 1.f, 0.f, 1.f}
	)

Randomize the positions and values of the cloud points.

Parameters

seed	Random seed number for generating positions and values.
bbox	Bounding box within which the points will be randomized.

remap_values()

void hmap::Cloud::remap_values	(	float	vmin,
		float	vmax
	)

Remap the values of the cloud points to a target range.

Parameters

vmin	The lower bound of the target range.
vmax	The upper bound of the target range.

shuffle()

void hmap::Cloud::shuffle	(	float	dx,
		float	dy,
		uint	seed,
		float	dv = 0.f
	)

Randomly perturbs the positions and values of all points in the cloud.

Parameters

dx	Scale factor for the random displacement along the X-axis.
dy	Scale factor for the random displacement along the Y-axis.
seed	Seed value for the pseudo-random number generator, ensuring reproducibility.
dv	Scale factor for the random displacement applied to the point's value component v.

snap_points_to_bounding_box()

void hmap::Cloud::snap_points_to_bounding_box	(	const glm::vec4 &	bbox = {0.f, 1.f, 0.f, 1.f},
		float	tolerance_ratio = 1.f
	)

Snap points to the bounding box edges and corners.

Points within a tolerance distance from the bounding box edges are projected onto the closest edge. Afterwards, the closest point to each corner is snapped exactly to that corner.

Parameters

bbox	Bounding box defined as (xmin, xmax, ymin, ymax).
tolerance_ratio	Ratio used to compute the snapping distance relative to the average point spacing.

from_csv()

bool hmap::Cloud::from_csv

(

const std::string &

fname

)

Loads point data from a CSV file into the Cloud object.

This function reads a CSV file where each line contains either 2D (X, Y) or 3D (X, Y, Z) point data. The function automatically detects the dimensionality of the points based on the number of values per line. The loaded points are stored in the points member of the Cloud object.

Parameters

fname

The path to the CSV file to be read.

Returns

true if the file was successfully read and the points were loaded, false otherwise.

Note

The CSV file must be well-formed, with each line containing either 2 or 3 comma-separated values. Lines with an unexpected number of values will cause the function to return false.

Warning

If the file cannot be opened or contains invalid data (e.g., non-numeric values), the function will log an error and return false.

to_array() [1/2]

void hmap::Cloud::to_array	(	Array &	array,
		glm::vec4	bbox = {0.f, 1.f, 0.f, 1.f}
	)		const

Project the cloud points onto an array.

This method projects the cloud points' values onto a given array, mapping their positions within the specified bounding box. The resulting array will be populated with the values of the points at their corresponding positions.

Parameters

array	The input array where the cloud points' values will be projected.
bbox	The bounding box that defines the mapping from the cloud points' coordinates to the array's coordinates.

to_array() [2/2]

Array hmap::Cloud::to_array	(	glm::ivec2	shape,
		glm::vec4	bbox
	)		const

See hmap::to_array.

to_array_interp()

void hmap::Cloud::to_array_interp	(	Array &	array,
		glm::vec4	bbox = {0.f, 1.f, 0.f, 1.f},
		InterpolationMethod2D	interpolation_method = InterpolationMethod2D::ITP2D_DELAUNAY,
		Array *	p_noise_x = nullptr,
		Array *	p_noise_y = nullptr,
		glm::vec4	bbox_array = {0.f, 1.f, 0.f, 1.f}
	)		const

Interpolate the values of an array using the cloud points.

This method populates an array with interpolated values based on the positions and values of the cloud points. The interpolation method can be specified, and optional noise arrays can be used for domain warping.

Parameters

array	The output array that will be populated with interpolated values.
bbox	The bounding box that defines the cloud's coordinate system.
interpolation_method	The method used for interpolation (e.g., nearest neighbor, bilinear).
p_noise_x	Optional reference to a noise array applied to the x-coordinates for domain warping (not in pixels).
p_noise_y	Optional reference to a noise array applied to the y-coordinates for domain warping (not in pixels).
bbox_array	The bounding box of the destination array.

Example

#include "highmap.hpp"
 
int main(void)
{
  glm::ivec2 shape = {256, 256};
  int        seed = 1;
 
  glm::vec4 bbox = {-1.f, 0.f, 0.5f, 1.5f};
 
  hmap::Cloud cloud = hmap::Cloud(10, seed, bbox);
 
  hmap::Array z0 = hmap::Array(shape);
  cloud.to_array(z0, bbox);
 
  hmap::Array z1 = hmap::Array(shape);
  cloud.to_array_interp(z1,
                        bbox,
                        hmap::InterpolationMethod2D::ITP2D_NEAREST,
                        nullptr,
                        nullptr,
                        bbox);
 
  hmap::Array nx = 0.5f * hmap::noise_fbm(hmap::NoiseType::PERLIN,
                                          shape,
                                          {2.f, 2.f},
                                          seed++);
  hmap::Array ny = 0.5f * hmap::noise_fbm(hmap::NoiseType::PERLIN,
                                          shape,
                                          {2.f, 2.f},
                                          seed++);
 
  hmap::Array z2 = hmap::Array(shape);
  hmap::Array z3 = hmap::Array(shape);
 
  cloud.to_array_interp(z2,
                        bbox,
                        hmap::InterpolationMethod2D::ITP2D_NEAREST,
                        &nx,
                        &ny,
                        bbox);
  cloud.to_array_interp(z3,
                        bbox,
                        hmap::InterpolationMethod2D::ITP2D_DELAUNAY,
                        &nx,
                        &ny,
                        bbox);
 
  hmap::export_banner_png("ex_cloud_to_array_interp.png",
                          {z0, z1, z2, z3},
                          hmap::Cmap::INFERNO);
}

Result

to_csv()

void hmap::Cloud::to_csv

(

const std::string &

fname

)

const

Export the cloud data to a CSV file.

Parameters

fname

The name of the output CSV file.

to_graph_delaunay()

Graph hmap::Cloud::to_graph_delaunay

(

)

Convert the cloud to a graph using Delaunay triangulation.

Returns

Graph The resulting graph from Delaunay triangulation.

to_png()

void hmap::Cloud::to_png	(	const std::string &	fname,
		int	cmap,
		glm::vec4	bbox = {0.f, 1.f, 0.f, 1.f},
		int	depth = CV_8U,
		glm::ivec2	shape = {512, 512}
	)

Saves the current data as a PNG image file.

Parameters

fname	The file name for the output PNG image. This should include the file extension (e.g., "output.png").
cmap	An integer specifying the colormap to be used for rendering the data. This index refers to a predefined colormap.
bbox	A glm::vec4 specifying the bounding box of the data to be included in the image. It is given as {xmin, xmax, ymin, ymax}. The default is {0.f, 1.f, 0.f, 1.f}.
depth	An integer specifying the bit depth of the image. It should be a value defined by OpenCV (e.g., CV_8U for 8-bit unsigned). The default is CV_8U.
shape	A glm::ivec2 specifying the dimensions of the output image. It is given as {width, height}. The default is {512, 512}.

to_vec3()

std::vector< glm::vec3 > hmap::Cloud::to_vec3

(

)

const

Convert path points to a vector of 3D positions.

Returns

Vector of points as (x, y, v).

Member Data Documentation

points

std::vector<Point> hmap::Cloud::points = {}

Points of the cloud.

---

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

• HighMap/include/highmap/geometry/cloud.hpp
• HighMap/src/geometry/cloud.cpp