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
- 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.
- 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.
- Produce database-ready output. The output isn't a smaller list of points — it's a list of
Segmentrecords with start/end coordinates, mean COG/SOG, and the count of original observations spanned. Each segment is a 2-pointLINESTRINGready forST_Intersectsand other PostGIS operations. - Stay framework-neutral. The core depends only on NumPy. AISdb is an optional adapter (
pip install "aissegments[aisdb]"); CSV files from Marine Cadastre, the Danish Maritime Authority, institutional exports or your own pipeline work viaread_csv_trackswithout any extra dependencies, and Parquet viaread_parquet_trackswithpip install "aissegments[parquet]".
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)— sameTrackinterface 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 ofSegmentrecords, one per consecutive key-point pair, ready for direct insertion as PostGISLINESTRING(start_lon start_lat, end_lon end_lat)geometries withcog_mean,sog_mean, andn_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 for the precise math, and examples/output/03_min_svd_sweep.png for a visual side-by-side.
Companion package
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
pip install aissegments
# with the optional AISdb adapter for ingestion from raw NMEA / CSV
pip install "aissegments[aisdb]"
# with the optional streaming Parquet reader (pyarrow)
pip install "aissegments[parquet]"
For development with full test + coverage tooling:
git clone https://github.com/axelHorteborn/AISsegments
cd AISsegments
pip install -e ".[dev,aisdb]"
pytest --cov
aisdb on Python 3.13+ (Windows)
aisdb publishes Windows wheels only up to CPython 3.12. On a newer interpreter pip
falls back to aisdb's source tarball, which fails immediately because it lists
patchelf (a Linux-only tool) as an unconditional build requirement. The Rust
extension itself compiles fine, so this repo ships a helper that downloads the
sdist, patches its pyproject.toml, builds a wheel for your interpreter and
installs it:
python tools/build_aisdb.py # then: pip install -e ".[dev,aisdb]"
maturin fetches a temporary Rust toolchain by itself. The only local prerequisite is the MSVC linker, i.e. Visual Studio Build Tools with the "Desktop development with C++" workload. The build takes a few minutes the first time. If PyPI already has a wheel for your interpreter the script just installs that.
Quickstart
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's TrackGen():
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
Reading CSV and Parquet files
The file readers recognise several provider layouts out of the box and expose the remaining knobs as keyword arguments, so a source that is not built in still works:
| Layout | Time column | Transceiver class | Ship type | Dimensions |
|---|---|---|---|---|
| Marine Cadastre | BaseDateTime ISO 8601 |
TransceiverClass = A / B |
VesselType numeric code |
Length / Width (halved into offsets) |
DMA aisdk |
# Timestamp dd/mm/yyyy HH:MM:SS |
Type of mobile = Class A / Class B |
Ship type decoded name |
A / B / C / D offsets |
| Generic | time as unix seconds or ISO 8601 |
optional | numeric code | dim_a.. or to_bow.. |
from aissegments import read_parquet_tracks, read_parquet_static_records, DEFAULT_SHIP_TYPE_NAMES
# DMA and Marine Cadastre need no arguments.
for track in read_parquet_tracks("aisdk-2025-01.parquet"):
...
# Other providers: override what differs.
tracks = read_csv_tracks(
"feed.csv",
time_format="%Y.%m.%d %H-%M-%S", # any strptime pattern
dayfirst=False, # for ambiguous mm/dd/yyyy strings
mobile_types=("A", "B", "Vessel"), # or None to keep every row
skip_invalid=True, # drop rows with blank SOG/COG instead of raising
)
static = read_csv_static_records(
"feed.csv",
ship_type_names={**DEFAULT_SHIP_TYPE_NAMES, "cargo ship": 70},
)
Both readers apply the same rules: the transceiver-class filter defaults to Class A and B
(matched case-insensitively, with or without the word "Class") and warns if it drops every
row, bare A/B/C/D columns are only treated as antenna offsets when all four are present,
and non-informative cells such as Undefined or Unknown are skipped.
What's in the package
| Module | Purpose |
|---|---|
aissegments.tdkc |
TDKC algorithm: SED + SVD, Compression Binary Tree, adaptive thresholds, key-node identification |
aissegments._types |
Track and Segment dataclasses, to_segments helper |
aissegments.adapters |
Input adapters: from_aisdb_track, read_csv_tracks, read_csv_static_records for vessel-info extraction |
aissegments.parquet |
Streaming Parquet readers read_parquet_tracks / read_parquet_static_records (optional pyarrow) |
aissegments._schema |
Provider-layout knowledge shared by both readers: column aliases, transceiver classes, ship-type names, timestamp formats |
Algorithm details
See 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.
Metadata
Release files for aissegments 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| aissegments-0.3.0.tar.gz | 41.9 kB | With provenance | Details for aissegments-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aissegments-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for aissegments-0.3.0-py3-none-any.whl |
Total release size: 70.5 kB
Release files / aissegments-0.3.0.tar.gz
| Download URL | aissegments-0.3.0.tar.gz |
|---|---|
| Size | 41.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
eead32639f85db5a9958a715a073b36fbb98e3eefe2b875ccce1e08385b8f758
|
|
BLAKE2b-256 checksum How to use checksums |
dd6cf3ecc93575c9f10d0f523803723aa22111204651b2a2792a8b46a2f4f83d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 13, 2026.
Transparency logRelease files / aissegments-0.3.0-py3-none-any.whl
| Download URL | aissegments-0.3.0-py3-none-any.whl |
|---|---|
| Size | 28.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b180589785a059d1f28b8a786dfb90b3fa6142e603bb69e23cc94703d62bcf26
|
|
BLAKE2b-256 checksum How to use checksums |
4ee4333901a39a154b443a7d3c51d4077bbc3c49dd0932eba5f2bd73c2fd0571
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 13, 2026.
Transparency logSecurity for aissegments 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for aissegments-0.3.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 13, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.