pyampp.geometry.core

Public vectorized geometry primitives for pyAMPP.

The gxbox tools historically carried the proven geometry implementation inside their application layer. This module promotes the reusable, headless pieces so all 3D structures can flow through the same world/observer projection path.

Functions

local_cartesian_to_world(...)	Convert model-local Cartesian points into world-frame coordinates.
project_world_to_observer_hpc(...)	Project world coordinates into the observer helioprojective frame.
project_world_to_observer_hcc(...)	Project world coordinates into the observer-centric heliocentric frame.
compute_inscribing_fov_from_hpc(→ dict | None)	Compute the smallest axis-aligned HPC rectangle covering the inputs.
compute_inscribing_fov_from_world(→ dict | None)	Project world coordinates and compute the enclosing 2D observer FOV.
compute_inscribing_fov_box_from_world(→ dict | None)	Compute the observer-aligned 3D FOV box enclosing the inputs.
build_fov_box_from_red_box_world(→ dict | None)	Build a full observer-aligned FOV box from red-box world corners.
build_fov_box_from_user_hpc_and_red_box_world(...)	Build user-defined x/y FOV with LOS-safe z from the red-box inscribing FOV box.
observer_fov_box_to_world_corners(...)	Reconstruct 8 world-space corners from saved observer fov_box metadata.
observer_rectangle_to_hpc_corners(...)	Construct 4 helioprojective rectangle corners for an observer view.
project_coordinate_edges_to_observer_hpc(...)	Project coordinate edge pairs into one observer helioprojective frame.
project_box_front_face_to_observer_hpc([back_face])	Project the nearer box face into the observer helioprojective frame.
project_world_to_pixel(→ tuple[numpy.ndarray, ...)	Project world coordinates into a map's pixel plane in one vectorized call.
world_to_local_cartesian_mm(→ numpy.ndarray | None)	Extract cartesian mm rows from world coords and shift z by z_base_mm.
make_observer_wcs_header(→ astropy.io.fits.Header)	Create a SunPy-compatible observer-aware WCS header.

Module Contents

pyampp.geometry.core.local_cartesian_to_world(local_points_mm: numpy.ndarray, *, frame, z_base_mm: float = 0.0) → astropy.coordinates.SkyCoord | None

Convert model-local Cartesian points into world-frame coordinates.

pyampp.geometry.core.project_world_to_observer_hpc(world: astropy.coordinates.SkyCoord, *, observer=None, obstime=None, frame_obs=None) → astropy.coordinates.SkyCoord | None

Project world coordinates into the observer helioprojective frame.

pyampp.geometry.core.project_world_to_observer_hcc(world: astropy.coordinates.SkyCoord, *, observer=None, obstime=None, frame_obs=None) → astropy.coordinates.SkyCoord | None

Project world coordinates into the observer-centric heliocentric frame.

pyampp.geometry.core.compute_inscribing_fov_from_hpc(coords_hpc: astropy.coordinates.SkyCoord, *, pad_arcsec: float = 0.0) → dict | None

Compute the smallest axis-aligned HPC rectangle covering the inputs.

pyampp.geometry.core.compute_inscribing_fov_from_world(world: astropy.coordinates.SkyCoord, *, observer=None, obstime=None, frame_obs=None, pad_arcsec: float = 0.0) → dict | None

Project world coordinates and compute the enclosing 2D observer FOV.

pyampp.geometry.core.compute_inscribing_fov_box_from_world(world: astropy.coordinates.SkyCoord, *, observer=None, obstime=None, frame_obs=None, pad_xy_arcsec: float = 0.0, pad_z_frac: float = 0.1) → dict | None

Compute the observer-aligned 3D FOV box enclosing the inputs.

pyampp.geometry.core.build_fov_box_from_red_box_world(world: astropy.coordinates.SkyCoord, *, observer=None, obstime=None, frame_obs=None, pad_xy_arcsec: float = 0.0, pad_z_frac: float = 0.1) → dict | None

Build a full observer-aligned FOV box from red-box world corners.

pyampp.geometry.core.build_fov_box_from_user_hpc_and_red_box_world(world: astropy.coordinates.SkyCoord, *, xc_arcsec: float, yc_arcsec: float, xsize_arcsec: float, ysize_arcsec: float, observer=None, obstime=None, frame_obs=None, pad_z_frac: float = 0.1) → dict | None

Build user-defined x/y FOV with LOS-safe z from the red-box inscribing FOV box.

pyampp.geometry.core.observer_fov_box_to_world_corners(*, xc_arcsec: float, yc_arcsec: float, xsize_arcsec: float, ysize_arcsec: float, zmin_mm: float, zmax_mm: float, observer, obstime, target_frame) → astropy.coordinates.SkyCoord | None

Reconstruct 8 world-space corners from saved observer fov_box metadata.

pyampp.geometry.core.observer_rectangle_to_hpc_corners(*, xc_arcsec: float, yc_arcsec: float, xsize_arcsec: float, ysize_arcsec: float, observer, obstime) → astropy.coordinates.SkyCoord | None

Construct 4 helioprojective rectangle corners for an observer view.

pyampp.geometry.core.project_coordinate_edges_to_observer_hpc(coords, *, edge_pairs, observer=None, obstime=None, frame_obs=None) → list[astropy.coordinates.SkyCoord] | None

Project coordinate edge pairs into one observer helioprojective frame.

pyampp.geometry.core.project_box_front_face_to_observer_hpc(world_corners: astropy.coordinates.SkyCoord, *, observer=None, obstime=None, frame_obs=None, front_face=(0, 1, 3, 2), back_face=(4, 5, 7, 6)) → astropy.coordinates.SkyCoord | None

Project the nearer box face into the observer helioprojective frame.

pyampp.geometry.core.project_world_to_pixel(world: astropy.coordinates.SkyCoord, smap) → tuple[numpy.ndarray, numpy.ndarray] | None

Project world coordinates into a map’s pixel plane in one vectorized call.

pyampp.geometry.core.world_to_local_cartesian_mm(world: astropy.coordinates.SkyCoord, *, z_base_mm: float = 0.0) → numpy.ndarray | None

Extract cartesian mm rows from world coords and shift z by z_base_mm.

pyampp.geometry.core.make_observer_wcs_header(*, nx: int, ny: int, xc_arcsec: float, yc_arcsec: float, dx_arcsec: float, dy_arcsec: float, observer: astropy.coordinates.SkyCoord, obs_time, bunit: str, observer_name: str = 'custom', rsun_ref_m: float | None = None, rsun_obs_arcsec: float | None = None) → astropy.io.fits.Header

Create a SunPy-compatible observer-aware WCS header.