<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">\documentclass[onecolumn,letterpaper,11pt]{article}

%===================================================================
\input{common_latex/common_latex_packages}
\input{common_latex/common_latex_definitions}
\input{common_latex/common_latex_help_format}
\input{common_latex/common_latex_help_format}
%===================================================================

\begin{document}

\begin{labcover}
\labtitle{The alogview Tool for Analyzing Mission Log Files}
\vspace{0.1in}
\labdate{Dec 2022}
\vspace{0.1in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Department of Mechanical Engineering}
\labauth{MIT, Cambridge MA 02139}
\labtoc{small}
\end{labcover}

\wikidoc{file=IvPTools.ALogView}
\wikidoc{bugz=alogview}
\wikidoc{auth=mikerb@mit.edu}

%=================================================================
\section{Overview}
%=================================================================
\label{sec_alogview}

The \app{alogview} application is a post-mission analysis utility
loaded with one or more alog files, typically one per vehicle. It is
more than a log file playback tool. A full state is maintained across
all vehicles for both playing back sequentially and rewinding or
jumping to any arbitrary point in time. The main window may look a bit
like the run-time \app{pMarineViewer} window, but many of the GUI
components in \app{alogview} are available solely for post-mission
analysis. A snapshot of the tool, with no pop-up sub-windows open, is
shown in Figure \ref{fig_alv_main}.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.92\textwidth]{figures/alv_main.png}
  \caption{{\bf The \vvar{alogview} tool}: used for post-mission
    rendering of alog files from one or more vehicles and stepping
    through time to analyze helm status, IvP objective functions, and
    other logged numerical data correlated to vehicle position in the
    op-area and time.}
\label{fig_alv_main}
\end{figure}

\vspace{0.1in} 
\noindent
Quick Start: Launch \app{alogview} with one or more alog files on the
command line, for example the two vehicle alog files from the
\var{m2\_berta} example mission:

\vspace{0.1in}
\begin{consoleverb}
 $ alogview henry.alog gilda.alog
\end{consoleverb}
\vspace{0.1in}

