<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">%=====================================================================
\section{The OpRegion Behavior}
%=====================================================================
%\wikisec{grp=bhvsolo, file=BehaviorOpRegion,short=OpRegion Behavior}
%\index{OpRegion Behavior}
\label{bhv_opregion}

This behavior provides four different types of safety functionality,
(a) a boundary box given by a convex polygon in the x-y or lat-lon
plane, (b) an overall timeout, (c) a depth limit, (d) an altitude
limit. The behavior does not produce an objective function to
influence the vehicle to avoid violating these safety constraints.
This behavior merely monitors the constraints and posts an error which
results in the posting of all-stop commands, which could  put the vehicle into
the \var{PARK} state if the helm is configured with \pvar{park\_on\_allstop} is 
set to true. More on this parameter can be found in Section \ref{sec_allstop}.

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

\input{includes/bhv_all_properties}

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

  {\bf Parameter}: &amp; {\bf Description} \\  

  \bvar{breached\_altitude\_flag}: &amp; A MOOS variable-value pair to be
  posted when or if the vehicle breaches the altitude limit set by
  this behavior.  New with Release 14.7.1. Section
  \ref{sec_bhvop_bflags}. \\

  \bvar{breached\_depth\_flag}: &amp; A MOOS variable-value pair to be
  posted when or if the vehicle breaches the depth limit set by
  this behavior. New with Release 14.7.1. Section
  \ref{sec_bhvop_bflags}. \\

  \bvar{breached\_poly\_flag}: &amp; A MOOS variable-value pair to be
  posted when or if the vehicle breaches the convex polygon op area
  limit set by this behavior. New with Release 14.7.1. Section
  \ref{sec_bhvop_bflags}. \\

  \bvar{breached\_time\_flag}: &amp; A MOOS variable-value pair to be
  posted when or if the vehicle breaches the time limit set by
  this behavior. New with Release 14.7.1. Section
  \ref{sec_bhvop_bflags}. \\

  \bvar{max\_time}: &amp; The max allowable time in seconds.  
  Section \ref{sec_safety_limits}. \\ 
  
  \bvar{max\_depth}: &amp; The max allowable depth in meters. 
  Section \ref{sec_safety_limits}. \\ 
  
  \bvar{min\_altitude}: &amp; The min allowable altitude in meters.  
  Section \ref{sec_safety_limits}.  \\ 
  
  \bvar{opregion\_poly\_var}: &amp; The name of a MOOS variable to which the 
  polygon points will be posted. By default is empty, meany no such post
  is made. \\

  \bvar{polygon}: &amp; The lat-lon area the vehicle is restricted
  to stay within. Section \ref{sec_bhvop_area}. \\ 

  \bvar{reset\_var}: &amp; A MOOS variable to allow behavior reset
  when or if the behavior is breached. New with Release 14.7.1.
  Section \ref{sec_bhvop_reset}. \\ 
 
  \bvar{time\_remaining\_var}: &amp; A MOOS variable to publish the remaining
  time left if \bvar{max\_time} is specified. If this variable is specified, 
  but the maximum time is not enforced, then it will publish with a value
  of -1. New with Release 14.7.1. \\
 
  \bvar{trigger\_entry\_time}: &amp; The time required for the vehicle 
  to have been within the polygon region before triggering the 
  polygon requirement. Section \ref{sec_bhvop_area}. \\ 
  
  \bvar{trigger\_exit\_time}: &amp; The time required to have been 
  outside the polygon before declaring a polygon containment 
  failure.  Section \ref{sec_bhvop_area}. \\
  
  \bvar{visual\_hints}: &amp; Hints for visual properties in variables
  posted intended for rendering. \\ 
  
\end{longtable}
\end{listing}
\normalsize

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

