Animations

This section provides the API reference for animation functions in mapflow.

Animation

class mapflow.Animation(x, y, crs=4326, verbose=0, borders=None)

A class for creating animations from 3D data with geographic borders.

This class is useful for creating multiple animations of the same geographic domain, as it pre-computes geographic borders.

Parameters:

x (np.ndarray) – Array of x-coordinates (e.g., longitudes).
y (np.ndarray) – Array of y-coordinates (e.g., latitudes).
crs (int | str | CRS, optional) – Coordinate Reference System. Defaults to 4326 (WGS84).
verbose (int, optional) – Verbosity level. If > 0, progress bars will be shown. Defaults to 0.
borders (gpd.GeoDataFrame | gpd.GeoSeries | None, optional) – Custom borders to use for plotting. If None, defaults to world borders. Defaults to None.

import xarray as xr
from mapflow import Animation

ds = xr.tutorial.open_dataset("era5-2mt-2019-03-uk.grib")
da = ds["t2m"].isel(time=slice(120))

animation = Animation(x=da.longitude, y=da.latitude, verbose=1)
animation(da, "animation.mp4")

__call__(data, path, figsize: tuple[float, float] | None = None, title: str | list[str] | tuple[str, ...] | None = None, fps: int | None = None, upsample_ratio: int | None = None, duration: int | None = None, cmap='jet', qmin=0.01, qmax=99.9, vmin=None, vmax=None, norm=None, log=False, diff=False, label=None, dpi=180, pad_inches: float = 0.2, video_width: int | None = None, n_jobs: int | None = None, timeout: int | str = 'auto', crf=20)

Generates an animation from a sequence of 2D data arrays.

The method processes the input data, optionally upsamples it for smoother transitions, generates individual frames in parallel, and then compiles these frames into a video file using FFmpeg.

Parameters:

data (np.ndarray) – A 3D numpy array where the first dimension is time (or frame sequence) and the next two are spatial (y, x).
path (str | Path) – The output path for the generated video file. Supported formats are avi, mkv, mov, and mp4.
figsize (tuple[float, float], optional) – Figure size (width, height) in inches. Defaults to None (matplotlib’s default).
title (str | list[str], optional) – Title for the plot. If a string, it’s used for all frames. If a list, each element corresponds to a frame’s title (before upsampling). Defaults to None.
fps (int, optional) – Frames per second for the output video. Defaults to 24.
upsample_ratio (int, optional) – Factor by which to upsample the data along the time axis for smoother animations. Defaults to 2.
duration (int, optional) – Duration of the video in seconds. Only two of ‘fps’, ‘upsample_ratio’, and ‘duration’ can be provided.
cmap (str, optional) – Colormap to use for the plot. Defaults to “jet”.
qmin (float, optional) – Minimum quantile for color normalization. Defaults to 0.01.
qmax (float, optional) – Maximum quantile for color normalization. Defaults to 99.9.
vmin (float, optional) – Minimum value for color normalization. Overrides qmin.
vmax (float, optional) – Maximum value for color normalization. Overrides qmax.
norm (matplotlib.colors.Normalize, optional) – Custom normalization object.
log (bool, optional) – Whether to use a logarithmic color scale. Defaults to False.
diff (bool, optional) – Whether to use a divergent colormap. Defaults to False.
label (str, optional) – Label for the colorbar. Defaults to None.
dpi (int, optional) – Dots per inch for the saved frames. Defaults to 180.
pad_inches (float, optional) – Padding in inches around the saved frames. Defaults to 0.2.
video_width (int, optional) – Target output video width in pixels.
n_jobs (int, optional) – Number of parallel jobs for frame generation. Defaults to 2/3 of CPU cores.
timeout (int | str, optional) – Timeout for the ffmpeg command in seconds. Defaults to “auto”, which sets the timeout to max(20, 0.1 * data_len).
crf (int, optional) – Constant Rate Factor for video encoding. Lower values mean better quality. Defaults to 20.

QuiverAnimation

class mapflow.QuiverAnimation(x, y, crs=4326, verbose=0, borders=None)

A class for creating quiver animations from 3D data with geographic borders.

