<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}
%===================================================================

\begin{document}

\begin{labcover}
\labtitle{pMarineViewer: A GUI for Mission Monitoring and Control}
\vspace{0.1in}
\labdate{December 2022}
\vspace{0.1in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Department of Mechanical Engineering}
\labauth{MIT, Cambridge MA 02139}
\labsrc{project-pavlab/apps/app\_pmviewer} 
\labtoc{small}
\end{labcover}

\wikidoc{file=IvPTools.PMViewer}
\wikidoc{bugz=pMarineViewer}
\wikidoc{auth=mikerb@mit.edu}

%===================================================================
\section{Overviewx}
%===================================================================
\label{sec_pmv}
%\index{pMarineViewer}
\label{sec_pmv_overview}

The \app{pMarineViewer} application is a MOOS application written with
FLTK and OpenGL for rendering vehicles and associated information and
history during operation or simulation. A screen shot of a simple one-vehicle
mission is shown below in Figure \ref{fig_pmv_alpha}.

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.78\textwidth]{figures/pmv_alpha.png}
  \caption{A \vvar{pMarineViewer} screen-shot executing a simple
    one-vehicle mission. The track of the vehicle is shown along with
    the set of waypoints it will traverse during this mission. }
\label{fig_pmv_alpha}
\end{figure}

\vspace{0.1in}
\noindent
The user is able manipulate a geo display to see multiple vehicle
tracks and monitor key information about individual vehicles. In the
primary interface mode the user is a passive observer, only able to
manipulate what it sees and not able to initiate communications to the
vehicles. However there are hooks available and described later in
this section to allow the interface to accept field control commands.
With Release 12.11, appcasting viewing is supported to allow the
\app{pMarineViewer} user to view appcasts across multiple fielded
vehicles within a single optional window pane. In the release
following 19.8, appcasting was complemented with realmcasting allowing
the user to view publications and subscriptions for any app on
multiple fielded vehicles. The user may also set up a watch cluster of
variables to monitor over a set of vehicles in a single pane. The
realmcasting utilities add quite a bit of power to developers of
multi-vehicle, i.e., swarm, autonomy missions.  This is described more
fully in Section \ref{sec_pmv_infocasting}.

%===================================================================
\subsection{The Shoreside-Vehicle Topology}
\label{sec_pmv_topology}

In some simple simulation single-vehicle arrangements
\app{pMarineViewer} may co-exist in the same MOOS community as the
helm and other components of a simulated vehicle. This is the case in
the Alpha example mission. A more typical module topology, however, is
that shown in Figure \ref{fig_pmv_topology}, where \app{pMarineViewer}
is running in its own dedicated local MOOS community while simulated
vehicles, or real vehicles on the water, transmit information in the
form of a stream of {\em node reports} to the local community.

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.7\textwidth]{figures/pmv_topology.png}
  \caption{A common usage of the \vvar{pMarineViewer} is to have it
    running in a local \aapp{MOOSDB} community while receiving node
    reports on vehicle poise from other MOOS communities running on
    either real or simulated vehicles.  The vehicles can also send
    messages with certain geometric information such as polygons and
    points that the view will accept and render.}
\label{fig_pmv_topology}
\end{figure}

\noindent
A key variable subscribed to by \app{pMarineViewer} is the variable
\mvar{NODE\_REPORT}, which has the following structure given by an
example:

\prevgreen
\begin{verbatim}
   NODE_REPORT = "NAME=henry,TYPE=uuv,TIME=1195844687.236,X=37.49,Y=-47.36,SPD=2.40,
                 HDG=11.17,LAT=43.82507169,LON=-70.33005531,TYPE=KAYAK,MODE=DRIVE,
                 ALLSTOP=clear,index=36,DEP=0,LENGTH=4"
\end{verbatim}
\postverb

\noindent
Reports from different vehicles are sorted by their vehicle name and
stored in histories locally in the \app{pMarineViewer} application.
The \mvar{NODE\_REPORT} is generated by the vehicles based on either
sensor information, e.g., GPS or compass, or based on a local vehicle
simulator. 

\vspace{0.1in}
\noindent
In addition to node reports, \app{pMarineViewer} subscribes to several
other types of information typically originating in the individual
vehicle communities. This include several types of geometric shapes for
which \app{pMarineViewer} has been written to handle. This includes points, 
polygons, lists of line segments, grids and so on. This is described
further in Section \ref{sec_pmv_geometry}.

\vspace{0.1in}
\noindent
In addition to consuming the above information, \app{pMarineViewer}
may also be configured to post certain information, usually for
command and control purposes. Since this is mission-specific, this
information is completely configured by the user to suit the
mission. Posted information may also be tied to mouse clicks to allow,
for example, a vehicle to be deployed to a point clicked by the
users. This is described further in Section \ref{sec_pmv_cmd_ctrl}.


%===================================================================
\subsection{Description of the pMarineViewer GUI Interface}
\label{sec_pmv_interface}

The viewable area of the GUI has three parts as shown in Figure
\ref{fig_pmv_panes} below. In the upper right, there is a geo display
area where vehicles and perhaps other objects are rendered.  The blue
panes on the upper left displays appcast information. These panes hold
appcast output from any appcast-enabled MOOS application running on
any node, including the shoreside node. This is a new feature of
Release 12.11 and may be toggled off and on with the \var{'a'} key,
and may be configured to be either open or closed by setting the
\pvar{appcast\_viewable} parameter inside the \app{pMarineViewer} MOOS
configuration block.  

\vspace{0.1in}
\noindent
In the lower pane, certain data fields associated with the {\em
  active} vehicle are updated.  Multiple vehicles may be rendered
simultaneously, but only one vehicle, the {\em active} will be
reflected in the data fields in the lower pane.  Changing the
designation of which vehicle is active can be accomplished by
repeatedly hitting the 'v' key. The active vehicle is always rendered
as red, while the non-active vehicles have a default color of yellow.
Individual vehicle colors can be given different default values (even
red, which could be confusing) by the user. 

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.99\textwidth]{figures/pmv_panes.png}
  \caption{ A screen shot of the \vvar{pMarineViewer} application
    running the alpha example mission. The position, heading, speed
    and other information related to the vehicle is reflected in the
    data fields at the bottom of the viewer.}
\label{fig_pmv_panes}
\end{figure}

Properties of the vehicle rendering such as the trail length, size,
and color, and vehicle size and color, and pan and zoom can be
adjusted dynamically in the GUI. They can also be set in the
\app{pMarineViewer} MOOS configuration block. Both methods of tuning
the rendering parameters are described later in this section.  The
individual fields of the data section are described below:

\small
\begin{itemize}
\item {\bf \var{VName}:} The name of the active vehicle associated with the
  data in the other GUI data fields. The active vehicle is typically
  indicated also by changing to the color red on the geo display.

\item {\bf \var{VType}:} The platform type, e.g., \pvar{auv}, \pvar{uuv},
  \pvar{glider}, \pvar{kayak}, \pvar{ship}, \pvar{heron}, \pvar{wamv},
  \pvar{buoy}, \pvar{mokai}, \pvar{longship}, \pvar{swimmer}
  or \pvar{unknown}. The buoy shape is just a circle. The swimmer shape
  is a triangle. 
 
\item {\bf \var{X(m)}:} The x (horizontal) position of the active vehicle
  given in meters in the local coordinate system.

\item {\bf \var{Y(m)}:} The y (vertical) position of the active vehicle
  given in meters in the local coordinate system.

\item {\bf \var{Lat}:} The latitude (vertical) position of the active
  vehicle given in decimal latitude coordinates.

\item {\bf \var{Lon}:} The longitude (horizontal) position of the active
  vehicle given in decimal longitude coordinates.

\item {\bf \var{Spd}:} The speed of the active vehicle given in meters
  per second.
    
\item {\bf \var{Hdg}:} The heading of the active vehicle given in
  degrees ($0-359.99$).

\item {\bf \var{Dep(m)}:} The depth of the active vehicle given in meters.

\item {\bf \var{Age(s)}:} The elapsed time in seconds since the last
  received node report for the active vehicle.

\item {\bf \var{Time}:} Time in seconds since \app{pMarineViewer}
  was launched.

\item {\bf \var{Warp}:} The MOOS Time-Warp value. Simulations may run
  faster than real-time by this warp factor. MOOSTimeWarp is set as a
  global configuration parameter in the \var{.moos} file.

\end{itemize}
\normalsize

The age of the node report is likely to remain zero in simulation as
shown in the figure, but when operating on the water, monitoring the
node report age field can be the first indicator when a vehicle has
failed or lost communications. Or it can act as an indicator of
communications link quality.

\vspace{0.1in}
\noindent
The lower three fields of the window are used for scoping on a single
MOOS variable. See Section \ref{sec_pmv_scoping} for information on
how to configure the \app{pMarineViewer} to scope on any number of
MOOS variables and select a single variable via an optional pull-down
menu.  The scope fields are:

\small
\begin{itemize}
\item {\bf \var{Variable}:} The variable name of the MOOS variable
currently being scoped, or \var{"n/a"} if no scope variables are 
configured. 

\item {\bf \var{Time}:} The variable name of the MOOS variable
currently being scoped, or \var{"n/a"} if no scope variables are 
configured. 

\item {\bf \var{Value}:} The actual current value for the presently
scoped variable.
\end{itemize}
\normalsize

%===================================================================
\subsection{The AppCasting, FullScreen and Traditional Display Modes}

As mentioned above, appcasting is new to release 12.11,
\app{pMarineViewer} supports three display modes. The first mode is
the {\em normal} mode familiar to pre-12.11 users of
\app{pMarineViewer} as it was the only mode. A second mode, the {\em
  appcasting} mode, also shows the three appcasting panes shown above
in Figure \ref{fig_pmv_panes}. The third mode is the {\em full-screen}
mode which shows only the geo-display part to maximize viewing of the
operation area. The modes may be toggled by single hot-key actions as
shown in the figure.

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.9\textwidth]{figures/pmv_modes.png}
  \caption{Three viewing modes are supported by \vvar{pMarineViewer}.
    The {\em normal} mode, the {\em infocasting} mode which renders
    appcast or realmcast output from any connected vehicle, or the {\em
      full-screen} mode to maximize viewing of the operation area and
    vehicles. The modes may be toggled with the hot-keys shown. When
    typing \vvar{'f'} in the full-screen mode, the viewer will return
    to the mode prior to entering the full-screen mode. The modes may
    also be changed via pull-down menu items, or set to personal
    preferences in the \vvar{.moos} configuration block. In software
    released after 19.8.x, the infocasting mode has two sub-modes, appcasting
  and realmcasting.}
\label{fig_pmv_modes}
\end{figure}

\noindent
To launch a mission in the appcasting mode, set
\pvar{appcast\_viewable}\psvar{=true} in the \app{pMarineViewer}
configuration block. To launch in the full-screen mode, set
\pvar{full\_screen}\psvar{=true} in the configuration block instead.

%===================================================================
\subsection{Run-Time and Mission Configuration}

Nearly all \app{pMarineViewer} configuration parameters may be
configured both at run-time, via pull-down menu selections, and prior
to launch via configuration lines in the \app{pMarineViewer}
configuration block of the \var{.moos} mission configuration file.  To
reduce the need to consult the documentation, the text of the
pull-down menu selection is identical to the text of the parameter in
the configuration file.  Furthermore, most parameter selections are a
choice from a fixed set of options. The present option for a parameter
is typically indicated by a radio button in the pull-down menu.

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.66\textwidth]{figures/pmv_radios.png}
  \caption{Most configuration parameters may be altered with pull-down
    menu selections. The radio-button shows the present parameter
    value and its neighbors show other legal settings. The text of the
    pull-down menu selection may be placed verbatim in the
    \vvar{.moos} configuration block to determine the setting upon the
    next mission launch. In general, menu items rendered in blue text
    are legally accepted parameters for placing in the \vvar{.moos}
    configuration block. Items in black are not.}
\label{fig_pmv_radios}
\end{figure}

\noindent
Most parameter options have either a hot key associated with each option
as shown in the left in Figure \ref{fig_pmv_radios}, or a hot key for 
toggling between options as on the right in the figure.

%===================================================================
\subsection{Recent Changes and Bug Fixes}

\subsubsection{Release 22.8.x}

Changes in Release 22.8.x (the first release after 22.8, until 22.8.1
is released, this means trunk/main).

\begin{packed_itemize}
\item A bug in loading multiple tiff files was fixed
\item Loading of multiple tiff files is supported, no longer limited to
  just two.
\item Tiff files can now be located using a shell path variable,
  \var{IVP\_IMAGE\_DIRS}.
\end{packed_itemize}

%-------------------------------------------------------------------
\subsubsection{Release 22.8 (Aug 2022)}

\begin{packed_itemize}
\item Major new augmentation to support RealmCasting, a powerful new
  tool for scoping on any app in a multi-vehicle mission. Clusters of
  variables can be configured to scope across multiple vehicles in a
  single table. This works in conjunction with a new app called
  pRealm, which requires no configuration and runs in each MOOS
  community. Toggling between appcasting and realmcasting is done with
  the \var{'a'} key.

\item Augmented the GUI to accept up to twenty buttons for command
  poking, up from the previous limit of four buttons. Buttons and info
  fields will automatically resize to accommodate however many buttons
  are used.

\item Command buttons, when hovering with the mouse, will show what is
  being commanded upon a button click.

\item \var{VPlug\_GeoShapes} class was modified to explicitly drop
  from memory shapes that arrive with \var{active=false}. Previously
  this would just result in the object being ignored, but not
  removed. This mod guards against unbounded memory growth in
  pMarineViewer in some longer missions.

\item \var{VPlug\_AppCastSettings} in \var{lib\_geometry} was replaced
  with \var{InfoCastSettings} in \var{lib\_apputil}. This class stores
  all the user preferences applicable to appcasting and
  realmcasting. The new class is also used by \app{uMACView}.

\item An additional variable, \var{REGION\_INFO}, is published upon startup,
  and whenever a new vehicle has been detected. This info holds info
  about the background image, the zoom, the datum, and the pan x/y
  info. It is intended simply to be logged, and used by alogview upon
  startup to replicate the background image and orientation to be
  similar to how pMarineViewer was launched.

\item Points and circles now have support to publish with a duration,
  and once the duration has been exceeded with now new publication
  (keyed on label), the object will be dropped from memory.

\item Improved rapid drawing for large sets of Polygons

\item Fixed bug where text/labels for objects off screen would be
  rendered on screen, appended to other objects' text, rather than
  simply not being drawn.

\item New Option of ingesting \var{NODE\_REPORT} info from
  uFldNodeComms as an intermediary. This enables smoother operation of
  pMarineViewer in missions with very high number of vehicles and very
  high time warp. Enabled with \mvar{node\_report\_unc=true}
  configuration. Of course must also be running \app{uFldNodeComms}.
  
\end{packed_itemize}


%===================================================================
\section{Command-and-Control}
%===================================================================
\label{sec_pmv_cmd_ctrl}

For the most part \app{pMarineViewer} is intended to be only a
receiver of information from the vehicles and the environment. Adding
command and control capability, e.g., widgets to re-deploy or
manipulate vehicle missions, can be readily done, but make the tool
more specialized, bloated and less relevant to a general set of users.
However, \app{pMarineViewer} does have a few powerful extendible
command and control capabilities under the hood. Each are simply ways
to conveniently post to the MOOSDB, and come in three forms: (a)
configurable pull-down menu actions, and (b) contextual mouse poking
with embedded oparea information, (c) configurable action buttons, and
in Release 17.7 and later, (d) a configure commander pop-up window.

%===================================================================
\subsection{Configurable Pull-Down Menu Actions}

The Action pull-down menu described in Section \ref{sec_pmv_actions} provides
a way to pre-define a set of MOOS postings, each selectable from the 
pull-down menu. For example, the alpha mission is configured with the 
below action: 

\prevblue
\begin{verbatim}
    action = RETURN = true
\end{verbatim}
\postverb

\noindent
This post to the MOOSDB correlates to a behavior condition of the helm
waypoint behavior with the return position. Actions may also be
grouped into a single pull-down selection, discussed in Section
\ref{sec_pmv_actions}.

