eye_patch.pixel_utils
=====================

.. py:module:: eye_patch.pixel_utils


Classes
-------

.. autoapisummary::

   eye_patch.pixel_utils.BeamShape


Functions
---------

.. autoapisummary::

   eye_patch.pixel_utils.get_beam_shape
   eye_patch.pixel_utils.get_pixels_per_beam


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

.. py:class:: BeamShape

   A simple container to represent a fitted 2D gaussian,
   intended for the main lobe of the synthesised beam. This
   class has been defined to avoid issues with the serialisation
   of astropy.units, which can cause strange and wonderful
   errors when being sent over the wire to workers.


   .. py:method:: from_radio_beam(radio_beam: radio_beam.Beam) -> BeamShape
      :classmethod:


      A helper function to convert a radio_beam.Beam into a
      BeamShape. This is prinicpally intended to be used when
      there is a need to exchange a Beam between processes
      that would need to serialise the object.

      :param radio_beam: The Beam to convert to normalised and known units
      :type radio_beam: Beam

      :returns: The normalised container without astropy units.
      :rtype: BeamShape



   .. py:attribute:: bmaj_arcsec
      :type:  float

      The size of the major-axis of the beam, in arcseconds.


   .. py:attribute:: bmin_arcsec
      :type:  float

      The size of the minor-axis of the beam, in arcseconds.


   .. py:attribute:: bpa_deg
      :type:  float

      Rotation of the beam, in degrees.


.. py:function:: get_beam_shape(fits_path: pathlib.Path) -> BeamShape | None

   Construct and return a beam shape from the fields in a FITS image

   :param fits_path: FITS image to extract the beam information from
   :type fits_path: Path

   :returns: Shape of the beam stored in the FITS image. None is returned if the beam is not found.
   :rtype: Optional[BeamShape]


.. py:function:: get_pixels_per_beam(fits_path: pathlib.Path) -> float | None

   Given a image with beam information, return the number of pixels
   per beam. The beam is taken from the FITS header. This is evaluated
   for pixels at the reference pixel position.

   :param fits_path: FITS image to consideer
   :type fits_path: Path

   :returns: Number of pixels per beam. If beam is not in header then None is returned.
   :rtype: float | None