gscrib.heightmaps

Heightmap implementations.

class gscrib.heightmaps.BaseHeightMap

Bases: ABC

Base class for height map implementations.

abstractmethod get_depth_at(x, y)

Get the interpolated elevation value at specific coordinates.

Parameters:

  • x (float) – X-coordinate in the height map.

  • y (float) – Y-coordinate in the height map.

Returns:

Interpolated elevation scaled by the scale factor.

Return type:

float

abstractmethod sample_path(line)

Sample height values along a straight line path.

Generates a series of points along the line with their corresponding heights, filtering out points where height differences are below the specified tolerance.

Parameters:

  • line (Sequence[float] | Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) – Sequence containing start and end points of the line to sample in the format (x1, y1, x2, y2).

  • tolerance (float, optional) – Minimum height difference between consecutive points to be included in the output.

Returns:

Array of points (x, y, z) along the line where

height changes exceed the tolerance.

Return type:

ndarray

Raises:

ValueError – If line does not contain exactly 4 elements or cannot be converted to float values.

class gscrib.heightmaps.FlatHeightMap

Bases: BaseHeightMap

No-op height map implementation.

get_depth_at(x, y)

Get the interpolated elevation value at specific coordinates.

Parameters:

  • x (float) – X-coordinate in the height map.

  • y (float) – Y-coordinate in the height map.

Returns:

Always returns zero.

Return type:

float

sample_path(line)

Return start and end points of the line with zero height.

Parameters:

line (Sequence[float] | Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) – Line coordinates as (x1, y1, x2, y2).

Returns:

Array of two points (x, y, z) with z = 0.

Return type:

ndarray

Raises:

ValueError – If line does not contain exactly 4 elements.

class gscrib.heightmaps.RasterHeightMap(image_data)

Bases: BaseHeightMap

Interpolates height map data from images.

This class processes grayscale image data into a normalized height map and provides methods for height interpolation at specific coordinates and along paths.

Example

>>> height_map = RasterHeightMap.from_path('terrain.png')
>>> height_map.set_scale(2.0)
>>> height = height_map.get_depth_at(100, 100)
Parameters:

image_data (ndarray)

classmethod from_path(path)

Create a HeightMap instance from an image file.

Parameters:

path (str) – Path to the grayscale image file

Returns:

New HeightMap instance

Return type:

HeightMap

Raises:

ImageLoadError – If the image file cannot be read.

get_depth_at(x, y)

Get the interpolated elevation value at specific coordinates.

Parameters:

  • x (float) – X-coordinate in the height map.

  • y (float) – Y-coordinate in the height map.

Returns:

Interpolated elevation scaled by the scale factor.

Return type:

float

get_height()

Get the height of the height map.

Returns:

Height of the image in pixels.

Return type:

int

get_width()

Get the width of the height map.

Returns:

Width of the image in pixels.

Return type:

int

sample_path(line)

Sample height values along a straight line path.

Generates a series of points along the line with their corresponding heights, filtering out points where height differences are below the specified tolerance.

Parameters:

  • line (Sequence[float] | Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) – Sequence containing start and end points of the line to sample in the format (x1, y1, x2, y2).

  • tolerance (float, optional) – Minimum height difference between consecutive points to be included in the output.

Returns:

Array of points (x, y, z) along the line where

height changes exceed the tolerance.

Return type:

ndarray

Raises:

ValueError – If line does not contain exactly 4 elements or cannot be converted to float values.

set_scale(scale_z)

Set the vertical scaling factor for height values.

Parameters:

scale_z (float) – Scaling factor to apply to normalized height values.

Raises:

ValueError – If scale_z is zero or negative

Return type:

None

set_tolerance(tolerance)

Set height difference threshold for path sampling.

This is the minimum height difference between consecutive points that will be considered significant during path sampling. Points with height differences below this value will be filtered out when using sample_path().

Parameters:

tolerance (float) – The minimum height difference

Raises:

ValueError – If tolerance is negative

Return type:

None

class gscrib.heightmaps.SparseHeightMap(sparse_data)

Bases: BaseHeightMap

Interpolates height map data from sparse point data.

This class reads scattered (x, y, z) probe data from a CSV file into a height map and provides methods for height interpolation at specific coordinates and along paths.

Example

>>> height_map = SparseHeightMap.from_path('heights.csv')
>>> height = height_map.get_depth_at(100, 100)
Parameters:

sparse_data (ndarray)

classmethod from_path(path)

Create a HeightMap instance from a CSV file.

Parameters:

path (str) – Path to the CSV file with X, Y, Z columns

Returns:

New HeightMap instance

Return type:

SparseHeightMap

Raises:

FileLoadError – If the CSV file cannot be read

get_depth_at(x, y)

Get the interpolated elevation value at specific coordinates.

Parameters:

  • x (float) – X-coordinate in the height map.

  • y (float) – Y-coordinate in the height map.

Returns:

Interpolated elevation scaled by the scale factor.

Return type:

float

sample_path(line)

Sample height values along a straight line path.

Generates a series of points along the line with their corresponding heights, filtering out points where height differences are below the specified tolerance.

Parameters:

  • line (Sequence[float] | Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) – Sequence containing start and end points of the line to sample in the format (x1, y1, x2, y2).

  • tolerance (float, optional) – Minimum height difference between consecutive points to be included in the output.

Returns:

Array of points (x, y, z) along the line where

height changes exceed the tolerance.

Return type:

ndarray

Raises:

ValueError – If line does not contain exactly 4 elements or cannot be converted to float values.

save_image(path)

Save the sparse height map as a raster image.

Parameters:

path (str) – Path where the image will be saved

Raises:

IOError – If the image cannot be written

Return type:

None

set_scale(scale_z)

Set the vertical scaling factor for height values.

Parameters:

scale_z (float) – Scaling factor to apply to normalized height values.

Raises:

ValueError – If scale_z is zero or negative

Return type:

None

set_tolerance(tolerance)

Set height difference threshold for path sampling.

This is the minimum height difference between consecutive points that will be considered significant during path sampling. Points with height differences below this value will be filtered out when using sample_path().

Parameters:

tolerance (float) – The minimum height difference

Raises:

ValueError – If tolerance is negative

Return type:

None