%===================================================================
\subsection{Contextual Mouse Poking with Embedded OpArea Information}

The mouse left and right buttons may be configured to make a post to
the MOOSDB with value partly comprised of the point in the oparea
under the mouse when clicked. For example, rather than commanding the
vehicle to return to a pre-defined return position as the case above
implies, the user may use this feature to command the vehicle to a
point selected by the user at run time with a mouse click. The
configuration might look like:

\prevblue
\begin{verbatim}
    left_context[return] = RETURN_POINT = points = $(XPOS),$(YPOS)
    left_context[return] = RETURN = true
\end{verbatim}
\postverb

\noindent
This is discussed further in Section \ref{sec_pmv_mouse_context}.

%===================================================================
\subsection{Action Button Configuration}
\label{sec_pmv_action_buttons}

Perhaps the most visible form of command and control is with the few
action buttons configurable for on-screen use. For example, the
\var{DEPLOY} and \var{RETURN} buttons in the lower right corner as in
Figures \ref{fig_pmv_alpha}, and \ref{fig_pmv_panes}. These buttons,
for example, are configures as follows:

\prevblue
\begin{verbatim}
    button_one = DEPLOY # DEPLOY=true
    button_one = MOOS_MANUAL_OVERIDE=false # RETURN=false
    button_two = RETURN # RETURN=true
\end{verbatim}
\postverb

\noindent
The general syntax is:

\prevblue
\begin{verbatim}
    button_one   = &lt;label&gt; # &lt;MOOSVar&gt;=&lt;value&gt; # &lt;MOOSVar&gt;=&lt;value&gt;  ...
    button_two   = &lt;label&gt; # &lt;MOOSVar&gt;=&lt;value&gt; # &lt;MOOSVar&gt;=&lt;value&gt;  ...
    button_three = &lt;label&gt; # &lt;MOOSVar&gt;=&lt;value&gt; # &lt;MOOSVar&gt;=&lt;value&gt;  ...
    button_four  = &lt;label&gt; # &lt;MOOSVar&gt;=&lt;value&gt; # &lt;MOOSVar&gt;=&lt;value&gt;  ...
\end{verbatim}
\postverb

\noindent
The left-hand side contains one of the four button keywords, e.g.,
\pvar{button\_one}. The right-hand side consists of a
\var{'\#'}-separated list. Each component in this list is either a
\var{'='}-separated variable-value pair, or otherwise it is
interpreted as the button's label. The ordering does not matter and
the \var{'\#'}-separated list can be continued over multiple lines as
in the simple example above.

\vspace{0.1in}
\noindent
The variable-value pair being poked on a button call will determine
the variable type by the following rule of thumb. If the value is
non-numerical, e.g., \var{true}, \var{one}, it is poked as a
string. If it is numerical it is poked as a double value. If one
really wants to poke a string of a numerical nature, the addition of
quotes around the value will suffice to ensure it will be poked as a
string. 

\vspace{0.1in}
\noindent
The couple of macros are supported for button clicks:

\begin{packed_itemize}
\item \var{\$[BIX]}: An integer that increments on each button click,
  regardless of whether other button clicks contain this macro.
  It starts at zero.
\item \var{\$[UTC]}: The current time in UTC seconds, in millisecond precision.
\end{packed_itemize}

\noindent
If either of these macros appear in isolation, they will be published
as type double, not type string. Support for this in the release after
Release 19.8.1.


%===================================================================
\subsubsection{Commander Pop-Up Window}
\label{sec_pmv_popup}

In Releases 17.7 the {\em commander pop-up} feature was added to
\app{pMarineViewer}. This can be thought of as the tool to use when
your mission requires the more than the four buttons allowed on the
lower right corner of the main screen (the {\em Action Buttons}
described above in Section \ref{sec_pmv_action_buttons}.  The
commander pop-up window contains user-configured commands to either
all vehicles, or particular vehicles, and commands to the shoreside if
desired.  If \app{pMarineViewer} is configured to use the commander
pop-up, this window is toggled open/closed with the space-bar key. It
also contains a log at the bottom of the window, showing exactly what
pokes to the MOOSDB are made upon each button click.

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.95\textwidth]{figures/pmv_command_popup.png}
  \caption{The commander pop-up window is toggled open/closed with the
    space-bar key and presents the user with a set of user-configured
    commands to either the all vehicles, individual vehicles, or the the
    \app{pMarineViewer} shoreside community itself.}
\label{fig_pmv_commander}
\end{figure}

\noindent
The above figure was generated from the \var{m2\_berta} mission, which
may be used as a good starting example.  This pop-up window is
configured in the \app{pMarineViewer} configuration block as described
further in Section \ref{sec_pmv_popup_full}.


%===================================================================
\section{The BackView Pull-Down Menu}
%===================================================================
\label{sec_pmv_backview}
%\index{pMarineViewer!Pull-Down Menu (BackView)}

The BackView pull-down menu deals mostly with panning, zooming and
issues related to the rendering of the background on which vehicles
and mission artifacts are rendered. The full menu is shown in Figure
\ref{fig_pmv_backview}.  
\begin{figure}[ht]
  \centering 
  \includegraphics[width=0.95\textwidth]{figures/pmv_backview.png}
  \caption{{\bf The BackView menu:} This pull-down menu lists the
    options, with hot-keys, for affecting rendering aspects of the
    geo-display background.}
\label{fig_pmv_backview}
\end{figure}
Although panning and zooming is not something typically done via the
pull-down menu, they are included in this menu primarily to remind the
user of their hot-keys.  The zooming commands affect the viewable area
and apparent size of the objects. Zoom in with the 'i' or 'I' key, and
zoom out with the 'o' or 'O' key. Return to the original zoom with
ctrl+'z'.


%===================================================================
\subsection{Panning and Zooming}
\label{sec_pmv_pan_zoom}
%\index{pMarineViewer!Panning and Zooming}

Panning is done with the keyboard arrow keys. Three rates of panning
are supported. To pan in 20 meter increments, just use the arrow
keys. To pan "slowly" in one meter increments, use the Alt + arrow
keys. And to pan "very slowly", in increments of a tenth of a meter,
use the Ctrl + arrow keys. The viewer supports two types of
"convenience" panning. It will pan to put the active vehicle in the
center of the screen with the 'C' key, and will pan to put the average
of all vehicle positions at the center of the screen with the 'c'
key. These are part of the 'Vehicles' pull-down menu discussed in
Section \ref{sec_pmv_vpulldown}.


%===================================================================
\subsection{Background Images}
\label{sec_pmv_bground_images}
%\index{pMarineViewer!Background Images}

The background can be in one of two modes; either displaying a
gray-scale background, or displaying a geo image read in as a texture
into OpenGL from an image file. The default is the geo display mode if
provided on start up, or the grey-scale mode if no image is provided.
The mode can be toggled by typing the 'b' or 'B' key.  The geo-display
mode can have two sub-modes if two image files are provided on
start-up. This is useful if the user has access to a satellite image
{\em and} a map image for the same operation area. The two can be
toggled by hitting the back tick key. After Release 22.8.x, multiple
tiff files may be provided, and toggling will cycle through all tiff
files.

\vspace{0.1in}
\noindent
When in the grey-scale mode, the background can be made lighter by
hitting the ctrl+'b' key, and darker by hitting the alt+'b' key.

\vspace{0.1in}
\noindent
To use an image in the geo display, the input to \app{pMarineViewer}
comes in two files, an image file in TIFF format, and an information
text file correlating the image to the local coordinate system. The
file names should be identical except for the suffix. For example
\var{dabob\_bay.tif} and \var{dabob\_bay.info}.  Only the \var{.tif}
file is specified in the \app{pMarineViewer} configuration block of
the MOOS file, and the application then looks for the corresponding
\var{.info} file. The info file correlates the image to the local
coordinate system and specifies the location of the local \var{(0,0)}
point. An example is given in Listing \ref{pmv_infofile}.

\vspace{0.15in}
\begin{listing}{An example .info file associated with a background image}
\label{pmv_infofile}
\footnotesize
\begin{verbatim}
 1  // Lines may be in any order, blank lines are ok
 2  // Comments begin with double slashes
 3
 4  datum_lat  = 47.731900
 5  datum_lon  = -122.85000
 6  lat_north  = 47.768868
 7  lat_south  = 47.709761
 8  lon_west   = -122.882080
 9  lon_east   = -122.794189
\end{verbatim}
\end{listing}
\normalsize

All four latitude/longitude parameters are mandatory. The two datum
lines indicate where $(0,0)$ in local coordinates is in earth
coordinates. However, the datum used by \app{pMarineViewer} is
determined by the \var{LatOrigin} and \var{LongOrigin} parameters set
globally in the MOOS configuration file. The datum lines in the above
information file are used by applications other than
\app{pMarineViewer} that are not configured from a MOOS configuration
file. The \var{lat\_north} parameters correlate the upper edge of the
image with its latitude position. Likewise for the other three
parameters and boundaries.  Two image files may be specified in the
\app{pMarineViewer} configuration block. This allows a map-like image
and a satellite-like image to be used interchangeably during use.  An
example of this is shown in Figure \ref{pmv_dabob} with two images of
Dabob Bay in Washington State. 

\vspace{0.15in}

\begin{figure}[H]
  \centering 
  \includegraphics[width=1.0\textwidth]{figures/util_pmv_dabob.png}
  \caption{{\bf Dual background geo images:} Two images loaded for
    use in the geo display mode of \vvar{pMarineViewer}. The user can
    toggle between both as desired during operation.}
\label{pmv_dabob}
\end{figure}

\vspace{0.1in}
\noindent
In the configuration block, the images can be specified by:

\prevblue
\begin{verbatim}
    tiff_file   = dabob_bay_map.tif
    tiff_file_b = dabob_bay_sat.tif
\end{verbatim}
\postverb

\noindent
In Release 22.8.x, more than two tiff files may be provided, with
successive \pvar{tiff\_file} lines. The parameter \pvar{tiff\_file\_b}
has been deprecated.  By default \app{pMarineViewer} will look for the
files \var{Default.tif} and \var{DefaultB.tif} in the local directory
unless alternatives are provided in the configuration block.

\vspace{0.1in}
\noindent
In Release 22.8.x \app{pMarineViewer} (and \app{alogview}) make use of
a shell environment variable \var{IVP\_IMAGE\_DIRS}. This is a
colon-separated path of directories on the local computer where images
files are searched for upon \app{pMarineViewer} startup. Image files
with paths relative to the mission directory are still suported. One
directory, \var{moos-ivp/ivp/data/} is hard-coded into the
\app{pMarineViewer} containing the Alpha mission image (Forest Lake
Maine), and the MIT Sailing Pavilion.


\vspace{0.1in}
\noindent
By default a copies of the background image and info files are {\em
  not} logged by \app{pLogger}. This may be changed by the setting the
following parameter: \pvar{log\_the\_image} \psvar{= true}. This is only
a request to \app{pLogger} in the form of the \mvar{PLOGGER\_CMD} posting:

\prevgreen
\begin{verbatim}
    PLOGGER_CMD = COPY_FILE_REQUEST = /home/jake/images/lake_george.tif
    PLOGGER_CMD = COPY_FILE_REQUEST = /home/jake/images/lake_george.info
\end{verbatim}
\postverb

\noindent
The result should be that the files are included in the folder created by 
\app{pLogger} with the \var{.\_tif} and \var{.\_info} suffixes. These may
then be used by post-mission analysis tools to re-convey the operation
area.

%===================================================================
\subsection{Local Grid Hash Marks}
\label{sec_pmv_hash}
%\index{pMarineViewer!Hash Marks}

Hash marks can be overlaid onto the background. By default this mode
is off, but can be toggled with the 'h' or 'H' key, or set in the
configuration file with the \pvar{hash\_viewable} parameter. The hash
marks are drawn in a grey-scale which can be made lighter by typing
the ctrl+'h' key, and darker by typing the alt+'h' key, or set in the
configuration file with the \pvar{hash\_shade} parameter. The hash mark
spacing may only be set to one of the values shown in the menu. If set
to different value, the closest legal value will be chosen.

%===================================================================
\subsection{Full-Screen Mode}
\label{sec_pmv_fullscreen}
%\index{pMarineViewer!Full-Screen Mode}

The viewer may be put into full-screen mode by toggling with the \var{'f'}
key. This will result in the data fields at the bottom of the viewer
being replace with a bit more viewing area for the geo display. As with 
all other blue items in this pull-down menu, the full-screen mode may
be set in the MOOS configuration block with \pvar{full\_screen}\psvar{=true}. The
default if false. Full-screen mode is useful when running simulations while
connected to a low-resolution projector for example.

%===================================================================
\input{help_mip_bkg_images}
%===================================================================

%===================================================================
\section{The GeoAttributes Pull-Down Menu}
%===================================================================
\label{sec_pmv_geometry}
%\index{pMarineViewer!Pull-Down Menu (GeoAttributes)}

The GeoAttributes pull-down menu allows the user to affect viewing
properties of geometric objects capable of being rendered by the
\app{pMarineViewer}. The viewer subscribes for and supports the
following geometric objects, typically generated by the helm or 
other MOOS applications:

\vspace{0.1in}
\begin{packed_itemize}
\item Polygons
\item SegLists
\item Points
\item Vectors
\item Circles
\item Markers
\item RangePulses
\item CommsPulses
\end{packed_itemize}
\vspace{0.2in}

\noindent
The viewer will also render the following other geometric objects set either
in the configuration file or interactively by the user:

\begin{packed_itemize}
\item Datum
\item OpArea
\item DropPoints
\end{packed_itemize}

The Datum is simply the point in local coordinates representing
\var{(0,0)}. The pull-down menu allows the user to toggle off or on
this rendering of the datum point as well as adjust its size and
color. The OpArea is used to render the boundaries, if they exist, of
an area of operation. DropPoints (described further in Section
\ref{sec_pmv_droppoints}) are labeled points the user may drop on the
viewing area for reference or mission planning

\vspace{0.1in}

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.94\textwidth]{figures/pmv_geoattr.png}
  \caption{{\bf The "GeoAttr" menu:} This pull-down menu lists the
    options and hot keys for affecting the rendering of geometric
    objects.}
\label{pmv_fig_geoattr}
\end{figure}

\noindent
The possible parameters settings for rendering the geometric objects
received by \app{pMarineViewer} via MOOS mail is provided in Section
\ref{sec_pmv_params_geo}.

%===================================================================
\subsection{Polygons, SegLists, Points, Circles and Vectors}
\label{sec_pmv_geo_objs}
%\index{pMarineViewer!Geometric Objects}

The five geometric objects, polygons, seglists, points, circles and
vectors, provide a core rendering capability for applications (like
the helm and its behaviors) to render visual artifacts related to the
unfolding of a mission. For example, in Figure \ref{fig_pmv_alpha}, a
seglist is used to render the vehicle waypoints, and a labeled point
is used to render the vehicles current next waypoint.

\vspace{0.1in}
\noindent
Objects are passed to \app{pMarineViewer} as strings via normal MOOS
mail. An example is given below for the seglist shown in Figure
\ref{fig_pmv_alpha}. The string is a comma-separated list of
variable=value pairs. Note the last pair is a label. Labels are used
by all five object types to distinguish uniqueness. 

\prevgreen
\begin{verbatim}
    VIEW_SEGLIST =  pts={60,-40:60,-160:150,-160:180,-100:150,-40},label=waypt_survey
\end{verbatim}
\postverb

\noindent
Uniqueness is used to either overwrite or erase previously rendered
object instances. For example the above seglist could be "moved"
five meters south by posting an identical message with the same label
and adjusted coordinates. The {\em source} of the object is also
tracked by \app{pMarineViewer}. This is given by the MOOS community
from which the message originated, and typically represents the
vehicle's name. Thus the above seglist could also be "moved" if the
posting originated from a second vehicle community, in the type of
arrangement shown in Figure \ref{fig_pmv_topology}.

%===================================================================
\subsection*{Parameters Common to Polygons, SegLists, Points, Circles and Vectors}

Other optional parameters may be associated with an object to specify
rendering preferences. They include:

