Ymir imaging I/O helpers

docs/index.md

@@ -5,11 +5,24 @@
   </br></br>
 </span>
 
+## Imaging Data Reduction Examples
+````{card}
+
+```{button-ref} user-guide/histogram_mode_detector
+:class: stretched-link
+
+Ymir - Histogram Mode Detector
+
+```
+
+````
+
 ```{toctree}
 ---
 hidden:
 ---
 
+user-guide/index
 api-reference/index
 developer/index
 about/index

docs/user-guide/histogram_mode_detector.ipynb

@@ -0,0 +1,193 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Histogram Mode Detector\n",
+    "\n",
+    "## IO\n",
+    "\n",
+    "I/O providers can load white beam images and slice them according to the image key.\n",
+    "\n",
+    "Note that not like the ``rotation_angle``, ``image_key`` is not assigned as a coordinate.\n",
+    "\n",
+    "Instead, we slice the data according to the ``image_key`` and separate image stacks earlier due to performance limitation of 3-dimensional data binning.\n",
+    "\n",
+    "> For example, for 400 images of 2_048 x 2_048 pixels couldn't be done in the regular laptop."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from ess.imaging.data import get_ymir_images_path\n",
+    "from ess.imaging.io import (\n",
+    "    FilePath,\n",
+    "    SampleImageStacks,\n",
+    "    RawSampleImageStacks,\n",
+    "    OpenBeamImageStacks,\n",
+    "    DarkCurrentImageStacks,\n",
+    "    AllImageStacks,\n",
+    ")\n",
+    "from ess.imaging.workflow import (\n",
+    "    YmirWorkflow,\n",
+    "    ImageDetectorName,\n",
+    "    RotationMotionSensorName,\n",
+    ")\n",
+    "\n",
+    "wf = YmirWorkflow()\n",
+    "wf[FilePath] = get_ymir_images_path()\n",
+    "wf[ImageDetectorName] = 'orca'\n",
+    "wf[RotationMotionSensorName] = 'motion_cabinet_2'"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "image_stack_types = (\n",
+    "    AllImageStacks,\n",
+    "    RawSampleImageStacks,\n",
+    "    OpenBeamImageStacks,\n",
+    "    DarkCurrentImageStacks,\n",
+    "    SampleImageStacks,\n",
+    ")\n",
+    "wf.visualize(image_stack_types)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "results = wf.compute(image_stack_types)\n",
+    "results[SampleImageStacks]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Save Individual Frame"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from ess.imaging.io import export_image_stacks_as_tiff, ImageKey\n",
+    "\n",
+    "from pathlib import Path\n",
+    "from tqdm import tqdm\n",
+    "\n",
+    "\n",
+    "output_dir = Path(\"images\")\n",
+    "export_image_stacks_as_tiff(\n",
+    "    output_dir=output_dir,\n",
+    "    image_stacks=results[AllImageStacks],\n",
+    "    merge_image_by_key=False,\n",
+    "    overwrite=True,\n",
+    "    progress_wrapper=tqdm,\n",
+    "    image_prefix_map={\n",
+    "        ImageKey.SAMPLE: \"sample\",\n",
+    "        ImageKey.DARK_CURRENT: \"dc\",\n",
+    "        ImageKey.OPEN_BEAM: \"ob\",\n",
+    "    },\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sorted(output_dir.iterdir())"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Save All Frames in One File"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from ess.imaging.io import export_image_stacks_as_tiff, ImageKey\n",
+    "from tqdm import tqdm\n",
+    "from pathlib import Path\n",
+    "\n",
+    "\n",
+    "output_dir = Path(\"images\")\n",
+    "export_image_stacks_as_tiff(\n",
+    "    output_dir=output_dir,\n",
+    "    image_stacks=results[AllImageStacks],\n",
+    "    merge_image_by_key=True,\n",
+    "    overwrite=True,\n",
+    "    progress_wrapper=tqdm,\n",
+    "    image_prefix_map={\n",
+    "        ImageKey.SAMPLE: \"sample\",\n",
+    "        ImageKey.DARK_CURRENT: \"dc\",\n",
+    "        ImageKey.OPEN_BEAM: \"ob\",\n",
+    "    },\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "tuple(output_dir.iterdir())"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "tags": [
+     "remove-cell"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "!rm -rf images"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "img-dev-310",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.14"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

docs/user-guide/index.md

@@ -0,0 +1,10 @@
+# User guide
+
+
+```{toctree}
+---
+maxdepth: 1
+---
+installation
+histogram_mode_detectors
+```

docs/user-guide/installation.md

@@ -0,0 +1,16 @@
+# Installation
+
+To install `essimaging` and all of its dependencies, use
+
+`````{tab-set}
+````{tab-item} pip
+```sh
+pip install essimaging
+```
+````
+````{tab-item} conda
+```sh
+conda install -c conda-forge -c scipp essimaging
+```
+````
+`````

pyproject.toml

@@ -37,6 +37,7 @@ dependencies = [
   "scipp>=23.8.0",
   "scippnexus>=23.11.1",
   "essreduce",
+  "tifffile",
 ]
 
 dynamic = ["version"]

src/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:5fbc52595f3e6117a2be2bb50866806a',
+            'README.md': 'md5:6ca6b4a79bcff2965a81767e12474617',
+        },
+    )
+
+
+_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')