adsb-generator 0.1.0__tar.gz

adsb_generator-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Hamri (adamhamri9)
+
+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.

adsb_generator-0.1.0/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: adsb-generator
+Version: 0.1.0
+Summary: `adsb-generator` produces realistic I/Q (In-phase/Quadrature) samples of clean and impaired ADS-B (Mode S Downlink Format 17) baseband signals, along with the raw 112-bit message and all applied parameters. It implements an infinite iterator that streams reproducible samples with full control over message type distributions, transmission parameters, and channel impairments.
+Author-email: Adam Hamri <adamhamri9@proton.me>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/adamhamri9/adsb-datagen
+Project-URL: Repository, https://github.com/adamhamri9/adsb-datagen
+Project-URL: Issues, https://github.com/adamhamri9/adsb-datagen/issues
+Keywords: adsb,mode-s,aviation,signal-generation,iq-samples,baseband
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Communications :: Ham Radio
+Requires-Python: <3.14,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Dynamic: license-file
+
+# adsb-generator
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/Python-3.10+-3776AB.svg)](https://www.python.org/downloads/)
+
+**Synthetic ADS-B data generator.**
+
+`adsb-generator` produces realistic I/Q (In-phase/Quadrature) samples of clean and impaired ADS-B (Mode S Downlink Format 17) baseband signals, along with the raw 112-bit message and all applied parameters. It implements an infinite iterator that streams reproducible samples with full control over message type distributions, transmission parameters, and channel impairments.
+
+## Key Features
+
+- **End-to-end pipeline**: random message generation, PPM encoding, and RF channel simulation in a single call.
+- **Four ADS-B message types**: identification, surface position, airborne position, and airborne velocity with configurable emission probabilities.
+- **Realistic channel impairments**: Gaussian Noise(both AWGN and Correlated) , frequency & phase offset, IQ imbalance, and DC offset, all sampled from configurable probability distributions.
+- **Reproducibility**: deterministic output via a shared seed across all pipeline stages.
+- **Configurable distributions**: override any transmission or channel parameter distribution to model specific receiver conditions or hardware behavior.
+- **NumPy-native**: all signals are `np.complex64` arrays, ready for direct use with any downstream processing tool.
+
+## Requirements
+
+- Python 3.10+
+- NumPy
+
+## Installation
+
+```bash
+pip install adsb-generator
+```
+
+## Usage
+
+```python
+from adsb_generator import ADSBGenerator
+
+# Create a generator with a fixed seed for reproducibility
+gen = ADSBGenerator(seed=42)
+
+# Each iteration yields an ADSBSample with the raw message,
+# clean signal, and channel-impaired signal
+for sample in gen:
+    print(f"Message type : {sample.message_type.value}")
+    print(f"Raw message  : {sample.message:#028x}")
+    print(f"Clean signal : {sample.clean_signal.shape} complex64 samples")
+    print(f"Noisy signal : {sample.channel_signal.shape} complex64 samples")
+    print(f"SNR (dB)     : {sample.channel_params['snr_db']:.1f}")
+    print(f"Amplitude    : {sample.tx_params['amplitude']:.3f}")
+    break
+```
+
+### Customizing Distributions
+
+```python
+from adsb_generator import ADSBGenerator, MessageType, ChannelParams
+
+# Favor airborne positions, restrict SNR to low-moderate range
+gen = ADSBGenerator(
+    message_type_probs={
+        MessageType.AIRBORNE_POSITION: 0.60,
+        MessageType.AIRBORNE_VELOCITY: 0.20,
+        MessageType.IDENTIFICATION: 0.10,
+        MessageType.SURFACE_POSITION: 0.10,
+    },
+    channel_params_distributions={
+        ChannelParams.SNR_DB: [
+            [3.0, 8.0, 0.70],
+            [8.0, 15.0, 0.30],
+        ],
+    },
+    sample_rate=2e6,
+    seed=12345,
+)
+
+sample = next(gen)
+```
+
+## API Reference
+
+### `ADSBGenerator`
+
+```python
+ADSBGenerator(
+    message_type_probs: dict[MessageType | str, float] | None = None,
+    tx_params_distributions: dict[TXParams | str, list[list[float]]] | None = None,
+    channel_params_distributions: dict[ChannelParams | str, list[list[float]]] | None = None,
+    sample_rate: float = 2e6,
+    seed: int | None = None,
+)
+```
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `message_type_probs` | `dict` or `None` | Equal 25% per type | Mapping of `MessageType` to emission probabilities (must sum to 1.0). |
+| `tx_params_distributions` | `dict` or `None` | Single amplitude band | Mapping of `TXParams` to `[[min, max, weight], ...]` intervals. |
+| `channel_params_distributions` | `dict` or `None` | Typical ADS-B conditions | Mapping of `ChannelParams` to `[[min, max, weight], ...]` intervals. |
+| `sample_rate` | `float` | `2e6` | Sampling rate in samples per second. |
+| `seed` | `int` or `None` | Random | Seed for deterministic output across all pipeline stages. |
+
+---
+
+### `ADSBSample`
+
+Dataclass returned by each iteration of `ADSBGenerator`.
+
+| Field | Type | Description |
+|---|---|---|
+| `message` | `int` | Complete 112-bit ADS-B message (including 24-bit CRC) as an integer. |
+| `message_type` | `MessageType` | The type of ADS-B message generated. |
+| `clean_signal` | `np.ndarray` | Complex baseband I/Q signal before channel impairments (`complex64`). |
+| `tx_params` | `dict[TXParams, float]` | Transmission parameters applied during encoding. |
+| `channel_signal` | `np.ndarray` | Complex baseband I/Q signal after channel impairments (`complex64`). |
+| `channel_params` | `dict[ChannelParams, float]` | Channel parameters applied to the signal. |
+
+---
+
+### `MessageType`
+
+| Value | Description |
+|---|---|
+| `IDENTIFICATION` | Aircraft identification (callsign) messages (TC 1--4). |
+| `SURFACE_POSITION` | Surface position messages (TC 5--8). |
+| `AIRBORNE_POSITION` | Airborne position messages (TC 9--18, 20--22). |
+| `AIRBORNE_VELOCITY` | Airborne velocity messages (TC 19). |
+
+---
+
+### `ADSBEncoder`
+
+Encodes 112-bit messages into complex baseband I/Q samples using PPM per the Mode S standard.
+
+```python
+ADSBEncoder(
+    sample_rate: float = 2e6,
+    tx_params_distributions: dict[TXParams | str, list[list[float]]] | None = None,
+    seed: int | None = None,
+)
+```
+
+| Method | Returns | Description |
+|---|---|---|
+| `encode(msg: int)` | `tuple[np.ndarray, dict[TXParams, float]]` | Encodes a 112-bit message into a 120-us baseband I/Q signal. |
+
+---
+
+### `ADSBChannel`
+
+Simulates realistic RF channel impairments on baseband I/Q signals.
+
+```python
+ADSBChannel(
+    sample_rate: float = 2e6,
+    channel_params_distributions: dict[ChannelParams | str, list[list[float]]] | None = None,
+    seed: int | None = None,
+)
+```
+
+| Method | Returns | Description |
+|---|---|---|
+| `apply(signal: np.ndarray)` | `tuple[np.ndarray, dict[ChannelParams, float]]` | Applies impairments: IQ imbalance, DC offset, frequency offset, phase offset, AWGN. |
+
+---
+
+### `ChannelParams`
+
+| Value | Description |
+|---|---|
+| `SNR_DB` | Signal-to-noise ratio in dB. |
+| `NOISE_CORRELATION` | I/Q noise correlation coefficient (-1.0 to 1.0). |
+| `FREQUENCY_OFFSET` | Carrier frequency offset in Hz. |
+| `PHASE_OFFSET` | Phase offset in radians. |
+| `DC_OFFSET_I` | DC offset on the in-phase component. |
+| `DC_OFFSET_Q` | DC offset on the quadrature component. |
+| `IQ_GAIN_IMBALANCE` | Gain imbalance between I and Q channels. |
+| `IQ_PHASE_IMBALANCE` | Phase imbalance between I and Q channels (degrees). |
+
+---
+
+### `ADSBAlgorithms`
+
+Static utility class providing ADS-B encoding algorithms.
+
+| Method | Returns | Description |
+|---|---|---|
+| `calculate_crc(data: int)` | `int` | Computes 24-bit CRC parity using polynomial `0xFFF409`. |
+| `encode_cpr(lat, lon, odd)` | `tuple[int, int]` | Encodes lat/lon into CPR 17-bit values. |
+| `encode_altitude(alt: int)` | `int` | Encodes altitude in feet into 12-bit Gillham-coded format. |
+| `encode_ground_track(degrees, valid)` | `tuple[int, int]` | Encodes ground track heading into the 7-bit format. |
+
+## Distribution Format
+
+All configurable distributions use the format `[[min_val, max_val, weight], ...]` where weights for a given parameter must sum to `1.0` (+/- 0.01 tolerance). Keys can be enum members or their string values (e.g., `ChannelParams.SNR_DB` or `"snr_db"`).
+
+## License
+
+[MIT](LICENSE) - Copyright (c) 2026 Adam Hamri (adamhamri9)

adsb_generator-0.1.0/README.md

@@ -0,0 +1,194 @@
+# adsb-generator
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/Python-3.10+-3776AB.svg)](https://www.python.org/downloads/)
+
+**Synthetic ADS-B data generator.**
+
+`adsb-generator` produces realistic I/Q (In-phase/Quadrature) samples of clean and impaired ADS-B (Mode S Downlink Format 17) baseband signals, along with the raw 112-bit message and all applied parameters. It implements an infinite iterator that streams reproducible samples with full control over message type distributions, transmission parameters, and channel impairments.
+
+## Key Features
+
+- **End-to-end pipeline**: random message generation, PPM encoding, and RF channel simulation in a single call.
+- **Four ADS-B message types**: identification, surface position, airborne position, and airborne velocity with configurable emission probabilities.
+- **Realistic channel impairments**: Gaussian Noise(both AWGN and Correlated) , frequency & phase offset, IQ imbalance, and DC offset, all sampled from configurable probability distributions.
+- **Reproducibility**: deterministic output via a shared seed across all pipeline stages.
+- **Configurable distributions**: override any transmission or channel parameter distribution to model specific receiver conditions or hardware behavior.
+- **NumPy-native**: all signals are `np.complex64` arrays, ready for direct use with any downstream processing tool.
+
+## Requirements
+
+- Python 3.10+
+- NumPy
+
+## Installation
+
+```bash
+pip install adsb-generator
+```
+
+## Usage
+
+```python
+from adsb_generator import ADSBGenerator
+
+# Create a generator with a fixed seed for reproducibility
+gen = ADSBGenerator(seed=42)
+
+# Each iteration yields an ADSBSample with the raw message,
+# clean signal, and channel-impaired signal
+for sample in gen:
+    print(f"Message type : {sample.message_type.value}")
+    print(f"Raw message  : {sample.message:#028x}")
+    print(f"Clean signal : {sample.clean_signal.shape} complex64 samples")
+    print(f"Noisy signal : {sample.channel_signal.shape} complex64 samples")
+    print(f"SNR (dB)     : {sample.channel_params['snr_db']:.1f}")
+    print(f"Amplitude    : {sample.tx_params['amplitude']:.3f}")
+    break
+```
+
+### Customizing Distributions
+
+```python
+from adsb_generator import ADSBGenerator, MessageType, ChannelParams
+
+# Favor airborne positions, restrict SNR to low-moderate range
+gen = ADSBGenerator(
+    message_type_probs={
+        MessageType.AIRBORNE_POSITION: 0.60,
+        MessageType.AIRBORNE_VELOCITY: 0.20,
+        MessageType.IDENTIFICATION: 0.10,
+        MessageType.SURFACE_POSITION: 0.10,
+    },
+    channel_params_distributions={
+        ChannelParams.SNR_DB: [
+            [3.0, 8.0, 0.70],
+            [8.0, 15.0, 0.30],
+        ],
+    },
+    sample_rate=2e6,
+    seed=12345,
+)
+
+sample = next(gen)
+```
+
+## API Reference
+
+### `ADSBGenerator`
+
+```python
+ADSBGenerator(
+    message_type_probs: dict[MessageType | str, float] | None = None,
+    tx_params_distributions: dict[TXParams | str, list[list[float]]] | None = None,
+    channel_params_distributions: dict[ChannelParams | str, list[list[float]]] | None = None,
+    sample_rate: float = 2e6,
+    seed: int | None = None,
+)
+```
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `message_type_probs` | `dict` or `None` | Equal 25% per type | Mapping of `MessageType` to emission probabilities (must sum to 1.0). |
+| `tx_params_distributions` | `dict` or `None` | Single amplitude band | Mapping of `TXParams` to `[[min, max, weight], ...]` intervals. |
+| `channel_params_distributions` | `dict` or `None` | Typical ADS-B conditions | Mapping of `ChannelParams` to `[[min, max, weight], ...]` intervals. |
+| `sample_rate` | `float` | `2e6` | Sampling rate in samples per second. |
+| `seed` | `int` or `None` | Random | Seed for deterministic output across all pipeline stages. |
+
+---
+
+### `ADSBSample`
+
+Dataclass returned by each iteration of `ADSBGenerator`.
+
+| Field | Type | Description |
+|---|---|---|
+| `message` | `int` | Complete 112-bit ADS-B message (including 24-bit CRC) as an integer. |
+| `message_type` | `MessageType` | The type of ADS-B message generated. |
+| `clean_signal` | `np.ndarray` | Complex baseband I/Q signal before channel impairments (`complex64`). |
+| `tx_params` | `dict[TXParams, float]` | Transmission parameters applied during encoding. |
+| `channel_signal` | `np.ndarray` | Complex baseband I/Q signal after channel impairments (`complex64`). |
+| `channel_params` | `dict[ChannelParams, float]` | Channel parameters applied to the signal. |
+
+---
+
+### `MessageType`
+
+| Value | Description |
+|---|---|
+| `IDENTIFICATION` | Aircraft identification (callsign) messages (TC 1--4). |
+| `SURFACE_POSITION` | Surface position messages (TC 5--8). |
+| `AIRBORNE_POSITION` | Airborne position messages (TC 9--18, 20--22). |
+| `AIRBORNE_VELOCITY` | Airborne velocity messages (TC 19). |
+
+---
+
+### `ADSBEncoder`
+
+Encodes 112-bit messages into complex baseband I/Q samples using PPM per the Mode S standard.
+
+```python
+ADSBEncoder(
+    sample_rate: float = 2e6,
+    tx_params_distributions: dict[TXParams | str, list[list[float]]] | None = None,
+    seed: int | None = None,
+)
+```
+
+| Method | Returns | Description |
+|---|---|---|
+| `encode(msg: int)` | `tuple[np.ndarray, dict[TXParams, float]]` | Encodes a 112-bit message into a 120-us baseband I/Q signal. |
+
+---
+
+### `ADSBChannel`
+
+Simulates realistic RF channel impairments on baseband I/Q signals.
+
+```python
+ADSBChannel(
+    sample_rate: float = 2e6,
+    channel_params_distributions: dict[ChannelParams | str, list[list[float]]] | None = None,
+    seed: int | None = None,
+)
+```
+
+| Method | Returns | Description |
+|---|---|---|
+| `apply(signal: np.ndarray)` | `tuple[np.ndarray, dict[ChannelParams, float]]` | Applies impairments: IQ imbalance, DC offset, frequency offset, phase offset, AWGN. |
+
+---
+
+### `ChannelParams`
+
+| Value | Description |
+|---|---|
+| `SNR_DB` | Signal-to-noise ratio in dB. |
+| `NOISE_CORRELATION` | I/Q noise correlation coefficient (-1.0 to 1.0). |
+| `FREQUENCY_OFFSET` | Carrier frequency offset in Hz. |
+| `PHASE_OFFSET` | Phase offset in radians. |
+| `DC_OFFSET_I` | DC offset on the in-phase component. |
+| `DC_OFFSET_Q` | DC offset on the quadrature component. |
+| `IQ_GAIN_IMBALANCE` | Gain imbalance between I and Q channels. |
+| `IQ_PHASE_IMBALANCE` | Phase imbalance between I and Q channels (degrees). |
+
+---
+
+### `ADSBAlgorithms`
+
+Static utility class providing ADS-B encoding algorithms.
+
+| Method | Returns | Description |
+|---|---|---|
+| `calculate_crc(data: int)` | `int` | Computes 24-bit CRC parity using polynomial `0xFFF409`. |
+| `encode_cpr(lat, lon, odd)` | `tuple[int, int]` | Encodes lat/lon into CPR 17-bit values. |
+| `encode_altitude(alt: int)` | `int` | Encodes altitude in feet into 12-bit Gillham-coded format. |
+| `encode_ground_track(degrees, valid)` | `tuple[int, int]` | Encodes ground track heading into the 7-bit format. |
+
+## Distribution Format
+
+All configurable distributions use the format `[[min_val, max_val, weight], ...]` where weights for a given parameter must sum to `1.0` (+/- 0.01 tolerance). Keys can be enum members or their string values (e.g., `ChannelParams.SNR_DB` or `"snr_db"`).
+
+## License
+
+[MIT](LICENSE) - Copyright (c) 2026 Adam Hamri (adamhamri9)

adsb_generator-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "adsb-generator"
+version = "0.1.0"
+description = "`adsb-generator` produces realistic I/Q (In-phase/Quadrature) samples of clean and impaired ADS-B (Mode S Downlink Format 17) baseband signals, along with the raw 112-bit message and all applied parameters. It implements an infinite iterator that streams reproducible samples with full control over message type distributions, transmission parameters, and channel impairments."
+readme = { file = "README.md", content-type = "text/markdown" }
+license = "MIT"
+requires-python = ">=3.10,<3.14"
+authors = [
+    { name = "Adam Hamri", email = "adamhamri9@proton.me" },
+]
+keywords = ["adsb", "mode-s", "aviation", "signal-generation", "iq-samples", "baseband"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Communications :: Ham Radio",
+]
+dependencies = [
+    "numpy>=1.26.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/adamhamri9/adsb-datagen"
+Repository = "https://github.com/adamhamri9/adsb-datagen"
+Issues = "https://github.com/adamhamri9/adsb-datagen/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

adsb_generator-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

adsb_generator-0.1.0/src/adsb_generator/__init__.py

@@ -0,0 +1,9 @@
+__version__ = "0.1.0"
+
+from .generator import ADSBSample, ADSBGenerator
+from .channel import ChannelParams, ADSBChannel
+from .encoder import TXParams, ADSBEncoder
+from .message import MessageType, ADSBMessage
+
+__all__ = ["ADSBSample", "ADSBGenerator", "ChannelParams", "ADSBChannel",
+            "TXParams", "ADSBEncoder", "MessageType", "ADSBMessage"]

adsb_generator-0.1.0/src/adsb_generator/algorithms.py

@@ -0,0 +1,84 @@
+import math
+
+class ADSBAlgorithms():
+
+    CRC_POLY = 0xFFF409
+
+    @classmethod
+    def calculate_crc(cls, data: int) -> int:
+
+        packet = data << 24
+        remainder = packet
+
+        for bit in range(111, 23, -1):
+            if (remainder >> bit) & 1:
+                remainder ^= cls.CRC_POLY << (bit - 24)
+
+        crc = remainder & 0xFFFFFF
+
+        return packet | crc
+
+    _NL_TABLE = [
+        (87, 59), (83, 58), (79, 57), (76, 56), (73, 55),
+        (70, 54), (66, 53), (63, 52), (60, 51), (57, 50),
+        (53, 49), (50, 48), (46, 47), (43, 46), (40, 45),
+        (37, 44), (34, 43), (31, 42), (28, 41), (25, 40),
+        (22, 39), (19, 38), (16, 37), (13, 36), (9, 35),
+        (6, 34), (3, 33), (0, 32),
+    ]
+
+    @classmethod
+    def _nl(cls, lat: float) -> int:
+        if abs(lat) >= 87:
+            return 1
+        for lat_min, nl in cls._NL_TABLE:
+            if abs(lat) >= lat_min:
+                return nl
+        return 32
+
+    @classmethod
+    def encode_cpr(cls, lat: float, lon: float, odd: bool) -> tuple[int, int]:
+        lat = max(-90.0, min(90.0, lat))
+        lon = max(-180.0, min(180.0, lon))
+
+        NB = 17
+        factor = 1 << NB
+
+        nz_lat = 59 if odd else 60
+        dlat = 360.0 / nz_lat
+
+        zone_lat = math.floor(lat / dlat)
+        rem_lat = lat - zone_lat * dlat
+        yz = int(round((rem_lat / dlat) * factor)) & (factor - 1)
+
+        rlat = dlat * (yz / factor + zone_lat)
+        rlat = max(-90.0, min(90.0, rlat))
+
+        nl = cls._nl(rlat)
+
+        dlon = 360.0 / nl
+        zone_lon = math.floor(lon / dlon)
+        rem_lon = lon - zone_lon * dlon
+        xz = int(round((rem_lon / dlon) * factor)) & (factor - 1)
+
+        return yz, xz
+
+    @staticmethod
+    def encode_altitude(alt: int) -> int:
+        alt_clamped = max(-1000, min(50100, alt))
+        n = (alt_clamped + 1000) // 25
+
+        top_bits = (n >> 4) & 0x7F
+        bottom_bits = n & 0x0F
+
+        return (top_bits << 5) | (1 << 4) | bottom_bits
+
+    @staticmethod
+    def encode_ground_track(degrees: float, valid: bool = True) -> tuple[int, int]:
+        if not valid or degrees is None:
+            return 0, 0
+
+        degrees = degrees % 360.0
+        trk_code = round(degrees * 128.0 / 360.0)
+
+        return 1, trk_code