Math

Random numbers, simplex noise and number helpers.

random

random(a=None, b=None)

Returns a random float.

random() returns a value in [0, 1), random(max) one in [0, max) and random(min, max) one in [min, max).

Parameters

Name	Type	Description	Default
a	float \| None	The upper bound, or the lower bound when `b` is given; 1 if omitted.	`None`
b	float \| None	The upper bound, when `a` is the lower bound.	`None`

Returns

Name	Type	Description
	float	A uniformly distributed float.

random_gaussian

random_gaussian(mean=0.0, std_dev=1.0)

Returns a normally distributed random float.

Parameters

Name	Type	Description	Default
mean	float	The mean.	`0.0`
std_dev	float	The standard deviation.	`1.0`

Returns

Name	Type	Description
	float	A float drawn from a normal distribution.

random_seed

random_seed(seed)

Seeds the random generator, making random calls repeatable.

Parameters

Name	Type	Description	Default
seed	int	The seed.	required

noise

noise(x, y=None, z=None, w=None)

Returns simplex noise in [0, 1] at a 1D to 4D position.

The dimension is the number of coordinates given. Pass floats for a float back, or numpy arrays (any shape; they are broadcast together) for an array back with the same values as the scalar version, to within 1e-6. Nearby inputs give nearby outputs, so scaling the coordinates sets the feature size: noise(x * 0.01) is smooth over about a hundred units.

Parameters

Name	Type	Description	Default
x	Arr	First coordinate.	required
y	Arr \| None	Second coordinate, for 2D noise and up.	`None`
z	Arr \| None	Third coordinate, for 3D noise and up.	`None`
w	Arr \| None	Fourth coordinate, for 4D noise.	`None`

Returns

Name	Type	Description
	Arr	The noise value, a float or an ndarray.

signed_noise

signed_noise(x, y=None, z=None, w=None)

Returns simplex noise in [-1, 1] at a 1D to 4D position.

Parameters

Name	Type	Description	Default
x	Arr	First coordinate.	required
y	Arr \| None	Second coordinate, for 2D noise and up.	`None`
z	Arr \| None	Third coordinate, for 3D noise and up.	`None`
w	Arr \| None	Fourth coordinate, for 4D noise.	`None`

Returns

Name	Type	Description
	Arr	The noise value, a float or an ndarray.

map

map(value, in_min, in_max, out_min, out_max, clamp=False)

Maps a value from one range to another.

This shadows the builtin map only inside the kiln namespace. Works on numpy arrays too when clamp is False; with clamp use scalars.

Parameters

Name	Type	Description	Default
value	Arr	The value to map.	required
in_min	float	Lower end of the input range.	required
in_max	float	Upper end of the input range.	required
out_min	float	Lower end of the output range.	required
out_max	float	Upper end of the output range. May be below `out_min`.	required
clamp	bool	Keep the result between `out_min` and `out_max`.	`False`

Returns

Name	Type	Description
	Arr	The mapped value. If the input range is empty, `out_min`.

clamp

clamp(value, low, high)

Limits a value to [low, high].

Parameters

Name	Type	Description	Default
value	float	The value.	required
low	float	Lower limit.	required
high	float	Upper limit.	required

Returns

Name	Type	Description
	float	`low`, `high` or `value`.

lerp

lerp(start, stop, amount)

Linearly interpolates between two values, without clamping.

Parameters

Name	Type	Description	Default
start	Arr	Value at `amount` 0.	required
stop	Arr	Value at `amount` 1.	required
amount	Arr	Interpolation position; outside [0, 1] extrapolates.	required

Returns

Name	Type	Description
	Arr	`start + (stop - start) * amount`.

dist

dist(x1, y1, x2, y2)

Returns the distance between two 2D points.

Parameters

Name	Type	Description	Default
x1	float	First point x.	required
y1	float	First point y.	required
x2	float	Second point x.	required
y2	float	Second point y.	required

Returns

Name	Type	Description
	float	The Euclidean distance.

dist_squared

dist_squared(x1, y1, x2, y2)

Returns the squared distance between two 2D points.

Parameters

Name	Type	Description	Default
x1	float	First point x.	required
y1	float	First point y.	required
x2	float	Second point x.	required
y2	float	Second point y.	required

Returns

Name	Type	Description
	float	The squared Euclidean distance, which skips the square root.

wrap

wrap(value, low, high)

Wraps a value into [low, high), like a clock face.

Parameters

Name	Type	Description	Default
value	float	The value.	required
low	float	Lower end of the range.	required
high	float	Upper end of the range.	required

Returns

Name	Type	Description
	float	The value wrapped into the range; `low` if the range is empty.

normalize

normalize(value, low, high)

Returns where a value sits in a range.

0 is at low and 1 at high.

Parameters

Name	Type	Description	Default
value	float	The value.	required
low	float	Lower end of the range.	required
high	float	Upper end of the range.	required

Returns

Name	Type	Description
	float	`(value - low) / (high - low)`, not clamped; 0 if the range is empty.

in_range

in_range(value, low, high)

Tells whether a value lies in [low, high].

Parameters

Name	Type	Description	Default
value	float	The value.	required
low	float	Lower end of the range.	required
high	float	Upper end of the range.	required

Returns

Name	Type	Description
	bool	True when `low <= value <= high`.

sign

sign(value)

Returns the sign of a number.

Parameters

Name	Type	Description	Default
value	float	The number.	required

Returns

Name	Type	Description
	int	-1 for negative, 1 for positive and 0 for zero.

is_power_of_two

is_power_of_two(n)

Tells whether an integer is a power of two.

Parameters

Name	Type	Description	Default
n	int	The integer.	required

Returns

Name	Type	Description
	bool	True for 1, 2, 4, 8, and so on.

next_power_of_two

next_power_of_two(n)

Returns the smallest power of two that is at least n.

Parameters

Name	Type	Description	Default
n	int	A positive integer.	required

Returns

Name	Type	Description
	int	The power of two, 1 for `n` of 1 or less.