Merge branch 'nion-software:master' into zoombutton

.github/workflows/python-package.yml

@@ -20,9 +20,9 @@ jobs:
         python-version: ["3.9", "3.10", "3.11", "3.12"]
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
     - name: Display Python version
@@ -45,7 +45,7 @@ jobs:
       run: |
         python -m unittest discover -s nion/swift -p '*_test.py'
     - name: Upload Artifacts
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.9'
       with:
         name: distribution

docs/basic_use.rst

@@ -2,10 +2,10 @@
 
 .. _basic-use:
 
-###########################
-Nion Swift Quickstart Guide
-###########################
-This quickstart guide will provide you with a quick tutorial on how to use the most important features of Nion Swift. For more in-depth explanations, please see the full :ref:`user-guide`.
+################################
+Nion Swift Introductory Tutorial
+################################
+This introductory tutorial will show you how to use the most important features of Nion Swift. For more in-depth explanations, please see the full :ref:`user-guide`.
 
 *******************
 Intro to Nion Swift

docs/conf.py

@@ -64,7 +64,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

docs/data.rst

@@ -3,29 +3,33 @@
 
 Data and Displays
 =================
-|AppName| operates on data arrays, which include 2D images and 1D spectra, which are generally called *Data Items*.
+This section describes the distinction between data items and display items in |AppName|.
 
-Data items represent data arrays with anywhere from one to five dimensions. The data array associated with a data item can be 1D or 2D data and then organized into 1D or 2D collections or 1D sequences. A data item can store scalar, complex, or RGB data. The scalar data can be integer or real.
+Data Items
+----------
+|AppName| primarily operates on data arrays such as 2D images and 1D spectra, which are generally called *Data Items*.
 
-A data item also stores both formal and informal metadata about the data. The formal metadata includes a title and description; the grouping of dimensions into data, collections, and sequences; dimensional and intensity calibrations; and creation and modification timestamps including time zone information. The informal metadata includes a freeform Python dict that is JSON compatible.
+The data in a data item may be organized into collections. For instance, a sequence of two dimensional images, or a two dimensional collection of one dimension spectra.
 
-A data item is displayed in one or more *Display Items*.
+The data in a data item may be stored as floating point numbers, integer numbers, complex numbers, or as RGB or RGBA values.
+
+A data item also stores metadata about the data. The metadata includes a title and description; the grouping of dimensions into data, collections, and sequences; dimensional and intensity calibrations; and creation and modification timestamps including time zone information. There may be other metadata stored as key-value pairs in more free-form manner.
 
 Display Items
 -------------
-Display items represent a view on one or more data items. A display item tracks things like how to translate the data in a 2D image data item to an image in the user interface. It also tracks how to reduce more complex data structures to either a 2D or 1D representation.
+Display items represent a view of one or more data items and can be edited separately its associated data items.
 
-Display items are distinct from data items so that you can have multiple views on a particular data item and also so that you can display multiple data items in the same display.
+A display item keeps track of how to display the data in a data item. For instance, the color table used to show an image or the range of data shown in a line plot.
 
-Display items include their own title and description. If these are empty, the title and description of the first data item is used instead.
+A data item can often represent more data than can be shown in a single display. For example, a sequence of 2D images can only sensibly display one of those images at once.
 
-Display panels show individual display items and also allow you to browse available display items. The data panel shows the list of display items available in the project. See :ref:`display-panels` and :ref:`user-interface` for more information.
+A display item ultimately must reduce complicated data to a single 2D image or 1D plot. For example, it keeps track of which index of a sequence of images is shown, similar to how a movie shows only a single frame at time. Display items keep track of similar data reductions for other types of collections and data types.
 
-Reducing Data for Display
--------------------------
-A data item can possibly represent more data than it can display at once. In addition, there may be multiple ways of viewing the data. The process of data reduction reduces all data items to either a 2D image or a 1D plot suitable for display.
+Display items may be associated with just a single data item, such as when the data is a 2D image. However, data items may also be associated with multiple data items, such as when multiple 1D data items are displayed on a single line plot.
 
