orca.utils.fitsutils
====================

.. py:module:: orca.utils.fitsutils

.. autoapi-nested-parse::

   FITS file I/O and image manipulation utilities.

   Provides functions for reading and writing FITS images, creating masks,
   co-adding images, and extracting cutouts and statistics around source
   positions.



Functions
---------

.. autoapisummary::

   orca.utils.fitsutils.read_image_fits
   orca.utils.fitsutils.write_image_fits
   orca.utils.fitsutils.write_fits_mask_with_box_xy_coordindates
   orca.utils.fitsutils.co_add
   orca.utils.fitsutils.co_add_arr
   orca.utils.fitsutils.get_peak_around_src
   orca.utils.fitsutils.std_and_max_around_src
   orca.utils.fitsutils.get_cutout
   orca.utils.fitsutils.get_sample_header


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

.. py:function:: read_image_fits(fn: str) -> Tuple[numpy.ndarray, astropy.io.fits.Header]

   Read a 2D image from a FITS file.

   Extracts the first plane from a 4D FITS cube (typical WSClean output).

   :param fn: Path to the FITS file.

   :returns: Tuple of (image_data, header).


.. py:function:: write_image_fits(fn: str, header: astropy.io.fits.Header, data: numpy.ndarray, overwrite: bool = False)

   Write a 2D image to a FITS file.

   Reshapes 2D data into 4D format for CASA/WSClean compatibility.

   :param fn: Output file path.
   :param header: FITS header to use.
   :param data: 2D image data array.
   :param overwrite: If True, overwrite existing file.


.. py:function:: write_fits_mask_with_box_xy_coordindates(output_fits_path: str, imsize: int, center_list: List[Tuple[int, int]], width_list: List[int]) -> str

   Writes a fits mask with a list of boxes to file.
   Writes a fits mask with a list of boxes to file. Both im+list and center_list are in
   WCS X Y coordindates (i.e. transpose of the numpy array
   from astropy.fits. The fits will NOT have a header that is accurate since only the pixels will be used.
   If you only need one box you can use one-element lists for the arguments.

   :param output_fits_path: The fits file path.
   :param imsize: size of the image.
   :param center_list: A list of enters of the boxes. Must be in XY index (i.e. what ds9 shows).
   :param width_list: A list of widths of the boxes in pixels, with each element being the width of the corresponding

   center_list element.

   Returns: The fits mask path.



.. py:function:: co_add(fits_list: List[str], output_fits_path: str, header_index: Optional[int] = None) -> str

.. py:function:: co_add_arr(fits_list, dims)

.. py:function:: get_peak_around_src(im_T: numpy.ndarray, source_coord: astropy.coordinates.SkyCoord, w: astropy.wcs.WCS, radius_px: int = 100) -> Tuple[int, int]

.. py:function:: std_and_max_around_src(im_T: numpy.ndarray, radius: int, source_coord: astropy.coordinates.SkyCoord, w: astropy.wcs.WCS) -> Tuple[float, float]

.. py:function:: get_cutout(im: numpy.ndarray, coord: astropy.coordinates.SkyCoord, w: astropy.wcs.WCS, radius_px: int) -> numpy.ndarray

.. py:function:: get_sample_header() -> astropy.io.fits.Header