docs: update documentation

docs/source/conf.py

@@ -56,6 +56,7 @@
     "myst_parser",
     "notfound.extension",
 ]
+sd_fontawesome_latex = True
 
 notfound_context = {
     "title": "Page not found",

docs/source/getting-started.rst

@@ -20,10 +20,15 @@ familiar with xarray.
 Installing
 ==========
 
-ERLabPy depends on a number of scientific python libraries. The recommended way to
-install ERLabPy is via conda. If you do not have conda installed, follow the :ref:`conda
-installation instructions <Installing conda>`. Once you have a working conda
-environment, you can install ERLabPy with the conda command line tool: ::
+ERLabPy depends on a number of scientific python libraries.
+
+
+conda
+-----
+
+The recommended way to install ERLabPy is via conda. If you do not have conda installed,
+follow the :ref:`conda installation instructions <Installing conda>`. Once you have a
+working conda environment, you can install ERLabPy with the conda command line tool: ::
 
   conda install -c conda-forge erlab
 
@@ -51,6 +56,10 @@ If you require other :ref:`optional dependencies`, add them to the line above.
   `conda-forge documentation
   <https://conda-forge.org/docs/maintainer/knowledge_base/#switching-blas-implementation>`_.
 
+
+pip
+---
+
 If you don’t use conda, you can install ERLabPy with pip: ::
 
   python -m pip install erlab
@@ -66,6 +75,9 @@ Optional dependency groups can be installed with the following commands: ::
 See the :ref:`optional dependencies` section for all available groups and their
 contents.
 
+From source
+-----------
+
 If you wish to install ERLabPy from source, see the :doc:`contributing`.
 
 Importing

docs/source/user-guide/imagetool.rst

@@ -1,5 +1,8 @@
-Using ImageTool
-===============
+ImageTool
+=========
+
+The ImageTool window
+--------------------
 
 .. image:: ../images/imagetool_light.png
     :align: center
@@ -17,7 +20,8 @@ Inspired by *Image Tool* for Igor Pro written by the Advanced Light Source at La
 Berkeley National Laboratory, :class:`ImageTool <erlab.interactive.imagetool.ImageTool>`
 is a simple tool exploring images interactively.
 
-Features:
+Features
+~~~~~~~~
 
 - Zoom and pan
 
@@ -32,40 +36,68 @@ Features:
 - Interactive editing like rotation, normalization, cropping, momentum conversion, and
   more
 
-ImageTool displays *image-like* :class:`xarray.DataArray`\ s from 2 to 4 dimensions. Non-uniform coordinates are converted to index arrays automatically.
+Displaying data in ImageTool
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ImageTool supports *image-like* :class:`xarray.DataArray`\ s from 2 to 4 dimensions.
+Non-uniform coordinates are converted to index arrays automatically.
 
 Invoke ImageTool by calling :func:`itool <erlab.interactive.imagetool.itool>`: ::
 
     import erlab.interactive as eri
     eri.itool(data)
 
-Or use the :class:`qshow <erlab.accessors.general.InteractiveDataArrayAccessor>` accessor: ::
+Or use the :meth:`DataArray.qshow <erlab.accessors.general.InteractiveDataArrayAccessor.__call__>` accessor: ::
 
     data.qshow()
 
 Tips
-----
+~~~~
 
 - Hover over buttons for tooltips.
 
-- Right-click plots for context menus.
+- Most actions have associated keyboard shortcuts. Explore the menu bar to learn them.
+
+- Right-click on plots for context menus with options like copying slicing code, locking
+  aspect ratio, exporting to a file, and more.
+
+- Cursor controls
+
+  - :material-regular:`grid_on`: snap cursors to pixel centers.
+
+  - :material-regular:`add` and :material-regular:`remove`: add and remove
+    cursors.
+
+- Color controls
+
+  - :material-regular:`brightness_auto`: lock color range and display a colorbar.
+
+    - When toggled on, the color range is locked to the minimum and maximum of the entire
+      data.
+
+    - The color range can be manually set by dragging or right-clicking on the colorbar.
+
+  - :material-regular:`vertical_align_center`: scale the
+    colormap gamma with respect to the midpoint of the colormap, similar to
+    :class:`CenteredPowerNorm <erlab.plotting.colors.CenteredPowerNorm>`.
 
-  - ``Copy selection code``: copies code to reproduce the data.
+  - :material-regular:`exposure`: switch between scaling behaviors of
+    :class:`PowerNorm <matplotlib.colors.PowerNorm>` and  :class:`InversePowerNorm
+    <erlab.plotting.colors.InversePowerNorm>`.
 
-- Toggle the ``Lock color limits`` button to lock color range and display a colorbar.
+- Binning controls
 
-  - When toggled on, the color range is locked to the minimum and maximum of the entire
-    data.
+  - :material-regular:`settings_backup_restore`: reset all bin widths to 1.
 
-  - The color range can be manually set by dragging or right-clicking on the colorbar.
+  - :material-regular:`sync`: Apply binning changes to all cursors.
 
 - Rotate and normalize data via the edit and view menus.
 
 - ImageTool is extensible. At our home lab, we use a modified version of ImageTool to
   plot data as it is being collected in real-time!
 
 Keyboard shortcuts
-------------------
+~~~~~~~~~~~~~~~~~~
 
 Some shortcuts not in the menu bar. Mac users replace :kbd:`Ctrl` with :kbd:`⌘` and
 :kbd:`Alt` with :kbd:`⌥`.
@@ -93,13 +125,22 @@ a cursor involves the :kbd:`Shift` key.
 
 Using the ImageTool manager
 ---------------------------
-Interactive tools in Jupyter notebooks block other code. Use :class:`ImageToolManager
-<erlab.interactive.imagetool.ImageToolManager>` as a workaround.
 
-Run ``itool-manager`` in a terminal to start the manager. Calls to :func:`itool
-<erlab.interactive.imagetool.itool>` and :meth:`DataArray.qshow
-<erlab.accessors.general.InteractiveDataArrayAccessor.__call__>` will open ImageTool in
-the manager.
+ImageTools can also be used as a standalone application with :class:`ImageToolManager
+<erlab.interactive.imagetool.ImageToolManager>`
+
+When the manager is running, calls to :func:`itool <erlab.interactive.imagetool.itool>`
+and :meth:`DataArray.qshow
+<erlab.accessors.general.InteractiveDataArrayAccessor.__call__>` from any python script
+or notebook will open the ImageTool in the manager program.
+
+The manager shows a list of opened ImageTools and buttons to manage them. Hover over
+buttons for tooltips.
+
+Starting the manager
+~~~~~~~~~~~~~~~~~~~~
+
+Run ``itool-manager`` in a terminal to start the manager.
 
 Or run: ::
 
@@ -115,8 +156,8 @@ Or run: ::
     <erlab.accessors.general.InteractiveDataArrayAccessor.__call__>` to open data
     directly.
 
-The manager shows a list of opened ImageTools and buttons to manage them. Hover over
-buttons for tooltips.
+Creating ImageTool windows
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Open data in the manager by:
 
@@ -126,10 +167,18 @@ Open data in the manager by:
 
 - Opening files through the ``File`` menu in the manager.
 
-- Dragging and dropping ARPES data into the manager window.
+- Dragging and dropping supported ARPES data into the manager window.
+
+Features
+~~~~~~~~
+
+- Save and load ImageTool windows to a HDF5 file via the ``Save Workspace As...`` and
+  ``Open Workspace...`` menu items.
 
-Save and load ImageTool windows to a HDF5 file via the ``Save Workspace As...`` and ``Open Workspace...`` menu items.
+- The manager has a Python console to manipulate ImageTool windows and data, and run
+  Python code.
 
-The manager has a Python console to manipulate ImageTool windows and data, and run Python code. Toggle the console with :kbd:`⌃+`` (Mac) or :kbd:`Ctrl+`` (Windows/Linux) or through the ``View`` menu.
+  Toggle the console with :kbd:`⌃+`` (Mac) or :kbd:`Ctrl+`` (Windows/Linux) or through
+  the ``View`` menu.
 
-Explore the menubar for more options!
+- Explore the menubar for more features!

docs/source/user-guide/index.rst

@@ -21,13 +21,13 @@ If you are new to using ERLabPy, you may want to start with the `getting started
    :caption: Table of Contents
    :maxdepth: 2
 
+   imagetool
    io
    indexing
    plotting
    kconv
    curve-fitting
    filtering
-   imagetool
 
 Further reading
 ===============

docs/source/user-guide/plotting.ipynb

@@ -419,9 +419,26 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Here, we notice that the first two plots slices through regions with less spectral weight, so the color across the three subplots are not on the same scale. This may be misleading in some occasions where intensity across different slices are important. Luckily, we have a function that can unify the color limits across multiple axes.\n",
+    "Here, we notice that the first two plots slices through regions with less spectral weight, so the color across the three subplots are not on the same scale. This may be misleading in some occasions where intensity across different slices are important. Luckily, we have a function that can unify the color limits across multiple axes."
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "metadata": {
+    "editable": true,
+    "raw_mimetype": "text/restructuredtext",
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": [],
+    "vscode": {
+     "languageId": "raw"
+    }
+   },
+   "source": [
+    ".. note::\n",
     "\n",
-    "The same effect can be achieved by passing on `same_limits=True` to `plot_slices`."
+    "   The same effect can be achieved by passing on `same_limits=True` to :func:`plot_slices <erlab.plotting.general.plot_slices>`."
    ]
   },
   {
@@ -711,7 +728,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "erlabnew",
+   "display_name": "erlab",
    "language": "python",
    "name": "python3"
   },
