Represents an ordered set of points in 2D, forming a polyline (open or closed). More...

#include <path.hpp>

Inheritance diagram for hmap::Path:

Collaboration diagram for hmap::Path:

[legend]

Public Types
enum class	EdgeDivisionMode : int { EDM_PER_EDGE , EDM_FULL_ARC }

Public Member Functions
	Path ()=default
	Construct a new Path object with default properties. Initializes an empty path with the `closed` property set to `false`.

	Path (int npoints, uint seed, glm::vec4 bbox={0.f, 1.f, 0.f, 1.f})
	Construct a new Path object with random positions and values. Initializes a path with a specified number of points, random values, and the option to be open or closed.

	Path (std::vector< Point > points)
	Construct a new Path object based on a list of points. Initializes a path with the specified points and an option to be open or closed.

	Path (std::vector< float > x, std::vector< float > y)
	Construct a new Path object based on `x` and `y` coordinates. Initializes a path with the specified `x` and `y` coordinates and an option to be open or closed.

	Path (std::vector< float > x, std::vector< float > y, std::vector< float > v)
	Construct a new Path object based on `x`, `y` coordinates, and values. Initializes a path with the specified `x` and `y` coordinates, associated values, and an option to be open or closed.

	Path (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.

	Path (const std::vector< glm::vec3 > &xyv)
	Constructs a new Path object from lists of xyz data as glm::vec3.

std::vector< float >	get_arc_length () const
	Get the arc length of the path.

std::vector< float >	get_cumulative_distance () const
	Get the cumulative distance of the path.

std::vector< float >	get_curvature (bool normalized=false) const
	Computes the signed curvature at each point of the path.

std::vector< Point >	get_edge_centers () const
	Compute midpoints of path edges.

std::vector< glm::vec2 >	get_normals () const
	Computes unit normals at each point of the path.

std::vector< glm::vec2 >	get_tangents () const
	Computes unit tangents at each point of the path.

std::vector< float >	get_values () const
	Get the values assigned to the points on the path.

std::vector< float >	get_x () const
	Get the `x` coordinates of the points on the path.

std::vector< float >	get_xy () const
	Get the coordinates of the points as a single vector.

std::vector< float >	get_y () const
	Get the `y` coordinates of the points on the path.

bool	is_closed () const
	Check whether the path is closed.

void	set_closed (bool new_value)
	Set whether the path is closed.

void	clear ()
	Clear the path data.

void	enforce_monotonic_values (bool decreasing=true)
	Enforces monotonicity on the values of the points in the path.

void	reorder_nns (int start_index=0)
	Reorder points using a nearest neighbor search.

void	reverse ()
	Reverse the order of points in the path.

void	divide ()
	Divide the path by adding a point between each pair of consecutive points.

void	resample_by_spacing (float delta, InterpolationMethod1D itp_method=InterpolationMethod1D::LINEAR)
	Resample the path to achieve an approximately constant distance between points.

void	resample_interp (int npoints, InterpolationMethod1D itp_method=InterpolationMethod1D::CUBIC)
	Resamples the path using cubic interpolation along arc length.

void	resample_uniform (InterpolationMethod1D itp_method=InterpolationMethod1D::LINEAR)
	Resample the path to achieve fairly uniform distance between consecutive points.

void	subsample (int step)
	Subsample the path by keeping only every n-th point.

void	to_array (Array &array, glm::vec4 bbox={0.f, 1.f, 0.f, 1.f}, bool filled=false) const
	Project path points to an array.

Array	to_array (glm::ivec2 shape, glm::vec4 bbox={0.f, 1.f, 0.f, 1.f}, bool filled=false) const
	See hmap::to_array.

void	to_array_mask (Array &array, glm::vec4 bbox={0.f, 1.f, 0.f, 1.f}, bool filled=false) const
	See hmap::to_array.

void	to_png (std::string fname, glm::ivec2 shape={512, 512})
	Export path as PNG image file.

Public Member Functions inherited from hmap::Cloud
	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.

Additional Inherited Members
Public Attributes inherited from hmap::Cloud
std::vector< Point >	points = {}
	Points of the cloud.

Detailed Description

Represents an ordered set of points in 2D, forming a polyline (open or closed).

The Path class extends the Cloud class to represent a sequence of points in 2D space that are connected in a specific order, forming a polyline. The polyline can be either open or closed, depending on whether the first and last points are connected. This class provides methods for various geometric operations, including path length calculation, point insertion, and more.

Example

#include "highmap.hpp"
 
int main(void)
{
  glm::ivec2 shape = {256, 256};
  int        seed = 1;
 
  glm::vec4 bbox = {-1.f, 2.f, 0.f, 5.f};
 
  // --- open path with (x, y) and values defined as vectors
 
  hmap::Path path = hmap::Path({-0.5f, 1.5f, 0.5f}, // x
                               {1.f, 2.f, 4.f},     // y
                               {0.f, 1.f, 2.f}      // values
  );
 
  hmap::Array z1 = hmap::Array(shape);
  path.to_array(z1, bbox);
 
  // --- generate a closed path using a random set of points
  int npoints = 5;
  path = hmap::Path(npoints, seed, bbox);
  path.set_closed(true);
 
  path.reorder_nns(); // reorder points to get a better look
 
  hmap::Array z2 = hmap::Array(shape);
  path.to_array(z2, bbox);
 
  // fractalize
  int   iterations = 4;
  float sigma = 0.3f;
 
  path.resample_uniform(); // to ensure a "uniform" output
  path = hmap::fractalize(path, iterations, seed, sigma);
 
  hmap::Array z3 = hmap::Array(shape);
  path.to_array(z3, bbox);
 
  hmap::export_banner_png("ex_path.png", {z1, z2, z3}, hmap::Cmap::INFERNO);
}

Result

Member Enumeration Documentation

◆ EdgeDivisionMode

enum class hmap::Path::EdgeDivisionMode : int

strong

Enumerator
EDM_PER_EDGE
EDM_FULL_ARC

Constructor & Destructor Documentation

◆ Path() [1/7]

hmap::Path::Path ( )

default

Construct a new Path object with default properties. Initializes an empty path with the closed property set to false.

◆ Path() [2/7]

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

inline

Construct a new Path object with random positions and values. Initializes a path with a specified number of points, random values, and the option to be open or closed.

Parameters

npoints	Number of points to generate.
seed	Random seed number for generating random values.
bbox	Bounding box for random point generation.

◆ Path() [3/7]

hmap::Path::Path ( std::vector< Point > points )

inline

Construct a new Path object based on a list of points. Initializes a path with the specified points and an option to be open or closed.

Parameters

points List of points defining the path.

◆ Path() [4/7]

hmap::Path::Path	(	std::vector< float >	x,
		std::vector< float >	y
	)

inline

Construct a new Path object based on x and y coordinates. Initializes a path with the specified x and y coordinates and an option to be open or closed.

Parameters

x	List of `x` coordinates for the points.
y	List of `y` coordinates for the points.

◆ Path() [5/7]

hmap::Path::Path	(	std::vector< float >	x,
		std::vector< float >	y,
		std::vector< float >	v
	)

inline

Construct a new Path object based on x, y coordinates, and values. Initializes a path with the specified x and y coordinates, associated values, and an option to be open or closed.

Parameters

x	List of `x` coordinates for the points.
y	List of `y` coordinates for the points.
v	List of values associated with the points.

◆ Path() [6/7]

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

inline

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). Default is {0.f, 1.f, 0.f, 1.f}.

