gri-convolve 0.2.0__py3-none-any.whl

gri_convolve/__init__.py

@@ -0,0 +1,5 @@
+"""Convolve points and ellipses/ellipsoids."""
+
+from .convolve import cluster_convolve, convolve, smart_convolve
+
+__all__ = ["cluster_convolve", "convolve", "smart_convolve"]

gri_convolve/altitude/__init__.py

@@ -0,0 +1,5 @@
+"""Altitude function to provide to smart_convolve."""
+
+from .nearest import nearest
+
+__all__ = ["nearest"]

gri_convolve/altitude/nearest.py

@@ -0,0 +1,28 @@
+"""Simple nearest distance altitude setter for smart convolve."""
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from gri_pos import LLA
+
+
+def nearest(inputs: Sequence[tuple[LLA, list[LLA]]]) -> list[float]:
+    """Take a list of (LLA, list[LLA]) and output the nearest altitude in list.
+
+    Args:
+        inputs(Sequence[tuple[LLA, list[LLA]]]): The LLA point to find the nearest
+            altitude to, and the list of LLA points to search for the nearest point.
+
+    Returns:
+        list of altitudes in the same order as points
+    """
+    alts: list[float] = []
+    for lla, points in inputs:
+        dist = [lla.dist_surface_simple_m(p) for p in points]
+        idx = np.argmin(dist)
+        alts.append(points[idx].alt_m)
+    return alts

gri_convolve/convolve/__init__.py

@@ -0,0 +1,7 @@
+"""Methods to convolve points and ellipses/ellipsoids."""
+
+from .cluster_convolve import cluster_convolve
+from .convolve import convolve
+from .smart_convolve import smart_convolve
+
+__all__ = ["cluster_convolve", "convolve", "smart_convolve"]

gri_convolve/convolve/atwa_convolve.py