-For example, a 2D spatial collection of 1D energy spectra (2D x 1D) cannot be displayed without reducing it. There are two obvious ways to reduce the data: either reduce to 1D by choosing a particular x, y coordinate from the collection dimensions; or reduce to 2D by choosing a particular energy at each x, y coordinate.
+Display items include their own title and description. If these are empty, the title and description of the first data item is used instead.
+
+Display items are shown in the workspace in display panels. See :ref:`display-panels` and :ref:`user-interface` for more information.
 
 Calibrations
 ------------
@@ -47,20 +51,20 @@ The freeform metadata can be viewed in the Metadata Panel or accessed from scrip
 
 Coordinate Systems
 ------------------
-To be consistent with scripting and Python NumPy coordinates, all coordinate systems increase towards the right and down and indices are ordered such that the slowest changing index in memory is first.
+In addition to calibrated coordinate systems, |AppName| uses pixel and relative coordinate systems.
 
-The pixel coordinate system displays pixels and can be displayed with the origin at the top-left or the origin at the center.
+The pixel coordinate system spans the size of the data array and can be displayed with the origin at the top-left or the origin at the center.
 
 The relative coordinate system displays fractional coordinates and can be displayed with the origin at the top-left and a range of 0.0 to 1.0 or with the origin at the center a range of -1.0 to 1.0.
 
 The calibrated coordinate system displays calibrated coordinates. The origin is determined by the calibration offset.
 
+Note: when referring to pixels, to be consistent with scripting and Python NumPy coordinates, all coordinate systems increase towards the right and down and indices are ordered such that the slowest changing index in memory is first, i.e. `image[y, x]`.
+
 Collections
 -----------
 Images and plots (2D and 1D) data can be arranged into collections with one or two dimensions. These are often expressed as 1D x 1D (spectra along a line), 2D x 1D (a spectrum image), 1D x 2D (images along a line), or 2D x 2D (4D STEM).
 
-Sequences
----------
 In addition to collections, 1D or 2D data or 1D or 2D collections of 1D or 2D data can be arranged into sequences. A sequence is roughly equivalent to a 1D collection.
 
 As an example, a sequence of 2D images would be a movie.

docs/index.rst

@@ -1,58 +1,54 @@
+.. include:: defs.rst
 .. _index:
 
-Nion Swift User's Guide (16.10.0)
+|AppName| User's Guide (16.11.0)
 ================================
-Nion Swift is open source scientific image processing software integrating hardware control, data acquisition,
-visualization, processing, and analysis using Python. Nion Swift is easily extended using Python. It runs on
-Windows, Linux, and macOS.
+|AppName| is an open-source scientific image-processing software that uses Python to integrate hardware control, data acquisition, visualization, processing, and analysis. It runs on Windows, Linux, and macOS.
 
 .. image:: graphics/workspace.png
   :width: 640
-  :alt: The Swift Workspace
+  :alt: The Main Workspace
+
+|AppName| is designed to be an intuitive and user-friendly platform, making the acquisition of scientific data from a range of microscopes and instruments a straightforward process. Its sophisticated data visualization, processing, and analysis capabilities further enhance your confidence in handling complex scientific data.
 
 Key Features
 
-- Data handling of 1D plots, 2D images, 1D and 2D collections of plots and images, and sequences.
-- Live computations that can be chained during acquisition or live parameter adjustment.
-- Open source, cross platform (macOS, Windows, Linux), and Python based scientific data processing.
+- Handles various data, including images, line plots, and higher dimensional data.
+- Live computations applied during acquisition or used for parameter adjustment.
 - Low latency, high throughput data acquisition platform.
+- Customization via scripting and plug-ins using Python.
+- Open source, cross-platform (macOS, Windows, Linux), and Python-based scientific data processing.
 
-Who Uses Nion Swift?
---------------------
+Who Uses |AppName|?
+-------------------
 
