asi_core.hdr_creation
=====================

.. py:module:: asi_core.hdr_creation

.. autoapi-nested-parse::

   This module provides functionality for all-sky imagers.



Functions
---------

.. autoapisummary::

   asi_core.hdr_creation.process_directory
   asi_core.hdr_creation.rescale_0_1
   asi_core.hdr_creation.correction_oversatured_regions
   asi_core.hdr_creation.merge_exposure_series
   asi_core.hdr_creation.create_and_save_hdr
   asi_core.hdr_creation.process_timestamp
   asi_core.hdr_creation.process_hdr_series


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

.. py:function:: process_directory(directory, save_dir)

   Processes a directory of images by grouping them into short time intervals and creating HDR images.

   :param directory: Path to the directory containing images.
   :param save_dir: Path to the directory where HDR images will be saved.


.. py:function:: rescale_0_1(image, min_val=None, max_val=None)

   Rescales an image to the range [0,1].

   :param image: Input image as a NumPy array.
   :param min_val: Minimum value for rescaling (optional).
   :param max_val: Maximum value for rescaling (optional).
   :return: Rescaled image with values between 0 and 1.


.. py:function:: correction_oversatured_regions(images, saturation=255)

   Corrects oversaturated regions in a series of images by setting all channels to maximum intensity.

   :param images: List of images as NumPy arrays.
   :param saturation: Saturation threshold (default: 255).
   :return: Tuple of corrected images and a mask indicating non-oversaturated regions.


.. py:function:: merge_exposure_series(img_series, exposure_times, algorithm='mertens', saturation=255, filetype='.jpg')

   Merges a series of images with different exposures into an HDR image.

   :param img_series: List of images as NumPy arrays.
   :param exposure_times: List of exposure times corresponding to the images.
   :param algorithm: HDR merging algorithm ('mertens' or 'debevec', default: 'mertens').
   :param saturation: Saturation threshold for correction (default: 255).
   :param filetype: Output file format ('.jpg', '.jp2', or '.png').
   :return: Merged HDR image as a NumPy array.


.. py:function:: create_and_save_hdr(img_series, exposure_times, output_path, **kwargs_merging)

   Creates an HDR image from a series of exposures and saves it to a file.

   :param img_series: List of images as NumPy arrays.
   :param exposure_times: List of exposure times corresponding to the images.
   :param output_path: Path where the HDR image will be saved.
   :param kwargs_merging: Additional parameters for the merging function.


.. py:function:: process_timestamp(timestamp_group, root_dir, target_dir)

   Process all images corresponding to a single timestamp.


.. py:function:: process_hdr_series(asi_files: pandas.Series, root_dir: str, target_dir: str, n_workers=0)

   Process a multi-index Pandas Series containing image paths in parallel to generate HDR images.

   :param asi_files: A multi-index Pandas Series where the index consists of timestamps and exposure times, and the values contain relative image paths.
   :type asi_files: pandas.Series
   :param root_dir: The root directory containing the source images.
   :type root_dir: str
   :param target_dir: The target directory where the generated HDR images will be stored.
   :type target_dir: str
   :param n_workers: The number of parallel workers to use for processing. Defaults to 0 (no parallelism).
   :type n_workers: int, optional
   :return: A Pandas Series with timestamps as the index and generated HDR file paths as values.
   :rtype: pandas.Series