orca.transform.imaging
======================

.. py:module:: orca.transform.imaging

.. autoapi-nested-parse::

   Image generation transforms using WSClean.

   Provides functions for creating dirty images, movies from FITS sequences,
   integrated images, and Stokes I/V imaging from measurement sets.
   Uses WSClean for imaging and supports multi-frequency synthesis.



Attributes
----------

.. autoapisummary::

   orca.transform.imaging.logger
   orca.transform.imaging.CLEAN_MGAIN
   orca.transform.imaging.SUN_CHANNELS_OUT
   orca.transform.imaging.IMSIZE
   orca.transform.imaging.IM_SCALE_DEGREE


Functions
---------

.. autoapisummary::

   orca.transform.imaging.make_movie_from_fits
   orca.transform.imaging.integrated_image
   orca.transform.imaging.make_dirty_image
   orca.transform.imaging.reproject_fits
   orca.transform.imaging.stack_images
   orca.transform.imaging.stokes_IV_imaging
   orca.transform.imaging.coadd_fits


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

.. py:data:: logger

.. py:data:: CLEAN_MGAIN
   :value: 0.8


.. py:data:: SUN_CHANNELS_OUT
   :value: 2


.. py:data:: IMSIZE
   :value: 4096


.. py:data:: IM_SCALE_DEGREE
   :value: 0.03125


.. py:function:: make_movie_from_fits(fits_tuple: Tuple[str], output_dir: str, scale: float, output_filename: Optional[str] = None) -> str

   Create an MP4 movie from a sequence of FITS images.

   Uses matplotlib to render each frame and ffmpeg to encode the movie.

   :param fits_tuple: Ordered sequence of paths to FITS image files.
   :param output_dir: Directory to save the output movie.
   :param scale: Symmetric color scale for image display (-scale to +scale).
   :param output_filename: Optional output filename. Defaults to input basename + .mp4.

   :returns: Path to the generated movie file.


.. py:function:: integrated_image(msl: List[str])

   Create an integrated image from multiple measurement sets.

   :param msl: List of measurement set paths.

   .. note:: Not yet implemented.


.. py:function:: make_dirty_image(ms_list: List[str], output_dir: str, output_prefix: str, make_psf: bool = False, briggs: float = 0, inner_tukey: Optional[int] = None, n_thread: int = 10, more_args: Optional[List[str]] = None) -> Union[str, Tuple[str, str]]

   Make dirty image from a list of measurement sets using WSClean.

   Creates a dirty (non-deconvolved) image with specified weighting scheme.
   Optionally generates the PSF image as well.

   :param ms_list: List of measurement set paths to image.
   :param output_dir: Directory for output images.
   :param output_prefix: Prefix for output filenames.
   :param make_psf: If True, also generate the PSF image at 2x size.
   :param briggs: Briggs robust weighting parameter (-2 to 2).
   :param inner_tukey: Inner Tukey taper width in wavelengths.
   :param n_thread: Number of threads for WSClean.
   :param more_args: Additional WSClean arguments.

   :returns: If make_psf is True, tuple of (image_path, psf_path).
             Otherwise, just the image path.


.. py:function:: reproject_fits(fits_path1: str, fits_path2: str, output_path: Union[str, None] = None) -> Union[str, numpy.ndarray]

   Reproject one fits image to wcs of another.

   :param fits_path1: fits file of reference image
   :param fits_path2: fits file to be reprojected
   :param output_path: output for reprojected fits image (optional)

   :returns: path to reprojected fits image if output_path is not None, else the numpy array of the reprojected image.


.. py:function:: stack_images(fits_list: List[str], output_path: str)

   Stacks images in fits_list and writes to output_path.

   :param fits_list: list of fits files to be stacked
   :param output_path: output path (including name)


.. py:function:: stokes_IV_imaging(spw_list: List[str], start_time: datetime.datetime, end_time: datetime.datetime, source_dir: str, work_dir: str, scratch_dir: str, phase_center: Optional[astropy.coordinates.SkyCoord] = None, taper_inner_tukey: int = 30, make_snapshots: bool = False, keep_scratch_dir: bool = False, partitioned_by_hour: bool = True)

   Generate Stokes I and V images from calibrated measurement sets.

   Celery task that applies calibration, flags, integrates across spectral
   windows, and produces Stokes I/V images. Can optionally generate snapshot
   images for each timestep.

   :param spw_list: List of spectral window identifiers.
   :param start_time: Start of the observation time range.
   :param end_time: End of the observation time range.
   :param source_dir: Directory containing source measurement sets.
   :param work_dir: Working directory for intermediate products.
   :param scratch_dir: Scratch directory for temporary files.
   :param phase_center: Optional phase center for imaging. Defaults to zenith.
   :param taper_inner_tukey: Inner Tukey taper width in wavelengths.
   :param make_snapshots: If True, produce per-timestep snapshot images.
   :param keep_scratch_dir: If True, don't delete temporary directory.
   :param partitioned_by_hour: Whether data is partitioned by hour.

   :returns: None. Writes output images to work_dir.


.. py:function:: coadd_fits(fits_list: List[str], output_path: str) -> Optional[str]

   Co-add multiple FITS images by averaging.

   Computes the mean of all input images pixel-by-pixel.
   Header is taken from the first image.

   :param fits_list: List of paths to FITS images to co-add.
   :param output_path: Output path for the averaged image.

   :returns: Output path on success, None if fewer than 2 images provided.