pyampp.io.refmaps

Utilities for adding external FITS maps to pyAMPP HDF5 refmaps.

Attributes

PathLike
MapIdFactory

Classes

AddedRefmap

Summary for one external FITS file embedded as a refmap.

Functions

add_fits_refmaps_to_h5(→ list[AddedRefmap])	Align external FITS maps and embed them in refmaps/ of a model HDF5.
add_fits_refmaps_from_dir_to_h5(→ list[AddedRefmap])	Embed FITS files from a directory into refmaps/ of an HDF5 model.
discover_fits_refmap_paths(→ list[pathlib.Path])	Resolve FITS files from a mix of file and directory paths.
infer_fits_refmap_id(→ str | None)	Infer the canonical refmap id for a FITS map.
discover_fits_refmap_map_ids(→ dict[pathlib.Path, str])	Resolve FITS refmap paths and canonical ids using the shared IO policy.
build_fits_refmaps_for_model(→ dict[str, dict[str, Any]])	Load FITS refmaps from paths and build model-aligned payloads.
model_obstime_from_base_index(→ str | None)	Return the model time from canonical base/index metadata.
build_refmap_payload_for_model(→ dict[str, Any])	Build a refmap payload using pyAMPP's model-time alignment policy.

Module Contents

class pyampp.io.refmaps.AddedRefmap

Summary for one external FITS file embedded as a refmap.

map_id: str

source_path: pathlib.Path

data_shape: tuple[int, Ellipsis]

data_dtype: str

pyampp.io.refmaps.PathLike

pyampp.io.refmaps.MapIdFactory

pyampp.io.refmaps.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.

Parameters:

• h5_path – pyAMPP model HDF5 file to modify in place.

• fits_paths – External FITS file paths to add.

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

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

• overwrite – Replace existing refmaps/<map_id> groups when true.

Returns:

One summary entry per embedded FITS file.

Return type:

list[AddedRefmap]

pyampp.io.refmaps.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.

pyampp.io.refmaps.discover_fits_refmap_paths(paths: Iterable[PathLike], *, recursive: bool = False) → list[pathlib.Path]

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

pyampp.io.refmaps.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.

pyampp.io.refmaps.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.

pyampp.io.refmaps.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.

pyampp.io.refmaps.model_obstime_from_base_index(model_or_h5: Any) → str | None

Return the model time from canonical base/index metadata.

pyampp.io.refmaps.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.