ngscopeclient · May 25, 2020 · May 25, 2020
diff --git a/glscopeclient-manual.tex b/glscopeclient-manual.tex
@@ -94,6 +94,12 @@
 \pagebreak
 \include{section-waveformgroups}
 
+\pagebreak
+\include{section-timeline}
+
+\pagebreak
+\include{section-waveformviews}
+
 \pagebreak
 \include{section-history}
 

diff --git a/images/eye-gradient-crt.png b/images/eye-gradient-crt.png
diff --git a/images/eye-gradient-grayscale.png b/images/eye-gradient-grayscale.png
diff --git a/images/eye-gradient-ironbow.png b/images/eye-gradient-ironbow.png
diff --git a/images/eye-gradient-krain.png b/images/eye-gradient-krain.png
diff --git a/images/eye-gradient-rainbow.png b/images/eye-gradient-rainbow.png
diff --git a/images/eye-gradient-viridis.png b/images/eye-gradient-viridis.png
diff --git a/images/multiple-groups.png b/images/multiple-groups.png
diff --git a/images/overview.png b/images/overview.png
diff --git a/section-mainwindow.tex b/section-mainwindow.tex
@@ -7,12 +7,46 @@ \subsection{Menu}
 
 \subsubsection{File}
 
+This menu contains commands for manipulating glscopeclient session files.
+
+A session consists of a YAML file called filename.scopesession containing instrument and UI configuration, as well
+as a directory called filename\_data which contains waveform metadata and sample values for all enabled instrument
+channels.
+
+\textbf{Save}: The UI layout may be saved to a session file so that a common instrument setup can be returned to in the
+future. Waveform data may optionally be saved in the session as well.
+
+\textbf{Open}: Loads a .scopesession file. Checkboxes at the bottom of the file browser dialog allow the UI
+configuration, instrument settings, and waveform data to be individually loaded or ignored.
+
+\textbf{Quit}: Exits the application
+
 \subsubsection{Setup}
 
+This menu allows instrument settings to be configured. Currently there's not much here.
+
 \subsubsection{View}
 
+This menu allows display settings to be configured. As of now, the only option is selection of the color palette for
+eye patterns.
+
+\begin{tabularx}{16cm}{llX}
+\thickhline
+\textbf{Name} & \textbf{Colors} & \textbf{Notes} \\
+\thickhline
+CRT & \includegraphics[width=5cm]{images/eye-gradient-crt.png} & Similar color scheme to a major scope vendor.\\
+Grayscale & \includegraphics[width=5cm]{images/eye-gradient-grayscale.png} & Common monochrome palette.\\
+Ironbow & \includegraphics[width=5cm]{images/eye-gradient-ironbow.png} & Common "hot metal" palette. \\
+KRain & \includegraphics[width=5cm]{images/eye-gradient-krain.png} & Similar color scheme to a major scope vendor.\\
+Rainbow & \includegraphics[width=5cm]{images/eye-gradient-rainbow.png} & Common HSV rainbow palette. \\
+Viridis & \includegraphics[width=5cm]{images/eye-gradient-viridis.png} & Perceptually uniform palette from matplotlib. \\
+\thickhline
+\end{tabularx}
+
 \subsubsection{Add}
 
+This menu allows a new waveform view to be created for any channel on a connected instrument.
+
 \subsection{Toolbar}
 
 The toolbar contains buttons and controls for the most frequently used actions.

diff --git a/section-timeline.tex b/section-timeline.tex
@@ -0,0 +1,14 @@
+
+\section{Timeline}
+
+The timeline is displayed at the top of each waveform group and shows the X axis scale for the group. The timeline (and
+all accompanying waveform views in the group) may be zoomed by scrolling with the mouse wheel, or panned by dragging
+with the left mouse button.
+
+Unlike classical oscilloscope user interfaces, there is \emph{no relationship} between the timeline scale/position and
+the duration of the acquisition. It is possible to zoom or scroll beyond the end of the acquisition (displaying empty
+background with no signal) or have a deep capture in which nearly all acquired data is offscreen.
+
+TODO: talk about how to set trigger offset in capture and change timebase once that's implemented
+
+TODO: insert screenshot after we have some pending UI changes done
diff --git a/section-waveformgroups.tex b/section-waveformgroups.tex
@@ -37,10 +37,16 @@ \subsection{Managing Groups}
 vertically, with the selected waveform moved or copied to the newly added group and all other waveforms in the original
 group.
 
