<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{uFldCollisionDetect: Detecting Collisions}
\vspace{0.1in}
\labdate{June 2018}
\vspace{0.1in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Department of Mechanical Engineering}
\labauth{MIT, Cambridge MA 02139}
\labtoc{small}
\end{labcover}

\wikidoc{file=IvPTools.UFldCollisionDetect}
\wikidoc{bugz=uFldCollisionDetect}
\wikidoc{auth=mikerb@mit.edu}

%=================================================================
\section{Overview}
%=================================================================
\label{sec_ufld_collision_detect}
\index{uFldCollisionDetect}

The \app{uFldCollisionDetect} application is run on the shoreside and
monitors pairs of vehicles for encounters that come within a certain
range.  The closest point of approach (CPA) is noted when the range
between two vehicles transitions from closing to opening. Depending on
the CPA value, one of three events may be declared, either an {\em
  encounter}, a {\em near miss}, or a {\em collision}, depending on
user configured range parameters.

%=================================================================
\section{Using uFldCollisionDetect}
%=================================================================

\subsection{Setting the Range Thresholds for Events}
\label{sec_cd_ranges}

There are three range threshold parameters that may be set. The first,
\pvar{encounter\_range} is the CPA range beyond which two vehicles are
considered to be too far away to be regarded as having had an
encounter. Outside this range it's a non-event.

\vspace{0.1in}
\noindent
The second parameter, \pvar{near\_miss\_range}, determines a CPA range
within which an encounter is considered to be a near miss. Encounters
even closer, with the range specified by \pvar{collision\_range}, are
categorized as collisions.

\vspace{0.1in}
\noindent
The default values are:

\begin{packed_itemize}
\item \pvar{encounter\_range}\var{ = 20}
\item \pvar{near\_miss\_range}\var{ = 6}
\item \pvar{collision\_range}\var{ = 3}
\end{packed_itemize}

\vspace{0.1in}
\noindent
The following relationship between parameters will be enforced:
\vspace{0.1in}

   \pvar{encounter\_range} &gt;=   \pvar{near\_miss\_range} &gt;=  \pvar{collision\_range} 

\vspace{0.1in}
\noindent
If this ordering is not respected by the configuration parameters,
then the following happens upon startup: (1) If the
\pvar{near\_miss\_range} is smaller than the \pvar{collision\_range},
the former is adjusted upward to the latter. (2) If the
\pvar{encounter\_range} is less than the \pvar{near\_miss\_range},
then the former is adjusted upward to the latter. (3) A configuration
warning is generated and shown in the appcasting output.

\vspace{0.1in}
\noindent
Upon each encounter less than or equal to the \pvar{encounter\_range},
an encounter counter is internally incremented. Likewise for near
misses and collisions.  A collision encounter will not however also
increment the near miss counter.  These counters are maintained
globally for all vehicles, as seen in lines 17-19 in the example
appcasting output in Listing \ref{lst_cd_appcast}. They are also
maintained {\em per vehicle}, as seen in lines 21-29 in Listing
\ref{lst_cd_appcast}.


%=================================================================
\subsection{Setting Flags to be Posted Upon Events}
\label{sec_cd_flags}

Flags may be configured to be posted upon each event type - collision,
near-miss or encounter. These flags are simply MOOS variable and value
pairs like the flags in many other MOOS applications and helm
behaviors.  There are also macros available that can be filled in a
run-time. 

\noindent
The following are the available macros:

\begin{packed_itemize}
\item \var{\$V1}: The name of vehicle 1. 
\item \var{\$V2}: The name of vehicle 2. 
\item \var{\$UP\_V1}: The upper case name of vehicle 1. 
\item \var{\$UP\_V2}: The upper case name of vehicle 2. 
\item \var{\$IDX}: The number of total encounters 
\item \var{\$CPA}: The CPA range of the encounter 
\end{packed_itemize}

\noindent
Note these macros are available for expansion in the contents of the
published MOOS message. If the \var{\$CPA} or \var{\$IDX} macros are
used in isolation in the message, the message will post as a double,
not a string. All macros (except \var{\$CPA}) may also be used in the
naming of the MOOS variable. The following are all valid
configurations:

\vspace{0.1in}
\begin{fileverb}
near_miss_flag  = NEAR_MISS_$UP_V1 = $CPA
encounter_flag  = WARNING = Something happened between $V1 and $V2
collision_flag  = CRITICAL = collision between $UP_V1 and $UP_V2
\end{fileverb}



%=================================================================
\subsection{Applying a Logic Condition}
\label{sec_cd_logic}

Logic conditions may also be used for disabling/enabling the reporting
activities of \app{uFldCollisionDectect}. Variables involved in the conditions
are automatically subscribed for by \app{uFldCollisionDectect}. For example