@@ -0,0 +1,186 @@
+# ruff: noqa: T201
+"""Test methods to compare various convolution methods. Not for production use."""
+
+# NOTE: Test functions ... this should not be used. Use convolve instead.
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+from gri_ell import Ell
+from gri_pos import Pos
+from gri_utils import conversion
+from scipy.linalg import block_diag
+
+if TYPE_CHECKING:
+    from collections.abc import Generator, Sequence
+
+
+def atwa_convolve(ells: Sequence[Ell] | Generator[Ell]) -> Ell:
+    """Compare various convolve types.
+
+    Args:
+        ells(Sequence[Ell]): A set of ell objects. Uses xyz and info.
+
+    Returns:
+        Ell
+    """
+    np.set_printoptions(suppress=True, precision=5)
+    ell = _position(ells)
+    print("\nATWAI_ENU")
+    # print(np.array(ell.cov.semi_axis_vec))
+    print(ell.cov)
+    print(ell.ellipse)
+
+    ell2 = _std_cov(ell, ells)
+    print("\nSTD COV")
+    # print(np.array(ell2.cov.semi_axis_vec))
+    print(ell2.cov)
+    print(ell2.ellipse)
+
+    ell3 = _bart_cov(ell, ells)
+    print("\nBART COV")
+    # print(np.array(ell2.cov.semi_axis_vec))
+    print(ell3.cov)
+    print(ell3.ellipse)
+
+    ell4 = _bart_cov2(ell, ells)
+    print("\nBART COV 2")
+    # print(np.array(ell2.cov.semi_axis_vec))
+    print(ell4.cov)
+    print(ell4.ellipse)
+
+    return ell3
+
+
+def _position(ells: Sequence[Ell] | Generator[Ell]) -> Ell:
+    """Get the position of the convolved point with direct covariance."""
+    # 3Nx3 identity stack
+    a = np.vstack([np.identity(3) for _ in ells])
+    # 3Nx3N diagonalized information matrices
+    w = block_diag(*(ell.info for ell in ells))
+    # 3Nx1 xyz positions
+    y = np.concatenate([e.xyz for e in ells])
+    atw = a.T @ w  # 3x3N
+    atwa = atw @ a  # 3x3
+    atwy = atw @ y  # 3x1
+    atwai = np.linalg.inv(atwa)  # 3x3
+    xyz = atwai @ atwy  # 3x1
+    atwai = conversion.xyz_to_enu_cov(xyz, atwai)
+    return Ell.COV(Pos.XYZ(xyz), atwai)
+
+
+def _std_cov(pos: Pos, ellipsoids: Sequence[Ell] | Generator[Ell]) -> Ell:
+    """Get the covariance the standard way."""
+    norm = 0
+    s = np.zeros((3, 3), dtype=float)
+    s_model = np.zeros((3, 3), dtype=float)
+    n = 0
+    for e in ellipsoids:
+        n += 1
+        w = e.info  # xyz, 1/m^2, 1 sigma
+        s_model += w
+        del_xyz = pos.delta_xyz(e)
+        norm += float(del_xyz @ w @ del_xyz)
+        s += np.outer(del_xyz, del_xyz)
+    s_model = np.linalg.inv(s_model)
+    x_2 = norm
+    s_mod_inflated = (x_2 + 1) / n * s_model
+    s_sample = s / n**2
+    cov = s_mod_inflated + s_sample
+    cov = conversion.xyz_to_enu_cov(pos.xyz, cov)
+    return Ell.COV(pos, cov)
+
+
+def _bart_cov(pos: Pos, ellipsoids: Sequence[Ell] | Generator[Ell]) -> Ell:
+    """Get the sample_smi variation of covariance."""
+    norm = 0
+    s = np.zeros((3, 3), dtype=float)
+    s_model = np.zeros((3, 3), dtype=float)
+    n = 0
+    for e in ellipsoids:
+        n += 1
+        w = e.info  # xyz, 1/m^2, 1 sigma
+        s_model += w
+        del_xyz = pos.delta_xyz(e)
+        norm += float(del_xyz @ w @ del_xyz)
+        # Bart's correction is to s
+        theta = e.ellipse.ori_rad
+        del_n1 = (pos.lla.lat_deg - e.lla.lat_deg) * 60 * 1.852 * 1000
+        avg_lat = (pos.lla.lat_deg + e.lla.lat_deg) / 2
+        del_e1 = (
+            (pos.lla.lon_deg - e.lla.lon_deg)
+            * 60
+            * 1.852
+            * np.cos(np.radians(avg_lat))
+            * 1000
+        )
+        del_smi = del_e1 * np.cos(theta) - del_n1 * np.sin(theta)
+        del_e = del_smi * np.cos(theta)
+        del_n = -del_smi * np.sin(theta)
+        enu_vec = np.array((del_e, del_n, pos.lla.alt_m - e.lla.alt_m))
+        s += np.outer(enu_vec, enu_vec)
+        # End bart's correction
+    s_model = np.linalg.inv(s_model)
+    x_2 = norm
+    s_mod_inflated = (x_2 + 1) / n * s_model
+    s_mod_inflated = conversion.xyz_to_enu_cov(pos.xyz, s_mod_inflated)
+    s_sample = s / n**2
+    cov = s_mod_inflated + s_sample
+    return Ell.COV(pos, cov)
+
+
+def _bart_cov2(pos: Pos, ellipsoids: Sequence[Ell] | Generator[Ell]) -> Ell:
+    """Original implementations."""
+    # s_model_inflated section
+    n = len(list(ellipsoids))
+    # chi squared
+    chi_squared = 0
+    for e in ellipsoids:
+        w = e.info  # xyz, 1/m^2, 95%
+        del_xyz = pos.delta_xyz(e)
+        chi_squared += float(del_xyz @ w @ del_xyz)
+
+    # inflation factor
+    inflation_factor = (chi_squared + 1) / n
+
+    # s model
+    s_model = np.zeros((3, 3))
+    for e in ellipsoids:
+        s_model += e.info
+    s_model = np.linalg.inv(s_model)
+
+    # inflated model
+    s_model_inflated = inflation_factor * s_model
+
+    # rotate from ecef to enu
+    s_model_inflated = conversion.xyz_to_enu_cov(pos.xyz, s_model_inflated)
+
+    # s_sample_minor
+    delta_enus = []
+    for e in ellipsoids:
+        orient_rad = e.ellipse.ori_rad
+
+        delta_north = 1.852 * 60 * (pos.lla.lat_deg - e.lla.lat_deg) * 1000
+        delta_east = (
+            1.852
+            * 60
+            * (pos.lla.lon_deg - e.lla.lon_deg)
+            * np.cos(np.radians((pos.lla.lat_deg + e.lla.lat_deg) / 2))
+            * 1000
+        )
+
+        delta_smi = delta_east * np.cos(orient_rad) - delta_north * np.sin(orient_rad)
+
+        delta_e = delta_smi * np.cos(orient_rad)
+        delta_n = -delta_smi * np.sin(orient_rad)
+        delta_up = pos.lla.alt_m - e.lla.alt_m
+
+        delta_enus.append(np.array([[delta_e], [delta_n], [delta_up]]))
+
+    s_sample_minor = 0
+    for enu in delta_enus:
+        s_sample_minor += enu @ enu.T
+    s_sample_minor /= n**2
+
+    cov = s_model_inflated + s_sample_minor
+    return Ell.COV(pos, cov)

