<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">%=================================================================
\section{The alogcd Tool}
%=================================================================
\label{sec_alogcd}
%\index{alogcd!Overview}

The \app{alogcd} tool is a utility for scanning a given alog file and
tallying the number of encounters, near misses, and collisions. This
utility works under the assumption that another utility had been
running during the mission, and monitoring encounters, near misses and
collisions. It assumes that these three events were separately noted
with MOOS variables that also indicate the closest point of approach
(CPA) range for each event. And it also assumes that these three
variables were logged in the alog file.

The \app{alogcd} utility uses the MOOS variables \mvar{ENCOUNTER},
\mvar{NEAR\_MISS}, and \mvar{COLLISION}. For now, these three
variables are hard-coded in this utility. The \app{uFldCollisionDetect}
utility is one utility capable of generating this kind of output.
If there is collision to report, the report will also show the CPA value
for the worst collision encounter. 

\pskip
\noindent
An example run may produce output similar to:

\vspace{0.1in}
\begin{consoleverb}
 $ alogcd file.alog
  
 7,686 total alog file lines.
 
 =========================================
 Collision Report:                        
 =========================================
 Encounters:  27  (avg 16.93 m)
 Near Misses: 6  (avg 10.18 m)
 Collisions:  3  (avg 5.55 m)
 Collision Worst: 3.87
\end{consoleverb}
\vspace{0.1in}


%=================================================================
\subsection{Producing a Time-Stamped file of Collisions and Near Misses}
%\index{alogcd!Time Stamped File}

The near misses and collisions are the real events of interests, and
if the standard summary report is not enough, a time stamped list of
each near miss and collision may be written to a file, if the
\var{--tfile=filename} parameter is provided. For example, the six
near misses and three collisions reported above could be written to
file with:

\vspace{0.1in}
\begin{consoleverb}
 $ alogcd file.alog --tfile=myfile
 $ cat myfile
 69.149,COLLISION,5.17
 231.826,NEAR_MISS,9.41
 351.374,NEAR_MISS,10.33
 556.815,NEAR_MISS,10.35
 592.976,NEAR_MISS,9.69
 792.884,COLLISION,3.87
 1065.484,NEAR_MISS,11.51
 1129.862,COLLISION,7.61
 1275.018,NEAR_MISS,9.82
\end{consoleverb}
\vspace{0.1in}

\noindent
The first column is the timestamp from the alog file, the second column
is the type of encounter (near miss or collision), and the third column
is the CPA distance for that encounter.

%=================================================================
\subsection{The Terse Output Option}
%\index{alogcd!Terse Output}

For a super terse, one line report, use the following, which produces
the below output for the same alog file as in the example above:

\vspace{0.1in}
\begin{consoleverb}
 $ alogcd file.alog 
 27/6/3
\end{consoleverb}
\vspace{0.1in}

\noindent
27 encounters, 6 near misses, 3 collisions.

%=================================================================
\subsection{Command Line Return Values}

The ultimate terse output is none at all! In this case we're only
interested in the return value of \app{alogcd}. This can be used for
example in a shell script to launch a series of simulations, altering
the configuration parameters until no collisions are detected. The
following (integer) return values are implemented:

\begin{packed_itemize}
\item \var{[0]}: The alog file was found and readable, encounters were
  indeed reported, and no collisions were reported. The success
  condition.
\item \var{[1]}: The alog file was not found or it was not readable.
\item \var{[2]}: The alog file was indeed found and was readable, but
  sadly, collisions were reported.
\item \var{[3]}: The alog file was indeed found and was readable, and no
  collisions were reported, but no encounters were reported
  either. Something is amiss. Either the vehicles never even got close
  enough to each other to constitute an encounter, or a monitoring app
  like \app{uFldCollisionDetect} was not even running.
\end{packed_itemize}


%=================================================================
\subsection{Command Line Usage for the alogcd Tool}
%\index{alogcd!Command Line Usage}
%\index{Command Line Usage!alogcd}

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

\vspace{0.1in}
\begin{listing}{Command line usage for the \app{alogcd} tool}
\label{alogcd_usage}
\scriptsize
\begin{verbatim}
  1  $ alogcd -h
  2    
  3  Usage: 
  4    alogcd .alog [OPTIONS]                    
  5                                                         
  6  Synopsis:                                                
  7    Scan an alog file for collision detection reports.     
  8    Tally the totals and averages, and optionally create   
  9    a file holding all the timestamps of events.           
 10                                                           
 11    By default, it scans for events defined by postings    
 12    to the following three MOOS variables:                 
 13                                                           
 14    (1) COLLISION                                          
 15    (2) NEAR_MISS                                          
 16    (3) ENCOUNTER                                          
 17                                                           
 18  Options:                                                 
 19    -h,--help       Displays this help message             
 20    -v,--version    Display current release version        
 21    -t,--terse      Write terse output.                    
 22                                                           
 23  Returns:                                                 
 24    0 if alog file ok, encounters detected, no collisions. 
 25    1 if alog file not ok, unable to open.                 
 26    2 if alog ok, but collisions were detected             
 27    3 if alog ok, no collisions or encounters detected     
\end{verbatim}
\end{listing}
\normalsize

%=================================================================
\subsection{Planned additions to the alogcd Utility}
%\index{alogcd!Planned additions}

\begin{packed_itemize}

\item Allow the key MOOS variables to be provided as parameters, rather then
  fixed to \mvar{ENCOUNTER}, \mvar{NEAR\_MISS}, and \mvar{COLLISION}.

\item Support cmd line option like \var{--collision\_count} which produces
  the integer value of collision counts as the command line return value.
  Perhaps the same for \var{--near\_miss\_count} or \var{encounter\_count}.
  
\end{packed_itemize}

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