<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">%====================================================================
\section{Contact Related Behaviors of the IvP Helm}
%====================================================================
\wikisec{grp=bhvmulti,file=HelmBehaviorsMulti,short=Contact Behaviors}

%\input{common_cpa_defs}

The section contains is a description of five behaviors currently
written for the helm that reason about relative position to another
vehicle or {\em contact}.

\begin{packed_itemize}[2]
\item The AvoidCollision behavior
\item The AvdColregsV19 behavior
\item The CutRange behavior
\item The Shadow behavior
\item The Trail behavior
\end{packed_itemize}

\noindent
Each behavior needs to be continuously updated with the position and
trajectory of a given contact. The helm subscribes to the MOOS
variable, \mvar{NODE\_REPORT}, which may have content similar to:

\prevgreen
\begin{verbatim}
NODE_REPORT= "NAME=alpha,TYPE=UUV,MOOSDB_TIME=39.01,TIME=1252348077.59,
              X=51.71,Y=-35.50,LAT=43.824981,LON=-70.329755,SPD=2.00,HDG=118.85,
              YAW=118.84754,DEPTH=4.63,LENGTH=3.8,MODE=SURVEYING"
\end{verbatim}
\postverb

\noindent
This contact information is stored in the helm information buffer for
any behavior that wishes to retrieve it on any iteration. Since each
behavior type needs to reason about contact information, the common code
for this is handled in superclass called \var{IvPContactBehavior}. So
for these behaviors, the class hierarchy looks like:

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.75\textwidth]{figures/contact_bhv_hier.png}
  \caption{{\bf IvP Contact Behaviors}: The contact-related behaviors
    share a common superclass to streamline the development of contact
    behaviors and provide a level consistency between behaviors.}
\label{fig_cn_bhvs}
\end{figure}

%==========================================================================
\subsection{Static Versus Dynamically Spawned Behaviors}

A contact behavior may be configured in one of two ways. The simplest
way is to reason about a particular contact with a name known at
mission time. This is more appropriate for a behavior that needs to
operate on one contact at a time, such as a trail or cut-range
behavior. While it is technically possible to try to cut-range or
trail multiple contacts simultaneously, and the IvP solver will
support such an attempt, typically such behaviors are focused on a
single contact. Configuration of the behavior simply names the contact

\prevblue
\begin{verbatim}
  contact = mothership
\end{verbatim}
\postverb

\vspace{0.1in}
\noindent
A second type of configuration is possible when several simultaneous
instances of the same behavior are desired, as during collision
avoidance with multiple contacts. In this case the behavior is
configured to enable {\em templating}, and the contact name is left
unspecified until a new contact emerges:

\prevblue
\begin{verbatim}
  templating = spawn
  contact = to_be_determined
\end{verbatim}
\postverb

\vspace{0.1in}
\noindent
A templating contact behavior works closely with a contact manager,
either the \app{pBasicContactMgr} app or the newer version,
\app{pContactMgrV20}.  The contact manager is responsible for
generating the MOOS posting events that trigger the spawning of a new
behavior. As depicted in Figure \ref{fig_bhv_spawn} below, the contact
manager applies a certain configurable criteria to a contact, and if
it passes that criteria, it generates an alert to the helm, resulting
in a spawned behavior.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.75\textwidth]{figures/bcm_helm_spawn.png}
  \caption{{\bf Relationship between the contact manager and spawned
      contact-related behaviors}: (1) A contact closes range to ownship,
    crossing a range threshold. (2) The contact manager makes note and
    changes the internal record associated with the contact. (3) An
    alert it generated and received by the helm. (4) The helm spawns a
    new contact-related behavior dedicated to this contact.x}
\label{fig_bhv_spawn}
\end{figure}

