Skip to main content

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]"); CSV files from Marine Cadastre, the Danish Maritime Authority, institutional exports or your own pipeline work via read_csv_tracks without any extra dependencies, and Parquet via read_parquet_tracks with pip 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) — 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 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)

Source distribution for aissegments 0.3.0
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)

Table of built distributions (wheels) for aissegments 0.3.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page