quiver(u, v, path, subsample: int = 1, figsize: tuple[float, float] | None = None, title: str | list[str] | tuple[str, ...] | None = None, fps: int = 24, upsample_ratio: int = 2, cmap='jet', qmin=0.01, qmax=99.9, vmin=None, vmax=None, norm=None, log=False, label=None, dpi=180, pad_inches: float = 0.2, video_width: int | None = None, n_jobs: int | None = None, timeout: int | str = 'auto', **kwargs)

Generates a quiver animation from two 3D data arrays.

Parameters:

u (xr.DataArray) – 3D DataArray for the U-component of the vector field.
v (xr.DataArray) – 3D DataArray for the V-component of the vector field.
path (str | Path) – The output path for the generated video file.
subsample (int, optional) – Subsampling factor for quiver arrows. Defaults to 1.
figsize (tuple, optional) – Figure size (width, height) in inches.
title (str | list[str], optional) – Title for the plot.
fps (int, optional) – Frames per second for the output video. Defaults to 24.
upsample_ratio (int, optional) – Factor to upsample data for smoother animation. Defaults to 2.
cmap (str, optional) – Colormap for the plot. Defaults to “jet”.
qmin (float, optional) – Minimum quantile for color normalization. Defaults to 0.01.
qmax (float, optional) – Maximum quantile for color normalization. Defaults to 99.9.
vmin (float, optional) – Minimum value for color normalization.
vmax (float, optional) – Maximum value for color normalization.
norm (matplotlib.colors.Normalize, optional) – Custom normalization object.
log (bool, optional) – Whether to use a logarithmic color scale. Defaults to False.
label (str, optional) – Label for the colorbar.
dpi (int, optional) – Dots per inch for saved frames. Defaults to 180.
pad_inches (float, optional) – Padding in inches around saved frames. Defaults to 0.2.
video_width (int, optional) – Target output video width in pixels.
n_jobs (int, optional) – Number of parallel jobs for frame generation.
timeout (int | str, optional) – Timeout for the ffmpeg command. Defaults to “auto”.
**kwargs – Additional keyword arguments.

animate

Creates an animation from a 3D xarray DataArray (time, y, x).

This function prepares data from an xarray DataArray (e.g., handling geographic coordinates, extracting time information for titles) and then uses the Animation class to generate and save the animation.

Parameters:

da (xr.DataArray) – Input DataArray with time as the animation dimension and x/y spatial dimensions. 2D inputs are not supported.
path (str) – Output path for the video file. Supported formats are avi, mkv, mov, and mp4.
time_name (str, optional) – Name of the time coordinate in da. If None, it’s guessed from [“time”, “t”, “times”]. Defaults to None.
x_name (str, optional) – Name of the x-coordinate (e.g., longitude) in da. If None, it’s guessed from [“x”, “lon”, “longitude”]. Defaults to None.
y_name (str, optional) – Name of the y-coordinate (e.g., latitude) in da. If None, it’s guessed from [“y”, “lat”, “latitude”]. Defaults to None.
crs (int | str | CRS, optional) – Coordinate Reference System of the data. Defaults to 4326 (WGS84).
borders (gpd.GeoDataFrame | gpd.GeoSeries | None, optional) – Custom borders to use for plotting. If None, defaults to world borders. Defaults to None.
verbose (int, optional) – Verbosity level for the Animation class. Defaults to 0.
fps (int, optional) – Frames per second for the output video. Defaults to 24.
upsample_ratio (int, optional) – Factor to upsample data temporally. Defaults to 2.
duration (int, optional) – Duration of the video in seconds. Only two of ‘fps’, ‘upsample_ratio’, and ‘duration’ can be provided.
video_width (int, optional) – Target output video width in pixels.
pad_inches (float, optional) – Padding in inches around saved frames. Defaults to 0.2.
**kwargs – Additional keyword arguments passed to the Animation class, including: - cmap (str, optional): Colormap for the plot. - norm (matplotlib.colors.Normalize, optional): Custom normalization object. - log (bool, optional): Use logarithmic color scale. - diff (bool, optional): Whether to use a divergent colormap. - qmin (float, optional): Minimum quantile for color normalization. - qmax (float, optional): Maximum quantile for color normalization. - vmin (float, optional): Minimum value for color normalization. - vmax (float, optional): Maximum value for color normalization. - time_format (str, optional): Strftime format for time in titles. - n_jobs (int, optional): Number of parallel jobs for frame generation. - dpi (int, optional): Dots per inch for the saved frames. - timeout (str | int, optional): Timeout for video creation. - crf (int, optional): Constant Rate Factor for video encoding. Lower values mean better quality.