\vspace{0.2in}
\small
\begin{packed_itemize}
\item \var{active}
\item \var{msg}
\item \var{vertex\_size}:
\item \var{vertex\_color}
\item \var{edge\_size}
\item \var{edge\_color}
\item \var{fill\_color}
\item \var{fill\_transparency}
\end{packed_itemize}
\normalsize
\vspace{0.2in}

\noindent
For example, the \mvar{VIEW\_SEGLIST} specification above may be augmented with the 
below string to specify edge and vertex size and color preferences:

\vspace{0.15in}
\footnotesize
\begin{verbatim}
   edge_color=pink,vertex_color=blue,vertex_size=4,edge_size=1
\end{verbatim}
\normalsize
\vspace{0.15in}

\noindent
The \var{active} parameter may be set to false to indicate that an
object, previously received with the same label, should not be drawn
by \var{pMarineViewer}.  The \var{msg} parameter may be used to
override the string rendered as the object's label. Since labels are
used to uniquely identify an object, the \var{msg} parameter may be
used to, for example, draw five points all with same rendered
text. The other six parameters are self-explanatory and not
necessarily relevant to all objects. For example, \app{pMarineViewer}
will ignore an \var{edge\_size} specification when drawing a point,
and a \var{fill\_color} will only be relevant for a polygon and a
circle.

%===================================================================
\subsection*{Serializing Geometric Objects for pMarineViewer Consumption}

Geometric objects are only {\em consumed} by \app{pMarineViewer}, but
it's worth discussing the issue of {\em generating} and serializing an
object into a string. It is possible to simply post a string in the
right format, as with:

\vspace{0.15in}
\footnotesize
\begin{verbatim}
  string str = "x=5,y=25,label=home,vertex_size=3";  // Not recommended
  m_Comms.Notify("VIEW_POINT", str);
\end{verbatim}
\normalsize
\vspace{0.15in}

\noindent
It is highly recommended that this be left to the serialization
function native to the C++ class.

\vspace{0.15in}
\footnotesize
\begin{verbatim}
  #include "XYPoint.h"

  XYPoint my_point(5, 25);                           // Recommended
  my_point.set_label("home");
  my_point.set_vertex_size(3);
  string str = my_point.get_spec();
  m_Comms.Notify("VIEW_POINT", str);
\end{verbatim}
\normalsize
\vspace{0.15in}

\noindent
The latter code is less prone to user error, and is more likely to
work in future code releases if the underlying formats need to be
altered. (This is the idea behind Google Protocol Buffers, but here the 
geometric classes are implemented with various geometry function relations
defined in addition to the serialization and de-serialization.) The full
set of interface possibilities for creating and manipulating geometry
objects is beyond the scope of the discussion here however. 

%===================================================================
\subsection{Markers}
\label{sec_pmv_markers}
%\index{pMarineViewer!Markers}

A set of marker object types are defined for rendering characteristics
of an operation area such as buoys, fixed sensors, hazards, or other
things meaningful to a user. The six types of markers are shown in
Figure \ref{pmv_markers}. They are configured in the
\app{pMarineViewer} configuration block of the MOOS file with the
following format:

\prevblue
\begin{verbatim}
  marker  = type=efield,x=100,y=20,label=alpha,color=red,width=4.5
  marker  = type=square,lat=42.358,lon=-71.0874,color=blue,width=8
\end{verbatim}
\postverb

\noindent
Each entry is a string of comma-separated pairs. The order is not
significant. The only mandatory fields are for the marker type and
position.  The position can be given in local x-y coordinates or in
earth coordinates.  If both are given for some reason, the earth
coordinates will take precedent. The \var{width} parameter is given in
meters drawn to scale on the geo display. Shapes are roughly 10x10
meters by default. The GUI provides a hook to scale all markers
globally with the \var{ALT-m} and \var{CTRL-m} hot keys and in the
GeoAttributes pull-down menu.

\vspace{0.2in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.95\textwidth]{figures/markers.png}
  \caption{{\bf Markers:} Types of markers known to the
    \vvar{pMarineViewer}.}
\label{pmv_markers} 
\end{figure}
\vspace{0.2in}

The color parameter is optional and markers have the default colors
shown in Figure \ref{pmv_markers}. Any of the colors described in the
Colors Appendix are fair game. The black part of the Gateway and
Efield markers is immutable. The label field is optional and is by
default the empty string. Note that if two markers of the same type
have the same non-empty label, only the first marker will be
acknowledged and rendered. Two markers of different types can have the
same label.

\vspace{0.1in}
\noindent
In addition to declaring markers in the configuration file, markers
can be received dynamically by \app{pMarineViewer} through the
\mvar{VIEW\_MARKER} MOOS variable, and thus can originate from any
other process connected to the \app{MOOSDB}. The syntax is exactly the
same, thus the above two markers could be dynamically received as:

\prevgreen
\begin{verbatim}
    VIEW_MARKER  = "type=efield,x=100,y=20,scale=4.3,label=alpha,color=red,width=4.5"
    VIEW_MARKER  = "type=square,lat=42.358,lon=-71.0874,scale=2,color=blue,width=8"
\end{verbatim}
\postverb


\noindent
The effect of a "moving" marker, or a marker that changes color, can
be achieved by repeatedly publishing to the \mvar{VIEW\_MARKER}
variable with only the position or color changing while leaving the
label and type the same. To dynamically alter the text rendered
with a marker, the \var{msg=value} field may be used instead. When the message
is non-empty, it will be rendered instead of the label text.

%===================================================================
\subsection{Comms Pulses}
\label{sec_pmv_pulses}
%\index{pMarineViewer!Range Pulses}
%\index{Comms Pulses!pMarineViewer}

Comms pulse objects were designed to convey a passing of information
from one node to another. At this writing, they are only used by the
\app{uFldNodeComms} application, but from the perspective of
\app{pMarineViewer} it does not matter the origin. The MOOS variable
is \mvar{VIEW\_COMMS\_PULSE}. They look something like that shown in
Figure \ref{pmv_fig_commspulse_rpt}. There are two pulses shown in
this figure. In this case they were posted by \app{uFldNodeComms} to
indicate that the two vehicles are receiving each other's node
reports.

\vspace{0.05in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.7\textwidth]{figures/comms_pulse.png}
  \caption{{\bf Comms Pulses:} A comms pulse directionally renders
    communication between vehicles. Here each vehicle is communicating
    with the other, and two different colored pulses are rendered.}
\label{pmv_fig_commspulse_rpt}
\end{figure}

The term "pulse" is used because the object has a duration (by
default three seconds), after which it will no longer be rendered by
\app{pMarineViewer}. The pulse will fade (become more transparent)
linearly with time as it approaches its expiration. If a subsequent
comms pulse is received with an identical label before the first pulse
times out, the second pulse will replace the first, in the style of
other geometric objects discussed previously. Although serializing
and de-serializing comms pulse messages is outside the scope of this
discussion, it it worth examining an example comms pulse message:

\prevgreen
\begin{verbatim}
  VIEW_COMMS_PULSE = sx=91,sy=29,tx=6.7,ty=1.4,beam_width=7,duration=10,fill=0.35,
                     label=GILDA2HENRY_MSG,fill_color=white,time=1350201497.27
\end{verbatim}
\postverb

\noindent
As with the object types discussed previously, the construction of the above
type messages should be handled by the \var{XYCommsPulse} class along the line
of something like:

\vspace{0.15in}
\footnotesize
\begin{verbatim}
  #include "XYCommsPulse.h"  

  XYCommsPulse my_pulse(91, 29, 6.7, 1.4);      
  my_pulse.set_label("GILDA2HENRY_MSG");
  my_pulse.set_duration(10);
  my_pules.set_beam_width(7);
  my_pules.set_fill(0.35);
  my_pulse.set_color("fill", "white");
  string str = my_pulse.get_spec();
  m_Comms.Notify("VIEW_COMMS_PULSE", str);
\end{verbatim}
\normalsize
\vspace{0.1in}

The white comms pulse shown in Figure \ref{pmv_fig_commspulse_msg}
indicates that a message has been sent from one vehicle to the
other. The fat end of the pulse indicates the receiving vehicle. The
color scheme is not a convention of \app{pMarineViewer}, but rather a
convention of the \app{uFldNodeComms} application which generated the
object in this case. A white pulse is typically rendered long enough
to allow the user to visually register the information.  It also
typically does not move with the vehicle, to convey to the user the
vehicle positions at the time of the communication.

\vspace{0.05in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.7\textwidth]{figures/comms_pulse_msg.png}
  \caption{{\bf Comms Pulses for Messaging:} In this figure the white
    comms pulse indicates that a message is being sent from one
    vehicle to another, via \vvar{uFldNodeComms}.}
\label{pmv_fig_commspulse_msg}
\end{figure}

\vspace{0.05in} The rendering of comms pulses may be toggled on or off
in \app{pMarineViewer} via a selection in the GeoAttr pull-down menu,
or via the \var{'@'} hot key.  It is not possible in
\app{pMarineViewer} to show just the white comms pulses, and hide the
colored node report comms pulses, or vice versa.  It is possible
however in the \app{uFldNodeComms} configuration to shut off the node
report pulses with \pvar{view\_node\_rpt\_pulses}\psvar{=false}.

%===================================================================
\subsection{Range Pulses}
%\index{pMarineViewer!Range Pulses}
%\index{Range Pulses!pMarineViewer}

Range pulse objects were designed to convey a passing of information or sensor
energy from one node to any other node in the vicinity, up to a certain range.
At this writing they are only used by the \app{uFldContactRangeSensor} and 
\app{uFldBeaconRangeSensor} applications, but from the perspective of 
\app{pMarineViewer} it does not matter the origin. The MOOS variable
is \mvar{VIEW\_RANGE\_PULSE}. They look something like that shown in
Figure \ref{pmv_fig_range_pulses}. Here the pulse is shown over three 
successive times. 


\vspace{0.05in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.84\textwidth]{figures/pmv_range_pulses.png}
  \caption{{\bf Comms Pulses:} A comms pulse directionally renders
    communication between vehicles. Here each vehicle is communicating
    with the other, and two different colored pulses are rendered.}
\label{pmv_fig_range_pulses}
\end{figure}

The term "pulse" is used because the object has a duration (by
default 15 seconds), after which it will no longer be rendered by
\app{pMarineViewer}. The pulse will grow in size and fade (become more
transparent) linearly with time as it approaches its expiration. If a
subsequent range pulse is received with an identical label before the
first pulse times out, the second pulse will replace the first, in the
style of other geometric objects discussed previously. Although
serializing and de-serializing range pulse messages is outside the
scope of this discussion, it it worth examining an example range pulse
message:

\prevgreen
\begin{verbatim}
  VIEW_RANGE_PULSE = x=99.2,y=68.9,radius=50,duration=6,fill=0.9,label=archie_ping, 
                     edge_color=white,fill_color=white,time=2700438154.35,edge_size=1
\end{verbatim}
\postverb


\noindent
As with the object types discussed previously, the construction of the above
type messages should be handled by the \var{XYRangePulse} class along the line
of something like:

\footnotesize
\begin{verbatim}
  #include "XYRangePulse.h"  

  XYRangePulse my_pulse(99.2, 68.9);      
  my_pulse.set_label("archie_ping");
  my_pulse.set_duration(6);
  my_pules.set_edge_size(1);
  my_pules.set_radius(50);
  my_pules.set_fill(0.9);
  my_pulse.set_color("edge", "white");
  my_pulse.set_color("fill", "white");
  string str = my_pulse.get_spec();
  m_Comms.Notify("VIEW_RANGE_PULSE", str);
\end{verbatim}
\normalsize
\vspace{0.1in}


%===================================================================
\subsection{Drop Points}
\label{sec_pmv_droppoints}
%\index{pMarineViewer!Drop Points}

A user may be interested in determining the coordinates of a point in
the geo portion of the \app{pMarineViewer} window. The mouse may be
moved over the window and when holding the \var{SHIFT} key, the point
under the mouse will indicate the coordinates in the local grid. When
holding the \var{CTRL} key, the point under the coordinates are shown
in lat/lon coordinates. The coordinates are updated as the mouse moves
and disappear thereafter or when the \var{SHIFT} or \var{CTRL} keys
are release. Drop points may be left on the screen by hitting the left
mouse button at any time. The point with coordinates will remain
rendered until cleared or toggled off. Each click leaves a new point,
as shown in Figure \ref{fig_drop_points}.

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.75\textwidth]{figures/pmv_drop_points.png}
  \caption{{\bf Drop points:} A user may leave drop points with
    coordinates on the geo portion of the \app{pMarineViewer}
    window. The points may be rendered in local coordinates or in
    lat/lon coordinates. The points are added by clicking the left
    mouse button while holding the \vvar{SHIFT} key or \vvar{CTRL}
    key.  The rendering of points may be toggled on/off, cleared in
    their entirety, or reduced by popping the last dropped point.}
\label{fig_drop_points}
\end{figure}

\noindent
Parameters regarding drop points are accessible from the \var{GeoAttr}
pull-down menu. The rendering of drop points may be toggled on/off by
hitting the 'r' key. Drop points may also be shut off in the mission
configuration file with
\pvar{drop\_point\_viewable\_all}\psvar{=false}.  The set of drop
points may be cleared in its entirety via the pull-down menu. Or the
most recently dropped point may be removed by typing the \var{CTRL-r}
key. The pull-down menu may also be used to change the rendering of
coordinates from \var{"as-dropped"} where some points are in local
coordinates and others in lat/lon coordinates, to \var{"local-grid"}
where all coordinates are rendered in the local grid, or
\var{"lat-lon"} where all coordinates are rendered in the lat/lon
format. By default the mode is \var{"as-dropped"}. The startup default
mode may be changed with \pvar{drop\_point\_coords}\psvar{=local-grid} for
example in the mission file.


%===================================================================
\newpage
\section{The Vehicles Pull-Down Menu}
%===================================================================
\label{sec_pmv_vpulldown}
%\index{pMarineViewer!Pull-Down Menu (Vehicles)}

The {\em Vehicles} pull-down menu deals with rendering properties of
vehicles, vehicle labels, and vehicle trails. The options are shown in
Figure \ref{fig_pmv_vehicles_menu}. The very first option is to turn on
or off the rendering of all vehicles. The can be done at run time via
the menu selection, or toggled with the \var{Ctrl-'a'} hot key. Like 
all blue options in this menu, the text in the menu item may be placed
verbatim in the mission configuration file to reflect the user's startup
preferences.

\begin{figure}[H]
  \centering
  \includegraphics[width=1.0\textwidth]{figures/pmv_vehicles_menu.png}
  \caption{{\bf The Vehicles menu:} This pull-down menu lists the
    options, with hot-keys, for affecting rendering vehicles and
    vehicle track history.}
\label{fig_pmv_vehicles_menu}
\end{figure}

%===================================================================
\subsection{The Vehicle Name Mode}
\label{sec_pmv_vehinames}
%\index{pMarineViewer!Vehicle Name Mode}

Each vehicle rendered in the viewer has an optional label rendered with it. 
This label may be rendered in one of five modes:

\begin{packed_itemize} 
\item {\em names}: Just the vehicle name is rendered.
\item {\em names+mode}: The vehicle name and the full helm mode is rendered.
\item {\em names+shortmode}: The vehicle name and the short helm mode is rendered.
\item {\em names+depth}: The vehicle name and its current depth are rendered.
\item {\em off}: No label is rendered.
\end{packed_itemize} 

\noindent
The default is {\em names+shortmode}. The {\em names}, {\em off} and
{\em depth} modes are self explanatory. The {\em names+mode} and {\em
  names+shortmode} involve information typically provided in vehicle
node reports about the state of the IvP helm. The helm uses
hierarchical mode declarations as a way of configuring behaviors for
missions. The helm mode for example be described with
string looking something like \var{"MODE@ACTIVE:LOITERING"}. In \app{pMarineViewer}
the text next to the vehicle would be either this whole string if configured
with the {\em names+mode} setting, or just \var{"LOITERING"} if configured
with the {\em names+shortmode} setting. 

\vspace{0.1in}
\noindent
The color of the rendered text may be changed from the default of white to 
any color in the Color Appendix with the \pvar{vehicles\_name\_color}
configuration parameter.

