asp_plot.report_pipeline
========================

.. py:module:: asp_plot.report_pipeline

.. autoapi-nested-parse::

   Declarative report pipeline for the ``asp_plot`` CLI.

   This module decouples the report-generation pipeline from Click. The CLI
   (:mod:`asp_plot.cli.asp_plot`) parses options, packs them into a
   :class:`ReportConfig`, and calls :func:`run_report` -- which is importable and
   callable from notebooks and tests without any Click context.

   The body of the report is a **declarative section registry**
   (:data:`REPORT_SECTIONS`): each entry is a :class:`ReportSpec` pairing an
   ``enabled(ctx)`` predicate with a ``build(ctx)`` function that returns the
   report sections to append. The orchestrator iterates the registry in order,
   so section ordering and figure numbering are data, not source-line position.
   Captions live in :mod:`asp_plot.report_captions`.



Attributes
----------

.. autoapisummary::

   asp_plot.report_pipeline.REPORT_SECTIONS


Classes
-------

.. autoapisummary::

   asp_plot.report_pipeline.ReportConfig
   asp_plot.report_pipeline.ReportContext
   asp_plot.report_pipeline.ReportSpec


Functions
---------

.. autoapisummary::

   asp_plot.report_pipeline.run_report


Module Contents
---------------

.. py:class:: ReportConfig

   All inputs needed to generate a report, decoupled from Click.

   Field names and defaults mirror the CLI options one-for-one so the Click
   wrapper can splat its parsed params straight in.


   .. py:attribute:: add_basemap
      :type:  bool
      :value: True



   .. py:attribute:: altimetry_csv
      :type:  Optional[str]
      :value: None



   .. py:attribute:: atl06sr_time_range
      :type:  str
      :value: 'all'



   .. py:attribute:: bundle_adjust_directory
      :type:  Optional[str]
      :value: None



   .. py:attribute:: dem_filename
      :type:  Optional[str]
      :value: None



   .. py:attribute:: dem_gsd
      :type:  Optional[float]
      :value: None



   .. py:attribute:: directory
      :type:  str
      :value: './'



   .. py:attribute:: map_crs
      :type:  Optional[str]
      :value: None



   .. py:attribute:: pc_align
      :type:  bool
      :value: True



   .. py:attribute:: plot_altimetry
      :type:  bool
      :value: True



   .. py:attribute:: plot_geometry
      :type:  bool
      :value: True



   .. py:attribute:: plot_icesat
      :type:  Optional[object]
      :value: None



   .. py:attribute:: reference_dem
      :type:  Optional[str]
      :value: None



   .. py:attribute:: report_command
      :type:  Optional[str]
      :value: None



   .. py:attribute:: report_filename
      :type:  Optional[str]
      :value: None



   .. py:attribute:: report_title
      :type:  Optional[str]
      :value: None



   .. py:attribute:: reuse_selections
      :type:  Optional[str]
      :value: None



   .. py:attribute:: stereo_directory
      :type:  str
      :value: 'stereo'



   .. py:attribute:: subset_km
      :type:  float
      :value: 1.0



.. py:class:: ReportContext

   Mutable runtime state shared across section builders.

   Built once by :func:`_setup_context`, then threaded through every
   :class:`ReportSpec` so builders can pull shared plotters/selections and
   draw sequential figure filenames without a module-global counter.


   .. py:method:: fig_path(fig_fn: str) -> str


   .. py:method:: next_fig_fn() -> str

      Next sequential ``NN.png`` figure filename (00, 01, 02, ...).



   .. py:attribute:: asp_dem
      :type:  Optional[str]


   .. py:attribute:: config
      :type:  ReportConfig


   .. py:attribute:: ctx_kwargs
      :type:  dict


   .. py:attribute:: icesat2_selections
      :type:  Optional[dict]
      :value: None



   .. py:attribute:: map_crs
      :type:  Optional[str]


   .. py:attribute:: plot_altimetry
      :type:  bool


   .. py:attribute:: plots_directory
      :type:  str


   .. py:attribute:: report_metadata
      :type:  Optional[asp_plot.report.ReportMetadata]
      :value: None



   .. py:attribute:: report_pdf_path
      :type:  str


   .. py:attribute:: report_title
      :type:  str


   .. py:attribute:: reuse_clip_windows
      :type:  Optional[list]
      :value: None



   .. py:attribute:: reuse_clip_windows_crs
      :type:  Optional[str]
      :value: None



   .. py:attribute:: reuse_parquet
      :type:  Optional[object]
      :value: None



   .. py:attribute:: reuse_segments
      :type:  Optional[object]
      :value: None



   .. py:attribute:: reuse_track
      :type:  dict


   .. py:attribute:: stereo_plotter
      :type:  asp_plot.stereo.StereoPlotter


.. py:class:: ReportSpec

   One declarative report section.

   ``enabled(ctx)`` gates the section on config/runtime state; ``build(ctx)``
   runs the plotting and returns the :class:`ReportSection` /
   :class:`AlignmentReportPage` objects to append (possibly several, possibly
   none).


   .. py:attribute:: build
      :type:  Callable[[ReportContext], List[object]]


   .. py:attribute:: enabled
      :type:  Callable[[ReportContext], bool]


   .. py:attribute:: name
      :type:  str


.. py:function:: run_report(config: ReportConfig) -> str

   Generate the ASP processing report described by ``config``.

   Builds the runtime context, iterates the declarative
   :data:`REPORT_SECTIONS` registry to assemble the report body, compiles the
   PDF, writes the figure-selections sidecar, and cleans up. Returns the path
   to the written PDF. Importable and callable without any Click context.


.. py:data:: REPORT_SECTIONS
   :type:  List[ReportSpec]