zyra.visualization package

class zyra.visualization.AnimateManager(*, mode: str = 'heatmap', basemap: str | None = None, extent: Sequence[float] | None = None, output_dir: str | None = None, filename_template: str = 'frame_{index:04d}.png')

Bases: Renderer

Create PNG frames for time-lapse heatmaps or contours.

Parameters:

• mode (str, default="heatmap") – One of {“heatmap”, “contour”, “vector”}.

• basemap (str, optional) – Background image to draw before data.

• extent (sequence of float, optional) – Geographic extent [west, east, south, north] in PlateCarree.

• output_dir (str, optional) – Directory to write frames and manifest (defaults to working dir if not set).

• filename_template (str, default="frame_{index:04d}.png") – Template for frame filenames.

configure(**kwargs: Any) → None

Configure renderer options.

Parameters:

**kwargs (Any) – Implementation-specific options (e.g., colormap, size, resources).

render(data: Any | None = None, **kwargs: Any)

Render the given data.

Parameters:

• data (Any) – Input data for rendering (e.g., 2D array, colormap spec).

• **kwargs (Any) – Implementation-specific options that influence rendering.

Returns:

A rendered artifact (e.g., Matplotlib figure, colormap objects).

Return type:

Any

save(output_path: str | None = None, *, as_buffer: bool = False)

Save the rendered artifact to a path and return the path if written.

Parameters:

output_path (str, optional) – Destination file path. If omitted, implementations may choose a default path or skip saving.

Returns:

The output path on success, or None if nothing was written.

Return type:

str or None

class zyra.visualization.ColormapManager

Bases: Renderer

Produce colormaps for use in plots.

Visualization Type

• Classified colormap from a list of color/boundary entries.

• Continuous colormap with transparency ramp and optional overall alpha.

Examples

Create a classified colormap and norm:

from zyra.visualization.colormap_manager import ColormapManager

cm = ColormapManager()
data = [
    {"Color": [255, 255, 229, 0], "Upper Bound": 5e-07},
    {"Color": [255, 250, 205, 51], "Upper Bound": 1e-06},
]
cmap, norm = cm.render(data)  # returns (cmap, norm)

Create a continuous colormap:

cmap = cm.render(
    "YlOrBr", transparent_range=2, blend_range=8, overall_alpha=0.8
)

configure(**kwargs)

Configure renderer options.

Parameters:

**kwargs (Any) – Implementation-specific options (e.g., colormap, size, resources).

static create_custom_classified_cmap(colormap_data)

Create a classified colormap and normalizer from colormap data.

Parameters:

colormap_data (list of dict) – Each entry contains a “Color” RGBA list (0–255) and an “Upper Bound”.

Returns:

The classified colormap and its corresponding normalizer.

Return type:

(ListedColormap, BoundaryNorm)

static create_custom_cmap(base_cmap='YlOrBr', transparent_range=1, blend_range=8, overall_alpha=1.0)

Create a continuous colormap with transparency ramp and overall alpha.

Parameters:

• base_cmap (str) – Name of the base colormap.

• transparent_range (int) – Number of entries to set fully transparent at the start.

• blend_range (int) – Number of entries over which alpha ramps to fully opaque.

• overall_alpha (float) – Overall transparency multiplier (0.0–1.0).

Returns:

The customized continuous colormap.

Return type:

matplotlib.colors.LinearSegmentedColormap

render(data, **kwargs)

Render a colormap from classified or continuous specifications.

Parameters:

• data (list or str) –

  • If list of dict entries with keys “Color” and “Upper Bound”, a classified colormap and norm are returned.

  • If str, treat as a base cmap name and return a continuous colormap customized by kwargs.

• transparent_range (int, optional) – Number of entries at the start to set fully transparent (continuous).

• blend_range (int, optional) – Number of entries over which alpha ramps to fully opaque (continuous).

• overall_alpha (float, optional) – Overall transparency multiplier for the colormap (continuous).

Returns:

(cmap, norm) for classified, or a continuous colormap.

Return type:

tuple or matplotlib.colors.LinearSegmentedColormap

save(output_path=None)

Save the rendered artifact to a path and return the path if written.

Parameters:

output_path (str, optional) – Destination file path. If omitted, implementations may choose a default path or skip saving.

Returns:

The output path on success, or None if nothing was written.

Return type:

str or None

class zyra.visualization.ContourManager(*, basemap: str | None = None, extent: Sequence[float] | None = None, cmap: Any = 'YlOrBr', filled: bool = True)

Bases: Renderer

Render contour or filled contours over a basemap.

Parameters:

• basemap (str, optional) – Path to a background image drawn before contours.

• extent (sequence of float, optional) – Geographic extent [west, east, south, north] in PlateCarree.

• cmap (str or Colormap, default=DEFAULT_CMAP) – Colormap used for filled contours.

• filled (bool, default=True) – Whether to draw filled contours (contourf) or lines (contour).

configure(**kwargs: Any) → None

Configure renderer options.

Parameters:

**kwargs (Any) – Implementation-specific options (e.g., colormap, size, resources).

render(data: Any | None = None, **kwargs: Any)

Render the given data.

Parameters:

• data (Any) – Input data for rendering (e.g., 2D array, colormap spec).

• **kwargs (Any) – Implementation-specific options that influence rendering.

Returns:

A rendered artifact (e.g., Matplotlib figure, colormap objects).

Return type:

Any

save(output_path: str | None = None, *, as_buffer: bool = False)

Save the rendered artifact to a path and return the path if written.

Parameters:

output_path (str, optional) – Destination file path. If omitted, implementations may choose a default path or skip saving.

Returns:

The output path on success, or None if nothing was written.

Return type:

str or None

class zyra.visualization.HeatmapManager(*, basemap: str | None = None, extent: Sequence[float] | None = None, cmap: Any = 'YlOrBr')

Bases: Renderer

Render a 2D array as a heatmap over an optional basemap.

Parameters:

• basemap (str, optional) – Path to a background image drawn before the heatmap.

• extent (sequence of float, optional) – Geographic extent [west, east, south, north] in PlateCarree.

