Architecture
A Project contains several kinds of objects.
A DataItem (aka "data item") represents an individual data array. A data array is stored internally by a NumPy-like array. It may be in memory, memory mapped, or not in memory. It may have any number of dimensions. A data item wraps a data array by providing a description of the dimensions, calibration, timestamps, and other metadata to be associated with the data array. See Data Items for more info.
A DisplayItem (aka "display") represents a particular presentation of one or more data items. Displays either display 1D or 2D data. There can be multiple distinct displays items for a given data item (e.g. one grayscale with 1:1 zoom; one with a color table with 1:8 zoom). In addition, a particular display may display multiple data items (e.g. a line plot with multiple layers).
A display uses a DisplayDataChannel (aka display data channel) to facilitate the reduction of a data array from a data item into 1D or 2D data. The display data channel describes how to reduce data arrays of higher dimensions to either 1D or 2D data suitable for use in a display. The display data channel also describes that way the intensity of a 2D image is mapped to a color. Display data channels are components of a display item and each display data channel is associated with a single display.
A display (see above) also contains a list of display layers and graphics.
A DisplayLayer (aka "display layer") describes the drawing order and drawing characteristics of a particular display data channel within the display. Currently only line plots implement multiple layers; raster image displays only implement a single layer.
TODO: Can display layers be merged with display data channels?
A Graphic (aka "graphic") describe one of several types of graphic objects that are drawn overlaid on a display. Graphics are typically associated with a particular coordinate or coordinates of the display.
The model within Swift is comprised of numerous objects such as data items, display items, and computations.
The model objects can be read and modified at any time from the main thread, including during async methods. The model objects can also be read from secondary threads, although care must be taken to ensure the objects are in a consistent state.
In order to support undo, modifications to the model objects should be performed through undoable commands.
TODO: How does the API allow modifications?
To support the highly dynamic nature of various UI elements and computations, changes to model objects trigger change events: property change events and item inserted/removed events. Other model objects and UI may be listeners for those change events and act accordingly.
Unfortunately, this system of change events and listeners is showing its limitations and we are searching for a better system. The difficulties are with threading, consistency of state, intermediate properties and objects, and ease of implementation.
One possible approach is using something similar to ReactiveX. Unfortunately ReactiveX does not address the issue of dynamic lists or consistency of state and only marginally addresses threading.