Helicorder Plotter

Helicorder Plotter is a Python-based tool that fetches seismic waveform data from FDSN web services, generates 24-hour helicorder (dayplot) images with earthquake event annotations, and produces a self-contained static website for browsing the results — including an interactive Leaflet map of all station locations.

How It Works

config.ini FDSN dataselect IRIS event service
│ │ │
▼ ▼ ▼
read_station_config get_waveforms fetch_earthquake_events
│ │ │
│ ▼ │
│ ObsPy Stream ──────────────────┘
│ │
│ ▼
│ create_helicorder()
│ ├─ full-res PNG
│ └─ thumbnail PNG
│ │
▼ ▼
generate_html() copy_static_files()
│
▼
helicorder_plots/
├── index.html
├── map_view.html
├── station_data.json
├── <station>.html (one per station)
├── <station>.png
├── <station>_thumb.png
└── static/
├── css/styles.css
└── js/main.js

Pipeline Steps

1. Configuration — Station definitions (network, station, channel, location) are read from config.ini.
2. Earthquake events — Recent significant earthquakes (M5.5+, last 24 hours) are fetched from the IRIS FDSN event service to annotate the plots.
3. Waveform retrieval — For each station, 24 hours of waveform data is requested from a local (or remote) FDSN dataselect service. Requests are parallelised across stations using a process pool.
4. Plot generation — Each waveform stream is rendered as a helicorder dayplot via ObsPy, with earthquake events overlaid as annotations. A thumbnail is generated alongside the full-resolution image.
5. HTML generation — Jinja2 templates produce an index page with thumbnail grid, individual station detail pages, and an interactive Leaflet map that plots each station's geographic coordinates.

Requirements

• Python 3.7+
• A running FDSN dataselect web service (e.g. SeisComP fdsnws, ringserver, or any FDSN-compliant server)

Python Dependencies

Listed in requirements.txt:

Package	Purpose
ObsPy	Waveform I/O, dayplot rendering, UTCDateTime
matplotlib	Plotting backend (used by ObsPy)
Pillow	Thumbnail generation
requests	HTTP requests to FDSN services
Jinja2	HTML template rendering

Installation

git clone https://github.com/comoglu/helicorder-plotter.git
cd helicorder-plotter
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt

Configuration

Station List (config.ini)

Each section defines a station to plot. The section name is Network.Station:

[AU.CNB]detecstream = BHZ
deteclocid = 00
[AU.CTA]detecstream = BHZ
deteclocid =

Key	Description
detecstream	SEED channel code (e.g. BHZ, SHZ, HHZ, EHZ)
deteclocid	SEED location code (e.g. 00, 01, or empty for --)

Service URLs (run.py)

Edit the constants at the top of run.py to point at your data sources:

BASE_URL="http://127.0.0.1:18081"# FDSN dataselect + station serviceEVENT_SERVICE_URL="http://service.iris.edu/fdsnws/event/1/query"# Earthquake event service

BASE_URL should point to a server that exposes both /fdsnws/dataselect/1/query and /fdsnws/station/1/query endpoints.

Usage

python run.py

The script will:

1. Validate the station configuration
2. Fetch M5.5+ earthquake events from the last 24 hours
3. Download waveforms for each configured station (in parallel)
4. Generate helicorder dayplots with event annotations
5. Build a static HTML site in the helicorder_plots/ directory

Open helicorder_plots/index.html in a browser to view the results.

Output Structure

helicorder_plots/
├── index.html # Thumbnail grid of all stations
├── map_view.html # Interactive Leaflet map
├── station_data.json # Station coordinates for the map
├── AU.CNB.00.BHZ.html # Individual station detail page
├── AU.CNB.00.BHZ.png # Full-resolution helicorder plot
├── AU.CNB.00.BHZ_thumb.png # Thumbnail
├── static/
│ ├── css/styles.css
│ └── js/main.js
└── ...

Logs

Log files are written to logs/ with timestamps (e.g. logs/helicorder_plotter_20260318_120000.log). Both file and console logging are enabled.

Project Structure

helicorder-plotter/
├── run.py # Entry point and configuration constants
├── config.ini # Station definitions
├── requirements.txt # Python dependencies
├── src/
│ ├── __init__.py
│ ├── data_fetcher.py # Config parsing, FDSN requests, station info
│ ├── plot_generator.py # Helicorder plot creation, parallel processing
│ ├── html_generator.py # Jinja2 HTML generation, static file copying
│ └── utils.py # Logging setup, timing decorator
├── templates/
│ ├── all_stations.html # Index page template
│ ├── station.html # Individual station page template
│ └── map_view.html # Leaflet map template
└── static/
├── css/styles.css # Shared stylesheet
└── js/main.js # Map initialisation script

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License — see the LICENSE file for details.