+Waveforms may be also be moved within, or between, groups by clicking the channel information box and dragging it. A
+yellow insertion bar will appear when dragging, showing the location the waveform will be inserted in.
+
+If a waveform is dragged to the very bottom or right side of a waveform group, the destination group will be split
+vertically or horizontally and the new waveform will be inserted below or to the right of the destination group. The
+insertion bar turns orange when dragging near the edge of a group, to indicate that a split will take place.
+
 Dividers between waveform groups may be dragged with the left mouse button. Any group may be subdivided again, to
 create arbitrarily complex tiles of waveforms. Figure \ref{multiple-groups} shows a two-level hierarchy created by
-moving channel 2 to a new group at right, moving channel 4 to this group, then moving channel 4 again a new group at
-bottom.
+moving channel 2 to a new group at right, then moving channel 4 to a new group below that one.
 
 \begin{figure}[h]
 \centering
@@ -49,107 +55,8 @@ \subsection{Managing Groups}
 \label{multiple-groups}
 \end{figure}
 
-A future software release will support using the mouse to move and copy waveforms, both between groups and within a
-group (scopehal-apps:6). The exact semantics for this are not yet defined.
+Protocol decode overlays may be reordered by dragging the channel information box with the mouse, however they cannot
+currently be moved to another waveform or group.
 
 New waveform groups are given an automatically generated name when created, for example "Waveform Group 2". This name
 will be editable in a future software release (scopehal-apps:53).