gri_convolve/convolve/cluster_convolve.py

@@ -0,0 +1,260 @@
+"""Find multiple convolved points with outlier detection."""
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+from gri_ell import Ell
+from gri_pos import Pos
+
+from .smart_convolve import smart_convolve
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Generator, Sequence
+
+    from gri_pos import LLA
+
+
+def cluster_convolve(  # noqa: PLR0913
+    ellipsoids: Sequence[Ell] | Generator[Ell],
+    *,
+    max_norm: float = 2,
+    min_pts: int = 3,
+    max_pts: int | None = None,
+    min_sma_m: float = 0,
+    max_ori_spread: bool = True,
+    alt_post_process: Callable[[Sequence[tuple[LLA, list[LLA]]]], Sequence[float]]
+    | None = None,
+    alt_post_process_fudge_m: float = 0,
+    # Can give a function that does the spline in utils, can take nearest, nearest+int,
+    # spline, spline+int # spline would need scipy in utils ... do we want that? Probs.
+    # alt can be handled by:
+    #   dted: https://pypi.org/project/dted/
+    #   elevation:  https://pypi.org/project/elevation/
+    #   google: https://developers.google.com/maps/documentation/javascript/elevation
+    #           https://airsci.com/google-maps-elevation-api-python-example/
+) -> tuple[list[Ell], list[list[int]], list[int]]:
+    """Find the convolved point location from all the points.
+
+    Returns a list of Ell convolved locations, the list of Ells per position that were
+    used by that location (such that return[1][1] is the list of Ells in return[1]), and
+    a list of remaining / discarded Ells.
+
+    Args:
+        ellipsoids(Sequence[Ell]|Generator[Ell]): A set of ell objects. Uses xyz and
+            info.
+        max_norm(float, optional): Maximum mahalanobis distance from convolved point to
+            allow. If an input it outside that range (input ell to point distance), add
+            it to the discard list and return it. Defaults to 2.0
+        min_pts(int, optional): Minimum allowed points in a convolved answer. Defaults
+            to 3
+        max_pts(int, optional): Maximum allowed points in a convolved answer. If there
+            are leftover points (eg: 5 points passed, 3 max and 3 min, 2 left over that
+            cannot be used), they will be added to discard. This takes more processing.
+        min_sma_m(float, optional): Do not allow final convolved sma to go below min
+            sma unless min_pts is reached. This will split up convolutions. If there are
+            leftover points that cannot be used, they will be added to discard. This
+            is iterative and takes a lot more processing.
+        max_ori_spread(bool, optional): If set to true, for any clusters that need to be
+            split up for min_sma or max_pts, first sort the data by orientation, then
+            split into quarters and shuffle so that maximal orientation differences are
+            seen by the convolver.
+        alt_post_process(Callable[[Sequence[tuple[LLA,Sequence[LLA]]]], Sequence[float]], optional):
+            A function that takes a list of (LLA,list[LLA]) where LLA is an np.ndarray
+            vector that is latitude degrees, longitude degrees, altitude meters. The
+            first element is the convolved location and the second element is the list
+            of positions (Ells) as LLAs that went into that location.  Sequences are
+            required to enable batch processing by the function.
+
+            It should then output a list of altitudes in the same order as the input
+            list.
+
+            This package provides altitude.nearest, which replaces the Ell altitude with
+            the nearest Ell altitude (often a decent estimate).
+        alt_post_process_fudge_m(float, optional): Adds a set amount of meters to the
+            altitude after any other alt_post_process function.
+
+    Returns:
+        (list[Ell], list[list[used Ells indexes]], list[discarded Ells indexes])
+    """  # noqa: E501
+    # To keep track of the index, make it a list of tuple[idx,ell]
+    ells = [(idx, ell) for idx, ell in enumerate(ellipsoids)]
+    if max_ori_spread:
+        # sort by ori, split into quarters and shuffle
+        ells = _max_spread_ori(ells)
+
+    locations, loc_ells, discards = _first_pass(ells, max_norm, min_pts)
+
+    # Now we have the collections that should go together (roughly), let's post process
+    reprocess: list[int] = []
+    for idx, (loc, loc_ell) in enumerate(zip(locations, loc_ells, strict=False)):
+        if (
+            max_pts is not None and len(loc_ell) > max_pts
+        ) or loc.ellipse.sma_95 < min_sma_m:
+            reprocess.append(idx)
+    for idx in reprocess:
+        new_locs, new_ells, new_discards = _reprocess(
+            [ells[i] for i in loc_ells[idx]],
+            max_norm,
+            min_pts,
+            max_pts,
+            min_sma_m,
+            max_ori_spread,
+        )
+        locations.extend(new_locs)
+        loc_ells.extend(new_ells)
+        discards.extend(new_discards)
+    for idx in reprocess[::-1]:
+        del locations[idx]
+        del loc_ells[idx]
+
+    # Adjust the altitude with a post process function if supplied and add any
+    # fudge altitude distances
+    if alt_post_process is not None or alt_post_process_fudge_m != 0:
+        locations = _fix_alts(
+            ells,
+            locations,
+            loc_ells,
+            alt_post_process,
+            alt_post_process_fudge_m,
+        )
+
+    # Sort the index lists
+    discards.sort()
+    loc_ells = [sorted(idxs) for idxs in loc_ells]
+    # Now sort by min ell sma (smallest to largest)
+    if len(locations) > 0:
+        tups = sorted(
+            zip(locations, loc_ells, strict=True),
+            key=lambda x: x[0].ellipse.sma_95,
+        )
+        locations, loc_ells = zip(*tups, strict=True)
+    return list(locations), list(loc_ells), discards
+
+
+def _max_spread_ori(ells: list[tuple[int, Ell]]) -> list[tuple[int, Ell]]:
+    """Spread the data into quarters by ori."""
+    ells = sorted(ells, key=lambda x: x[1].ellipse.ori_deg)
+    a = np.array([e[0] for e in ells], dtype=int)
+    add = np.array([-1] * int(np.ceil(len(a) / 4) * 4 - len(a)), dtype=int)
+    a = np.append(a, add)
+    a = a.reshape((4, -1))
+    a = a.T.flatten()
+    a = a[a >= 0]
+    return [ells[idx] for idx in a]
+
+
+def _reprocess(  # noqa: PLR0913
+    loc_ells: list[tuple[int, Ell]],
+    max_norm: float = 2,
+    min_pts: int = 3,
+    max_pts: int | None = None,
+    min_sma_m: float = 0,
+    max_ori_spread: bool = False,  # noqa: FBT001, FBT002
+) -> tuple[list[Ell], list[list[int]], list[int]]:
+    """Find any indexes (loc,loc_ells) that we need to reprocess for max_pts or min_sma.
+
+    Reprocess them in place. Remove from lists, add to tail end with new answers.
+    """
+    if max_ori_spread:
+        # respread
+        loc_ells = _max_spread_ori(loc_ells)
+
+    if max_pts is None:
+        max_pts = len(loc_ells)
+
+    start = 0
+    stop = max_pts
+    ells = [ell for _, ell in loc_ells]
+    new_locs: list[Ell] = []
+    new_loc_ells: list[list[int]] = []
+    new_discarded: list[int] = []
+    while stop - start >= min_pts:
+        ans = smart_convolve(
+            ells[start:stop],
+            max_norm=max_norm,
+            min_pts=min_pts,
+        )
+        if ans is None:
+            # odd case where we can't find an answer within max_pts but could with
+            # the whole number of ells. Skip this batch
+            start = stop
+            stop = min(start + max_pts + 1, len(ells))
+            new_discarded.extend(list(range(start, stop)))
+            continue
+        ell, used, discard = ans
+        if min_sma_m > 0 and ell.ellipse.sma_95 < min_sma_m and stop - start > min_pts:
+            stop -= 1
+            continue
+        # discards are unlikely in this case, just skip handling them
+        new_discarded.extend([loc_ells[d + start][0] for d in discard])
+        new_locs.append(ell)
+        new_loc_ells.append([loc_ells[u + start][0] for u in used])
+        start = stop
+        stop = min(start + max_pts, len(ells))
+    # Add any unused at the tail
+    new_discarded.extend(range(start, stop))
+    return new_locs, new_loc_ells, new_discarded
+
+
+def _fix_alts(
+    ells: list[tuple[int, Ell]],
+    locations: list[Ell],
+    loc_ells: list[list[int]],
+    alt_post_process: Callable[[Sequence[tuple[LLA, list[LLA]]]], Sequence[float]]
+    | None = None,
+    alt_post_process_fudge_m: float = 0,
+) -> list[Ell]:
+    """Use the provided function to adjust altitudes, and add any fudge factor."""
+    # Get base alts
+    if alt_post_process is not None:
+        # Convert to LLAs
+        pos = [e.lla for e in locations]
+        pos_lists = [[ells[idx][1].lla for idx in idx_list] for idx_list in loc_ells]
+        # Get alts
+        alts = alt_post_process(list(zip(pos, pos_lists, strict=True)))
+    else:
+        # Get existing alts
+        alts = [e.lla.alt_m for e in locations]
+    # Replace alts
+    new_ell: list[Ell] = []
+    for alt, ell in zip(alts, locations, strict=True):
+        new_ell.append(
+            Ell.COV(
+                Pos.LLA(
+                    ell.lla.lat_deg,
+                    ell.lla.lon_deg,
+                    alt + alt_post_process_fudge_m,
+                ),
+                ell.cov,
+            ),
+        )
+    return new_ell
+
+
+def _first_pass(
+    ells: list[tuple[int, Ell]],
+    max_norm: float = 2,
+    min_pts: int = 3,
+) -> tuple[list[Ell], list[list[int]], list[int]]:
+    """First smart convolve pass.
+
+    Get all convolved locations to cluster data regardless of max size or min sma.
+    """
+    locations: list[Ell] = []
+    loc_ells: list[list[int]] = []
+    # To keep track of the index, make it a list of tuple[idx,ell]
+    # First pass
+    while ans := smart_convolve(
+        [ell for _, ell in ells],
+        max_norm=max_norm,
+        min_pts=min_pts,
+    ):
+        ell, used, discard = ans
+        # Add location
+        locations.append(ell)
+        # Add the original indexes to the location ell
+        loc_ells.append([e[0] for idx, e in enumerate(ells) if idx in used])
+        # redo ells list to be the remainint tuples of unused ells
+        ells = [e for idx, e in enumerate(ells) if idx in discard]
+
+    return locations, loc_ells, [e[0] for e in ells]

