Skip to main content

New scaling utils and import changes

· 3 min read
Jan Bouwhuis
Jan Bouwhuis

New utils for scaling brightness​

Multiple integrations have implemented there own scaling algorithm to scale brightness. New utils are introduced now to simplify the implementation of brightness scaling in homeassistant.util.color:

def brightness_to_value(low_high_range: tuple[float, float], brightness: int) -> float:
    """Given a brightness_scale convert a brightness to a single value.

    Do not include 0 if the light is off for value 0.

    Given a brightness low_high_range of (1,100) this function
    will return:

    255: 100.0
    127: ~49.8039
    10: ~3.9216
    """
    ...

If you'd rather like to scale brightness to an integer range you can also use scale_ranged_value_to_int_range, described here.

def value_to_brightness(low_high_range: tuple[float, float], value: float) -> int:
    """Given a brightness_scale convert a single value to a brightness.

    Do not include 0 if the light is off for value 0.

    Given a brightness low_high_range of (1,100) this function
    will return:

    100: 255
    50: 127
    4: 10

    The value will be clamped between 1..255 to ensure valid value.
    """
    ...

This also ensures a valid brightness value is returned.

Background​

To scale fan speed percentage we already have some utils homeassistant.utils.percentage:

def ranged_value_to_percentage(
    low_high_range: tuple[float, float], value: float
) -> int:
    ...

and

def percentage_to_ranged_value(
    low_high_range: tuple[float, float], percentage: int
) -> float:
    ...

These percentage utils will now use new generic scaling utils in homeassistant.utils.scaling:

scale_ranged_value_to_int_range and scale_to_ranged_value

def scale_ranged_value_to_int_range(
    source_low_high_range: tuple[float, float],
    target_low_high_range: tuple[float, float],
    value: float,
) -> int:
    """Given a range of low and high values convert a single value to another range.

    Given a source low value of 1 and a high value of 255 and
    a target range from 1 to 100 this function
    will return:

    (1,255), 255: 100
    (1,255), 127: 50
    (1,255), 10: 4
    """
    ...

and

def scale_to_ranged_value(
    source_low_high_range: tuple[float, float],
    target_low_high_range: tuple[float, float],
    value: int,
) -> float:
    """Given a range of low and high values convert a single value to another range.

    Do not include 0 in a range if 0 means off,
    e.g. for brightness or fan speed.

    Given a source low value of 1 and a high value of 255 and
    a target range from 1 to 100 this function
    will return:

    (1,255), 255: 100
    (1,255), 127: ~49.8039
    (1,255), 10: ~3.9216
    """
    ...

Utils int_states_in_range and states_in_range are moved​

These utils are now under homeassistant.util.scaling. If these are used in your custom integration, make sure you update the import to the new module.