\begin{fileverb}
Behavior = BHV_OpRegion
{
  // General Behavior Parameters
  // ---------------------------
  name         = op_region                 // example
  pwt          = 100                       // default
  condition    = SAFETY=true               // example
  updates      = OPREGION_UPDATES          // example

  // Parameters specific to this behavior
  // ------------------------------------
                 max_time = 0              // default (seconds)
                max_depth = 0              // default (meters)
             min_altitude = 0              // default (meters)
                reset_var = OPREGION_RESET // example
       trigger_entry_time = 1              // default (seconds)
        trigger_exit_time = 0.5            // default (seconds) 

                  polygon = pts={-80,-50:-30,-175:150,-100:95,25}, label=area_x

   breached_altitude_flag = SAY_MOOS = Sir, the min altitude has been excceded
      breached_depth_flag = SAY_MOOS = Sir, the max depth has been excceded
       breached_poly_flag = SAY_MOOS = Sir, the op region has been violated
       breached_time_flag = SAY_MOOS = Sir, the maximum mission time has been exceeded

             visual_hints = vertex_color = brown  // default
             visual_hints = vertex_size  = 3      // default
             visual_hints = edge_color   = aqua   // default
             visual_hints = edge_size    = 1      // 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{OPREG\_TRAJECTORY\_PERIM\_DIST}: Distance, in meters, to the 
    perimeter on the current trajectory. 
    
  \item \mvar{OPREG\_TRAJECTORY\_PERIM\_ETA}: Time to the
    perimiter on the current speed and trajectory. 
    
  \item \mvar{OPREG\_ABSOLUTE\_PERIM\_DIST}: Distance, in meters, to the 
    op-region in any direction. 
    
  \item \mvar{OPREG\_ABSOLUTE\_PERIM\_ETA}: Time to the op-region perimeter
    at current speed in any direction. 
    
  \item \mvar{OPREG\_TIME\_REMAINING}: Time, in seconds, until the 
    \bvar{max\_time} upper bound is exceeded. 

  \item \mvar{VIEW\_POLYGON}: A visual cue for rendering the polygon 
    containment region.
\end{packed_itemize}


%=======================================================================
\subsection{Safety Checking Applied to an Operation Region}
\label{sec_bhvop_area}

One safety check performed by the OpRegion behavior is to ensure that
the vehicle remains in an operation region defined by a convex polygon
in the x-y plane.

\vspace{0.15in}

\begin{itemize}

\item \bvar{polygon}: A colon separated list of x,y pairs given as
  points in space, typically meters. A pair given by "label,string"
  can associate an optional label with the point list. {\em The
    collection of points must be a convex polygon.} A check for
  convexity is done upon helm/behavior start-up. Behavior
  initialization will fail if it is not convex. If no polygon is
  provided, no X,Y checks are made.

\item \bvar{trigger\_entry\_time}: The amount of time required for the
  vehicle to have been within the polygon containment region before
  triggering the polygon containment requirement.  This is useful when
  launching vehicles from a dock structure such as the MIT Sailing
  Pavilion. The default setting is zero meaning the polygon
  containment requirement is active immediately.

\item \bvar{trigger\_exit\_time}: The amount of time required to have
  been outside the polygon containment region before declaring a
  polygon containment failure. This is useful if the vehicle
  \mvar{NAV\_X} and \mvar{NAV\_Y} position is based on a sensor
  without outlier detection. The kayaks, for example, are often
  relying solely on GPS which occasionally emits an outlier well out
  of the containment region. By setting this value high enough,
  outliers are ignored. Each time a recorded position is contained
  within the polygon region, the clock is set to zero. The default
  setting is zero, meaning the very first detection outside the
  polygon will result in a polygon containment error.

\end{itemize}

%=======================================================================
\subsection{Safety Limits on Operation Time, Depth, and Vehicle Altitude}
\label{sec_safety_limits}

\begin{itemize}

\item \bvar{max\_time}: The maximum allowable time (in seconds) that
  the helm is allowed to run. The clock starts when the pHelmIvP
  process first takes control, i.e., enters the \var{DRIVE} state. If
  no maximum time is specified, then no time checks are made.

\item \bvar{max\_depth}: The maximum allowable depth of the vehicle
  (in meters).  If no depth is provided, no depth checks are made.

\item \bvar{min\_altitude}: The minimum allowable altitude of the
  vehicle (in meters).  If no altitude is provided, no altitude checks
  are made.

\end{itemize}

%=======================================================================
\subsection{Variables Published by the OpRegion Behavior}

The behavior also produces a set of status variables regarding the
vehicle position with respect to the containment region. Since a
violation of this constraint results in a vehicle full-stop and the
helm relinquishing control, other behaviors or MOOS processes may want
to take measures to avoid it. These status variables provide
information on the position and estimated time between the vehicle and
the perimeter, based both on the absolute position as well as the
current vehicle trajectory. See Figure \ref{opregion_fig}.

\vspace{0.2in}

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.9\textwidth]{figures/bhv_opreg.png}
  \caption{{\bf The OpRegion polygon and status variables:} The
    OpRegion behavior publishes information regarding its estimated
    distance and time of arrival (ETA) to the perimeter of the polygon
    containment region. It publishes two sets of information; one
    based on the current trajectory and the other based on the
    absolute distance to the perimeter at top vehicle speed.}