• cmap (str or Colormap, default=DEFAULT_CMAP) – Colormap to use.

configure(**kwargs: Any) → None

Configure renderer options.

Parameters:

**kwargs (Any) – Implementation-specific options (e.g., colormap, size, resources).

render(data: Any | None = None, **kwargs: Any)

Render the given data.

Parameters:

• data (Any) – Input data for rendering (e.g., 2D array, colormap spec).

• **kwargs (Any) – Implementation-specific options that influence rendering.

Returns:

A rendered artifact (e.g., Matplotlib figure, colormap objects).

Return type:

Any

save(output_path: str | None = None, *, as_buffer: bool = False)

Save the rendered artifact to a path and return the path if written.

Parameters:

output_path (str, optional) – Destination file path. If omitted, implementations may choose a default path or skip saving.

Returns:

The output path on success, or None if nothing was written.

Return type:

str or None

class zyra.visualization.InteractiveManager(*, engine: str = 'folium', extent: Sequence[float] | None = None, cmap: str = 'YlOrBr')

Bases: Renderer

configure(**kwargs: Any) → None

Configure renderer options.

Parameters:

**kwargs (Any) – Implementation-specific options (e.g., colormap, size, resources).

render(data: Any | None = None, **kwargs: Any) → Any

Render the given data.

Parameters:

• data (Any) – Input data for rendering (e.g., 2D array, colormap spec).

• **kwargs (Any) – Implementation-specific options that influence rendering.

Returns:

A rendered artifact (e.g., Matplotlib figure, colormap objects).

Return type:

Any

save(output_path: str | None = None, *, as_buffer: bool = False) → str | None

Save the rendered artifact to a path and return the path if written.

Parameters:

output_path (str, optional) – Destination file path. If omitted, implementations may choose a default path or skip saving.

Returns:

The output path on success, or None if nothing was written.

Return type:

str or None

class zyra.visualization.PlotManager(basemap=None, overlay=None, image_extent=None, base_cmap='YlOrBr')

Bases: Renderer

Render 2D data arrays over basemap images using Cartopy + Matplotlib.

Visualization Type

• Basemap overlay (JPEG/PNG) with a 2D data array on top.

param basemap:

Path to a basemap image.

type basemap:

str, optional

param overlay:

Path to an optional overlay image applied before drawing data.

type overlay:

str, optional

param image_extent:

Geographic extent of the basemap in PlateCarree (west, east, south, north).

type image_extent:

list or tuple, optional

param base_cmap:

Default colormap name used when a custom cmap is not provided.

type base_cmap:

str, default=”YlOrBr”

Examples

Minimal usage:

pm = PlotManager(basemap="/path/to/basemap.jpg")
pm.configure(image_extent=[-180, 180, -90, 90])
fig = pm.render(data)
pm.save("./plot.png")

configure(**kwargs)

Update configuration (basemap, overlay, extent, base colormap).

Parameters:

• basemap (str, optional) – Path to basemap image.

• overlay (str, optional) – Path to overlay image.

• image_extent (list or tuple, optional) – Geographic extent in PlateCarree (west, east, south, north).

• base_cmap (str, optional) – Default colormap name.

static plot_data_array(data_oc, custom_cmap, norm, basemap_path, overlay_path=None, date_str=None, image_extent=None, output_path='plot.png', border_color='#333333CC', coastline_color='#333333CC', linewidth=2)

Static convenience for plotting using a one-off figure.

Parameters:

• data_oc (numpy.ndarray) – Data array to plot (masked NaNs are handled).

• custom_cmap (Any) – Colormap for the data layer.

• norm (Any) – Normalization for colormap values.

• basemap_path (str) – Path to the basemap image file.

• overlay_path (str, optional) – Path to an overlay image (currently unused).

• date_str (str, optional) – Optional label for time annotation (currently unused).

• image_extent (list or tuple, optional) – Geographic extent in PlateCarree (west, east, south, north).

• output_path (str, default="plot.png") – Destination file path.

• border_color (str, optional) – Colors for borders and coastlines.

• coastline_color (str, optional) – Colors for borders and coastlines.

• linewidth (float, default=2) – Line width for borders/coastlines.

render(data, **kwargs)

Plot a single 2D array on the configured basemap.

Parameters:

• data (numpy.ndarray) – 2D array to plot.

• custom_cmap (Any, optional) – Colormap or name used for drawing the data layer.

• norm (Any, optional) – Normalizer for the colormap.

• vmin (float, optional) – Data range limits for colormap mapping.

• vmax (float, optional) – Data range limits for colormap mapping.

• flip_data (bool, default=False) – If True, flip the array vertically before drawing.

• width (int, optional) – Output figure width and height in pixels (defaults 4096x2048).

• height (int, optional) – Output figure width and height in pixels (defaults 4096x2048).

• dpi (int, default=96) – Dots per inch for rendering.

• border_color (str, optional) – Colors for borders and coastlines.

• coastline_color (str, optional) – Colors for borders and coastlines.

• linewidth (float, optional) – Line width for borders/coastlines.

Returns:

The created figure, or None on error.

Return type:

matplotlib.figure.Figure or None

save(output_path=None)

Save the most recently rendered figure to disk.

Parameters:

output_path (str, optional) – Destination path. Defaults to "plot.png".

Returns:

Output path on success; None if nothing to save.

Return type:

str or None

sos_plot_data(data, custom_cmap, output_path='plot.png', width=4096, height=2048, dpi=96, flip_data=False, border_color=None, coastline_color=None, linewidth=None, vmin=None, vmax=None)

Compatibility wrapper that calls render() then save().

Returns:

The output path on success; None if rendering failed.

Return type:

str or None

class zyra.visualization.Renderer

Bases: ABC

Abstract base for visualization components in the Zyra pipeline.

A renderer is the visualization stage that takes processed data from the processing layer and produces a visual artifact (e.g., a figure, image, or colormap). This base class standardizes three phases:

• configure(**kwargs): set renderer options/resources

• render(data, **kwargs): draw or produce a visual artifact from data

