| --- |
| license: cc-by-4.0 |
| library_name: onnxruntime |
| tags: |
| - mlwp |
| - atmosphere |
| - weather |
| - front |
| pipeline_tag: image-segmentation |
| --- |
| |
| ## 🌬️ 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. |
|
|
| ```bash |
| 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**. |
| ```bash |
| 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** |
|
|
