<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{uFldAnemo: Generation of Simulated Wind Measures}
\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}
\labtoc{small}
\end{labcover}

\wikidoc{file=IvPTools.UFldAnemo}
\wikidoc{bugz=uFldCollObDetect}
\wikidoc{auth=mikerb@mit.edu}

%=================================================================
\section{Overview}
%=================================================================
\label{sec_ufld_anemo}
\index{uFldAnemo}

The \app{uFldAnemo} app acts as simulated wind sensor. It is typically
launched on the shoreside to present wind conditions equally to all
vehicles. It may present wind speed/direction info to the vehicles
independent of vehicle or dependent on vehicle position (not yet
implemented). It is capable of presenting wind conditions by playing
back historical data ingested from a file with time-series data (not
yet implemented).  It is capable of presenting wind conditions with
error w.r.t. a ground truth condition. Presumably the vehicle helm
would receive the wind condtion with error, while the vehicle motion
simulator receives the the ground truth condition.

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.75\textwidth]{figures/ufld_anemo_concept.png}
  \caption{{\bf Simulated Anemometer}: The \app{uFldAnemo} app will
    provide wind speed and direction to any number of simulated
    vehicles. The data can be either (1) static, (2) changing based on
    any user-provided algorithm implementing variation and noise, or
    (3) played back from a time series historical data from in-field
    experiments or prior simulations.}
  \label{fig_ufld_anemo_concept}
\end{figure}
\vspace{0.1in}

\noindent
To be written

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.75\textwidth]{figures/ufld_anemo_topo.png}
  \caption{{\bf Simulated Anemometer}: The \app{uFldAnemo} app will
    provide wind speed and direction to any number of simulated
    vehicles. The data can be either (1) static, (2) changing based on
    any user-provided algorithm implementing variation and noise, or
    (3) played back from a time series historical data from in-field
    experiments or prior simulations.}
  \label{fig_ufld_anemo_concept}
\end{figure}
\vspace{0.1in}


%=================================================================
\section{Using uFldAnemo}
%=================================================================

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

There are three range threshold parameters that may be set. The first,
\pvar{encounter\_range} is the CPA range beyond which a vehicle and an
obstacle 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{ = 30}
\item \pvar{near\_miss\_range}\var{ = 10}
\item \pvar{collision\_range}\var{ = 5}
\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 and obstacles, as seen in lines 17-19 in the example
appcasting output in Listing \ref{lst_cod_appcast}. They are also
maintained {\em per vehicle}, as seen in lines 21-29 in Listing
\ref{lst_cod_appcast}.


