<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{pEncircle: Decentralized Group Balancend Encircling}
\vspace{0.1in}
\labdate{Dec 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.PEncircle}
\wikidoc{bugz=pEncircle}
\wikidoc{auth=mikerb@mit.edu}

%=================================================================
\newpage
\section{Overview}
%=================================================================
\label{sec_pen}
\index{pEncircle}

The \app{pEncircle} app is designed to support a mission comprised of
a group of vehicles, each encircling a common point with a common
encircling radius. This output of this app will be a speed adjustment
recommendation to ownship based the distance between ownship and the
closest vehicle fore and aft of ownship on the circle.

\vspace{0.1in}
\noindent
This app assumes ownship is presently in an autonomy mode utilizing the
Loiter behavior, and there is presently a collision avoidance behavior
also actively ensuring against collisions between vehicles. 

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.8\textwidth]{figures/pencircle.png}
  \caption{{\bf Balanced Encircling}: Left: four vessels encircling a
    common point with common radius, but with unequal spacing between
    vehicles. Right: four vessels encircling a common point and common
    radius with equal spacing between vehicles.}
  \label{fig_pencircle}
\end{figure}
\vspace{0.1in}


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

The following parameters are defined for \app{pEncircle}. A more
detailed description is provided in other parts of this
section. Parameters having default values are indicated.

\vspace{0.15in}
\begin{listing}{Configuration Parameters for \app{pEncircle}}
\label{lst_params_umwatch}
\renewcommand{\arraystretch}{1.1}
\begin{longtable}{rp{0.75\textwidth}} 

  \pvar{alert\_range}: &amp; The range in meters, between ownship and an
  obstacle, that an alert will be triggered.  Section
  \ref{sec_obmgr_alert}. \\

  \pvar{ignore\_range}: &amp; The range in meters, between an incoming
  point (tracked feature) and ownship, beyond which the point will
  be ignored. \\

  \pvar{lasso}: &amp; If \var{true}, the polygon associated with each
  cluster will be firmly set to a circular polygon of a set radius and
  set number of vertices. The default is \var{false}. Section
  \ref{sec_obmgr_pts}. \\

  \pvar{lasso\_points}: &amp; The number of points used in the regular
  polygon representing the obstacle, if the \pvar{lasso} parameter is
  set to \var{true}. The default is 6, a hexagon.
  Section \ref{sec_obmgr_pts}. \\

  \pvar{lasso\_radius}: &amp; The radius (distance to any vertex) used in
  the regular polygon representing the obstacle, if the \pvar{lasso}
  parameter is set to \var{true}. The default is 5 meters. Section
  \ref{sec_obmgr_pts}. \\

  \pvar{max\_age\_per\_point}: &amp; The maximum number of seconds that a
  point (tracked feature) will be retained in memory. Beyond this
  number, points will be dropped.  The default is $20$ seconds.
  Section \ref{sec_obmgr_moving}. \\
  
  \pvar{max\_pts\_per\_cluster}: &amp; The maximum number of points
  (tracked features) retained in memory per cluster (points having the
  same label). Beyond this number, oldest points will be dropped.
  The default is $20$ points. Section \ref{sec_obmgr_moving}. \\

  \pvar{point\_var}: &amp; The name of the MOOS variable to looked
  for tracked features. The default is \mvar{TRACKED\_FEATURE}.
  Section \ref{sec_obmgr_pts}. \\

  \pvar{obstacles\_color}: &amp; When the obstacle manager is rendering
  obstacles (\pvar{post\_view\_polys} is \var{true}), this parameter
  will set the obstacle color. The default value is \var{blue}. \\

  \pvar{poly\_label\_thresh}: &amp; When the number of obstacle polygons
  is greater than this parameter, the view polylgons will be published
  with a label color of \var{invisible}, resulting in less work for
  the \app{pMarineViewer}. The default is $25$. This is solely to
  help boost performance of \app{pMarineViewer} in extreme uses
  cases of very large numbers of obstacles and high time warp, and
  possibly slower machines. It does not affect the function of the
  obstacle manager in any other way. \\
  
  \pvar{poly\_shade\_thresh}: &amp; When the number of obstacle polygons
  is greater than this parameter, the view polylgons will be published
  with a shade (fill) color of \var{invisible}, resulting in less work
  for the \app{pMarineViewer}. The default is $100$. This is solely to
  help boost performance of \app{pMarineViewer} in extreme uses cases
  of very large numbers of obstacles and high time warp, and possibly
  slower machines. It does not affect the function of the obstacle
  manager in any other way. \\
  
  \pvar{poly\_vertex\_thresh}: &amp; When the number of obstacle polygons
  is greater than this parameter, the view polylgons will be published
  with a vertex size of zero, resulting in less work for the
  \app{pMarineViewer} by only rendering the polygon edges, without the
  vertices. The default is $150$. This is solely to help boost
  performance of \app{pMarineViewer} in extreme uses cases of very
  large numbers of obstacles and high time warp, and possibly slower
  machines. It does not affect the function of the obstacle manager in
  any other way. \\

  \pvar{post\_dist\_to\_polys}: &amp; Legal values are \var{true},
  \var{false}, or \var{close}. If \var{true}, the distance from
  ownship to an obstacle is published for each obstacle, to the
  variable \mvar{OBM\_DIST\_TO\_OBJ}. When set to \var{close}, these
  publications only occur when the obstacle is closer than
  \pvar{alert\_range}.  When \var{false}, these postings are turned of
  completely. The default is \var{close}. \\
  
  \pvar{post\_view\_polys}: &amp; When \var{true}, the obstacle polygons
  are published published by the obstacle manager. Normally this is
  redundant since the obstacles are also published by the obstacle
  avoidance behavior and the obstacle simulator. Legal values are
  \var{true} and \var{false}. The default is \var{false}. \\
  