\noindent
Upon launch, the viewer should look similar to Figure \ref{fig_alv_main}.
Step forward or backward through time with the \var{'['} or \var{']'} keys, 
or click anywhere in the time-series in the bottom part of the screen. Replay
can also be automated by accelerating or decelerating replay with the \var{'a}
or \var{'z'} characters. Many other replay and visualization options are 
available via the pull-down menus and are introduced in later sections. 

%=================================================================
\section*{Recent History of Development with Releases}

\begin{packed_itemize}

\item Pre-2011: This tool existed as \cmd{logview}, was not
  documented and had limited support for rendering objective functions
  and helm information.  Mostly used in-house by developers.

\item 2011: Better support for IvP function rendering. Initial thin
  documentation. Support added for geometric log entries. Still very
  buggy but useful enough to share with other adventurous
  users. Biggest limitations: (a) initial full-alog load into memory
  too huge for anything but small missions. (b) no general scoping
  tool available for non-numerical data, (c) many little bugs or
  incomplete features.

\item 2015: First real attempt to support users generally outside core
  developers. Better memory management for large and/or multi-vehicle
  missions. New scope for non-numerical data. Pop-up implementation of
  sub-windows. Unlimited sub-windows supported for multi-vehicle
  missions. Overall much less buggy and more feature-rich.
\end{packed_itemize}


%There are two general modes of interaction. Upon startup, the tool is
%"paused" at a particular instance in time, and the user may step
%forward or backward, or jump to any point in time by clicking in the
%lower pane containing time series data. Alternatively, the user may be
%in a "Replay" mode where the time is incremented automatically at a
%user specified speed with a user-specified refresh rate. This is
%useful for running alongside a third party video capture tool (e.g.,
%QuickTime in OSX) for mission videos. The Replay mode is discussed in
%more detail in Section \ref{sec_alv_replay}.

%=================================================================
\section{The Five Primary Viewing Windows}
%=================================================================

The \app{alogview} tool can be described by its five GUI components,
listed below. The first two are always open upon startup, and the
remaining three are upon user request via the pull-down menus:

\begin{packed_itemize}
\item The {\em NavPlot} window: This is the main vehicle viewing area
  shown at the top in Figure \ref{fig_alv_main}. It primarily shows
  the current vehicle position(s) and perhaps recent trajectory and
  other geometric artifacts produced by the vehicle apps or behaviors,
  such as waypoints or sensor artifacts. More detail in Section
  \ref{sec_alv_navplot}.

\item The {\em LogPlot} window: This is the time-series window shown
  at the bottom in Figure \ref{fig_alv_main}. The variable's rendered
  are selected by the user from the list any logged numerical data
  from any vehicle. More detail in Section \ref{sec_alv_logplot}.

\item The {\em IPFPlot} window: (pronounced "i-p-f-plot") This is a
  pop-up window launched from the \var{IPFPlots} pull-down menu, for a
  chosen vehicle. It will render the prevailing IvP objective
  functions responsible for latest helm decision. More detail in
  Section \ref{sec_alv_ipfplot}.

\item The {\em HelmPlot} window: This is a pop-up window launched from
  the \var{HelmPlots} pull-down menu, for a chosen vehicle. It shows
  the helm state in terms of active, running, idle behaviors, as well
  as behavior warnings, errors and life events. More detail in Section
  \ref{sec_alv_helmplot}.

\item The {\em VarPlot} window: This is a pop-up window launched from
  the \var{VarPlots} pull-down menu, for a chosen vehicle, and chosen
  logged MOOS variable (string or double). It shows an ordered list of
  recent and pending postings for the given variable. Additional
  variables can be added resulting in an interleaved sequence. More
  detail in Section \ref{sec_alv_varplot}.
\end{packed_itemize}

\vspace{0.1in}
\noindent
In all windows, the current time can be altered with the same keyboard
hot keys, found in the \var{Replay} pull-down menu and described in Section
\ref{sec_alv_navplot}.


%=================================================================
\section{The NavPlot Window and Controlling Replay}
%=================================================================
\label{sec_alv_navplot}

The {\em NavPlot} window is the main viewing space, shown upon startup, 
with the current and recent vehicle positions rendered for each vehicle
alog file. It is the top part shown in Figure \ref{fig_alv_main}. 

%=================================================================
\subsection{Controlling the Current Time in Paused Mode}
\label{sec_alv_time_paused}

By default \app{alogview} is paused upon startup. The options for stepping
forward and backward through time may be seen from the \var{Replay} pull-down
menu. There are three pairs of options:

\vspace{0.1in}
\begin{packed_itemize}
\item The \var{'['} and \var{']'} keys for stepping forward and
  backward by 1 second.
\item The \var{'{'} and \var{'}'} keys for stepping forward and
  backward by 5 seconds.
\item The \var{'ctrl-['} and \var{'ctrl-]'} keys for stepping forward
  and backward by 0.1 seconds.
\end{packed_itemize}
\vspace{0.1in}

%=================================================================
\subsection{Controlling the Current Time in Streaming Mode}
\label{sec_alv_time_replay}

Replay may also be put into a streaming mode at any time by
accelerating or decelerating the streaming speed. Streaming is
controlled by the following three keys:

\vspace{0.1in}
\begin{packed_itemize}
\item The \var{'a'} key will accelerate the time warp, doubling the
  warp upon each successive hit, up to 64Hz.
\item The \var{'z'} key will decelerate the time warp, halving the
  warp upon each successive hit, down to 1/8Hz.
\item The \var{'SPACEBAR'} key will pause or unpause the streaming
  mode at any time.
\end{packed_itemize}
\vspace{0.1in}

\noindent
The time warp is always shown in the very top of the \var{alogview}
window. When streaming at say 16Hz, you should see \var{(Time Warp =
  16)} in the window title bar. When not streaming, i.e., paused, this
is indicated instead of the time warp, as in Figure
\ref{fig_alv_main}.

\pskip

Note that in streaming, between each update, there is work going on
under the hood in addition to the rendering tasks. This includes the
update of the current state of what is being rendered in the main and
pop-up windows. Often it is not possible to refresh at the time warp
requested. In this situation, \app{alogview}, and your machine, will
do the best it can to keep up. Instead of seeing \var{(Time Warp =
  16)} in the title bar, you may see something like \var{(Time Warp =
  16)(Actual:8.73)}.  The latter number will vary, but represents the
best warping rate possible given what is being updated between
refreshes.

\pskip

A faster observed time warp can be achieved by altering the {\em
  streaming redraw interval}. By default this interval is 0.5
seconds. So, for example, if the replay time warp is 4, then 8
re-draws will need to be handled per second. This may or may not be
achievable. If the redraw interval is instead 1.0 seconds, then half
as many re-draws are required for the same effective time warp. The
drawback will be that the motion of the vehicle and objects will
appear more "jumpy". The {\em streaming redraw interval} may be altered
in the \var{Replay} pull-down menu.

%-----------------------------------------------------------------------                      
\input{help_mip_bkg_images}

%=================================================================
\section{Video Capture}
%=================================================================

Video capture is no longer natively supported in \var{alogview} due to
the common availability of third party video capturing software. Just
launch \app{alogview}, put it into streaming mode (Section
\ref{sec_alv_time_replay}) at the desired rate, and launch your
favorite video capture program.


%=================================================================
\section{The LogPlot Window For Viewing Time-Series Data}
%=================================================================
\label{sec_alv_logplot}

The {\em LogPlot} window allows the rendering of any numerical data
from any loaded alog file to be plotted against time, as shown in
Figure \ref{fig_alv_main} and up close in Figure \ref{fig_alv_logplot}
below. The user may zoom in to see finer resolution in the postings,
by clicking either the \var{IN} or \var{OUT} buttons, or by the
\var{'i'} or \var{'o'} keys while the mouse is in the {\em LogPlot}
window. To return to the original full apperature zoom, hit the
\var{RESET} button.  The user may left-click at any point in the time
series to adjust the current time (shown by the red bar in the
viewer). This time adjustment is propagated not only to the {\em
  NavPlot} viewer but to all open pop-up windows.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=1.0\textwidth]{figures/alv_logplot.png}
  \caption{{\bf The \vvar{logplot} window}: is used for viewing any
    numerical data found in any of the alog files loaded into
    \app{alogview}. Here the desired and actual vehicle headings are
    logged side-by-side.}
  \label{fig_alv_logplot}