• save(output_path=None): persist the rendered artifact

Parameters:

... – Concrete renderers define their own constructor parameters (e.g., basemap, overlays, figure size, or colormap options).

Examples

Typical usage pattern:

from zyra.visualization.plot_manager import PlotManager

renderer = PlotManager(basemap="/path/to/basemap.jpg")
renderer.configure(image_extent=[-180, 180, -90, 90])
fig = renderer.render(data_array)
renderer.save("./output.png")

abstract configure(**kwargs: Any) → None

Configure renderer options.

Parameters:

**kwargs (Any) – Implementation-specific options (e.g., colormap, size, resources).

abstract render(data: Any, **kwargs: Any) → Any

Render the given data.

Parameters:

• data (Any) – Input data for rendering (e.g., 2D array, colormap spec).

• **kwargs (Any) – Implementation-specific options that influence rendering.

Returns:

A rendered artifact (e.g., Matplotlib figure, colormap objects).

Return type:

Any

abstract save(output_path: str | None = None) → str | None

Save the rendered artifact to a path and return the path if written.

Parameters:

output_path (str, optional) – Destination file path. If omitted, implementations may choose a default path or skip saving.

Returns:

The output path on success, or None if nothing was written.

Return type:

str or None

class zyra.visualization.TimeSeriesManager(*, title: str | None = None, xlabel: str | None = None, ylabel: str | None = None, style: str = 'line')

Bases: Renderer

Render a time series chart from CSV or NetCDF inputs.

Parameters:

• title (str, optional) – Figure title.

• xlabel (str, optional) – Axis labels.

• ylabel (str, optional) – Axis labels.

• style (str, default="line") – One of {“line”, “marker”, “line_marker”}.

configure(**kwargs: Any) → None

Configure renderer options.

Parameters:

**kwargs (Any) – Implementation-specific options (e.g., colormap, size, resources).

render(data: Any | None = None, **kwargs: Any)

Render the given data.

Parameters:

• data (Any) – Input data for rendering (e.g., 2D array, colormap spec).

• **kwargs (Any) – Implementation-specific options that influence rendering.

Returns:

A rendered artifact (e.g., Matplotlib figure, colormap objects).

Return type:

Any

save(output_path: str | None = None, *, as_buffer: bool = False)

Save the rendered artifact to a path and return the path if written.

Parameters:

output_path (str, optional) – Destination file path. If omitted, implementations may choose a default path or skip saving.

Returns:

The output path on success, or None if nothing was written.

Return type:

str or None

class zyra.visualization.VectorFieldManager(*, basemap: str | None = None, extent: Sequence[float] | None = None, color: str = '#333333', density: float = 0.2, scale: float | None = None, streamlines: bool = False)

Bases: Renderer

Render vector fields (U/V) as arrows over a basemap.

Parameters:

• basemap (str, optional) – Path to a background image drawn before quivers.

• extent (sequence of float, optional) – Geographic extent [west, east, south, north] in PlateCarree.

• color (str, default="#333333") – Arrow color.

• density (float, default=0.2) – Sampling density in (0, 1]; lower values draw fewer arrows.

• scale (float, optional) – Quiver scale parameter controlling arrow length relative to data.

configure(**kwargs: Any) → None

Configure renderer options.

Parameters:

**kwargs (Any) – Implementation-specific options (e.g., colormap, size, resources).

render(data: Any | None = None, **kwargs: Any)

Render the given data.

Parameters:

• data (Any) – Input data for rendering (e.g., 2D array, colormap spec).

• **kwargs (Any) – Implementation-specific options that influence rendering.

Returns:

A rendered artifact (e.g., Matplotlib figure, colormap objects).

Return type:

Any

save(output_path: str | None = None, *, as_buffer: bool = False)

Save the rendered artifact to a path and return the path if written.

Parameters:

output_path (str, optional) – Destination file path. If omitted, implementations may choose a default path or skip saving.

Returns:

The output path on success, or None if nothing was written.

Return type:

str or None

class zyra.visualization.VectorParticlesManager(*, basemap: str | None = None, extent: Sequence[float] | None = None, color: str = '#333333', size: float = 0.5, method: str = 'euler')

Bases: Renderer

configure(**kwargs: Any) → None

Configure renderer options.

Parameters:

**kwargs (Any) – Implementation-specific options (e.g., colormap, size, resources).

render(data: Any | None = None, **kwargs: Any)

Render the given data.

Parameters:

• data (Any) – Input data for rendering (e.g., 2D array, colormap spec).

• **kwargs (Any) – Implementation-specific options that influence rendering.

Returns:

A rendered artifact (e.g., Matplotlib figure, colormap objects).

Return type:

Any

save(output_path: str | None = None, *, as_buffer: bool = False)

Save the rendered artifact to a path and return the path if written.

Parameters:

output_path (str, optional) – Destination file path. If omitted, implementations may choose a default path or skip saving.

Returns:

The output path on success, or None if nothing was written.

Return type:

str or None

zyra.visualization.add_basemap_cartopy(ax, extent: Iterable[float] | None = None, *, image_path: str | None = None, image_extent: Iterable[float] | None = None, features: Iterable[str] | None = None, alpha: float = 1.0)

Add a simple basemap to a Cartopy axis.

Parameters:

• ax (cartopy.mpl.geoaxes.GeoAxesSubplot) – Target axes with a geographic projection (PlateCarree recommended).

• extent (iterable of float, optional) – The viewport: [west, east, south, north] in PlateCarree coordinates, passed to ax.set_extent.

• image_path (str, optional) – Path to a background image to draw via imshow.