\end{longtable}
\end{listing}
  

%=================================================================
\subsection{An Example MOOS Configuration Block}
\label{sec_obmgr_config_block}

To see an example MOOS configuration block, enter the following from
the command-line:

\vspace{0.15in}
\noindent
\begin{consoleverb}
 $ pBasicContactMgr --example or -e
\end{consoleverb}
\vspace{0.15in}

\noindent
This will show the output shown in Listing \ref{lst_obmgr_econfig} below.

\vspace{0.1in}
\begin{listing}{A Simple \app{pEncircle} Example}
\label{lst_obmgr_econfig}
\footnotesize
\begin{verbatim}
 1  =============================================================== 
 2  pEncircle Example MOOS Configuration                         
 3  =============================================================== 
 4                                                                  
 5  ProcessConfig = pEncircle                                    
 6  {                                                               
 7    AppTick   = 4                                                 
 8    CommsTick = 4                                                 
 9                                                                  
10    point_var = TRACKED_FEATURE  // default is TRACKED_FEATURE    
11                                                                  
12    given_obstacle = pts={90.2,-80.4:...:85.4,-80.4},label=ob_23  
13                                                                  
14    post_dist_to_polys = true  // true, false or (close)          
15    post_view_polys = true     // (true) or false or              
16                                                                  
17    max_pts_per_cluster = 20   // default is 20                   
18    max_age_per_point   = 20   // (secs)  default is 20           
19                                                                  
20    alert_range  = 20          // (meters) default is 20          
21    ignore_range = -1          // (meters) default is -1, (off)   
22                                                                  
23    lasso = true               // default is false                
24    lasso_points = 6           // default is 6                    
25    lasso_radius = 5           // (meters) default is 5           
26                                                                  
27    obstacles_color = color    // default is blue                 
28                                                                  
29    // To squeeze more viewer effic when large # of obstacles:    
30    poly_label_thresh = 25     // Set label color=off if amt&gt;25   
31    poly_shade_thresh = 100    // Set shade color=off if amt&gt;100  
32    poly_vertex_thresh = 150   // Set vertex size=0 if amt&gt;150    
33  }                                                               
\end{verbatim}
\end{listing}
\normalsize

%=================================================================
\section{Publications and Subscriptions of pEncircle}
%=================================================================
\index{pEncircle!Publications and Subscriptions}
\index{Publications and Subscriptions!pEncircle}
\label{sec_obmgr_interface}

The interface for \app{pEncircle}, 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}
 $ pEncircle --interface or -i
\end{consoleverb}
\vspace{0.05in}

%=================================================================
\subsection{Variables Published by pEncircle}
\label{sec_obmgr_pubs}

The output of \app{pEncircle} is: 

\begin{packed_itemize}[2]
\item \mvar{APPCAST}: Contains an appcast report identical to the
  terminal output. Appcasts are posted only after an appcast request
  is received from an appcast viewing utility. 

\item \mvar{[ALERT\_VAR]}: The obstacle manager will publish alerts
  through a variable specified in an alert configuration, via the
  incoming \mvar{OBM\_ALERT\_REQUEST} message. See Section
  \ref{sec_obmgr_alert}.

\item \mvar{VIEW\_POLYGON}: The polygon representing the obstacle is
  posted in this variable. It is re-published when/if the shape or
  location changes, or upon ownship approaching within range of the
  obstacle.

