<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">%=====================================================================
\section{The AvdColregs Behavior}
%=====================================================================
\wikisec{grp=bhvmulti}
\wikisec{file=BehaviorAvdColregs, short=AvdColregs Behavior}
\label{bhv_avddcolregs}
\index{IvP Behaviors Implemented!\var{BHV\_AvdColregs}}
\index{AvdColregs Behavior}

The AvdColregs behavior will produce IvP objective functions designed
to avoid collisions (and near collisions) with another specified
vehicle, based on the protocol found in the US Coast Guard Collision
Regulations (COLREGS) \cite{colregs}. The IvP functions produced by
this behavior are defined over the domain of posssible heading and
speed choices. The utility assigned to a point in this domain (a
heading-speed pair) depends in part on the calculated closest point of
approach (CPA) between the candidate maneuver leg, and the contact leg
formed from the contact's position and trajectory. A further
user-defined utility function is applied to the CPA calculation for a
candidate maneuver.

\vspace{0.1in}
\noindent
{\bf Note}: This behavior is invoked as \var{BHV_AvdColregsV17} in mission 
files. The \var{m2_berta_detect} mission is an example simulation mission
for this behavior. Note finally that the configuration interface for this
behavior is very similar to \var{BHV_AvoidCollision}, even though the 
effects of the behavior are quite different. Documenation is evolving for 
this behavior. If you would like a more detail discussion of the algorithms
implementing the COLREGS behavior, please see MIT CSAIL TR-2017-09. As this
remains a very active area of research in this lab, further releases and 
documentation are expected later in 2017 and beyond. 

%=====================================================================
\subsection{Configuration Parameters}
\label{sec_avdcol_params}

\input{includes/bhv_all_properties}

\input{includes/bhv_contact_properties}

\vspace{0.15in}
\begin{listing}{Configuration Parameters for the AvdColregs Behavior}
\label{lst_bhv_avd_colregs}
\small
\renewcommand{\arraystretch}{1.15}
\begin{longtable}{rp{0.76\textwidth}} 

  {\bf Parameter} &amp; {\bf Description} \\  
  
  \bvar{completed\_dist}: &amp; Range to contact outside of which the 
  behavior completes and dies. \\  
  
  \bvar{max\_util\_cpa\_dist}: &amp; Range to contact outside which a
  considered maneuver will have max utility. Section
  \ref{sec_bhv_avdcol_cpa_params}. \\

  \bvar{giveway\_bow\_dist}: &amp; In the giveway consideration, when
  determining if ok to cross the contact's bow, this range to contact
  at time of crossing from contact's port to starboard, must be met in
  order for ownship to consider crossing the contac'ts bow. This is a
  new option in V19 of this vehavior. If left unspecified, it will
  revert to the criteria used in previous versions. \\

  \bvar{min\_util\_cpa\_dist}: &amp; Range to contact within which a
  considered maneuver will have min utility. Section
  \ref{sec_bhv_avdcol_cpa_params}. \\

  \bvar{no\_alert\_request}: &amp; If true will turn off automatic
  handshaking with the contact manager. Section
  \ref{sec_bhv_avdcol_alerts}. \\

  \bvar{pwt\_grade}: &amp; Grade of priority growth as the contact moves
  from the \bvar{pwt\_outer\_dist} to the
  \bvar{pwt\_inner\_dist}. Choices are \var{linear}, \var{quadratic},
  or \var{quasi}. Section \ref{sec_bhv_avdcol_pwt_params}. \\

  \bvar{pwt\_inner\_dist}: &amp; Range to contact within which the
  behavior has maximum priority weight. Section
  \ref{sec_bhv_avdcol_pwt_params}. \\

  \bvar{pwt\_outer\_dist}: &amp; Range to contact outside which the
  behavior has zero priority weight. Section
  \ref{sec_bhv_avdcol_pwt_params}. \\

  \bvar{refinery}: &amp; If true, the behavior will create an IvP Function
  using the refinery, using large pieces for plateau regions. This is
  a new feature after Release 19.8, and currently only is used in the
  CPA or in-extremis modes. The default is false.
\end{longtable}
\end{listing}
\normalsize


\vspace{0.15in}
\begin{listing}{Example Configuration Block}
\label{lst_bhv_avd_colregs_ex}