◆ Path() [7/7]

hmap::Path::Path ( const std::vector< glm::vec3 > & xyv )

inline

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

Member Function Documentation

◆ get_arc_length()

std::vector< float > hmap::Path::get_arc_length ( ) const

Get the arc length of the path.

The arc length is the cumulative distance along the path, normalized to the range [0, 1]. This represents the distance traveled from the start to each point along the path as a fraction of the total path length.

Returns: std::vector<float> Vector of arc length values, where each entry corresponds to a point on the path and represents the normalized distance from the start of the path to that point.

◆ get_cumulative_distance()

std::vector< float > hmap::Path::get_cumulative_distance ( ) const

Get the cumulative distance of the path.

This method computes the cumulative distance along the path, which is the total distance traveled up to each point on the path. It accumulates the distances from the start of the path to each point.

Returns: std::vector<float> Vector of cumulative distance values, where each entry represents the distance from the start of the path to the respective point.

◆ get_curvature()

std::vector< float > hmap::Path::get_curvature ( bool normalized = false ) const

Computes the signed curvature at each point of the path.

Parameters

normalized If true, scales values to [-1, 1] using the maximum absolute curvature.

Returns: Vector of curvature values.

◆ get_edge_centers()

std::vector< Point > hmap::Path::get_edge_centers ( ) const

Compute midpoints of path edges.

Returns the midpoint of each segment between consecutive points.

Returns: Vector of edge center points.

◆ get_normals()

std::vector< glm::vec2 > hmap::Path::get_normals ( ) const

Computes unit normals at each point of the path.

Returns: Vector of normal vectors.

◆ get_tangents()

std::vector< glm::vec2 > hmap::Path::get_tangents ( ) const

Computes unit tangents at each point of the path.

Returns: Vector of tangent vectors.

◆ get_values()

std::vector< float > hmap::Path::get_values ( ) const

Get the values assigned to the points on the path.

This method retrieves the values assigned to each point on the path. These values can represent any attribute associated with the points, such as color, intensity, or other metrics.