\item \mvar{OBM\_DIST\_TO\_OBJ}: For each object retained in the
  object manager's memory, object manager will continually post the
  distance from ownship to the obstacle, in meters. This posting can
  disabled by setting the \pvar{post\_dist\_to\_polys} to \var{false}.
  By default it is enabled.

\item \mvar{OBM\_CONNECT}: Upon successful launch of the obstacle
  manager, this variable is posted. It helps coordinate with the
  obstacle simulator which may be running on the shoreside and may
  have already published obstacle information. Upon receipt of this
  posting, the obstacle simulator will refresh the postings.

\item \mvar{OBM\_MIN\_DIST\_EVER}: The obstacle manager uses its
  knowlege of all obstacle locations and ownship location and keeps
  track of the closest that an obstacle has ever come to ownship. This
  minimum distance, and the id of the obstacle, are posted to this
  variable.

\item \mvar{OBM\_RESOLVED}: When an obstacle is removed from the
  obstacle manager, a notice is posted containing just the id of the
  removed obstacle. This may be used by the obstacle avoidance
  behavior in the helm to let it know that this obstacle no longer
  exists. Section \ref{sec_obmgr_rm}.
  
\end{packed_itemize}

\noindent
The obstacle manager will also publish to whatever MOOS variables are
specified in the obstacle alerts. See Section \ref{sec_obmgr_alerts}.


%=================================================================
\subsection{Variables Subscribed for by pEncircle}
\label{sec_obmgr_subs}

The \app{pEncircle} application will subscribe for the following
four MOOS 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}: The position of other vehicles in the group

\item \mvar{NODE\_REPORT\_LOCAL}: The position of ownship

\item \mvar{ENCIRCLE\_POSITION}: The position and radius of the circle. 

\item \mvar{ENCIRCLE\_AGGRESSION}: 

\item \mvar{ENCIRCLE\_MAXSPEED}: 

\item \mvar{ENCIRCLE\_GRP\_SPEED}: 

\item \mvar{ENCIRCLE\_ACTIVE}: 

\end{packed_itemize}


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

The \app{pEncircle} application produces some useful information to
the terminal on every iteration of the application. An example is
shown in Listing \ref{lst_obmgr_appcast} below. This application is
also appcast enabled, meaning its reports are published to the MOOSDB
and viewable from any \app{uMAC} application or
\app{pMarineViewer}. The counter on the end of line 2 is incremented
on each iteration of \app{pEncircle}, and serves a bit as a
heartbeat indicator.  The \var{"0/0"} also on line 2 indicates there
are no configuration or run warnings detected.

\pskip

\noindent
The output in the below example comes from the
\var{s1\_alpha\_obstacles} mission.

\vspace{0.1in}
\begin{listing}{Example terminal or appcast output for \app{pEncircle}}
\label{lst_obmgr_appcast}
\footnotesize
\begin{verbatim}
 1  ===================================================================
 2  pEncircle alpha                                         0/0(238)
 3  ===================================================================
 4  Configuration (point handling):             
 5    point_var:    TRACKED_FEATURE
 6    max_pts_per_cluster: 50
 7    max_age_per_point:   60
 8    ignore_range:        40
 9  Configuration (alerts):                     
10    alert_var:   OBSTACLE_ALERT
11    alert_name:  avoid_obstacle_
12    alert_range: 19
13  Configuration (lasso option):               
14    lasso:        true
15    lasso_points: 8
16    lasso_radius: 6
17  ============================================
18  State:                                      
19    Nav Position:      (61,-129.7)
20    Points Received:   58
21    Points Invalid:    0
22    Points Ignored:    147
23    Polygon obstacles: 4
24    Clusters:          4
25    Clusters released: 0
26  
27  ObstacleKey  Points  HullSize  Updates
28  -----------  ------  --------  -------
29  b            14      8         n/a    
30  c            16      8         55     
31  d            13      8         23     
32  e            11      8         46    
\end{verbatim}
\end{listing}
\normalsize
\vspace{0.1in}

\noindent
The first group of lines (4-16) show the configuration settings for
\app{pEncircle}.  The status of \app{pEncircle} is shown in
Lines 18-32.

%=================================================================
\section{Simple Example Missions}
%=================================================================
\label{sec_pen_missions}

As of Release 19.8, there are two example missions using the
obstacle manager.

\begin{packed_itemize}
\item \var{s1\_alpha\_obstaclemgr}: A single vehicle mission with
  obstacles generate by a stream of points.
\item \var{m2\_berta\_obstacles}: A two vehicle mission with obstacles
  given at fixed locations.
\end{packed_itemize}

\end{document}


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