pyampp.geometry.core
====================

.. py:module:: pyampp.geometry.core

.. autoapi-nested-parse::

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

.. autoapisummary::

   pyampp.geometry.core.local_cartesian_to_world
   pyampp.geometry.core.project_world_to_observer_hpc
   pyampp.geometry.core.project_world_to_observer_hcc
   pyampp.geometry.core.compute_inscribing_fov_from_hpc
   pyampp.geometry.core.compute_inscribing_fov_from_world
   pyampp.geometry.core.compute_inscribing_fov_box_from_world
   pyampp.geometry.core.build_fov_box_from_red_box_world
   pyampp.geometry.core.build_fov_box_from_user_hpc_and_red_box_world
   pyampp.geometry.core.observer_fov_box_to_world_corners
   pyampp.geometry.core.observer_rectangle_to_hpc_corners
   pyampp.geometry.core.project_coordinate_edges_to_observer_hpc
   pyampp.geometry.core.project_box_front_face_to_observer_hpc
   pyampp.geometry.core.project_world_to_pixel
   pyampp.geometry.core.world_to_local_cartesian_mm
   pyampp.geometry.core.make_observer_wcs_header


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

.. py:function:: 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.


.. py:function:: 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.


.. py:function:: 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.


.. py:function:: 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.


.. py:function:: 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.


.. py:function:: 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.


.. py:function:: 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.


.. py:function:: 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.


.. py:function:: 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.


.. py:function:: 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.


.. py:function:: 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.


.. py:function:: 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.


.. py:function:: 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.


.. py:function:: 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.


.. py:function:: 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.