Metadata-Version: 2.4
Name: sigwx-parser
Version: 1.5.2
Summary: A Python parser for converting WAFS IWXXM SIGWX XML files into GeoJSON, WKT, or WKB feature collections.
Author-email: Miguel Ebersbach <ebersbachmiguel@gmail.com>
Project-URL: Homepage, https://github.com/miguel-pub/sigwx-parser
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: lxml
Requires-Dist: shapely
Requires-Dist: antimeridian

# sigwx-parser

A Python parser for converting WAFS IWXXM SIGWX XML files into GeoJSON, WKT, or WKB feature collections.

SIGWX (Significant Weather) charts are issued by the World Area Forecast System (WAFS) and contain information about meteorological hazards for aviation — things like icing, turbulence, jet streams, and tropical cyclones. This library parses the IWXXM XML format of those files and outputs structured geometry data in your choice of format.

## Installation

```bash
pip install sigwx-parser
```

## Usage

```python
from sigwx_parser import SigwxParser

# From a file
parser = SigwxParser(file_path="sigwx_output.xml")

# From a raw XML string
parser = SigwxParser(file_path=None, xml_content=xml_string)

forecasts = parser.parse()
```

The `output_format` parameter controls the geometry representation. It defaults to `"geojson"`, but `"wkt"` and `"wkb"` are also supported:

```python
forecasts = parser.parse(output_format="geojson")  # default
forecasts = parser.parse(output_format="wkt")
forecasts = parser.parse(output_format="wkb")
```

The top-level key of the feature collection in each result dict matches the chosen format.

---

### GeoJSON output (`output_format="geojson"`)

```python
[
    {
        "valid_time": "2024-02-22T12:00:00Z",
        "issue_time": "2024-02-21T18:00:00Z",
        "geojson": {
            "type": "FeatureCollection",
            "features": [
                {
                    "type": "Feature",
                    "geometry": {
                        "type": "Polygon",
                        "coordinates": [ [ [lon, lat], ... ] ]
                    },
                    "properties": {
                        "feature_id": "uuid.12345...",
                        "phenomenon": "AIRFRAME_ICING",
                        "upper_fl": "240",
                        "lower_fl": "100"
                    }
                }
            ]
        }
    }
]
```

### WKT output (`output_format="wkt"`)

```python
[
    {
        "valid_time": "2024-02-22T12:00:00Z",
        "issue_time": "2024-02-21T18:00:00Z",
        "wkt": {
            "features": [
                {
                    "geometry": "POLYGON ((lon lat, lon lat, ...))",
                    "properties": {
                        "feature_id": "uuid.12345...",
                        "phenomenon": "AIRFRAME_ICING",
                        "upper_fl": "240",
                        "lower_fl": "100"
                    }
                }
            ]
        }
    }
]
```

### WKB output (`output_format="wkb"`)

```python
[
    {
        "valid_time": "2024-02-22T12:00:00Z",
        "issue_time": "2024-02-21T18:00:00Z",
        "wkb": {
            "features": [
                {
                    "geometry": "0103000000...",
                    "properties": {
                        "feature_id": "uuid.12345...",
                        "phenomenon": "AIRFRAME_ICING",
                        "upper_fl": "240",
                        "lower_fl": "100"
                    }
                }
            ]
        }
    }
]
```

WKB geometries are returned as **hex-encoded strings** so they remain JSON-serializable. To get raw bytes for direct database insertion:

```python
raw_bytes = bytes.fromhex(feature["geometry"])
```

Most databases (PostGIS, SpatiaLite, etc.) also accept the hex string directly via their `ST_GeomFromWKB` / `GeomFromWKB` functions, so in practice you often don't need to convert.

---

### Excluding feature types

You can skip specific phenomenon types by passing an `exclude` set to `parse()`:

```python
forecasts = parser.parse(exclude={"CLOUD", "RADIATION"})
```

Valid values for `exclude`:

| Value | Description |
|---|---|
| `AIRFRAME_ICING` | Airframe icing areas |
| `CLOUD` | Significant cloud (e.g. CB, TCU) |
| `JETSTREAM` | Jet stream axes |
| `TROPOPAUSE` | Tropopause height |
| `TURBULENCE` | Turbulence areas |
| `RADIATION` | Radiation hazards |
| `TROPICAL_CYCLONE` | Tropical cyclone positions |
| `VOLCANO` | Volcanic ash areas |

## Notes

- Polygon winding order is corrected automatically using Shapely.
- Geometries that cross the antimeridian are split correctly using the [antimeridian](https://github.com/gadomski/antimeridian) library.
- Namespaces are stripped from the XML before parsing, so the XPath queries stay clean.

## Dependencies

- [lxml](https://lxml.de/)
- [Shapely](https://shapely.readthedocs.io/)
- [antimeridian](https://github.com/gadomski/antimeridian)

## License

MIT

