Skip to content

compas_fab.utilities ¤

Utility functions for compas_fab.

Numerical helpers (allclose, arange, clamp, diffs, map_range, range_geometric_row, sign, argmax, argmin, argsort) and a lazy-import helper (LazyLoader).

Classes¤

LazyLoader ¤

LazyLoader(local_name, parent_module_globals, name)

Lazily import a module, mainly to avoid pulling in large dependencies.

contrib, and ffmpeg are examples of modules that are large and not always needed, and this allows them to only be loaded when they are used.

Functions:¤

allclose ¤

allclose(l1: list[float], l2: list[float], tol: float = 1e-05) -> bool

Returns True if two lists are element-wise equal within a tolerance.

The function is similar to NumPy's allclose function.

Parameters:

  • l1 (list[float]) –

    The first list.

  • l2 (list[float]) –

    The second list.

  • tol (float, default: 1e-05 ) –

    The tolerance within which the lists are considered equal. Default is 1e-05.

Returns:

  • bool –

    True if the lists are equal within the tolerance, otherwise False.

Raises:

  • ValueError –

    If 2 lists of different length are passed.

arange ¤

arange(start: float, stop: float, step: float) -> list[float]

Returns evenly spaced values within a given interval.

The function is similar to NumPy's arange function.

Parameters:

  • start (float) –

    The starting value of the sequence.

  • stop (float) –

    The end value of the sequence.

  • step (float) –

    The spacing between the values.

Returns:

  • obj:`list` of :obj:`float` –

    The list of evenly spaced values.

argmax ¤

argmax(numbers: list[float]) -> int

Returns the index of the maximum value in numbers.

The function is similar to NumPy's argmax function.

Parameters:

  • numbers (list[float]) –

    A list of numbers.

Returns:

  • obj:`int` –

    The index of the maximum value in the list.

Notes

For a large list of numbers reconsider using NumPy's argmax function, since this function might take too long.

argmin ¤

argmin(numbers: list[float]) -> int

Returns the index of the minimum value in numbers.

The function is similar to NumPy's argmin function.

Parameters:

  • numbers (list[float]) –

    A list of numbers.

Returns:

  • obj:`int` –

    The index of the minimum value in the list.

Notes

For a large list of numbers reconsider using NumPy's argmin function, since this function might take too long.

argsort ¤

argsort(numbers: list[float]) -> list[int]

Returns the indices that would sort an array of numbers.

The function is similar to NumPy's argsort function.

Parameters:

  • numbers (list[float]) –

    A list of numbers.

Returns:

  • obj:`list` of :obj:`int` –

    The indices that would sort the array.

Notes

For a large list of numbers reconsider using NumPy's argsort function, since this function might take too long.

clamp ¤

clamp(value: float, min_value: float, max_value: float) -> float

Clamps a value within the bound [min_value, max_value]

Parameters:

  • value (float) –

    The value to clamp.

  • min_value (float) –

    The minimum value.

  • max_value (float) –

    The maximum value.

Returns:

  • float –

    The clamped value.

diffs ¤

diffs(l1: list[float], l2: list[float]) -> list[float]

Returns the element-wise differences between two lists.

Parameters:

Returns:

  • obj:`list` of :obj:`float` –

    The element-wise differences between the two lists.

Raises:

  • ValueError –

    If 2 lists of different length are passed.

list_files_in_directory ¤

list_files_in_directory(
    directory: str, fullpath: bool = False, extensions: list[str] | None = None
) -> list[str]

This function lists just the files in a directory, not sub-directories.

Parameters:

  • directory (str) –

    The directory to search for files.

  • fullpath (bool, default: False ) –

    Specifies if the returned list of strings is with the full path.

  • extensions (list[str] | None, default: None ) –

    A list of allowed extensions, e.g. ["jpg", "png"] if you just want to list images.

Returns:

  • obj:`list` of :obj:`str` –

    A list of files as string if files exist, or empty list.

map_range ¤

map_range(
    value: float, from_min: float, from_max: float, to_min: float, to_max: float
) -> float

Performs a linear interpolation of a value within the range of [from_min, from_max] to another range of [to_min, to_max].

Parameters:

  • value (float) –

    The value to map.

  • from_min (float) –

    The minimum value of the input range.

  • from_max (float) –

    The maximum value of the input range.

  • to_min (float) –

    The minimum value of the output range.

  • to_max (float) –

    The maximum value of the output range.

Returns:

  • obj:`float` –

    The mapped value.

range_geometric_row ¤

range_geometric_row(number: float, d: int, r: float = 1.1) -> list[float]

Returns a list of numbers with a certain relation to each other.

The function divides one number into a list of d numbers [n0, n1, ...], such that their sum is number and the relation between the numbers is defined with n1 = n0 / r, n2 = n1 / r, n3 = n2 / r, ...

Parameters:

  • number (float) –

    The initial number to divide. This number is the first element in the returned list.

  • d (int) –

    The number of elements in the returned list.

  • r (float, default: 1.1 ) –

    The ratio between the numbers in the list. Default is 1.1.

Returns:

  • obj:`list` of :obj:`float` –

    The list of numbers with the geometric relation.

sign ¤

sign(number: float) -> int

Returns the sign of a number: +1 or -1.

Parameters:

  • number (float) –

    A number to check the sign of.

Returns:

  • int –

    +1 if the number has positive sign, 0 if the number is zero, -1 if the number has negative sign.