\end{figure}

\vspace{0.1in} 
\noindent
Two variables, and two y-axes are available for selection. By default
they are drawn on independent scales to allow variables with starkly
different ranges, such as speed and heading, to be meaningfully
rendered. The user may choose to synchronize the two variable ranges
rendered to allow for more meaningful comparisons when the two
variables have the same range, such as desired and observed
speed. The synchronization is done by hitting the \var{SYNC} button at
the top of the logplot window. The user chooses which two variables
are rendered from the pull-down menu as shown in Figure
\ref{fig_alv_logplot_pd}.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.7\textwidth]{figures/alv_logplot_pulldown.png}
  \caption{{\bf The \vvar{logplot} pull-down menu}: is used for first selecting
  the vehicle and then the variable to be plotted.}
\label{fig_alv_logplot_pd}
\end{figure}

\vspace{0.1in} 
\noindent
If you find yourself wanting to repeatedly open an alog file with same 
one or two variables chosen for the {\em LogPlot} window, these variables
can be chosen and at launch time passed as command line arguments: 

\vspace{0.1in}
\begin{consoleverb}
 $ alogview --lp=henry:NAV_SPEED --rp=gilda:NAV_SPEED
\end{consoleverb}

%=================================================================
\subsection{Using the Detached Variable Option}

Certain string log entries may be in the format of multi-part comma-separated
pairs (CSP). For example:

\vspace{0.1in}
\begin{fileverb}
  REPORT =  x=77, y=99, speed=3.2, depth=4.5, heading=93, battery_level=16.4
\end{fileverb}
\vspace{0.1in}

\noindent
Normally, during the split/cache stage at launch time, would create a
single \var{.klog} file, \var{REPORT.klog}.  However, one or more
fields may be desired for plotting in alogview
With the optional \var{--detached=VARNAME} command line argument, the
variable \var{VARNAME} will be parsed and separate \var{.klog} files
created for sub-components of the contents of the string. For example,
the following argument:

\vspace{0.1in}
\begin{consoleverb}
  $ alogview --detached=REPORT file.alog
\end{consoleverb}
\vspace{0.1in}

\noindent
would result in the creation of \var{.klog} files for each of the
sub-components: 

\vspace{0.1in}
\begin{consoleverb}
  REPORT:x.klog
  REPORT:y.klog
  REPORT:speed.klog
  REPORT:depth.klog
  REPORT:heading.klog
  REPORT:batter_level.klog
\end{consoleverb}
\vspace{0.1in}

\noindent
If the run-time speed of launching \cmd{alogview} is a concern,
especially on very large files, the above action can be quickened by
isolating just the sub-component of interest:


\vspace{0.1in}
\begin{consoleverb}
  $ alogview --detached=REPORT:speed file.alog
\end{consoleverb}
\vspace{0.1in}

\noindent
would create just the following \var{.klog} file:

\vspace{0.1in}
\begin{consoleverb}
  REPORT:speed.klog
\end{consoleverb}
\vspace{0.1in}

\noindent
If two or more sub-components are desired, the following two
equivalent invocations could be used:

\vspace{0.1in}
\begin{consoleverb}
  $ alogview --detached=REPORT:speed --detached=REPORT:depth file.alog
  $ alogview --detached=REPORT:speed:depth file.alog
\end{consoleverb}
\vspace{0.1in}

