aissegments 0.2.0__py3-none-any.whl

aissegments/__init__.py

@@ -0,0 +1,37 @@
+"""AIS trajectory segmentation and feature-preserving compression.
+
+Public API:
+
+- :class:`Track` / :class:`Segment` — typed input/output containers.
+- :func:`to_segments` — pair consecutive points of a Track into Segment records.
+- :func:`tdkc` — Top-Down Kinematic Compression; returns a compressed Track.
+- :func:`tdkc_segments` — convenience wrapper: TDKC plus segment construction
+  with original-point-count enrichment.
+
+Reference
+---------
+Guo, S., Bolbot, V., & Valdez Banda, O. (2024). An adaptive trajectory
+compression and feature preservation method for maritime traffic analysis.
+*Ocean Engineering*, 312, 119189.
+"""
+from aissegments._types import Segment, Track, to_segments
+from aissegments.adapters import (
+    from_aisdb_track,
+    read_csv_static_records,
+    read_csv_tracks,
+)
+from aissegments.tdkc import tdkc, tdkc_segments
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "Segment",
+    "Track",
+    "__version__",
+    "from_aisdb_track",
+    "read_csv_static_records",
+    "read_csv_tracks",
+    "tdkc",
+    "tdkc_segments",
+    "to_segments",
+]

aissegments/_types.py

@@ -0,0 +1,153 @@
+"""Typed containers for AIS tracks and the linestring-segment records they yield."""
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+import numpy as np
+
+_FLOAT_FIELDS = ("t", "lon", "lat", "sog", "cog")
+
+
+@dataclass
+class Track:
+    """An ordered AIS track for a single vessel.
+
+    All array fields must be the same length and ``t`` must be
+    monotonically non-decreasing.  Construct via :meth:`from_arrays` to get
+    consistent ``float64`` dtypes; the constructor itself only validates.
+
+    Attributes
+    ----------
+    mmsi : int
+        Maritime Mobile Service Identity for the vessel.
+    t : numpy.ndarray
+        Unix timestamps in seconds since epoch (UTC).  Shape ``(N,)``.
+    lon, lat : numpy.ndarray
+        WGS84 longitude/latitude in degrees.  Shape ``(N,)``.
+    sog : numpy.ndarray
+        Speed over ground in knots.  Shape ``(N,)``.
+    cog : numpy.ndarray
+        Course over ground in degrees, ``[0, 360)``.  Shape ``(N,)``.
+    """
+
+    mmsi: int
+    t: np.ndarray
+    lon: np.ndarray
+    lat: np.ndarray
+    sog: np.ndarray
+    cog: np.ndarray
+
+    def __post_init__(self) -> None:
+        n = len(self.t)
+        for name in _FLOAT_FIELDS[1:]:
+            arr = getattr(self, name)
+            if len(arr) != n:
+                raise ValueError(
+                    f"Track field {name!r} has length {len(arr)}, expected {n}"
+                )
+        if n > 1:
+            diffs = np.diff(self.t)
+            if np.any(diffs < 0):
+                raise ValueError("Track.t must be monotonically non-decreasing")
+
+    def __len__(self) -> int:
+        return len(self.t)
+
+    @classmethod
+    def from_arrays(
+        cls,
+        mmsi: int,
+        t: Iterable[float],
+        lon: Iterable[float],
+        lat: Iterable[float],
+        sog: Iterable[float],
+        cog: Iterable[float],
+    ) -> Track:
+        """Coerce Python iterables / mixed dtypes into a validated ``Track``."""
+        return cls(
+            mmsi=int(mmsi),
+            t=np.asarray(list(t), dtype=np.float64),
+            lon=np.asarray(list(lon), dtype=np.float64),
+            lat=np.asarray(list(lat), dtype=np.float64),
+            sog=np.asarray(list(sog), dtype=np.float64),
+            cog=np.asarray(list(cog), dtype=np.float64),
+        )
+
+    def take(self, indices: Iterable[int]) -> Track:
+        """Return a new ``Track`` containing only the points at ``indices``."""
+        idx = np.asarray(list(indices), dtype=np.int64)
+        return Track(
+            mmsi=self.mmsi,
+            t=self.t[idx],
+            lon=self.lon[idx],
+            lat=self.lat[idx],
+            sog=self.sog[idx],
+            cog=self.cog[idx],
+        )
+
+
+@dataclass(frozen=True)
+class Segment:
+    """A constant-COG/SOG linestring between two key AIS points.
+
+    Attributes
+    ----------
+    mmsi : int
+        Vessel identifier.
+    t_start, t_end : float
+        Unix-second timestamps of the segment endpoints.
+    lon_start, lat_start, lon_end, lat_end : float
+        WGS84 coordinates (degrees) of the endpoints.
+    cog_mean, sog_mean : float
+        Mean course (degrees) and speed (knots) across the segment endpoints.
+    n_points : int
+        Number of *original* AIS points represented by the segment, including
+        both endpoints.  ``2`` if the segment was built without a backing
+        original track; ``>=2`` after enrichment by :func:`tdkc_segments`.
+    """
+
+    mmsi: int
+    t_start: float
+    t_end: float
+    lon_start: float
+    lat_start: float
+    lon_end: float
+    lat_end: float
+    cog_mean: float
+    sog_mean: float
+    n_points: int = 2
+
+
+def to_segments(track: Track) -> list[Segment]:
+    """Pair consecutive points of ``track`` into ``Segment`` records.
+
+    Each segment carries ``n_points = 2`` since the source track is treated as
+    already-compressed (or already-key-point-only).  Use
+    :func:`aissegments.tdkc_segments` if you need the original-point-count
+    enrichment.
+    """
+    n = len(track)
+    if n < 2:
+        return []
+    segments: list[Segment] = []
+    for i in range(n - 1):
+        # Course wrap: take the shorter of the two arc directions when the
+        # endpoints straddle 0/360.  Mean is then re-wrapped to [0, 360).
+        cog_diff = ((track.cog[i + 1] - track.cog[i] + 180.0) % 360.0) - 180.0
+        cog_mean = (track.cog[i] + cog_diff / 2.0) % 360.0
+        segments.append(
+            Segment(
+                mmsi=track.mmsi,
+                t_start=float(track.t[i]),
+                t_end=float(track.t[i + 1]),
+                lon_start=float(track.lon[i]),
+                lat_start=float(track.lat[i]),
+                lon_end=float(track.lon[i + 1]),
+                lat_end=float(track.lat[i + 1]),
+                cog_mean=float(cog_mean),
+                sog_mean=float((track.sog[i] + track.sog[i + 1]) / 2.0),
+                n_points=2,
+            )
+        )
+    return segments

