Merge pull request #691 from scipp/slicer-instrument-view

New instrument view with better performance

Author: nvaytet

.buildconfig/ci-linux.yml

@@ -16,7 +16,7 @@ dependencies:
   - mantid==6.15.0
   - matplotlib==3.9.4
   - mpltoolbox==25.10.0
-  - plopp==25.11.0
+  - plopp==26.4.1
   - pooch==1.9.0
   - pydantic==2.12.4
   - pytest==8.3.3

docs/user-guide/instrument-view.ipynb

@@ -2,186 +2,210 @@
  "cells": [
   {
    "cell_type": "markdown",
+   "id": "0",
    "metadata": {},
    "source": [
     "# Instrument view\n",
     "\n",
-    "## Overview\n",
+    "A simple version of the [Mantid instrument view](https://docs.mantidproject.org/nightly/workbench/instrumentviewer.html#instrumentviewer) is available in scippneutron.\n",
     "\n",
-    "A simple version of the Mantid [instrument view](https://www.mantidproject.org/MantidPlot:_Instrument_View) is available in `scippneutron`.\n",
     "It currently does not support detector 'picking' and manual drawing of masks,\n",
     "nor does it render the actual shape of the detectors (currently it represents them as 2-D squares),\n",
-    "but basic functionalities such as spatial slicing,\n",
-    "as well as navigation through the time-of-flight dimension via a slider, are provided."
+    "but basic functionalities such as spatial slicing, as well as navigation through the time-of-flight dimension via a slider, are provided."
    ]
   },
   {
-   "cell_type": "markdown",
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "1",
    "metadata": {},
+   "outputs": [],
    "source": [
-    "<div class=\"alert alert-info\">\n",
-    "\n",
-    "**Note**\n",
-    "\n",
-    "The file used in this notebook is from the Mantid [training course data](https://www.mantidproject.org/installation/index#sample-data).\n",
-    "\n",
-    "</div>"
+    "import scipp as sc\n",
+    "import scippneutron as scn\n",
+    "from scippneutron import data"
    ]
   },
   {
    "cell_type": "markdown",
+   "id": "2",
    "metadata": {},
    "source": [
-    "<div class=\"alert alert-warning\">\n",
+    "## Load the data\n",
     "\n",
-    "**Warning**\n",
-    "    \n",
-    "While you can interact with the 3D view of the instrument,\n",
-    "the buttons and sliders will have no effect in the documentation pages,\n",
-    "as there is no kernel to perform the operations.\n",
-    "These will only work inside a Jupyter notebook.\n",
-    "\n",
-    "</div>"
+    "We load an example dataset for the Dream (ESS) instrument.\n",
+    "In each detector bank, the data is organised by `wire`, `strip`, `module`, `segment`, and `counter`."
    ]
   },
   {
-   "cell_type": "markdown",
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3",
    "metadata": {},
+   "outputs": [],
    "source": [
-    "We load a file containing a `position` coordinate:"
+    "dg = data.example_dream_data()\n",
+    "dg"
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
+   "cell_type": "markdown",
+   "id": "4",
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "source": [
-    "import numpy as np\n",
-    "import scipp as sc\n",
-    "import scippneutron as scn\n",
-    "import scippneutron.data"
+    "## Full instrument view\n",
+    "\n",
+    "We first histogram the data along the time-of-flight (`tof`) dimension,\n",
+    "making sure the same bins are used for all elements:"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "id": "5",
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "outputs": [],
    "source": [
-    "sample = scn.data.powder_sample()['data'].hist()\n",
-    "sample"
+    "tof_edges = sc.linspace(\"tof\", 1.0e7, 1.0e8, 51, unit=\"ns\", dtype=int)\n",
+    "histogram = dg.hist(tof=tof_edges)"
    ]
   },
   {
    "cell_type": "markdown",
-   "metadata": {},
+   "id": "6",
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "source": [
-    "The `instrument_view` function can now be used to display a 3-D representation:"
+    "We now use the `instrument_view` function to show the 3D view of the instrument pixels,\n",
+    "specifying that we wish to have a slider along the `tof` dimension:"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "id": "7",
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "outputs": [],
    "source": [
-    "scn.instrument_view(sample)"
+    "full_view = scn.instrument_view(histogram, dim=\"tof\")\n",
+    "full_view"
    ]
   },
   {
    "cell_type": "markdown",
-   "metadata": {},
+   "id": "8",
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "source": [
-    "The <img src='https://upload.wikimedia.org/wikipedia/commons/thumb/b/b3/Font_Awesome_5_solid_cube.svg/240px-Font_Awesome_5_solid_cube.svg.png' width=\"20\"/>\n",
-    "button in the toolbar activates a tool that lets you can create spatial cuts to slice your data in 3D.\n",
+    "Note that it is possible to use any dimension for the slider instead of `tof`, such as `wavelength` (if present in the data).\n",
+    "\n",
+    "## Displaying individual detector elements\n",
     "\n",
-    "It is possible to customize the figure using the usual arguments, as well as adjusting the pixel size, e.g."
+    "It is also possible to view a single detector element, selecting e.g. `mantle` from the original data:"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "id": "9",
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "outputs": [],
    "source": [
-    "scn.instrument_view(\n",
-    "    sample, cmap=\"magma\", vmax=2000.0 * sc.units.counts, norm=\"log\", pixel_size=0.03\n",
-    ")"
+    "mantle_view = scn.instrument_view(histogram[\"mantle\"], dim=\"tof\")\n",
+    "mantle_view"
    ]
   },
   {
    "cell_type": "markdown",
+   "id": "10",
    "metadata": {},
    "source": [
-    "## Displaying additional components\n",
-    "\n",
-    "Additional beamline components can be displayed in the instrument view by providing a `dict` of component settings.\n",
-    "As we can see above, the loaded data array also contains `source_position` and `sample_position` stored as 3-D vector coordinates.\n",
-    "This is in addition to the `position` coordinate, which defines only the positions of detector pixels.\n",
+    "The instrument view is designed to be flexible in terms of what it accepts as input.\n",
+    "This means that you can easily inspect, for example, a single module by using the usual slicing notation for data arrays.\n",
     "\n",
-    "Apart from `position`, the `instrument_view` does not require data arrays to follow a pre-defined naming convention for additional components.\n",
-    "Instead it relies on the aforementioned `dict` of components, which can be customized, e.g., for a particular beamline.\n",
+    "The `dim` argument can also be omitted; in this case a reduction `operation` (sum by default) along all non-position dimensions is applied to the data before displaying.\n",
     "\n",
-    "The `dict` key of the component is used as the text label.\n",
-    "Component settings are given in the form of a dictionary defining, e.g., `color`, `size`, and `type`.\n",
-    "We can pick from a limited number of `type`s including `cylinder`, `disk` and `box`:"
+    "Below, we display the first module in the backward end-cap detector, without a `tof` slider:"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
+   "id": "11",
    "metadata": {},
    "outputs": [],
    "source": [
-    "sample_settings = {\n",
-    "    'center': sample.coords['sample_position'],\n",
-    "    'color': '#000000',\n",
-    "    'wireframe': True,\n",
-    "    'size': sc.vector(value=[0.3, 0.3, 0.3], unit=sc.units.m),\n",
-    "    'type': 'box',\n",
-    "}\n",
-    "source_settings = {\n",
-    "    'center': sample.coords['source_position'],\n",
-    "    'color': '#FFC133',\n",
-    "    'size': sc.vector(value=[1000, 2000, 1000], unit=sc.units.mm),\n",
-    "    'type': 'cylinder',\n",
-    "}\n",
-    "scn.instrument_view(\n",
-    "    sample, components={'sample': sample_settings, 'source': source_settings}\n",
-    ")"
+    "scn.instrument_view(dg[\"endcap_backward\"][\"module\", 0].hist())"
    ]
   },
   {
    "cell_type": "markdown",
+   "id": "12",
    "metadata": {},
    "source": [
-    "## Defining detector positions\n",
+    "## Spatial slicing\n",
+    "\n",
+    "A tool for selecting parts of the displayed detectors is available by clicking the 'layers' (last) button in the toolbar.\n",
     "\n",
-    "If data comes without pre-defined detector-positions, e.g., when they are not contained in the original file, they can be defined by simply adding a `position` coordinate to a data array:"
+    "Adding and moving selection regions can help inspect data inside volumetric detectors:"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
+   "id": "13",
    "metadata": {},
    "outputs": [],
    "source": [
-    "nx, ny = (10, 10)\n",
-    "points_x = np.linspace(0, 1, nx)\n",
-    "points_y = np.linspace(0, 1, ny)\n",
-    "xv, yv = np.meshgrid(points_x, points_y)\n",
-    "\n",
-    "_x = sc.array(dims=['spectrum'], values=xv.ravel())\n",
-    "_y = sc.array(dims=['spectrum'], values=yv.ravel())\n",
-    "_z = sc.array(dims=['spectrum'], values=np.zeros(100))\n",
-    "\n",
-    "data = sc.arange('spectrum', 100.0, unit='counts')\n",
-    "da = sc.DataArray(data)\n",
-    "da.coords['position'] = sc.spatial.as_vectors(_x, _y, _z)\n",
-    "da.coords['spectrum'] = sc.arange('spectrum', 100)\n",
-    "\n",
-    "scn.instrument_view(da, pixel_size=0.1)"
+    "mantle_view = scn.instrument_view(histogram[\"mantle\"], dim=\"tof\")\n",
+    "mantle_view"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "14",
+   "metadata": {
+    "nbsphinx": "hidden"
+   },
+   "outputs": [],
+   "source": [
+    "mantle_view.toolbar['cut3d'].value = True\n",
+    "mantle_view.bottom_bar.children[0][0]._add_cut('y')"
    ]
   }
  ],
@@ -201,9 +225,9 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.14"
+   "version": "3.12.12"
   }
  },
  "nbformat": 4,
- "nbformat_minor": 4
+ "nbformat_minor": 5
 }

pyproject.toml

@@ -37,7 +37,7 @@ dependencies = [
     "lazy_loader>=0.4",
     "mpltoolbox>=24.6.0",
     "numpy>=1.20",
-    "plopp>=24.09.1",
+    "plopp>=26.4.1",
     "pydantic>=2",
     "scipp>=24.07.0",
     "scippnexus>=23.11.0",