Array class, helper to manipulate 2D float array with "(i, j)" indexing. More...

#include <array.hpp>

Inheritance diagram for hmap::Array:

Collaboration diagram for hmap::Array:

[legend]

Public Member Functions
	Array ()
	Constructs a new Array object.

	Array (Vec2< int > shape)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

	Array (Vec2< int > shape, float value)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

	Array (const std::string &filename)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Array &	operator= (const float value)
	Overloads the assignment operator for scalar assignment.

Array &	operator*= (const float value)
	Overloads the multiplication-assignment operator for scalar multiplication.

Array &	operator*= (const Array &array)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Array &	operator/= (const float value)
	Overloads the division-assignment operator for scalar division.

Array &	operator/= (const Array &array)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Array &	operator+= (const float value)
	Overloads the addition-assignment operator for scalar addition.

Array &	operator+= (const Array &array)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Array &	operator-= (const float value)
	Overloads the subtraction-assignment operator for scalar subtraction.

Array &	operator-= (const Array &array)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Array	operator* (const float value) const
	Overloads the multiplication operator for scalar multiplication.

Array	operator* (const Array &array) const
	Overloads the multiplication operator for element-wise multiplication with another array.

Array	operator/ (const float value) const
	Overloads the division operator for scalar division.

Array	operator/ (const Array &array) const
	Overloads the division operator for element-wise division by another array.

Array	operator+ (const float value) const
	Overloads the addition operator for scalar addition.

Array	operator+ (const Array &array) const
	Overloads the addition operator for element-wise addition with another array.

Array	operator- () const
	Overloads the unary minus operator.

Array	operator- (const float value) const
	Overloads the subtraction operator for scalar subtraction.

Array	operator- (const Array &array) const
	Overloads the subtraction operator for element-wise subtraction with another array.

float &	operator() (int i, int j)
	Overloads the function call operator to access the array value at index (i, j).

const float &	operator() (int i, int j) const
	Overloads the function call operator to access the array value at index (i, j) (const version).

std::vector< float >	col_to_vector (int j)
	Extracts a column 'j' as a std::vector.

int	count_non_zero ()
	Return the number of non-zero elements in the array.

void	depose_amount_bilinear_at (int i, int j, float u, float v, float amount)
	Distribute a value 'amount' around the four cells (i, j), (i + 1, j), (i, j + 1), (i + 1, j + 1) by "reversing" the bilinear interpolation.

void	depose_amount_kernel_bilinear_at (int i, int j, float u, float v, int ir, float amount)

void	depose_amount_kernel_at (int i, int j, const Array &kernel, float amount)
	Distributes a specified amount of value around the cell located at (i, j) using a 1D deposition kernel applied in both horizontal and vertical directions.

void	dump (const std::string &fname="out.png") const
	Debug tool, dump some infos and generate an output file (16bits grayscale)

Array	extract_slice (Vec4< int > idx) const
	Extracts a subarray defined by the slice indices {i1, i2, j1, j2} from the original array, creating a new array. Note that i2 and j2 are excluded from the slice.

Array	extract_slice (int i1, int i2, int j1, int j2) const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void	from_file (const std::string &fname)
	Import array data from a raw binary file.

void	from_numpy (const std::string &fname)
	Import array data from a numpy binary file.

float	get_gradient_x_at (int i, int j) const
	Calculates the gradient in the 'x' (or 'i') direction at a specified index (i, j) using a 2nd order central difference scheme.

float	get_gradient_y_at (int i, int j) const
	Calculates the gradient in the 'y' (or 'j') direction at a specified index (i, j) using a 2nd order central difference scheme.

float	get_gradient_x_bilinear_at (int i, int j, float u, float v) const
	Calculates the gradient in the 'x' (or 'i') direction at a location (x, y) near the index (i, j) using bilinear interpolation.

float	get_gradient_y_bilinear_at (int i, int j, float u, float v) const
	Calculates the gradient in the 'y' (or 'j') direction at a location (x, y) near the index (i, j) using bilinear interpolation.

Vec3< float >	get_normal_at (int i, int j) const
	Calculates the surface normal vector at the index (i, j).

Vec2< int >	get_shape ()
	Retrieves the shape of the array.

size_t	get_sizeof () const
	Retrieves the number of bytes occupied by the array data.

float	get_value_bicubic_at (int i, int j, float u, float v) const
	Retrieves the array value at the location (x, y) near the index (i, j) using bicubic interpolation.

float	get_value_bilinear_at (int i, int j, float u, float v) const
	Retrieves the array value at the location (x, y) near the index (i, j) using bilinear interpolation.

float	get_value_nearest (float x, float y, Vec4< float > bbox)
	Retrieves the nearest value at the location (x, y) within a bounded domain.

std::vector< float >	get_vector () const
	Retrieves the underlying data vector.

void	infos (std::string msg="") const
	Display various information about the array.

int	linear_index (int i, int j) const
	Return the linear index corresponding to the (i, j) cell in a 2D array.

Vec2< int >	linear_index_reverse (int k) const
	Convert a linear index to its corresponding (i, j) cell coordinates.

float	max () const
	Return the value of the greatest element in the array.

float	mean () const
	Return the mean value of the elements in the array.

float	min () const
	Return the value of the smallest element in the array.

void	normalize ()
	Normalize array values so that the sum of all elements is equal to 1.

Vec2< float >	normalization_coeff (float vmin=0.f, float vmax=1.f) const
	Computes normalization coefficients (a, b) such that a * array + b maps the values to the range [vmin, vmax].

void	print () const
	Print the array values to the standard output (stdout).

float	ptp () const
	Return the peak-to-peak amplitude (i.e., the difference between the maximum and minimum values) of the array values.

