Add dilation/erosion and morphological operation (open - close)

[gjeanner]

Je propose d’ajouter des opérations de dilatation/érosion et de morphologie simple (ouverture/fermeture) pour les objets portion.Interval. L’objectif est de permettre des extensions ou réductions d’intervalles directement via apply tout en restant cohérent avec l’esprit de portion.

Motivation :
Actuellement, il n’existe pas d’API native pour décaler facilement les bornes d’un intervalle de manière abstraite (temps, distance, etc.). L’implémentation proposée s’appuie sur apply, ce qui reste simple et performant.

Points clés :

• L’érosion est obtenue via dilate_intervals avec magnitude < 0.
• Ouverture/fermeture morphologique = deux dilatations successives.
• Conserve la simplicité et la flexibilité de portion tout en ajoutant des fonctionnalités utiles.

Questions / discussion :

• Serait-il pertinent d’ajouter ces méthodes directement à l’API Interval ?
  -Devrait-on prévoir des tests unitaires spécifiques pour ces nouvelles opérations ?

import portion as P
from portion import Interval, closed
from datetime import timedelta


##### Dilatation (et érosion via magnitude négative) #####
def _shift_interval(interval: Interval, magnitude: float, bound: str):
    """Décale un intervalle selon la magnitude et le côté choisi.

    Parameters
    ----------
    interval : Interval
        Intervalle à décaler.
    magnitude : float
        Quantité de décalage (abstraite, e.g., temps, distance...).
    bound : str
        Côté à décaler : 'both', 'low', ou 'high'.

    Returns
    -------
    Interval
        L'intervalle décalé.
    """
    if bound == "both":
        return closed(interval.lower - magnitude, interval.upper + magnitude)
    elif bound == "low":
        return closed(interval.lower - magnitude, interval.upper)
    elif bound == "high":
        return closed(interval.lower, interval.upper + magnitude)
    else:
        raise ValueError(f"Invalid value for 'bound': {bound!r}. Expected 'both', 'low', or 'high'.")


def dilate_intervals(intervals: Interval, magnitude: int | float, bound: str = "both") -> Interval:
    """Applique une dilatation (ou érosion si magnitude négative) à un ensemble d'intervalles.

    Parameters
    ----------
    intervals : Interval
        Collection d'intervalles à modifier.
    magnitude : float
        Quantité de dilatation (positive) ou d'érosion (négative).
    bound : str, optional
        Côté à modifier : 'both', 'low', ou 'high'. Par défaut 'both'.

    Returns
    -------
    Interval
        Les intervalles modifiés.
    """
    if not isinstance(magnitude, (int, float, timedelta)):
        raise TypeError(f"'magnitude' must be numeric, not {type(magnitude).__name__}.")
    return intervals.apply(lambda x: _shift_interval(x, magnitude, bound))


##### Opérations morphologiques simplifiées #####
def open_intervals(interval: Interval, magnitude: int | float) -> Interval:
    """Ouverture morphologique : érosion puis dilatation."""
    # open = dilate(dilate(interval, -magnitude), +magnitude)
    result = dilate_intervals(dilate_intervals(interval, -magnitude), +magnitude)
    valid_intervals = P.empty()
    for inter in result:
        if inter.lower < inter.upper:
            valid_intervals |= P.closed(inter.lower, inter.upper)
    return valid_intervals


def close_intervals(interval: Interval, magnitude: int | float) -> Interval:
    """Fermeture morphologique : dilatation puis érosion."""
    # close = dilate(dilate(interval, +magnitude), -magnitude)
    result = dilate_intervals(dilate_intervals(interval, +magnitude), -magnitude)
    valid_intervals = P.empty()
    for inter in result:
        if inter.lower < inter.upper:
            valid_intervals |= P.closed(inter.lower, inter.upper)
    return valid_intervals
 

[AlexandreDecan]

Bonjour,

Je propose de poursuivre ici plutôt que par e-mail, par facilité (et pour tout centraliser). Comme dit par e-mail, j'ai l'impression que ces opérations peuvent s'implémenter assez facilement en utilisant une combinaison de apply/replace :

i.apply(lambda x: x.replace(lower=lambda v: v - d, upper=lambda v: v +d)) où "d" représente la dilatation (valeur positive) ou l'érosion (valeur négative).

Dès lors, je ne suis pas convaincu qu'il est utile d'intégrer directement ces fonctions dans l'API de portion. Par contre, je suis d'avis d'ajouter une référence vers cette discussion/issue depuis la documentation, afin de fournir un pointeur à ceux qui souhaitent faire usage de ces opérations (il faudrait juste qu'on passe en anglais pour que tout le monde puisse en profiter ;-))

