opticam.utils.fits_handlers
===========================

.. py:module:: opticam.utils.fits_handlers


Functions
---------

.. autoapisummary::

   opticam.utils.fits_handlers.get_header_info
   opticam.utils.fits_handlers.get_data
   opticam.utils.fits_handlers.save_stacked_images
   opticam.utils.fits_handlers.get_stacked_images


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

.. py:function:: get_header_info(file, instrument, barycenter)

   Get the timestamp, exposure length, filter, and binning of the file.

   Parameters
   ----------
   file : MEFSlice
       The `MEFSlice` instance representing the file.
   instrument : Instrument
       The instrument that created the file.
   barycenter : bool
       Whether to apply a Barycentric correction to the image's timestamp.

   Returns
   -------
   Tuple[float, float, str, str, str, float]
       The timestamp, exposure length, camera, filter, and binning of the image.


.. py:function:: get_data(file, instrument, rebin_factor, remove_cosmic_rays, bias_corrector = None, dark_corrector = None, flat_corrector = None)

   Get the (calibrated) image data from a file.

   Parameters
   ----------
   file : MEFSlice
       The `MEFSlice` instance representing the file.
   instrument : Instrument
       The instrument that created the file.
   rebin_factor : int
       The image rebinning factor.
   remove_cosmic_rays : bool
       Whether to remove cosmic rays from the image.
   bias_corrector : BiasCorrector | None, optional
       The bias corrector, by default `None`. If `None`, no bias corrections are performed.
   dark_corrector : DarkNoiseCorrector | None, optional
       The dark noise corrector, by default `None`. If `None`, no dark noise corrections are performed.
   flat_corrector : FlatFieldCorrector | None, optional
       The flat-field corrector, by default `None`. If `None`, no flat-field corrections are performed.

   Returns
   -------
   Tuple[NDArray[np.float64], float | NDArray[np.float64], float | NDArray[np.float64], float | NDArray[np.float64]]
       The corrected image and the master bias, dark, and flat variances. If any of the correctors are undefined,
       the variance of that corrector is set to 0.


.. py:function:: save_stacked_images(stacked_images, out_directory, overwrite)

   Save the stacked images to a compressed multi-extension FITS file.

   Parameters
   ----------
   stacked_images : dict[str, NDArray]
       The stacked images {filter: stacked image}.
   out_directory : Path
       The path to the directory in which the stacked images will be saved.
   overwrite : bool
       Whether to overwrite the file if it already exists.


.. py:function:: get_stacked_images(out_directory)

   Unpacked the stacked catalog images from `out_directory/cat/stacked_images.fits.gz`.

   Parameters
   ----------
   out_directory : Path
       The path to the directory containing the stacked images.

   Returns
   -------
   Dict[str, NDArray[np.float64]]
       The stacked images {filter: image}.