\begin{fileverb}
  condition = COLLISION_DETECT=true
  condition = DEPLOY_ALL=true
\end{fileverb}

\noindent
If multiple conditions are specified, they must {\em all} be true for
application to actively report events.


%=================================================================
\subsection{Configuring Visual Range Pulses to be Generated}
\label{sec_cd_pulses}

Range pulses can be configured to show the user a visual signal that an
interaction has occurred.  The range pulse can be configured to change
both its range and duration using configuration parameters.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.45\textwidth]{figures/col_detect_range_pulse.png}
  \caption{{\bf Using Range Pulse with uFldCollisionDetect:} A range
    pulse is displayed in pMarineViewer with each detected interaction.}
\end{figure}
\vspace{0.1in}


%=================================================================
\subsection{Ignoring Collisions Between Certain Contacts}
\label{sec_cd_ignore}

In certain missions, it may be desirable to ignore encounters between
certain contacts. Perhaps we want to focus on a particular vehicle. Or
perhaps there are multiple contacts without collision avoidance
enabled (hopefully only in simulation). In any event, there are two
configuration parameters for \app{uFldCollisionDetect} that allow
certain encounters to be disregarded. The \pvar{ignore\_group}
parameter and the \pvar{reject\_group} parameter. Both parameters name
one or more vehicle {\em groups}.

\vspace{0.1in}
\noindent
\pvar{ignore\_group = commercial}

\noindent
\pvar{reject\_group = sailing,rowing}
\vspace{0.1in}

\noindent
For a vehicle in one of the {\em ignore} groups, encounters between
this vehicle and any other vehicle also in an ignore group, the
encounter will be disregarded. However, if the other vehicle is not in
an ignore or reject group, the encounter will be included in the
analysis. For a vehicle in one the {\em reject} groups, incoming node
reports for this vehicle are rejected on arrival. Any encounter with
this vehicle and any other vehicle will not be included in the
analysis.

\vspace{0.1in}

\noindent
An example is given in Figure \ref{fig_cd_ignore} below:

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.65\textwidth]{figures/ignore_groups.png}
  \caption{{\bf Filtering out encounters base on group:} An encounter
    is only analyzed if at least one of vehicles is not in an ignore group
    {\em and} both vehicles are not members of a reject group.}
\end{figure}
\label{fig_cd_ignore}
\vspace{0.1in}

\noindent
The group name for a vehicle comes from the incoming node report, and the
group name is set in the configuration of \app{pNodeReporter} for that
vehicle.

%=================================================================
\subsection{Posting Range Status Messages}
\label{sec_cd_status}

On each iteration of \app{uFldCollisionDetect}, the range between all pairs
of vehicles is noted. For that instant in time, the minimum range of all
ranges is also noted, and published in the variable:

\vspace{0.1in}
\noindent
\mvar{UCD\_CLOSEST\_RANGE}

\vspace{0.1in}
\noindent
This variable is only published when configured to do so:

\vspace{0.1in}
\noindent
\pvar{post\_closest\_range=true}

\vspace{0.1in}
\noindent
Additionally, the minimum range ever noted between any two vehicles is published
in the variable:

\vspace{0.1in}
\noindent
\mvar{UCD\_CLOSEST\_RANGE\_EVER}


%=================================================================
\section{Configuration Parameters for uFldCollisionDetect}
%=================================================================
\index{uFldCollisionDetect!Configuration Parameters}
\index{Configuration Parameters!uFldCollisionDetect}

The \app{uFldCollisionDetect} application may be configured with a
configuration block within a MOOS mission file, typically with a
\var{.moos} file suffix.  The following parameters are defined for
\app{uFldCollisionDetect}.

