asi_core.image.hdr.pipeline

This module provides all processing steps for merging exposure series of all-sky images for high-dynamic range imaging.

Attributes

_EXPO_RE

Functions

_parse_exposure_from_name(→ Optional[int])

Parse exposure time (integer) from filename tail: *_<EXPO>.<ext>

_group_files_by_time(...)

Group image files found in directory by rounded timestamp (e.g., every 30s) into exposure brackets.

_save_response_plot(→ pathlib.Path)

Plot the camera log-response g(z) per channel and save the figure.

save_response_curve(→ None)

Save response curve to npz file in LOG domain (Debevec g(z)) with JSON-formatted metadata.

load_response_curve(→ numpy.ndarray)

Load response curve from npz, returning (256, C) in LOG domain and metadata dict.

calibrate_camera(→ numpy.ndarray)

Calibrate camera response (Debevec) from a subset of exposure brackets in a directory.

get_lne_range(→ Tuple[float, float])

Compute a global (min_lnE, max_lnE) using the saved NPZ response curve and all

create_and_save_hdr(img_series, exposure_times, ...)

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

process_timestamp(timestamp_group, root_dir, target_dir)

Process all images corresponding to a single timestamp.

process_hdr_series(asi_files, root_dir, target_dir[, ...])

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

process_directory(directory, save_dir[, round_ts_to, ...])

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

Module Contents

asi_core.image.hdr.pipeline._EXPO_RE
asi_core.image.hdr.pipeline._parse_exposure_from_name(name: str) → int | None

Parse exposure time (integer) from filename tail: *_<EXPO>.<ext>

asi_core.image.hdr.pipeline._group_files_by_time(directory: str | pathlib.Path, round_ts_to: str = '30s') → pandas.core.groupby.DataFrameGroupBy

Group image files found in directory by rounded timestamp (e.g., every 30s) into exposure brackets. Returns a pandas groupby indexed by the rounded timestamp.

asi_core.image.hdr.pipeline._save_response_plot(response: numpy.ndarray, out_path: str | pathlib.Path, include_mean: bool = True, dpi: int = 150) → pathlib.Path

Plot the camera log-response g(z) per channel and save the figure.

Parameters:

  • response (np.ndarray) – Response curve in LOG domain. Shape (256, 1, C) or (256, C).

  • out_path (str | Path) – Output image path (e.g., ‘response_curve.png’).

  • include_mean (bool) – If True, also plot the channel-mean curve. Default is True.

  • dpi (int) – Figure DPI. Default is 150.

Returns:

The saved file path.

Return type:

Path

asi_core.image.hdr.pipeline.save_response_curve(path: str | pathlib.Path, response: numpy.ndarray, metadata: dict = None, save_plot: bool = True, plot_filename: str = 'response_curve.jpg') → None

Save response curve to npz file in LOG domain (Debevec g(z)) with JSON-formatted metadata.

The response curve is stored in a .npz file with the key ‘response’ containing an array of shape (256, C), where C is the number of color channels. Metadata is saved as a JSON string under the key ‘metadata’.

If save_plot is True, a plot of the response curve is also saved as a JPEG file in the same directory.

Parameters:

  • path (str | Path) – The output file path for the .npz file.

  • response (np.ndarray) – The response curve data of shape (256, C) or (256, 1, C).

  • metadata (dict, optional) – A dictionary containing metadata to be saved with the curve.

  • save_plot (bool) – Whether to save a plot of the response curve.

  • plot_filename (str) – The filename of the plot of the response curve.

Returns:

None

Return type:

None

asi_core.image.hdr.pipeline.load_response_curve(path: str | pathlib.Path) → numpy.ndarray

Load response curve from npz, returning (256, C) in LOG domain and metadata dict.

asi_core.image.hdr.pipeline.calibrate_camera(image_dir: str | pathlib.Path, response_file: str | pathlib.Path, samples_per_image: int = 1000, sample_technique: str = 'random', max_processed_groups: int = 10, smoothness: float = 50.0, weight_type: str = 'triangle', low_clip: int = 5, high_clip: int = 250, seed: int | None = None, round_ts_to: str = '30s') → numpy.ndarray

