vpype_gscrib.heightmaps

Heightmap implementations for toolpath and power compensation.

class vpype_gscrib.heightmaps.BaseHeightMap

Bases: ABC

Base class for height map implementations.

abstractmethod get_depth_at(x: Real, y: Real) → float

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: Sequence[float] | Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → ndarray

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 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 vpype_gscrib.heightmaps.FlatHeightMap

Bases: BaseHeightMap

No-op height map implementation.

get_depth_at(x: Real, y: Real) → float

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: Sequence[float] | Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → ndarray

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

Parameters:

line – 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 vpype_gscrib.heightmaps.RasterHeightMap(image_data: ndarray)

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)
classmethod from_path(path: str) → RasterHeightMap

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: Real, y: Real) → float

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() → int

Get the height of the height map.

Returns:

Height of the image in pixels.

Return type:

int

get_width() → int

Get the width of the height map.

Returns:

Width of the image in pixels.

Return type:

int

sample_path(line: Sequence[float] | Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → ndarray

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 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: float) → None

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

set_tolerance(tolerance: float) → None

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

class vpype_gscrib.heightmaps.SparseHeightMap(sparse_data: ndarray)

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)
classmethod from_path(path: str) → SparseHeightMap

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: Real, y: Real) → float

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: Sequence[float] | Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → ndarray

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 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: str) → None

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

set_scale(scale_z: float) → None

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

set_tolerance(tolerance: float) → None

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