aissegments/adapters.py

@@ -0,0 +1,354 @@
+"""Adapters for getting AIS data into ``aissegments``.
+
+- :func:`from_aisdb_track` — single AISdb track-dict → :class:`Track`.
+- :func:`read_csv_tracks` — generic CSV loader; groups by MMSI, returns one
+  :class:`Track` per vessel.  Recognises common column name variants
+  (Marine Cadastre's ``BaseDateTime``/``LAT``/``LON``, etc.) and parses
+  ISO 8601 timestamps as well as unix seconds.  Handles ``.gz`` transparently.
+- :func:`read_csv_static_records` — companion to ``read_csv_tracks`` that
+  surfaces per-vessel static fields (VesselType, Length, Width, Draft,
+  IMO, …) when the source CSV carries them.  Output is shaped to match
+  AISdb's static-row dict so downstream consumers can treat aisdb-decoded
+  data and rich-CSV data uniformly.
+
+None of these pull in extra runtime dependencies beyond ``numpy``.
+"""
+from __future__ import annotations
+
+import csv
+import gzip
+from collections import defaultdict
+from collections.abc import Mapping
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from aissegments._types import Track
+
+# Column aliases (all lower-cased before matching).  First element is the
+# canonical name used in error messages.
+_CSV_COLUMN_ALIASES: dict[str, tuple[str, ...]] = {
+    "mmsi": ("mmsi",),
+    "time": ("time", "basedatetime", "timestamp", "datetime", "date_time"),
+    "lon": ("lon", "longitude"),
+    "lat": ("lat", "latitude"),
+    "sog": ("sog", "speed"),
+    "cog": ("cog", "course"),
+}
+
+# Optional static-info columns recognised by :func:`read_csv_static_records`.
+# All aliases are matched lowercase.  Output keys mirror AISdb's static-row
+# dict so the same downstream code path can consume aisdb-decoded rows and
+# rich-CSV rows uniformly.
+_STATIC_COLUMN_ALIASES: dict[str, tuple[str, ...]] = {
+    "vessel_name": ("vesselname", "vessel_name", "name"),
+    "call_sign": ("callsign", "call_sign"),
+    "imo": ("imo", "imo_num"),
+    "ship_type": ("vesseltype", "ship_type", "shiptype"),
+    "destination": ("destination",),
+    # Source columns that get split into AISdb's per-quadrant antenna offsets.
+    "length": ("length", "loa", "ship_length"),
+    "width": ("width", "beam", "breadth"),
+    "draught": ("draft", "draught"),
+}
+
+
+def _resolve_csv_columns(fieldnames: list[str]) -> dict[str, str]:
+    """Map each canonical name to the actual header it found, or raise."""
+    lower_to_actual = {c.strip().lower(): c for c in fieldnames}
+    resolved: dict[str, str] = {}
+    missing: list[str] = []
+    for canonical, aliases in _CSV_COLUMN_ALIASES.items():
+        for alias in aliases:
+            if alias in lower_to_actual:
+                resolved[canonical] = lower_to_actual[alias]
+                break
+        else:
+            missing.append(canonical)
+    if missing:
+        raise KeyError(f"CSV missing required columns (any of these aliases): {missing}")
+    return resolved
+
+
+def _to_unix_seconds(value: str) -> float:
+    """Parse either a numeric unix-seconds timestamp or an ISO 8601 string.
+
+    Naive ISO timestamps are interpreted as UTC, the de-facto convention for
+    AIS data feeds.
+    """
+    s = value.strip()
+    try:
+        return float(s)
+    except ValueError:
+        pass
+    if s.endswith("Z"):
+        s = s[:-1] + "+00:00"
+    dt = datetime.fromisoformat(s)
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt.timestamp()
+
+
+def _open_text_csv(path: Path):
+    """Open a CSV file transparently, gunzipping if the suffix says so."""
+    if path.suffix.lower() == ".gz":
+        return gzip.open(path, "rt", newline="", encoding="utf-8")
+    return path.open(newline="", encoding="utf-8")
+
+
+def from_aisdb_track(track_dict: Mapping[str, Any]) -> Track:
+    """Convert an AISdb ``TrackGen`` track dictionary into an :class:`aissegments.Track`.
+
+    AISdb yields tracks as dictionaries with at least these keys:
+
+    - ``mmsi``  (scalar int)
+    - ``time``  (1-D array of unix seconds)
+    - ``lon``   (1-D array, degrees)
+    - ``lat``   (1-D array, degrees)
+    - ``sog``   (1-D array, knots)
+    - ``cog``   (1-D array, degrees)
+
+    Tracks are passed through with no resampling or smoothing — TDKC is
+    designed to operate on the raw AIS time series.
+
+    Parameters
+    ----------
+    track_dict : Mapping[str, Any]
+        A track dict in AISdb's column-array layout.
+
+    Returns
+    -------
+    Track
+        A validated :class:`aissegments.Track`.
+
+    Raises
+    ------
+    KeyError
+        If the dict is missing any required key.
+    ValueError
+        If the array fields disagree on length or ``time`` is not monotonic.
+    """
+    required = ("mmsi", "time", "lon", "lat", "sog", "cog")
+    missing = [k for k in required if k not in track_dict]
+    if missing:
+        raise KeyError(f"AISdb track dict is missing keys: {missing}")
+    return Track.from_arrays(
+        mmsi=int(track_dict["mmsi"]),
+        t=np.asarray(track_dict["time"], dtype=np.float64),
+        lon=np.asarray(track_dict["lon"], dtype=np.float64),
+        lat=np.asarray(track_dict["lat"], dtype=np.float64),
+        sog=np.asarray(track_dict["sog"], dtype=np.float64),
+        cog=np.asarray(track_dict["cog"], dtype=np.float64),
+    )
+
+
+def read_csv_tracks(path: Path | str) -> list[Track]:
+    """Load AIS pings from a CSV (optionally ``.gz``) and group them by MMSI.
+
+    The header row must contain (in any order, case-insensitive) one
+    column for each of the six required fields below.  Common aliases are
+    accepted so that files exported by different data providers work
+    out-of-the-box:
+
+    | Field | Recognised header names                                          |
+    |-------|------------------------------------------------------------------|
+    | mmsi  | ``mmsi``                                                         |
+    | time  | ``time``, ``BaseDateTime``, ``timestamp``, ``datetime``, ``date_time`` |
+    | lon   | ``lon``, ``longitude``, ``LON``                                  |
+    | lat   | ``lat``, ``latitude``, ``LAT``                                   |
+    | sog   | ``sog``, ``speed``                                               |
+    | cog   | ``cog``, ``course``                                              |
+
+    Time values are accepted as either:
+
+    - Unix seconds (numeric, e.g. ``1625097600``), or
+    - ISO 8601 strings (e.g. ``2019-01-01T14:15:12``, ``...Z``, or
+      ``...+00:00``).  Naive timestamps are interpreted as UTC.
+
+    Rows are grouped by ``mmsi`` and sorted by time within each group, so
+    the order of rows in the source file does not matter.
+
+    Parameters
+    ----------
+    path : Path or str
+        Path to a ``.csv`` or ``.csv.gz`` file.
+
+    Returns
+    -------
+    list[Track]
+        One :class:`Track` per unique MMSI, sorted by descending track length
+        so callers can pick the densest tracks easily.
+
+    Raises
+    ------
+    KeyError
+        If a required column is missing from the header.
+    ValueError
+        If the file is empty, or any required field is missing / non-numeric
+        / un-parseable.
+    """
+    path = Path(path)
+    by_mmsi: dict[int, list[tuple[float, float, float, float, float]]] = defaultdict(list)
+
+    with _open_text_csv(path) as f:
+        reader = csv.DictReader(f)
+        if reader.fieldnames is None:
+            raise ValueError(f"Empty CSV (no header row): {path}")
+        col_map = _resolve_csv_columns(list(reader.fieldnames))
+
+        for line_no, row in enumerate(reader, start=2):
+            try:
+                mmsi = int(row[col_map["mmsi"]])
+                t = _to_unix_seconds(row[col_map["time"]])
+                lon = float(row[col_map["lon"]])
+                lat = float(row[col_map["lat"]])
+                sog = float(row[col_map["sog"]])
+                cog = float(row[col_map["cog"]])
+            except (TypeError, ValueError) as exc:
+                raise ValueError(f"Invalid row {line_no} in {path}: {exc}") from exc
+            by_mmsi[mmsi].append((t, lon, lat, sog, cog))
+
+    tracks: list[Track] = []
+    for mmsi, rows in by_mmsi.items():
+        rows.sort(key=lambda r: r[0])
+        cols = np.asarray(rows, dtype=np.float64).T
+        tracks.append(
+            Track(
+                mmsi=mmsi,
+                t=cols[0],
+                lon=cols[1],
+                lat=cols[2],
+                sog=cols[3],
+                cog=cols[4],
+            )
+        )
+    tracks.sort(key=len, reverse=True)
+    return tracks
+
+
+def _to_int_or_none(value: str) -> int | None:
+    """Parse a CSV cell as int, tolerating empties, whitespace, and floats."""
+    s = (value or "").strip()
+    if not s:
+        return None
+    try:
+        return int(float(s))
+    except (TypeError, ValueError):
+        return None
+
+
+def _to_float_or_none(value: str) -> float | None:
+    s = (value or "").strip()
+    if not s:
+        return None
+    try:
+        return float(s)
+    except (TypeError, ValueError):
+        return None
+
+
+def read_csv_static_records(path: Path | str) -> dict[int, dict[str, Any]]:
+    """Extract per-MMSI static info from a CSV (e.g. Marine Cadastre).
+
+    The CSV must have ``mmsi`` and a recognised time column (see
+    :func:`read_csv_tracks` for aliases).  Optional static columns are
+    detected case-insensitively:
+
+    | Output key  | Recognised headers             |
+    |-------------|---------------------------------|
+    | vessel_name | ``VesselName``, ``name``        |
+    | call_sign   | ``CallSign``                    |
+    | imo         | ``IMO``, ``imo_num``            |
+    | ship_type   | ``VesselType``, ``ShipType``    |
+    | destination | ``Destination``                 |
+    | dim_bow / dim_stern | (split from ``Length`` / ``LOA``)  — half each |
+    | dim_port / dim_star | (split from ``Width`` / ``Beam``)  — half each |
+    | draught     | ``Draft``, ``Draught``          |
+
+    Marine Cadastre publishes overall ``Length``/``Width`` rather than the
+    per-quadrant antenna offsets that AIS Type-5 carries.  The split is
+    halved into ``dim_bow``/``dim_stern`` (and similarly for width) — a
+    centred-antenna approximation, which is what most AIS feeds report
+    when the antenna position is unknown.
+
+    Multiple rows per MMSI are merged with **last non-NULL value wins per
+    field**, and the latest ``time`` is recorded.  Returns ``{}`` if no
+    recognised static columns are present.
+
+    Output dict is shaped to match AISdb's static-row dict so the same
+    downstream code (e.g. OMRAT's ``_ensure_static``/``_ensure_state``)
+    can consume both data sources uniformly.
+
+    Raises
+    ------
+    ValueError
+        If the file is empty (no header).
+    KeyError
+        If ``mmsi`` or ``time`` columns are missing.
+    """
+    path = Path(path)
+    out: dict[int, dict[str, Any]] = {}
+
+    with _open_text_csv(path) as f:
+        reader = csv.DictReader(f)
+        if reader.fieldnames is None:
+            raise ValueError(f"Empty CSV (no header row): {path}")
+        kinematic_map = _resolve_csv_columns(list(reader.fieldnames))
+        # Build the static column map; absent columns are simply skipped.
+        lower_to_actual = {c.strip().lower(): c for c in reader.fieldnames}
+        static_map: dict[str, str] = {}
+        for canonical, aliases in _STATIC_COLUMN_ALIASES.items():
+            for alias in aliases:
+                if alias in lower_to_actual:
+                    static_map[canonical] = lower_to_actual[alias]
+                    break
+        if not static_map:
+            return {}
+
+        for row in reader:
+            try:
+                mmsi = int(row[kinematic_map["mmsi"]])
+            except (TypeError, ValueError, KeyError):
+                continue
+            try:
+                t = _to_unix_seconds(row[kinematic_map["time"]])
+            except (TypeError, ValueError, KeyError):
+                continue
+
+            entry = out.setdefault(mmsi, {"mmsi": mmsi, "time": t})
+            # Track latest timestamp per MMSI.
+            if t > entry.get("time", t):
+                entry["time"] = t
+
+            for canonical, src_col in static_map.items():
+                # csv.DictReader yields "" for missing/blank cells; the
+                # parsers below all return None for empty input so no
+                # explicit None-guard is needed here.
+                raw = row.get(src_col, "")
+                if canonical in ("imo", "ship_type"):
+                    val = _to_int_or_none(raw)
+                elif canonical in ("length", "width", "draught"):
+                    val = _to_float_or_none(raw)
+                else:
+                    s = str(raw).strip()
+                    val = s or None
+                if val is not None:
+                    entry[canonical] = val
+
+    # Convert overall Length / Width into AISdb's per-quadrant antenna
+    # offsets (halved — centred-antenna approximation).
+    for entry in out.values():
+        length = entry.pop("length", None)
+        width = entry.pop("width", None)
+        if length is not None:
+            half = length / 2.0
+            entry["dim_bow"] = half
+            entry["dim_stern"] = half
+        if width is not None:
+            half = width / 2.0
+            entry["dim_port"] = half
+            entry["dim_star"] = half
+
+    return out