\vspace{0.1in}
\noindent
Typically the contact manager criteria for generating an alert is
based on the {\em range} of the contact to ownship. However, the
contact manager may also utilize additional filters, providing user
configurable selectivity as to which contacts generate alerts
resulting in behavior spawnings. These filters may be configured at
the contact manager level, e.g., ignore all contacts of type sailboat.
Or they may be configure at the behavior level, e.g., one collision
avoidance behavior matches sailboats, and another collision avoidance
behavior matches motorboats. This is covered in part in the
documentation of \app{pContactMgrV20}, but portion that is accessible
through behavior configuration is described next.

%=======================================================================
\subsection{Exclusion Filters}
\label{sec_cbhv_filters}

An {\em exclusion filter} is tool for allowing the contact manager
and/or the helm to treat distinct contacts differently, based on a
certain property. {\em The contact manager has an exclusion filter,
  and all behaviors have an exclusion filter.} They can be safely
ignored if one wishes to simply treat all contacts equally, but they
can provide some powerful options when applied to a particular
situation.

%-----------------------------------------------------------------------
\subsubsection{Types of Contact Exclusion Filters}

Contact exclusion filters may be configured around four different types
of properties:

\begin{packed_itemize}
\item \var{name}: This is the most direct method but rather
  brittle. But if there is a particular named vehicle that you'd like
  to handle differently, it can be just called out by name.
\item \var{type}: The vehicle type is part of the incoming
  \mvar{NODE\_REPORT} message, e.g., UUV, USV and so on.
\item \var{group}: The vehicle group is part of the incoming
  \mvar{NODE\_REPORT} message, e.g., friendly, foe and so on.
\item \var{region}: A convex polygon describing a region of the operation
  area.
\end{packed_itemize}

\noindent
Each of the above four properties can be configured as \var{match} or
\var{ignore} filters. For example, \bvar{match\_type=kayak} indicates
that the contact must by of type \var{kayak}. Likewise
\bvar{ignore\_type=kayak} indicates that the contact must be of some
type other than \var{kayak}. The same is true for \var{name},
\var{group}, and \var{region} properties. This makes eight possible
configuration parameters available to all contact behaviors when
templating is enabled:

\begin{packed_itemize}
\item \bvar{match\_group} and \bvar{ignore\_group}
\item \bvar{match\_name} and \bvar{ignore\_name}
\item \bvar{match\_type} and \bvar{ignore\_type}
\item \bvar{match\_region} and \bvar{ignore\_region}
\end{packed_itemize}

\noindent
Multiple entries for each property may be used. If for example
multiple \var{match\_name} configurations are used, a contact will
pass the filter if it matches at least one. If multiple
\var{ignore\_name} configurations are used, a contact will pass the
filter only if it has a name different from all.

\vspace{0.1in}
\noindent
The \var{region} property is a bit different from the other three
properties.  While a contact's \var{name}, \var{type}, and \var{group}
properties tend not to change as a mission unfolds, the contact
position does. When the \var{region} is used by the contact manager as
a filter it applies only to that moment in time. If, for example, the
contact was outside a \var{match\_region} but then enters it, it will
now pass the filter and an alert will be generated, provided all other
filter and range criteria are met. Likewise if the contact manager
generated an alert for a contact, but then moved out of a
\var{match\_region} or into an \var{ignore\_region}, the previously
generated alert will not somehow be retracted.

\vspace{0.1in}
\noindent
One last note about \var{region} filters: non-convex regions may be
implemented by using two or more convex regions that "cover" the
desired non-convex region. And consistent with the above discussion,
the approximating convex regions may harmlessly overlap.

%-----------------------------------------------------------------------
\subsubsection{Configuring Exclusion Filters Globally or Locally}

As shown in Figure \ref{fig_bhv_spawn} above, the contact manager is
the gatekeeper for sending the helm alert messages that may trigger
the spawning of the behavior. Users can configure the exclusion
filters in one of two ways:

\vspace{0.05in}
\begin{packed_itemize}
\item Global configuration via the contact manager,
  \app{pContactMgrV20}, or
\item Local configuration via individual behaviors in the helm.
\item A third configuration method, dealing with behaviors {\em after}
  they have been spawned, is discussed in Section \ref{sec_bhv_exfilt}.