%===================================================================
\subsection{Dealing with Stale Vehicles}
\label{sec_pmv_staleness}
%\index{pMarineViewer!Stale Vehicles}
%\index{Stale Vehicles!pMarineViewer}

A stale vehicle is one who has not been heard from for a some time,
perhaps because the vehicle is disabled, out of range, or recovered
from the field. These vehicles can be a distraction. Their history may
be outright cleared as described in Section \ref{sec_pmv_vehitrails},
but this requires action by the user or a posting to the \app{MOOSDB}. 

\vspace{0.1in}
\noindent
Stale vehicles are also automatically dealt with by
\app{pMarineViewer} in another way. After some number of seconds (30
by default), the vehicle label indicates the staleness. The label may
look something like \var{"henry (Stale Report: 231)"} where the number
indicates the number of seconds since the last node report received
for this vehicle. After another period of time (30 by default), the
vehicle may no longer rendered and removed from the appcasting pane.

\vspace{0.1in}
\noindent
A few features of this policy are configurable through the mission
configuration file. The duration of time after which a vehicle is
reported as stale may be changed from its default of $30$ seconds with
the \pvar{stale\_report\_thresh} parameter. The duration of time after
which a vehicle is removed may be changed from its default of $30$
seconds with the \pvar{stale\_remove\_thresh} parameter.

\vspace{0.1in}
\noindent
Stale vehicles are handled a bit differently when running in
simulation and when running vehicles in the field. The difference
between the two is determined by the MOOS time warp. Although it's
possible to simulate with a time warp of one, here a time warp of one
is interpreted as running physical vehicles. Simulated vehicles will
be automatically removed from the viewer after
\pvar{stale\_report\_thresh} + \pvar{stale\_remove\_thresh} seconds.
When running actual vehicles, stale vehicles must be explicitly 
removed using the \var{alt+'k'} key to remove all stale vehicles, or 
\var{ctrl+'k'} key to remove the currently selected vehicle in the 
appcast pane.


%===================================================================
\subsection{Supported Vehicle Shapes}
\label{sec_pmv_vehishapes}
%\index{pMarineViewer!Vehicle Shapes}

The shape rendered for a particular vehicle depends on the {\em type}
of vehicle indicated in the node report received in
\app{pMarineViewer}. There are several types that are currently
handled:

\vspace{0.1in}

\begin{packed_itemize}
\item \pvar{kayak}
\item \pvar{uuv}
\item \pvar{auv} (same as \pvar{uuv})
\item \pvar{glider}
\item \pvar{mokai}
\item \pvar{ship}
\item \pvar{longship}
\item \pvar{heron}
\item \pvar{buoy}
\item \pvar{swimmer}
\item \pvar{cray, crayx, bcray, bcrayx}
\end{packed_itemize}

\vspace{0.1in}
\noindent
Note: the \pvar{swimmer}, \pvar{buoy}, \pvar{cray},
\pvar{bcray}, \pvar{crayx}, and \pvar{bcrayx}, types were introduced
     {\em after} release 22.8.

\vspace{0.1in}
\noindent
Some shapes are shown in Figure \ref{pmv_shapes}.

\vspace{0.1in}

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.9\textwidth]{figures/vshapes.png}
  \caption{{\bf Vehicles:} Types of vehicle shapes supported by
    \aapp{pMarineViewer}. The C-Ray shapes were added {\em after} release 22.8.}
\label{pmv_shapes}
\end{figure}

\vspace{0.12in}
\noindent
The default shape for an unknown vehicle type is currently set to be
the shape "ship". 

%===================================================================
\subsection{Vehicle Colors}
\label{sec_pmv_vehicolors}
%\index{pMarineViewer!Vehicle Colors}

Vehicles are rendered in one of two colors, the {\em active vehicle color} and 
the {\em inactive vehicle color}. The active vehicle is the one who's data is being
rendered in the data fields at the bottom of the \app{pMarineViewer} window, and
who's name is in the \var{VName:} field. The active vehicle may be changed by 
selecting \var{"Cycle Vehicle Focus"} from the Vehicles pull-down menu, or toggling
through with the \var{'v'} key. The default color for the active vehicle is red, 
and the default for the inactive vehicle is yellow. These can be changed via the
pull-down menu, or with the following parameters in the configuration file:

\prevblue
\begin{verbatim}
  vehicles_active_color   = &lt;color&gt;    // default is red
  vehicles_inactive_color = &lt;color&gt;    // default is yellow
\end{verbatim}
\postverb

\noindent
The parameters and colors are case insensitive. All colors of the
form described in the Color Appendix are acceptable.

%===================================================================
\subsection{Centering the Image According to Vehicle Positions}
\label{sec_pmv_image_pos}
%\index{pMarineViewer!Image Shifting To Vehicles}

The \pvar{center\_view} menu items alters the center of the view screen
to be panned to either the position of the active vehicle, or the
position representing the average of all vehicle positions. Once the
user has selected this, this mode remains {\em sticky}, that is the
viewer will automatically pan as new vehicle information arrives such
that the view center remains with the active vehicle or the vehicle
average position. As soon as the user pans manually (with the arrow
keys), the viewer breaks from trying to update the view position in
relation to received vehicle position information. The rendering of
the vehicles can made larger with the '+' key, and smaller with the
'-' key, as part of the \var{VehicleSize} pull-down menu as shown.
The size change is applied to all vehicles equally as a scalar
multiplier. Currently there is no capability to set the vehicle size
individually, or to set the size automatically to scale.

%===================================================================
\subsection{Vehicle Trails}
\label{sec_pmv_vehitrails}
%\index{pMarineViewer!Vehicle Trails}

Vehicle trail (track history) rendering can be toggled off and on with
the \var{'t'} key. The default is on. The startup default setting may
be changed to off in the mission configuration file with
\pvar{trails\_viewable}\psvar{=false}.

%===================================================================
\subsection*{Trail Color and Point Size}
The trail color by default is white. A few other colors are available
in the Vehicles pull-down menu. A color may also be chosen in the
mission configuration file with \pvar{trail\_color}\psvar{=&lt;color&gt;}
using any color listed in the Color Appendix. The trail point
size may range from $[1,10]$. The default setting is $2$. The size may
be changed at runtime by the Vehicles/Trails pull-down menu, or with
the \var{'\{'} and \var{'\}'} hot keys. The startup trail size may also
be set in the mission configuration file with
\pvar{trails\_point\_size}\psvar{=&lt;int&gt;} parameter.

%===================================================================
\subsection*{Trail Length and Connectivity}

Trails have a fixed-length history by default of $100$ points. This may
be changed via the Vehicles/Trails pull-down menu, or with the hot keys
\var{'('} and \var{')'}. The startup default length may also be set in the
mission configuration file with \pvar{trails\_length}\psvar{=&lt;int&gt;} with values
in range of $[0, 10000]$. 

\vspace{0.1in}
\noindent
Individual trail points can be rendered with a line connecting each
point, or by just showing the points. When the node report stream is
flowing quickly, typically the user doesn't need or want to connect
the points. When the viewer is accepting input from an AUV with
perhaps a minute or longer delay in between reports, the connecting of
points is helpful. This setting can be toggled with the \var{'y'} or
key, with the default being off. The startup default may be set to on
with the mission file parameter \pvar{trails\_connect\_viewable}\psvar{=true}.

%===================================================================
\subsection*{Resetting or Clearing the Trails}

A vehicle's history sometimes needs to be cleared, for example when a
vehicle has not been heard from in a long time, or has been
recovered. Its trails and other geometric objects posted to the viewer
can become a distraction. This may be done in a couple ways. First via
the Action pull-down menu, the last menu item allows the user to clear
the history of all vehicles or a selected vehicle. The \var{Ctrl-9}
hot key can be used to clear all vehicle histories.  A select vehicle
history may also be cleared by posting to the MOOS variable
\mvar{TRAIL\_RESET} with the name of the vehicle.

%\index[vars]{\mvar{TRAIL\_RESET}}


%===================================================================
\section{The InfoCasting Pull-Down Menu}
%===================================================================
\label{sec_pmv_infocasting}
%\index{pMarineViewer!Pull-Down Menu (InfoCasting)}
%\index{InfoCasting!pMarineViewer}

Infocasting refers to two optional modes for operating
\app{pMarineViewer}.  The first is {\em appcasting}, introduced in
2012 in Release 12.11. The second mode is {\em realmcasting},
developed in December 2020 for the first release following 19.8.
With these tools, \app{pMarineViewer} has been augmented to serve as
an appcast and realmcast viewer. Other apps may be used for appcast
viewing, such as \app{uMAC}, and \app{uMACView}. Realmcast viewing is
also supported in \app{uMACView}, but not \app{uMAC}.

Appcasting requires that each app be "appcast enabled", and virtually
all MOOS apps distributed with MOOS-IvP are appcast enabled.  The
motivation for appcasting and how to build appcast enabled MOOS
applications are discussed elsewhere in the appcasting documentation.
Realmcasting, on the other hand, requires nothing of the user other
than running an app called \app{pRealm} in each MOOS community.  In
the simplest case, \app{pRealm} can be run with no configuration
parameters, allowing it to be very easily added to legacy missions. 

\vspace{0.1in}
\noindent
Quick points to note:

\begin{packed_itemize}
\item The term {\em infocasting} refers generally to include either appcasting or
  realmcasting.
\item By default, when \app{pMarineViewer} launches, Infocasting panes on the
  left are rendering appcast content, typically with a white-on-indigo color
  scheme.
\item The content of the infocasting panes can be switched between appcasting
  and realmcasting by hitting the \var{'a'} key.
\item The infocasting panes can be toggled/hidden entirely by hitting the
  \var{ctrl-'a'} key.
\end{packed_itemize}



%===================================================================
\subsection{Turning On and Off InfoCast Viewing}
\label{sec_pmv_appcast_onoff}

The InfoCasting pull-down menu, shown in Figure
\ref{fig_pmv_infocast_menu} allows adjustments to be made to the
infocast rendering and content. The very first set of menu options
allows the user to control whether the infocasting panes are shown or
not (toggling with \var{ctrl-'a'}, followed by options for controlling
the content, appcasting or realmcasting. As with all
\app{pMarineViewer} pull-down menu items, if they are rendered in
blue, then the same text can be placed in the \app{pMarineViewer}
configuration block to be applied automatically at startup.

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.97\textwidth]{figures/pmv_infocast_menu.png}
  \caption{{\bf The InfoCast menu:} This pull-down menu lists the
  options, with hot-keys, for affecting rendering aspects of the
  appcast panels, and policy for soliciting appcasts from known
  vehicles and applications.}
\label{fig_pmv_infocast_menu}
\end{figure}

%===================================================================
\subsection{Adjusting the InfoCast Viewing Panes Height and Width}
\label{sec_pmv_appcast_extents}

The next set of menu items allow the relative size of the infocasting
panes to be adjusted. The width of the three panes may be increased or
decreased with the shift-left and shift-right arrow keys, and the height of the
lower infocasting window relative to the two upper windows may be
adjusted with the shift-up and shift-down arrow keys.

\vspace{0.1in}
\noindent
The infocast pane extents may also be set to the user's liking in the
mission configuration file with the parameters \pvar{infocast\_width}
and \pvar{infocast\_height}. The allowable range of values for each may
be seen by pulling down the "InfoCast Pane Width" and "InfoCast Pane
Height" sub-menus of the InfoCasting pull-down menu.

%===================================================================
\subsection{Adjusting the InfoCast Refresh Mode}
\label{sec_pmv_appcast_refresh}

The infocast {\em refresh mode} refers to the policy of sending
appcast and realmcast requests to known vehicles and
applications. This is discussed more fully in appcast documentation,
but summarized here. Appcasting and Realmcasting are implemented to be
lazy with respect to generating appcast and infocast reports - they
will not generate them unless asked. And even when asked, the request
comes with an expiration after which, if no new request has been
received, the application returns to the lazy mode of producing no
appcasts. So, for \app{pMarineViewer} to function as an appcast and
realmcast viewer, under the hood it must be also generating appcast
requests (\mvar{APPCAST\_REQ} postings) and realmcast requests
(\mvar{REALMCAST\_REQ} postings) to the \app{MOOSDB}. The refresh mode
refers to this under-the-hood policy.

\vspace{0.1in}
\noindent
In the {\em paused} refresh mode, \app{pMarineViewer} is not generating
any infocast requests at all. This is not the default and typically not
very helpful, but it may be useful when the viewer is situated in the 
field with only a low-bandwidth connection to remote vehicles.
The refresh mode may be set to {\em paused} via the pull-down menu
selection, with the \var{CTRL+Spacebar} hot key, or set in the mission
configuration file with \pvar{refresh\_mode}\psvar{=paused}.

\vspace{0.1in}
\noindent
In the {\em events} refresh mode, the default mode,
\app{pMarineViewer} is generating appcast requests only to the
selected vehicle and the selected MOOS application. Even this is only
partly true.  In fact it is generating another kind of appcast request
to all vehicles and apps, but this kind of request comes with the
caveat that an app should only generate an appcast report if a new run
warning has been detected. Otherwise these apps remain lazy. In this
mode you should expect to see regular appcasts received for the
selected app, and updates for the other apps only if something worthy
of a run warning has occurred. You can confirm this for yourself by
looking at the counter reflecting the number of appcasts received for
any application. This counter is under the \var{AC} column in the
upper panes.  The refresh mode may be set to {\em events} via the
pull-down menu selection, with the \var{CTRL+'e'} hot key, or set in
the mission configuration file with \pvar{refresh\_mode}\psvar{=events}. The
latter would be redundant however since this is the default mode.

\vspace{0.1in}
\noindent
In the {\em streaming} refresh mode, \app{pMarineViewer} is generating
appcast requests to all vehicles and all apps to generate appcasts all
the time. This mode is a bandwidth hog, but it may be useful at times,
especially to debug why a particular application is silent. If it is
not generating and appcast in this mode, then something may indeed be
wrong.  The refresh mode may be set to {\em streaming} via the
pull-down menu selection, with the \var{CTRL+'s'} hot key, or set in
the mission configuration file with \pvar{refresh\_mode}\psvar{=streaming}.
The {\em streaming} mode is not relevant to realmcast generation. Realmcast
generation may be only in either the paused for events mode.


%===================================================================
\subsection{Adjusting the InfoCast Fonts}
\label{sec_pmv_appcast_fonts}

The font size of the text in the infocasting panes may be adjusted. There
are three panes:

\begin{packed_itemize}[2]
\item {\em Nodes Pane}: The upper left pane shows the list of nodes
  (typically synonymous with vehicles), presently known to the viewer.
\item {\em Procs Pane}: The upper right pane show the list of apps,
  for the chosen node, presently known to the viewer. 
\item {\em InfoCast Pane}: The bottom pane shows the contents of the 
  presently selected appcast or realmcast report.
\end{packed_itemize}

For each pane the possible font settings are \var{xlarge}, \var{large},
\var{medium}, \var{small}, and \var{xsmall}. The default for the upper
panes is \var{large}, and the default for the infocast pane is
\var{medium}. Font sizes may be changed via the pull-down menu or set
to the user's liking in the mission configuration file with
\pvar{nodes\_font\_size}, \pvar{procs\_font\_size}, and
\pvar{infocast\_font\_size} parameters.

%===================================================================
\subsection{AppCasting Versus RealmCasting}
\label{sec_pmv_ac_vs_rc}

Although both types of infocast content, appcast and realmcast reports,
can be viewed from other client apps like \app{uMACView} and \app{uMAC},
they were originally and primarily designed to be accessed from within
\app{pMarineViewer}. It is worth discussing here their similarities and
differences. In distributed multi-vehicle simulations and in-field
operations, the content available through infocasting is priceless for
development and safe field operation. Much care was taken to allow the user
access to an enormous variety of information across all vehicles, while
ensuring that the information flow is restricted to be only what the user is
presently monitoring through the current infocast pane. In both modes,
if bandwidth is an issue, information flow can be halted immediately by
hitting \var{ctrl-spacebar}.