gri_convolve/convolve/convolve.py

@@ -0,0 +1,88 @@
+"""Convolution of all points.
+
+Find the center of the points via convolution and find the error region via different
+inflation methods.
+"""
+
+from typing import TYPE_CHECKING, Literal
+
+import numpy as np
+from gri_ell import Ell
+from gri_pos import Pos
+from gri_utils import conversion
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
+def convolve(
+    ellipsoids: Sequence[Ell],
+    *,
+    inflation: Literal["none", "std", "bart"] = "bart",
+) -> Ell:
+    """Find the convolved point location from all the points.
+
+    Does not throw away any points. Choose an inflation technique to estimate the error
+    region.
+
+    Args:
+        ellipsoids: A set of ell objects. Uses xyz and info.
+        inflation: "none" performs strict covariance calculations by combining
+            information matrices. "std" inflates covariance based on the sample
+            distribution, "bart" inflates covariances based on SMI reduction rules.
+
+    Returns:
+        Ell
+    """
+    # Find the position and basic uninflated covariance
+    s_model = np.add.reduce([e.info for e in ellipsoids])  # xyz, 1/m^2, 1-sigma
+    s_var = np.add.reduce([e.info @ e.xyz for e in ellipsoids])
+    cov = np.linalg.inv(s_model)
+    pos = Pos.XYZ(cov @ s_var)
+    ell = Ell.COV(pos, cov)
+    if inflation == "none":
+        return ell
+
+    # Begin normalized and smi-normalized inflation of covariance
+    s_model = cov
+    n = len(ellipsoids)
+    x_2 = 0
+    s = np.zeros((3, 3), dtype=float)
+    for e in ellipsoids:
+        del_xyz = pos.delta_xyz(e)
+        x_2 += float(del_xyz @ e.info @ del_xyz)
+        if inflation == "std":
+            s += np.outer(del_xyz, del_xyz)
+        elif inflation == "bart":
+            theta = e.ellipse.ori_rad
+
+            delta_north = 1.852 * 60 * 1000 * (pos.lla.lat_deg - e.lla.lat_deg)
+            delta_east = (
+                1.852
+                * 60
+                * 1000
+                * (pos.lla.lon_deg - e.lla.lon_deg)
+                * np.cos(np.radians((pos.lla.lat_deg + e.lla.lat_deg) / 2))
+            )
+
+            delta_smi = delta_east * np.cos(theta) - delta_north * np.sin(theta)
+
+            del_e = delta_smi * np.cos(theta)
+            del_n = -delta_smi * np.sin(theta)
+            del_u = pos.lla.alt_m - e.lla.alt_m
+
+            enu_vec = np.array((del_e, del_n, del_u))
+
+            s += np.outer(enu_vec, enu_vec)
+        else:
+            raise ValueError("Bad inflation setting")
+    s_sample = s / n**2
+    s_mod_inflated = (x_2 + 1) / n * s_model
+    # s_mod_inflated is in xyz
+    # std s_sample is in xyz, bart s_sample is in enu
+    if inflation == "std":
+        cov = conversion.xyz_to_enu_cov(pos.xyz, s_mod_inflated + s_sample)
+    else:
+        s_mod_inflated = conversion.xyz_to_enu_cov(pos.xyz, s_mod_inflated)
+        cov = s_mod_inflated + s_sample
+    return Ell.COV(pos, cov)

