Numeric

Module path

kivydk.utils.numeric

---

Overview

Helpers used throughout KiviDK for value manipulation, scaling and normalization. These functions provide small, reliable primitives for common numeric operations.

They are intended to support UI logic, animations, visualizers and any component that needs consistent numeric transformations without relying on external libraries.

---

Reference

clamp(value: int | float, bounds: tuple[int | float, int | float] = (0, 1)) → int | float

Constrain a numeric value to the inclusive range defined by bounds. The bounds are automatically ordered.

Parameters

Name	Description
value	The value to clamp.
bounds	A tuple containing two numeric limits.

Example

clamp(-2)
# 0

clamp(2, bounds=(4, 6))
# 4

clamp(10, bounds=(5, 2))
# 5    (bounds become [2, 5])

normalize(value: int | float, bounds: tuple[int | float, int | float] = (0, 1), digits: int = 8) → int | float

Map a numeric value from the range defined by bounds into the normalized range. The bounds are automatically ordered and the result is not clamped.

Parameters

Name	Description
value	The value to normalize.
bounds	A tuple containing two numeric limits.
digits	Maximum fractional digits.

Example

normalize(1, bounds=(0, 2))
# 0.5

normalize(2, bounds=(5, 1))
# 0.25    (bounds become [1, 5])

normalize(-2, bounds=(2, 0))
# -1.0    (bounds become [0, 2])

normalize_relative(*values: int | float, scale: int | float = 1, digits: int = 8) → list[float]

Normalize a sequence of numeric values relative to their maximum value. Each result is in the range [0, scale].

Useful for visualizers, meters or any context where values must be expressed as proportions of the largest value.

Parameters

Name	Description
values	The values to normalize.
scale	The upper bound of the normalized range.
digits	Maximum fractional digits.

Example

normalize_relative(1, 2, 3, 4, 5)
# [0.2, 0.4, 0.6, 0.8, 1.0]

normalize_relative(1, 2, 3, 4, 5, scale=2)
# [0.4, 0.8, 1.2, 1.6, 2.0]

normalize_relative(-1, -2, -3, -4, -5)
# [-0.2, -0.4, -0.6, -0.8, -1.0]

remap_range(*values: int | float, actual: tuple[int | float, int | float], desired: tuple[int | float, int | float] = (0, 1), digits: int | None = None) → list[int | float]

Map numeric values from an actual range into a desired range.

Values outside the actual range will produce results outside the desired range. Useful for UI scaling, visualizers, animations, and any context where values must be expressed in a different numeric domain.

Parameters

Name	Description
values	Values to remap.
actual	Source range (min, max).
desired	Target range (min, max).
digits	Optional rounding precision.

Example

remap_range(1, 2, 3, 4, 5, actual=(1, 5))
# [0.0, 0.25, 0.5, 0.75, 1.0]

remap_range(1, 2, 3, 4, 5, 6, 7, 8, actual=(3, 7), desired=(0, 2))
# [-1.0, -0.5, 0.0, 0.5, 1.0, 1.5, 2.0, 2.5]