[Workflow Gap] Expose the SOS equirectangular renderer on the CLI (with fixed color scaling)

[github-actions]

🔗 Synced from upstream: NOAA-GSL/zyra#284

This issue is mirrored from the upstream repository. Status changes here will be synced back.

---

Summary

A workflow request requires functionality that is not currently implemented in the Zyra CLI.

Current State

• Available commands used: zyra visualize heatmap --map-type image --extent -180 180 -90 90 --width --height --cmap (+ batch --inputs/--output-dir), zyra visualize compose-video
• Missing functionality:
  1. PlotManager / PlotManager.sos_plot_data() (PlateCarree, set_global(), axis-off, edge-to-edge 2:1, vmin/vmax) exists in src/zyra/visualization/plot_manager.py but is not wired to any visualize subcommand.
  2. The heatmap CLI handler exposes no --vmin/--vmax, so frame sequences self-scale per frame and the resulting animation flickers.

Desired Behavior

• Add support for: a CLI path to the SOS renderer with a fixed color range, ideally batch-capable for frame sequences.

• Expected usage example:

  zyra visualize sos --inputs ./nc/*.nc --output-dir ./frames \
    --var <VAR> --cmap YlOrBr --width 4096 --height 2048 \
    --vmin 0 --vmax 50
  

  (Alternatively/additionally: add --vmin/--vmax and a --map-type sos option to visualize heatmap.)

Implementation Plan (Proposal)

• Implement core functionality in src/zyra/ (a cli_sos.py handler + handle_sos, or thread vmin/vmax + an sos map-type through cli_heatmap.py → HeatmapManager/PlotManager)
• Add tests in tests/ (single + batch render; verify 2:1 edge-to-edge output and identical color scaling across frames)
• Ensure comprehensive docstrings for auto-generated documentation
• Include example in sample workflows (FV3-Chem SOS frames)

Context

Science On a Sphere frames must be PlateCarree, full-globe, 2:1, edge-to-edge, with a consistent color scale across all frames to avoid flicker. The library already does all of this via PlotManager; it just isn't reachable from the CLI/zyra run YAML. Exposing it (plus vmin/vmax) is the difference between "frames render" and "production-quality SOS animation" for any gridded-data SOS workflow.