-
-\pagebreak
-\section{Timeline}
-
-The timeline is displayed at the top of each waveform group and shows the X axis scale for the group. The timeline (and
-all accompanying waveform views in the group) may be zoomed by scrolling with the mouse wheel, or panned by dragging
-with the left mouse button.
-
-Unlike classical oscilloscope user interfaces, there is \emph{no relationship} between the timeline scale/position and
-the duration of the acquisition. It is possible to zoom or scroll beyond the end of the acquisition (displaying empty
-background with no signal) or have a deep capture in which nearly all acquired data is offscreen.
-
-TODO: talk about how to set trigger offset in capture and change timebase once that's implemented
-
-TODO: insert screenshot after we have some pending UI changes done
-
-\pagebreak
-\section{Waveform Views}
-
-A waveform view is a 2D graph of a signal or protocol decode within a waveform group.
-
-\subsection{Plot Area}
-
-The plot area shows the waveform being displayed. The background has a subtle gradient from light at top to dark at
-bottom, in order to visually separate adjacent waveform view within the same group.
-
-The horizontal grid lines line up with the voltage scale markings on the Y axis. If the plot area includes Y=0, the
-grid line for zero is slightly brighter.
-
-\begin{figure}[H]
-\centering
-\includegraphics[width=10cm]{images/waveform-graph.png}
-\caption{Waveform plot area}
-\label{waveform-graph}
-\end{figure}
-
-The waveform is drawn as a semi-transparent line so that when zoomed out, the density of voltage at various points in
-the graph may be seen as lighter or darker areas. This is referred to as ``intensity grading".
-
-\begin{figure}[H]
-\centering
-\includegraphics[width=10cm]{images/graded-waveform.png}
-\caption{Intensity-graded waveform}
-\label{graded-waveform2}
-\end{figure}
-
-\subsection{Y Axis Scale}
-
-Each waveform view has its own Y axis scale, which is locked to the ADC range of the instrument.
-
-Dragging the Y axis scale with the left mouse button currently does nothing (scopehal-apps:54) but in a future software
-release will change the voltage offset of the channel.
-
-Scrolling the Y axis scale with the mouse wheel changes the gain of the channel.
-
-If a left-pointing arrow (as seen in Fig. \ref{y-axis}) is visible, the current channel is selected as a trigger
-source. Click on the arrow and drag up or down to select the trigger level.
-
-\begin{figure}[H]
-\centering
-\includegraphics[height=3cm]{images/y-axis.png}
-\caption{Y axis of a waveform view showing trigger arrow}
-\label{y-axis}
-\end{figure}
-
-\subsection{Channel Information Box}
-
-The channel information box is displayed in the lower left corner of each waveform view. It contains summary
-information about the channel. Currently this is the display name of the channel, the sample rate, and the record
-length of the acquisition. Other information, such as probe coupling, may be displayed there in the future.
-
-Double-clicking the information box opens the channel properties dialog.
-
-\begin{figure}[H]
-\centering
-\includegraphics[width=2cm]{images/channel-infobox.png}
-\caption{Channel information box}
-\label{channel-infobox}
-\end{figure}
-
-\subsection{Overlays}
-
-Waveforms may have additional information overlaid on top of them, such as protocol decodes. Each overlay has its own
-information box, which may be double-clicked to open the properties dialog and configure it just like any other
-channel.
-
-Fig. \ref{overlays} shows
-an example of an analog waveform with three overlays: thresholding it to NRZ digital, recovering a sampling
-clock with a CDR PLL, and finally decoding the serial NRZ data stream to TMDS protocol data and control events.
-
-\begin{figure}[H]
-\centering
-\includegraphics[width=14cm]{images/overlays.png}
-\caption{Waveform showing two digital overlays and a data decode overlay}
-\label{overlays}
-\end{figure}
-
-Overlays can be deleted but cannot currently be moved between waveform areas or reordered within a single waveform area
-(scopehal-apps:7, scopehal-apps:6)
diff --git a/section-waveformviews.tex b/section-waveformviews.tex
@@ -0,0 +1,82 @@
+\section{Waveform Views}
+
+A waveform view is a 2D graph of a signal or protocol decode within a waveform group.
+
+\subsection{Plot Area}
+
+The plot area shows the waveform being displayed. The background has a subtle gradient from light at top to dark at
+bottom, in order to visually separate adjacent waveform view within the same group.
+
+The horizontal grid lines line up with the voltage scale markings on the Y axis. If the plot area includes Y=0, the
+grid line for zero is slightly brighter.
+
+\begin{figure}[H]
+\centering
+\includegraphics[width=10cm]{images/waveform-graph.png}
+\caption{Waveform plot area}
+\label{waveform-graph}
+\end{figure}
+
+The waveform is drawn as a semi-transparent line so that when zoomed out, the density of voltage at various points in
+the graph may be seen as lighter or darker areas. This is referred to as ``intensity grading".
+
+\begin{figure}[H]
+\centering
+\includegraphics[width=10cm]{images/graded-waveform.png}
+\caption{Intensity-graded waveform}
+\label{graded-waveform2}
+\end{figure}
+
+\subsection{Y Axis Scale}
+
+Each waveform view has its own Y axis scale, which is locked to the ADC range of the instrument.
+
+Dragging the Y axis scale with the left mouse button currently does nothing (scopehal-apps:54) but in a future software
+release will change the voltage offset of the channel.
+
+Scrolling the Y axis scale with the mouse wheel changes the gain of the channel.
+
+If a left-pointing arrow (as seen in Fig. \ref{y-axis}) is visible, the current channel is selected as a trigger
+source. Click on the arrow and drag up or down to select the trigger level.
+
+\begin{figure}[H]
+\centering
+\includegraphics[height=3cm]{images/y-axis.png}
+\caption{Y axis of a waveform view showing trigger arrow}
+\label{y-axis}
+\end{figure}
+
+\subsection{Channel Information Box}
+
+The channel information box is displayed in the lower left corner of each waveform view. It contains summary
+information about the channel. Currently this is the display name of the channel, the sample rate, and the record
+length of the acquisition. Other information, such as probe coupling, may be displayed there in the future.
+
+Double-clicking the information box opens the channel properties dialog.
+
+\begin{figure}[H]
+\centering
+\includegraphics[width=2cm]{images/channel-infobox.png}
+\caption{Channel information box}
+\label{channel-infobox}
+\end{figure}
+
+\subsection{Overlays}
+
+Waveforms may have additional information overlaid on top of them, such as protocol decodes. Each overlay has its own
+information box, which may be double-clicked to open the properties dialog and configure it just like any other
+channel.
+
+Fig. \ref{overlays} shows
+an example of an analog waveform with three overlays: thresholding it to NRZ digital, recovering a sampling
+clock with a CDR PLL, and finally decoding the serial NRZ data stream to TMDS protocol data and control events.
+
+\begin{figure}[H]
+\centering
+\includegraphics[width=14cm]{images/overlays.png}
+\caption{Waveform showing two digital overlays and a data decode overlay}
+\label{overlays}
+\end{figure}
+
+Overlays can be deleted but cannot currently be moved between waveform areas or reordered within a single waveform area
+(scopehal-apps:7, scopehal-apps:6)