\end{packed_itemize}

\vspace{0.05in}
\noindent
The former method is arguably more convenient but the filters apply
to all behavior templates equally. If the contact manager is
configured to ignore sailboats, there is no way to otherwise configure
the helm to have a spawnable behavior that will handle
sailboats. Maybe you really do want to just ignore all sailboats. But
if instead you'd like to have one type of behavior ignore sailboats
and another type of behavior ignore motorboats, then the filter needs
to be configured at the behavior level instead.

\vspace{0.1in}
\noindent
Figure \ref{fig_bhv_spawn2} below depicts a helm locally configured
with two distinct behavior templates, with the filter configuration
done in the helm configuration. In this way, one distinct behavior is
used for Contact Abe, and another for Contact Ben. It may be that both
are collision avoidance behaviors, but perhaps the safety region
around Abe is larger than Ben. Likewise the filter could have involved
the vehicle type, group or region.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.86\textwidth]{figures/bcm_helm_spawn2.png}
  \caption{{\bf Configuration of contact filter at the local behavior
      level}: Compare with Figure \ref{fig_bhv_spawn}, the match
    filters are provided in the helm configuration rather than the
    contact manager configuration. This allows different behavior
    types or templates to work with different contacts. In the
    previous example in Figure \ref{fig_bhv_spawn} every matched
    contact was handled by the same behavior type.}
\label{fig_bhv_spawn2}
\end{figure}

\vspace{0.1in}
\noindent
Using both global and local exclusion filters is certainly allowable,
but keep in mind that if a contact is excluded at the global contact
manager level, it does not matter what configurations are specified at
the local behavior level.

%-----------------------------------------------------------------------
\subsubsection{Enabling Strict Filtering}
\label{sec_cbhv_filters_strict}

Filtering based on the contact \var{type} or \var{group} depends on
this information being known about the contacts. Typically this is
embedded in each incoming \var{NODE\_REPORT}. In some cases,
especially in sensor-based contact management, this information may
not be known.

\vspace{0.1in}
\noindent
For {\em match} filtering, this is not an issue. This is because the
spirit of match filtering is that, for example if we say that a contact
must be of type motor-boat, and the contact type is unknown, it's pretty
clear that condition is not satisfied and thus the contact with unknown
type is filtered out.

\vspace{0.1in}
\noindent
With {\em ignore} filtering it is more ambiguous. This is because the
spirit of ignore filtering is that, for example if we say that a contact
cannot be of type motor-boat, and the contact type is unknown, we might
be inclined to say that it should not be filtered out. The user may however
want to be strict about this and say that it {\em should} be filtered out
since we don't know the contact type, and for all we know it could be
a motor-boat. 

\vspace{0.1in}
\noindent
To allow the user to have some control and be explicit about the above
situation, filtering can be configured to be {\em strict} by setting
\bvar{strict\_ignore} to be \var{true} or \var{false}. The below set of
examples hopefully makes this clear.


\vspace{0.15in}
\label{tab_strict}
\small
\renewcommand{\arraystretch}{1.15}
\begin{longtable}{|c|c|c|c|} 

  {\bf Contact Type} &amp; {\bf Ignore Group} &amp;  {\bf Strict Ignore} &amp; {\bf Filtered Out} \\  
  sailboat  &amp;   sailboat  &amp;  true or false  &amp; yes \\
  sailboat  &amp;   motorboat &amp;  true or false  &amp; no  \\
  unknown   &amp;   motorboat &amp;  false          &amp; no  \\
  unknown   &amp;   motorboat &amp;  true           &amp; yes \\
\end{longtable}
\normalsize

\noindent
The \bvar{strict\_ignore} parameter, as with other filtering
parameters, is also used in configuring the contact manager, applied globally
and overriding any local filter behavior configurations.

%-----------------------------------------------------------------------
\subsubsection{Failing an Exclusion Filter on Spawned Behavior}
\label{sec_bhv_exfilt}