\vspace{0.1in}
\noindent
With appcasting, the basic idea is shown in Figure
\ref{fig_pmv_info_ac}.  The \app{pMarineViewer} user selects a node
(either the shoreside or one of the simulated or deployed vehicles),
and a process/app running on that node.  This information is contained
in an \mvar{APPCAST\_REQ} message published by \app{pMarineViewer}
which is shared out to the particular node and app. If this app is
appcast enabled (most are), it will respond with an \mvar{APPCAST}
message. This single string message will be expanded to a multi-line
report displayed in the infocast pane when received by
\app{pMarineViewer}.

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.8\textwidth]{figures/info_appcasting.png}
  \caption{{\bf Appcasting Information Flow:} An appcast viewing client,
    like \app{pMarineViewer}, \app{uMACView}, or \app{uMAC} will generate
    an appcast request to a targeted remote application. If the remote
    application is appcast enabled, it will respond with an appcast report
    for viewing in the appcast viewing client.}
\label{fig_pmv_info_ac}
\end{figure}

\vspace{0.1in}
\noindent
Realmcasting works a bit differently. It does not involve direct
communication with remote apps as with appcasting. Instead,
realmcasting is supported by a single instance of another app,
\app{pRealm}. This app is run on each node, including the shoreside.
This app is more fully described in \cite{url_prealm}. It utilizes a
special variable published by the local MOOSDB, \mvar{DB\_RWSUMMARY}
which informs \app{pRealm} what variables are subscribed for and
published for each app connected to the MOOSDB. With this information,
\app{pRealm} also subscribes for all variables and is able to form a
realmcast report. Typically the form of this report is a summary, for
a specified app, of all variables involved in subscriptions or
publications. As with appcasting, the report generation is on-demand,
requiring a realmcast request followed by a realmcast reply, as shown
in Figure \ref{fig_pmv_info_rc}.

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.8\textwidth]{figures/info_realmcasting.png}
  \caption{{\bf Realmcasting Information Flow:} An realmcast viewing
    client, like \app{pMarineViewer} or \app{uMACView} will generate
    an realmcast request to a targeted node running an instance of
    \app{pRealm}. The realmcast request will specify a particular
    app and the realmcast response will report the status of variables
    involved in publications or subscriptions for that app.}
\label{fig_pmv_info_rc}
\end{figure}

\vspace{0.1in}
\noindent
The realmcast report is split into two parts. The top part shows all
variables subscribed for by the given application, and the bottom part
similarly shows all variables published by the application. In this
way, a realmcast report is another way to glean the pub/sub interface
for any application. A typical report is shown in Figure
\ref{fig_pmv_rc_example} below.

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.98\textwidth]{figures/pmv_relcast_example.png}
  \caption{{\bf Example RealmCast Report:} A realmcast message is expanded
    into a multi-line report, consisting of a report on subscribed variables
    and published variables for a given application. In this case the report
    is for the \app{pContactMgrV20} application on vehicle \var{gilda}.}
\label{fig_pmv_rc_example}
\end{figure}

%===================================================================
\subsection{Adjusting the RealmCast Content}
\label{sec_pmv_relcast_content}

The content of the report can be adjusted by the client, e.g.,
\app{pMarineViewer} user, to help visualize the important information. There
are seven options:

\begin{packed_itemize}
\item Source: The Source column of the report may be suppressed.
\item Community: The Community column of the report may be suppressed.
\item UTC Time: The time format may be shown in absolute UTC time, or relative
  to the start of the local MOOSDB.
\item Subscriptions: The subscriptions portion of the report may be suppressed.
\item Mask: In the subscriptions portion, virgin variables may be suppressed.
\item Wrap: Long string content may be wrapped over several lines, e.g., as in
  Figure \ref{fig_pmv_rc_example}.
\item Truncate: Long string content may be truncated.
\end{packed_itemize}

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.94\textwidth]{figures/pmv_relcast_buttons_both.png}
  \caption{{\bf Adjusting RealmCast Buttons:} Realmcast content may be adjusted
    through the seven buttons on the lower left corner of \app{pMarineViewer}.
    These buttons are only present when realmcasting is enabled.}
\label{fig_pmv_rc_buttons}
\end{figure}

\vspace{0.1in}
\noindent
The start-up value of these settings may also be set to the user's
liking in the \app{pMarineViewer} configuration block:

\prevblue
\begin{verbatim}
  realmcast_show_source        = true/false   // Default is true
  realmcast_show_community     = true/false   // Default is true
  realmcast_show_subscriptions = true/false   // Default is true
  realmcast_show_masked        = true/false   // Default is true
  realmcast_wrap_content       = true/false   // Default is false
  realmcast_trunc_content      = true/false   // Default is false
  realmcast_time_format_utc    = true/false   // Default is false
\end{verbatim}
\postverb


%===================================================================
\subsection{Additional RealmCast Capability: Watch Clusters}
\label{sec_pmv_watch_clusters}

The normal realmcast reports allow the user to peer into any vehicle
and any app to examine the state of variables involved in the
subscriptions and publications for that app. However, in some
multi-vehicle missions, it may be very useful to quickly see the value
of certain variables for all vehicles {\em simultaneously}. For this
purpose, \app{pMarineViewer} may be optionally configured with one or
more {\em watch clusters}.

\vspace{0.1in}
\noindent
A watch cluster is a group of variables, with an associated grouping
key, to allow simultaneous monitoring of these variable over all
vehicles in the realmcast pane. This configuration is done on the
client (\app{pMarineViewer}) side, and will result in a modified
posting of \app{REALMCAST\_REQ}. The \app{pRealm} applications knows
how to receive these requests, and will generate a posting to the
\app{WATCHCAST} variable, one for each cluster variable, containing
the most recent information for that variable.

\vspace{0.1in}
\noindent
We will explain by way of an example. Suppose we have a mission with
six vehicles, \var{abe}, \var{ben}, \var{cal}, \var{deb}, \var{eve},
and \var{fin}. And we would like to monitor the local MOOS variables
\mvar{DEPLOY}, \mvar{RETURN}, \mvar{STATION\_KEEP}, and \mvar{COVER}.
These four variables constitute our watch cluster, and we pick a keyname,
say \var{mission\_top}. The watch cluster would be configured with the
following line in the \app{pMarineViewer} configuration block:

\prevblue
\begin{verbatim}
   watch_cluster = key=mission_top, vars=DEPLOY:RETURN:STATION_KEEP:COVER
\end{verbatim}
\postverb

\vspace{0.1in}
\noindent
The watch cluster key, \var{mission\_top}, should then appear in the Nodes
pane when launched, as shown in Figure \ref{fig_pmv_rc_watch_all}

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.94\textwidth]{figures/pmv_cluster_all.png}
  \caption{{\bf RealmCast Watch Cluster Example:} A watch cluster has been
    configured with four variables, with the cluster name of \vvar{mission\_top}.
    When the user selects \vvar{mission\_top} in the nodes pane, the values of
    the four watched variables, for the six vehicles in the mission, are shown
    in a table in the bottom realmcast pane. This table is only refreshed when
    one or more of the variables has been changed on one or more of the vehicles.}
\label{fig_pmv_rc_watch_all}
\end{figure}

\vspace{0.1in}
\noindent
The table in Figure \ref{fig_pmv_rc_watch_all} is quite concise,
providing a substantial amount of information. However, it comes at
the expense of leaving out certain information for each cell, such as
the source, time, and community associated with the posting in that
cell.  For each variable in the cluster, the user has the option of
finding out more.  Notice the four cluster variables are listed in the
upper right pane. By clicking on any one of them, the realmcast pane
switches from the collective table format of Figure
\ref{fig_pmv_rc_watch_all} to the single variable table, with examples
shown in Figure \ref{fig_pmv_rc_watch_one} below.

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.99\textwidth]{figures/pmv_cluster_one.png}
  \caption{{\bf Examining a Single Variable in a Watch Cluster:} When
    a single variable is selected in the watch cluster, the realmcast
    pane reports only on this variable, with one row for each
    vehicle. In this way, the user may see more information about the
    current posted value, such as the publisher (source), time posted,
    and the community of the app that posted the variable. When the
    user clicks again on the cluster keyname (in this case
    \vvar{mission\_top}), the realmcast pane reverts to reporting on
    all variables in the cluster as in Figure
    \ref{fig_pmv_rc_watch_all}.}
\label{fig_pmv_rc_watch_one}
\end{figure}


%===================================================================
\subsection{Adjusting the AppCast and RealmCast Color Scheme}
\label{sec_pmv_infocast_colors}

The infocast color schemes are by default different when the
infocasting panes are in appcasting or realmcasting modes. There are a
few different color schemes available to select from.  The default
appcast color scheme is \var{"indigo"}, reflected for example in
Figures \ref{fig_pmv_panes} or \ref{fig_pmv_infocast_menu}.  The
default realmcast color scheme is \var{"hillside"}, reflected for
example in Figures \ref{fig_pmv_rc_buttons} or
\ref{fig_pmv_rc_watch_all}. The color scheme may be changed by selecting
a different option from the \var{InfoCasting} pull-down menu, or toggling
through options with the hot key \var{Alt-'a'} for appcasting or
\var{Alt-'A'} for realmcasting. Alternatively they may be configured
in the \app{pMarineViewer} configuration block to have a different
color scheme at launch time:

\prevblue
\begin{verbatim}
  appcast_color_scheme   = indigo/white/beige           // Default is indigo
  realmcast_color_scheme = indigo/white/beige/hillside  // Default is hillside
\end{verbatim}
\postverb

%===================================================================
\section{The MOOS-Scope Pull-Down Menu}
%===================================================================
\label{sec_pmv_scoping}
%\index{pMarineViewer!Pull-Down Menu (Scope)}

The MOOS-Scope pull-down menu allows the user to configure 
\app{pMarineViewer} to scope on one or more variables in the \app{MOOSDB}.
The viewer allows visual scoping on only a single variable at a time,
but the user can select different variables via the pull-down menu, or
toggle between the current and previous variable with the \var{'/'}
key, or cycle between all registered variables with the \var{CTRL+'/'}
key. The scope fields are on the bottom of the viewer as shown in
Figure \ref{fig_pmv_scope_menu}. 

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.9\textwidth]{figures/pmv_scope_menu.png}
  \caption{{\bf The Scope Menu:} This pull-down menu allows the user
    to adjust which pre-configured MOOS variable is to be scoped, or
    to add a new variable to the scope list.}
\label{fig_pmv_scope_menu}
\end{figure}

The three fields show (a) the variable name, (b) the last time is was
updated, and (c) the current value of the variable. Configuration of
the menu is done in the MOOS configuration block with entries similar
to the following (which correlate to the particular items in the 
pull-down menu in Figure \ref{fig_pmv_scope_menu}):

\prevblue
\begin{verbatim}
    scope = RETURN, WPT_STAT, VIEW_SEGLIST, VIEW_POINT, VIEW_POLYGON
    scope = MVIEWER_LCLICK, MVIEWER_RCLICK
\end{verbatim}
\postverb


\noindent
The keyword \pvar{scope} is not case sensitive, but the MOOS variables
are. If no entries are provided in the MOOS configuration block, the
pull-down menu contains a single item, the \var{"Add Variable"} item.
By selecting this, the user will be prompted to add a new MOOS
variable to the scope list. This variable will then immediately become
the actively scoped variable, and is added to the pull-down menu.

%===================================================================
\section{The Exclusion Filter}
%===================================================================
\label{sec_pmv_exfilter}
%\index{pMarineViewer!Exclusion Filter}

A new feature added after Release 19.8.2: In situations where incoming
information from a particular vehicle, or set of vehicles, is to be
ignored, an {\em exclusion filter} may be used. \app{pMarineViewer}
contains a filter that may be configured by specifying one or more
vehicle names to ignore:

\prevblue
\begin{verbatim}
    ignore_name = abe
    ignore_name = abe, ben, cal
\end{verbatim}
\postverb

\vspace{0.1in}
\noindent
It may also be configured to consume information only by vehicles
explicitly named:

\prevblue
\begin{verbatim}
    match_name = ben, deb
    match_name = abe
\end{verbatim}
\postverb

\vspace{0.1in}
\noindent
For an incoming posting to survive the exclusion filter it must (a)
match any one of the list of match names, if any are provided, {\em
  and}, not match any one of the ignore names, if any are provided.
Of course if no \pvar{match\_name} or \pvar{ignore\_name} parameters
are provided, then nothing is filtered out.

\vspace{0.1in}
\noindent
The filter is applied to incoming node reports (\mvar{NODE\_REPORT}),
and incoming geometric messages such as \mvar{VIEW\_POINT} or
\mvar{VIEW\_POLYGON}.

\vspace{0.1in}
\noindent
Note: Certain geometric objects such as \mvar{VIEW\_COMMS\_PULSE},
that are published by apps in the shoreside community, will not be
filtered. Filtering is carried out by using the MOOS host community
information of the incoming MOOS mail, which typically matches
the vehicle name. Information such as \mvar{VIEW\_COMSS\_PULSE}, are
generated by a shoreside MOOS app, such as \app{uFldNodeComms} in this
case. As such, it will not be filtered.


%===================================================================
\section{The Action Pull-Down Menu}
%===================================================================
%\index{pMarineViewer!Pull-Down Menu (Action)}
\label{sec_pmv_actions}
%\index{pMarineViewer!Actions}
%\index{pMarineViewer!Poking the \app{MOOSDB}}

The Action pull-down menu allows the user to invoke pre-define pokes
to the \app{MOOSDB} (the \app{MOOSDB} to which the \app{pMarineViewer}
is connected). While hooks for a limited number of pokes are available
by configuring on-screen buttons (Section
\ref{sec_pmv_action_buttons}), the number of buttons is limited to
four. The "Action" pull-down menu allows for as many entries as will
reasonably be shown on the screen. Each action, or poke, is given by a
variable-value pair, and an optional grouping key.  Configuration is
done in the MOOS configuration block with entries of the following
form:

\prevblue
\begin{verbatim}
    action = menu_key=&lt;key&gt; # &lt;MOOSVar&gt;=&lt;value&gt; # &lt;MOOSVar&gt;=&lt;value&gt; # ...
\end{verbatim}
\postverb

\noindent
If no such entries are provided, this pull-down menu will not appear.
The fields to the right of the \pvar{action} are separated by the
\var{'\#'} character for convenience to allow several entries on one
line. If one wants to use the \var{'\#'} character in one of the
variable values, putting double-quotes around the value will suffice
to treat the \var{'\#'} character as part of the value and not the
separator.  If the pair has the key word \var{menu\_key} on the left,
the value on the right is a key associated with all variable-value
pairs on the line.  When a menu selection is chosen that contains a
key, then all variable-value pairs with that key are posted to the
\app{MOOSDB}. The following configuration will result in the
pull-down menu depicted in Figure \ref{pmv_fig_actions}.

\prevblue
\begin{verbatim}
    action  = menu_key=deploy # DEPLOY = true # RETURN = false
    action+ = menu_key=deploy # MOOS_MANUAL_OVERIDE=false
    action  = RETURN=true
\end{verbatim}
\postverb

\vspace{0.05in}
\noindent
The \pvar{action+} variant hints to the viewer that a line should be rendered
in the pull-down menu separating it from following items.

\vspace{0.05in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.85\textwidth]{figures/pmv_action_menu.png}
  \caption{{\bf The Action menu:} The variable value pairs on each
    menu item may be selected for poking or writing the
    \app{MOOSDB}. The three variable-value pairs above the menu
    divider will be poked in unison when any of the three are chosen,
    because they were configured with the same key, \vvar{&lt;deploy&gt;},
    shown to the right on each item.}
\label{pmv_fig_actions}
\end{figure}

\noindent
The variable-value pair being poked on an action selection will
determine the variable type by the following rule of thumb. If the
value is non-numerical, e.g., \var{true}, \var{one}, it is poked as a
string. If it is numerical it is poked as a double value. If one
really wants to poke a string of a numerical nature, the addition of
quotes around the value will suffice to ensure it will be poked as a
string. For example:

\prevblue
\begin{verbatim}
    action = Vehicle=Nomar # ID="7"
\end{verbatim}
\postverb

\noindent
As with any other publication to the \app{MOOSDB}, if a variable has been
previously posted with one type, subsequent posts of a different type
will be ignored.

