pyModeS 3.4.0__tar.gz → 3.5.1__tar.gz

{pymodes-3.4.0 → pymodes-3.5.1}/CHANGELOG.md

@@ -5,6 +5,81 @@ All notable changes to pyModeS are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [3.5.1] — 2026-07-16
+
+### Added
+
+- `decode()`, `Message.decode()`, and `PipeDecoder` now accept
+  `include_meteo=True` to opt into heuristic Comm-B BDS 4,4 routine
+  meteorological reports and BDS 4,5 meteorological hazard reports. The
+  default remains `False` because these payload patterns can overlap other
+  Comm-B registers.
+- The `modes decode`, `modes live`, and `scripts/stream_filtered.py` interfaces
+  expose the same behavior through `--include-meteo`.
+
+## [3.5.0] — 2026-07-15
+
+### Added
+
+- `PipeDecoder` now uses the last validated airborne position as a local CPR
+  reference for subsequent BDS 0,5 frames. This makes a position available on
+  the current streaming `decode()` call when no fresh global even/odd pair is
+  available, instead of relying on retroactive mutation of an earlier result.
+- `local_ref_window` configures the maximum reference age (30 seconds by
+  default); set it to zero to disable local airborne decoding.
+  `PipeDecoder.stats["local_positions"]` reports positions produced by this
+  path.
+- Position bootstrap now locks as soon as three candidates are pairwise
+  motion-consistent instead of always waiting for all five candidate slots.
+  The five-candidate limit still allows two unrelated outliers to be ignored.
+- The mixed-traffic benchmark now reports immediate streaming position yield
+  and frame-by-frame coordinate agreement for v2.21.1, released v3.4.0, and
+  v3.5.0 in addition to throughput.
+
+### Changed
+
+- `crc_valid` is now `None` when an address-parity message cannot be checked
+  independently. It remains `True` or `False` for frames whose parity can be
+  validated without assuming the address derived from that same parity.
+- `PipeDecoder` uses each message's source timestamp for state validity while
+  retaining a monotonic high-water mark for eviction. Reordered capture data
+  therefore cannot revive expired observations or prematurely evict newer
+  state.
+- Plausibility and position validation are isolated in a dedicated internal
+  module, keeping the streaming pipeline and its decision comments easier to
+  follow without changing the public API.
+- Release publishing now runs only after the full test matrix succeeds, checks
+  that the Git tag matches the package version, and smoke-tests the exact wheel
+  artifact that will be uploaded.
+
+### Fixed
+
+- Surface references remain optional and are used only for BDS 0,6 surface
+  positions. Positions derived from `surface_ref` can never seed local
+  airborne CPR decoding.
+- Rejected global position candidates cannot become local CPR references; a
+  separate last-accepted airborne reference is maintained and TTL-evicted.
+- Bootstrap promotion, including `flush()`, initializes the latest accepted
+  airborne reference while keeping surface-derived positions separate.
+- Globally decoded surface CPR positions now select the correct longitude zone
+  across the antimeridian and other CPR zone boundaries.
+- Beast stream input resynchronizes after malformed or truncated frames instead
+  of losing subsequent valid messages.
+- Beast receiver timestamps are back-projected from the current wall clock with
+  rollover-safe receiver-tick deltas, avoiding dates near the Unix epoch and
+  preserving correct timing across the 12 MHz counter rollover.
+- BDS inference compares headings using circular angular distance, so values
+  around 0/360 degrees are scored correctly.
+- Trusted ICAO observations expire according to the configured state TTL and
+  cannot be refreshed by older, reordered messages.
+- Integer messages outside the valid 56-bit and 112-bit Mode S frame ranges are
+  rejected instead of being silently truncated or misclassified.
+- Network endpoint and surface-reference CLI arguments are validated before a
+  stream starts, and network sources are closed deterministically on normal
+  exit, errors, and interruption.
+- The live terminal UI synchronizes access to shared aircraft state, preventing
+  concurrent decoder and renderer updates from racing.
+
 ## [3.4.0] — 2026-07-13
 
 ### Fixed
