pyampp.io.refmaps
=================

.. py:module:: pyampp.io.refmaps

.. autoapi-nested-parse::

   Utilities for adding external FITS maps to pyAMPP HDF5 refmaps.



Attributes
----------

.. autoapisummary::

   pyampp.io.refmaps.PathLike
   pyampp.io.refmaps.MapIdFactory


Classes
-------

.. autoapisummary::

   pyampp.io.refmaps.AddedRefmap


Functions
---------

.. autoapisummary::

   pyampp.io.refmaps.add_fits_refmaps_to_h5
   pyampp.io.refmaps.add_fits_refmaps_from_dir_to_h5
   pyampp.io.refmaps.discover_fits_refmap_paths
   pyampp.io.refmaps.infer_fits_refmap_id
   pyampp.io.refmaps.discover_fits_refmap_map_ids
   pyampp.io.refmaps.build_fits_refmaps_for_model
   pyampp.io.refmaps.model_obstime_from_base_index
   pyampp.io.refmaps.build_refmap_payload_for_model


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

.. py:class:: AddedRefmap

   Summary for one external FITS file embedded as a refmap.


   .. py:attribute:: map_id
      :type:  str


   .. py:attribute:: source_path
      :type:  pathlib.Path


   .. py:attribute:: data_shape
      :type:  tuple[int, Ellipsis]


   .. py:attribute:: data_dtype
      :type:  str


.. py:data:: PathLike

.. py:data:: MapIdFactory

.. py:function:: add_fits_refmaps_to_h5(h5_path: PathLike, fits_paths: Iterable[PathLike], *, crop_refmap: str | None = 'Bz_reference', map_ids: Mapping[PathLike, str] | Sequence[str] | MapIdFactory | None = None, overwrite: bool = False) -> list[AddedRefmap]

   Align external FITS maps and embed them in ``refmaps/`` of a model HDF5.

   :param h5_path: pyAMPP model HDF5 file to modify in place.
   :param fits_paths: External FITS file paths to add.
   :param crop_refmap: Existing refmap whose WCS footprint is used as the alignment target
                       for Earth-line-of-sight maps. Use ``None`` to embed maps without a
                       model-FOV target.
   :param map_ids: Optional map-id source. This can be a mapping from path to id, a
                   sequence aligned with ``fits_paths``, or a callable ``(path, sunpy_map)
                   -> str``. When omitted, ids are inferred from FITS metadata and names.
   :param overwrite: Replace existing ``refmaps/<map_id>`` groups when true.

   :returns: One summary entry per embedded FITS file.
   :rtype: list[AddedRefmap]


.. py:function:: add_fits_refmaps_from_dir_to_h5(h5_path: PathLike, fits_dir: PathLike, *, pattern: str | None = None, recursive: bool = False, crop_refmap: str | None = 'Bz_reference', map_ids: Mapping[PathLike, str] | Sequence[str] | MapIdFactory | None = None, overwrite: bool = False) -> list[AddedRefmap]

   Embed FITS files from a directory into ``refmaps/`` of an HDF5 model.

   When ``pattern`` is omitted, all supported FITS extensions are included:
   ``.fits``, ``.fit``, ``.fts``, their uppercase variants, and ``.fits.gz``.


.. py:function:: discover_fits_refmap_paths(paths: Iterable[PathLike], *, recursive: bool = False) -> list[pathlib.Path]

   Resolve FITS files from a mix of file and directory paths.


.. py:function:: infer_fits_refmap_id(path: PathLike, smap=None, *, generic: bool = True) -> str | None

   Infer the canonical refmap id for a FITS map.

   Known observation products are identified from FITS metadata. When
   ``generic`` is true, unknown FITS files fall back to a sanitized file stem;
   when false, unknown files are ignored by returning ``None``.


.. py:function:: discover_fits_refmap_map_ids(paths: Iterable[PathLike], *, recursive: bool = False, generic: bool = True) -> dict[pathlib.Path, str]

   Resolve FITS refmap paths and canonical ids using the shared IO policy.


.. py:function:: build_fits_refmaps_for_model(paths: Iterable[PathLike], *, model_obstime: str | astropy.time.Time | None, target_fov: tuple[astropy.coordinates.SkyCoord, astropy.coordinates.SkyCoord] | None = None, target_template=None, map_ids: Mapping[PathLike, str] | Sequence[str] | MapIdFactory | None = None, reproject_algorithm: str = 'adaptive', recursive: bool = False, generic: bool = True) -> dict[str, dict[str, Any]]

   Load FITS refmaps from paths and build model-aligned payloads.


.. py:function:: model_obstime_from_base_index(model_or_h5: Any) -> str | None

   Return the model time from canonical ``base/index`` metadata.


.. py:function:: build_refmap_payload_for_model(smap, *, model_obstime: str | astropy.time.Time | None, target_template=None, target_fov: tuple[astropy.coordinates.SkyCoord, astropy.coordinates.SkyCoord] | None = None, source_path: pathlib.Path | None = None, reproject_algorithm: str = 'adaptive') -> dict[str, Any]

   Build a refmap payload using pyAMPP's model-time alignment policy.

   Earth-line-of-sight maps are solar-rotated to the model time and remapped
   onto a target FOV WCS. Non-Earth maps keep their native WCS and data so the
   viewer can display them in their own spacecraft LOS mode.