essimaging 24.9.0__py3-none-any.whl

ess/imaging/__init__.py

@@ -0,0 +1,12 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2024 Scipp contributors (https://github.com/scipp)
+# ruff: noqa: E402, F401
+
+import importlib.metadata
+
+try:
+    __version__ = importlib.metadata.version("essimaging")
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0"
+
+del importlib

ess/imaging/data.py

@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2024 Scipp contributors (https://github.com/scipp)
+import pathlib
+
+import pooch
+
+_version = '0'
+
+
+def _make_pooch():
+    return pooch.create(
+        path=pooch.os_cache('essimaging'),
+        env='BEAMLIME_DATA_DIR',
+        retry_if_failed=3,
+        base_url='https://public.esss.dk/groups/scipp/ess/imaging/',
+        version=_version,
+        registry={
+            'small_ymir_images.hdf': 'md5:cf83695d5da29e686c10a31b402b8bdb',
+            'README.md': 'md5:0f375972d4008de6060b065ac13ba17f',
+        },
+    )
+
+
+_pooch = _make_pooch()
+_pooch.fetch('README.md')
+
+
+def get_path(name: str) -> pathlib.Path:
+    """
+    Return the path to a data file bundled with ess.imaging test helpers.
+
+    This function only works with example data and cannot handle
+    paths to custom files.
+    """
+
+    return pathlib.Path(_pooch.fetch(name))
+
+
+def get_ymir_images_path() -> pathlib.Path:
+    """
+    Return the path to the small YMIR images HDF5 file.
+    """
+
+    return get_path('small_ymir_images.hdf')

ess/imaging/io.py

@@ -0,0 +1,360 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2024 Scipp contributors (https://github.com/scipp)
+import warnings
+from collections.abc import Callable, Generator, Iterable
+from enum import Enum
+from itertools import pairwise
+from pathlib import Path
+from typing import NewType
+
+import scipp as sc
+import scippnexus as snx
+from tifffile import imwrite
+
+from ess.reduce.nexus.types import FilePath
+
+from .types import (
+    DEFAULT_HISTOGRAM_PATH,
+    HistogramModeDetectorsPath,
+    ImageDetectorName,
+    ImageKeyLogs,
+    RotationLogs,
+    RotationMotionSensorName,
+)
+
+FileLock = NewType("FileLock", bool)
+"""File lock mode for reading nexus file."""
+DEFAULT_FILE_LOCK = FileLock(True)
+
+HistogramModeDetector = NewType("HistogramModeDetector", sc.DataGroup)
+"""Histogram mode detector data group."""
+HistogramModeDetectorData = NewType("HistogramModeDetectorData", sc.DataArray)
+"""Histogram mode detector data."""
+ImageKeyCoord = NewType("ImageKeyCoord", sc.Variable)
+"""Image key coordinate."""
+SampleImageStacksWithLogs = NewType("SampleImageStacksWithLogs", sc.DataArray)
+"""Raw image stacks separated by ImageKey values via timestamp."""
+RotationAngleCoord = NewType("RotationAngleCoord", sc.Variable)
+"""Rotation angle coordinate."""
+
+RawSampleImageStacks = NewType("RawSampleImageStacks", sc.DataArray)
+"""Sample image stacks."""
+OpenBeamImageStacks = NewType("OpenBeamImageStacks", sc.DataArray)
+"""Open beam image stacks."""
+DarkCurrentImageStacks = NewType("DarkCurrentImageStacks", sc.DataArray)
+"""Dark current image stacks."""
+
+
+IMAGE_KEY_COORD_NAME = "image_key"
+"""Image key coordinate name."""
+TIME_COORD_NAME = "time"
+"""Time coordinate name."""
+ROTATION_ANGLE_COORD_NAME = "rotation_angle"
+"""Rotation angle coordinate name."""
+DIM1_COORD_NAME = "dim_1"
+"""Dimension 1 coordinate name."""
+DIM2_COORD_NAME = "dim_2"
+"""Dimension 2 coordinate name."""
+
+
+class ImageKey(Enum):
+    """Image key values."""
+
+    SAMPLE = 0
+    OPEN_BEAM = 1
+    DARK_CURRENT = 2
+
+    @classmethod
+    def as_index(cls, key: "ImageKey", target_da: sc.DataArray | None) -> sc.Variable:
+        if target_da is None:
+            return sc.scalar(cls(key).value, unit=None)
+        elif IMAGE_KEY_COORD_NAME in target_da.coords:
+            return sc.scalar(
+                cls(key).value,
+                unit=target_da.coords[IMAGE_KEY_COORD_NAME].unit,
+                dtype=target_da.coords[IMAGE_KEY_COORD_NAME].dtype,
+            )
+        else:
+            return sc.scalar(cls(key).value, unit=target_da.unit, dtype=target_da.dtype)
+
+
+def load_nexus_histogram_mode_detector(
+    *,
+    file_path: FilePath,
+    image_detector_name: ImageDetectorName,
+    histogram_mode_detectors_path: HistogramModeDetectorsPath = DEFAULT_HISTOGRAM_PATH,
+    locking: FileLock = DEFAULT_FILE_LOCK,
+) -> HistogramModeDetector:
+    try:
+        with snx.File(file_path, mode="r", locking=locking) as f:
+            img_path = f"{histogram_mode_detectors_path}/{image_detector_name}"
+            dg: sc.DataGroup = f[img_path][()]
+    except PermissionError as e:
+        raise PermissionError(
+            f"Permission denied to read the nexus file [{file_path}]. "
+            "Please check the permission of the file or the directory. "
+            "Consider using the `file_lock` parameter to avoid file locking "
+            "if the file system is mounted on a network file system. "
+            "and it is safe to read the file without locking."
+        ) from e
+
+    # Manually assign unit to the histogram detector mode data
+    img: sc.DataArray = dg['data']
+    if (original_unit := img.unit) != 'counts':
+        img.unit = 'counts'
+        warnings.warn(
+            f"The unit of the histogram detector data is [{original_unit}]. "
+            f"It is expected to be [{img.unit}]. "
+            f"The loader manually assigned the unit to be [{img.unit}].",
+            stacklevel=0,
+        )
+    return HistogramModeDetector(dg)
+
+
+MinDim1 = NewType("MinDim1", sc.Variable | None)
+"""Minimum value of the first dimension."""
+MaxDim1 = NewType("MaxDim1", sc.Variable | None)
+"""Maximum value of the first dimension."""
+MinDim2 = NewType("MinDim2", sc.Variable | None)
+"""Minimum value of the second dimension."""
+MaxDim2 = NewType("MaxDim2", sc.Variable | None)
+
+
+def _make_coord_if_needed(da: sc.DataArray, dim: str) -> None:
+    if dim not in da.coords.keys():
+        da.coords[dim] = sc.arange(dim=dim, start=0, stop=da.sizes[dim])
+
+
+def separate_detector_images(
+    dg: HistogramModeDetector,
+    min_dim_1: MinDim1,
+    max_dim_1: MaxDim1,
+    min_dim_2: MinDim2,
+    max_dim_2: MaxDim2,
+) -> HistogramModeDetectorData:
+    da: sc.DataArray = sc.sort(dg['data'], 'time')
+    # Assign position coordinates to the detector data
+    _make_coord_if_needed(da, DIM1_COORD_NAME)
+    _make_coord_if_needed(da, DIM2_COORD_NAME)
+    # Crop the detector data by the given coordinates
+    da = da[DIM1_COORD_NAME, min_dim_1:max_dim_1][DIM2_COORD_NAME, min_dim_2:max_dim_2]
+    return HistogramModeDetectorData(da)
+
+
+def separate_image_key_logs(*, dg: HistogramModeDetector) -> ImageKeyLogs:
+    return ImageKeyLogs(sc.sort(dg['image_key']['value'], key='time'))
+
+
+def load_nexus_rotation_logs(
+    file_path: FilePath,
+    motion_sensor_name: RotationMotionSensorName,
+    locking: FileLock = DEFAULT_FILE_LOCK,
+) -> RotationLogs:
+    log_path = f"entry/instrument/{motion_sensor_name}/rotation_stage_readback"
+    with snx.File(file_path, mode="r", locking=locking) as f:
+        return RotationLogs(f[log_path][()]['value'])
+
+
+def derive_log_coord_by_range(da: sc.DataArray, log: sc.DataArray) -> sc.Variable:
+    """Sort the logs by time and decide which log entry corresponds to each time bin.
+
+    It assumes a log value is valid until the next log entry.
+    """
+    log = sc.sort(log, TIME_COORD_NAME)
+    indices = [*log.coords[TIME_COORD_NAME], None]
+    return sc.concat(
+        [
+            sc.broadcast(
+                log.data[TIME_COORD_NAME, i_time],
+                dims=[TIME_COORD_NAME],
+                shape=(da[TIME_COORD_NAME, start:end].sizes[TIME_COORD_NAME],),
+            )
+            for i_time, (start, end) in enumerate(pairwise(indices))
+        ],
+        TIME_COORD_NAME,
+    )
+
+
+def _slice_da_by_keys(
+    da: sc.DataArray, image_keys: ImageKeyLogs, image_key: ImageKey
+) -> Generator[sc.DataArray, None, None]:
+    matching_value = image_key.as_index(image_key, image_keys)
+    time_coord = image_keys.coords[TIME_COORD_NAME]
+    time_intervals = image_keys.sizes[TIME_COORD_NAME]
+    for i_time, (cur_time, image_key) in enumerate(
+        zip(time_coord, image_keys.data, strict=True)
+    ):
+        if image_key == matching_value:
+            if i_time == time_intervals - 1:
+                yield da[TIME_COORD_NAME, cur_time:]
+            else:
+                next_time = time_coord[i_time + 1]
+                yield da[TIME_COORD_NAME, cur_time:next_time]
+
+
+def _retrieve_image_stacks_by_key(
+    da: HistogramModeDetectorData, image_keys: ImageKeyLogs, image_key: ImageKey
+) -> sc.DataArray:
+    images = [
+        sliced_da
+        for sliced_da in _slice_da_by_keys(da, image_keys, image_key)
+        if da.sizes[TIME_COORD_NAME] > 0
+    ]
+    if len(images) == 0:
+        raise ValueError(f"No images found for {image_key}.")
+    elif len(images) == 1:
+        return images[0]
+    return sc.concat(images, 'time')
+
+
+AllImageStacks = NewType("AllImageStacks", dict[ImageKey, sc.DataArray])
+
+
+def separate_image_by_keys(
+    da: HistogramModeDetectorData,
+    image_keys: ImageKeyLogs,
+) -> AllImageStacks:
+    return AllImageStacks(
+        {key: _retrieve_image_stacks_by_key(da, image_keys, key) for key in ImageKey}
+    )
+
+
+def retrieve_open_beam_images(
+    da: HistogramModeDetectorData, image_keys: ImageKeyLogs
+) -> OpenBeamImageStacks:
+    return OpenBeamImageStacks(
+        _retrieve_image_stacks_by_key(da, image_keys, ImageKey.OPEN_BEAM)
+    )
+
+
+def retrieve_dark_current_images(
+    da: HistogramModeDetectorData, image_keys: ImageKeyLogs
+) -> DarkCurrentImageStacks:
+    return DarkCurrentImageStacks(
+        _retrieve_image_stacks_by_key(da, image_keys, ImageKey.DARK_CURRENT)
+    )
+
+
+def retrieve_sample_images(
+    da: HistogramModeDetectorData, image_keys: ImageKeyLogs
+) -> RawSampleImageStacks:
+    return RawSampleImageStacks(
+        _retrieve_image_stacks_by_key(da, image_keys, ImageKey.SAMPLE)
+    )
+
+
+def apply_logs_as_coords(
+    samples: RawSampleImageStacks, rotation_angles: RotationLogs
+) -> SampleImageStacksWithLogs:
+    # Make sure the data has the same range as the rotation angle coordinate
+    min_log_time = rotation_angles.coords[TIME_COORD_NAME].min(TIME_COORD_NAME)
+    sliced = samples[TIME_COORD_NAME, min_log_time:].copy(deep=False)
+    if sliced.sizes != samples.sizes:
+        warnings.warn(
+            "The sample data has been sliced to match the rotation angle coordinate.",
+            stacklevel=0,
+        )
+    rotation_angle_coord = derive_log_coord_by_range(samples, rotation_angles)
+    sliced.coords['rotation_angle'] = rotation_angle_coord
+    return SampleImageStacksWithLogs(sliced)
+
+
+DEFAULT_IMAGE_NAME_PREFIX_MAP = {
+    ImageKey.SAMPLE: "sample",
+    ImageKey.DARK_CURRENT: "dc",
+    ImageKey.OPEN_BEAM: "ob",
+}
+
+
+def dummy_progress_wrapper(core_iterator: Iterable) -> Iterable:
+    yield from core_iterator
+
+
+def _save_merged_images(
+    *, image_stacks: SampleImageStacksWithLogs, image_prefix: str, output_dir: Path
+) -> None:
+    image_path = output_dir / Path(
+        f"{image_prefix}_0000_{image_stacks.sizes['time']:04d}.tiff"
+    )
+    imwrite(image_path, image_stacks.values)
+
+
+def _save_individual_images(
+    *,
+    image_stacks: SampleImageStacksWithLogs,
+    image_prefix: str,
+    output_dir: Path,
+    progress_wrapper: Callable[[Iterable], Iterable] = dummy_progress_wrapper,
+) -> None:
+    for i_image in progress_wrapper(range(image_stacks.sizes['time'])):
+        cur_image = image_stacks['time', i_image]
+        image_path = output_dir / Path(f"{image_prefix}_{i_image:04d}.tiff")
+        imwrite(image_path, cur_image.values)
+
+
+def _validate_output_dir(output_dir: str | Path) -> None:
+    output_dir = Path(output_dir)
+    if not output_dir.exists():
+        # make sure the output directory exists
+        output_dir.mkdir(parents=True, exist_ok=False)
+    elif not output_dir.is_dir():
+        raise ValueError(f"Output directory {output_dir} is not a directory.")
+    elif next(output_dir.iterdir(), None) is not None:
+        raise RuntimeError(f"Output directory {output_dir} is not empty.")
+
+
+def export_image_stacks_as_tiff(
+    *,
+    output_dir: str | Path,
+    image_stacks: AllImageStacks,
+    merge_image_by_key: bool,
+    overwrite: bool,
+    progress_wrapper: Callable[[Iterable], Iterable] = dummy_progress_wrapper,
+    image_prefix_map: dict[ImageKey, str] = DEFAULT_IMAGE_NAME_PREFIX_MAP,
+) -> None:
+    """Save images into disk.
+
+    Parameters
+    ----------
+    output_dir:
+        Output directory to save images.
+
+    image_stacks:
+        Image stacks to save.
+
+    merge_image_by_key:
+        Flag to merge images into one file.
+
+    overwrite:
+        Flag to overwrite existing files.
+        If True, it will clear the output directory before saving images.
+
+    image_prefix_map:
+        Map of image name prefixes to their corresponding image key.
+
+    """
+    # Remove existing files if overwrite is True
+    if (
+        overwrite
+        and (output_path := Path(output_dir)).exists()
+        and output_path.is_dir()
+    ):
+        for file in output_path.iterdir():
+            file.unlink()
+
+    _validate_output_dir(output_path)
+
+    for image_key, cur_images in progress_wrapper(image_stacks.items()):
+        if merge_image_by_key:
+            _save_merged_images(
+                image_stacks=SampleImageStacksWithLogs(cur_images),
+                image_prefix=image_prefix_map[image_key],
+                output_dir=output_path,
+            )
+        else:
+            _save_individual_images(
+                image_stacks=SampleImageStacksWithLogs(cur_images),
+                image_prefix=image_prefix_map[image_key],
+                output_dir=output_path,
+                progress_wrapper=progress_wrapper,
+            )

ess/imaging/normalize.py

@@ -0,0 +1,262 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2024 Scipp contributors (https://github.com/scipp)
+
+import warnings
+from typing import NewType
+
+import scipp as sc
+
+from .io import (
+    TIME_COORD_NAME,
+    DarkCurrentImageStacks,
+    OpenBeamImageStacks,
+    SampleImageStacksWithLogs,
+)
+
+AverageBackgroundPixelCounts = NewType("AverageBackgroundPixelCounts", sc.Variable)
+"""mean(background)."""
+AverageSamplePixelCounts = NewType("AverageSamplePixelCounts", sc.Variable)
+"""mean(sample)."""
+ScaleFactor = NewType("ScaleFactor", sc.Variable)
+"""AverageBackgroundPixelCounts / AverageSamplePixelCounts."""
+
+OpenBeamImage = NewType("OpenBeamImage", sc.DataArray)
+"""Open beam image. mean(OpenBeam)"""
+DarkCurrentImage = NewType("DarkCurrentImage", sc.DataArray)
+"""Dark current image. mean(DarkCurrentImages)"""
+CleansedOpenBeamImage = NewType("CleansedOpenBeamImage", sc.DataArray)
+"""OpenBeam - DarkCrrent"""
+CleansedSampleImages = NewType("CleansedSampleImages", sc.DataArray)
+"""SampleImageStack - DarkCurrent"""
+SampleImageStacks = NewType("SampleImageStacks", sc.DataArray)
+"""Sample image stack ready to be used for normalization."""
+BackgroundImage = NewType("BackgroundImage", sc.DataArray)
+"""Background image ready to be used for normalization."""
+NormalizedSampleImages = NewType("NormalizedSampleImages", sc.DataArray)
+"""Normalized sample image stack. SampleImages / Background * ScaleFactor"""
+
+
+BackgroundPixelThreshold = NewType("BackgroundPixelThreshold", sc.Variable)
+"""Threshold of the background pixel values."""
+SamplePixelThreshold = NewType("SamplePixelThreshold", sc.Variable)
+"""Threshold of the sample pixel values."""
+
+
+def _warn_constant_exposure_time(target: str) -> None:
+    warning_message = f"Computing {target.strip()} assuming constant exposure time."
+    warnings.warn(warning_message, stacklevel=1)
+
+
+def _mean_all_dims(data: sc.Variable) -> sc.Variable:
+    """Calculate the mean of all dimensions one by one to avoid overflow."""
+    if data.shape == ():  # scalar
+        return data
+    return _mean_all_dims(data.mean(dim=data.dims[0]))
+
+
+def average_open_beam_images(open_beam: OpenBeamImageStacks) -> OpenBeamImage:
+    """Average the open beam image stack.
+
+    .. math::
+
+        OpenBeam = mean(OpenBeam, dim=\\text{'time'})
+
+    """
+    _warn_constant_exposure_time("average open beam image")
+    return OpenBeamImage(sc.mean(open_beam, dim=TIME_COORD_NAME))
+
+
+def average_dark_current_images(
+    dark_current: DarkCurrentImageStacks,
+) -> DarkCurrentImage:
+    """Average the dark current image stack.
+
+    .. math::
+
+        DarkCurrent = mean(DarkCurrent, dim=\\text{'time'})
+
+    """
+    _warn_constant_exposure_time("average dark current image")
+    return DarkCurrentImage(sc.mean(dark_current, dim=TIME_COORD_NAME))
+
+
+def cleanse_open_beam_image(
+    open_beam: OpenBeamImage, dark_current: DarkCurrentImage
+) -> CleansedOpenBeamImage:
+    """Calculate the background image stack.
+
+    .. math::
+
+        Background = OpenBeam - DarkCurrent
+
+    Parameters
+    ----------
+    open_beam:
+        Open beam image.
+
+    dark_current:
+        Dark current image.
+
+    """
+    return CleansedOpenBeamImage(open_beam - dark_current)
+
+
+def cleanse_sample_images(
+    sample_images: SampleImageStacksWithLogs, dark_current: DarkCurrentImage
+) -> CleansedSampleImages:
+    """Cleanse the sample image stack.
+
+    We subtract the averaged dark current image from the sample image stack.
+
+    .. math::
+
+        CleansedSample_{i} = Sample_{i} - mean(DarkCurrent, dim=\\text{'time'})
+
+        \\text{where } i \\text{ is an index of an image.}
+
+    Parameters
+    ------
+    sample_images:
+        Sample image stack.
+
+    dark_current:
+        Dark current image.
+
+    """
+    return CleansedSampleImages(sample_images - dark_current)
+
+
+def average_background_pixel_counts(
+    background: BackgroundImage,
+) -> AverageBackgroundPixelCounts:
+    """Calculate the average background pixel counts."""
+    _warn_constant_exposure_time("average background pixel counts")
+    return AverageBackgroundPixelCounts(background.data.mean())
+
+
+def average_sample_pixel_counts(
+    sample_images: SampleImageStacks,
+) -> AverageSamplePixelCounts:
+    """Calculate the average sample pixel counts.
+
+    Notes
+    -----
+    For performance reason, we tried calculating
+    the mean of sample images and dark current images
+    first and subtract them afterwards,
+    instead of using the subtracted image stack directly.
+    It was to utilize that the integer operation is faster than
+    the floating point operation.
+
+    However, we are ceiling negative values to zero
+    after cleansing the sample images with dark current images.
+
+    Therefore we need to calculate the mean of the cleansed sample images
+    to avoid negative values in the average calculation.
+
+    We don't calculate ``mean(cleansed_sample_images)`` at once
+    since it is a large array and it may cause memory issues.
+
+    There was an example of 361 images of 2048x2048 pixels with 32-bit integer data
+    exceeded the limit of the maximum integer so the average calculation failed
+    and returned negative values.
+    """
+    _warn_constant_exposure_time("average sample pixel counts")
+    return AverageSamplePixelCounts(_mean_all_dims(sample_images.data))
+
+
+def calculate_scale_factor(
+    average_bg: AverageBackgroundPixelCounts, average_sample: AverageSamplePixelCounts
+) -> ScaleFactor:
+    """Calculate the scale factor from average background and sample pixel counts.
+
+    .. math::
+
+            ScaleFactor = AverageBackgroundPixelCounts / AverageSamplePixelCounts
+
+    """
+    return ScaleFactor(average_bg / average_sample)
+
+
+def apply_threshold_to_sample_images(
+    samples: CleansedSampleImages, sample_threshold: SamplePixelThreshold
+) -> SampleImageStacks:
+    """Apply the threshold to the sample image stack.
+
+    Parameters
+    ----------
+    samples:
+        Sample image stack.
+
+    sample_threshold:
+        Threshold for the sample pixel values.
+        Any pixel values less than ``sample_threshold``
+        are replaced with ``sample_threshold``.
+
+    """
+    samples = CleansedSampleImages(samples.copy(deep=False))
+    samples.data = sc.where(
+        samples.data < sample_threshold, sample_threshold, samples.data
+    )
+    return SampleImageStacks(samples)
+
+
+def apply_threshold_to_background_image(
+    background: CleansedOpenBeamImage, background_threshold: BackgroundPixelThreshold
+) -> BackgroundImage:
+    """Apply the threshold to the background image.
+
+    Parameters
+    ----------
+    background:
+        Background image.
+
+    background_threshold:
+        Threshold for the background pixel values.
+        Any pixel values less than ``background_threshold``
+        are replaced with ``background_threshold``.
+
+    """
+    background = CleansedOpenBeamImage(background.copy(deep=False))
+    background.data = sc.where(
+        background.data < background_threshold, background_threshold, background.data
+    )
+    return BackgroundImage(background)
+
+
+def normalize_sample_images(
+    *, samples: SampleImageStacks, background: BackgroundImage, factor: ScaleFactor
+) -> NormalizedSampleImages:
+    """Normalize the sample image stack.
+
+    .. math::
+
+            NormalizedImages = SampleImages / Background * ScaleFactor
+
+    Parameters
+    ----------
+
+    samples:
+        Sample image stack to be normalized.
+
+    background:
+        Background image to be used for normalization.
+
+    factor:
+        Scale factor for the normalization.
+
+
+    Raises
+    ------
+    ValueError:
+        If the scale factor is negative.
+        It is for the safety of the calculation on short data type.
+        Depending on how you calculate the scale factor,
+        the operation might fail and return negative values.
+
+    """
+    if factor < 0:
+        raise ValueError(f"Scale factor must be positive, but got {factor}.")
+    _warn_constant_exposure_time("normalized sample image stack")
+    # For performance reason, background / factor is calculated first.
+    return NormalizedSampleImages(samples / (background / factor))

ess/imaging/types.py

@@ -0,0 +1,24 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2024 Scipp contributors (https://github.com/scipp)
+from typing import NewType
+
+import scipp as sc
+
+ImageDetectorName = NewType('ImageDetectorName', str)
+"""Histogram mode detector name."""
+
+ImageKeyLogs = NewType('ImageKeyLogs', sc.DataArray)
+"""Image key logs."""
+
+RotationMotionSensorName = NewType('RotationMotionSensorName', str)
+"""Rotation sensor name."""
+
+RotationLogs = NewType('RotationLogs', sc.DataArray)
+"""Rotation logs data."""
+
+HistogramModeDetectorsPath = NewType('HistogramModeDetectorsPath', str)
+"""Path to the histogram mode detectors in a nexus file."""
+
+DEFAULT_HISTOGRAM_PATH = HistogramModeDetectorsPath(
+    "/entry/instrument/histogram_mode_detectors"
+)

ess/imaging/workflow.py

@@ -0,0 +1,121 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2024 Scipp contributors (https://github.com/scipp)
+import sciline as sl
+import scipp as sc
+
+from .io import (
+    DEFAULT_FILE_LOCK,
+    FileLock,
+    MaxDim1,
+    MaxDim2,
+    MinDim1,
+    MinDim2,
+    apply_logs_as_coords,
+    load_nexus_histogram_mode_detector,
+    load_nexus_rotation_logs,
+    retrieve_dark_current_images,
+    retrieve_open_beam_images,
+    retrieve_sample_images,
+    separate_detector_images,
+    separate_image_by_keys,
+    separate_image_key_logs,
+)
+from .normalize import (
+    BackgroundPixelThreshold,
+    SamplePixelThreshold,
+    apply_threshold_to_background_image,
+    apply_threshold_to_sample_images,
+    average_background_pixel_counts,
+    average_dark_current_images,
+    average_open_beam_images,
+    average_sample_pixel_counts,
+    calculate_scale_factor,
+    cleanse_open_beam_image,
+    cleanse_sample_images,
+    normalize_sample_images,
+)
+from .types import (
+    DEFAULT_HISTOGRAM_PATH,
+    HistogramModeDetectorsPath,
+    ImageDetectorName,
+    RotationMotionSensorName,
+)
+
+_IO_PROVIDERS = (
+    apply_logs_as_coords,
+    load_nexus_histogram_mode_detector,
+    load_nexus_rotation_logs,
+    retrieve_dark_current_images,
+    retrieve_open_beam_images,
+    retrieve_sample_images,
+    separate_detector_images,
+    separate_image_by_keys,
+    separate_image_key_logs,
+)
+_NORMALIZATION_PROVIDERS = (
+    apply_threshold_to_background_image,
+    apply_threshold_to_sample_images,
+    average_background_pixel_counts,
+    average_dark_current_images,
+    average_open_beam_images,
+    average_sample_pixel_counts,
+    calculate_scale_factor,
+    cleanse_open_beam_image,
+    cleanse_sample_images,
+    normalize_sample_images,
+)
+_DEFAULT_BACKGROUND_THRESHOLD = BackgroundPixelThreshold(sc.scalar(1.0, unit="counts"))
+_DEFAULT_SAMPLE_THRESHOLD = SamplePixelThreshold(sc.scalar(0.0, unit="counts"))
+
+
+def YmirImageNormalizationWorkflow() -> sl.Pipeline:
+    """
+    Ymir histogram mode imaging normalization workflow.
+
+    Default Normalization Formula
+    -----------------------------
+
+    .. math::
+
+        NormalizedSample_{i} = SampleImageStacks_{i} / BackgroundImage * ScaleFactor
+
+
+    .. math::
+
+        ScaleFactor = AverageBackgroundPixelCounts / AverageSamplePixelCounts
+
+
+    .. math::
+
+        SampleImageStacks_{i} = Sample_{i} - mean(DarkCurrent, dim=\\text{'time'})
+
+        \\text{where } i \\text{ is an index of an image.}
+
+        \\text{Pixel values less than sample_threshold}
+
+        \\text{ are replaced with sample_threshold}.
+
+    .. math::
+
+        BackgroundImage = mean(OpenBeam, dim=\\text{'time'})
+        - mean(DarkCurrent, dim=\\text{'time'})
+
+        \\text{Pixel values less than } \\text{background_threshold}
+
+        \\text{ are replaced with } \\text{background_threshold}.
+    """
+    return sl.Pipeline(
+        (*_IO_PROVIDERS, *_NORMALIZATION_PROVIDERS),
+        params={
+            MinDim1: MinDim1(None),
+            MaxDim1: MaxDim1(None),
+            MinDim2: MinDim2(None),
+            MaxDim2: MaxDim2(None),
+            HistogramModeDetectorsPath: DEFAULT_HISTOGRAM_PATH,
+            ImageDetectorName: ImageDetectorName('orca'),
+            RotationMotionSensorName: RotationMotionSensorName('motion_cabinet_2'),
+            BackgroundPixelThreshold: _DEFAULT_BACKGROUND_THRESHOLD,
+            SamplePixelThreshold: _DEFAULT_SAMPLE_THRESHOLD,
+            FileLock: DEFAULT_FILE_LOCK,
+        },
+    )

essimaging-24.9.0.dist-info/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2024, Scipp contributors (https://github.com/scipp)
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

essimaging-24.9.0.dist-info/METADATA

@@ -0,0 +1,80 @@
+Metadata-Version: 2.1
+Name: essimaging
+Version: 24.9.0
+Summary: Imaging data reduction for the European Spallation Source
+Author: Scipp contributors
+License: BSD 3-Clause License
+        
+        Copyright (c) 2024, Scipp contributors (https://github.com/scipp)
+        All rights reserved.
+        
+        Redistribution and use in source and binary forms, with or without
+        modification, are permitted provided that the following conditions are met:
+        
+        1. Redistributions of source code must retain the above copyright notice, this
+           list of conditions and the following disclaimer.
+        
+        2. Redistributions in binary form must reproduce the above copyright notice,
+           this list of conditions and the following disclaimer in the documentation
+           and/or other materials provided with the distribution.
+        
+        3. Neither the name of the copyright holder nor the names of its
+           contributors may be used to endorse or promote products derived from
+           this software without specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+        
+Project-URL: Bug Tracker, https://github.com/scipp/essimaging/issues
+Project-URL: Documentation, https://scipp.github.io/essimaging
+Project-URL: Source, https://github.com/scipp/essimaging
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: dask
+Requires-Dist: graphviz
+Requires-Dist: plopp[all]
+Requires-Dist: sciline >=23.9.1
+Requires-Dist: scipp >=23.8.0
+Requires-Dist: scippnexus >=23.11.1
+Requires-Dist: essreduce
+Requires-Dist: tifffile
+Provides-Extra: test
+Requires-Dist: pytest ; extra == 'test'
+Requires-Dist: pooch ; extra == 'test'
+
+[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md)
+[![PyPI badge](http://img.shields.io/pypi/v/essimaging.svg)](https://pypi.python.org/pypi/essimaging)
+[![Anaconda-Server Badge](https://anaconda.org/scipp/essimaging/badges/version.svg)](https://anaconda.org/scipp/essimaging)
+[![License: BSD 3-Clause](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](LICENSE)
+
+# ESSimaging
+
+## About
+
+Imaging data reduction for the European Spallation Source
+
+## Installation
+
+```sh
+python -m pip install essimaging
+```

essimaging-24.9.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+ess/imaging/__init__.py,sha256=x8w4NyzTnfZ3IDYuwfo_TftgHFUgh2maZBR0Ej82_8w,313
+ess/imaging/data.py,sha256=OxKAm-NBSGOKWQ6AmHnnxMXBd3TR7WNyYqpERO_rZ9U,1060
+ess/imaging/io.py,sha256=hZku7nr0KYmxSnXxONGGvUZgrGQAe31zP9NYh0DiRa0,12203
+ess/imaging/normalize.py,sha256=uCI_PxoLN_M4wMxz0dYar-TosS4dzWvB0_jvGRcjxek,8084
+ess/imaging/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ess/imaging/types.py,sha256=HI3o6wcqRgszf5x7nx13xtjKqhyWNdf9C4qsIpu2Pvo,736
+ess/imaging/workflow.py,sha256=ImrA_jH-NmBGF6JpjtN2ASqVcwUE8ieZF_ktw5_et0k,3455
+essimaging-24.9.0.dist-info/LICENSE,sha256=nVEiume4Qj6jMYfSRjHTM2jtJ4FGu0g-5Sdh7osfEYw,1553
+essimaging-24.9.0.dist-info/METADATA,sha256=1swB3bGlyob0_zrXzLJtZpX7RrTzlmv2dwa-0BuSYRU,3637
+essimaging-24.9.0.dist-info/WHEEL,sha256=GV9aMThwP_4oNCtvEC2ec3qUYutgWeAzklro_0m4WJQ,91
+essimaging-24.9.0.dist-info/top_level.txt,sha256=0JxTCgMKPLKtp14wb1-RKisQPQWX7i96innZNvHBr-s,4
+essimaging-24.9.0.dist-info/RECORD,,

essimaging-24.9.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.1.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

essimaging-24.9.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ess