\label{opregion_fig}
\end{figure}

\vspace{0.2in}

\noindent
The four variables produced by the behavior (and posted to the MOOSDB
by the Helm) are:

\begin{itemize}

\item \mvar{OPREG\_TRAJECTORY\_PERIM\_DIST}: The distance (in meters)
  between the current vehicle position to the perimeter of the polygon
  containment region (given by the \bvar{polygon} parameter), based on
  the vehicle remaining on the current trajectory.

\item \mvar{OPREG\_TRAJECTORY\_PERIM\_ETA}: The amount of time (in
  seconds) needed for the vehicle to reach the perimeter of the
  polygon containment region (given by the \bvar{polygon} parameter),
  based on the vehicle remaining on the current trajectory.

\item \mvar{OPREG\_ABSOLUTE\_PERIM\_DIST}: The distance (in meters)
  between the current vehicle position to the perimeter of the polygon
  containment region (given by the \bvar{polygon} parameter),
  regardless of the current vehicle trajectory.

\item \mvar{OPREG\_ABSOLUTE\_PERIM\_ETA}: The amount of time (in
  seconds) needed for the vehicle to reach the perimeter of the
  polygon containment region (given by the \bvar{polygon} parameter),
  regardless of the current vehicle trajectory. Calculated on the
  maximum vehicle speed.

\end{itemize}

%===================================================================
\subsection{Publishing Breach Flags}
\label{sec_bhvop_bflags}

The behavior may be configured with four different types of {\em breach flags}:

\begin{packed_itemize}
\item The \bvar{breached\_altitude\_flag} names a MOOS variable-value pair to be
posted when or if the minimum altitude (if set) is exceeded.

\item The \bvar{breached\_depth\_flag} names a MOOS variable-value pair to be
posted when or if the maximum depth (if set) is exceeded.

\item The \bvar{breached\_poly\_flag} names a MOOS variable-value pair
  to be posted when or if the vehicle exits the polygon containment
  area (if set).

\item The \bvar{breached\_time\_flag} names a MOOS variable-value pair
  to be posted when or if the maximum mission time (if set) is exceeded.
\end{packed_itemize}

\noindent
Each type of flag may be configured with more than one posting using separate
lines in the configuration block. The flags are posted {\em once} upon the 
initial breach, but may be posted again later if the behavior is re-set and 
the breach re-occurrs.

%===================================================================
\subsection{Resetting a Breach Condition}
\label{sec_bhvop_reset}

The behavior may be configured to accept a reset after one of the breach
conditions occur. This is done by naming a MOOS variable using the 
\bvar{reset\_var} parameter. Upon receipt of this mail, the behavior 
returns to the state as when it was first spawned at launch time.

\vspace{0.1in}
\noindent
For example, if the behavior were configured with:

\bvar{reset\_var = OPR\_RESET}

\vspace{0.1in}
\noindent
then the following postings would reset the behavior if the vehicle
breached the OpRegion polygon:

\mvar{OPR\_RESET = poly}

\vspace{0.1in}
\noindent
Similarly, if the OpRegion behavior were breached due to a depth
violation, posting \mvar{OPR\_RESET=depth} would reset the
behavior. Posting \mvar{OPR\_RESET=time} would reset the behavior
after breaching its max time limit. Posting
\mvar{OPR\_RESET=altittude} would reset the behavior after breaching
its min altitude limit.



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