aissegments/tdkc.py

@@ -0,0 +1,292 @@
+"""Top-Down Kinematic Compression (TDKC) on AIS tracks.
+
+Implements the algorithm of:
+
+    Guo, S., Bolbot, V., & Valdez Banda, O. (2024). An adaptive trajectory
+    compression and feature preservation method for maritime traffic analysis.
+    *Ocean Engineering*, 312, 119189.  https://doi.org/10.1016/j.oceaneng.2024.119189
+
+Pipeline
+--------
+1. Recursively build a *Compression Binary Tree* (CBT).  Each node records the
+   intermediate point with the maximum aggregated z-score of Synchronous
+   Euclidean Distance (SED) and Synchronous Velocity Difference (SVD), and
+   splits the sub-trajectory at that point.  Recursion exhausts down to
+   length-2 leaves; the threshold is *not* applied during construction.
+2. Compute adaptive thresholds ``sed_eps`` and ``svd_eps`` as the mean SED and
+   mean SVD across all CBT nodes (paper Eqs. 27-28), each clamped to a
+   user-configurable floor that defends against floating-point noise on clean
+   inputs.  Real AIS data is unaffected (mean SED ~10²-10³ m, well above the
+   1 m default floor).
+3. A node is a *key node* if either of its measurements exceeds its threshold,
+   *or* any of its children is a key node — this is the recursion-termination
+   fix from the paper.  Indices of key-node split points are retained.
+4. Output: original first/last point + every key-node split point.
+
+Recursion depth scales with tree depth (≈ ``log2(N)`` for balanced inputs).
+For pathological inputs that produce a degenerate tree, raise the system
+recursion limit before calling :func:`tdkc`.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from itertools import pairwise
+
+import numpy as np
+
+from aissegments._types import Segment, Track, to_segments
+
+# Earth radius in metres for haversine.  WGS84 mean radius.
+_EARTH_RADIUS_M = 6_371_008.8
+
+# Default threshold floors.  Below GPS accuracy (~10 m for Class A AIS) but
+# well above double-precision arithmetic noise on lat/lon arithmetic.
+_DEFAULT_MIN_SED_M = 1.0
+_DEFAULT_MIN_SVD_KN = 0.01
+
+
+# ---------------------------------------------------------------------------
+# Internal numerics
+# ---------------------------------------------------------------------------
+
+
+def _haversine_m(
+    lon1: np.ndarray, lat1: np.ndarray, lon2: np.ndarray, lat2: np.ndarray
+) -> np.ndarray:
+    """Great-circle distance in metres, vectorised over numpy arrays."""
+    lon1r = np.deg2rad(lon1)
+    lat1r = np.deg2rad(lat1)
+    lon2r = np.deg2rad(lon2)
+    lat2r = np.deg2rad(lat2)
+    dlon = lon2r - lon1r
+    dlat = lat2r - lat1r
+    a = np.sin(dlat / 2.0) ** 2 + np.cos(lat1r) * np.cos(lat2r) * np.sin(dlon / 2.0) ** 2
+    return 2.0 * _EARTH_RADIUS_M * np.arcsin(np.sqrt(np.clip(a, 0.0, 1.0)))
+
+
+def _zscore(x: np.ndarray) -> np.ndarray:
+    """Z-score normalise; return zeros if std is zero (constant input)."""
+    if x.size == 0:
+        return x
+    mean = x.mean()
+    std = x.std()
+    if std == 0.0:
+        return np.zeros_like(x)
+    return (x - mean) / std
+
+
+def _compute_sed_svd(
+    t: np.ndarray,
+    lon: np.ndarray,
+    lat: np.ndarray,
+    sog: np.ndarray,
+    cog: np.ndarray,
+    start: int,
+    end: int,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Compute SED and SVD for every intermediate point in ``[start, end]``.
+
+    Returns two arrays of shape ``(end - start - 1,)``.  Caller guarantees
+    ``end - start >= 2`` so there is at least one intermediate.  Zero-fills
+    if the start and end share a timestamp (synchronous interpolation
+    degenerates).
+    """
+    inter = np.arange(start + 1, end)
+    n_inter = inter.size
+    t_s, t_e = float(t[start]), float(t[end])
+    dt_total = t_e - t_s
+    if dt_total <= 0.0:
+        return np.zeros(n_inter), np.zeros(n_inter)
+    frac = (t[inter] - t_s) / dt_total
+
+    # SED: distance between the actual point and the synchronous-interpolated
+    # point on the start-end great circle (paper Eqs. 4-7, generalised to the
+    # sphere via haversine — see paper Sec. 3.2.1 par. on Cartesian distortion).
+    lon_sync = lon[start] + frac * (lon[end] - lon[start])
+    lat_sync = lat[start] + frac * (lat[end] - lat[start])
+    sed = _haversine_m(lon_sync, lat_sync, lon[inter], lat[inter])
+
+    # SVD: magnitude of the velocity-vector difference between the actual
+    # point and the synchronous-interpolated velocity (paper Eqs. 11-19).
+    delta_s = float(sog[end]) - float(sog[start])
+    delta_c = ((float(cog[end]) - float(cog[start]) + 180.0) % 360.0) - 180.0
+    s_sync = sog[start] + frac * delta_s
+    c_sync = cog[start] + frac * delta_c
+    vx_sync = s_sync * np.sin(np.deg2rad(c_sync))
+    vy_sync = s_sync * np.cos(np.deg2rad(c_sync))
+    vx_pt = sog[inter] * np.sin(np.deg2rad(cog[inter]))
+    vy_pt = sog[inter] * np.cos(np.deg2rad(cog[inter]))
+    svd = np.hypot(vx_sync - vx_pt, vy_sync - vy_pt)
+    return sed, svd
+
+
+# ---------------------------------------------------------------------------
+# Compression Binary Tree
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class _Node:
+    idx: int
+    sed: float
+    svd: float
+    left: _Node | None = None
+    right: _Node | None = None
+
+
+def _build_cbt(
+    t: np.ndarray,
+    lon: np.ndarray,
+    lat: np.ndarray,
+    sog: np.ndarray,
+    cog: np.ndarray,
+    start: int,
+    end: int,
+) -> _Node | None:
+    """Recursive CBT construction (paper Algorithm 3).  No threshold applied."""
+    if end - start < 2:
+        return None
+    sed_arr, svd_arr = _compute_sed_svd(t, lon, lat, sog, cog, start, end)
+    aggregated = _zscore(sed_arr) + _zscore(svd_arr)
+    rel_max = int(np.argmax(aggregated))
+    split_idx = start + 1 + rel_max
+    return _Node(
+        idx=split_idx,
+        sed=float(sed_arr[rel_max]),
+        svd=float(svd_arr[rel_max]),
+        left=_build_cbt(t, lon, lat, sog, cog, start, split_idx),
+        right=_build_cbt(t, lon, lat, sog, cog, split_idx, end),
+    )
+
+
+def _collect_thresholds(
+    node: _Node | None, sed_acc: list[float], svd_acc: list[float]
+) -> None:
+    if node is None:
+        return
+    sed_acc.append(node.sed)
+    svd_acc.append(node.svd)
+    _collect_thresholds(node.left, sed_acc, svd_acc)
+    _collect_thresholds(node.right, sed_acc, svd_acc)
+
+
+def _identify_keys(
+    node: _Node | None,
+    sed_eps: float,
+    svd_eps: float,
+    out: set[int],
+) -> bool:
+    """Return True if ``node`` (or any descendant) is a key node.  Mutates ``out``."""
+    if node is None:
+        return False
+    self_key = (node.sed > sed_eps) or (node.svd > svd_eps)
+    left_key = _identify_keys(node.left, sed_eps, svd_eps, out)
+    right_key = _identify_keys(node.right, sed_eps, svd_eps, out)
+    if self_key or left_key or right_key:
+        out.add(node.idx)
+        return True
+    return False
+
+
+def _adaptive_thresholds(
+    cbt: _Node, min_sed_m: float, min_svd_kn: float
+) -> tuple[float, float]:
+    """Mean SED / SVD across the tree, clamped to the configured floors."""
+    sed_acc: list[float] = []
+    svd_acc: list[float] = []
+    _collect_thresholds(cbt, sed_acc, svd_acc)
+    sed_eps = max(float(np.mean(sed_acc)), float(min_sed_m))
+    svd_eps = max(float(np.mean(svd_acc)), float(min_svd_kn))
+    return sed_eps, svd_eps
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def tdkc(
+    track: Track,
+    *,
+    min_sed_m: float = _DEFAULT_MIN_SED_M,
+    min_svd_kn: float = _DEFAULT_MIN_SVD_KN,
+) -> Track:
+    """Compress ``track`` using TDKC; return a new Track of only the key points.
+
+    Endpoints are always retained.  Tracks of length ``<= 2`` pass through
+    unchanged.
+
+    Parameters
+    ----------
+    track : Track
+        Input AIS track for a single vessel.
+    min_sed_m : float, optional
+        Lower bound for the adaptive SED threshold, in metres.  Defaults to
+        ``1.0`` (below typical GPS accuracy, above floating-point noise).
+        Set to ``0`` for paper-faithful behaviour at the cost of FP-driven
+        artefacts on perfectly clean inputs.
+    min_svd_kn : float, optional
+        Lower bound for the adaptive SVD threshold, in knots.  Defaults to
+        ``0.01``.  Set to ``0`` for paper-faithful behaviour.
+
+    Returns
+    -------
+    Track
+        New track containing the original endpoints plus every key-node split
+        point identified by TDKC.  Always sorted by ``t``.
+    """
+    n = len(track)
+    if n <= 2:
+        return track
+    cbt = _build_cbt(track.t, track.lon, track.lat, track.sog, track.cog, 0, n - 1)
+    assert cbt is not None  # n >= 3 guarantees a non-empty intermediate set
+    sed_eps, svd_eps = _adaptive_thresholds(cbt, min_sed_m, min_svd_kn)
+    keys: set[int] = {0, n - 1}
+    _identify_keys(cbt, sed_eps, svd_eps, keys)
+    return track.take(sorted(keys))
+
+
+def tdkc_segments(
+    track: Track,
+    *,
+    min_sed_m: float = _DEFAULT_MIN_SED_M,
+    min_svd_kn: float = _DEFAULT_MIN_SVD_KN,
+) -> list[Segment]:
+    """Compress with TDKC and emit one ``Segment`` per consecutive key-pair.
+
+    Each segment's ``n_points`` is the count of *original* points spanned,
+    including both endpoints — useful when the segments are written into a
+    PostGIS table that wants to preserve the underlying observation density.
+
+    See :func:`tdkc` for ``min_sed_m`` / ``min_svd_kn``.
+    """
+    n = len(track)
+    if n < 2:
+        return []
+    if n == 2:
+        return to_segments(track)
+    cbt = _build_cbt(track.t, track.lon, track.lat, track.sog, track.cog, 0, n - 1)
+    assert cbt is not None
+    sed_eps, svd_eps = _adaptive_thresholds(cbt, min_sed_m, min_svd_kn)
+    keys: set[int] = {0, n - 1}
+    _identify_keys(cbt, sed_eps, svd_eps, keys)
+    sorted_idx = sorted(keys)
+    compressed = track.take(sorted_idx)
+    base_segments = to_segments(compressed)
+    enriched: list[Segment] = []
+    for seg, (i_start, i_end) in zip(base_segments, pairwise(sorted_idx), strict=True):
+        enriched.append(
+            Segment(
+                mmsi=seg.mmsi,
+                t_start=seg.t_start,
+                t_end=seg.t_end,
+                lon_start=seg.lon_start,
+                lat_start=seg.lat_start,
+                lon_end=seg.lon_end,
+                lat_end=seg.lat_end,
+                cog_mean=seg.cog_mean,
+                sog_mean=seg.sog_mean,
+                n_points=int(i_end - i_start + 1),
+            )
+        )
+    return enriched