@@ -38,8 +113,8 @@ Comm-B reply to the wrong aircraft.
 ### Added
 
 - `PipeDecoder` bootstrap cluster analysis for the first position per
-  ICAO: lat/lon emission is held until `_BOOTSTRAP_K` (=5) candidate
-  positions agree under a motion-consistency check. Prevents an
+  ICAO: lat/lon emission is held until five candidate positions agree
+  under a motion-consistency check. Prevents an
   initial phantom frame from anchoring the rolling position history.
   On each decode the held result dicts are retro-filled once the
   cluster locks. Scattered buffers reset and accumulate a fresh K.

{pymodes-3.4.0 → pymodes-3.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyModeS
-Version: 3.4.0
+Version: 3.5.1
 Summary: Python Mode-S and ADS-B Decoder
 Project-URL: homepage, https://mode-s.org
 Project-URL: repository, https://github.com/junzis/pyModeS
@@ -109,7 +109,7 @@ print(r["latitude"], r["longitude"])  # 43.6264..., 1.3747...
 `PipeDecoder` is stateful — it holds per-ICAO state across calls,
 matches CPR pairs automatically, evicts stale aircraft after a
 TTL, and flags DF20/21 messages as `icao_verified` when their
-CRC-derived ICAO was already seen in a clean DF17/18 plaintext.
+CRC-derived ICAO was seen recently in clean DF17/18 plaintext.
 
 ```python
 from pyModeS import PipeDecoder
@@ -117,7 +117,7 @@ from pyModeS import PipeDecoder
 pipe = PipeDecoder(surface_ref="EHAM")
 for msg, timestamp in stream:
     decoded = pipe.decode(msg, timestamp=timestamp)
-    if "latitude" in decoded:
+    if decoded.get("latitude") is not None:
         print(decoded["icao"], decoded["latitude"], decoded["longitude"])
 ```
 
@@ -194,36 +194,16 @@ the full command reference.
 - Unified `decode()` returns every decodable field in one dict
 - Batch mode preserves list length (errors become error-dicts, not
   exceptions)
-- `PipeDecoder` for streams: per-ICAO state, CPR pair accumulation,
-  TTL eviction, DF20/21 ICAO verification via trusted-set promotion
+- `PipeDecoder` for streams: per-ICAO state, global and local CPR position
+  decoding, TTL eviction, DF20/21 ICAO verification via trusted-set promotion
 - `full_dict=True` populates every key in the canonical 123-field
   schema for pandas / parquet workflows
 - `known=` aircraft state disambiguates Comm-B BDS 5,0/6,0 ambiguity
+- `include_meteo=True` opts into heuristic Comm-B BDS 4,4/4,5 inference
 - Airport ICAO database for surface CPR resolution (`surface_ref="EHAM"`)
 - Type-checked under mypy strict across all source files
 - Golden-file oracle regression test against `pyModeS 2.21.1`
 
-## Performance
-
-The committed benchmarks run each released/working-tree version in an
-isolated environment and reject output mismatches before reporting timings.
-On the captured 176,612-frame mixed Beast feed, the header-prefiltered v3 path
-processes 85,963 incoming messages/s:
-
-| Decoder path | Throughput |
-|---|---:|
-| pyModeS 2.21.1 selective helpers | 52,998 msg/s |
-| released v3.3.0 `PipeDecoder` | 3,897 msg/s |
-| v3.4.0 `PipeDecoder` | 49,243 msg/s |
-| v3.4.0 + header prefilter | **85,963 msg/s** |
-
-On the 2,000-aircraft synthetic PipeDecoder workload, v3.4.0 processes
-38,838 msg/s versus v2's 39,604 msg/s, with identical normalized output.
-
-See [`scripts/README.md`](./scripts/README.md) for the reproducible commands
-and [`scripts/benchmark_results/`](./scripts/benchmark_results/) for the full
-methodology, timings, and output digests.
-
 ## Supported messages
 
 - **DF4 / DF20:** altitude code (surveillance altitude reply)
@@ -249,6 +229,10 @@ methodology, timings, and output digests.
   - BDS 5,0: track and turn report
   - BDS 6,0: heading and speed report
 
+BDS 4,4 and 4,5 are heuristic and disabled by default. Enable them with
+`decode(..., include_meteo=True)` or `PipeDecoder(include_meteo=True)` when
+these meteorological registers are expected on the input feed.
+
 ## Migrating from pyModeS 2.x
 
 pyModeS 3 is **not backwards-compatible** with pyModeS 2.x. The

{pymodes-3.4.0 → pymodes-3.5.1}/README.md

@@ -82,7 +82,7 @@ print(r["latitude"], r["longitude"])  # 43.6264..., 1.3747...
 `PipeDecoder` is stateful — it holds per-ICAO state across calls,
 matches CPR pairs automatically, evicts stale aircraft after a
 TTL, and flags DF20/21 messages as `icao_verified` when their
-CRC-derived ICAO was already seen in a clean DF17/18 plaintext.
+CRC-derived ICAO was seen recently in clean DF17/18 plaintext.
 
 ```python
 from pyModeS import PipeDecoder
@@ -90,7 +90,7 @@ from pyModeS import PipeDecoder
 pipe = PipeDecoder(surface_ref="EHAM")
 for msg, timestamp in stream:
     decoded = pipe.decode(msg, timestamp=timestamp)
-    if "latitude" in decoded:
+    if decoded.get("latitude") is not None:
         print(decoded["icao"], decoded["latitude"], decoded["longitude"])
 ```
 
@@ -167,36 +167,16 @@ the full command reference.
 - Unified `decode()` returns every decodable field in one dict
 - Batch mode preserves list length (errors become error-dicts, not
   exceptions)
-- `PipeDecoder` for streams: per-ICAO state, CPR pair accumulation,
-  TTL eviction, DF20/21 ICAO verification via trusted-set promotion
+- `PipeDecoder` for streams: per-ICAO state, global and local CPR position
+  decoding, TTL eviction, DF20/21 ICAO verification via trusted-set promotion
 - `full_dict=True` populates every key in the canonical 123-field
   schema for pandas / parquet workflows
 - `known=` aircraft state disambiguates Comm-B BDS 5,0/6,0 ambiguity
+- `include_meteo=True` opts into heuristic Comm-B BDS 4,4/4,5 inference
 - Airport ICAO database for surface CPR resolution (`surface_ref="EHAM"`)
 - Type-checked under mypy strict across all source files
 - Golden-file oracle regression test against `pyModeS 2.21.1`
 
-## Performance
-
-The committed benchmarks run each released/working-tree version in an
-isolated environment and reject output mismatches before reporting timings.
-On the captured 176,612-frame mixed Beast feed, the header-prefiltered v3 path
-processes 85,963 incoming messages/s:
-
-| Decoder path | Throughput |
-|---|---:|
-| pyModeS 2.21.1 selective helpers | 52,998 msg/s |
-| released v3.3.0 `PipeDecoder` | 3,897 msg/s |
-| v3.4.0 `PipeDecoder` | 49,243 msg/s |
-| v3.4.0 + header prefilter | **85,963 msg/s** |
-
-On the 2,000-aircraft synthetic PipeDecoder workload, v3.4.0 processes
-38,838 msg/s versus v2's 39,604 msg/s, with identical normalized output.
-
-See [`scripts/README.md`](./scripts/README.md) for the reproducible commands
-and [`scripts/benchmark_results/`](./scripts/benchmark_results/) for the full
-methodology, timings, and output digests.
-
 ## Supported messages
 
 - **DF4 / DF20:** altitude code (surveillance altitude reply)
@@ -222,6 +202,10 @@ methodology, timings, and output digests.
   - BDS 5,0: track and turn report
   - BDS 6,0: heading and speed report
 
+BDS 4,4 and 4,5 are heuristic and disabled by default. Enable them with
+`decode(..., include_meteo=True)` or `PipeDecoder(include_meteo=True)` when
+these meteorological registers are expected on the input feed.
+
 ## Migrating from pyModeS 2.x
 
 pyModeS 3 is **not backwards-compatible** with pyModeS 2.x. The

{pymodes-3.4.0 → pymodes-3.5.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pyModeS"
-version = "3.4.0"
+version = "3.5.1"
 description = "Python Mode-S and ADS-B Decoder"
 authors = [{ name = "Junzi Sun", email = "git@junzis.com" }]
 license = { text = "GNU GPL v3" }

{pymodes-3.4.0 → pymodes-3.5.1}/scripts/README.md

@@ -13,13 +13,21 @@ through their names; generated benchmark reports live in
 
   ```bash
   uv run python scripts/stream_filtered.py \
-    --network airsquitter.lr.tudelft.nl:10006 > decoded.jsonl
+    --network airsquitter.lr.tudelft.nl:10006 \
+    --include-meteo > decoded.jsonl
   ```
 
+  `--include-meteo` is optional and enables heuristic Comm-B BDS 4,4/4,5
+  reports when the feed is expected to contain meteorological data.
+
 ## Benchmarks
 
-- `benchmark_mixed_traffic.py` — isolated v2, released-v3, updated-v3, and
-  prefiltered-v3 comparison on mixed captured traffic. Writes
+- `benchmark_mixed_traffic.py` — isolated v2.21.1, released v3.5.0, v3.5.1,
+  and prefiltered v3.5.1 comparison on mixed captured traffic. It measures
+  throughput, immediate streaming position yield, and coordinate agreement.
+  By default it fails below 80% of v2 position yield, below 99% agreement
+  within 100 m, or when v3.5.1 yields fewer positions than v3.5.0. The two
+  percentage floors are configurable through command-line options. Writes
   `benchmark_results/mixed_traffic.md` by default.
 - `benchmark_pipe.py` — synthetic high-cardinality PipeDecoder comparison.
   Writes `benchmark_results/pipe.md` by default.
@@ -54,5 +62,6 @@ access unless those packages are already cached.
   environment and checks the public API.
 - `smoke_test_cli.sh` — checks CLI decoding and a short live Beast connection.
 
-The CLI smoke test requires network access. The wheel smoke test uses the most
-recent `dist/pymodes-*.whl` when no path is supplied.
+The CLI smoke test requires network access. The wheel smoke test accepts an
+explicit wheel path; without one, it builds a fresh working-tree wheel in a
+temporary directory so stale files under `dist/` cannot be selected.

{pymodes-3.4.0 → pymodes-3.5.1}/src/pyModeS/__init__.py

@@ -18,9 +18,13 @@ and are NOT interchangeable:
   45 NM of the true position — tighter than the airborne tolerance.
 
 For streaming workflows where references aren't known ahead of time,
-use :class:`PipeDecoder` which resolves airborne positions from
-even/odd CPR pairs without any reference and still accepts
-``surface_ref`` for surface messages.
+use :class:`PipeDecoder`. It establishes airborne positions from even/odd CPR
+pairs, then resolves later frames locally from the last validated airborne
+position. The optional ``surface_ref`` applies only to surface messages.
+
+Comm-B BDS 4,4/4,5 meteorological inference is heuristic and disabled by
+default. Pass ``include_meteo=True`` to :func:`decode` or
+:class:`PipeDecoder` when these reports are expected on the input feed.
 """
 
 from importlib.metadata import version as _version