\noindent
would create just the following two \var{.klog} files:

\vspace{0.1in}
\begin{consoleverb}
  REPORT:speed.klog
  REPORT:depth.klog
\end{consoleverb}
\vspace{0.1in}

\noindent
If a detached variable is named, e.g., a file like
\var{REPORT:depth.klog} is created, then \cmd{alogview} will now have
this as a pull-down menu option for plotting.

\vspace{0.1in}
\noindent
Note, if the string is in JSON format, e.g.

\vspace{0.1in}
\begin{fileverb}
  REPORT =  {"x":77, "y":99, "speed":3.2, "depth":4.5, "heading":93}
\end{fileverb}
\vspace{0.1in}

\noindent
then \cmd{alogview} will internally convert this into CSP format, and
will handle accordingly.


%=================================================================
\subsection{Additional Buried but Useful Hot-Keys in the LogPlot Window}

There are a few hot-key functions available (only when the main window
is active and the mouse is over the {\em LogPlot} window, that may not
be apparent from simply interacting with the window:

\begin{packed_itemize}
\item The \var{'i'} key: will zoom in the resolution on the plot. This can 
  also be done by hitting the \var{IN} button. 
\item The \var{'o'} key: will zoom out the resolution on the plot. This can 
  also be done by hitting the \var{OUT} button. 
\item The \var{'LEFT'} and \var{'RIGHT'} keys: will step forward and backward
  through time by 1 second.
\item The \var{'UP'} and \var{'DOWN'} keys: will zoom in and out on the plot, 
  essentially the same as the \var{'i'} and \var{'o'} keys.
\end{packed_itemize}

\vspace{0.1in}
\noindent
The above hot-keys are in addition to the time control hot-keys listed
in Section \var{sec\_alv\_time\_replay} and Section \ref{sec_alv_time_paused}.


%=================================================================
\section{The IPFPlot Window For Viewing Helm Objective Functions}
%=================================================================
\label{sec_alv_ipfplot}

The {\em IPFPlot} window allows the rendering of an IvP function (IPF)
from any vehicle and any behavior found in any of the alog files
loaded into \app{alogview}. 

%=================================================================
\subsection{Launching an IPFPlot Window}

An {\em IPFPlot} pop-up window is launched from the \app{alogview}
main pull-down window as shown in Figure \ref{fig_alv_ipfplot_pd}, by
choosing a vehicle name. Separate windows can be opened for different
vehicles, or even for the same vehicle.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.76\textwidth]{figures/alv_ipfplot_pd.png}
  \caption{{\bf The \vvar{ipfplot} pull-down menu}: is used for first
    selecting the vehicle and then the variable to be plotted.}
\label{fig_alv_ipfplot_pd}
\end{figure}

\vspace{0.1in} 
\noindent
A newly launched pop-up window loads the relevant information from
disk into the \app{alogview} memory space. This includes all IvP
functions for all behaviors at all times, for the given vehicle. This
can be large.  For some (larger) missions and some computer
configurations, the larger memory footprint will begin to be noticed
in terms of application responsiveness. Likewise, the internal data
structure updates, each time the current time is changed, increases
for each pop-up window. This may result in a slower streaming rate
when in replay. Closing the pop-up window releases the memory and should
immediately boost responsiveness and playback rate.

%=================================================================
\subsection{Stepping Through Time and Replay Control in the IPFPlot Window}

The current time is shown in the upper left corner and is synchronized
with the main viewing window and any other pop-up windows that may be
open. The same time keys are functional when this window is active,
e.g., \var{'['}, \var{']'}, \var{'{'}, \var{'}'}, for stepping forward
and backward in time. The replay control keys, e.g., \var{'a'},
\var{'z'}, are also functional, and the replay state and rate is also
shown in the title bar of this window.


%=================================================================
\subsection{Selecting the IvP Function in the IPFPlot Window}

The user may choose any single objective function at a time from the
menu on the left side of the window shown in Figure
\ref{fig_alv_ipfplot}. The current behavior weight is shown alongside
the behavior name in the menu. If a behavior presently has a weight of
zero, no function will be rendered when that behavior is selected.
Multiple objective functions may be viewed simultaneously by launching
more pop-up windows.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.7\textwidth]{figures/alv_ipf.png}
  \caption{{\bf The \vvar{ipfplot} window}: used for examining IvP
    functions for the chosen vehicle at the current time.}
\label{fig_alv_ipfplot}
\end{figure}

\vspace{0.1in} 
\noindent
Since each window is associated with a particular vehicle, the helm
iteration may be shown unambiguously in the redish window in the
upper left. The rendering of the IvP function may be rotated or tilted
for different perspectives by using the arrow keys. The perspective
may be returned to the bird's eye view by hitting the \var{SET}
button. 