aissegments-0.2.0.dist-info/METADATA

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: aissegments
+Version: 0.2.0
+Summary: AIS trajectory segmentation and feature-preserving compression for maritime traffic analysis.
+Project-URL: Homepage, https://github.com/axelHorteborn/AISsegments
+Project-URL: Repository, https://github.com/axelHorteborn/AISsegments
+Project-URL: Issues, https://github.com/axelHorteborn/AISsegments/issues
+Author-email: Axel Hörteborn <axel.horteborn@ri.se>
+License: MIT
+License-File: LICENSE
+Keywords: AIS,Douglas-Peucker,TDKC,compression,maritime,segmentation,trajectory
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Provides-Extra: aisdb
+Requires-Dist: aisdb>=1.0; extra == 'aisdb'
+Provides-Extra: dev
+Requires-Dist: aisdb>=1.7; extra == 'dev'
+Requires-Dist: matplotlib>=3.7; extra == 'dev'
+Requires-Dist: pytest-cov>=4; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.7; extra == 'viz'
+Description-Content-Type: text/markdown
+
+# AISsegments
+
+**A Python toolkit for compressing AIS vessel trajectories into compact, query-friendly linestring segments — without losing the kinematic features that maritime safety and risk analysis depend on.**
+
+## What is this?
+
+`aissegments` takes raw AIS position reports (millions of pings per day in a busy sea area) and outputs a small number of **constant-COG/SOG linestring segments per vessel**, one row per (vessel, time-window, course/speed). The output is shaped to drop straight into a PostGIS `LINESTRING` table.
+
+It is the reference Python implementation of the **Top-Down Kinematic Compression (TDKC)** algorithm of Guo, Bolbot & Valdez Banda (Ocean Engineering 312 (2024), 119189), with the recursion-termination and adaptive-threshold fixes described in the paper.
+
+## Goals
+
+1. **Shrink AIS data without losing the maritime-relevant features.** A continent-scale AIS feed easily produces hundreds of millions of position reports per month. Most of those points are uninformative — a vessel cruising in a straight line at a steady speed needs only its endpoints. TDKC keeps the points where vessels actually do something interesting (turn, accelerate, stop, manoeuvre) and drops the rest.
+2. **Treat AIS as a sequence of *kinematic states*, not just positions.** The classical Douglas-Peucker simplification looks only at how far points stray from a straight line. That throws away course and speed changes that lie on a straight track, which are exactly the events maritime risk analysis cares about. TDKC uses both position (Synchronous Euclidean Distance) **and** velocity (Synchronous Velocity Difference) with adaptive per-track thresholds.
+3. **Produce database-ready output.** The output isn't a smaller list of points — it's a list of `Segment` records with start/end coordinates, mean COG/SOG, and the count of original observations spanned. Each segment is a 2-point `LINESTRING` ready for `ST_Intersects` and other PostGIS operations.
+4. **Stay framework-neutral.** The core depends only on NumPy. AISdb is an optional adapter (`pip install "aissegments[aisdb]"`); other input paths (CSV from Marine Cadastre / institutional exports / your own pipeline) work via [`read_csv_tracks`](src/aissegments/adapters.py) without any extra dependencies.
+
+## Who is this for?
+
+- **Maritime risk analysts** who need to run collision/grounding/allision queries against millions of vessel positions per area-year and want the spatial+temporal index to fit in memory.
+- **AIS data engineers** maintaining a Postgres/PostGIS warehouse of vessel tracks and looking for a principled way to densify ingestion without overwhelming storage.
+- **Researchers** reproducing or extending Guo et al.'s adaptive trajectory compression work.
+
+## What it produces
+
+- `tdkc(track)` — same `Track` interface but with only the *key points* retained (typically 1-5% of the input, depending on track shape and threshold tuning).
+- `tdkc_segments(track)` — a list of `Segment` records, one per consecutive key-point pair, ready for direct insertion as PostGIS `LINESTRING(start_lon start_lat, end_lon end_lat)` geometries with `cog_mean`, `sog_mean`, and `n_points` (count of original AIS pings each segment represents).
+
+## Why not just use Douglas-Peucker?
+
+DP and its variants throw away every point that lies on a straight line, regardless of whether the vessel's *behaviour* is changing. A vessel slowing from 15 to 5 knots while continuing to head east — DP keeps two points (start, end) and you lose the entire speed change. TDKC keeps the deceleration point because its **velocity vector** has shifted. See [`docs/algorithm.md`](docs/algorithm.md) for the precise math, and [`examples/output/03_min_svd_sweep.png`](examples/output/) for a visual side-by-side.
+
+## Companion package
+
+[OMRAT](https://github.com/axelande/OMRAT) (Open Maritime Risk Analysis Tool) — a QGIS plugin for collision/grounding/allision risk modelling — uses AISsegments as its segment-ingestion backend. The OMRAT pipeline shows a complete end-to-end flow: NMEA / CSV → aisdb decode → TDKC compression → bulk-load into a year-partitioned PostGIS schema.
+
+## Install
+
+```bash
+pip install aissegments
+
+# with the optional AISdb adapter for ingestion from raw NMEA / CSV
+pip install "aissegments[aisdb]"
+```
+
+For development with full test + coverage tooling:
+
+```bash
+git clone https://github.com/axelHorteborn/AISsegments
+cd AISsegments
+pip install -e ".[dev,aisdb]"
+pytest --cov
+```
+
+## Quickstart
+
+```python
+import numpy as np
+from aissegments import Track, tdkc, tdkc_segments
+
+# Build a Track from your own arrays (lat/lon in degrees, sog in knots, cog in degrees).
+track = Track.from_arrays(
+    mmsi=219000123,
+    t=np.array([0, 60, 120, 180, 240], dtype=float),     # unix seconds
+    lon=np.array([12.0, 12.001, 12.002, 12.003, 12.004]),
+    lat=np.array([55.0, 55.0, 55.0, 55.0, 55.0]),
+    sog=np.array([10.0, 10.0, 10.0, 10.0, 10.0]),
+    cog=np.array([90.0, 90.0, 90.0, 90.0, 90.0]),
+)
+
+# Compress: returns a Track containing only the key points.
+compressed = tdkc(track)
+print(len(compressed), "key points kept out of", len(track))
+
+# Or go straight to segment records (one per consecutive key-point pair).
+segments = tdkc_segments(track)
+for s in segments:
+    print(s.t_start, s.t_end, s.cog_mean, s.sog_mean, s.n_points)
+```
+
+## Using AISdb as an input adapter
+
+`aissegments` can consume the per-vessel track dicts produced by [AISdb](https://github.com/AISViz/AISdb)'s `TrackGen()`:
+
+```python
+import aisdb
+from aissegments.adapters import from_aisdb_track
+from aissegments import tdkc_segments
+
+with aisdb.SQLiteDBConn(dbpath="ais.db") as conn:
+    qry = aisdb.DBQuery(start=..., end=..., callback=aisdb.sql_query_strs.in_bbox_time)
+    tracks = aisdb.TrackGen(qry.gen_qry(), decimate=False)
+    for t_dict in tracks:
+        track = from_aisdb_track(t_dict)
+        for seg in tdkc_segments(track):
+            ...  # write seg to your PostGIS table
+```
+
+## What's in the package
+
+| Module | Purpose |
+| --- | --- |
+| [`aissegments.tdkc`](src/aissegments/tdkc.py) | TDKC algorithm: SED + SVD, Compression Binary Tree, adaptive thresholds, key-node identification |
+| [`aissegments._types`](src/aissegments/_types.py) | `Track` and `Segment` dataclasses, `to_segments` helper |
+| [`aissegments.adapters`](src/aissegments/adapters.py) | Input adapters: `from_aisdb_track`, `read_csv_tracks` (Marine Cadastre etc.), `read_csv_static_records` for vessel-info extraction |
+
+## Algorithm details
+
+See [docs/algorithm.md](docs/algorithm.md) for the mathematical formulation, with equation references back to the source paper.
+
+## Citation
+
+If you use this package in academic work, please cite both the software and the underlying paper:
+
+> Guo, S., Bolbot, V., & Valdez Banda, O. (2024). An adaptive trajectory compression and feature preservation method for maritime traffic analysis. *Ocean Engineering*, 312, 119189. https://doi.org/10.1016/j.oceaneng.2024.119189
+
+A `CITATION.cff` is included so GitHub renders a "Cite this repository" widget.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

aissegments-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+aissegments/__init__.py,sha256=sYtJDLpXS9VAI5tuKrRlSW_XzP5ifEDlS3Gx6Y_b-xo,1071
+aissegments/_types.py,sha256=r5ecX240XuFb2qYrNzTZYHLT8Ko2sUO_DaiFBZkoYbc,4939
+aissegments/adapters.py,sha256=yzXrFPkoIg2vrEJJ-MAqta3dg720ZWsbBjebSm0n14A,13283
+aissegments/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aissegments/tdkc.py,sha256=v-CHnT6EB7rmSQsa8s4o7wl1yd1RNURhJm48f48EYiM,10403
+aissegments-0.2.0.dist-info/METADATA,sha256=itKGv9NV0149CmWEEnwE1f3BahFum5heq_5mvRSZ5ko,8594
+aissegments-0.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+aissegments-0.2.0.dist-info/licenses/LICENSE,sha256=IgsaQEbxB00lWlxntjhHIPweHYTzJAYd5tIsvOMrZmg,1072
+aissegments-0.2.0.dist-info/RECORD,,

aissegments-0.2.0.dist-info/WHEEL

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

aissegments-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Axel Hörteborn
+
+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.