-Nion Swift has been primarily developed for the operation of Nion electron microscopes and also as an offline tool to
-visualize, process, and analyze scientific data from electron microscopes, other instrumentation, and other scientific
-fields.
+|AppName| has been primarily developed for the operation of Nion electron microscopes and also as an offline tool to visualize, process, and analyze scientific data from electron microscopes, other instrumentation, and other scientific fields.
 
-Nion Swift is open source. You can find the source code on
-`GitHub Nion Swift <https://github.com/nion-software/nionswift/>`_.
+|AppName| is open source. You can find the source code on
+`GitHub |AppName| <https://github.com/nion-software/nionswift/>`_.
 
 Installation/Upgrading
 ----------------------
-The quickest and easiest way to get Nion Swift running is to download a pre-built version that includes everything needed to run the basic application.
+The quickest and easiest way to get |AppName| running is to download a pre-built version that includes everything needed to run the basic application.
 
 * `Download for macOS, Linux, or Windows <https://nion.com/swift/downloads>`_.
 
-To install Nion Swift from Python source code, you will need to install a Python environment and then install Python packages required for Nion
-Swift.
+To install |AppName| from Python source code, you will need to install a Python environment and then install Python packages required for |AppName|.
 
-For specific installation details and download links, follow link below. Instructions to install additional packages to
-extend Nion Swift are also covered.
+For specific installation details and download links, follow link below. Instructions to install additional packages to extend |AppName| are also covered.
 
 * :ref:`installation`
 * :ref:`upgrading`
 
 Release Notes
 -------------
-To see a list of changes for each version of Nion Swift, follow the link below.
+To see a list of changes for each version of |AppName|, follow the link below.
 
 * :ref:`release-notes`
 
-Using Nion Swift
-----------------
-Once you have installed Nion Swift and successfully launched it, you can read the introduction to understand the basic
-ideas, follow through the basic tutorial to try out key concepts, and consult the user guide for more advanced use,
-Python scripting, and reference.
+Using |AppName|
+---------------
+Once you have installed |AppName| and successfully launched it, you can read the introduction to understand the basic ideas, follow through the basic tutorial to try out key concepts, and consult the user guide for more advanced use, Python scripting, and reference.
 
 * :ref:`basic-use`
 * :ref:`user-guide`
@@ -61,14 +57,13 @@ Python scripting, and reference.
 
 Python Scripting
 ----------------
-Nion Swift offers a great deal of functionality using the user interface. However, sometimes you will want to go beyond
-its intrinsic capabilities. Fortunately it is easy to extend the functionality using Python.
+|AppName| offers a great deal of functionality using the user interface. However, sometimes you will want to go beyond its intrinsic capabilities. Fortunately it is easy to extend the functionality using Python.
 
 * :ref:`scripting`
 
-Nion Swift Links
-----------------
-`Nion Swift Google Group <https://groups.google.com/forum/#!forum/nionswift>`_ News and Announcements.
+|AppName| Links
+---------------
+`|AppName| Google Group <https://groups.google.com/forum/#!forum/nionswift>`_ News and Announcements.
 
 Indices and Tables
 ==================

docs/installation.rst

@@ -1,9 +1,18 @@
 :orphan:
 
+.. include:: defs.rst
 .. _installation:
 
 Nion Swift Installation
 =======================
+The quickest and easiest way to get |AppName| running is to download a pre-built version that includes everything needed to run the basic application with key plug-ins.
+
+* `Download for macOS, Linux, or Windows <https://nion.com/swift/downloads>`_.
+
+Installation from Source Code
+-----------------------------
+To install |AppName| from Python source code, you will need to install a Python environment and then install Python packages required for |AppName|.
+
 Nion Swift is written in the Python programming language. To use Nion Swift, you will need to install a Python environment.
 
 As an open source project, there are many possible installation scenarios such as for offline use, for use on a Nion electron microscope, or for open source development. In addition, Python installation itself is highly flexible. Some Python installations will be used with other software, and others specifically with Nion Swift.