asp_plot.mapproject
===================

.. py:module:: asp_plot.mapproject

.. autoapi-nested-parse::

   Reconstruct ``mapproject`` commands from ASP-mapprojected GeoTIFF metadata.

   ASP's ``mapproject`` tool does not write a log file the way ``bundle_adjust`` /
   ``stereo`` / ``point2dem`` do, so :mod:`asp_plot.asp_log` (which parses those
   logs) has nothing to read for the mapprojection step (issue #96).

   Fortunately ``mapproject`` stamps everything we need into the *output* GeoTIFF
   header, so the command can be reconstructed from the output data alone -- no new
   ASP ``--log`` flag required. The fields written by ASP are:

   - ``INPUT_IMAGE_FILE`` -- the image that was mapprojected
   - ``CAMERA_FILE`` -- the camera model
   - ``DEM_FILE`` -- the DEM used as the projection surface
   - ``CAMERA_MODEL_TYPE`` -- the resolved ``--session-type`` / ``-t``
   - ``BUNDLE_ADJUST_PREFIX`` -- the ``--bundle-adjust-prefix`` (``"NONE"`` if unset)

   combined with the raster's own CRS (``--t_srs``), resolution (``--tr``), and
   bounds (``--t_projwin``).

   The reconstruction is faithful but *not* byte-for-byte re-runnable: the session
   type is the resolved value (not necessarily what the user typed), an input
   ``--mpp`` shows up resolved as ``--tr``, and the output name is read from the
   file itself. Callers that surface this to users (e.g. the PDF report) should say
   so. See ``reconstruct_mapproject_command`` for the exact argv order.



Attributes
----------

.. autoapisummary::

   asp_plot.mapproject.RASTER_EXTENSIONS
   asp_plot.mapproject.REQUIRED_TAGS
   asp_plot.mapproject.logger


Functions
---------

.. autoapisummary::

   asp_plot.mapproject.find_mapproject_commands
   asp_plot.mapproject.reconstruct_mapproject_command


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

.. py:function:: find_mapproject_commands(directories, stereo_command=None)

   Find ASP-mapprojected outputs across ``directories`` and reconstruct them.

   Scans each directory (non-recursively) for GeoTIFFs and keeps those carrying
   the ASP mapproject metadata signature (see ``REQUIRED_TAGS``) -- identity is
   decided entirely by the file's own metadata, not by its name, so the result
   is robust to ASP/asp_plot filename conventions. Each kept output is
   reconstructed into a command; results are deduplicated (the same scene can be
   reached via more than one of the passed directories) and returned sorted for
   stable report output.

   :param directories: Directories to scan (e.g. the processing root, stereo dir, BA dir).
                       ``None`` entries are skipped.
   :type directories: iterable of str or None
   :param stereo_command: The stereo command line for the run being reported. When given, a
                          mapprojected output is kept only if its filename appears among the
                          stereo inputs (i.e. this run actually consumed it). This scopes the
                          result to the run at hand: a non-mapprojected stereo run that shares a
                          directory with leftover mapprojected scenes (e.g. ``stereo/`` and
                          ``stereo_no_mapproj/`` under one parent) no longer picks them up. A
                          mapprojected run's ``stereo`` command lists the ``*_map.tif`` inputs; a
                          non-mapprojected run lists the raw images instead, so the gate is a
                          plain filename-membership test -- no fragile positional parsing. When
                          ``None`` (or empty), no gating is applied and every discovered output is
                          returned.
   :type stereo_command: str, optional

   :returns: Reconstructed ``mapproject`` command lines, sorted; empty if none found.
   :rtype: list of str


.. py:function:: reconstruct_mapproject_command(raster_path)

   Reconstruct the ``mapproject`` command for an ASP-mapprojected GeoTIFF.

   :param raster_path: Path to a GeoTIFF that may be an ASP ``mapproject`` output.
   :type raster_path: str

   :returns: The reconstructed ``mapproject ...`` command line, or ``None`` if the
             file is missing the ASP mapproject metadata signature (i.e. it is not a
             mapproject output, or was written by a tool that did not stamp the
             header).
   :rtype: str or None

   .. rubric:: Notes

   The reconstructed argv order mirrors the ASP CLI::

       mapproject [-t SESSION] [--t_srs SRS] --tr TR \
           --t_projwin XMIN YMIN XMAX YMAX \
           [--bundle-adjust-prefix PREFIX] \
           DEM_FILE INPUT_IMAGE CAMERA OUTPUT

   ``--t_srs`` is emitted as ``EPSG:XXXX`` when the CRS has an exact EPSG code,
   otherwise as the PROJ string (quoted), so custom planetary/local projections
   (e.g. the stereographic frames used in jitter solving) still round-trip.


.. py:data:: RASTER_EXTENSIONS
   :value: ('*.tif', '*.tiff')


.. py:data:: REQUIRED_TAGS
   :value: ('INPUT_IMAGE_FILE', 'CAMERA_FILE', 'DEM_FILE')


.. py:data:: logger