Array	resample_to_shape (Vec2< int > new_shape) const
	Return a resampled array of shape `new_shape` using bilinear interpolation.

Array	resample_to_shape_bicubic (Vec2< int > new_shape) const
	Return a resampled array of shape `new_shape` using bicubic interpolation.

Array	resample_to_shape_bilinear (Vec2< int > new_shape) const

Array	resample_to_shape_nearest (Vec2< int > new_shape) const
	Return a resampled array of shape `new_shape` using nearest neighbor interpolation.

std::vector< float >	row_to_vector (int i)
	Return a row `i` as a `std::vector<float>`.

void	set_shape (Vec2< int > new_shape)
	Sets a new shape for the array.

void	set_slice (Vec4< int > idx, float value)
	Set the value of a slice defined by indices {i1, i2, j1, j2} to a new value.

void	set_slice (Vec4< int > idx, const Array &array)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

int	size () const
	Return the total number of elements in the array.

float	std () const
	Return the standard deviation of all array values.

float	sum () const
	Return the sum of all array values.

cv::Mat	to_cv_mat ()
	Converts a 2D `Array` to an OpenCV `cv::Mat`.

void	to_exr (const std::string &fname) const
	Export the array as an OpenEXR image file.

void	to_file (const std::string &fname) const
	Export the array to a raw binary file.

void	to_numpy (const std::string &fname) const
	Export the array to a numpy binary file.

void	to_png (const std::string &fname, int cmap, bool hillshading=false, int depth=CV_8U) const
	Export the array as a PNG image file with a specified colormap and hillshading.

void	to_png_grayscale (const std::string &fname, int depth=CV_8U) const
	Export the array as a grayscale PNG image file with specified bit depth.

void	to_tiff (const std::string &fname) const
	Export the array as a TIFF image file.

void	to_raw_16bit (const std::string &fname) const
	Export the array as a 16-bit raw file for Unity terrain import.

std::vector< float >	unique_values ()
	Return the unique elements of the array.

Public Attributes
Vec2< int >	shape
	The shape of the array {ni, nj}.

std::vector< float >	vector
	The underlying data storage, a vector of size shape.x * shape.y.

Friends
Array	operator* (const float value, const Array &array)
	Overloads the multiplication operator for scalar multiplication.

Array	operator/ (const float value, const Array &array)
	Overloads the division operator for scalar division.

Array	operator+ (const float value, const Array &array)
	Overloads the addition operator for scalar addition.

const Array	operator- (const float value, const Array &array)
	Overloads the subtraction operator for scalar subtraction.

Detailed Description

Array class, helper to manipulate 2D float array with "(i, j)" indexing.

Constructor & Destructor Documentation

◆ Array() [1/4]

hmap::Array::Array ( )

Constructs a new Array object.

Parameters

shape	The shape of the array {ni, nj}.
value	The initial value to fill the array with.

Example #1

#include <iostream>
 
#include "highmap.hpp"
 
int main(void)
{
  hmap::Vec2<int> shape = {6, 4};
  hmap::Array     a = hmap::Array(shape);
 
  a = 1.f;
 
  for (int i = 0; i < a.shape.x; i++)
    for (int j = 0; j < a.shape.y; j++)
      std::cout << i << " " << j << " " << a(i, j) << std::endl;
}

Example #2

#include "highmap.hpp"
 
int main(void)
{
 
  const hmap::Vec2<int>   shape = {512, 512};
  const hmap::Vec2<float> res = {4.f, 4.f};
  int                     seed = 2;
 
  // write png
  hmap::Array z1 = hmap::noise_fbm(hmap::NoiseType::PERLIN,
                                   shape,
                                   res,
                                   seed,
                                   8);
  hmap::remap(z1);
  z1.to_png("out_rgb.png", hmap::Cmap::JET);
  z1.to_png_grayscale("out_8bit.png");
  z1.to_png_grayscale("out_16bit.png", CV_16U);
 
  // create Array from png
  hmap::Array z2 = hmap::Array("out_8bit.png");
  hmap::Array z3 = hmap::Array("out_16bit.png");
 
  z1.to_raw_16bit("out.raw");
 
  hmap::export_banner_png("ex_to_png.png", {z1, z2, z3}, hmap::Cmap::INFERNO);
}

◆ Array() [2/4]

hmap::Array::Array ( Vec2< int > shape )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ Array() [3/4]