Calibrate camera response (Debevec) from a subset of exposure brackets in a directory.

  • Groups files by rounded timestamp (e.g., every 30s).

  • For up to max_processed_groups groups:

    • parses and sorts images by exposure time,

    • samples P pixels (xs, ys),

    • builds stacks (P, N, C) across N exposures,

    • (optionally) clips dynamic range for stability,

    • calibrates response g(z) per channel.

  • Saves response to response_file (NPZ of shape (256, C), LOG domain).

  • Returns response as (256, 1, C) in LOG domain.

Notes: - Assumes filenames like: YYYYmmddHHMMSS_<EXPO>.<ext>, where <EXPO> is an integer.

Parameters:

  • image_dir (str | Path) – Directory containing image files grouped by timestamp.

  • response_file (str | Path) – Output file path for saving the calibrated response curve.

  • samples_per_image (int) – Number of pixel samples to extract from each image. Default is 1000.

  • sample_technique (str) – Sampling method ('random'` (default) | 'histogram'`).

  • max_processed_groups (int) – Maximum number of timestamp groups to process. Default is 10.

  • smoothness (float) – Smoothing factor for the response curve fitting. Default is 50.0.

  • weight_type (str) – Weighting function type for calibration (('triangle'` (default) | 'sine'`).

  • low_clip (int) – Lower intensity threshold to discard unreliable low values. Default is 5.

  • high_clip (int) – Upper intensity threshold to discard unreliable high values. Default is 250.

  • seed (Optional[int]) – Optional random seed for reproducibility.

  • round_ts_to (str) – Time resolution for grouping images (e.g., '30s' (default), '1min').

Returns:

Camera response curve in LOG domain with shape (256, 1, C).

Return type:

np.ndarray

asi_core.image.hdr.pipeline.get_lne_range(image_dir: str | pathlib.Path, response_file: str | pathlib.Path, round_ts_to: str = '30s') → Tuple[float, float]

Compute a global (min_lnE, max_lnE) using the saved NPZ response curve and all exposure times present in directory. Useful for consistent normalization.

Parameters:

  • image_dir (str | Path) – Directory containing image files grouped by timestamp.

  • response_file (str | Path) – Path to the saved NPZ response curve file.

  • round_ts_to (str) – Time resolution for grouping images (e.g., ’30s’ (default), ‘1min’).

Returns:

A tuple of (min_lnE, max_lnE) representing the global log exposure range.

Return type:

Tuple[float, float]

asi_core.image.hdr.pipeline.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.

Parameters:

  • img_series – List of images as NumPy arrays.

  • exposure_times – List of exposure times corresponding to the images.

  • output_path – Path where the HDR image will be saved.

  • kwargs_merging – Additional parameters for the merging function.

asi_core.image.hdr.pipeline.process_timestamp(timestamp_group, root_dir, target_dir)

Process all images corresponding to a single timestamp.

asi_core.image.hdr.pipeline.process_hdr_series(asi_files: pandas.Series, root_dir: str, target_dir: str, n_workers=0)

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

Parameters:

  • asi_files (pd.Series) – A multi-index Pandas Series where the index consists of timestamps and exposure times, and the values contain relative image paths.

  • root_dir (str) – The root directory containing all the source images.

  • target_dir (str) – The target directory where the generated HDR images will be stored (relative paths with respect to root_dir are retained).

  • n_workers (int, optional) – The number of parallel workers to use for processing. Defaults to 0 (no parallelism).

Returns:

A Pandas Series with timestamps as the index and generated HDR file paths as values.

Return type:

pd.Series

asi_core.image.hdr.pipeline.process_directory(directory, save_dir, round_ts_to='30s', response_file=None, **kwargs)

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

This function performs the following steps:

  1. Groups image files in the specified directory by timestamp with a given rounding interval.

  2. If a response file is provided, it loads the camera response curve.

  3. For each group of images with similar timestamps, it creates an HDR image.

  4. Saves the resulting HDR images to the specified output directory.

Parameters:

  • directory (str) – Path to the directory containing images.

  • save_dir (str) – Path to the directory where HDR images will be saved.

  • round_ts_to (str) – Time resolution for grouping images (e.g., ’30s’ (default), ‘1min’).

  • response_file (str, optional) – Path to the saved NPZ response curve file (optional).

  • kwargs (dict) – Additional keyword arguments passed to the HDR merging function.

Returns:

None

Return type:

None