The primary use of exclusion filters is to affect which behaviors are
spawned.  However, the configured criteria is based on the vehicle
properties of group, name, platform type and location, and these
properties may change {\em after} a behavior is spawned. Normally a
contact behavior does not complete, and exit, until it has gone out of
range. The user may also opt to have the behavior exit if its
properties change after spawning such that it no longer satisfies the
original exclusion filter.

\vspace{0.1in}
\noindent
A contact behavior will accept the following three configuration parameters:

\begin{packed_itemize}
\item \bvar{exit\_on\_filter\_group}: If true, will apply the current
  known group name to an exclusion filter.
\item \bvar{exit\_on\_filter\_vtype}: If true, will apply the current
  known vehicle to an exclusion filter.
\item \bvar{exit\_on\_filter\_region}: If true, will apply the current
  known vehicle position to the region component of an exclusion filter.
\end{packed_itemize}

\vspace{0.1in}
\noindent
The default for all parameters is false. A common example is when a
detected change of group name or vehicle type is learned via
communications or sensors.  A vehicle may also move into a region
where a behavior may be configured to be no longer concerned with a
contact. Failing the exclusion filter in a spawned behavior will
simply result in the exit/removal of the behavior from the helm, and
deletion of the behavior from memory space.

\vspace{0.1in}
\noindent
Unlike the group, vehicle type and region components of an exclusion
filter, the vehicle {\em name} component of the exclusion filter is
not re-assesed after a behavior has spawned, since contact behaviors
are essentially keyed by vehicle name.

\vspace{0.1in}
\noindent
While the above three parameters are supported by all contact
behaviors, not all contact behaviors respect this additional
feature. Currently (Aug 2021) only the collision avoidance behaviors
(CPA based and COLREGS based) support this feature. Support in additional
behaviors will be rolled in on future updates.


%==========================================================================
\subsection{Contact Flags}

Available after Release 19.8.1, {\em contact flags} are an additional
way to configure behaviors to post configurable information upon
events based on the relative position between ownship and the
contact. Most other types of behavior flags contain simply a variable
value pair.  For example:

\prevbhv
\begin{verbatim}
  endflag = RETURN = true
\end{verbatim}
\postverb

\noindent
Contact flags allow the user to check for expected results over the course
of a mission. It also allows missions to be configured on contact related
events such as posting a message to command-and-control or to another
vessel when the relative position or range to a contact has been achieved.

%==========================================================================
\subsubsection{Contact Flag Trigger Tags}

With contact flags, a {\em trigger tag} is included with the flag
configuration corresponding to certain events. For example, the
\bnivar{@cpa} trigger tag will ensure the configured flag will be
posted at the time of an observed CPA between ownship and the contact:

\prevbhv
\begin{verbatim}
  cnflag = @cpa SEND_MESSAGE = true
\end{verbatim}
\postverb

\noindent
The trigger tag is always at the beginning of the flag configuration
with at least one white space between the tag and the rest of the flag
configuration.  The trigger tags only apply to contact flags, for
contact behaviors, using the \bvar{cnflag} parameter.

\noindent
Supported trigger flags:

\vspace{0.15in}
%\label{tab_strict}
\small
\renewcommand{\arraystretch}{1.15}
\begin{longtable}{rl} 

  {\bf Trigger Flag} &amp; {\bf Meaning}  \\  
  \bnivar{@cpa}:  &amp; When the closes point of approach is observed \\