\begin{fileverb}
Behavior = BHV_AvdColregsV17
{
  // General Behavior Parameters
  // ---------------------------
  name         = avdcollision_                     // example
  pwt          = 200                               // example
  condition    = AVOID = true                      // example
  updates      = CONTACT_INFO                      // example
  endflag      = CONTACT_RESOLVED = $[CONTACT]     // example
  templating   = spawn                             // example


  // General Contact Behavior Parameters
  // -----------------------------------
      bearing_lines = white:0, green:0.65, yellow:0.8, red:1.0   // example

            contact = henry            // example
              decay = 15,30            // default (seconds)
        extrapolate = true             // default
   on_no_contact_ok = true             // default
        time_on_leg = 60               // default (seconds)


  // Parameters specific to this behavior
  // ------------------------------------
     completed_dist = 500              // default
  max_util_cpa_dist = 75               // default
  min_util_cpa_dist = 10               // default
   no_alert_request = false            // default
          pwt_grade = quasi            // default
     pwt_inner_dist = 50               // default
     pwt_outer_dist = 200              // default
}
\end{fileverb}
\end{listing}

%----------------------------------------------------------------------
\subsection{Variables Published}

The below MOOS variables will be published by the behavior during
normal operation, in addition to any configured flags. A variable
published by any behavior may be supressed or changed to a different
variable name using the \bvar{post\_mapping} configuration parameter
described in Section \ref{sec_bhv_post_mapping}.

\begin{packed_itemize}[2]

\item \mvar{BCM\_ALERT\_REQUEST}: A request to the contact manager
  specifying the conditions for contact alerts.
    
\item \mvar{CLOSING\_SPD\_AVD}: The current closing speed, in meters
  per second, to the contact.
    
\item \mvar{CONTACT\_RESOLVED}: Posted with contact name when the
  behavior completes and dies.

\item \mvar{RANGE\_AVD}: The current range, in meters, to the contact.

\item \mvar{VIEW\_SEGLIST}: A bearing line between ownship and the
  contact if configured for rendering.
\end{packed_itemize}

%=======================================================================
\subsection{Configuring and Using the AvdColregs Behavior}

The AvdColregs behavior produces an objective function based on
the relative positions and trajectories between the vehicle and a
given contact. The objective function is based on applying a utility 
to the calculated closest point of approach (CPA) for a candidate
maneuver. The user may configure a priority weight, but this weight
is typically degraded as a function of the range to the contact. The
behavior may be configured for avoidance with respect to a known 
contact, or it may be configured to spawn a new instance upon demand
as contacts present themselves.

%=======================================================================
\subsection{Automatic Requests for Contact Manager Alerts}
\label{sec_avdcol_alerts}

The collision avoidance behavior is most commonly configured as a {\em
  template}, meaning instances will not be spawned until an outside
event, i.e, posting to the MOOSDB, is received by the helm.
  This was discussed in detail in Section
\ref{sec_bhv_templates}.  The spawning event for the collision
avoidance behavior typically comes from the \app{pBasicContactMgr}
application. This app therefore needs to be informed, by the collision
avoidance behavior, of the desired conditions for generating
behavior-spawning alerts. This is done automatically upon helm startup
with a posting of the form:

\vspace{0.1in}
\begin{fileverb}
  BCM_ALERT_REQUEST = id=avd, var=CONTACT_INFO, val="name=$[VNAME] # contact=$[VNAME]",
                      alert_range=80, cpa_range=100
\end{fileverb}
\vspace{0.1in}


\noindent
The values for this posting are chosen as follows:

\begin{packed_itemize}[2]
\item The value from the \var{var} component, e.g.,
  \var{CONTACT\_INFO} in the example above, is the variable named in the 
  \bvar{updates} parameter for the behavior.

\item The value from the \var{alert\_range} component, e.g., 80 in the
  example above, is the value specified in the \bvar{pwt\_outer\_dist}
  parameter for the behavior. This is the range between ownship and contact
  beyond which the behavior assigns a priority weight of zero.

\item The value from the \var{alert\_range\_cpa} component, e.g., 100
  in the example above, is the value specified in the
  \bvar{completed\_dist} parameter for the behavior. This is the range
  between ownship and contact beyond which the behavior will initiate
  its own completion and de-instatiation.
\end{packed_itemize}