\vspace{0.15in}
\begin{listing}{Configuration Parameters for uFldCollisionDetect}
  \label{lst_cd_params}
  \renewcommand{\arraystretch}{1.1}
  \begin{longtable}{rp{0.7\textwidth}} 
     
    \pvar{collision\_flag}: &amp; A MOOS variable and value posted upon
    the detection of a collision. Section \ref{sec_cd_flags}. \\

    \pvar{collision\_range}: &amp; The inter-vehicle range, within which
    the CPA is regarded as a collision. Section
    \ref{sec_cd_ranges}.\\

    \pvar{condition}: &amp; A logic condition which if not evaluated to
    be true, the monitoring of collisions will not be conducted.
    Section \ref{sec_cd_logic}. \\

    \pvar{encounter\_flag}: &amp; A MOOS variable and value posted upon
    the detection of an encounter. Section \ref{sec_cd_flags}. \\

    \pvar{encounter\_range}: &amp; The inter-vehicle range, within which
    the CPA is considered to be an encounter. Section
    \ref{sec_cd_ranges}. \\

    \pvar{ignore\_group}: &amp; A comma-separated lists of group names.
    Encounters for vehicles in one of these groups will be ignored, if
    the other vehicle is also in one of these groups.  Section
    \ref{sec_cd_ignore}. \\

    \pvar{near\_miss\_flag}: &amp; A MOOS variable and value posted upon
    the detection of a near miss. Section \ref{sec_cd_flags}. \\

    \pvar{near\_miss\_range}: &amp; The inter-vehicle range, within which
    the CPA is regarded as a near miss. Section
    \ref{sec_cd_ranges}. \\

    \pvar{pulse\_duration}: &amp; Sets the duration of the visual range
    pulse posted. Default is 10 seconds. \ref{sec_cd_pulses}. \\

    \pvar{pulse\_range}:  &amp; Sets the range of the visual range pulse
    posted. Default is 20 meters. \ref{sec_cd_pulses}. \\

    \pvar{pulse\_render}: &amp; Determines if a visual range pulse will be
    posted on encounters. Default is true. Section
    \ref{sec_cd_pulses}. \\

    \pvar{reject\_group}: &amp; A comma-separated lists of group names.
    Encounters for vehicles in one of these groups will be completely
    disregarded, regardless of the group of the other vehicle.
    Section \ref{sec_cd_ignore}. \\

    \pvar{report\_all\_encounters}: &amp; If true, all encounters will be
    published in the \mvar{UCD\_REPORT}, not just near misses or
    collisions. The default is false. \\

  \end{longtable}
\end{listing}

%=================================================================
\subsection*{An Example MOOS Configuration Block}

An example MOOS configuration block is provided in Listing
\ref{lst_ufcd_econfig} below. This can also be obtained from a
terminal window with:

\vspace{0.1in}
\begin{consoleverb}
$ uFldCollisionDetect --example or -e
\end{consoleverb}
\vspace{0.1in}
	
\vspace{0.25in}
\begin{listing}{Example configuration of the uFldCollisionDetect application}
\label{lst_ufcd_econfig}
\footnotesize
\begin{verbatim}
=============================================================== 
uFldCollisionDetect Example MOOS Configuration                  
=============================================================== 
                                                                
ProcessConfig = uFldCollisionDetect                             
{                                                               
  AppTick   = 4                                                 
  CommsTick = 4                                                 
                                                                
  condition = DEPLOY_ALL = true                                 
                                                                
  encounter_flag = ENCOUNTER = $CPA                             
  collision_flag = COLLISION = $CPA                             
  near_miss_flag = NEAR_MISS = vname1=$V1,vname2=$V2,cpa=$CPA   
                                                                
  encounter_range = 10         // the default in meters       
  near_miss_range = 6          // the default in meters       
  collision_range = 3          // the default in meters       
                                                                
  ignore_group = alpha                                          
  reject_group = bravo                                          
                                                                
  pulse_render   = true         // default true                 
  pulse_range    = 20           // default is 20 meters         
  pulse_duration = 10           // default is 10 seconds        
                                                                
  report_all_encounters = true  // default is false    
}                                                      

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

%=================================================================
\section{Publications and Subscriptions for uFldCollisionDetect}
%=================================================================
\index{uFldCollisionDetect!Publications and Subscriptions}
\index{Publications and Subscriptions!uFldCollisionDetect}
\label{sec_cd_interface}

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

\vspace{0.1in}
\begin{consoleverb}
$ uFldCollisionDetect --interface or -i
\end{consoleverb}
\vspace{0.05in}
                             
%=================================================================
\subsection{Variables Published by uFldCollisionDetect}
\label{sec_cd_pubs}

The user may configure any number of postings (flags) to be generated upon
an encounter, near miss or collision. 

\begin{packed_itemize}[2]
\item \mvar{APPCAST}: Contains an appcast report identical to the
  terminal output. Reports are posted only in response to an appcast
  request messages.

\item \mvar{COLLISION\_DETECT\_PARAMS}: The values for
  \pvar{encounter\_range}, \pvar{near\_miss\_range}, and
  \pvar{collision\_range} are posted upon startup to other
  applications may use this information. For example:

\noindent
\mvar{COLLISION\_DETECT\_PARAMS}\var{="collision\_range=3,near\_miss\_range=6,encounter\_range=20"}

\vspace{0.12in}

\item \mvar{ENCOUNTER\_TOTAL}: Total number of encounters, within
  \pvar{encounter\_range}, regardless of CPA.

\item \mvar{UCD\_REPORT}: A report generated on each encounter showing
  which vehicles where involved and the CPA value. For example:

\noindent
\mvar{UCD\_REPORT}\var{="cpa=11.2,vname1=henry,vname2=gus,rank=near\_miss"}

\item \mvar{UCD\_CLOSEST\_RANGE}: If the \pvar{post\_closest\_range} parameter
  is set to true, this variable is published. The value is the minimum range
  between all currently monitored vehicles. 

