iblsoft/AIFDS

🌬️ 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