gri_convolve/convolve/smart_convolve.py

@@ -0,0 +1,72 @@
+"""Find convolved point with outlier detection."""
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+from gri_utils import constants
+
+from .convolve import convolve
+
+if TYPE_CHECKING:
+    from collections.abc import Generator, Sequence
+
+    from gri_ell import Ell
+
+
+def smart_convolve(
+    ellipsoids: Sequence[Ell] | Generator[Ell],
+    *,
+    max_norm: float = 2,
+    min_pts: int = 3,
+) -> None | tuple[Ell, list[int], list[int]]:
+    """Find the convolved point location from all the points.
+
+    Returns an Ell (or None), the list of Ells (by index) used to make that
+    ellipsoid, and the remaining Ells (by index) that were excluded.
+
+    Useful to tell all the points that should go together (by norm) and remove the
+    points that do not belong.
+
+    Note that outlier convolve can (incorrectly) return no answer when an answer does
+    exist if the data is not pre-clustered decently. EG: a valid cluster of five points
+    and a invalid group of twenty points further away that does not convolve will
+    exclude the five points first by norm, then exclude each other. Roughly pre-cluster
+    your data before using this function.
+
+    Args:
+        ellipsoids(Sequence[Ell]|Generator[Ell]): A set of ell objects. Uses xyz and
+            info.
+        max_norm(float, optional): Maximum ellipse norm distance from convolved point to
+            allow. If an input it outside that range (input ell to point distance), add
+            it to the discard list and return it. Defaults to 2.0
+        min_pts(int, optional): Minimum allowed points in a convolved answer. Defaults
+            to 3
+
+    Returns:
+        tuple[Ell, list[used Ells idx], list[discarded Ells idx]] or None
+    """
+    # To keep track of the index, make it a list of tuple[idx,ell]
+    ells = [(idx, ell) for idx, ell in enumerate(ellipsoids)]
+    # Verify length is minimal
+    if len(ells) < min_pts:
+        return None
+    unused: list[int] = []
+    # loop as long as we have enough ells until none are discarded or all are discarded.
+    while len(ells) >= min_pts:
+        ell, discard_idx = _test_norm([ell for _, ell in ells], max_norm)
+        if discard_idx is None:
+            # Answer found!
+            return ell, [idx for idx, _ in ells], unused
+        # Remove index from ells and add to unused
+        unused.append(ells[discard_idx][0])
+        del ells[discard_idx]
+    # Not enough left and no answer found
+    return None
+
+
+def _test_norm(ells: list[Ell], max_norm: float) -> tuple[Ell, int | None]:
+    """Get a discarded index at max norm distance or None if all are contained."""
+    ell = convolve(ells, inflation="none")
+    norms = [e.dist_mahalanobis(ell) / constants.SIG_TO_95_3D**0.5 for e in ells]
+    idx = int(np.argmax(norms))
+    return ell, idx if norms[idx] > max_norm else None

