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().

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, 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) – [west, east, south, north] in PlateCarree coordinates.

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

• 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().

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, 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) – [west, east, south, north] in PlateCarree coordinates.

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

• 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.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.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_animate.handle_animate(ns) → int

Handle visualize animate CLI subcommand.

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.

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

Handle visualize heatmap CLI subcommand.

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.