hmap::Array::Array	(	Vec2< int >	shape,
		float	value
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ Array() [4/4]

hmap::Array::Array ( const std::string & filename )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Member Function Documentation

◆ operator=()

Array & hmap::Array::operator= ( const float value )

Overloads the assignment operator for scalar assignment.

Parameters

value The scalar value to assign.

Returns: Array& Reference to the current Array object.

◆ operator*=() [1/2]

Array & hmap::Array::operator*= ( const float value )

Overloads the multiplication-assignment operator for scalar multiplication.

Parameters

value The scalar value to multiply.

Returns: Array& Reference to the current Array object.

◆ operator*=() [2/2]

Array & hmap::Array::operator*= ( const Array & array )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ operator/=() [1/2]

Array & hmap::Array::operator/= ( const float value )

Overloads the division-assignment operator for scalar division.

Parameters

value The scalar value to divide by.

Returns: Array& Reference to the current Array object.

◆ operator/=() [2/2]

Array & hmap::Array::operator/= ( const Array & array )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ operator+=() [1/2]

Array & hmap::Array::operator+= ( const float value )

Overloads the addition-assignment operator for scalar addition.

Parameters

value The scalar value to add.

Returns: Array& Reference to the current Array object.

◆ operator+=() [2/2]

Array & hmap::Array::operator+= ( const Array & array )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ operator-=() [1/2]

Array & hmap::Array::operator-= ( const float value )

Overloads the subtraction-assignment operator for scalar subtraction.

Parameters

value The scalar value to subtract.

Returns: Array& Reference to the current Array object.

◆ operator-=() [2/2]

Array & hmap::Array::operator-= ( const Array & array )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ operator*() [1/2]

Array hmap::Array::operator* ( const float value ) const

Overloads the multiplication operator for scalar multiplication.

Parameters

value The scalar value to multiply.

Returns: Array The resulting Array after multiplication.

◆ operator*() [2/2]

Array hmap::Array::operator* ( const Array & array ) const

Overloads the multiplication operator for element-wise multiplication with another array.

Parameters

array The Array to multiply with.

Returns: Array The resulting Array after element-wise multiplication.

◆ operator/() [1/2]

Array hmap::Array::operator/ ( const float value ) const

Overloads the division operator for scalar division.

Parameters

value The scalar value to divide by.

Returns: Array The resulting Array after division.

◆ operator/() [2/2]

Array hmap::Array::operator/ ( const Array & array ) const

Overloads the division operator for element-wise division by another array.

Parameters

array The Array to divide by.

Returns: Array The resulting Array after element-wise division.

◆ operator+() [1/2]

Array hmap::Array::operator+ ( const float value ) const

Overloads the addition operator for scalar addition.

Parameters

value The scalar value to add.

Returns: Array The resulting Array after addition.

◆ operator+() [2/2]

Array hmap::Array::operator+ ( const Array & array ) const

Overloads the addition operator for element-wise addition with another array.

Parameters

array The Array to add.

Returns: Array The resulting Array after element-wise addition.

◆ operator-() [1/3]

Array hmap::Array::operator- ( ) const

Overloads the unary minus operator.

Returns: Array The resulting Array after applying the unary minus.

◆ operator-() [2/3]

Array hmap::Array::operator- ( const float value ) const

Overloads the subtraction operator for scalar subtraction.

Parameters

value The scalar value to subtract.

Returns: Array The resulting Array after subtraction.

◆ operator-() [3/3]

Array hmap::Array::operator- ( const Array & array ) const

Overloads the subtraction operator for element-wise subtraction with another array.

Parameters

array The Array to subtract.

Returns: Array The resulting Array after element-wise subtraction.

◆ operator()() [1/2]

float & hmap::Array::operator()	(	int	i,
		int	j
	)

inline

Overloads the function call operator to access the array value at index (i, j).

Parameters

i	The row index.
j	The column index.

Returns: float& Reference to the array value at index (i, j).

◆ operator()() [2/2]

const float & hmap::Array::operator()	(	int	i,
		int	j
	)		const

inline

Overloads the function call operator to access the array value at index (i, j) (const version).

Parameters

i	The row index.
j	The column index.

Returns: const float& Reference to the array value at index (i, j). <This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ col_to_vector()

std::vector< float > hmap::Array::col_to_vector ( int j )

Extracts a column 'j' as a std::vector.

Parameters

j	The column index.

Returns: std::vector<float> The column values as a vector.

◆ count_non_zero()

int hmap::Array::count_non_zero ( )

Return the number of non-zero elements in the array.

Returns: int The number of non-zero elements.

◆ depose_amount_bilinear_at()

void hmap::Array::depose_amount_bilinear_at	(	int	i,
		int	j,
		float	u,
		float	v,
		float	amount
	)

Distribute a value 'amount' around the four cells (i, j), (i + 1, j), (i, j + 1), (i + 1, j + 1) by "reversing" the bilinear interpolation.

Parameters

i	Index.
j	Index.
u	'u' interpolation parameter, expected to be in [0, 1[.
v	'v' interpolation parameter, expected to be in [0, 1[.
amount	Amount to be deposited.

◆ depose_amount_kernel_bilinear_at()

void hmap::Array::depose_amount_kernel_bilinear_at	(	int	i,
		int	j,
		float	u,
		float	v,
		int	ir,
		float	amount
	)

◆ depose_amount_kernel_at()

void hmap::Array::depose_amount_kernel_at	(	int	i,
		int	j,
		const Array &	kernel,
		float	amount
	)

Distributes a specified amount of value around the cell located at (i, j) using a 1D deposition kernel applied in both horizontal and vertical directions.

Parameters

i	Index of the cell in the array where the deposition starts.
j	Index of the cell in the array where the deposition starts.
kernel	1D deposition kernel to be used for distribution. The kernel must contain an odd number of elements.
amount	The amount of value to be distributed around the cell.

◆ dump()

void hmap::Array::dump ( const std::string & fname = "out.png" ) const

Debug tool, dump some infos and generate an output file (16bits grayscale)

◆ extract_slice() [1/2]

Array hmap::Array::extract_slice ( Vec4< int > idx ) const

Extracts a subarray defined by the slice indices {i1, i2, j1, j2} from the original array, creating a new array. Note that i2 and j2 are excluded from the slice.

Parameters

idx	A Vec4<int> containing the slice extent indices {i1, i2, j1, j2}.

Returns: Array The extracted subarray.

◆ extract_slice() [2/2]

Array hmap::Array::extract_slice	(	int	i1,
		int	i2,
		int	j1,
		int	j2
	)		const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ from_file()

void hmap::Array::from_file ( const std::string & fname )

Import array data from a raw binary file.

   This function loads the array data from a binary file specified by

fname. The file should contain raw binary data that corresponds to the internal representation of the array. The array's size and data type must match the expected format in the file.

Parameters

fname The name of the file to import data from.

◆ from_numpy()

void hmap::Array::from_numpy ( const std::string & fname )

Import array data from a numpy binary file.

Parameters

fname The name of the file to import data from.

Example

#include <iostream>
 
#include "highmap.hpp"
 
int main(void)
{
  hmap::Vec2<int>   shape = {512, 256};
  hmap::Vec2<float> res = {4.f, 2.f};
  int               seed = 1;
 
  hmap::Array z1 = hmap::noise_fbm(hmap::NoiseType::PERLIN, shape, res, seed);
 
  z1.to_numpy("out.npy");
 
  hmap::Array z2;
  z2.from_numpy("out.npy");
 
  hmap::export_banner_png("ex_from_numpy.png", {z1, z2}, hmap::Cmap::INFERNO);
}

◆ get_gradient_x_at()

float hmap::Array::get_gradient_x_at	(	int	i,
		int	j
	)		const

Calculates the gradient in the 'x' (or 'i') direction at a specified index (i, j) using a 2nd order central difference scheme.

   This function computes the gradient in the x-direction, which

measures the rate of change along the x-axis. Note that this function cannot be used at the borders of the data, as the central difference scheme requires values from both sides of the point of interest.

Warning: The gradient cannot be computed at the borders of the data array. Specifically, the function is not defined for i = 0, j = 0, i = shape.x - 1, or j = shape.y - 1.

Parameters

i	Index along the x-direction, expected to be in the range [1, shape.x - 2].
j	Index along the y-direction, expected to be in the range [1, shape.y - 2].

Returns: float The computed gradient value in the x-direction at the specified index.

◆ get_gradient_y_at()

float hmap::Array::get_gradient_y_at	(	int	i,
		int	j
	)		const

Calculates the gradient in the 'y' (or 'j') direction at a specified index (i, j) using a 2nd order central difference scheme.

   This function computes the gradient in the y-direction, which

measures the rate of change along the y-axis. Note that this function cannot be used at the borders of the data, as the central difference scheme requires values from both sides of the point of interest.

Warning: The gradient cannot be computed at the borders of the data array. Specifically, the function is not defined for i = 0, j = 0, i = shape.x - 1, or j = shape.y - 1.

Parameters

i	Index along the x-direction, expected to be in the range [1, shape.x - 2].
j	Index along the y-direction, expected to be in the range [1, shape.y - 2].

Returns: float The computed gradient value in the y-direction at the specified index.

◆ get_gradient_x_bilinear_at()

float hmap::Array::get_gradient_x_bilinear_at	(	int	i,
		int	j,
		float	u,
		float	v
	)		const

Calculates the gradient in the 'x' (or 'i') direction at a location (x, y) near the index (i, j) using bilinear interpolation.

   This function uses bilinear interpolation to estimate the gradient

in the x-direction at a point within the cell defined by (i, j). The gradient is based on a 2nd order central difference scheme but interpolated to a finer resolution.

Warning: The gradient cannot be computed at the borders of the data array. Specifically, the function is not defined for i = 0, j = 0, i = shape.x - 1, or j = shape.y - 1.

Parameters

i	Index along the x-direction, expected to be in the range [1, shape.x - 2].
j	Index along the y-direction, expected to be in the range [1, shape.y - 2].
u	'u' interpolation parameter, expected to be in the range [0, 1[.
v	'v' interpolation parameter, expected to be in the range [0, 1[.

Returns: float The interpolated gradient value in the x-direction at the specified location.

◆ get_gradient_y_bilinear_at()

float hmap::Array::get_gradient_y_bilinear_at	(	int	i,
		int	j,
		float	u,
		float	v
	)		const

Calculates the gradient in the 'y' (or 'j') direction at a location (x, y) near the index (i, j) using bilinear interpolation.

   This function uses bilinear interpolation to estimate the gradient

in the y-direction at a point within the cell defined by (i, j). The gradient is based on a 2nd order central difference scheme but interpolated to a finer resolution.

Warning: The gradient cannot be computed at the borders of the data array. Specifically, the function is not defined for i = 0, j = 0, i = shape.x - 1, or j = shape.y - 1.

Parameters

i	Index along the x-direction, expected to be in the range [1, shape.x - 2].
j	Index along the y-direction, expected to be in the range [1, shape.y - 2].
u	'u' interpolation parameter, expected to be in the range [0, 1[.
v	'v' interpolation parameter, expected to be in the range [0, 1[.

Returns: float The interpolated gradient value in the y-direction at the specified location.

◆ get_normal_at()

Vec3< float > hmap::Array::get_normal_at	(	int	i,
		int	j
	)		const

Calculates the surface normal vector at the index (i, j).

   This function computes the surface normal at the specified index (i,

j) in the data array. The normal vector is a three-dimensional vector (x, y, z) that is perpendicular to the surface at that point.

Parameters

i	Index along the x-direction.
j	Index along the y-direction.

Returns: Vec3<float> The normal vector at the specified index (i, j).

◆ get_shape()

Vec2< int > hmap::Array::get_shape ( )

Retrieves the shape of the array.

Returns: Vec2<int> The shape {ni, nj}.

◆ get_sizeof()

size_t hmap::Array::get_sizeof ( ) const

Retrieves the number of bytes occupied by the array data.

   This function returns the total size in bytes of the underlying

storage vector that holds the array data. This can be useful for memory management or debugging purposes.

Returns: size_t The size of the array data in bytes.

◆ get_value_bicubic_at()

float hmap::Array::get_value_bicubic_at	(	int	i,
		int	j,
		float	u,
		float	v
	)		const

Retrieves the array value at the location (x, y) near the index (i, j) using bicubic interpolation.

   This function uses bicubic interpolation to estimate the value at a

point within the cell defined by (i, j). Bicubic interpolation provides a smoother result compared to bilinear interpolation by taking into account the values of the surrounding 4x4 grid of points, resulting in better accuracy when interpolating in areas with gradients or curves.

Warning: This function cannot be used at the upper borders of the array, specifically for i = shape.x - 2 or j = shape.y - 2, as bicubic interpolation requires surrounding data points from a 4x4 neighborhood.

Parameters

i	Index along the x-direction, expected to be in the range [1, shape.x - 3].
j	Index along the y-direction, expected to be in the range [1, shape.y - 3].
u	'u' interpolation parameter, expected to be in the range [0, 1[.
v	'v' interpolation parameter, expected to be in the range [0, 1[.

Returns: float The interpolated value at the specified location (x, y).

◆ get_value_bilinear_at()

float hmap::Array::get_value_bilinear_at	(	int	i,
		int	j,
		float	u,
		float	v
	)		const

Retrieves the array value at the location (x, y) near the index (i, j) using bilinear interpolation.

   This function uses bilinear interpolation to estimate the value at a

point within the cell defined by (i, j). Bilinear interpolation is applied based on the surrounding values to approximate the value at the specified (x, y) location.

Warning: This function cannot be used at the upper borders of the array, specifically for i = shape.x - 1 or j = shape.y - 1, as bilinear interpolation requires surrounding data points.

Parameters

i	Index along the x-direction, expected to be in the range [0, shape.x - 2].
j	Index along the y-direction, expected to be in the range [0, shape.y - 2].
u	'u' interpolation parameter, expected to be in the range [0, 1[.
v	'v' interpolation parameter, expected to be in the range [0, 1[.

Returns: float The interpolated value at the specified location (x, y).

◆ get_value_nearest()

float hmap::Array::get_value_nearest	(	float	x,
		float	y,
		Vec4< float >	bbox
	)

Retrieves the nearest value at the location (x, y) within a bounded domain.

   This function retrieves the nearest value to the specified (x, y)

coordinates from the array, assuming the array covers a domain defined by the bounding box bbox. If the coordinates (x, y) are outside the domain, they are clamped to the nearest valid position within the bounding box.

Parameters

x	Coordinate along the x-axis.
y	Coordinate along the y-axis.
bbox	Bounding box defining the domain of the array. It is expected to be in the form of {xmin, xmax, ymin, ymax}.

Returns: float The nearest value at the clamped location (x, y).

◆ get_vector()

std::vector< float > hmap::Array::get_vector ( ) const

Retrieves the underlying data vector.

Returns: std::vector<float> The vector containing the array's data.

◆ infos()

void hmap::Array::infos ( std::string msg = "" ) const

Display various information about the array.

   This function outputs details about the array, such as its

dimensions, data type, and any other relevant information. The optional msg parameter can be used to include a custom message in the output.

Parameters

msg	Optional message to include in the output.

◆ linear_index()

int hmap::Array::linear_index	(	int	i,
		int	j
	)		const

Return the linear index corresponding to the (i, j) cell in a 2D array.

   This function calculates the linear index for a cell specified by

the (i, j) coordinates in a 2D array. The linear index is useful for accessing elements in a flattened or 1D representation of the array.

Parameters

i	The 'i' index (row index).
j	The 'j' index (column index).

Returns: int The linear index corresponding to the (i, j) cell.

◆ linear_index_reverse()

Vec2< int > hmap::Array::linear_index_reverse ( int k ) const

Convert a linear index to its corresponding (i, j) cell coordinates.

   This function calculates the 2D cell coordinates (i, j) in the array

from a given linear index k. This is useful for mapping between the 1D and 2D representations of the array.

Parameters

k	The linear index.

Returns: Vec2<int> The (i, j) coordinates corresponding to the linear index k.

◆ max()

float hmap::Array::max ( ) const

Return the value of the greatest element in the array.

   This function computes the maximum value present in the array. If

the array is empty, the behavior of this function is undefined.

Returns: float The maximum value in the array.

◆ mean()

float hmap::Array::mean ( ) const

Return the mean value of the elements in the array.

   This function calculates the average value of all elements in the

array. If the array is empty, the behavior of this function is undefined.

Returns: float The mean value of the elements in the array.

◆ min()

float hmap::Array::min ( ) const

Return the value of the smallest element in the array.

   This function computes the minimum value present in the array. If

the array is empty, the behavior of this function is undefined.

Returns: float The minimum value in the array.

◆ normalize()

void hmap::Array::normalize ( )

Normalize array values so that the sum of all elements is equal to 1.

   This function adjusts the values in the array so that their total

sum is normalized to 1. This is often used in scenarios where the array represents a probability distribution.

◆ normalization_coeff()

Vec2< float > hmap::Array::normalization_coeff	(	float	vmin = `0.f`,
		float	vmax = `1.f`
	)		const

Computes normalization coefficients (a, b) such that a * array + b maps the values to the range [vmin, vmax].

   This function calculates the coefficients used to normalize the

array values so that they fit within the specified range [vmin, vmax]. The normalization is performed using the linear transformation: a * array + b.

Parameters

vmin	Lower bound of the desired range.
vmax	Upper bound of the desired range.

Returns: Vec2<float> Normalization coefficients (a, b) where a scales the values and b shifts them.

◆ print()

void hmap::Array::print ( ) const

Print the array values to the standard output (stdout).

   This function prints the contents of the array in a human-readable

format to the standard output. This can be useful for debugging or inspecting the values of the array.

◆ ptp()

float hmap::Array::ptp ( ) const

Return the peak-to-peak amplitude (i.e., the difference between the maximum and minimum values) of the array values.

   This function calculates the peak-to-peak amplitude of the array,

which is the difference between the maximum and minimum values in the array.

Returns: float The peak-to-peak amplitude of the array values.

◆ resample_to_shape()

Array hmap::Array::resample_to_shape ( Vec2< int > new_shape ) const

Return a resampled array of shape new_shape using bilinear interpolation.

   This function resamples the array to a new shape `new_shape` using

bilinear interpolation. The resampling changes the dimensions of the array while preserving the data's spatial relationships.

Parameters

new_shape The target shape for the resampled array.

Returns: Array The resampled array with the specified new_shape.

Example

#include "highmap.hpp"
 
int main(void)
{
  hmap::Vec2<int>   shape = {256, 256};
  hmap::Vec2<float> res = {4.f, 4.f};
  int               seed = 1;
 
  hmap::Array z = hmap::noise(hmap::NoiseType::PERLIN, shape, res, seed);
 
  auto zr = z.resample_to_shape({32, 32});
 
  zr.to_png("ex_resample_to_shape.png", hmap::Cmap::VIRIDIS);
}

Result

◆ resample_to_shape_bicubic()

Array hmap::Array::resample_to_shape_bicubic ( Vec2< int > new_shape ) const

Return a resampled array of shape new_shape using bicubic interpolation.

   This function resamples the array to a new shape `new_shape` using

bicubic interpolation. The resampling changes the dimensions of the array while preserving the data's spatial relationships with a higher degree of smoothness compared to bilinear interpolation.

Parameters

new_shape The target shape for the resampled array.

Returns: Array The resampled array with the specified new_shape.

Example

#include "highmap.hpp"
 
int main(void)
{
  hmap::Vec2<int>   shape = {256, 256};
  hmap::Vec2<float> res = {4.f, 4.f};
  int               seed = 1;
 
  hmap::Array z0 = hmap::noise_fbm(hmap::NoiseType::PERLIN, shape, res, seed);
 
  hmap::Vec2<int> new_shape = {1024, 1024};
 
  hmap::Array z1 = z0.resample_to_shape(new_shape);
  z1 = z1.resample_to_shape(shape);
 
  hmap::Array z2 = z0.resample_to_shape_bicubic(new_shape);
  z2.to_png("out.png", hmap::Cmap::JET);
  z2 = z2.resample_to_shape(shape);
 
  hmap::export_banner_png("ex_array_interp.png",
                          {z0, z1, z2},
                          hmap::Cmap::MAGMA);
}

Result

◆ resample_to_shape_bilinear()

Array hmap::Array::resample_to_shape_bilinear ( Vec2< int > new_shape ) const

◆ resample_to_shape_nearest()

Array hmap::Array::resample_to_shape_nearest ( Vec2< int > new_shape ) const

Return a resampled array of shape new_shape using nearest neighbor interpolation.

   This function resamples the array to a new shape `new_shape` using

nearest neighbor interpolation. This method selects the value from the nearest neighbor in the original array, which can be faster but may produce blocky artifacts compared to other interpolation methods.

Parameters

new_shape The target shape for the resampled array.

Returns: Array The resampled array with the specified new_shape.

◆ row_to_vector()

std::vector< float > hmap::Array::row_to_vector ( int i )

Return a row i as a std::vector<float>.

   This function extracts the specified row `i` from the array and

returns it as a std::vector<float>. This is useful for operations where you need to work with individual rows outside of the array structure.

Parameters

i	Row index to extract.

Returns: std::vector<float> The values of the specified row as a vector.

◆ set_shape()

void hmap::Array::set_shape ( Vec2< int > new_shape )

Sets a new shape for the array.

Parameters

new_shape The new shape of the array.

◆ set_slice() [1/2]

void hmap::Array::set_slice	(	Vec4< int >	idx,
		float	value
	)

Set the value of a slice defined by indices {i1, i2, j1, j2} to a new value.

   This function updates all elements within the specified slice of the

array to the given value. The slice is defined by the extents {i1, i2, j1, j2}, where i1 and i2 specify the range for the rows, and j1 and j2 specify the range for the columns.

Parameters

idx	Slice extent indices: {i1, i2, j1, j2}.
value	The new value to set for the specified slice.

◆ set_slice() [2/2]

void hmap::Array::set_slice	(	Vec4< int >	idx,
		const Array &	array
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ size()

int hmap::Array::size ( ) const

Return the total number of elements in the array.

   This function returns the size of the array, which is the total

number of elements it contains. This can be useful for iterating over the array or for checking its dimensions.

Returns: int The total number of elements in the array.

◆ std()

float hmap::Array::std ( ) const

Return the standard deviation of all array values.

Returns: float The standard deviation of all elements in the array.

◆ sum()

float hmap::Array::sum ( ) const

Return the sum of all array values.

   This function calculates and returns the sum of all elements in the

array. It can be used to obtain aggregate values or to check the overall magnitude of the array's contents.

Returns: float The sum of all elements in the array.

◆ to_cv_mat()

cv::Mat hmap::Array::to_cv_mat ( )

Converts a 2D Array to an OpenCV cv::Mat.

This function converts a 2D Array object into an OpenCV cv::Mat. The conversion process does not involve copying the data; instead, it uses pointers to the original data in the Array. As a result, any modifications to the Array will directly affect the corresponding cv::Mat and vice versa.

Note: Since this function relies on pointers to the original data, it is crucial for the user to ensure that the Array object remains in scope and valid for the entire lifetime of the cv::Mat. If the Array is destroyed or goes out of scope, the cv::Mat will reference invalid memory, which can lead to undefined behavior.

Returns: A cv::Mat object that shares the data with the input Array.

Example

#include <opencv2/opencv.hpp>
 
#include "highmap.hpp"
 
int main(void)
{
  hmap::Vec2<int>   shape = {512, 256};
  hmap::Vec2<float> res = {4.f, 2.f};
  int               seed = 1;
 
  hmap::Array z = hmap::noise_fbm(hmap::NoiseType::PERLIN, shape, res, seed);
  hmap::remap(z, 0.f, 1.f);
 
  z.to_png("out.png", hmap::Cmap::GRAY);
 
  z.infos();
 
  cv::Mat img = z.to_cv_mat();
  cv::cvtColor(img, img, cv::COLOR_GRAY2BGR);
 
  std::vector<int> codec_params = {cv::IMWRITE_EXR_TYPE,
                                   cv::IMWRITE_EXR_TYPE_FLOAT,
                                   cv::IMWRITE_EXR_COMPRESSION,
                                   cv::IMWRITE_EXR_COMPRESSION_NO};
 
  cv::imwrite("out.exr", img, codec_params);
 
  // set compression to cv::IMWRITE_TIFF_COMPRESSION_LZW (apparently
  // not available in openCV public header?)
  codec_params = {cv::IMWRITE_TIFF_COMPRESSION, 5};
 
  cv::imwrite("out.tiff", img, codec_params);
 
  img.convertTo(img, CV_16U, 65535);
  cv::imwrite("out_cv.png", img);
 
  cv::imshow("example", img);
  cv::waitKey(0);
}

◆ to_exr()

void hmap::Array::to_exr ( const std::string & fname ) const

Export the array as an OpenEXR image file.

   This function saves the array data as an OpenEXR image file. OpenEXR

is a high dynamic range (HDR) image file format. The file will be created or overwritten with the name specified by fname.

Parameters

fname The name of the OpenEXR file to be created or overwritten.

Example

◆ to_file()

void hmap::Array::to_file ( const std::string & fname ) const

Export the array to a raw binary file.

   This function writes the contents of the array to a file in raw

binary format. This can be useful for saving the array data to disk or for transferring it between programs. The file will be created or overwritten with the specified fname.

Parameters

fname The name of the file to which the array data will be written.

◆ to_numpy()

void hmap::Array::to_numpy ( const std::string & fname ) const

Export the array to a numpy binary file.

Parameters

fname The name of the file to which the array data will be written.

Example

#include <iostream>
 
#include "highmap.hpp"
 
int main(void)
{
  hmap::Vec2<int>   shape = {512, 256};
  hmap::Vec2<float> kw = {4.f, 2.f};
  int               seed = 1;
 
  hmap::Array z = hmap::noise_fbm(hmap::NoiseType::PERLIN, shape, kw, seed);
 
  std::cout << z(10, 12) << std::endl;
 
  z.to_numpy("out.npy");
  z.to_png("ex_to_numpy.png", hmap::Cmap::JET);
 
  // --- python script to check this provided below in the comments
 
  // import matplotlib.pyplot as plt
  // import numpy as np
  // z = np.load('out.npy')
  // print(z.shape)
  // print(z[10, 12])
  // plt.imshow(z, cmap='jet')
  // plt.show()
}

◆ to_png()

void hmap::Array::to_png	(	const std::string &	fname,
		int	cmap,
		bool	hillshading = `false`,
		int	depth = `CV_8U`
	)		const

Export the array as a PNG image file with a specified colormap and hillshading.

   This function saves the array data as a PNG image file. The colors

of the image are determined by the specified colormap (cmap), and optional hillshading can be applied to enhance the visual representation of the data. The file will be created or overwritten with the name specified by fname.

Parameters

fname	The name of the PNG file to be created or overwritten.
cmap	The colormap to be used for visualizing the data. Refer to `cmap` for available options.
hillshading	Boolean flag to enable or disable hillshading. If true, hillshading will be applied.

Example

#include "highmap.hpp"
 
int main(void)
{
 
  const hmap::Vec2<int>   shape = {512, 512};
  const hmap::Vec2<float> res = {4.f, 4.f};
  int                     seed = 2;
 
  // write png
  hmap::Array z1 = hmap::noise_fbm(hmap::NoiseType::PERLIN,
                                   shape,
                                   res,
                                   seed,
                                   8);
  hmap::remap(z1);
  z1.to_png("out_rgb.png", hmap::Cmap::JET);
  z1.to_png_grayscale("out_8bit.png");
  z1.to_png_grayscale("out_16bit.png", CV_16U);
 
  // create Array from png
  hmap::Array z2 = hmap::Array("out_8bit.png");
  hmap::Array z3 = hmap::Array("out_16bit.png");
 
  z1.to_raw_16bit("out.raw");
 
  hmap::export_banner_png("ex_to_png.png", {z1, z2, z3}, hmap::Cmap::INFERNO);
}

◆ to_png_grayscale()

void hmap::Array::to_png_grayscale	(	const std::string &	fname,
		int	depth = `CV_8U`
	)		const

Export the array as a grayscale PNG image file with specified bit depth.

This function saves the array data as a grayscale PNG image file. The bit depth of the image is determined by the depth parameter, allowing for either 8-bit (0-255) or 16-bit (0-65535) grayscale values. The resulting image will be created or overwritten with the name specified by fname.

Parameters

fname	The name of the PNG file to be created or overwritten.
depth	The bit depth of the PNG image. Default is 8-bit (CV_8U). Use CV_16U for 16-bit depth if higher precision is needed.

Example

#include "highmap.hpp"
 
int main(void)
{
 
  const hmap::Vec2<int>   shape = {512, 512};
  const hmap::Vec2<float> res = {4.f, 4.f};
  int                     seed = 2;
 
  // write png
  hmap::Array z1 = hmap::noise_fbm(hmap::NoiseType::PERLIN,
                                   shape,
                                   res,
                                   seed,
                                   8);
  hmap::remap(z1);
  z1.to_png("out_rgb.png", hmap::Cmap::JET);
  z1.to_png_grayscale("out_8bit.png");
  z1.to_png_grayscale("out_16bit.png", CV_16U);
 
  // create Array from png
  hmap::Array z2 = hmap::Array("out_8bit.png");
  hmap::Array z3 = hmap::Array("out_16bit.png");
 
  z1.to_raw_16bit("out.raw");
 
  hmap::export_banner_png("ex_to_png.png", {z1, z2, z3}, hmap::Cmap::INFERNO);
}

◆ to_tiff()

void hmap::Array::to_tiff ( const std::string & fname ) const

Export the array as a TIFF image file.

   This function saves the array data as a TIFF (Tagged Image File

Format) image file. The file will be created or overwritten with the name specified by fname.

Parameters

fname The name of the TIFF file to be created or overwritten.

Example

◆ to_raw_16bit()

void hmap::Array::to_raw_16bit ( const std::string & fname ) const

Export the array as a 16-bit raw file for Unity terrain import.

   This function saves the array data as a raw binary file with 16-bit

depth. The resulting file is suitable for use with Unity terrain import formats. The file will be created or overwritten with the name specified by fname.

Parameters

fname The name of the raw file to be created or overwritten.

Example

◆ unique_values()

std::vector< float > hmap::Array::unique_values ( )

Return the unique elements of the array.

   This function extracts and returns a vector containing all unique

values present in the array. The values are sorted in ascending order.

Returns: std::vector<float> A vector of unique values found in the array.

Friends And Related Symbol Documentation

◆ operator*

Array operator*	(	const float	value,
		const Array &	array
	)

friend

Overloads the multiplication operator for scalar multiplication.

Parameters

value	The scalar value to multiply.
array	The Array to multiply with.

Returns: Array The resulting Array after multiplication.

◆ operator/

Array operator/	(	const float	value,
		const Array &	array
	)

friend

Overloads the division operator for scalar division.

Parameters

value	The scalar value to divide by.
array	The Array to divide by.

Returns: Array The resulting Array after division.

◆ operator+

Array operator+	(	const float	value,
		const Array &	array
	)

friend

Overloads the addition operator for scalar addition.

Parameters

value	The scalar value to add.
array	The Array to add.

Returns: Array The resulting Array after addition.

◆ operator-

const Array operator-	(	const float	value,
		const Array &	array
	)

friend

Overloads the subtraction operator for scalar subtraction.

Parameters

value	The scalar value to subtract.
array	The Array to subtract from.

Returns: Array The resulting Array after subtraction.

Member Data Documentation

◆ shape

Vec2<int> hmap::Array::shape

The shape of the array {ni, nj}.

◆ vector

std::vector<float> hmap::Array::vector

The underlying data storage, a vector of size shape.x * shape.y.

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

HighMap/include/highmap/array.hpp
HighMap/src/array/array.cpp
HighMap/src/array/io.cpp
HighMap/src/array/methods.cpp
HighMap/src/array/opencv_wrapper.cpp

Public Member Functions

Public Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Array() [1/4]

◆ Array() [2/4]

◆ Array() [3/4]

◆ Array() [4/4]

Member Function Documentation

◆ operator=()

◆ operator*=() [1/2]

◆ operator*=() [2/2]

◆ operator/=() [1/2]

◆ operator/=() [2/2]

◆ operator+=() [1/2]

◆ operator+=() [2/2]

◆ operator-=() [1/2]

◆ operator-=() [2/2]

◆ operator*() [1/2]

◆ operator*() [2/2]

◆ operator/() [1/2]

◆ operator/() [2/2]

◆ operator+() [1/2]

◆ operator+() [2/2]

◆ operator-() [1/3]

◆ operator-() [2/3]

◆ operator-() [3/3]

◆ operator()() [1/2]

◆ operator()() [2/2]

◆ col_to_vector()

◆ count_non_zero()

◆ depose_amount_bilinear_at()

◆ depose_amount_kernel_bilinear_at()

◆ depose_amount_kernel_at()

◆ dump()

◆ extract_slice() [1/2]

◆ extract_slice() [2/2]

◆ from_file()

◆ from_numpy()

◆ get_gradient_x_at()

◆ get_gradient_y_at()

◆ get_gradient_x_bilinear_at()

◆ get_gradient_y_bilinear_at()

◆ get_normal_at()

◆ get_shape()

◆ get_sizeof()

◆ get_value_bicubic_at()

◆ get_value_bilinear_at()

◆ get_value_nearest()

◆ get_vector()

◆ infos()

◆ linear_index()

◆ linear_index_reverse()

◆ max()

◆ mean()

◆ min()

◆ normalize()

◆ normalization_coeff()

◆ print()

◆ ptp()

◆ resample_to_shape()

◆ resample_to_shape_bicubic()

◆ resample_to_shape_bilinear()

◆ resample_to_shape_nearest()

◆ row_to_vector()

◆ set_shape()

◆ set_slice() [1/2]

◆ set_slice() [2/2]

◆ size()

◆ std()

◆ sum()

◆ to_cv_mat()

◆ to_exr()

◆ to_file()

◆ to_numpy()

◆ to_png()

◆ to_png_grayscale()

◆ to_tiff()

◆ to_raw_16bit()