\vspace{0.12in}

\item \mvar{VIEW\_RANGE\_PULSE}: A visual artifact generated upon an
  encounter centered at the mid-point between the two vehicles.
  
\end{packed_itemize}

%=================================================================
\subsection{Variables Subscribed for by uFldCollisionDetect}
\label{sec_cd_subs}

The \app{uFldCollisionDetect} application will subscribe for the following
variables:

\begin{packed_itemize}[2]
	
\item \mvar{APPCAST\_REQ}: A request to generate and post a new
  apppcast report, with reporting criteria, and expiration.

\item \mvar{NODE\_REPORT}: A report on a vehicle location and status.
	
\end{packed_itemize}

\noindent
Additionally, any variable used in a logic condition will also be 
subscribed for. See Section \ref{sec_cd_logic} for more on the use
of logic conditions.


%=================================================================
\subsection*{Command Line Usage of uFldCollisionDetect}
\label{sec_cd_cmdline}
\index{Command Line Usage!uFldCollisionDetect}
\index{uFldCollisionDetect!Command Line Usage}

The \app{uFldCollisionDetect} application is typically launched as a
part of a batch of processes by pAntler, but may also be launched from
the command line by the user.  To see command-line options enter the
following from the command-line:

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

\noindent
This will show the output shown below.

\vspace{0.1in}
\begin{consoleverb}
 Usage: uFldCollisionDetect file.moos [OPTIONS]                
                                                          
 Options:                                               
   --alias=&lt;ProcessName&gt;                                
       Launch uFldCollisionDetect with the given process    
       name rather than uFldCollisionDetect.                
   --example, -e                                        
       Display example MOOS configuration block         
   --help, -h                                           
       Display this help message.                       
   --interface, -i                                               
      Display MOOS publications and subscriptions.  
   --version,-v                                         
       Display the release version of uFldCollisionDetect.     
\end{consoleverb}


%=================================================================
\section{Terminal and AppCast Output}
%=================================================================
\label{sec_cd_appcast}

The \app{uFldCollisionDetect} application produces some useful
information to the terminal and identical content through
appcasting. An example is shown in Listing \ref{lst_cd_appcast}
below.  On line 2, the name of the local community, typically the
shoreside community, is listed on the left. On the right,
\var{"0/0(2769)} indicates there are no configuration or run warnings,
and the current iteration of \app{uFldCollisionDetect} is 2769. Lines
4-11 show the how the application was configured at launch time.

Lines 13-19 convey the the overall application state, whether or not
the application is actively assessing encounters (line 16), and the
total number of encounters, near missions and collisions (lines 17-19).

\vspace{0.2in}
\begin{listing}{Example terminal or appcast output for \app{uFldCollisionDetect}}
\label{lst_cd_appcast}
\footnotesize
\vspace{0.1in}
\begin{verbatim}
  1  ===================================================================
  2  uFldCollisionDetect shoreside                             0/0(2769)
  3  ===================================================================
  4  Configuration:                               
  5  ============================================ 
  6         encounter_dist: 30.00
  7         collision_dist: 8.00
  8         near_miss_dist: 12.00
  9     range_pulse_render: true
 10   range_pulse_duration: 30.00
 11      range_pulse_range: 20.00
 12  
 13  ============================================ 
 14  State Overall:                               
 15  ============================================ 
 16               Active: true
 17     Total Encounters: 19
 18    Total Near Misses: 0
 19     Total Collisions: 0
 20  
 21  ============================================ 
 22  State By Vehicle:                            
 23  ============================================ 
 24  Vehicle  Encounters  Near Misses  Collisions
 25  -------  ----------  -----------  ----------
 26  abe      9           0            0         
 27  ben      9           0            0         
 28  cal      10          0            0         
 29  deb      10          0            0         
 30  
 31  ===================================================================
 32  Most Recent Events (8):
 33  ===================================================================
 34  [806.84]: ben::deb, cpa=22.79
 35  [783.85]: abe::ben, cpa=18.26
 36  [757.90]: cal::deb, cpa=29.16
 37  [638.36]: cal::deb, cpa=27.73
 38  [629.30]: ben::deb, cpa=16.85
 39  [611.36]: ben::cal, cpa=28.97
 40  [583.23]: ben::deb, cpa=19.33
 41  [578.27]: abe::ben, cpa=17.02
\end{verbatim}
\end{listing}
\normalsize

\vspace{0.1in}
\noindent
The state is further broken down by vehicle in lines 21-29. The total
number of encounters, near misses and collisions per vehicle is shown.
In the final portion of the the appcast output are the 8 most recent
events. Each encounter is an event, and the cpa distance for is also
shown. 


\end{document}

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