\noindent
If some other contact manager regime is being used other than
\app{pBasicContactMgr}, the above automatic posting is probably
harmless. However, if one really wants to disable this automatic
posting, it can be turned off by setting the configuration parameter
\bvar{no\_alert\_request} to true.

\pskip

Implementation note: One may wonder when or how the behavior can make
this automatic posting when the behavior is configured as a template.
An instance is never spawned until an alert is received, but the alert
parameters are posted by the behavior, creating a bit of a chicken or
the egg conundrum. The alert request is actually posted by an instance
of the behavior created ever so briefly at helm startup. At startup,
the helm creates instances of {\em all} behaviors, even templates, to
ensure the configuration parameters are correct. The ultimate
confirmation of behavior parameter correctness is obtained by a
behavior instance itself confirming each parameter. The helm will then
immediately, before its first iteration, delete any behaviors
temporarily created from template behaviors. During this brief startup
period, the helm will invoke the function \func{onHelmStart()} for all
behaviors. This function is defined at the IvPBehavior superclass
level just like \func{onRunState()}. In the case of the collision
avoidance behavior, this function is implemented to make the automatic
alert configuration posting to \mvar{BCM\_ALERT\_REQUEST}.


%=======================================================================
\subsection{Specifying the Priority Policy - the \bvar{pwt\_*\_dist} Parameters}
\label{sec_avdcol_pwt_params}

The AvdColregs behavior may be configured to increase its priority
as its range to the contact diminishes. The priority weight specified
in its configuration represents the {\em maximum} possible priority
applied to the behavior, presumably in close range to the contact. The
range at which this maximum priority applies is specified in the
\bvar{pwt\_inner\_dist} parameter. Likewise, the
\bvar{pwt\_outer\_dist} parameter specifies a range to the contact
where the priority weight becomes zero, regardless of the priority
weight specified in the configuration file. This relationship is shown
in Figure \ref{fig_avd_collide}.

\vspace{0.15in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=1.0\textwidth]{figs_bhvs/avoid_collision_pwt.png}
  \caption{{\bf Parameters for the BHV\_AvdColregs behavior:} The
    {\em ownship} vehicle is the platform running the helm. The range
    between the two vehicles affects whether the behavior is active
    and with what priority weight. Beyond the range specified by
    \bvar{pwt\_outer\_dist}, the behavior is not be active. Within
    the range of \bvar{pwt\_inner\_dist}, the behavior is active with
    100\% of its configured priority weight.}
  \label{fig_avd_collide}
\end{figure}
\vspace{0.15in}

By default, the priority weight decreases linearly between the two
depicted ranges. The \bvar{pwt\_grade} parameter allows the degradation
from maximum priority to zero priority to fall more steeply by setting
\bvar{pwt\_grade}\bsvar{=quadratric}.


%\small
%\begin{align*}
%  pwt(r) &amp;= \begin{cases}
%    0        &amp; r \geq r^+,  \\
%    P_{max}   &amp; r \leq r^-,  \\
%    P_{max} (\frac{3}{4}) &amp; otherwise 
%  \end{cases} \\
%\end{align*}
%\normalsize

%=======================================================================
\subsection{Associating Utility to CPA of Candidate Maneuvers}
\label{sec_avdcol_cpa_params}


\begin{itemize}
\item \bvar{min\_util\_cpa\_dist}: The distance (in meters) between
  ownship and the contact at the closest point of approach (CPA) for a
  candidate maneuver, below which the behavior treats the distance as
  it would an actual collision between the two vehicles.

\item \bvar{max\_util\_cpa\_dist}: The distance (in meters) between
  ownship and the contact at the closest point of approach (CPA) for a
  candidate maneuver, above which the behavior treats the distance as
  having the maximum utility.
\end{itemize}

\begin{figure}[H]
  \centering 
  \includegraphics[width=1.0\textwidth]{figs_bhvs/avoid_collision_cpa.png}
  \caption{Parameters for the BHV\_AvdColregs behavior. The {\em
      ownship} vehicle is the platform running the helm.  The
    \bvar{collision\_distance} is used when applying a utility metric
    to a calculated closest point of approach (CPA) for a candidate
    maneuver. A CPA less than or equal to the
    \bvar{collision\_distance} is treated as an actual collision with
    the lowest utility rating.}
\end{figure}

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