%=================================================================
\subsection{Rendering the Collective IvP Function in the IPFPlot Window}

IvP functions of two forms are renderable - those defined over course
and speed, and those defined over depth. In both cases, a rendering of
the collective function is possible by clicking on the
\var{Collective} or \var{CollectiveD} check-boxes on the left. In
Figure \ref{fig_alv_ipfplotb} below, the collective objective function
is shown, showing the weighted sum of the two behaviors The purplish
pin rendered in Figures \ref{fig_alv_ipfplot} and
\ref{fig_alv_ipfplotb} shows the actual chosen decision for the
present helm iteration. When rendering the collective function as in
Figure \ref{fig_alv_ipfplotb} the pin should be visually consistent
with the peak of the function. When rendering a single objective
function, as in Figure \ref{fig_alv_ipfplot}, the pin may not visually
correlate to the peak of the function since other functions may be in
play. For example in Figure \ref{fig_alv_ipfplot} the pin identifies
one of many points on the red plateau. The pin can be toggled on and off
by hitting the \var{PIN} button.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.6\textwidth]{figures/alv_ipfplot_b.png}
  \caption{{\bf The \vvar{ipfplot} window}: showing here the collective
    objective function representing the weighted sum of the two active
    behaviors.}
\label{fig_alv_ipfplotb}
\end{figure}
\vspace{0.1in} 

%=================================================================
\subsection{Variable Scoping Within the IPFPlot Window}

Often it is useful to scope on a couple key variables related to the
rendered objective function, to observe how they change and perhaps
influence the function as time evolves. Although a general scoping
ability exists via the {\em VarPlot} window described below in Section
\ref{sec_alv_varplot}, it can be handy to see the variable value(s)
right in the {\em IPFPlot} window. The two pull-down menu buttons in
the upper right in Figure \ref{fig_alv_ipfplotb} allow the selection
of two variables whose values are output in the upper and lower left
hand corners of the window as shown. The choice of these two variables
is specific to the chosen behavior, or collective function. A
different set of variables my be associated with each behavior, and
they will be refreshed accordingly as the user switches between
behaviors.


%=================================================================
\subsection{Additional Buried but Useful Hot-Keys in the IPFPlot Window}

There are a few hot-key functions available that may not be apparent from
simply interacting with the window:

\begin{packed_itemize}
\item The \var{'+'} key: will increase the font size in the browser pane, 
  and the font size of any scoped variable.
\item The \var{'-'} key: will decrease the font size in the browser panes,
  and the font size of any scoped variable.
\item The \var{'c'} key: will toggle the IvP function rendering from an 
  individual selected function to the collective objective function.
\item The \var{'f'} key: will put the window in a "full-window" mode showing
  only the rendered objective function, without the browser pane.
\item The \var{'UP'} and \var{'DOWN'} keys: will tilt the rendered objective
  functions.
\item The \var{'LEFT'} and \var{'RIGHT'} keys: will rotate the rendered
  objective functions.
\end{packed_itemize}

\vspace{0.1in}
\noindent
The above hot-keys are in addition to the time control hot-keys listed
in Section \var{sec\_alv\_time\_replay} and Section \ref{sec_alv_time_paused}.


%=================================================================
\section{The HelmPlot Window For Viewing Helm State}
%=================================================================
\label{sec_alv_helmplot}

The {\em HelmPlot} window renders information regarding the 
present helm state, including which behaviors are in which state and for
how long, summary of update attempts for each behavior, behavior warnings, 
behavior errors, a history of helm mode changes, and a history of helm
life events. 

%=================================================================
\subsection{Launching the HelmPlot Window}

The {\em HelmPlot} pop-up window is launched from the \app{alogview}
main pull-down window as shown in Figure \ref{fig_alv_helmplot_pd}, by
choosing a vehicle name. Separate windows can be opened for different
vehicles, or even for the same vehicle.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.76\textwidth]{figures/alv_helm_pd.png}
  \caption{{\bf The \vvar{helmplot} pull-down menu}: is used for first
    selecting the vehicle and launching the {\em HelmPlot} window.}
\label{fig_alv_helmplot_pd}
\end{figure}

\vspace{0.1in} 
\noindent
A newly launched pop-up window loads the relevant information from
disk into the \app{alogview} memory space. For some (larger) missions
and some computer configurations, the larger memory footprint will
begin to be noticed in terms of application responsiveness. Likewise,
the internal data structure updates, each time the current time is
changed, increases for each pop-up window. This may result in a slower
streaming rate when in replay.