@@ -725,7 +742,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.6"
+   "version": "3.12.7"
   }
  },
  "nbformat": 4,

src/erlab/interactive/imagetool/controls.py

@@ -43,7 +43,7 @@
     "minus": "mdi6.minus",
     "reset": "mdi6.backup-restore",
     # all_cursors="mdi6.checkbox-multiple-outline",
-    "all_cursors": "mdi6.select-multiple",
+    "all_cursors": "mdi6.sync",
 }  #: Mapping from custom aliases to qtawesome icon names.
 
 

src/erlab/interactive/imagetool/manager.py

@@ -12,7 +12,15 @@
 
 from __future__ import annotations
 
-__all__ = ["PORT", "ImageToolManager", "is_running", "main", "show_in_manager"]
+__all__ = [
+    "PORT",
+    "ImageToolManager",
+    "ToolNamespace",
+    "ToolsNamespace",
+    "is_running",
+    "main",
+    "show_in_manager",
+]
 
 import contextlib
 import datetime
@@ -1306,7 +1314,7 @@ def sizeHint(self) -> QtCore.QSize:
         return QtCore.QSize(300, 186)
 
 
-class ImageToolManagerJupyterConsole(QtWidgets.QDockWidget):
+class _ImageToolManagerJupyterConsole(QtWidgets.QDockWidget):
     def __init__(self, manager: ImageToolManager) -> None:
         super().__init__("Console", manager, flags=QtCore.Qt.WindowType.Window)
 
@@ -1566,7 +1574,7 @@ def __init__(self: ImageToolManager) -> None:
         self.setMinimumWidth(301)
         self.setMinimumHeight(487)
 
-        self.console = ImageToolManagerJupyterConsole(self)
+        self.console = _ImageToolManagerJupyterConsole(self)
 
         # Event filters
         self._kb_filter = KeyboardEventFilter(self)