%=================================================================
\subsection{Setting Flags to be Posted Upon Events}
\label{sec_cod_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 for the {\em variable} portion
of the flag:

\begin{packed_itemize}
\item \var{\$VNAME}: The name of vehicle involved in the encounter. 
\item \var{\$UP\_VNAME}: The uppercase name of the vehicle involved in the encounter. 
\item \var{\$ID}: The ID or label of the obstacle involved in the encounter. 
\end{packed_itemize}

\noindent
The following are the available macros for the {\em value} portion of
the flag:

\begin{packed_itemize}
\item \var{\$VNAME}: The name of vehicle involved in the encounter. 
\item \var{\$UP\_VNAME}: The uppercase name of the vehicle involved in the encounter. 
\item \var{\$ID}: The ID or label of the obstacle involved in the encounter. 
\item \var{\$ENC\_CNT}: The number of total encounters 
\item \var{\$MISS\_CNT}: The number of total near misses 
\item \var{\$COLL\_CNT}: The number of total collisions
\item \var{\$DIST}: The CPA range of the encounter
\item \var{\$CPA}: The CPA range of the encounter
\end{packed_itemize}

\noindent
If the \var{\$DIST}, \var{\$ENG\_CNT}, \var{\$COLL\_CNT}, or
\var{\$MISS\_CNT} macros are used in isolation in the message, the
message will post as a double, not a string. This allows certain
post-mission tools like \app{alogview} to generate time plots when
posted as a double.

\vspace{0.1in}
\begin{fileverb}
near_miss_flag  = NEAR_MISS_$UP_VNAME = $CPA
encounter_flag  = WARNING = Something happened between $VNAME and obstacle $ID
collision_flag  = CRITICAL = collision between $UP_VNAME and $ID
collision_flag  = $DIST
encounter_flag  = $ENC\_CNT
\end{fileverb}


%=================================================================
\section{Configuration Parameters for uFldCollObDetect}
%=================================================================
\index{uFldCollObDtected!Configuration Parameters}
\index{Configuration Parameters!uFldCollObDetect}

The \app{uFldCollObDetect} 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{uFldCollObDetect}.

\vspace{0.15in}
\begin{listing}{Configuration Parameters for uFldCollObDetect}
  \label{lst_cod_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 between a vehicle and an
    obstacle. Section \ref{sec_cod_flags}. \\

    \pvar{collision\_dist}: &amp; The distance, in meters, within which
    the CPA between a vehicle and an obstacle is regarded as a
    collision. The default is 5 meters. Section
    \ref{sec_cod_ranges}. \\

    \pvar{collision\_range}: &amp; Same as \pvar{collision\_dist}. \\

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

    \pvar{encounter\_dist}: &amp; The distance, in meters, within which
    the CPA between a vehicle and obstacle is considered to be an
    encounter. The default is 30 meters. Section
    \ref{sec_cod_ranges}. \\

    \pvar{encounter\_range}: &amp; Same as \pvar{encounter\_dist}. \\
    
    \pvar{near\_miss\_flag}: &amp; A MOOS variable and value posted upon
    the detection of a near miss between a vehicle and an
    obstacle. Section \ref{sec_cod_flags}. \\
    
    \pvar{near\_miss\_dist}: &amp; The distance, in meters, within which
    the CPA between a vehicle and an obstacle is regarded as a near
    miss. The default is 10 meters. Section \ref{sec_cod_ranges}. \\
    
    \pvar{near\_miss\_range}: &amp; The range, in meters, within which the
    CPA between a vehicle and an obstacle is regarded as a near
    miss. The default is 10 meters. Section \ref{sec_cod_ranges}. \\

    \pvar{near\_miss\_range}: &amp; Same as \pvar{near\_miss\_dist}. \\

  \end{longtable}
\end{listing}

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

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

\vspace{0.1in}
\begin{consoleverb}
$ uFldCollObDetect --example or -e
\end{consoleverb}
\vspace{0.1in}
	
\vspace{0.25in}
\begin{listing}{Example configuration of the uFldCollObDetect application}
\label{lst_cod_econfig}
\footnotesize
\begin{verbatim}
=============================================================== 
uFldCollObDetect Example MOOS Configuration                  
=============================================================== 
                                                                
ProcessConfig = uFldCollObDetect                             
{                                                               
  AppTick   = 4                                                 
  CommsTick = 4                                                 
                                                                
  encounter_flag = ENCOUNTER = $CPA                             
  collision_flag = COLLISION = $CPA                             
  near_miss_flag = NEAR_MISS = vname=$VNAME,obstacle=$ID,cpa=$CPA   
                                                                
  encounter_range = 30        // the default in meters       
  near_miss_range = 10        // the default in meters       
  collision_range = 5         // the default in meters       
}                                                      

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

%=================================================================
\section{Publications and Subscriptions for uFldCollObDetect}
%=================================================================
\index{uFldCollObDetect!Publications and Subscriptions}
\index{Publications and Subscriptions!uFldCollObDetect}
\label{sec_cod_interface}

The interface for \app{uFldCollObDetect}, 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}
$ uFldCollObDetect --interface or -i
\end{consoleverb}
\vspace{0.05in}
                             
%=================================================================
\subsection{Variables Published by uFldCollObDetect}
\label{sec_cod_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.

\end{packed_itemize}

%=================================================================
\subsection{Variables Subscribed for by uFldCollObDetect}
\label{sec_cod_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{KNOWN\_OBSTACLE}: Information about a known obstacle.
	
\item \mvar{NODE\_REPORT}: A report on a vehicle location and status.
	
\end{packed_itemize}

\noindent
Obstacle information typically comes from \app{uFldObstacleSim}.


%=================================================================
\subsection*{Command Line Usage of uFldCollObDetect}
\label{sec_cod_cmdline}
\index{Command Line Usage!uFldCollObDetect}
\index{uFldCollObDetect!Command Line Usage}

The \app{uFldCollObDetect} 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}
 $ uFldCollObDetect --help or -h
\end{consoleverb}

\noindent
This will show the output shown below.

\vspace{0.1in}
\begin{consoleverb}
 Usage: uFldCollObDetect 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_cod_appcast}

The \app{uFldCollObDetect} application produces some useful
information to the terminal and identical content through
appcasting. An example is shown in Listing \ref{lst_cod_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(2426)}
indicates there are no configuration or run warnings, and the current
iteration of \app{uFldCollObDetect} is 2426. Lines 4-9 show the
how the application was configured at launch time.

\vspace{0.1in}
\noindent
Lines 11-15 convey the the overall application state, the total number
of encounters, near missions and collisions (lines 12-14), and the
closest that any vehicle has come to any obstacle ever (line 15).

\vspace{0.1in}
\noindent
Lines 17-25 show the current state of each vehicle with respect to
each obstacle.  These distances will go lower as the vehicle closes on
an obstacle and then reset once the vehicle has cleared the obstacle.
Lines 27-32 show the minimum distance, per vehicle, during the
lifetime of the mission. Lines 35-43 show recent events, including
reacent postings configured by the user through its flags.


\vspace{0.2in}
\begin{listing}{Example terminal or appcast output for \app{uFldCollisionDetect}}
\label{lst_cod_appcast}
\footnotesize
\vspace{0.1in}
\begin{verbatim}
  1  ===================================================================
  2  uFldCollisionDetect shoreside                             0/0(2426)
  3  ===================================================================
  4  Configuration:                               
  5  ============================================ 
  6  Obstacles: 5
  7  Collision Dist: 1
  8  Near Miss Dist: 5
  9  Encounter Dist: 14
 10  ============================================
 11  State:                                      
 12  Total Encounters:  44
 13  Total Near Misses: 14
 14  Total Collisions:  0
 15  Global Min Dist:   2.5
 16  ============================================
 17  Min Distances (for current encounter):      
 18  ============================================
 19  obstacle  gilda  henry
 20  --------  -----  -----
 21  ob_0      14.7   14.6
 22  ob_1      14.2   14.4
 23  ob_2      14.9   14.9
 24  ob_3      14.8   14.6
 25  ob_4      14.6   14
 26  ============================================
 27  Min Distances (foe each vehicle, ever):     
 28  ============================================
 29  Vehicle  Min Dist Ever
 30  -------  -------------
 31  gilda    2.5
 32  henry    4.1
 33
 34  ===================================================================
 35  Most Recent Events (8):
 36  ===================================================================
 37  [1046.54]: OB_TOTAL_ENCOUNTERS=44
 38  [1046.54]: OB_TOTAL_NEAR_MISSES=14
 39  [1046.54]: OB_ENCOUNTER=2.52
 40  [1046.54]: OB_NEAR_MISS=2.52
 41  [1046.54]: OB_NEAR_MISS_FULL=vname=gilda,ob=ob_0,dist=2.52
 42  [1044.85]: OB_TOTAL_ENCOUNTERS=43
 43  [1044.85]: OB_TOTAL_NEAR_MISSES=13
\end{verbatim}
\end{listing}
\normalsize

\end{document}

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