[gjeanner]

Tu as tout à fait raison, je n'avais compris au départ, la question de la dilution / érosion n’est effectivement plus d’actualité, la mise en œuvre s’avère finalement très simple avec apply et replace, comme tu le montres. 😄

En revanche, il reste à trancher sur la gestion de l’ouverture et de la fermeture : doit-on les considérer comme des opérations composées à proposer directement, ou simplement les illustrer dans la doc via un exemple d’usage ?

Voici un exemple de ce que le code pourrait donner, avec la docstring en anglais 😉. Les noms de fonctions, variables et types sont bien sûr ouverts à modification.

Remarque, les fonctions pourrait aussi être des méthodes d'Interval (en remplaçant simplement l'argument interval par keyword self)

import portion as P
from portion import Interval

def open_intervals(interval: Interval, erosion_offset: int | float, dilation_offset: int | float) -> Interval:
    """
    Performs the morphological opening of an interval.

    The opening operation consists of an erosion followed by a dilation.
    It is typically used to remove small artifacts or irregularities in the interval
    while preserving the overall shape.

    Parameters
    ----------
    interval : Interval
        The input interval to process.
    erosion_offset : int | float
        The amount by which to shrink (erode) the interval boundaries.
        Positive values reduce the size of the interval.
    dilation_offset : int | float
        The amount by which to expand (dilate) the interval boundaries.
        Positive values increase the size of the interval.

    Returns
    -------
    Interval
        The interval after applying the opening operation (erosion followed by dilation).

    Examples
    --------
    >>> i = P.closed(10, 22) | P.closed(30, 55)
    >>> open_intervals(i, erosion_offset=1, dilation_offset=2)
    [9,23] | [29,56]
    """
    # Step 1: Erosion (shrink the interval)
    eroded = interval.apply(
        lambda x: x.replace(
            lower=lambda v: v + erosion_offset,
            upper=lambda v: v - erosion_offset
        )
    )
    # Step 2: Dilation (expand the interval)
    opened = eroded.apply(
        lambda x: x.replace(
            lower=lambda v: v - dilation_offset,
            upper=lambda v: v + dilation_offset
        )
    )
    return opened


def close_intervals(interval: Interval, dilation_offset: int | float, erosion_offset: int | float) -> Interval:
    """
    Performs the morphological closing of an interval.

    The closing operation consists of a dilation followed by an erosion.
    It is typically used to fill small gaps or holes in an interval while
    preserving its overall boundaries.

    Parameters
    ----------
    interval : Interval
        The input interval to process.
    dilation_offset : int | float
        The amount by which to expand (dilate) the interval boundaries.
        Positive values increase the size of the interval.
    erosion_offset : int | float
        The amount by which to shrink (erode) the interval boundaries.
        Positive values reduce the size of the interval.

    Returns
    -------
    Interval
        The interval after applying the closing operation (dilation followed by erosion).

    Examples
    --------
    >>> i = P.closed(10, 22) | P.closed(30, 55)
    >>> close_intervals(i, dilation_offset=1, erosion_offset=3)
    [12,20] | [32,53]
    """
    return open_intervals(interval, dilation_offset=-erosion_offset, erosion_offset=-dilation_offset)

open_intervals(P.closed(10, 22) | P.closed(30, 55), erosion_offset=1, dilation_offset=2)
close_intervals(P.closed(10, 22) | P.closed(30, 55), dilation_offset=1, erosion_offset=3)

[AlexandreDecan]

En revanche, il reste à trancher sur la gestion de l’ouverture et de la fermeture : doit-on les considérer comme des opérations composées à proposer directement, ou simplement les illustrer dans la doc via un exemple d’usage ?

Je suis plutôt d'avis de les illustrer dans la documentation (ou plutôt, de faire référence au code que tu proposes ci-dessus). Je ne suis pas convaincu de la valeur ajoutée de supporter ces opérations directement dans portion puisque cela s'implémente relativement facilement (en réalité : "facilement" ici est un peu trompeur, l'implémentation n'est pas forcément triviale, mais une fois qu'on a le code, sa compréhension et son utilisation est naturelle...) D'où l'ide de proposer ce code plutôt comme "recette" dans la documentation, et non directement dans portion.

Je vais également réfléchir dans quelle mesure il serait judicieux d'inclure une sorte de "FAQ" ou "Recipes" dans la documentation, voire éventuellement proposer ces différents morceaux de code plus "spécifiques" au travers d'un module contrib (mais j'aime moins cela, car je ne souhaite pas spécialement m'engager dans la maintenance de cette partie du code :-))