%=================================================================
\subsection{Stepping Through Time and Replay Control in the HelmPlot Window}

The current time is shown in the upper left corner and is synchronized
with the main viewing window and any other pop-up windows that may be
open. The same time keys are functional when this window is active,
e.g., \var{'['}, \var{']'}, \var{'{'}, \var{'}'}, for stepping forward
and backward in time. The replay control keys, e.g., \var{'a'},
\var{'z'}, are also functional, and the replay state and rate is also
shown in the title bar of this window.  

%=================================================================
\subsection{Behavior States in the Helm Plot Window}

Each behavior known to the helm up to the present time is grouped into
a list of either active, running, idle or completed modes as shown in
Figure \ref{fig_alv_helmplot}. 

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.7\textwidth]{figures/alv_helm.png}
  \caption{{\bf The \vvar{helmplot} window}: used for analyzing the 
    helm state and behavior modes.}
\label{fig_alv_helmplot}
\end{figure}

\vspace{0.1in} 
\noindent
For each behavior, the behavior name is listed, along with the elapsed
time since the behavior has been in that mode. If the behavior is
configured with the \bvar{updates} parameter, then the number of
successful vs attempted updates are also listed. If the behavior does
not have the \bvar{updates} parameter set, then \var{n/a} will instead
be listed in that column as with the station-keep behavior in the
figure below.  For active, behaviors, the present priority weight and
number of pieces is also shown.

%=================================================================
\subsection{Behavior Warnings, Errors, Mode History and Life Events}

The bottom pane of the {\em HelmPlot} window may have one of four
content modes, selectable with the check-box shown.

\begin{packed_itemize}
\item {\em Behavior Warnings}: In this mode, all behavior warnings, in
  the form of messages written to \mvar{BHV\_WARNING}, will be listed
  in chronological order with the most recent at the top. One handy
  feature is that the existence of possible future warnings can be see
  in the check-box label. In parentheses, \var{(a/b)} indicates that
  $a$ warnings are shown in the list out of $b$ warnings total for the
  mission.
\item {\em Behavior Errors}: In this mode, all behavior errors, in the
  form of messages written to \mvar{BHV\_ERROR}, will be listed in
  chronological order with the most recent at the top.  In the
  check-box label, in parentheses, \var{(a/b)} indicates that $a$
  errors are shown in the list out of $b$ errors total for the
  mission.
\item {\em Mode History}: In this viewing mode, all helm mode changes
  will be listed in chronological order with the most recent at the
  top.
\item {\em Life Events}: In this viewing mode, all helm life events
  (behavior spawning and deaths) will be listed in chronological
  order with the most recent at the top.
\end{packed_itemize}

%=================================================================
\subsection{Additional Buried but Useful Hot-Keys in the HelmPlot Window}

There are a few hot-key functions available that may not be apparent from
simply interacting with the window:

\begin{packed_itemize}
\item The \var{'+'} key: will increase the font size in the browser pane, 
  and the font size of any scoped variable.
\item The \var{'-'} key: will decrease the font size in the browser panes,
  and the font size of any scoped variable.
\item The \var{'UP'} and \var{'DOWN'} keys: will tilt the rendered objective
  functions.
\item The \var{'LEFT'} and \var{'RIGHT'} keys: will rotate the rendered
  objective functions.
\end{packed_itemize}

\vspace{0.1in}
\noindent
The above hot-keys are in addition to the time control hot-keys listed
in Section \var{sec\_alv\_time\_replay} and Section
\ref{sec_alv_time_paused}.


%=================================================================
\section{The VarPlot Window For Viewing Variable Histories}
%=================================================================
\label{sec_alv_varplot}

The {\em VarPlot} window renders the full history of one or more chosen
MOOS variables, allowing the user to see the present value, recent postings, 
and upcoming pending postings. This holds for both numerical and string
variables. 

%=================================================================
\subsection{Launching the VarPlot Window}

The {\em VarPlot} pop-up window is launched from the \app{alogview}
main pull-down window as shown in Figure \ref{fig_alv_varplot_pd}, by
choosing a vehicle name, and MOOS variable name. Separate windows can
be opened for different vehicles, variables, or even for the same vehicle 
and variable. Although one variable is chosen upon launch, any number of
variables can be inserted later from the VarPlot pull-down buttons

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.8\textwidth]{figures/alv_varplot_pd.png}
  \caption{{\bf The \vvar{VarPlot} pull-down menu}: is used for first
    selecting a vehicle and variable name, and launching the {\em
      VarPlot} window.}
\label{fig_alv_varplot_pd}
\end{figure}

