pyModeS 3.0.0__tar.gz → 3.1.0__tar.gz

{pymodes-3.0.0 → pymodes-3.1.0}/CHANGELOG.md

@@ -5,6 +5,49 @@ 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.1.0] — 2026-04-14
+
+Streaming-robustness release. Adds defences against phantom positions
+at stream start and against DF20 CRC-collisions that attribute a
+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
+  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.
+- `PipeDecoder` altitude cross-check on DF20 Comm-B replies: if the
+  message's 13-bit AC-code disagrees with the ICAO's most recent
+  ADS-B-derived altitude by more than `_altitude_tolerance(dt)` (a
+  linearly growing, floored-and-capped window), the BDS payload
+  fields are stripped from the result and `altitude_mismatch=True`
+  is set. The AC-code altitude itself is preserved so callers see
+  why the frame was flagged.
+- `PipeDecoder.flush()` method that finalizes any still-bootstrapping
+  ICAOs, running cluster analysis on whatever candidates are
+  buffered (even if fewer than K) and retro-filling the held result
+  dicts in place. Automatically called by the batch `decode(list,
+  timestamps=list)` code path so batch callers get positions on
+  every resolvable frame without having to reach into `PipeDecoder`.
+- Four new per-stream stat counters exposed via `PipeDecoder.stats`:
+  `altitude_mismatch`, `position_rejected`, `bootstrap_held`,
+  `bootstrap_reset`.
+
+### Fixed
+
+- `airborne_position_pair` now rejects CPR pairs that resolve to
+  physically impossible latitudes (|lat| > 90). Root cause: real
+  DF17 pairs that straddle a `cprNL` zone can slip past the
+  pre-pair `NL(lat_even) == NL(lat_odd)` check and produce
+  latitudes in [90, 270) — e.g. an aircraft climbing out of
+  Amsterdam resolving to lat ≈ 113° over the Bering Sea.
+  Observed on ICAO 485A33 (2025-04-13 19:34:57 UTC, OpenSky feed)
+  — now rejected at the pair resolver rather than poisoning the
+  receiver's position history.
+
 ## [3.0.0] — 2026-04-13
 
 First release of the v3 ground-up rewrite. **Not backwards-compatible

{pymodes-3.0.0 → pymodes-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyModeS
-Version: 3.0.0
+Version: 3.1.0
 Summary: Python Mode-S and ADS-B Decoder
 Project-URL: homepage, https://mode-s.org
 Project-URL: repository, https://github.com/junzis/pyModeS

{pymodes-3.0.0 → pymodes-3.1.0}/pyproject.toml

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

{pymodes-3.0.0 → pymodes-3.1.0}/src/pyModeS/_altcode.py

@@ -5,9 +5,12 @@ It supports two encodings:
 
 - Q = 1: 25-foot interval, linear. 11 bits form a value N;
   altitude = N * 25 - 1000 (feet).
-- Q = 0: 100-foot interval, Gillham gray code. Re-orders the 11 non-M
-  non-Q bits into a gray-coded (500-ft, 100-ft) pair and converts to
-  feet via `alt = n500 * 500 + n100 * 100 - 1300`.
+- Q = 0: 100-foot interval, Gillham code (a Gray-code variant used by
+  legacy pressure altimeters; see ICAO Annex 10 Vol IV and DO-260).
+  Re-orders the 11 non-M non-Q bits into a Gillham-coded (500-ft,
+  100-ft) pair and converts to feet via
+  `alt = n500 * 500 + n100 * 100 - 1300`. Note: Q=0 is a distinct
+  encoding standard, not an indicator of high altitude.
 
 If the entire 13-bit field is zero, altitude is reported as unknown.
 """
@@ -41,7 +44,7 @@ def altcode_to_altitude(ac: int) -> int | None:
         return n * 25 - 1000
 
     if m_bit == 0 and q_bit == 0:
-        # 100-foot interval, Gillham gray code.
+        # 100-foot interval, Gillham code.
         # Extract each named bit from the 13-bit AC field.
         def b(pos: int) -> int:
             return (ac >> (12 - pos)) & 0x1
@@ -53,9 +56,10 @@ def altcode_to_altitude(ac: int) -> int | None:
         b2, d2 = b(9), b(10)
         b4, d4 = b(11), b(12)
 
-        # Re-order into the Gillham gray string:
-        #   graystr = D2 D4 A1 A2 A4 B1 B2 B4 C1 C2 C4  (11 bits)
-        # Split: gc500 = first 8, gc100 = last 3.
+        # Rearrange the non-M, non-Q bits per DO-260 into the sequence
+        #   D2 D4 A1 A2 A4 B1 B2 B4 C1 C2 C4  (11 bits)
+        # The first 8 bits form a Gillham-coded 500-ft counter and the
+        # last 3 bits a 100-ft counter, per ICAO Annex 10 Vol IV.
         gc500 = (
             (d2 << 7)
             | (d4 << 6)
@@ -90,7 +94,11 @@ def altcode_to_altitude(ac: int) -> int | None:
 
 
 def _gray2int(n: int) -> int:
-    """Convert an unsigned Gillham gray code to a plain binary integer."""
+    """Convert an unsigned Gillham code to a plain binary integer.
+
+    Gillham is a reflected Gray-code variant, so the standard Gray-to-binary
+    fold (XOR with successive right-shifts) applies.
+    """
     n ^= n >> 8
     n ^= n >> 4
     n ^= n >> 2