%===================================================================
\section{The Mouse-Context Pull-Down Menu}
%===================================================================
\label{sec_pmv_mouse_context}
%\index{pMarineViewer!Pull-Down Menu (MouseContext)}
%\index[vars]{\mvar{MVIEWER\_LCLICK}} 
%\index[vars]{\mvar{MVIEWER\_RCLICK}}
%\index{Mouse!Mouse Pokes in pMarineViewer}

The Mouse-Context pull-down menu is an optional menu - it will not
appear unless it is configured for use. It is used for changing the
context of left and right mouse clicks on the operation area.

%===================================================================
\subsection{Generic Poking of the MOOSDB with the Operation Area Position}
\label{sec_pmv_generic_click}
%\index{pMarineViewer!Poking the \app{MOOSDB}}

When the user clicks the left or right mouse in the geo portion of the
\app{pMarineViewer} window, the variables \mvar{MVIEWER\_LCLICK} and
\mvar{MVIEWER\_RCLICK} are published respectively with the operation
area location of the mouse click, and the name of the active
vehicle. A left mouse click may result in a publication similar to:

\prevgreen
\begin{verbatim}
    MVIEWER_LCLICK = x=19.0,y=57.0,lat=43.8248027,lon=-70.3290334,vname=henry,counter=1
\end{verbatim}
\postverb

\noindent
A counter is maintained by \app{pMarineViewer} and is incremented and
included on each post. The above style posting presents a generic way
to convey to other MOOS applications an operation area position. In
this case the other MOOS applications need to conform to this generic
output. But, with a bit of further configuration, a similar {\em
  custom} post to the \app{MOOSDB} is possible to shift the burden of
conformity away from the other MOOS applications where typically a
user does not have the ability to change the interface.

%===================================================================
\subsection{Custom Poking of the MOOSDB with the Operation Area Position}
\label{sec_pmv_custom_click}

Custom configuration of mouse clicks is possible by (a) allowing the
MOOS variable and value to be defined by the user, and (b) exposing a
few macros in the custom specification to embed operation area
information. Configuration is done in the MOOS configuration block
with entries of the following form: 

%\index{Mouse!Mouse Poke Configuration}

\prevblue
\begin{verbatim}
   left_context[&lt;key&gt;]  = &lt;var-data-pair&gt;
   right_context[&lt;key&gt;] = &lt;var-data-pair&gt;
\end{verbatim}
\postverb

\noindent
The \pvar{left\_context} and \pvar{right\_context} keywords are case
insensitive.  If no entries are provided, this pull-down menu will not
appear. The \var{&lt;key&gt;} component is optional and allows for groups of
variable-data pairs with the same key to be posted together with the
same mouse click. This is the selectable {\em context} in the
Mouse-Context pull-down menu.  If the \var{&lt;key&gt;} is empty, the
defined posting will be made on all mouse clicks regardless of the
grouping, as is the case with \mvar{MVIEWER\_LCLICK} and
\mvar{MVIEWER\_RCLICK}.

\vspace{0.1in}
\noindent
Macros may be embedded in the string to allow the string to contain
information on where the user clicked in the operation area. These
patterns are: \var{\$(XPOS)} and \var{\$(YPOS)} for the local \var{x}
and \var{y} position respectively, and \var{\$(LAT)}, and
\var{\$(LON)} for the latitude and longitude positions. The pattern
\var{\$(IX)} will expand to an index (beginning with zero by default)
that is incremented each time a click/poke is made. This index can be
configured to start with any desired index with the
\pvar{lclick\_ix\_start} and \pvar{rclick\_ix\_start} configuration
parameters for the left and right mouse clicks respectively.  The
following configuration will result in the pull-down menu depicted in
Figure \ref{pmv_fig_context}.

\prevblue
\begin{verbatim}
   left_context[surface_point] = SPOINT = $[XPOS],$[YPOS]
   left_context[surface_point] = COME_TO_SURFACE = true
   left_context[return_point]  = RETURN_POINT = point=$[XPOS],$[YPOS], vname=$[VNAME]
   left_context[return_point]  = RETURN_HOME = true
   left_context[return_point]  = RETURN_HOME_INDEX = $[IX]
   right_context[loiter_point] = LOITER_POINT = lat=$[LAT], lon=$[LON]
   right_context[loiter_point] = LOITER_MODE = true
\end{verbatim}
\postverb

\noindent
Note in the figure that the first menu option is \var{"no-action"}
which shuts off all MOOS pokes associated with any defined groups
(keys). In this mode, the \mvar{MVIEWER\_LCLICK} and
\mvar{MVIEWER\_RCLICK} pokes will still be made, along with any other
poke configured without a \var{&lt;key&gt;}.

\vspace{0.05in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.8\textwidth]{figures/pmv_pull_context.png}
  \caption{{\bf The Mouse-Context menu:} Keywords selected from this
    menu will determine which groups of MOOS variables will be poked
    to the \app{MOOSDB} on left or mouse clicks. The variable values
    may have information embedded indicating the position of the mouse
    in the operation area at the time of the click.}
\label{pmv_fig_context}
\end{figure}

\noindent
The full set of macros are:

\begin{packed_itemize}
\item \var{\$[XPOS]}: The local x coordinate of the mouse click, to 0.1 meters.
\item \var{\$[X]}: The local x coordinate of the mouse click, to 1 meter.
\item \var{\$[YPOS]}: The local y coordinate of the mouse click, to 0.1 meters.
\item \var{\$[Y]}: The local y coordinate of the mouse click, to 1 meter.
\item \var{\$[IX]}: An integer that increments each each left mouse click. It starts
  at zero, but can be made to start at N with the config parameter
  \pvar{lclick\_ix\_start}.
\item \var{\$[BIX]}: An integer that increments each each right mouse
  click. It starts at zero, but can be made to start at N with the
  config parameter \pvar{rclick\_ix\_start}.
\item \var{\$[UTC]}: The current time in UTC seconds, in millisecond precision.
\item \var{\$[LAT]}: The local latitude coordinate of the mouse click.
\item \var{\$[LON]}: The local longitude coordinate of the mouse click.

\item \var{\$[VNAME]}: The active vehicle name
\item \var{\$[VNAME\_CLOSEST]}: The name of the vehicle closest to the mouse click
\item \var{\$[UP\_VNAME]}: The active vehicle name in upper case
\item \var{\$[UP\_VNAME\_CLOSEST]}: The name of the vehicle, in upper
  case, closest to the mouse click
\item \var{\$[HDG]}: The heading from the active vehicle to the x-y position of
  the mouse click.
\end{packed_itemize}

\vspace{0.1in}
\noindent
Note macros above are of the form \var{\$[MACRO]} using square brackets. Macros specified
with parentheses, e.g., \var{\$(MACRO)}, are also supported. The preferred form is
the former, since parentheses macros are used by the \app{splug} utility for
expanding mission files. Using square macros in \app{pMarineViewer} can help
ward off confusion.

\vspace{0.1in}
\noindent
Certain macros are also available for expansion in the MOOS variable name component
of a posting. For example, consider the following configuration entry:

\prevblue
\begin{verbatim}
   left_context[return_point]  = RETURN_POINT_$[UP_VNAME_CLOSEST] = point=$(XPOS),$(YPOS)
\end{verbatim}
\postverb

\noindent
the macro \var{\$[UP\_VNAME\_CLOSEST]} will expand to the upper case name of the
vehicle closest to the mouse click, and may result in a posting like:

\prevgreen
\begin{verbatim}
   RETURN_POINT_HENRY = point=87.2,99.8
\end{verbatim}
\postverb

\noindent
The list of macros available for expansion in the MOOS variable name are:

\begin{packed_itemize}
\item \var{\$[VNAME]}: The active vehicle name
\item \var{\$[VNAME\_CLOSEST]}: The name of the vehicle closest to the mouse click
\item \var{\$[UP\_VNAME]}: The active vehicle name in upper case
\item \var{\$[UP\_VNAME\_CLOSEST]}: The name of the vehicle, in upper
  case, closest to the mouse click
\end{packed_itemize}



%===================================================================
\section{Configuring and Using the Commander Pop-Up Window}
%===================================================================
\label{sec_pmv_popup_full}

The {\em commander pop-up} window is meant to provide an extendible
command and control interface for missions requiring more than a few
on-screen buttons. It needs to be configured and thought through prior
to mission launch, to reflect whatever the mission operator may need to 
do during the mission. The window conveniently pops up and is hidden by
toggling the space bar. An example is shown below.

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.95\textwidth]{figures/pmv_command_popup2.png}
  \caption{The commander pop-up window is toggled open/closed with the
    space-bar key and presents the user with a set of user-configured
    commands to either the all vehicles, individual vehicles, or the the
    \app{pMarineViewer} shoreside community itself.}
\label{fig_pmv_commander2}
\end{figure}

\noindent
Below we discuss how to work with the window and its content, how to configure
the pop-up window, and the related assumptions of configuration in
\app{uFldShoreBroker} to ensure proper command out to the vehicles.


%===================================================================
\subsection{Commander Pop-Up Window Actions and Content}
\label{sec_pmv_popup_windows}

The commander pop-up window has typically four components as indicated
in Figure \ref{fig_pmv_cmd_pop}. The first component contains a single
pane of buttons with postings to the local shoreside MOOSDB, not
intended to be passed on to any vehicles. The second component
contains a single pane of buttons for postings intended to be sent to
all vehicles. The third component holds a dedicated pane for each
known vehicle, with buttons intended for direct communication to the
named vehicle. The fourth component contains the {\em command history}, 
a list of the actual postings made from recent button clicks, with the
most recent postings at top.

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.75\textwidth]{figures/pmv_popup_annotated.png}
  \caption{The commander pop-up window is contains four parts as
    shown. The button grouping is done automatically depending on the
    user configuration.  Each button may be configured to make one or
    more posts to the MOOSDB.}
\label{fig_pmv_cmd_pop}
\end{figure}

\vspace{0.1in}
\noindent
The command history also indicates the clustering of posts associated
with recent button clicks. The Post-ID, is shown in the middle
column. All postings from the same button click, begin with the same
letter, allowing the user to discern the group of postings resulting
from a single button click. The user may also may a hypothetical post
by clicking any button with the shift-key held down. In this case,
no post will be made to the MOOSDB, but the actions that would have
been posted are added to the command history, separated by a dashed
line as in Figure \ref{fig_pmv_cmd_pop}. A subsequent actual button
click would erase he hypothetical lines from the command history.
Finally, if screen real estate is an issue, the command history pane
may be hidden by toggling with the \var{'p'} character. 

\vspace{0.1in}
\noindent
The position and sizing of the command-popup window may be adjusted
upon opening, with the buttons retaining their size, but the button
positions automatically adjusted to best fit the size of the window.
As the user adjusts wider, the number of buttons in each row will
grow, and the height will be as high as needed to fit the content. As
the user adjusts taller, the command history pane is grown to show
more history. The whole command pop-up window may be hidden and
re-shown by toggling the spacebar-key. When doing so, note that not
only the shape, but also the position w.r.t. the \app{pMarineViewer}
window is also retained.


%===================================================================
\subsection{Commander Pop-Up Configuration}
\label{sec_pmv_popup_config}

The set of possible command buttons and their corresponding posts to
the MOOSDB may be referred to as a command portfolio, or {\em
  commandfolio} for short. This configuration is achieved with a set
of lines of the following format:

\begin{fileverb}
  cmd = label=&lt;val&gt;, var&lt;val&gt;, sval=&lt;val&gt;, dval=&lt;val&gt;, receivers=&lt;val&gt;, color=&lt;val&gt;
\end{fileverb}

\vspace{0.15in}
\noindent
{\bf The label field}:
\vspace{0.05in}
\noindent
The button label is the text that will appear on the viewer button. It
is also used as a unique identifier to associate several configuration
lines together to make several posts with a single button.

\vspace{0.15in}
\noindent
{\bf The \var{var} field}:
    
\noindent
The \var{var} field names a single MOOS variable to be used in a post
when this button is clicked. As such it should follow MOOS conventions
and be upper case, no white space, not begin with a number, no use of
special characters like \var{'@', '?', '('} etc., and use the
underscore character \var{'\_'} to separate components. These are only
conventions and not enforced.

\vspace{0.15in}
\noindent
{\bf The \var{sval} field}:

\noindent
If a posting is to be made with a string value, the \var{sval} field
should be used to specify this value.

\vspace{0.15in}
\noindent
{\bf The \var{dval} field}:
\vspace{0.05in}
\noindent
If a posting is to be made with a numerical (double) value, the
\var{dval} field should be used to specify this value.

\vspace{0.15in}
\noindent
{\bf The \var{receivers} field}:
\vspace{0.05in}
\noindent
This field specifies a colon-separated list of vehicles, e.g.,
\var{henry:gilda} to be receivers of the posts associated with this
button. If, for example, a vehicle named \var{henry} is named, with
the MOOS variable \var{DEPLOY}, a button click will result in a
posting to the variable \var{DEPLOY\_HENRY}. Two special names are
reserved, \var{"all"} and \var{"shoreside"}.  If \var{"all"} is used,
\var{DEPLOY\_ALL} will be posted, {\em not} \var{DEPLOY\_GILDA} and
\var{DEPLOY\_HENRY} for example.  If \var{"shoreside"} is used, simply
\var{DEPLOY} will be posted.

\vspace{0.15in}
\noindent
{\bf The \var{colors} field}:

\noindent
If the user desires a certain command button to visually stand out, a
color may be specified. For example, in Figure \ref{fig_pmv_cmd_pop},
the button to order a vehicle to station keep is highlighted in red,
since this is often regarded as the go-to action when or if a surface
vehicle encounters intervention from an operator.

%===================================================================
\subsection{Commander Pop-Up Example Configuration from m2\_berta Mission}
\label{sec_pmv_popup_example}

Below is an example commander pop-up window configuration from the
\var{m2\_berta} mission. It will result in the commander window shown
in Figure \ref{fig_pmv_cmd_pop}. Note the macro \var{\$(VNAMES)} in many
of the configuration lines. This macro is filled in at launch time by the
colon-separated list of all vehicles being launched. See the launch script
in the \var{m2\_berta} mission for an example.

\vspace{0.15in}
\begin{fileverb}
 cmd = label=DEPLOY, var=DEPLOY,  sval=true,  receivers=all:$(VNAMES)
 cmd = label=DEPLOY, var=MOOS_MANUAL_OVERRIDE,  sval=false,  receivers=all:$(VNAMES)
 cmd = label=DEPLOY, var=AVOID,  sval=true,  receivers=all:$(VNAMES)
 cmd = label=DEPLOY, var=RETURN,  sval=false,  receivers=all:$(VNAMES)
 cmd = label=DEPLOY, var=STATION_KEEP,  sval=false,  receivers=all:$(VNAMES)

 cmd = label=RETURN, var=RETURN, sval=true, receivers=all:$(VNAMES)
 cmd = label=RETURN, var=STATION_KEEP, sval=false, receivers=all:$(VNAMES)

 cmd = label=PERMUTE, var=UTS_FORWARD,  dval=0,  receivers=shore

 cmd = label=STATION, var=STATION_KEEP,  sval=true,  receivers=all:$(VNAMES), color=pink

 cmd = label=LOITER-FAST, var=UP_LOITER,  sval=speed=2.8,  receivers=all:$(VNAMES)
 cmd = label=LOITER-SLOW, var=UP_LOITER,  sval=speed=1.4,  receivers=all:$(VNAMES)

 cmd = label=LOITER-CLOCKWISE-TRUE,  var=UP_LOITER, sval=clockwise=true,  receivers=all:$(VNAMES)
 cmd = label=LOITER-CLOCKWISE-FALSE, var=UP_LOITER, sval=clockwise=false, receivers=all:$(VNAMES)
 cmd = label=LOITER-CLOCKWISE-BEST,  var=UP_LOITER, sval=clockwise=false, receivers=all:$(VNAMES)
\end{fileverb}
	

%===================================================================
\subsection{Commander Pop-Up Coordination with pShare and uFldShoreBroker}
\label{sec_pmv_popup_pshare}

