Basic Interface Overview

Useful class definitions

MainWindow

The MainWindow in SpecViz is the top level visible widget. It is at this level that the main tool bar actions, menu bar actions, and plugin items are maintained. There can be any number of MainWindows per SpecViz application sessions.

The signal MainWindow.window_activated(QMainWindow) can be used to listen for which MainWindow instance has become the focus of the user.

Creating a MainWindow is done at the Application level; from an Application instance, calling the add_workspace method will create a new MainWindow. and the currently active MainWindow can be retrieved via Application.current_window.

Workspace

Internally, the Workspace class is a separate widget, but due to the fact that the MainWindow and Workspace functionality are so intertwined (the latter is the central widget of the former), the MainWindow + Workspace combination is referred to simply as a workspace. In the future, serialization of the state of the workspace will allow users to store and retrieve their work.

The Workspace maintains the core data QStandardItemModel instance that houses the DataItems users have loaded. It is also responsible for adding and removing PlotWindow instances to the QMdiArea for displaying DataItems.

Calling the add_plot_window function will create a new PlotWindow instance and add it to the QMdiArea. Removing the current plot window can be done by calling the remove_plot_window function.

The Workspace is also where the QListView item model view is maintained. Note that the model for the QListView is always a QSortFilterProxyModel provided by the current PlotWindow. This proxy model maintains a list of PlotDataItems that can be displayed and used on the PlotWindow.

PlotWindow

The PlotWindow is an instance of a QMdiSubWindow and maintains the proxy model and references to the currently selected item from the Workspace's QListView. It also contains plot tool bar actions, as well as the reference to the PlotWidget instance.

PlotWidget

This is the plot on which the PlotDataItem data is displayed. This class maintains all visible unit conversion behavior for display purposes, including the axis labels. In addition, it contains the functionality for adding and removing ROIs.

PlotDataItem

These items are created only for use with the proxy model, and are never used directly for data manipulation (only for plot display manipulation). Instances of this class are created automatically and always have a reference to the DataItem stored in the QStandardItemModel instance that contains all the actual data for a particular spectrum.

DataItem

DataItems are QStandardItems that act as containers for specutils.Spectrum1D objects and maintain some associated properties like the data item's name and id.

Adding data to the model

Data is added to the model by calling the add_data function on the Workspace's model. This expects a specutils.Spectrum1D instance which can be created (and is done so nominally) using the static read method. This allows for defining the custom loader associated with loading this data:

spec = Spectrum1D.read(<file_path>, format='wcs1d-fits')
workspace.model.add_data(spec, name=name)

The add_data function will create the DataItem object and add it to the model.

Plotting a DataItem

Currently, to plot something programmatically requires that users get an instance of the PlotWidget, along with the QModelIndex from the proxy model they wish to plot. This will be improved in the future.

# Given the `DataItem` they want to plot
item = workspace.proxy_model.item_from_index(0)  # Gets a PlotDataItem

plot_widget = workspace.current_window.plot_widget
plot_widget.add_plot(item=item)