%  \bvar{@&lt; range} &amp; When the range crosses below \bvar{range} \\
%  \bvar{@&gt; range} &amp; When the range crosses above \bvar{range} \\
%  \bvar{&lt; range} &amp; Whenever the range is below \bvar{range} \\
%  \bvar{&gt; range} &amp; Whenever the range is above \bvar{range} \\
  \bnivar{@os\_passes\_cn}: &amp; When ownship passes contact's beam \\
  \bnivar{@os\_passes\_cn\_port} &amp; When ownship passes contact's port beam \\
  \bnivar{@os\_passes\_cn\_star}: &amp; When ownship passes contact's starboard beam \\
  \bnivar{@cn\_passes\_os} &amp; When ownship passes contact's beam \\
  \bnivar{@cn\_passes\_os\_port} &amp; When contact passes contact's port beam \\
  \bnivar{@cn\_passes\_os\_star} &amp; When contact passes contact's starboard beam \\
  \bnivar{@os\_crosses\_cn} &amp; When ownship crosses contact's side \\
  \bnivar{@os\_crosses\_cn\_bow} &amp; When ownship crosses contact's side fore of contact \\
  \bnivar{@os\_crosses\_cn\_stern} &amp; When ownship crosses contact's side aft of contact \\
  \bnivar{@cn\_crosses\_os} &amp; When contact crosses ownship's side \\
  \bnivar{@cn\_crosses\_os\_bow} &amp; When contact crosses ownship's side fore of ownship \\
  \bnivar{@cn\_crosses\_os\_stern} &amp; When contact crosses ownship's side aft of ownship \\

\end{longtable}
\normalsize

\vspace{0.1in}
\noindent
An example is given in Figure \ref{fig_cnflags} below of an encounter between ownship
and a contact. The relevant trigger tags are shown. 


\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.8\textwidth]{figures/cnflags.png}
  \caption{{\bf An example encounter with trigger tags}:
    As a contact passes ownship various trigger tags become satisfied. The first two
    trigger tags are based purely on range and are triggered as the vehicle enters
    the range. The last trigger tag is triggered as the contact opens range to 60.
    As the two vehicles pass, several trigger tags are satisfied simultaneously.}
\label{fig_cnflags}
\end{figure}

%==========================================================================
\subsubsection{Contact Flag Macros}

Contact flags have a number of supported macros that may be expanded
in any value component of a posting. For example, the range between
ownship and the contact can be used in a \bvar{cnflag} posting:

\prevbhv
\begin{verbatim}
  cnflag = @cpa RANGE_TO_CONTACT = $[RANGE]
\end{verbatim}
\postverb

\noindent
The value of \bnivar{\$[RANGE]} is determined at the moment the flag is triggered. 
Supported macros:

\vspace{0.15in}
%\label{tab_strict}
\small
\renewcommand{\arraystretch}{1.15}
\begin{longtable}{|r|l|} 

  {\bf MACROS} &amp; {\bf Meaning}  \\  
  \bnivar{\$[RANGE]}  &amp; Range between ownship and contact \\
  \bnivar{\$[CN\_NAME]}  &amp; Name of the contact \\
  \bnivar{\$[CN\_GROUP]}  &amp; Name of the contact \\
  \bnivar{\$[CN\_VTYPE]}  &amp; Vehicle type of the contact \\  
  \bnivar{\$[ROC]}  &amp; Rate of Closure between ownship and the contact \\  
  \bnivar{\$[OS\_CN\_REL\_BNG]}  &amp; Relative bearing of the contact to ownship \\  
  \bnivar{\$[CN\_OS\_REL\_BNG]}  &amp; Relative bearing of ownship to the contact \\  
  \bnivar{\$[BNG\_RATE]}  &amp; Bearing Rate \\  
  \bnivar{\$[CN\_SPD\_IN\_OS\_POS]} &amp; Speed of contact in the direction of ownship position \\  
  \bnivar{\$[OS\_FORE\_OF\_CN]} &amp; true if ownship is currently fore of the contact \\  
  \bnivar{\$[OS\_AFT\_OF\_CN]} &amp; true if ownship is currently aft of the contact \\  
  \bnivar{\$[OS\_PORT\_OF\_CN]} &amp; true if ownship is currently on port side of the contact \\  
  \bnivar{\$[OS\_STAR\_OF\_CN]} &amp; true if ownship is currently on starboard side of the contact \\  
  \bnivar{\$[CN\_FORE\_OF\_OS]} &amp; true if the contact is currently fore of ownship \\  
  \bnivar{\$[CN\_AFT\_OF\_OS]} &amp; true if the contact is currently aft of ownship \\  
  \bnivar{\$[CN\_PORT\_OF\_OS]} &amp; true if the contact is currently on port side of ownship \\  
  \bnivar{\$[CN\_STAR\_OF\_OS]} &amp; true if the contact is currently on starboard side of ownship \\  