Neither the commander popup window, nor \app{pMarineViewer} for that matter,
are able to communicate with vehicles directly. The convention here is that
if posting such as \var{DEPLOY=true} is desired to be sent to say vehicle
\var{"henry"}, then a post of \var{DEPLOY\_HENRY=true} is made instead.
And if all vehicles are to be deployed with a single button click, then
a posting of \var{DEPLOY\_ALL=true} is made. 


\noindent
The assumption is made that an inter-MOOSDB share arrangement of some
form, typically with \app{pShare}, is made from the shoreside
community to each vehicle. This can be made directly with \app{pShare}
with a pair of lines as the following:

\vspace{0.1in}
\begin{fileverb}
  Output = src_name=DEPLOY_ALL, dest_name=DEPLOY, route=192.168.1.12:9300
  Output = src_name=DEPLOY_GUS, dest_name=DEPLOY, route=192.168.1.12:9300
\end{fileverb}
\vspace{0.1in}

\noindent
The above pair of lines would be needed for {\em each} vehicle command,
for {\em each} vehicle. This is accomplished much more conveniently if
the uField Toolbox tool \app{uFldShoreBroker} is used to automatically
coordinate known vehicles, and commands with \app{pShare}. The above
pair of lines is instead:

\vspace{0.1in}
\begin{fileverb}
  qbridge = DEPLOY
\end{fileverb}

\vspace{0.1in}

\noindent
And for multiple commands, with say five vehicles for example:

\vspace{0.1in}
\begin{fileverb}
  qbridge = DEPLOY, RETURN, STATION_KEEP, UP_LOITER, MOOS_MANUAL_OVERRIDE
\end{fileverb}

\vspace{0.1in}

\noindent
This single line using \app{uFldShoreBroker} would require 30 separate
\app{pShare} lines.



%===================================================================
\section{Configuration Parameters for pMarineViewer}
%===================================================================
\label{pmv_runtime}
%\index{pMarineViewer!Configuration Parameters}
%\index{Configuration Parameters!pMarineViewer}

The blue items in pull-down menus are also available as mission file
configuration parameters. The configuration parameter is identical to
the pull-down menu text. For example in the BackView menu shown in
Figure \ref{fig_pmv_backview}, the menu item \pvar{full\_screen}\psvar{=true}
may also be set in the \app{pMarineViewer} configuration block
verbatim with \pvar{full\_screen}\psvar{=true}.

%===================================================================
\subsection{Configuration Parameters for the BackView Menu}
\label{sec_pmv_params_backview}

The parameters in Listing \ref{lst_pmv_params_backview} relate to the
BackView menu described more fully in Section \ref{sec_pmv_backview}.
Parameters in blue below correlate to parameters in blue in the
pull-down menu.  For these parameters, the text in the pull-down menu
is identical to a similar entry in the configuration file.

\vspace{0.15in}
\begin{listing}{Configuration Parameters for \app{pMarineViewer} BackView Menu}
\label{lst_pmv_params_backview}
\renewcommand{\arraystretch}{1.1}
\begin{longtable}{rp{0.761\textwidth}}

  \pvar{back\_shade}: &amp; Shade of gray background when no image is
  used. Legal value range: [0, 1].  Zero is black, one is white. \\

  \pvar{full\_screen}: &amp; If true, viewer is in full
  screen mode (no appcasts, no fields rendered at the bottom). Legal
  values: true, false. Section \ref{sec_pmv_fullscreen}. \\

  \pvar{hash\_delta}: &amp; Sets the hash line
  spacing. Legal values: 50, 100, 200, 500, 1000. The default is 100.
  Section \ref{sec_pmv_hash}. \\

  \pvar{hash\_shade}: &amp; Shade of hash marks. Legal value range: [0, 1]. 
  Zero is black, one is white. Section \ref{sec_pmv_hash}. \\

  \pvar{hash\_viewable}: &amp; If true, hash lines are
  rendered over the op area.  Legal values: true, false. The default
  is false. Section \ref{sec_pmv_hash}. \\

  \pvar{log\_the\_image}: &amp; If true, a request is posted to pLogger to 
  log a copy of the image and info file. Legal values: true, false. The default
  is false. Section \ref{sec_pmv_bground_images}. \\

  \pvar{tiff\_file}: &amp; Filename of a tiff file background image. After
  Release 22.8.x, multiple lines of this parameter will load multiple
  tiff files. Section \ref{sec_pmv_bground_images}. \\

  \pvar{tiff\_file\_b}: &amp; Filename of another tiff file
  background image. Deprecated after Release 22.8.x: just use multiple
  \pvar{tiff\_file} lines. Section \ref{sec_pmv_bground_images}. \\

  \pvar{tiff\_type}: &amp; Parameter no longer supported, after Release 22.8.x \\

  \pvar{tiff\_viewable}: &amp; Use the tiff background image if set to
  true. Otherwise a gray screen is used as a background. Legal values:
  true, false. The default it true. Section
  \ref{sec_pmv_bground_images}. \\
 
  \pvar{view\_center}: &amp; Sets the center of the viewing image in x,y 
  local coordinates. Legal values: (double,double). The default is 
  (0,0).

\end{longtable}
\end{listing}

%===================================================================
\subsection{Configuration Parameters for the GeoAttributes Menu}
\label{sec_pmv_params_geo}

The parameters in Listing \ref{lst_pmv_params_geo} relate to the
GeoAttributes pull-down menu described more fully in Section
\ref{sec_pmv_geometry}.  Parameters in blue below correlate to
parameters in blue in the pull-down menu.  For these parameters, the
text in the pull-down menu is identical to a similar entry in the
configuration file.

\vspace{0.15in}
\begin{listing}{Configuration Parameters for \app{pMarineViewer} Geometry Menu}
\label{lst_pmv_params_geo}
\renewcommand{\arraystretch}{1.1}
\begin{longtable}{rp{0.68\textwidth}} 

  %------ Circle
  \pvar{circle\_viewable\_all}: &amp; If false, circles are 
  suppressed from rendering. Legal values: true, false. The default is true. 
  Section \ref{sec_pmv_geo_objs}. \\

  \pvar{circle\_viewable\_labels}: &amp; If false, circle labels
  are suppressed from rendering. Legal values: true, false. The default is true. 
  Section \ref{sec_pmv_geo_objs}. \\

  %------ CommsPulse
  \pvar{comms\_pulse\_viewable\_all}: &amp; If false, comms pulses
  are suppressed from rendering. Legal values: true, false. The default is true. 
  Section \ref{sec_pmv_pulses}. \\

  %------ Datum
  \pvar{datum\_viewable}: &amp; If false, the datum is
  suppressed from rendering. Legal values: true, false. The default is true. 
  Sections \ref{sec_pmv_bground_images} and \ref{sec_pmv_geometry}. \\  
  \pvar{datum\_color}: &amp; The color used for rendering the
  datum. Legal values: Any color listed in the Colors Appendix. The default is red. 
  Sections \ref{sec_pmv_bground_images} and \ref{sec_pmv_geometry}. \\
  \pvar{datum\_size}: &amp; The size of the point used to render the 
  datum.  Legal values: Integers in the range $[1, 10]$. The default is 2. 
  Sections \ref{sec_pmv_bground_images} and \ref{sec_pmv_geometry}. \\

  %------ Drop Points
  \pvar{drop\_point\_viewable\_all}: &amp; If false, drop points are 
  suppressed from rendering. Legal values: true, false. The default is true. 
  Section \ref{sec_pmv_droppoints}. \\
  \pvar{drop\_point\_coords}: &amp; Specifies whether the drop point
  labels are in earth or local coordinates. Legal values are: as-dropped, lat-lon, 
  local-grid. The default is as-dropped. Section \ref{sec_pmv_droppoints}. \\
  \pvar{drop\_point\_vertex\_size}: &amp; The size of the point used
  to render a drop point. Legal values: Integers in the range $[1, 10]$. 
  The default is 2.   Section \ref{sec_pmv_droppoints}. \\

  %------ Grids
  \pvar{grid\_viewable\_all}: &amp; If false, grids are 
  suppressed from rendering. Legal values: true, false. The default is true. \\
  \pvar{grid\_viewable\_labels}: &amp; If false, grid labels are 
  suppressed from rendering. Legal values: true, false. The default is true. \\
  \pvar{grid\_viewable\_opaqueness}: &amp; The degree to which 
  grid renderings are opaque. Legal range: $[0, 1]$. The default is $0.3$. \\

  %------ Markers
  \pvar{marker} &amp; A marker may be stated in the configuration file with the same
  format of the \mvar{VIEW\_MARKER} message. Section \ref{sec_pmv_markers}. \\

  \pvar{marker\_scale}: &amp; The scale applied to marker renderings. Legal range: 
  $[0.1, 100]$.  The default is $1.0$. Section \ref{sec_pmv_markers}. \\

  \pvar{marker\_viewable\_all}: &amp; If false,
  markers are suppressed from rendering. Legal values: true,
  false. The default is true. Section \ref{sec_pmv_markers}. \\

  \pvar{marker\_edge\_width}: &amp; Markers are rendered with an outer black edge. The
  edge may be set thicker to aid in viewing. Legal values: Integer values in the
  range $[1, 10]$. The default is $1$. Section \ref{sec_pmv_markers}. \\

  \pvar{marker\_viewable\_labels}: &amp; If false, marker labels
  are suppressed from rendering. Legal values: true, false. The default is true. 
  Section \ref{sec_pmv_markers}. \\

  %------ OpArea
  \pvar{oparea\_viewable\_all}: &amp; If false, oparea lines are 
  suppressed from rendering. Legal values: true, false. The default is true. \\
  \pvar{oparea\_viewable\_labels}: &amp; If false, oparea label
  is suppressed from rendering. Legal values: true, false. The default is true. \\

  %------ Points
  \pvar{point\_viewable\_all}: &amp; If false, points are 
  suppressed from rendering. Legal values: true, false. The default is true. 
  Section \ref{sec_pmv_geo_objs}. \\
  \pvar{point\_viewable\_labels}: &amp; If false, point labels are 
  suppressed from rendering. Legal values: true, false. The default is true. 
  Section \ref{sec_pmv_geo_objs}. \\

  %------ Polygon
  \pvar{polygon\_viewable\_all}: &amp; If false, polygons
  are suppressed from rendering. Legal values: true, false. The default is true. 
  Section \ref{sec_pmv_geo_objs}. \\
  \pvar{polygon\_viewable\_labels}: &amp; If false, polygon labels
  are suppressed from rendering. Legal values: true, false. The default is true. 
  Section \ref{sec_pmv_geo_objs}. \\

  %------ Range Pulse
  \pvar{range\_pulse\_viewable\_all}: &amp; If false, range pulses
  are suppressed from rendering. Legal values: true, false. The default is true. 
  Section \ref{sec_pmv_pulses}. \\

  %------ Seglist
  \pvar{seglist\_viewable\_all}: &amp; If false, seglists are
  suppressed from rendering. Legal values: true, false. The default is true. 
  Section \ref{sec_pmv_geo_objs}. \\
  \pvar{seglist\_viewable\_labels}: &amp; If false, seglist labels
  are suppressed from rendering. Legal values: true, false. The default is true. 
  Section \ref{sec_pmv_geo_objs}. \\

  %------ Vectors
  \pvar{vector\_viewable\_all}: &amp; If false, vectors are 
  suppressed from rendering. Legal values: true, false. The default is true. 
  Section \ref{sec_pmv_geo_objs}. \\
  \pvar{vector\_viewable\_labels}: &amp; If false, vector labels
  are suppressed from rendering. Legal values: true, false. The default is true. 
  Section \ref{sec_pmv_geo_objs}. \\

\end{longtable}
\end{listing}

%===================================================================
\subsection{Configuration Parameters for the Vehicles Menu}
\label{sec_pmv_params_vehicles}

The parameters in Listing \ref{lst_pmv_params_vehicles} relate to the
Vehicles pull-down menu described more fully in Section
\ref{sec_pmv_vpulldown}.  Parameters in blue below correlate to
parameters in blue in the pull-down menu.  For these parameters, 
text in the pull-down menu is identical to a similar entry in the
configuration file.