gri_convolve-0.2.0.dist-info/METADATA

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: gri-convolve
+Version: 0.2.0
+Project-URL: repository, https://gitlab.com/geosol-foss/python/gri-convolve
+Project-URL: homepage, https://geosolresearch.com
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.14
+Requires-Dist: gri-ell
+Requires-Dist: gri-pos
+Requires-Dist: gri-utils
+Requires-Dist: numpy>=2.3.3
+Description-Content-Type: text/markdown
+
+[![GeoSol Research Logo](https://geosolresearch.com/logos/foss_logo.png "GeoSol Research")](https://geosolresearch.com)
+
+# Convolve (Ellipsoid Fusion)
+
+Ellipsoid convolution functions for combining geolocation estimates with outlier detection and multi-cluster support.
+
+## Overview
+
+gri-convolve provides three functions of increasing sophistication for fusing collections of `Ell` (ellipsoid) objects into combined position estimates:
+
+- **`convolve`** -- combine all input ellipsoids into a single fused result with no outlier rejection
+- **`smart_convolve`** -- iteratively remove outliers by Mahalanobis distance before fusing
+- **`cluster_convolve`** -- find multiple clusters within a dataset and fuse each independently
+
+Each function operates on `Ell` objects from gri-ell, which pair a 3D position with a statistical covariance (or information matrix). The output is one or more fused `Ell` objects representing the combined position estimate and its uncertainty.
+
+Requires Python 3.14+.
+
+## Mathematical Background
+
+**Information matrix fusion.** Given N ellipsoids, each with position `x_k` and information matrix `I_k` (the inverse of the covariance matrix, in XYZ coordinates, 1/m^2, 1-sigma), the fused position and information matrix are:
+
+    S = sum(I_k)              (combined information matrix)
+    x = S^{-1} sum(I_k x_k)  (fused position)
+
+This is the maximum-likelihood estimator under Gaussian assumptions.
+
+**Inflation methods.** The raw fusion above underestimates uncertainty when inputs are inconsistent. Three modes control how the output covariance is inflated:
+
+- `"none"` -- strict information matrix combination (no inflation)
+- `"std"` -- inflate by the sample scatter of input positions in XYZ
+- `"bart"` -- inflate along the semi-major axis direction in ENU (recommended default)
+
+**Outlier detection.** `smart_convolve` computes the Mahalanobis distance from each input to the fused point:
+
+    d_M = sqrt((x - mu)^T I (x - mu))
+
+where `mu` is the fused position and `I` is its information matrix. Distances are normalized to 95% confidence scale. Inputs exceeding `max_norm` are iteratively removed, worst first.
+
+Reference: Mahalanobis, P.C. (1936). "On the generalized distance in statistics."
+
+## Installation
+
+```bash
+pip install gri-convolve
+```
+
+For development:
+
+```bash
+git clone https://gitlab.com/geosol-foss/python/gri-convolve.git
+cd gri-convolve
+. .init_venv.sh
+```
+
+## Quick Start
+
+```python
+from gri_convolve import convolve, smart_convolve, cluster_convolve
+from gri_ell import Ell
+from gri_pos import Pos
+import numpy as np
+
+# Create some ellipsoids at nearby positions
+e1 = Ell.from_2d(Pos.LLA(40.0, -105.0, 1600), 100, 50, 45)
+e2 = Ell.from_2d(Pos.LLA(40.001, -105.001, 1610), 120, 60, 30)
+e3 = Ell.from_2d(Pos.LLA(40.0005, -104.999, 1605), 90, 45, 50)
+
+# Simple fusion
+fused = convolve([e1, e2, e3])
+print(fused.lla)            # Fused position
+print(fused.ellipse.sma_95) # Fused semi-major axis (95%, meters)
+```
+
+## `convolve()`
+
+Fuses all input ellipsoids into a single result. No outlier detection.
+
+```python
+fused = convolve(ellipsoids, inflation="bart")
+```
+
+**Parameters:**
+
+- `ellipsoids` -- sequence of `Ell` objects
+- `inflation` -- `"none"`, `"std"`, or `"bart"` (default: `"bart"`)
+
+**Returns:** A single fused `Ell`.
+
+## `smart_convolve()`
+
+Fuses with iterative outlier rejection. Computes the fused point, finds the input with the largest normalized Mahalanobis distance, and removes it if it exceeds `max_norm`. Repeats until all remaining inputs are within tolerance or fewer than `min_pts` remain.
+
+```python
+result = smart_convolve(ellipsoids, max_norm=2.0, min_pts=3)
+if result is not None:
+    fused_ell, used_indices, discarded_indices = result
+```
+
+**Parameters:**
+
+- `ellipsoids` -- sequence of `Ell` objects
+- `max_norm` -- maximum allowed normalized distance (default: 2.0)
+- `min_pts` -- minimum inputs required for a valid result (default: 3)
+
+**Returns:** `(Ell, list[int], list[int])` or `None` if no valid cluster is found.
+
+Pre-cluster your data before calling `smart_convolve`. Without pre-clustering, a large group of scattered noise points can cause valid clusters to be discarded first.
+
+## `cluster_convolve()`
+
+Finds multiple clusters within a dataset by iteratively applying `smart_convolve`. After finding the largest valid cluster, the discarded points are passed back in to find additional clusters.
+
+```python
+locations, used_per_location, discarded = cluster_convolve(
+    ellipsoids,
+    max_norm=2.0,
+    min_pts=3,
+    max_pts=10,
+    min_sma_m=50.0,
+)
+
+for loc, indices in zip(locations, used_per_location):
+    print(f"Cluster at {loc.lla} using {len(indices)} inputs")
+```
+
+**Parameters:**
+
+- `ellipsoids` -- sequence of `Ell` objects
+- `max_norm` -- maximum normalized Mahalanobis distance (default: 2.0)
+- `min_pts` -- minimum inputs per cluster (default: 3)
+- `max_pts` -- maximum inputs per cluster; splits larger groups (default: None)
+- `min_sma_m` -- minimum semi-major axis for output ellipsoids in meters (default: 0)
+- `max_ori_spread` -- sort by orientation before splitting for diversity (default: True)
+- `alt_post_process` -- callback for altitude correction (e.g., snap to terrain)
+
+**Returns:** `(list[Ell], list[list[int]], list[int])`
+
+## Units and Conventions
+
+- Positions are in ECEF XYZ (meters) internally
+- Information matrices are in XYZ, 1/m^2, 1-sigma
+- Covariance matrices are in ENU, m^2, 1-sigma
+- Output ellipse parameters (SMA, SMI, orientation) are at 95% confidence
+- Mahalanobis distances are normalized to 95% scale for `max_norm` comparisons
+
+## Dependencies
+
+- **gri-ell**: Ellipsoid objects with position and covariance
+- **gri-pos**: Position objects (XYZ, LLA coordinates)
+- **gri-utils**: Coordinate conversions and constants
+- **numpy**: Array operations
+
+
+## Other Projects
+
+Current list of other [GRI FOSS Projects](.docs_other_projects.md) we are building and maintaining.
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

gri_convolve-0.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+gri_convolve/__init__.py,sha256=UAP0TyrpUN1IvpcIikEv_pgp8nPs6QQhsEBz_KVQ5-I,175
+gri_convolve/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gri_convolve/altitude/__init__.py,sha256=la-somGa2CQ2jv0D13fMFuQVIeWrBA-TdQVebCxpejY,107
+gri_convolve/altitude/nearest.py,sha256=JX1kU0rS0kGAw-euofynnyDsDjTPIi-ji67qOrtd6Co,820
+gri_convolve/convolve/__init__.py,sha256=zDdlA3mhvg0CeylrN3hec1f-RhQ5Ugr7ao5lkA76hGo,242
+gri_convolve/convolve/atwa_convolve.py,sha256=wm_VpJkWL05yPt3Jl3vTIR--TL55OjinQ19m7PEcA_Q,5563
+gri_convolve/convolve/cluster_convolve.py,sha256=kfHgLYCrN00ze52FeWz6QGPTqLt947n_HssgLjVPbcE,10142
+gri_convolve/convolve/convolve.py,sha256=homB2MrfGabMslD6qbP93miK9NMU4eaKisyLbeRC7MQ,2851
+gri_convolve/convolve/smart_convolve.py,sha256=k5MAgXL6aLoFisl2oIR5E7qaHQ6w-uFt6NwxdYUDO4w,2809
+gri_convolve-0.2.0.dist-info/METADATA,sha256=D3KxLJyZsUM_CxM4dDtOLl4KrPi6Yofzp6jN3JFQhKA,6382
+gri_convolve-0.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+gri_convolve-0.2.0.dist-info/licenses/LICENSE,sha256=Noh51pACFQty7ATtDK2D_6HNrc_UIcsyCFYJY0I9zEM,1077
+gri_convolve-0.2.0.dist-info/RECORD,,

gri_convolve-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

gri_convolve-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 GeoSol Research Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.