aissegments 0.2.0__tar.gz

aissegments-0.2.0/.gitignore

@@ -0,0 +1,41 @@
+# Python build artefacts
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+build/
+dist/
+.eggs/
+*.so
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.tox/
+.nox/
+.qgis-settings/
+
+# Editors / IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Virtualenvs
+.venv/
+venv/
+env/
+
+# Hatch
+.hatch/
+
+# Ruff cache
+.ruff_cache/
+
+# mypy
+.mypy_cache/

aissegments-0.2.0/CITATION.cff

@@ -0,0 +1,32 @@
+cff-version: 1.2.0
+title: "AISsegments: AIS trajectory segmentation and feature-preserving compression"
+message: "If you use AISsegments in academic work, please cite both this software and the underlying TDKC algorithm paper."
+type: software
+authors:
+  - family-names: Hörteborn
+    given-names: Axel
+    email: axel.horteborn@ri.se
+    affiliation: "RISE Research Institutes of Sweden"
+license: MIT
+repository-code: "https://github.com/axelHorteborn/AISsegments"
+keywords:
+  - AIS
+  - maritime
+  - trajectory
+  - compression
+  - TDKC
+
+references:
+  - type: article
+    title: "An adaptive trajectory compression and feature preservation method for maritime traffic analysis"
+    authors:
+      - family-names: Guo
+        given-names: Shaoqing
+      - family-names: Bolbot
+        given-names: Victor
+      - family-names: Valdez Banda
+        given-names: Osiris
+    journal: "Ocean Engineering"
+    volume: 312
+    year: 2024
+    doi: "10.1016/j.oceaneng.2024.119189"

aissegments-0.2.0/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.

aissegments-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,121 @@
+# 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/pyproject.toml

@@ -0,0 +1,102 @@
+[build-system]
+requires = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aissegments"
+version = "0.2.0"
+description = "AIS trajectory segmentation and feature-preserving compression for maritime traffic analysis."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Axel Hörteborn", email = "axel.horteborn@ri.se" },
+]
+requires-python = ">=3.10"
+dependencies = [
+    "numpy>=1.24",
+]
+keywords = ["AIS", "maritime", "trajectory", "compression", "TDKC", "Douglas-Peucker", "segmentation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: GIS",
+]
+
+[project.optional-dependencies]
+aisdb = ["aisdb>=1.0"]
+viz = ["matplotlib>=3.7"]
+dev = [
+    "pytest>=7",
+    "pytest-cov>=4",
+    "ruff>=0.5",
+    "matplotlib>=3.7",
+    "aisdb>=1.7",
+]
+
+[project.urls]
+Homepage = "https://github.com/axelHorteborn/AISsegments"
+Repository = "https://github.com/axelHorteborn/AISsegments"
+Issues = "https://github.com/axelHorteborn/AISsegments/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aissegments"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/aissegments",
+    "tests",
+    "README.md",
+    "LICENSE",
+    "CITATION.cff",
+    "pyproject.toml",
+]
+# Local AIS data files dropped under tests/data/ are kept out of the
+# distribution — they can be large (tens of MB) and may have third-party
+# attribution requirements that are easier to manage out-of-band.  The
+# directory's README.md is small and documents the format, so it stays in.
+exclude = [
+    "tests/data/*.csv",
+    "tests/data/*.csv.gz",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = [
+    "--strict-markers",
+    "--strict-config",
+    "-ra",
+]
+markers = [
+    "aisdb: integration tests that require the optional aisdb package and its bundled test data",
+    "local_csv: integration tests that need a CSV file dropped under tests/data/",
+]
+
+[tool.coverage.run]
+source = ["aissegments"]
+branch = true
+
+[tool.coverage.report]
+fail_under = 100
+exclude_also = [
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+    "@overload",
+    "pragma: no cover",
+]
+show_missing = true
+skip_covered = false
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "B", "SIM", "RUF"]
+ignore = ["E501"]  # line-length handled by formatter

aissegments-0.2.0/src/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-0.2.0/src/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