pyampp.gxbox.selector_api
=========================

.. py:module:: pyampp.gxbox.selector_api


Classes
-------

.. autoapisummary::

   pyampp.gxbox.selector_api.CoordMode
   pyampp.gxbox.selector_api.BoxGeometrySelection
   pyampp.gxbox.selector_api.SelectorSessionInput
   pyampp.gxbox.selector_api.DisplayFovSelection
   pyampp.gxbox.selector_api.DisplayFovBoxSelection
   pyampp.gxbox.selector_api.SelectorDialogResult
   pyampp.gxbox.selector_api.GeometrySelectionConsumer


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

.. py:class:: CoordMode

   Bases: :py:obj:`str`, :py:obj:`enum.Enum`


   Coordinate representation used by the GUI center fields.


   .. py:attribute:: HPC
      :value: 'hpc'



   .. py:attribute:: HGC
      :value: 'hgc'



   .. py:attribute:: HGS
      :value: 'hgs'



.. py:class:: BoxGeometrySelection

   Workflow-relevant box geometry values in the same shape as pyAMPP GUI fields.

   These map directly to the existing ``PyAmppGUI`` input widgets:
   - ``coord_x`` / ``coord_y`` -> ``coord_x_edit`` / ``coord_y_edit``
   - ``grid_x`` / ``grid_y`` / ``grid_z`` -> ``grid_*_edit``
   - ``dx_km`` -> ``res_edit`` (CLI ``--dx-km``)


   .. py:attribute:: coord_mode
      :type:  CoordMode


   .. py:attribute:: coord_x
      :type:  float


   .. py:attribute:: coord_y
      :type:  float


   .. py:attribute:: grid_x
      :type:  int


   .. py:attribute:: grid_y
      :type:  int


   .. py:attribute:: grid_z
      :type:  int


   .. py:attribute:: dx_km
      :type:  float


   .. py:method:: as_gui_text_fields() -> dict[str, str]

      Return values formatted for direct assignment to QLineEdit widgets.



.. py:class:: SelectorSessionInput

   Inputs needed to launch a future standalone map/box selector GUI.

   ``map_ids`` and ``initial_map_id`` are UI-only state for visualization and
   are not part of the geometry return contract.


   .. py:attribute:: time_iso
      :type:  str


   .. py:attribute:: data_dir
      :type:  str


   .. py:attribute:: geometry
      :type:  BoxGeometrySelection


   .. py:attribute:: fov
      :type:  DisplayFovSelection | None
      :value: None



   .. py:attribute:: fov_box
      :type:  DisplayFovBoxSelection | None
      :value: None



   .. py:attribute:: square_fov
      :type:  bool
      :value: False



   .. py:attribute:: allow_geometry_edit
      :type:  bool
      :value: True



   .. py:attribute:: map_ids
      :type:  tuple[str, Ellipsis]
      :value: ()



   .. py:attribute:: map_files
      :type:  dict[str, str] | None
      :value: None



   .. py:attribute:: refmaps
      :type:  dict[str, dict[str, Any]] | None
      :value: None



   .. py:attribute:: base_maps
      :type:  dict[str, Any] | None
      :value: None



   .. py:attribute:: base_wcs_header
      :type:  str | None
      :value: None



   .. py:attribute:: base_geometry
      :type:  BoxGeometrySelection | None
      :value: None



   .. py:attribute:: map_source_mode
      :type:  str
      :value: 'auto'



   .. py:attribute:: display_observer_key
      :type:  str
      :value: 'earth'



   .. py:attribute:: custom_observer_ephemeris
      :type:  dict[str, Any] | None
      :value: None



   .. py:attribute:: custom_observer_label
      :type:  str | None
      :value: None



   .. py:attribute:: custom_observer_source
      :type:  str | None
      :value: None



   .. py:attribute:: available_observer_keys
      :type:  tuple[str, Ellipsis] | None
      :value: None



   .. py:attribute:: observer_availability_notice
      :type:  str | None
      :value: None



   .. py:attribute:: initial_map_id
      :type:  str | None
      :value: None



   .. py:attribute:: pad_frac
      :type:  float | None
      :value: None



.. py:class:: DisplayFovSelection

   Observer-plane image FOV used for synthetic image framing and canvas centering.

   This is intentionally separate from the model box geometry. Values are expressed
   in helioprojective (observer-plane) arcsec, regardless of the red-box input
   coordinate mode.


   .. py:attribute:: center_x_arcsec
      :type:  float


   .. py:attribute:: center_y_arcsec
      :type:  float


   .. py:attribute:: width_arcsec
      :type:  float


   .. py:attribute:: height_arcsec
      :type:  float


   .. py:method:: as_gui_text_fields() -> dict[str, str]


.. py:class:: DisplayFovBoxSelection

   Observer-aligned 3D FOV box.

   The x/y footprint matches the image-plane FOV rectangle in helioprojective
   arcsec. The z extent is stored in observer-centric heliocentric coordinates
   (Mm) along the line of sight, where larger values are closer to the
   observer.


   .. py:attribute:: center_x_arcsec
      :type:  float


   .. py:attribute:: center_y_arcsec
      :type:  float


   .. py:attribute:: width_arcsec
      :type:  float


   .. py:attribute:: height_arcsec
      :type:  float


   .. py:attribute:: z_min_mm
      :type:  float


   .. py:attribute:: z_max_mm
      :type:  float


   .. py:attribute:: corners_local_mm
      :type:  tuple[tuple[float, float, float], Ellipsis] | None
      :value: None



   .. py:attribute:: observer_key
      :type:  str
      :value: 'earth'



   .. py:method:: from_display_fov(fov: DisplayFovSelection, z_min_mm: float, z_max_mm: float, *, observer_key: str = 'earth') -> DisplayFovBoxSelection
      :classmethod:



   .. py:method:: as_observer_metadata(*, square: bool = False) -> dict[str, float | str | bool]


.. py:class:: SelectorDialogResult

   Accepted result returned by the standalone selector dialog.


   .. py:attribute:: geometry
      :type:  BoxGeometrySelection


   .. py:attribute:: fov
      :type:  DisplayFovSelection | None
      :value: None



   .. py:attribute:: square_fov
      :type:  bool
      :value: False



.. py:class:: GeometrySelectionConsumer

   Bases: :py:obj:`Protocol`


   Callback protocol for receiving accepted geometry selections.


   .. py:method:: apply_geometry_selection(selection: BoxGeometrySelection) -> None

      Apply an accepted geometry selection to the host GUI/application.