ASTERIX Decoder

This repository provides a processing pipeline for reading SASS-C Final Format data and decoding ADS-B information from Eurocontrol ASTERIX CAT021 Category 21 data.

The current implementation is built around CAT021 v0.26.

Overview

The workflow is:

1. Extract original .gz archives into Final Format (.ff) files.
2. Decode the extracted files according to the ASTERIX CAT021 v0.26 specification.
3. Export decoded ADS-B records to CSV files, grouped by icao24.
4. Optionally resample the decoded trajectories.

This project is intended for SASS-C Final Format inputs where the raw data is distributed as compressed .gz archives, extracted into .ff files, and then decoded for ADS-B analysis.

Repository Structure

.
+-- env/
|   +-- environment.yml
|   +-- README.md
|   `-- requirements.txt
`-- src/
    +-- extract.sh
    +-- decoder.py
    +-- resampler.py
    `-- core/

Requirements

• Python 3
• Conda
• 7z command available in your shell
• A Bash-compatible shell for running extract.sh

Python dependencies are listed in env/requirements.txt.

Environment Setup

Create the Conda environment:

conda env create -f ./env/environment.yml
conda activate asterix-decoder

If needed, install the Python packages explicitly:

uv pip install -r ./env/requirements.txt

Input Data

This repository expects:

• Original source files compressed as .gz
• Extracted SASS-C Final Format files with the .ff extension
• Final Format payloads containing ASTERIX CAT021 records

The decoder reads the Final Format binary files directly and parses CAT021 records using the local ASTERIX parser implementation in src/core/asterix/.

Step 1: Extract .gz Files

Use the extraction script to unpack all .gz files from a source directory into a destination directory:

bash ./src/extract.sh /path/to/source_gz_folder /path/to/extracted_folder

Notes:

• The script requires exactly two arguments: source folder and destination folder.
• It uses 7z x internally.
• The script extracts every *.gz file in the source folder.
• The extracted outputs are the Final Format .ff files used by the decoder.

Step 2: Decode Final Format Files to CSV

Run the decoder on the extracted Final Format .ff files:

python ./src/decoder.py --adsb-folder /path/to/extracted_folder --csv-folder /path/to/decoded_csv

What the decoder does:

• Reads each binary input file from --adsb-folder
• Splits reports using the Final Format footer marker
• Parses ASTERIX CAT021 records using the CAT021 v0.26 rule set
• Extracts ADS-B-related fields
• Saves one CSV per icao24 under a time-stamped output subfolder

The output folder structure looks like this:

decoded_csv/
`-- YYYYMMDD_HHMMSS/
    +-- YYYYMMDD_HHMMSS_abc123.csv
    +-- YYYYMMDD_HHMMSS_def456.csv
    `-- ...

Decoded Fields

The CSV output may include the following fields:

• board_number
• line_number
• recording_day
• time
• sac
• sic
• timestamp
• icao24
• callsign
• squawk
• latitude
• longitude
• groundspeed
• track
• baro_altitude
• geo_altitude
• baro_vertical_rate
• geo_vertical_rate

These fields are extracted from CAT021 items implemented in the parser, including identifiers, position, speed, heading, and altitude-related values.

Step 3: Resample Decoded Data

After decoding, you can resample the trajectory data across a selected time window:

python ./src/resampler.py \
  --csv-from-folder /path/to/decoded_csv \
  --csv-to-folder /path/to/resampled_csv \
  --start-time 2025-06-23 \
  --end-time 2025-07-01 \
  --sampling-interval 1

Recommended setting:

• Use a 1 second sampling interval for most downstream analysis.

What the resampler does:

• Selects decoded folders whose names fall within the requested time range
• Merges per-aircraft CSV files
• Converts record time to datetime
• Splits long gaps into separate trajectory segments
• Aggregates records by the requested sampling interval
• Writes resampled CSV files named as:

{icao24}_{start_unix_timestamp}_{end_unix_timestamp}.csv

Notes and Limitations

• The implementation currently targets Eurocontrol ASTERIX CAT021 v0.26.
• The extraction script assumes the source files are .gz.
• The decoder is intended to read extracted Final Format .ff files.
• The decoder is designed for SASS-C Final Format data layout used in this project.
• Runtime can be long for large datasets. The source code notes that decoding and resampling can take multiple hours depending on data volume.

Suggested End-to-End Workflow

# 1. Extract raw archives
bash ./src/extract.sh ./data/source_gz_folder ./data/extracted_folder

# 2. Decode extracted `.ff` files
python ./src/decoder.py --adsb-folder ./data/extracted_folder --csv-folder ./data/decoded_csv

# 3. Resample decoded trajectories to 1-second intervals
python ./src/resampler.py \
  --csv-from-folder ./data/decoded_csv \
  --csv-to-folder ./data/resampled_csv \
  --start-time 2025-06-23 \
  --end-time 2025-07-01 \
  --sampling-interval 1 \
  --num-proc 8

---

Disclaimer: This readme was AI-generated. (Created using Codex GPT-5.4 with medium reasoning.)