\vspace{0.1in} 
\noindent
A newly launched pop-up window loads the variable history information
from disk into the \app{alogview} memory space. For some (larger)
missions and some computer configurations, the larger memory footprint
will begin to be noticed in terms of application
responsiveness. Likewise, the internal data structure updates,
conducted each time the current time is changed, increases for each
pop-up window. This may result in a slower streaming rate when in
replay. Closing the pop-up window releases the memory and should
immediately boost responsiveness and playback rate.

%=================================================================
\subsection{Viewing the Variable History in the VarPlot Window}

The {\em VarPlot} window contains two primary panes. The top pane
shows everything in the past, up to the most recent post. The bottom pane
shows everything in the future, starting with the next pending post. 
The "current time" can be regarded as being in between the two panes. 

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.6\textwidth]{figures/alv_hist.png}
  \caption{{\bf The \vvar{VarPlot} window}: used for scoping on a set
    of MOOS variables into the past and upcoming in the future.}
\label{fig_alv_varplot}
\end{figure}

\vspace{0.1in} 
\noindent
Each variable posting has six components, separated into six columns in both
panes:

\begin{packed_itemize}[2]
  \item {\em Time}: The timestamp of the posting. This is always shown in the
    first column.
  \item {\em Node}: The node, i.e., vehicle name is shown in the second column.
    Since the scope may contain values across nodes, this can be useful to see. 
    If only scoping on one variable, or if all variables are from the same node, 
    then this column can be hidden by toggling the \var{Node} check-box.
  \item {\em Variable Name}: If scoping on only one variable, this third column
    may be hidden to provide more visibility to the other columns.
  \item {\em Source}: The source, i.e., MOOS App that generated the posting, 
    is shown in the fourth column. This may be toggled on or off.
  \item {\em Auxiliary Source}: The auxiliary source is shown in the
    fifth column. Most MOOS apps do not make postings with an
    auxiliary source. The helm does however, and this typically
    indicates the particular behavior that produced the posting.
  \item {\em Variable Value}: The last column is just the value of the posting. 
    This column cannot be hidden.
\end{packed_itemize}

%=================================================================
\subsection{Adding and Removing Variables from the History List}

Upon launching the {\em VarPlot} window, a single variable is
chosen. After launching, additional variables may be added (from any
vehicle) from the \var{Add Variable} pull-down menu button as shown in
Figure \ref{fig_alv_varplot_add}. The \var{Set Variable} button
presents the same set of choices, but will essentially remove all
previously selected variables and replace it with the chosen one. The
\var{Del Variable} button will remove the selected variable from the
current set of variables.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.6\textwidth]{figures/alv_varplot_addvar.png}
  \caption{{\bf The \vvar{VarPlot} window}: Any variable from any vehicle
    may be added any time after the window is opened.}
\label{fig_alv_varplot_add}
\end{figure}


%=================================================================
\subsection{Additional Buried but Useful Hot-Keys in the VarPlot Window}

There are a few hot-key functions available that may not be apparent from
simply interacting with the window:

\begin{packed_itemize}
\item The \var{'+'} key: will increase the font size in the browser panes.
\item The \var{'-'} key: will decrease the font size in the browser panes.
\end{packed_itemize}

\vspace{0.1in}
\noindent
The above hot-keys are in addition to the time control hot-keys listed
in Section \var{sec\_alv\_time\_replay} and Section \ref{sec_alv_time_paused}.


%=================================================================
\section{Command Line Usage for the alogview Tool}
%=================================================================

The \app{alogview} tool is run from the command line with one or more
given \var{.alog} files and a number of options.  The usage options are
listed when the tool is launched with the \var{-h} switch:

\begin{consoleverb}
 $ alogview --help or -h
\end{consoleverb}

