Metadata-Version: 2.4
Name: mapflow
Version: 0.3.1
Summary: Create geographic plots and animations from xarray DataArrays
Project-URL: Documentation, https://mapflow.readthedocs.io
Project-URL: Homepage, https://github.com/CyrilJl/mapflow
Project-URL: Issues, https://github.com/CyrilJl/mapflow/issues
Project-URL: Source, https://github.com/CyrilJl/mapflow
Author: Cyril Joly
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: animation,geospatial,matplotlib,visualization,xarray
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.10
Requires-Dist: geopandas
Requires-Dist: matplotlib
Requires-Dist: numpy
Requires-Dist: pyproj
Requires-Dist: shapely
Requires-Dist: tqdm
Requires-Dist: xarray
Provides-Extra: docs
Requires-Dist: sphinx>=7; extra == 'docs'
Requires-Dist: sphinxawesome-theme; extra == 'docs'
Requires-Dist: sphinxcontrib-video; extra == 'docs'
Provides-Extra: test
Requires-Dist: netcdf4; extra == 'test'
Requires-Dist: pytest>=8; extra == 'test'
Description-Content-Type: text/markdown

<div align="center">
<img src="https://raw.githubusercontent.com/CyrilJl/mapflow/main/_static/logo.svg" alt="mapflow logo" width="200" height="200">

# mapflow

[![PyPI version](https://badge.fury.io/py/mapflow.svg)](https://pypi.org/project/mapflow/)
[![Conda version](https://anaconda.org/conda-forge/mapflow/badges/version.svg)](https://anaconda.org/conda-forge/mapflow)
[![CI](https://github.com/CyrilJl/mapflow/actions/workflows/CI.yaml/badge.svg)](https://github.com/CyrilJl/mapflow/actions/workflows/CI.yaml)
[![Documentation Status](https://readthedocs.org/projects/mapflow/badge/?version=latest)](https://mapflow.readthedocs.io/en/latest/)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
</div>

`mapflow` creates geographic plots and video animations directly from
[`xarray.DataArray`](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) objects. It detects common
coordinate names, understands CRS metadata, includes world borders, and streams lazily backed animation frames to
keep memory use bounded.

## Installation

Install the Python package from PyPI:

```bash
python -m pip install mapflow
```

Or from conda-forge, which also installs FFmpeg:

```bash
conda install -c conda-forge mapflow
```

Creating animations requires the `ffmpeg` executable on `PATH`. Static plots do not require FFmpeg.

## Quick start

```python
import xarray as xr

from mapflow import animate, plot_da

ds = xr.tutorial.open_dataset("era5-2mt-2019-03-uk.grib")
temperature = ds["t2m"]

plot_da(temperature.isel(time=0))
animate(temperature.isel(time=slice(120)), "temperature.mp4", video_width=1280)
```

<img src="https://raw.githubusercontent.com/CyrilJl/mapflow/main/_static/plot_da.png" alt="Example mapflow plot" width="500">

The [documentation](https://mapflow.readthedocs.io) covers static plots, scalar animations, vector-field quiver
plots, CRS handling, color normalization, and the reusable `PlotModel` and `Animation` classes.

## Development

```bash
git clone https://github.com/CyrilJl/mapflow.git
cd mapflow
uv sync --group dev
uv run pytest
uv run ruff check .
uv run ruff format --check .
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contribution and release checks. Changes are documented in
[CHANGELOG.md](CHANGELOG.md).

## License

Licensed under the [Apache License 2.0](LICENSE).