Returns: std::vector<float> Vector of values assigned to the points on the path.

◆ get_x()

std::vector< float > hmap::Path::get_x ( ) const

Get the x coordinates of the points on the path.

This method retrieves the x coordinates of all points in the path. Each value in the returned vector corresponds to the x coordinate of a point along the path.

Returns: std::vector<float> Vector of x values of the points on the path.

◆ get_xy()

std::vector< float > hmap::Path::get_xy ( ) const

Get the coordinates of the points as a single vector.

This method returns the coordinates of the points in the path as a single vector, where the coordinates are interleaved: (x0, y0, x1, y1, ...). This format is useful for operations that require a flat representation of the coordinates.

Returns: std::vector<float> Vector of interleaved x and y coordinates of the points on the path.

◆ get_y()

std::vector< float > hmap::Path::get_y ( ) const

Get the y coordinates of the points on the path.

This method retrieves the y coordinates of all points in the path. Each value in the returned vector corresponds to the y coordinate of a point along the path.

Returns: std::vector<float> Vector of y values of the points on the path.

◆ is_closed()

bool hmap::Path::is_closed ( ) const

Check whether the path is closed.

Returns: True if the path is closed, false otherwise.

◆ set_closed()

void hmap::Path::set_closed ( bool new_value )

Set whether the path is closed.

Parameters

new_value True to close the path, false to keep it open.

◆ clear()

void hmap::Path::clear ( )

Clear the path data.

This method removes all points and associated data from the path, effectively resetting it to an empty state.

◆ enforce_monotonic_values()

void hmap::Path::enforce_monotonic_values ( bool decreasing = true )

Enforces monotonicity on the values of the points in the path.

This method adjusts the v values of the points in the path to ensure that they are either monotonically decreasing or increasing, based on the input parameter.

Parameters

decreasing If true, enforces a monotonically decreasing order for the values. If false, enforces a monotonically increasing order for the values.

Note: This method modifies the path in place.

◆ reorder_nns()

void hmap::Path::reorder_nns ( int start_index = 0 )

Reorder points using a nearest neighbor search.

This method reorders the points in the path to minimize the total distance by performing a nearest neighbor search starting from the specified start_index. This approach is useful for optimizing the path or improving its order.

Parameters

start_index Index of the starting point for the nearest neighbor search. Default is 0.

◆ reverse()

void hmap::Path::reverse ( )

Reverse the order of points in the path.

This method reverses the sequence of points in the path, which can be useful for various applications, such as changing the direction of the path traversal.

◆ divide()

void hmap::Path::divide ( )

Divide the path by adding a point between each pair of consecutive points.

This method adds new points in the middle of each segment of the path to create a denser set of points along the path. This is useful for increasing the resolution of the path.

◆ resample_by_spacing()

void hmap::Path::resample_by_spacing	(	float	delta,
		InterpolationMethod1D	itp_method = `InterpolationMethod1D::LINEAR`
	)

Resample the path to achieve an approximately constant distance between points.

This method adjusts the points in the path to ensure that the distance between each consecutive point is approximately equal to the specified delta. This is useful for creating a path with evenly spaced points.

Parameters

delta	Target distance between consecutive points.
itp_method	Interpolation method used to resample the path.

◆ resample_interp()

void hmap::Path::resample_interp	(	int	npoints,
		InterpolationMethod1D	itp_method = `InterpolationMethod1D::CUBIC`
	)

Resamples the path using cubic interpolation along arc length.

The path is reparameterized by arc length and interpolated using cubic splines for x, y, and value components.

Parameters

npoints	Number of points to resample.
itp_method	Interpolation method to use (default is CUBIC).

Example

#include "highmap.hpp"
 
