🌬️ AI Front Detection and Segmentation
This repository contains the ONNX (Open Neural Network Exchange) model for FieldDiagnostics within the Visual Weather 10.*+ by IBL.
Attached is a default color gradient to be used to visualize the output categorical map.
🧠 Model Overview
- Purpose: To perform inference on atmospheric fields to identify and categorize atmospheric fronts.
- Architecture:
- The model utilizes a U-Net-style convolutional neural network (CNN) architecture with attention ops.
- Some of the structure and many skeletal parts were inspired by ConvNeXt-V2 and SHViT.
- A custom block utilizing parallel convolutions at different kernel sizes stacked into a depthwise convolution was used to make the network wider and shallower, minimizing the memory footprint.
- Training & Performance:
- The model was trained using atmospheric data from the ERA5 global reanalysis.
- Inference has been tested on multiple Numerical Weather Prediction (NWP) models and generally performs better at coarser scales.
- Training Data:
- Input Fields (Training): Atmospheric data from the ERA5 global reanalysis.
- Target Data (Training): Front analysis data sourced from NOAA Unified Surface Analysis Fronts and front polylines from archive of operational surface analysis from GeoSphere.
📦 Prerequisites
To run inference using this model, you need the onnxruntime Python package. Either install directly or via your venv manager.
ipython -m pip install onnxruntime
Optionally, if AI_DEBUG_LEVEL>1 png output is to be generated, for which you will need to install matplotlib.
ipython -m pip install matplotlib
💾 Model Access and Setup
The pretrained model is available in this repository (model.onnx). It must be saved in the following path:
share/ai/FrontSegmentation/model.onnx
The attached front_gradient.xml contains the default color map/gradient, which can be imported and used on the output field.
🧩 Output Interpretation
The processed output contains a single scalar field with discrete values. Each value represent a category of the front and associated level of probability. The types are split into two levels: low and high probability of the respective front being present.
The categorical map is as follows:
| Index | Boundary Range | Category | Probability | RGBA (CSS) |
|---|---|---|---|---|
| 0 | <0.5 | No Front | N/A | rgba(85, 85, 85, 0.0) |
| 1 | 0.5−1.0 | Warm Front | Low | rgba(209, 17, 17, 0.2) |
| 2 | 1.0−1.5 | Warm Front | High | rgba(209, 17, 17, 0.7) |
| 3 | 1.5−2.0 | Cold Front | Low | rgba(34, 34, 221, 0.2) |
| 4 | 2.0−2.5 | Cold Front | High | rgba(34, 34, 221, 0.7) |
| 5 | 2.5−3.0 | Stationary Front | Low | rgba(18, 69, 28, 0.2) |
| 6 | 3.0−3.5 | Stationary Front | High | rgba(18, 69, 28, 0.7) |
| 7 | 3.5−4.0 | Occluded Front | Low | rgba(176, 34, 176, 0.2) |
| 8 | 4.0−4.5 | Occluded Front | High | rgba(176, 34, 176, 0.7) |
| 9 | 4.5−5.0 | Convergence Line | Low | rgba(230, 179, 26, 0.2) |
| 10 | 5.0−5.5 | Convergence Line | High | rgba(230, 179, 26, 0.7) |
| 11 | 5.5−6.0 | Trough Axis | Low | rgba(26, 26, 26, 0.2) |
| 12 | 6.0−6.5 | Trough Axis | High | rgba(26, 26, 26, 0.7) |
Given the nature of the training data, it is expected to be dominated by Warm, Cold and Occluded fronts with an occasional Through Axis.
Avoid interpolating the output field. It is recommended to use "Decode in original projection" within Visual Weather.
The output can be visually interpreted with various NWP fields as the background. The most straightforward ones to use are e.g. equipotential temperature, relative humidity, and wind at 850-700 hPa.
⚙️ Environment Variables (Optional)
All of them are optional. Each one except AI_FRONT_CONFIG_PATH has a config-file
equivalent that takes precedence — the variable is read only when the matching key
in UNetFrontSegment.json is unset, so these are best used for ad-hoc operator
overrides rather than as the primary configuration.
| Variable | Values | Description | Config key |
|---|---|---|---|
AI_FRONT_CONFIG_PATH | <path> | Configuration file to load (absolute path). Highest precedence of all config locations; otherwise UNetFrontSegment.json is looked up beside the model, then beside the plugin. | — |
AI_DEBUG_LEVEL | 0 | No debug output (default). | debug.level |
1 | Basic info output — config resolution and per-step timings. | ||
2 | Detailed info output, including plotting of results. | ||
AI_FRONT_PNG_PATH | <path> | Debug plot output (default ./ai_front.png; used when AI_DEBUG_LEVEL>=2). | debug.png_path |
AI_FRONT_RAW_PATH | <path> | If set, dumps the raw per-class probability field to this .npz. | debug.raw_path |
AI_FRONT_GEOJSON_PATH | <path> | GeoJSON polyline output when no path is configured (default ./ai_front.geojson). | output.geojson_path / output.path |
AI_FRONT_XML_PATH | <path> | Visual Weather feature-XML polyline output when no path is configured (default ./ai_front.xml). | output.xml_path / output.path |
📚 References
The model was trained using data and concepts derived from the following sources:
- Ronneberger, O., Fischer, P., & Brox, T. (2015). U-Net: Convolutional networks for biomedical image segmentation. Medical Image Computing and Computer-Assisted Intervention (MICCAI). https://doi.org/10.1007/978-3-319-24574-4\_28
- Woo, S., et al. (2023). ConvNeXt V2: Co-designing and scaling ConvNets with masked autoencoders. Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition (CVPR). https://arxiv.org/abs/2301.00808
- Yun, S., & Ro, Y. (2024). SHViT: Single-Head Vision Transformer with memory efficient macro design. Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition (CVPR). https://arxiv.org/abs/2401.16456
- Hersbach, H., et al. (2020). The ERA5 global reanalysis. Quarterly Journal of the Royal Meteorological Society. https://doi.org/10.1002/qj.3803
- NOAA. (2023). NOAA Unified Surface Analysis Fronts (1.0) [Data set]. Zenodo. https://doi.org/10.5281/zenodo.7505022
🔥 Attribution
- GeoSphere, Austria