import xarray as xr
from mapflow import animate

ds = xr.tutorial.open_dataset("era5-2mt-2019-03-uk.grib")
animate(da=ds['t2m'].isel(time=slice(120)), path='animation.mp4')

See also

Animation: The underlying animation class used by this function.

animate_quiver

mapflow.animate_quiver(u: DataArray, v: DataArray, path: str, time_name: str | None = None, x_name: str | None = None, y_name: str | None = None, crs=None, field_name: str | None = None, borders: GeoDataFrame | GeoSeries | None = None, verbose: int = 0, subsample: int = 1, arrows_kwgs: dict[str, Any] | None = None, video_width: int | None = None, pad_inches: float = 0.2, **kwargs)

Creates a quiver animation from two xarray DataArrays.

Parameters:

u (xr.DataArray) – Input DataArray for the U-component with time as the animation dimension and x/y spatial dimensions. Must be 3D (time, y, x).
v (xr.DataArray) – Input DataArray for the V-component with time as the animation dimension and x/y spatial dimensions. Must be 3D (time, y, x).
path (str) – Output path for the video file. Supported formats are avi, mkv, mov, and mp4.
time_name (str, optional) – Name of the time coordinate in u and v. If None, it’s guessed from [“time”, “t”, “times”]. Defaults to None.
x_name (str, optional) – Name of the x-coordinate (e.g., longitude) in da. If None, it’s guessed from [“x”, “lon”, “longitude”]. Defaults to None.
y_name (str, optional) – Name of the y-coordinate (e.g., latitude) in da. If None, it’s guessed from [“y”, “lat”, “latitude”]. Defaults to None.
crs (int | str | CRS, optional) – Coordinate Reference System of the data. Defaults to 4326 (WGS84).
field_name (str, optional) – Name of the field to be displayed in the title.
borders (gpd.GeoDataFrame | gpd.GeoSeries | None, optional) – Custom borders to use for plotting. If None, defaults to world borders. Defaults to None.
verbose (int, optional) – Verbosity level for the Animation class. Defaults to 0.
subsample (int, optional) – The subsampling factor for the quiver arrows. For example, a value of 10 will plot one arrow for every 10 grid points. Defaults to 1.
arrows_kwgs (dict, optional) – Additional keyword arguments passed to matplotlib.pyplot.quiver. Defaults to None.
video_width (int, optional) – Target output video width in pixels.
pad_inches (float, optional) – Padding in inches around saved frames. Defaults to 0.2.
**kwargs – Additional keyword arguments passed to the QuiverAnimation class, including: - cmap (str, optional): Colormap for the plot. - norm (matplotlib.colors.Normalize, optional): Custom normalization object. - log (bool, optional): Use logarithmic color scale. - qmin (float, optional): Minimum quantile for color normalization. - qmax (float, optional): Maximum quantile for color normalization. - vmin (float, optional): Minimum value for color normalization. - vmax (float, optional): Maximum value for color normalization. - time_format (str, optional): Strftime format for time in titles. - upsample_ratio (int, optional): Factor to upsample data temporally. - fps (int, optional): Frames per second for the video. - n_jobs (int, optional): Number of parallel jobs for frame generation. - dpi (int, optional): Dots per inch for the saved frames. - timeout (str | int, optional): Timeout for video creation.

Example

import xarray as xr
from mapflow import animate_quiver

ds = xr.tutorial.load_dataset("air_temperature_gradient").isel(time=slice(96))
animate_quiver(u=ds["dTdx"], v=ds["dTdy"], path='animation.mkv', subsample=3)