int main(void)
{
  glm::ivec2 shape = {256, 256};
  int        seed = 0;
 
  glm::vec4  bbox = {1.f, 2.f, -0.5f, 0.5f};
  hmap::Path path = hmap::Path(10, seed, {1.2f, 1.8f, -0.3, 0.3f});
  path.reorder_nns();
 
  const int npoints = 100;
 
  const std::vector<hmap::InterpolationMethod1D> methods = {
      hmap::InterpolationMethod1D::AKIMA,
      hmap::InterpolationMethod1D::AKIMA_PERIODIC,
      hmap::InterpolationMethod1D::CUBIC,
      hmap::InterpolationMethod1D::CUBIC_PERIODIC,
      hmap::InterpolationMethod1D::LINEAR,
      // hmap::InterpolationMethod1D::POLYNOMIAL, // severe overshoot
      // hmap::InterpolationMethod1D::STEFFEN // cannot be used
  };
 
  std::vector<hmap::Array> arrays;
 
  // --- Open path
 
  path.set_closed(false);
 
  // original path
  arrays.clear();
  arrays.push_back(path.to_array(shape, bbox));
 
  for (const auto method : methods)
  {
    hmap::Path path_copy = path;
    path_copy.resample_interp(npoints, method);
 
    // plot to an array
    arrays.push_back(path_copy.to_array(shape, bbox));
  }
 
  hmap::export_banner_png("ex_path_resample0.png", arrays, hmap::Cmap::INFERNO);
 
  // --- Closed path
 
  path.set_closed(true);
 
  // original path
  arrays.clear();
  arrays.push_back(path.to_array(shape, bbox));
 
  for (const auto method : methods)
  {
    hmap::Path path_copy = path;
    path_copy.resample_interp(npoints, method);
 
    // plot to an array
    arrays.push_back(path_copy.to_array(shape, bbox));
  }
 
  hmap::export_banner_png("ex_path_resample1.png", arrays, hmap::Cmap::INFERNO);
 
  // --- Wrappers
 
  path.set_closed(false);
 
  arrays.clear();
  arrays.push_back(path.to_array(shape, bbox));
 
  {
    hmap::Path path_copy = path;
    path_copy.resample_uniform();
    arrays.push_back(path_copy.to_array(shape, bbox));
  }
 
  {
    hmap::Path path_copy = path;
    path_copy.resample_by_spacing(0.01f);
    arrays.push_back(path_copy.to_array(shape, bbox));
  }
 
  hmap::export_banner_png("ex_path_resample2.png", arrays, hmap::Cmap::INFERNO);
}

Result

◆ resample_uniform()

void hmap::Path::resample_uniform ( InterpolationMethod1D itp_method = InterpolationMethod1D::LINEAR )

Resample the path to achieve fairly uniform distance between consecutive points.

This method adjusts the path so that the distance between each consecutive point is as uniform as possible. It redistributes the points to ensure more even spacing along the path.

Parameters

itp_method Interpolation method used for resampling.

◆ subsample()

void hmap::Path::subsample ( int step )

Subsample the path by keeping only every n-th point.

This method reduces the number of points in the path by retaining only every 'step'-th point, effectively subsampling the path. This can be useful for simplifying the path or reducing data size.

Parameters

step	The interval of points to keep. For example, a step of 2 will keep every second point.

◆ to_array() [1/2]

void hmap::Path::to_array	(	Array &	array,
		glm::vec4	bbox = `{0.f, 1.f, 0.f, 1.f}`,
		bool	filled = `false`
	)		const

Project path points to an array.

This method projects the points of the path onto a 2D array, filling the array based on the path's points. Optionally, the contour of the path can be filled using flood fill if the filled parameter is set to true.

Example

Parameters

array	The array to which the path points will be projected.
bbox	Bounding box defining the domain of the array.
filled	Boolean flag indicating whether to perform flood filling of the path's contour.

◆ to_array() [2/2]

Array hmap::Path::to_array	(	glm::ivec2	shape,
		glm::vec4	bbox = `{0.f, 1.f, 0.f, 1.f}`,
		bool	filled = `false`
	)		const

See hmap::to_array.

◆ to_array_mask()

void hmap::Path::to_array_mask	(	Array &	array,
		glm::vec4	bbox = `{0.f, 1.f, 0.f, 1.f}`,
		bool	filled = `false`
	)		const

See hmap::to_array.

◆ to_png()

void hmap::Path::to_png	(	std::string	fname,
		glm::ivec2	shape = `{512, 512}`
	)

Export path as PNG image file.

This method generates a PNG image representing the path and saves it to the specified file. The resolution of the image can be adjusted using the shape parameter.

Example

Parameters

fname	The filename for the output PNG image.
shape	Resolution of the image, specified as width and height. Default is {512, 512}.

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

HighMap/include/highmap/geometry/path.hpp
HighMap/src/geometry/path.cpp

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ EdgeDivisionMode

Constructor & Destructor Documentation

◆ Path() [1/7]

◆ Path() [2/7]

◆ Path() [3/7]

◆ Path() [4/7]

◆ Path() [5/7]

◆ Path() [6/7]

◆ Path() [7/7]

Member Function Documentation

◆ get_arc_length()

◆ get_cumulative_distance()

◆ get_curvature()

◆ get_edge_centers()

◆ get_normals()

◆ get_tangents()

◆ get_values()

◆ get_x()

◆ get_xy()

◆ get_y()

◆ is_closed()

◆ set_closed()

◆ clear()

◆ enforce_monotonic_values()

◆ reorder_nns()

◆ reverse()

◆ divide()

◆ resample_by_spacing()

◆ resample_interp()

◆ resample_uniform()

◆ subsample()

◆ to_array() [1/2]

◆ to_array() [2/2]

◆ to_array_mask()

◆ to_png()