hbutils.algorithm.linear

Piecewise linear mapping utilities.

This module provides utilities for creating multi-staged linear gradient mappings based on float numbers. It exposes a single public factory function, linear_map(), which builds a callable piecewise linear mapping from control points. Control points can be specified as a sequence of y-values with automatic x-spacing or as explicit (x, y) tuples.

The module contains the following main components:

  • linear_map() - Create a callable piecewise linear mapping function

Note

When using implicit x-spacing (a sequence of y-values), at least two points are required. A single point causes a ZeroDivisionError because the spacing denominator becomes zero.

Example:

>>> from hbutils.algorithm.linear import linear_map
>>> # Implicit x-spacing over [0, 1]
>>> f = linear_map((0.0, 1.0, 0.5))
>>> f(0.5)
1.0
>>> # Explicit x-coordinates
>>> g = linear_map(((-0.2, 0.0), (0.7, 1.0), (1.1, 0.5)))
>>> g(0.7)
1.0

__all__

hbutils.algorithm.linear.__all__ = ['linear_map']

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

linear_map

hbutils.algorithm.linear.linear_map(points: Sequence[float] | Sequence[Tuple[float, float]]) → Callable[[float], float][source]

Create a multiple-staged linear gradient calculation function based on control points.

This function generates a piecewise linear mapping function from a sequence of control points. The points can be specified in two ways:

  1. Simple sequence of y-values: x-values are automatically distributed evenly from 0 to 1. The spacing uses i / (n - 1), so at least two points are required.

  2. Sequence of (x, y) tuples: explicit x and y coordinates for each control point.

The returned callable performs linear interpolation between the neighboring control points. If explicit tuples are supplied, the order check uses Python’s tuple ordering, which requires the sequence of tuples to be strictly increasing lexicographically (typically implying strictly increasing x-values; if x-values are equal, the y-values must be strictly increasing).

Parameters:

points (Union[Sequence[float], Sequence[Tuple[float, float]]]) – Points for this linear mapping. If the sequence consists of float numbers, it will be seen as the simple linear mapping with x-values automatically distributed from 0 to 1. If the elements are binary tuples (contains 2 float numbers), it means the x-range is assigned explicitly.

Returns:

A callable function for linear mapping that takes a float x-value and returns the interpolated y-value.

Return type:

Callable[[float], float]

Raises:

  • AssertionError – If points is empty or if the control points are not strictly increasing under tuple ordering.

  • ZeroDivisionError – If points contains a single y-value, causing the implicit x-spacing denominator to be zero.

  • TypeError – If points is not iterable or contains elements incompatible with the expected formats.

  • ValueError – If the input x-value to the returned function is outside the valid range.

Examples::

  • Simple Linear Mapping

>>> from hbutils.algorithm import linear_map
>>>
>>> f = linear_map((0, 1, 0.5))
>>> f(0)
0.0
>>> f(0.25)
0.5
>>> f(1 / 3)
0.6666666666666666
>>> f(0.5)
1.0
>>> f(2 / 3)
0.8333333333333334
>>> f(0.75)
0.75
>>> f(1)
0.5

  • Complex Linear Mapping (x values are customized)

>>> f = linear_map(((-0.2, 0), (0.7, 1), (1.1, 0.5)))
>>> f(-0.2)
0.0
>>> f(0)
0.22222222222222227
>>> f(0.25)
0.5000000000000001
>>> f(1 / 3)
0.5925925925925927
>>> f(0.5)
0.7777777777777778
>>> f(2 / 3)
0.9629629629629631
>>> f(0.7)
1.0
>>> f(0.75)
0.9375
>>> f(0.8)
0.875
>>> f(1)
0.625
>>> f(1.1)
0.5