• image_extent (iterable of float, optional) –

  The geographic extent the image itself covers, defaulting to the whole globe — which is what every basemap shipped in zyra.assets.images is (equirectangular, 2:1).

  This is deliberately not extent. Reusing the viewport here stretched a global image into whatever region was being viewed, so a North America viewport rendered the entire world squashed into that box (#284). Cartopy crops the image to the viewport on its own once the image is placed at its true extent.

• features (iterable of str, optional) – Feature names to add: any of {“coastline”, “borders”, “gridlines”}.

• alpha (float, default=1.0) – Opacity for the background image.

zyra.visualization.add_basemap_tile(ax, extent: Iterable[float] | None = None, *, tile_source: str | None = None, zoom: int = 3)

Add a tile basemap using contextily, if available.

Notes

• This is a best-effort helper. If contextily is not installed or tiles cannot be fetched (e.g., no network), the function returns without raising.

• The axis is expected to use PlateCarree.

zyra.visualization.apply_matplotlib_style()

Apply minimal Matplotlib rcParams for consistent styling.

Safe to call multiple times. Only sets a handful of parameters to avoid surprising downstream consumers.

Core modules

class zyra.visualization.base.Renderer

Bases: ABC

Abstract base for visualization components in the Zyra pipeline.

A renderer is the visualization stage that takes processed data from the processing layer and produces a visual artifact (e.g., a figure, image, or colormap). This base class standardizes three phases:

• configure(**kwargs): set renderer options/resources

• render(data, **kwargs): draw or produce a visual artifact from data

• save(output_path=None): persist the rendered artifact

Parameters:

... – Concrete renderers define their own constructor parameters (e.g., basemap, overlays, figure size, or colormap options).

Examples

Typical usage pattern:

from zyra.visualization.plot_manager import PlotManager

renderer = PlotManager(basemap="/path/to/basemap.jpg")
renderer.configure(image_extent=[-180, 180, -90, 90])
fig = renderer.render(data_array)
renderer.save("./output.png")

abstract configure(**kwargs: Any) → None

Configure renderer options.

Parameters:

**kwargs (Any) – Implementation-specific options (e.g., colormap, size, resources).

abstract render(data: Any, **kwargs: Any) → Any

Render the given data.

Parameters:

• data (Any) – Input data for rendering (e.g., 2D array, colormap spec).

• **kwargs (Any) – Implementation-specific options that influence rendering.

Returns:

A rendered artifact (e.g., Matplotlib figure, colormap objects).

Return type:

Any

abstract save(output_path: str | None = None) → str | None

Save the rendered artifact to a path and return the path if written.

Parameters:

output_path (str, optional) – Destination file path. If omitted, implementations may choose a default path or skip saving.

Returns:

The output path on success, or None if nothing was written.

Return type:

str or None

Plot 2D arrays over basemaps using Cartopy + Matplotlib.

This module exposes PlotManager, a renderer that composes a basemap image and a 2D data array into a final plot. It supports optional coastlines, borders, custom colormaps, and saving to file.

class zyra.visualization.plot_manager.PlotManager(basemap=None, overlay=None, image_extent=None, base_cmap='YlOrBr')

Bases: Renderer

Render 2D data arrays over basemap images using Cartopy + Matplotlib.

Visualization Type

• Basemap overlay (JPEG/PNG) with a 2D data array on top.

param basemap:

Path to a basemap image.

type basemap:

str, optional

param overlay:

Path to an optional overlay image applied before drawing data.

type overlay:

str, optional

param image_extent:

Geographic extent of the basemap in PlateCarree (west, east, south, north).

type image_extent:

list or tuple, optional

param base_cmap:

Default colormap name used when a custom cmap is not provided.

type base_cmap:

str, default=”YlOrBr”

Examples

Minimal usage:

pm = PlotManager(basemap="/path/to/basemap.jpg")
pm.configure(image_extent=[-180, 180, -90, 90])
fig = pm.render(data)
pm.save("./plot.png")

configure(**kwargs)

Update configuration (basemap, overlay, extent, base colormap).

Parameters:

• basemap (str, optional) – Path to basemap image.

• overlay (str, optional) – Path to overlay image.

• image_extent (list or tuple, optional) – Geographic extent in PlateCarree (west, east, south, north).

• base_cmap (str, optional) – Default colormap name.

static plot_data_array(data_oc, custom_cmap, norm, basemap_path, overlay_path=None, date_str=None, image_extent=None, output_path='plot.png', border_color='#333333CC', coastline_color='#333333CC', linewidth=2)

Static convenience for plotting using a one-off figure.

Parameters:

• data_oc (numpy.ndarray) – Data array to plot (masked NaNs are handled).

• custom_cmap (Any) – Colormap for the data layer.

• norm (Any) – Normalization for colormap values.

• basemap_path (str) – Path to the basemap image file.

• overlay_path (str, optional) – Path to an overlay image (currently unused).

• date_str (str, optional) – Optional label for time annotation (currently unused).

• image_extent (list or tuple, optional) – Geographic extent in PlateCarree (west, east, south, north).

• output_path (str, default="plot.png") – Destination file path.

• border_color (str, optional) – Colors for borders and coastlines.

• coastline_color (str, optional) – Colors for borders and coastlines.

• linewidth (float, default=2) – Line width for borders/coastlines.

render(data, **kwargs)

Plot a single 2D array on the configured basemap.

Parameters:

• data (numpy.ndarray) – 2D array to plot.

• custom_cmap (Any, optional) – Colormap or name used for drawing the data layer.

• norm (Any, optional) – Normalizer for the colormap.

• vmin (float, optional) – Data range limits for colormap mapping.

• vmax (float, optional) – Data range limits for colormap mapping.

• flip_data (bool, default=False) – If True, flip the array vertically before drawing.

• width (int, optional) – Output figure width and height in pixels (defaults 4096x2048).

• height (int, optional) – Output figure width and height in pixels (defaults 4096x2048).

• dpi (int, default=96) – Dots per inch for rendering.

• border_color (str, optional) – Colors for borders and coastlines.

• coastline_color (str, optional) – Colors for borders and coastlines.

• linewidth (float, optional) – Line width for borders/coastlines.

Returns:

The created figure, or None on error.

Return type:

matplotlib.figure.Figure or None

save(output_path=None)

Save the most recently rendered figure to disk.

Parameters:

output_path (str, optional) – Destination path. Defaults to "plot.png".

Returns:

Output path on success; None if nothing to save.

Return type:

str or None

sos_plot_data(data, custom_cmap, output_path='plot.png', width=4096, height=2048, dpi=96, flip_data=False, border_color=None, coastline_color=None, linewidth=None, vmin=None, vmax=None)

Compatibility wrapper that calls render() then save().

Returns:

The output path on success; None if rendering failed.

Return type:

str or None

Colormap utilities for classified and continuous rendering.

This module exposes ColormapManager, a lightweight renderer that produces colormap objects (e.g., matplotlib.colors.ListedColormap, and a matching matplotlib.colors.BoundaryNorm for classified data).

class zyra.visualization.colormap_manager.ColormapManager

Bases: Renderer

Produce colormaps for use in plots.

Visualization Type

• Classified colormap from a list of color/boundary entries.

• Continuous colormap with transparency ramp and optional overall alpha.

Examples

Create a classified colormap and norm:

from zyra.visualization.colormap_manager import ColormapManager

cm = ColormapManager()
data = [
    {"Color": [255, 255, 229, 0], "Upper Bound": 5e-07},
    {"Color": [255, 250, 205, 51], "Upper Bound": 1e-06},
]
cmap, norm = cm.render(data)  # returns (cmap, norm)

Create a continuous colormap:

cmap = cm.render(
    "YlOrBr", transparent_range=2, blend_range=8, overall_alpha=0.8
)

configure(**kwargs)

Configure renderer options.

Parameters:

**kwargs (Any) – Implementation-specific options (e.g., colormap, size, resources).

static create_custom_classified_cmap(colormap_data)

Create a classified colormap and normalizer from colormap data.

Parameters:

colormap_data (list of dict) – Each entry contains a “Color” RGBA list (0–255) and an “Upper Bound”.

Returns:

The classified colormap and its corresponding normalizer.

Return type:

(ListedColormap, BoundaryNorm)

static create_custom_cmap(base_cmap='YlOrBr', transparent_range=1, blend_range=8, overall_alpha=1.0)

Create a continuous colormap with transparency ramp and overall alpha.

Parameters:

• base_cmap (str) – Name of the base colormap.

• transparent_range (int) – Number of entries to set fully transparent at the start.

• blend_range (int) – Number of entries over which alpha ramps to fully opaque.

• overall_alpha (float) – Overall transparency multiplier (0.0–1.0).

Returns:

The customized continuous colormap.

Return type:

matplotlib.colors.LinearSegmentedColormap

render(data, **kwargs)

Render a colormap from classified or continuous specifications.

Parameters:

• data (list or str) –

  • If list of dict entries with keys “Color” and “Upper Bound”, a classified colormap and norm are returned.

  • If str, treat as a base cmap name and return a continuous colormap customized by kwargs.

• transparent_range (int, optional) – Number of entries at the start to set fully transparent (continuous).

• blend_range (int, optional) – Number of entries over which alpha ramps to fully opaque (continuous).

• overall_alpha (float, optional) – Overall transparency multiplier for the colormap (continuous).

Returns:

(cmap, norm) for classified, or a continuous colormap.

Return type:

tuple or matplotlib.colors.LinearSegmentedColormap

save(output_path=None)

Save the rendered artifact to a path and return the path if written.

Parameters:

output_path (str, optional) – Destination file path. If omitted, implementations may choose a default path or skip saving.

Returns:

The output path on success, or None if nothing was written.

Return type:

str or None

Basemap helpers for Cartopy/Matplotlib renderers.

Functions here are intentionally lightweight and avoid hard dependencies on optional tile providers. Tile support is stubbed and only enabled if the dependency is available at runtime.

zyra.visualization.basemap.add_basemap_cartopy(ax, extent: Iterable[float] | None = None, *, image_path: str | None = None, image_extent: Iterable[float] | None = None, features: Iterable[str] | None = None, alpha: float = 1.0)

Add a simple basemap to a Cartopy axis.

Parameters:

• ax (cartopy.mpl.geoaxes.GeoAxesSubplot) – Target axes with a geographic projection (PlateCarree recommended).

• extent (iterable of float, optional) – The viewport: [west, east, south, north] in PlateCarree coordinates, passed to ax.set_extent.

• image_path (str, optional) – Path to a background image to draw via imshow.

• image_extent (iterable of float, optional) –

  The geographic extent the image itself covers, defaulting to the whole globe — which is what every basemap shipped in zyra.assets.images is (equirectangular, 2:1).

  This is deliberately not extent. Reusing the viewport here stretched a global image into whatever region was being viewed, so a North America viewport rendered the entire world squashed into that box (#284). Cartopy crops the image to the viewport on its own once the image is placed at its true extent.

• features (iterable of str, optional) – Feature names to add: any of {“coastline”, “borders”, “gridlines”}.

• alpha (float, default=1.0) – Opacity for the background image.

zyra.visualization.basemap.add_basemap_tile(ax, extent: Iterable[float] | None = None, *, tile_source: str | None = None, zoom: int = 3)

Add a tile basemap using contextily, if available.

Notes

• This is a best-effort helper. If contextily is not installed or tiles cannot be fetched (e.g., no network), the function returns without raising.

• The axis is expected to use PlateCarree.

Managers

Render 2D heatmaps with optional basemap using Cartopy + Matplotlib.

class zyra.visualization.heatmap_manager.HeatmapManager(*, basemap: str | None = None, extent: Sequence[float] | None = None, cmap: Any = 'YlOrBr')

Bases: Renderer

Render a 2D array as a heatmap over an optional basemap.

Parameters:

• basemap (str, optional) – Path to a background image drawn before the heatmap.

• extent (sequence of float, optional) – Geographic extent [west, east, south, north] in PlateCarree.

• cmap (str or Colormap, default=DEFAULT_CMAP) – Colormap to use.

configure(**kwargs: Any) → None

Configure renderer options.

Parameters:

**kwargs (Any) – Implementation-specific options (e.g., colormap, size, resources).

render(data: Any | None = None, **kwargs: Any)

Render the given data.

Parameters:

• data (Any) – Input data for rendering (e.g., 2D array, colormap spec).

• **kwargs (Any) – Implementation-specific options that influence rendering.

Returns:

A rendered artifact (e.g., Matplotlib figure, colormap objects).

Return type:

Any

save(output_path: str | None = None, *, as_buffer: bool = False)

Save the rendered artifact to a path and return the path if written.

Parameters:

output_path (str, optional) – Destination file path. If omitted, implementations may choose a default path or skip saving.

Returns:

The output path on success, or None if nothing was written.

Return type:

str or None

Render contour or filled contour plots with optional basemap.

class zyra.visualization.contour_manager.ContourManager(*, basemap: str | None = None, extent: Sequence[float] | None = None, cmap: Any = 'YlOrBr', filled: bool = True)

Bases: Renderer

Render contour or filled contours over a basemap.

Parameters:

• basemap (str, optional) – Path to a background image drawn before contours.

• extent (sequence of float, optional) – Geographic extent [west, east, south, north] in PlateCarree.

• cmap (str or Colormap, default=DEFAULT_CMAP) – Colormap used for filled contours.

• filled (bool, default=True) – Whether to draw filled contours (contourf) or lines (contour).

configure(**kwargs: Any) → None

Configure renderer options.

Parameters:

**kwargs (Any) – Implementation-specific options (e.g., colormap, size, resources).

render(data: Any | None = None, **kwargs: Any)

Render the given data.

Parameters:

• data (Any) – Input data for rendering (e.g., 2D array, colormap spec).

• **kwargs (Any) – Implementation-specific options that influence rendering.

Returns:

A rendered artifact (e.g., Matplotlib figure, colormap objects).

Return type:

Any

save(output_path: str | None = None, *, as_buffer: bool = False)

Save the rendered artifact to a path and return the path if written.

Parameters:

output_path (str, optional) – Destination file path. If omitted, implementations may choose a default path or skip saving.

Returns:

The output path on success, or None if nothing was written.

Return type:

str or None

Render 2D vector fields (U/V) as quivers over an optional basemap.

Use for winds, ocean currents, or any horizontal vector field on a lon/lat grid.

class zyra.visualization.vector_field_manager.VectorFieldManager(*, basemap: str | None = None, extent: Sequence[float] | None = None, color: str = '#333333', density: float = 0.2, scale: float | None = None, streamlines: bool = False)

Bases: Renderer

Render vector fields (U/V) as arrows over a basemap.

Parameters:

• basemap (str, optional) – Path to a background image drawn before quivers.

• extent (sequence of float, optional) – Geographic extent [west, east, south, north] in PlateCarree.

• color (str, default="#333333") – Arrow color.

• density (float, default=0.2) – Sampling density in (0, 1]; lower values draw fewer arrows.

• scale (float, optional) – Quiver scale parameter controlling arrow length relative to data.

configure(**kwargs: Any) → None

Configure renderer options.

Parameters:

**kwargs (Any) – Implementation-specific options (e.g., colormap, size, resources).

render(data: Any | None = None, **kwargs: Any)

Render the given data.

Parameters:

• data (Any) – Input data for rendering (e.g., 2D array, colormap spec).

• **kwargs (Any) – Implementation-specific options that influence rendering.

Returns:

A rendered artifact (e.g., Matplotlib figure, colormap objects).

Return type:

Any

save(output_path: str | None = None, *, as_buffer: bool = False)

Save the rendered artifact to a path and return the path if written.

Parameters:

output_path (str, optional) – Destination file path. If omitted, implementations may choose a default path or skip saving.

Returns:

The output path on success, or None if nothing was written.

Return type:

str or None

Render particle advection frames over a vector field (U/V).

Supports NetCDF (time, lat, lon) variables or 3D NumPy stacks. Particles are seeded on a grid, at random, or from a CSV and advected using Euler or RK2.

class zyra.visualization.vector_particles_manager.ParticleFrame(index: 'int', path: 'str')

Bases: object

index: int

path: str

class zyra.visualization.vector_particles_manager.VectorParticlesManager(*, basemap: str | None = None, extent: Sequence[float] | None = None, color: str = '#333333', size: float = 0.5, method: str = 'euler')

Bases: Renderer

configure(**kwargs: Any) → None

Configure renderer options.

Parameters:

**kwargs (Any) – Implementation-specific options (e.g., colormap, size, resources).

render(data: Any | None = None, **kwargs: Any)

Render the given data.

Parameters:

• data (Any) – Input data for rendering (e.g., 2D array, colormap spec).

• **kwargs (Any) – Implementation-specific options that influence rendering.

Returns:

A rendered artifact (e.g., Matplotlib figure, colormap objects).

Return type:

Any

save(output_path: str | None = None, *, as_buffer: bool = False)

Save the rendered artifact to a path and return the path if written.

Parameters:

output_path (str, optional) – Destination file path. If omitted, implementations may choose a default path or skip saving.

Returns:

The output path on success, or None if nothing was written.

Return type:

str or None

Render time series from CSV or NetCDF as simple line charts.

class zyra.visualization.timeseries_manager.TimeSeriesManager(*, title: str | None = None, xlabel: str | None = None, ylabel: str | None = None, style: str = 'line')

Bases: Renderer

Render a time series chart from CSV or NetCDF inputs.

Parameters:

• title (str, optional) – Figure title.

• xlabel (str, optional) – Axis labels.

• ylabel (str, optional) – Axis labels.

• style (str, default="line") – One of {“line”, “marker”, “line_marker”}.

configure(**kwargs: Any) → None

Configure renderer options.

Parameters:

**kwargs (Any) – Implementation-specific options (e.g., colormap, size, resources).

render(data: Any | None = None, **kwargs: Any)

Render the given data.

Parameters:

• data (Any) – Input data for rendering (e.g., 2D array, colormap spec).

• **kwargs (Any) – Implementation-specific options that influence rendering.

Returns:

A rendered artifact (e.g., Matplotlib figure, colormap objects).

Return type:

Any

save(output_path: str | None = None, *, as_buffer: bool = False)

Save the rendered artifact to a path and return the path if written.

Parameters:

output_path (str, optional) – Destination file path. If omitted, implementations may choose a default path or skip saving.

Returns:

The output path on success, or None if nothing was written.

Return type:

str or None

Generate animation frames (PNG sequence) for heatmap/contour modes.

This manager writes a numbered frame sequence and a small JSON manifest. It does not invoke FFmpeg; composing video is left to downstream tools.

class zyra.visualization.animate_manager.AnimateManager(*, mode: str = 'heatmap', basemap: str | None = None, extent: Sequence[float] | None = None, output_dir: str | None = None, filename_template: str = 'frame_{index:04d}.png')

Bases: Renderer

Create PNG frames for time-lapse heatmaps or contours.

Parameters:

• mode (str, default="heatmap") – One of {“heatmap”, “contour”, “vector”}.

• basemap (str, optional) – Background image to draw before data.

• extent (sequence of float, optional) – Geographic extent [west, east, south, north] in PlateCarree.

• output_dir (str, optional) – Directory to write frames and manifest (defaults to working dir if not set).

• filename_template (str, default="frame_{index:04d}.png") – Template for frame filenames.

configure(**kwargs: Any) → None

Configure renderer options.

Parameters:

**kwargs (Any) – Implementation-specific options (e.g., colormap, size, resources).

render(data: Any | None = None, **kwargs: Any)

Render the given data.

Parameters:

• data (Any) – Input data for rendering (e.g., 2D array, colormap spec).

• **kwargs (Any) – Implementation-specific options that influence rendering.

Returns:

A rendered artifact (e.g., Matplotlib figure, colormap objects).

Return type:

Any

save(output_path: str | None = None, *, as_buffer: bool = False)

Save the rendered artifact to a path and return the path if written.

Parameters:

output_path (str, optional) – Destination file path. If omitted, implementations may choose a default path or skip saving.

Returns:

The output path on success, or None if nothing was written.

Return type:

str or None

class zyra.visualization.animate_manager.FrameInfo(index: 'int', path: 'str', timestamp: 'str | None' = None)

Bases: object

index: int

path: str

timestamp: str | None = None

Interactive visualizations using Folium or Plotly.

This manager produces a standalone HTML document containing an interactive map or figure. It supports lightweight overlays for gridded heatmaps/contours and point layers from CSV. Optional engines are imported lazily.

class zyra.visualization.interactive_manager.InteractiveManager(*, engine: str = 'folium', extent: Sequence[float] | None = None, cmap: str = 'YlOrBr')

Bases: Renderer

configure(**kwargs: Any) → None

Configure renderer options.

Parameters:

**kwargs (Any) – Implementation-specific options (e.g., colormap, size, resources).

render(data: Any | None = None, **kwargs: Any) → Any

Render the given data.

Parameters:

• data (Any) – Input data for rendering (e.g., 2D array, colormap spec).

• **kwargs (Any) – Implementation-specific options that influence rendering.

Returns:

A rendered artifact (e.g., Matplotlib figure, colormap objects).

Return type:

Any

save(output_path: str | None = None, *, as_buffer: bool = False) → str | None

Save the rendered artifact to a path and return the path if written.

Parameters:

output_path (str, optional) – Destination file path. If omitted, implementations may choose a default path or skip saving.

Returns:

The output path on success, or None if nothing was written.

Return type:

str or None

Styles and CLI

Centralized visualization styles and defaults.

These values are intentionally conservative and can be overridden via Renderer.configure or function parameters.

zyra.visualization.styles.apply_matplotlib_style()

Apply minimal Matplotlib rcParams for consistent styling.

Safe to call multiple times. Only sets a handful of parameters to avoid surprising downstream consumers.

zyra.visualization.styles.apply_view_extent(ax, extent) → None

Crop a GeoAxes view to extent; keep the global view for the default.

extent is [west, east, south, north] in PlateCarree degrees. Regional extents previously rendered as a small stamp on a world map because the managers hardcoded ax.set_global() — for regional products (e.g. HRRR) that wastes almost the whole frame.

zyra.visualization.styles.timestamp_anchor(loc: str)

Map a location keyword to axes-relative position and alignment.

Returns (x, y, ha, va).

Compatibility wrapper delegating to the root CLI.

This module remains importable for now to avoid breaking existing docs/tests. It forwards all arguments to zyra.cli.

zyra.visualization.cli.main(argv: list[str] | None = None) → int

zyra.visualization.cli_utils.cmap_norm_from_palette(spec: dict)

Build (cmap, norm_or_None) from a validated palette spec.

Classified specs return a (ListedColormap, BoundaryNorm) pair; continuous specs return (LinearSegmentedColormap, None).

zyra.visualization.cli_utils.features_from_ns(ns) → list[str] | None

Build a features list from argparse namespace flags.

Honors --features (CSV) and negation flags --no-coastline, --no-borders, and --no-gridlines. Falls back to MAP_STYLES["features"] when not explicitly provided.

zyra.visualization.cli_utils.load_data_array(input_path: str, *, var: str | None = None, xarray_engine: str | None = None, band: int = 1, geotiff_south_up: bool = True)

Load a 2D array from a .nc/.nc4, .npy, or GeoTIFF file.

Parameters:

• input_path (str) – Path to a NetCDF (.nc/.nc4), NumPy (.npy), or GeoTIFF (.tif/.tiff) file.

• var (str, optional) – Variable name to extract; required for NetCDF inputs.

• xarray_engine (str, optional) – Engine passed to xarray.open_dataset() (e.g., netcdf4, h5netcdf, scipy).

• band (int, default 1) – Band to read for GeoTIFF inputs (nodata is mapped to NaN).

• geotiff_south_up (bool, default True) – Whether GeoTIFF input is returned south-up (row 0 southernmost), which is what the figure path needs because it draws with origin="lower". Pass False to get the file’s own orientation, which is what anything writing a raster straight to an image file needs.

Returns:

The loaded array.

Return type:

numpy.ndarray

Raises:

ValueError – If var is missing for NetCDF inputs, or the file type is unsupported.

zyra.visualization.cli_utils.load_geotiff_array(input_path: str, *, band: int = 1, south_up: bool = True)

Read one band of a GeoTIFF as float32 with nodata mapped to NaN.

NaN renders transparent in the raster visualizers, so warp fill and masked regions disappear instead of plotting as a solid value.

Orientation of the returned array depends on south_up, and the two consumers want opposite things.

By default it is south-up — row 0 is the southernmost row. That is the convention every figure visualizer here assumes: heatmap draws with origin="lower" and contour builds its y coordinates as linspace(south, north). GeoTIFFs are conventionally north-up instead, so returning one as read renders it mirrored about the equator (see #281 — the global smoke frames put northern-hemisphere plumes over the Southern Ocean). The flip is keyed off the transform rather than assumed, so a genuinely south-up GeoTIFF is left alone either way.

With south_up=False the file’s own row order is preserved, so a conventional north-up GeoTIFF comes back north-up. That is what the data-encoded writer needs: write_luma_png hands the array straight to PIL and a PNG’s first row is its top, with no origin="lower" anywhere to undo a flip. Taking the default there reproduced #281 on the one path it could not have covered.

Parameters:

• input_path (str) – Path to a .tif/.tiff file.

• band (int, default 1) – 1-based band index to read.

• south_up (bool, default True) – Whether to return the array south-up (row 0 southernmost), flipping a north-up GeoTIFF to match. Pass False to keep the file’s own row order — needed when the array is written straight to an image rather than drawn with origin="lower". The default preserves the figure path’s behaviour exactly.

Raises:

ValueError – If rasterio is unavailable or band is out of range.

zyra.visualization.cli_utils.load_palette_spec(path: str) → dict

Load and validate a palette (--cmap-file).

Accepts a local path, - (stdin), or an http(s):// / s3:// URL — the same forms every other zyra input takes, so a palette can be referenced as a shared, versioned asset instead of a file the caller has to stage locally first.

Two shapes are accepted (see ColormapManager, which consumes them):

• {"type": "classified", "entries": [{"Color": [R,G,B(,A)], "Upper Bound": n}, ...]} — fixed color bands.

• {"type": "continuous", "base": "YlOrBr", "transparent_range": 2, "blend_range": 8, "overall_alpha": 0.9} — a named base colormap with an optional transparency ramp.

Raises:

ValueError – On unreadable files or URLs, invalid JSON, or a spec that fails validation. Handlers surface these as exit code 2.

zyra.visualization.cli_utils.resolve_basemap_ref(ref: str | None) → tuple[str | None, ExitStack | None]

Resolve a basemap reference to a filesystem path.

Supports three forms:

• Absolute/relative filesystem path (returned unchanged)

• Bare filename under packaged assets/images (e.g., “earth_vegetation.jpg”)

• Packaged reference using pkg: scheme: - pkg:package/resource or pkg:package:resource

Returns a tuple of (path, guard). If a temporary path context is used, a contextlib.ExitStack is returned and must be kept alive until the path is no longer needed. Call ``guard.close()” when finished.

zyra.visualization.cli_utils.resolve_cmap_args(ns)

Resolve (cmap, norm) from the --cmap/--cmap-file flags.

Returns the plain colormap name with no norm when no palette file is given. Classified palettes reject --vmin/--vmax — the bounds come from the palette table.

zyra.visualization.cli_utils.resolve_extent(ns) → list[float]

Validate and default the --extent value on a parsed namespace.

The extent flags are declared with action="extend"/nargs="+" so both the CLI spelling (--extent w e s n) and the Domain API’s repeated-flag expansion (--extent w --extent e ...) accumulate into one list; the parser can no longer enforce the length, so it is validated here. Returns the full-globe default (styles.DEFAULT_EXTENT) when unset.

Exits with code 2 (message on stderr via logging) on a wrong-length value, or on one whose bounds are inverted — see below. The numeric exit code keeps the failure a clean exit-status signal rather than relying on the Domain API executor’s message-string handling.

zyra.visualization.cli_utils.write_legend(output_path: str, *, cmap, norm=None, vmin=None, vmax=None, label: str | None = None, orientation: str = 'horizontal') → str

Write a standalone colorbar legend image (--legend-file).

Renders only the colorbar (transparent background) so globe/sphere display targets can place it as screen-space UI instead of baking it into the frame, where it would wrap onto the globe.

Raises:

ValueError – If neither a norm nor both vmin/vmax are given — the legend must reflect the scale actually used for the render, and a data-derived auto-scale is not visible here.

zyra.visualization.cli_animate.handle_animate(ns) → int

Handle visualize animate CLI subcommand.

Argument errors surface as a clean logged error with exit code 2 instead of a traceback or a bare exit 1 — the same contract handle_heatmap/handle_contour use. Runtime failures (render/ffmpeg errors) and the --to-video path guards keep raising SystemExit deliberately.

zyra.visualization.cli_compose_video.handle_compose_video(ns) → int

Handle visualize compose-video CLI subcommand.

zyra.visualization.cli_contour.handle_contour(ns) → int

Handle visualize contour CLI subcommand.

Input/validation errors (unsupported suffix, missing –var, GeoTIFF band out of range, missing rasterio) surface as a clean logged error with exit code 2 instead of a traceback.

zyra.visualization.cli_heatmap.handle_heatmap(ns) → int

Handle visualize heatmap CLI subcommand.

Input/validation errors (unsupported suffix, missing –var, GeoTIFF band out of range, missing rasterio) surface as a clean logged error with exit code 2 instead of a traceback.

zyra.visualization.cli_interactive.handle_interactive(ns) → int

Handle visualize interactive CLI subcommand.

zyra.visualization.cli_timeseries.handle_timeseries(ns) → int

Handle visualize timeseries CLI subcommand.

zyra.visualization.cli_vector.handle_vector(ns) → int

Handle visualize vector CLI subcommand.

Argument errors surface as a clean logged error with exit code 2 instead of a bare exit 1 — the same contract handle_heatmap/handle_contour use. This handler raises no SystemExit of its own; animate and sos do, for path guards and render failures respectively.