Seismic waveform pipeline for atmospheric re-entry events using orbital ground tracks and seismic station data.
Quick Start »
·
Report Bug
·
Request Feature
Table of Contents
Groundtrack is a Python library developed for discovering and analyzing seismic signals that are produced when an object re-enters the atmosphere. When space debris or a spacecraft re-enters the atmosphere at hypersonic speeds, it generates sonic booms that then couple into the ground and are recorded by seismic stations. Groundtrack automates the full pipeline from orbital data to the processed waveforms, while allowing each piece of the pipeline to be easily configured/called if the user wishes:
- Fetches TLE elements from Space-Track using a user-provided NORAD ID
- Propagates the ground track over a user-defined analysis window
- Tiles the track into spatial boxes and queries FDSN providers for any nearby seismic stations that fall within a given box
- Downloads waveform data for stations within a configurable distance from the ground track
- Applies instrument response removal and bandpass filtering
- Provides optional visualization tools for validating output
The library was developed at Johns Hopkins University as independent research in collaboration with Dr. Benjamin Fernando (Department of Earth and Planetary Sciences), building on the methodology established in his work on seismic detection of the 2024 Shenzhou-15 re-entry. The pipeline was first validated in multiple proof-of-concept Jupyter notebooks replicating published detection results before being migrated into this library format.
Groundtrack includes built-in plotting utilities for analyzing re-entry events:
- Ground track + download boxes visualization
- Station distribution maps
- Raw vs. processed waveform comparisons
Install with plotting support:
pip install groundtrack[plotting]
- Python 3.10+
- A free Space-Track account for TLE and TIP message access
Install from PyPI:
pip install groundtrackWith optional plotting support:
pip install groundtrack[plotting]Groundtrack requires Space-Track credentials to fetch orbital data. Create a .env file in your project root:
SPACETRACK_USER=your_email@example.com
SPACETRACK_PASS=your_password
Add .env to your .gitignore to avoid accidentally committing credentials:
echo ".env" >> .gitignoreOr pass them directly to run_pipeline():
results = run_pipeline(
...,
username="your_email@example.com",
password="your_password",
)from groundtrack import run_pipeline
results = run_pipeline(
norad_id=56873,
start="2024-04-02T08:40:00Z",
end="2024-04-02T09:00:00Z",
cache_dir="data/cache",
output_dir="data/outputs",
event_name="shenzhou15_reentry",
)results = run_pipeline(
norad_id=56873,
start="2024-04-02T08:40:00Z",
end="2024-04-02T09:00:00Z",
cache_dir="data/cache",
output_dir="data/outputs",
event_name="shenzhou15_reentry",
corridor_km=100.0, # station inclusion threshold
chunk_km=300.0, # along-track box size
apply_processing=True, # remove instrument response + bandpass
freqmin=1.0, # bandpass lower corner (Hz)
freqmax=20.0, # bandpass upper corner (Hz)
)Download first, process later with different parameters:
from groundtrack import run_pipeline, process_boxes
# Step 1 - download only
results = run_pipeline(
norad_id=56873,
start="2024-04-02T08:40:00Z",
end="2024-04-02T09:00:00Z",
cache_dir="data/cache", # TLEs are cached here to avoid redundant Space-Track requests
output_dir="data/outputs",
event_name="shenzhou15_reentry",
)
# Step 2 - process separately with custom settings
process_boxes(
boxes_root=results["manifest"]["boxes_root"],
freqmin=1.0,
freqmax=10.0,
)from groundtrack import (
plot_track_and_boxes,
plot_stations,
plot_all_waveforms,
)
from pathlib import Path
# Plot ground track and download boxes
plot_track_and_boxes(
track_points=results["track"]["track_points"],
box_windows=results["boxes"],
)
# Plot all processed waveforms for a specific box
plot_all_waveforms(
boxes_root=Path(results["manifest"]["boxes_root"]),
box_ids="box_006",
t_start_utc="2024-04-02T08:44:00Z",
t_end_utc="2024-04-02T08:54:00Z",
)- Validated against Shenzhou-15 re-entry event
- Space-Track TLE fetching with local caching
- Orbital propagation and ground track tiling
- FDSN station discovery with 100 km corridor filter (configurable)
- MassDownloader-based waveform acquisition
- Instrument response removal and bandpass filtering
- Visualization utilities
- Automated test suite
- Full documentation site
- Parallelized station queries for full-orbit passes
- Automated sonic boom detection and classification
- Trajectory reconstruction from detection results
- Live re-entry support with real-time orbital data updates
See the open issues for a full list of proposed features and known issues.
Contributions are welcome. If you have a suggestion or find a bug, please open an issue or submit a pull request.
- Fork the project
- Create your feature branch (
git checkout -b feature/YourFeature) - Commit your changes (
git commit -m 'Add YourFeature') - Push to the branch (
git push origin feature/YourFeature) - Open a pull request
Distributed under the MIT License. See LICENSE for more information.
Joseph Steinberg - LinkedIn - josephsteinberg933@gmail.com
Project Link: https://github.com/jsteinberg34/groundtrack
- Dr. Benjamin Fernando - Johns Hopkins University, Department of Earth and Planetary Sciences. Scientific methodology and validation.
- ObsPy - Core seismic data library
- Skyfield - Orbital propagation
- Space-Track - TLE and TIP message data
- Cartopy - Map visualization
- Ed Williams' Aviation Formulary - Spherical cross-track distance formula