\end{longtable}
\normalsize

%==========================================================================
\subsection{Properties Common to All Contact Related Behaviors}

Contact related behaviors are distinct from non contact related
behaviors in that they share a fair amount of functionality in dealing
with their contact of interest. Contact related behaviors are
implemented as a subclass of the \var{IvPContactBehavior} class, which
is a subclass of the \var{IvPBehavior} class. Much of the shared
functionality of contact related behaviors is implemented in the
former. The shared functionality includes several common configuration
parameters, and mechanisms for reasoning about the closest point of
approach (CPA) between the platform and contact for candidate maneuver
considerations. These topics are discussed next, prior to the sections
on the behaviors themselves.


%--------------------------------------------------------------------------
\subsubsection{Common Behavior Configuration Parameters}
\label{bhv_multi_common}

The following set of parameters are common to all the contact related
behaviors:

\input{bhv_contact_properties}

\label{bhv_param_contact}

\noindent
The \bvar{contact} parameter specifies the contact name or identifier.
This name is used as a key by the behaviors for querying the contact
position and trajectory. It must match the contact name received by
the helm in an incoming \mvar{NODE\_REPORT} message. The contact name
may be specified at helm launch time, but it may also be specified at
run time if the behavior is configured as a template for dynamic
spawning. The latter is more common, for example, in a collision
avoidance behavior where the name or ID of the contact is not known
until a contact manager alerts the helm. See the Berta mission for an
example of this usage.

\label{bhv_param_extrap}
\label{bhv_param_decay}

\vspace{0.1in}
\noindent
The \bvar{extrapolate} and \bvar{decay} parameters are used to address
the situation where a contact/node report has significant delays
between updates. Extrapolation is enabled by setting the
\bvar{extrapolate} parameter to \var{true}, which is the default. The
behavior may be configured to have limited extrapolation by setting a
decay time interval. The extrapolated position is based on the last
known contact position, heading and speed. The speed used for
calculations may begin decaying at the beginning of the decay interval
and will have decayed to zero at the end of the decay interval. The
default setting is \bsvar{"decay = 15, 30"}, in seconds. The idea is
shown in Figure \ref{fig_extrap}.


\vspace{0.15in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.85\textwidth]{figures/extrapolate.png}
  \caption{{\bf Contact Extrapolations:} Contact related behaviors may
    use an extrapolated position of the contact to compensate for
    periods of no new reports for the contact. A decay period may be
    used to effectively halt the extrapolated contact position after
    some specified period of time. In the example in this figure, the
    decay window is [15, 30] seconds. After 30 seconds, the
    extrapolated position does not extend further.}
\label{fig_extrap}
\end{figure}
\vspace{0.15in}

\label{bhv_param_no_contact_ok}

\vspace{0.1in}
\noindent
The \bvar{on\_no\_contact\_ok} parameter determines how the behavior
should regard the situation where it is unable to find any information
about a given contact. If this parameter is set to true, the
default, then the behavior will post a warning, \mvar{BHV\_WARNING} if
no contact information is found. Otherwise the behavior will post an
error with \mvar{BHV\_ERROR}. In the latter case the helm may interpret
this as request to halt the helm and come to zero speed and depth.

\vspace{0.1in}
\noindent
The \bvar{time\_on\_leg} parameter refers to the behavior's
calculations of the closest point of approach (CPA) for candidate
maneuver legs.  A candidate maneuver leg is defined by a the heading,
speed, and time-on-leg components. Longer time-on-leg settings tend to
report deceivingly worrisome CPA distances even for contacts at a
great distance, and lower time-on-leg settings tend to report
deceivingly comfortable CPA distances even for vehicles at relatively
low distances. The default setting for this parameter is 60 seconds.


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