\vspace{0.15in}
\begin{listing}{Configuration Parameters for pMarineViewer Vehicles Pull-Down Menu}
\label{lst_pmv_params_vehicles}
\renewcommand{\arraystretch}{1.1}
\begin{longtable}{rp{0.68\textwidth}} 

  \pvar{bearing\_lines\_viewable}: &amp; If false,
  bearing lines will be suppressed from rendering. Legal values:
  true, false. The default is true. \\

  \pvar{center\_view}: &amp; Sets the pan position to be either directly
  above the active vehicle, or the average of all vehicles. Legal
  values: active, average.  The default is neither, resulting in the
  pan position being set to either (0,0) or set via other
  configuration parameters. Section \ref{sec_pmv_image_pos}. \\

  \pvar{stale\_remove\_thresh}: &amp; Number of seconds after a stale
  vehicle has been detetected before being removed. When time warp is
  one, vehicles are {\em not} automatically removed at all, and this
  number is meaningless.  Legal values: Any non-negative number. The
  default is 30. Section \ref{sec_pmv_staleness}. \\

  \pvar{stale\_report\_thresh}: &amp; Number of seconds after
  which a vehicle report will be considered stale. Legal values: Any non-negative
  number. The default is 60. Section \ref{sec_pmv_staleness}. \\

  \pvar{trails\_color}: &amp; The color of trail
  points rendered behind vehicles to indicate recent vehicle position
  history.  Legal values: Any color listed in the Colors Appendix. The
  default is white. Section \ref{sec_pmv_vehitrails}. \\

  \pvar{trails\_connect\_viewable}: &amp; If true the
  vehicle trail points are each connected by a line. Useful when node
  reports have large gaps in time.  Legal values: true, false. The
  default is true. Section \ref{sec_pmv_vehitrails}. \\

  \pvar{trails\_length}: &amp; The number of points retained for the rendering of 
  vehicle trails. Legal values: Integers in the range $[1, 100000]$. The 
  default is $100$. Section \ref{sec_pmv_vehitrails}. \\

  \pvar{trails\_point\_size}: &amp; The size of the points rendering the 
  vehicle trails. Legal values: Integers in the range $[1, 10]$. 
  The default is $1$. Section \ref{sec_pmv_vehitrails}. \\

  \pvar{trails\_viewable}: &amp; If false, vehicle trails are
  suppressed from rendering. Legal values: true, false. The default is true. 
  Section \ref{sec_pmv_vehitrails}. \\

  \pvar{vehicles\_active\_color}: &amp; The color of the active vehicle
  (the one who's data is being shown in the bottom data fields).
  Legal values: Any color listed in the Colors Appendix. The default
  is red.  Section \ref{sec_pmv_vehicolors}. \\

  \pvar{vehicles\_inactive\_color}: &amp; The color of inactive
  vehicles. Legal values: Any color listed in the Colors Appendix. The
  default is yellow. Section \ref{sec_pmv_vehicolors}. \\

  \pvar{vehicles\_shape\_scale}: &amp; The scale factor applied to vehicle
  size rendering. Legal values in the range: $[0.1, 100]$. The default
  is $1.0$.  Section \ref{sec_pmv_vehishapes}. \\

  \pvar{vehicles\_name\_mode}: &amp; Sets the mode for rendering
  the vehicle label. Legal values are: names, names+mode, names+shortmode, names+depth, off.
  The default is names+shortmode. Section \ref{sec_pmv_vehinames}. \\

  \pvar{vehicles\_name\_color}: &amp; Sets the color for rendering
  the vehicle label. Legal values are any color in the Colore Appendix.
  The default is white. Section \ref{sec_pmv_vehicolors}. \\

  \pvar{vehicles\_viewable}: &amp; If false, vehicles are
  suppressed from rendering. Legal values: true, false. The default is true. 
  Section \ref{sec_pmv_vpulldown}. \\

\end{longtable}
\end{listing}

%===================================================================
\subsection{Configuration Parameters for the InfoCasting Menu}
\label{sec_pmv_params_appcast}

The parameters in Listing \ref{lst_pmv_params_appcast} relate to the
InfoCasting pull-down menu described more fully in Section
\ref{sec_pmv_infocasting}.  Parameters in blue below correlate to
parameters in blue in the pull-down menu.  For these parameters, 
text in the pull-down menu is identical to a similar entry in the
configuration file.


\vspace{0.1in}
\noindent
Note: Starting with the first release after 2019's Release 19.8, this
\app{pMarineViewer} was augmented to include realmcasting in addition
to appcasting. The term {\em infocasting} is the general term refering
to either appcasting or realmcasting.  As such, some of the earlier
configuration parameters, e.g., \pvar{appcast\_font\_size}, have been
replace with a term like \app{infocast\_font\_size}. The older
configuration parameters are deprecated, still supported forseeable
releases.

\vspace{0.15in}
\begin{listing}{Configuration Parameters for pMarineViewer AppCast Pull-Down Menu}
\label{lst_pmv_params_appcast}
\renewcommand{\arraystretch}{1.1}
\begin{longtable}{rp{0.63\textwidth}} 

  \pvar{appcast\_color\_scheme}: &amp; The color scheme used in all three
  appcasting panes, affecting background color and font
  color. Possible settings, {\var{default}, \var{beige}, \var{indigo}
    or \var{white}}. The default is \var{indigo}. Section
  \ref{sec_pmv_infocast_colors}. \\
  
  \pvar{content\_mode}: &amp; Sets the on startup content, which can be
  changed by the user at any time. Either \var{appcast} or
  \var{realmcast}. The default is \var{appcast}. \\

  \pvar{infocast\_font\_size}: &amp; The font size uses in the {\em
    infocast} pane of the set of infocasting panes. Legal values:
  \var{xlarge}, \var{large}, \var{medium}, \var{small}, \var{xsmall}.
  The default is \var{medium}. Section \ref{sec_pmv_appcast_fonts}. \\

  \pvar{infocast\_height}: &amp; The height of the appcasting bottom pane
  as a percentage of the total \app{pMarineViewer} window
  height. Legal values: [30, 35, 40, 45,..., 85, 90]. The default is
  $75$.  Section \ref{sec_pmv_appcast_extents}.\\

  \pvar{infocast\_viewable}: &amp; If \var{true}, the infocasting set of
  panes are rendered on the left side of the viewer. Legal values:
  \var{true} or \var{false}.  The default is \var{true}. Section
  \ref{sec_pmv_appcast_onoff}.\\

  \pvar{infocast\_width}: &amp; The width of the infocasting panes as a
  percentage of the total \app{pMarineViewer} window width. Legal
  values: [20, 25, 30, 35,..., 65, 70]. The default is $30$.
  Section \ref{sec_pmv_appcast_extents}.\\

  \pvar{nodes\_font\_size}: &amp; The font size used in the {\em nodes}
  pane of the set of infocasting panes. Possible settings,
  {\var{xsmall}, \var{small}, \var{medium}, \var{large}, or
    \var{xlarge}}. The default is \var{large}. Section
  \ref{sec_pmv_appcast_fonts}.\\

  \pvar{procs\_font\_size}: &amp; The font size used in the {\em procs}
  pane of the set of infocasting panes. Possible settings,
  {\var{xsmall}, \var{small}, \var{medium}, \var{large} or
    \var{xlarge}}. The default is \var{large}. Section
  \ref{sec_pmv_appcast_fonts}.\\

  \pvar{realmcast\_color\_scheme}: &amp; Either \var{indigo}, \var{beige},
  \var{hillside}, \var{white}, or \var{default}. The default is
  \var{hillside}. Section \ref{sec_pmv_infocast_colors}. \\

  \pvar{realmcast\_show\_source}: &amp; If \var{true}, the Source column
  is shown on realmcast output. Setting to \var{false} conserves
  screen space, possibly enhancing readability.  The default is
  \var{true}. Section \ref{sec_pmv_relcast_content}. \\

  \pvar{realmcast\_show\_community}: &amp; If \var{true}, the Community
  column is shown on realmcast output. Setting to \var{false}
  conserves screen space, possibly enhancing readability.  The default
  is \var{true}. Section \ref{sec_pmv_relcast_content}. \\
  
  \pvar{realmcast\_show\_subscriptions}: &amp; If \var{true}, the
  Subscriptions block is shown on realmcast output. Setting to
  \var{false} conserves screen space, possibly enhancing readability.
  The default is \var{true}. Section \ref{sec_pmv_relcast_content}. \\

  \pvar{realmcast\_show\_masked}: &amp; If \var{true}, certain variables
  are excluded in realmcast output, e.g., virgin variables. Setting to
  \var{false} conserves screen space, possibly enhancing readability.
  The default is \var{true}. Section \ref{sec_pmv_relcast_content}. \\
  
  \pvar{realmcast\_wrap\_content}: &amp; If \var{true}, the variable Value
  column in realmcast output will wrap onto several lines. Setting to
  \var{true} possibly enhances readability for very long output.  The
  default is \var{false}. Section \ref{sec_pmv_relcast_content}. \\

  \pvar{realmcast\_trunc\_content}: &amp; If \var{true}, the variable Value
  column in realmcast output will be truncated. Setting to
  \var{true} possibly enhances readability for very long output.  The
  default is \var{false}. Section \ref{sec_pmv_relcast_content}. \\

  \pvar{realmcast\_time\_format\_utc}: &amp; If \var{true} the Time column
  in realmcast output will be shown in UTC time instead of local time
  since app startup. The default is \var{false}. Section
  \ref{sec_pmv_relcast_content}.  \\

  
  \pvar{refresh\_mode}: &amp; Determines the manner in which appcast
  requests are sent to apps. Legal values: \var{paused}, \var{events},
  \var{streaming}.  The default is \var{events}. Section
  \ref{sec_pmv_appcast_refresh}.
  
\end{longtable}
\end{listing}

%===================================================================
\subsection{Configuration Parameters for the Scope, MouseContext and Action Menus}
\label{sec_pmv_params_other}

\vspace{0.15in}
\begin{listing}{Configuration Parameters the Scope, MouseContext and Action Menus}
\label{lst_pmv_params_other}
\renewcommand{\arraystretch}{1.1}
\begin{longtable}{rp{0.78\textwidth}} 

  \pvar{scope}: &amp; A comma separated list of MOOS variables to
  scope. Section \ref{sec_pmv_scoping}. \\

  \pvar{oparea}: &amp; A specification of the operation area boundary for
  optionally rendering. \\

  \pvar{button\_one}: &amp; A configurable command and control
  button. The parameter \pvar{button\_1} may also be used.
  Section \ref{sec_pmv_action_buttons}.\\

  \pvar{button\_two}: &amp; A configurable command and control
  button. The parameter \pvar{button\_2} may also be used.
  Section \ref{sec_pmv_action_buttons}. \\

  \pvar{button\_three}: &amp; A configurable command and control
  button. The parameter \pvar{button\_3} may also be used.
  Section \ref{sec_pmv_action_buttons}.\\

  \pvar{button\_four}: &amp; A configurable command and control
  button. The parameter \pvar{button\_4} may also be used.
  Section \ref{sec_pmv_action_buttons}.\\

  \pvar{button\_five-twenty}: &amp; Additional configurable command and
  control button release following Release 19.8.1. Section
  \ref{sec_pmv_action_buttons}.\\

  \pvar{action}: &amp; A MOOS variable-value pair for posting, available
  under the Action pull-down menu. Section \ref{sec_pmv_actions}. \\

  \pvar{left\_context}: &amp; Allows the custom configuration of left mouse
  click context.  Section \ref{sec_pmv_mouse_context}. \\

  \pvar{right\_context}: &amp; Allows the custom configuration of right
  mouse click context.  Section \ref{sec_pmv_mouse_context}. \\

  \pvar{lclick\_ix\_start}: &amp; Starting index for the left mouse index
  macro.  Section \ref{sec_pmv_mouse_context}. \\

  \pvar{rclick\_ix\_start}: &amp; Starting index for the right mouse index
  macro.  Section \ref{sec_pmv_mouse_context}. \\

\end{longtable}
\end{listing}


%===================================================================
\subsection{Configuration Parameters for Optimizing in Extreme Load Situations}
\label{sec_pmv_params_opt}

In missions with a very high number of vehicles and very high time
warp, and perhaps also a very high number of geometric objects to
render, \app{pMarineViewer} will strain, slow or even freeze. The
breaking point is partly dependent on the speed and number of CPU
cores on your machine. There are a few measures that can be taken to
reduce the CPU load and squeeze more performance from
\app{pMarineViewer}. 


\vspace{0.15in}
\begin{listing}{Configuration Parameter for Optimizing with High Number of Vehicles}
\label{lst_pmv_params_opt}
\renewcommand{\arraystretch}{1.1}
\begin{longtable}{rp{0.78\textwidth}} 

  \pvar{node\_report\_unc}: &amp; If true, node reports will be ingested from
  \app{uFldNodeComms} rather than directly from the vehicles. (Introduced
  {\em after} Release 19.8.1.) \\

\end{longtable}
\end{listing}

\noindent
By setting the \pvar{node\_report\_unc} parameter to true,
\app{pMarineViewer} will register for \mvar{NODE\_REPORT\_UNC} as its
source for receiving node reports. Normally this information comes
from \mvar{NODE\_REPORT}. Normally the latter is shared directly from
vehicles. A typical vehicle will produce this message at 4Hz. In
simulations with a time warp of say 50, and simulating say 50
vehicles, this results in 10,000 node reports per second arriving in
the mailbox of \app{pMarineViewer}. While this may be managable,
depending on the computer, it consumes a sizeable portion of the CPU
load. If there are also happen to be very many geometric objects to
render, then the workload will strain.

\vspace{0.1in}
\noindent
By ingesting node reports instead from \app{uFldNodeComms}, the rate
of incoming node reports can be reduced to a level suitable for smooth
trajectory rendering. In practice this seems to be about 10-20Hz
before the human eye regards the motion as "jumpy". For the extreme
case described above, the \app{uFldNodeComms} app can reduce the rate
from 200Hz to 10Hz. Since \app{uFldNodeComms} is handling all these
node reports anyway, and since it is likely relegated to a CPU
different from \app{pMarineViewer} on multi-core machines, it is an
effective way to aid \app{pMarineViewer}.



%===================================================================
\section{Publications and Subscriptions for pMarineViewer}
%===================================================================
%\index{pMarineViewer!Publications and Subscriptions}
%\index{Publications and Subscriptions!pMarineViewer}
\label{sec_pmv_pubs_subs}

The interface for \app{pMarineViewer}, in terms of publications and
subscriptions, is described below. This same information may also be
obtained from the terminal with:

\begin{consoleverb}
 $ pMarineViewer --interface or -i
\end{consoleverb}

%===================================================================
\subsection{Variables Published by pMarineViewer}
\label{sec_pmv_pubs}

It is possible to configure \app{pMarineViewer} to poke the
\app{MOOSDB} via either the Action pull-down menu (Section
\ref{sec_pmv_actions}), or via configurable GUI buttons (Section
\ref{sec_pmv_action_buttons}). It may also publish to the \app{MOOSDB}
variables configured to mouse clicks (Section
\ref{sec_pmv_mouse_context}). So the list of variables that
\app{pMarineViewer} publishes is somewhat user dependent, but the
following few variables may be published in all configurations.

\begin{packed_itemize}[2]
\item \mvar{APPCAST}: Contains an appcast report identical to the
  terminal output. Appcasts are posted only after an appcast request
  is received from an appcast viewing utility.

\item \mvar{APPCAST\_REQ\_&lt;COMMUNITY&gt;}: As an appcast viewer,
  \app{pMarineViewer} also generates outgoing appcast requests to MOOS
  communities it is aware of, including its own MOOS community. These
  postings are typically bridged to the other named MOOS community 
  with the variable renamed simply to \mvar{APPCAST\_REQ} when it
  arrives in the other community.

\item \mvar{HELM\_MAP\_CLEAR}: This variable is published once when the
  viewer connects to the \app{MOOSDB}.  It is used in the
  \app{pHelmIvP} application to clear a local buffer used to prevent
  successive identical publications to its variables.

\item \mvar{PMV\_CONNECT}: This variable is published once when the
  viewer connects to the \app{MOOSDB}.  It is always published with the 
  value 0. It can be used by any application that would like to publish
  or republish visual artifacts ensuring that \app{pMarineViewer} receives
  all mail in a sequence. Otherwise if the viewer comes up after the 
  sequences is published, it may only get the last element in the sequence.

\item \mvar{MVIEWER\_LCLICK}: When the user clicks the left mouse
  button, the position in local coordinates, along with the name of
  the active vehicle is reported. This can be used as a command and
  control hook as described in Section \ref{sec_pmv_mouse_context}.

\item \mvar{MVIEWER\_RCLICK}: This variable is published when the user
  clicks with the right mouse button. The same information is
  published as with the left click.

\item \mvar{MVIEWER\_UNHANDLED\_MAIL}: If the viewer receives mail that
  it is unable to parse, info on the MOOS variable and its content will
  be posted in this variable for debugging.

\item \mvar{PLOGGER\_CMD}: This variable is published with a 
  \var{"COPY\_FILE\_REQUEST"} to log a copy of the image and info
  file, only if \pvar{log\_the\_image} is set to true. Section
  \ref{sec_pmv_bground_images}.

\end{packed_itemize}

%===================================================================
\subsection{Variables Subscribed for by pMarineViewer}
\label{sec_pmv_subs}

\begin{packed_itemize}[2]
\item \mvar{APPCAST}: As an appcast enabled {\em viewer}, \app{pMarineViewer} also
  subscribes for appcasts from other other applications and communities to 
  provide the content for its own viewing capability.

\item \mvar{APPCAST\_REQ}: As an appcast enabled MOOS application,
  \app{pMarineViewer} also subscribes for appcast requests. Each
  incoming message is a request to generate and post a new appcast
  report, with reporting criteria, and expiration.

\item \mvar{REALMCAST}: As an realmcast enabled {\em viewer},
  \app{pMarineViewer} also subscribes for realmcasts from MOOS communities
  running \app{pRealm}, and renders them in the infocast panes
  described in Section \ref{sec_pmv_ac_vs_rc}.

\item \mvar{WATCHCAST}: As an realmcast enabled {\em viewer},
  \app{pMarineViewer} also subscribes for watchcasts from MOOS communities
  running \app{pRealm}, and renders them in the infocast panes
  described in Section \ref{sec_pmv_watch_clusters}.

\item \mvar{NODE\_REPORT}: This is the primary variable consumed by
  \app{pMarineViewer} for collecting vehicle position information.

\item \mvar{NODE\_REPORT\_LOCAL}: This serves the same purpose as the
  above variable. In some simulation cases this variable is used.

\item \mvar{PHI\_HOST\_INFO}: A string representing the detected IP
  address, published by \app{pHostInfo}. Used for augmenting the 
  \app{pMarineViewer} title bar with the current IP address.

\item \mvar{TRAIL\_RESET}: When the viewer receives this variable it
  will clear the history of trail points associated with each vehicle.
  This is used when the viewer is run with a simulator and the 
  vehicle position is reset and the trails become discontinuous.

\item \mvar{VIEW\_CIRCLE}: A string representation of an XYCircle object.
\item \mvar{VIEW\_COMMS\_PULSE}: A string representation of an XYCommsPulse object.
\item \mvar{VIEW\_GRID}: A string representation of a XYConvexGrids object.
\item \mvar{VIEW\_GRID\_CONFIG}: A string representation of a XYGrid configuration.
\item \mvar{VIEW\_GRID\_DELTA}: A string representation of a XYGrid configuration.
\item \mvar{VIEW\_POINT}: A string representation of an XYPoint object.
\item \mvar{VIEW\_POLYGON}: A string representation of an XYPolygon object.
\item \mvar{VIEW\_SEGLIST}: A string representation of an XYSegList object.
\item \mvar{VIEW\_MARKER}: A string designation of a marker type, size
and location.
\item \mvar{VIEW\_RANGE\_PULSE}: A string representation of an XYRangePulse object.
\item \mvar{VIEW\_VECTOR}: A string representation of an XYVector object

\end{packed_itemize}
 
\bibliographystyle{plain}
\footnotesize
\bibliography{biblio.bib}
\end{document}

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