\vspace{0.1in}
\begin{listing}{Command line usage for the \app{alogview} tool}
\label{alogview_usage}
\scriptsize
\begin{verbatim}
   1  Usage:                                                         
   2    alogview file.alog [another_file.alog] [OPTIONS]             
   3                                                                 
   4  Synopsis:                                                      
   5    Renders vehicle paths from multiple MOOS .alog files. Replay 
   6    logged data or step through manually. Supports several       
   7    specialized pop-up windows for viewing helm state, objective 
   8    functions, any logged variable across vehicles. If multiple  
   9    alog files are given, they will synchronized. Upon launch,   
  10    the original alog files are split into dedicated directories  
  11    to cache data base on the MOOS variable name.                
  12                                                                 
  13  Standard Arguments:                                            
  14    file.alog - The input logfile.                               
  15                                                                 
  16  Options:                                                      
  17    -h,--help       Displays this help message                  
  18    -v,--version    Displays the current release version        
  19    -vb, --verbose  Verbose output                              
  20                                                                
  21    --bg=file.tiff  Specify an alternate background image.      
  22                                                                
  23    --lp=VEH:VAR    Specify starting left log plot.             
  24    --rp=VEH:VAR    Specify starting right log plot.            
  25                    Example: --lp=henry:NAV_X                   
  26                    Example: --rp=NAV_SPEED                     
  27                                                                
  28    --bv=BHV:VAR    Assoc scope var w/ behavior for IPF viewer. 
  29                                                              
  30  --nowtime=val   Set the initial startup time                
  31  --mintime=val   Clip all times/vals below this time         
  32  --maxtime=val   Clip all times/vals above this time         
  33                                                              
  34  --quick,-q      Quick start (no geo shapes, logplots)       
  35  --altnav=PREF   Alt nav solution prefix, e.g., NAV_GT_      
  36                                                              
  37  --zoom=val      Set initial zoom value (default: 1)         
  38  --panx=val      Set initial panx value (default: 0)         
  39  --pany=val      Set initial pany value (default: 0)         
  40                                                              
  41  --grep=str1     Set grep pattern 1 in AppLog viewer         
  42  --grep=str2     Set grep pattern 2 in AppLog viewer         
  43                                                              
  44  --alc=FILE      Read config params from file named FILE.    
  45                  FILE may contain any param except this one. 
  46                                                              
  47  --geometry=xsmall  Open GUI with dimensions 770x605         
  48  --geometry=small   Open GUI with dimensions 980x770         
  49  --geometry=medium  Open GUI with dimensions 1190x935        
  50  --geometry=large   Open GUI with dimensions 1400x1100       
  51  --geometry=WxH     Open GUI with dimensions WxH             
  52                                                              
  53  --detached=var          Detached var for plotting           
  54  --detached=var:key      Detached var for plotting           
  55                                                              
  56  --seglist_viewable_all=true/false                           
  57  --seglist_viewable_labels=true/false                        
  58  --seglr_viewable_all=true/false                             
  59  --seglr_viewable_labels=true/false                          
  60  --point_viewable_all=true/false                             
  61  --point_viewable_labels=true/false                          
  62  --vector_viewable_all=true/false                            
  63  --vector_viewable_labels=true/false                         
  64  --circle_viewable_all=true/false                            
  65  --circle_viewable_labels=true/false                         
  66  --grid_viewable_all=true/false                              
  67  --grid_viewable_labels=true/false                           
  68  --range_pulse_viewable_all=true/false                       
  69  --trails_color=COLOR                                        
  70  --hash_vieweble=true/false                                  
  71  --tiff_viewable=true/false                                  
  72  --hash_delta={10,50,100,200,500,1000}                       
  73  --vehicles_shape_scale=(currently unsupported)              
  74  --vehicles_viewable=true/false                              
  75  --trails_point_size=(currently unsupported)                 
  76  --trails_viewable=true/false                                
  77  --trails_color=COLOR                                        
  78  --marker_viewable_all=true/false                            
  79  --marker_viewable_labels=true/false                         
  80  --polygon_viewable_all=true/false                           
  81  --polygon_viewable_labels=true/false                        
  82                                                              
  83  --web,-w   Open browser to:                                 
  84             https://oceanai.mit.edu/ivpman/apps/alogview     
  85                                                                
  86  Further Notes:                                                
  87    (1) Multiple .alog files ok - typically one per vehicle     
  88    (2) See also: alogscan, alogrm, alogclip, aloggrep          
  89        alogsort, alogiter, aloghelm                            
  90    (3) Config params may also be read from .alogview hidden    
  91        file if present in the directory where launched.  

\end{verbatim}
\end{listing}
\normalsize

\noindent
The order of the arguments passed to \app{alogview} do not matter.
The \var{--mintime} and \var{--maxtime} arguments allow the user to
effectively clip the alog files to reduce the amount of data loaded
into RAM by \app{alogview} during a session. The \var{--geometry}
argument allows the user to custom set the size of the display window.
A few shortcuts, \var{"large"}, \var{"medium"}, \var{"small"}, and
\var{"xsmall"} are allowed. 


\end{document}

% Todo
% NavPlot 
%  - zooming in-out, panning, 
%  - naming the pan/zoom upon alogview startup
%  - Vehicle shapes, size
%  - Under the hood - what variables are being stored? NAV_X, NAV_Y, NAV_HEADING, others?
%  - Trails 
% 
% 
% 
% 
% 
% 
% 
% 
% 
% 
% 
% 

</pre></body></html>