<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">%======================================================================
\section{The Waypoint Behavior}
%======================================================================
\wikisec{grp=bhvsolo, file=BehaviorWaypoint,short=Waypoint Behavior}
\label{bhv_waypoint}
\index{IvP Behaviors Implemented!\var{BHV\_Waypoint}}
\index{Waypoint Behavior}

The Waypoint behavior is used for transiting to a set of specified
waypoint in the x-y plane. The primary parameter is the set of
waypoints. Other key parameters are the inner and outer radius around
each waypoint that determine what it means to have met the conditions
for moving on to the next waypoint. Thee basic idea is shown in Figure
\ref{fig_bhv_waypoint}.

\vspace{0.15in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.8\textwidth]{figs_bhvs/bhv_waypoint.png}
  \caption{{\bf The Waypoint behavior:} The waypoint behavior basic
    purpose is to traverse a set of waypoints. A capture radius is
    specified to define what it means to have achieved a waypoint, and
    a non-monotonic radius is specified to define what it means to be
    "close enough" should progress toward the waypoint be noted to
    degrade.}
  \label{fig_bhv_waypoint}
\end{figure}
\vspace{0.2in} 

\noindent
The behavior may also be configured to perform a degree of track-line
following, that is, steering the vehicle not necessarily toward the
next waypoint, but to a point on the line between the previous and
next waypoint. This is to ensure the vehicle stays closer to this line
in the face of external forces such as wind or current. The behavior
may also be set to "repeat" the set of waypoints indefinitely, or a
fixed number of times. The waypoints may be specified either directly
at start-up, or supplied dynamically during operation of the vehicle. 
There are also a number of accepted geometry patterns that may be given 
in lieu of specific waypoints, such as polygons, lawnmower pattern and
so on.

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

\input{includes/bhv_all_properties}

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

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

  \bvar{capture\_radius}: &amp; The radius tolerance, in meters, for
  satisfying the arrival at a waypoint. The default is 3. Section
  \ref{sec_wpt_capture_params}. \\
  
  \bvar{capture\_line}: &amp; If set to true, waypoint arrival will be
  achieved if the vehicle crosses the line perpendicular to the line
  approaching the waypoint. Default is false. Section
  \ref{sec_wpt_capture_line}. \\
  
  \bvar{crs\_spd\_zaic\_ratio}: &amp; Specifies the relative weight of the 
  course portion of the ZAIC. Valid range is $[1,99]$. Default is 50. \\

  \bvar{cycleflag}: &amp; Optional MOOS variable-value pairs posted at end
  of each cycle through waypoints. \\

  \bvar{efficiency\_measure}: &amp; Determines if leg by leg efficiency is to
  be measured and/or reported. The default is \var{"off"}. \\

  \bvar{lead}: &amp; If this parameter is set, track-line following
  between waypoints is enabled. Section \ref{sec_wpt_lead}. \\ 

  \bvar{lead\_damper}: &amp; Distance from trackline within which the
  \var{lead} distance is stretched out. Section \ref{sec_wpt_lead}. \\ 
  
  \bvar{lead\_to\_start}: &amp; Boolean indicating whether trackline
  following is applied to first waypoint. The default is
  false. Section \ref{sec_wpt_lead}. \\

  \bvar{order}: &amp; The order in which waypoints are traversed -
  \var{"normal"}, \var{"reverse"}, and with 14.3 or later,
  \var{"toggle"}. Section \ref{sec_wpt_params}. \\

  \bvar{points}: &amp; A colon separated list of x,y pairs given as
  points in 2D space, in meters. Section \ref{sec_wpt_params}. \\ 
  
  \bvar{point}: &amp; A single x,y pair given as a point in 2D space, 
  in meters. Section \ref{sec_wpt_params}. \\ 
  
  \bvar{polygon}: &amp; An alias for \bvar{points}. Need not be a convex
  polygon. Section \ref{sec_wpt_params}. \\
  
  \bvar{post\_suffix}: &amp; A suffix tagged onto the \mvar{WPT\_STATUS}, 
  \mvar{WPT\_INDEX} and \mvar{CYCLE\_INDEX} variables. \\ 

  \bvar{radius}: &amp; An alias for \bvar{capture\_radius}. Section
  \ref{sec_wpt_capture_params}. \\ 
  
  \bvar{repeat}: &amp; The number of {\em extra} times traversed through
  the waypoints. Or \var{"forever"}. The default is \var{"normal"}
  meaning the points will be visited in the order listed. Section
  \ref{sec_wpt_order_repeat}. \\

  \bvar{slip\_radius}: &amp; An "outer" capture radius. Arrival declared
  when the vehicle is in this range and the distance to the next
  waypoint begins to increase. The default is 15 meters. Section
  \ref{sec_wpt_capture_params}. \\

  \bvar{speed}: &amp; The desired speed (m/s) at which the vehicle travels
  through the points. Accepts only non-negative numbers.  The default
  is 0.\\

  \bvar{speed\_alt}: &amp; An alternative desired speed (m/s) at which the
  vehicle travels through the points. Applies only when the
  \bvar{use\_alt\_speed} parameter is set to true. The default is -1,
  which indicates internally that it has not been set. (Introduced after
  release 15.5.) \\

  \bvar{use\_alt\_speed}: &amp; If true then attempt to use the altnernate
  speed set with the \bvar{speed\_alt} parameter, if that speed is set
  to a non-negative value. The default is false. (Introduced after release
  15.5.)\\
  
  \bvar{visual\_hints}: &amp; Optional hints for visual properties in
  variables posted intended for rendering. Section
  \ref{sec_wpt_visual_hints}. \\
  
  \bvar{wpt\_status\_var}: &amp; Optional MOOS variable for posting the 
  waypoint status messages as described in Section \ref{sec_wpt_publish}. \\

  \bvar{wpt\_index\_var}: &amp; Optional MOOS variable for posting the 
  waypoint index messages as described in Section \ref{sec_wpt_publish}. \\

  \bvar{wptflag}: &amp; Optional MOOS variable-value pairs posted after
  each waypoint has been reached. \\

\end{longtable}
\end{listing}
\normalsize

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

\begin{fileverb}
Behavior = BHV_Waypoint
{
  // General Behavior Parameters
  // ---------------------------
  name         = transit               // example
  pwt          = 100                   // default
  condition    = MODE==TRANSITING      // example
  updates      = TRANSIT_UPDATES       // example

  // Parameters specific to this behavior
  // ------------------------------------
     capture_radius = 3                       // default
       capture_line = false                   // default
          cycleflag = COMMS_NEEDED=true       // example
               lead = -1                      // default
        lead_damper = -1                      // default
      lead_to_start = false                   // default
              order = normal                  // default 
             points = pts={-200,-200:30,-60}  // example
        post_suffix = HENRY                   // example
             repeat = 0                       // default
        slip_radius = 15                      // default
              speed = 1.2                     // default is zero
            wptflag = HITPTS = $(X),$(Y)      // example     

       visual_hints = vertex_size  = 3             // default
       visual_hints = edge_size    = 1             // default
       visual_hints = vertex_color = dodger_blue   // default
       visual_hints = edge_color   = white         // default
       visual_hints = nextpt_color = yellow        // default
       visual_hints = nextpt_lcolor = aqua         // default
       visual_hints = nextpt_vertex_size = 5       // 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}[0]
\item \mvar{WPT\_STAT}: A comma-separated string showing the status in
  hitting the list of points.
\item \mvar{WPT\_INDEX}: The index of the current waypoint. First
  point has index 0.
\item \mvar{CYCLE\_INDEX}: The number of times the full set of points
  has been traversed, if repeating.
\item \mvar{VIEW\_POINT}: A visual cue for indicating the waypoint
  currently heading toward.
\item \mvar{VIEW\_POINT}: A visual cue for indicating the steering
  point, if the \var{lead} parameter is used.
\item \mvar{VIEW\_SEGLIST}: A visual cue for rendering the full set of
  waypoints.
\end{packed_itemize}

\noindent
The Waypoint behavior will also publish any MOOS variables configured with
the general behavior flags:

\begin{packed_itemize}[0]
\item \bvar{runflag}, \bvar{idleflag}, \bvar{activeflag},
  \bvar{inactiveflag}, and \bvar{endflag}, described in Section
  \ref{sec_bhv_common_params}.
\end{packed_itemize}

\noindent
as well as the flags defined locally for the Waypoint behavior:

\begin{packed_itemize}[0]
\item \bvar{cyleflag} and \bvar{wptflag}. 
\end{packed_itemize}


%===============================================================================
\subsection{Specifying Waypoints with the \bvar{points} or \bvar{point} Parameter}
\label{sec_wpt_points}

There are a few formats supported for setting the list of
waypoints. In the simplest case, when there is just a single point, as
with the waypoint return behavior in the alpha mission, the following
format may be used:

\prevbhv
\begin{verbatim}
 point = 0,0
\end{verbatim}
\postverb

\noindent 
Using the plural \bvar{points} parameter is also ok when there is only
one point. Another common method is to specify a colon-separated list of
comma-separate pairs. For example, also from the alpha mission:

\prevbhv
\begin{verbatim}
 points = 60,-40:60,-160:150,-160:180,-100:150,-40
\end{verbatim}
\postverb


\noindent
Other formats supported are tied to the \var{XYSegList} and
\var{XYPolyogn} classes. The former represents a set of vertices
connected by line segments with a clear first and last vertex. The
latter represents a convex polygon over vertices with the notion of
the first or last vertex less clear in some cases. So for example, both
of the following ways of setting waypoints are supported:

\prevbhv
\begin{verbatim}
 points = pts={60,-40:60,-160:150,-160:180,-100:150,-40}
 points = format=lawnmower, x=0, y=40, height=60, width=180, lane_width=15
\end{verbatim}
\postverb

\noindent
When loading a waypoint specification, the behavior will first attempt to
build an XYSeglist from one of the above formats. Failing this, it will try
to build an XYPolygon from the specification. Therefore any of the XYPologon
string formats described in the Geometry documentation is supported.
For example:

\prevbhv
\begin{verbatim}
 points = format=radial, label=foxtrot, x=0, y=40, radius=60, pts=6, snap=1
 points = format=ellipse, label=golf, x=0, y=40, degs=45, pts=14, snap=1,
             major=100, minor=70
\end{verbatim}
\postverb

\noindent
In specifying a list of points indirectly via the lawnmower, radial or ellipse
patterns, the "first" point in the list may be less predictable. 


%===============================================================================
\subsection{The \bvar{order} and \bvar{repeat} Parameters}
\label{sec_wpt_order_repeat}

The order of the parameters may be reversed with the \bvar{order}
parameter, and the number of times the waypoints are traversed may be
adjusted with the \bvar{repeat} parameter. An example specification:

\prevbhv
\begin{verbatim}
  points  = 60,-40:60,-160:150,-160:180,-100:150,-40
  order   = reverse  // default is "normal"
  repeat  = 3        // default is 0
\end{verbatim}
\postverb

\noindent
A waypoint behavior with this specification will traverse the five
points in reverse order (150, -40 first) four times (one initial cycle
and then repeated three times) before completing.  If there is a
syntactic error in this specification at helm start-up, an output
error will be generated and the helm will launch in the
\var{MALCONFIG} mode.  If the syntactic error is passed as part of a
dynamic update (see Section \ref{sec_updates}), the change in
waypoints will be ignored and the a warning posted to the
\mvar{BHV\_WARNING} variable. See the Geometry documentation for more
methods for specifying sets of waypoints.  The behavior can be set to
repeat its waypoints indefinitely by setting \bsvar{repeat="forever"}.
The \bvar{point} parameter may be used insted of \bvar{points} when
there is only a single waypoint.


%=======================================================================
\subsection{The \bvar{capture\_radius} and \bvar{slip\_radius} Parameters}
\label{sec_wpt_capture_params}

The \bvar{capture\_radius} parameter specifies the distance to a given
waypoint the vehicle must be before it is considered to have arrived
at or achieved that waypoint. It is the inner radius around the points
in Figure \ref{fig_bhv_waypoint}.  The \bvar{slip\_radius} parameter
specifies an alternative criteria for achieving a waypoint.

\vspace{0.15in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.92\textwidth]{figs_bhvs/bhv_wpt_nonmono.png}
  \caption{{\bf The capture radius and slip radius:} (a) a successful
    waypoint arrival by achieving proximity less than the capture
    radius. (b) a missed waypoint likely resulting in the vehicle
    looping back to try again. (c) a missed waypoint but arrival
    declared anyway when the distance to the waypoint begins to
    increase and the vehicle is within the slip radius.}
  \label{fig_nonmono}
\end{figure}
\vspace{0.15in}

As the vehicle progresses toward a waypoint, the sequence of measured
distances to the waypoint decreases monotonically. The sequence
becomes non-monotonic when it hits its waypoint or when there is a
near-miss of the waypoint capture radius. The \bvar{slip\_radius}, is
a capture radius distance within which a detection of increasing
distances to the waypoint is interpreted as a waypoint arrival.  This
distance would have to be larger than the capture radius to have any
effect. As a rule of thumb, a distance of twice the capture radius is
practical.  The idea is shown in Figure \ref{fig_nonmono}. The
behavior keeps a running tally of hits achieved with the capture
radius and those achieved with the slip radius. These tallies are
reported in a status message described in Section
\ref{sec_wpt_publish} below.


%=======================================================================
\subsection{The \bvar{capture\_line} Parameter}
\label{sec_wpt_capture_line}

The \bvar{capture\_line} parameter allows for an alternative or
additional arrival criteria to be applied. When set to \var{true},
waypoint arrival will be achieved if the vehicle crosses the line
perpendicular to the line segment approaching the waypoint from the
previous waypoint. In the case of the first waypoint, the "previous"
waypoint is defined by the vehicle position when the behavior first
becomes active.

\pskip

When \bvar{capture\_line} is set to \var{true}, both the capture line
criteria {\em and} the capture and slip radius criteria apply. If
either is satisfied, then arrival is achieved. If the
\bvar{capture\_line} criteria is set instead to \var{absolute}, then
the capture and slip radius criteria is disabled, and only the capture
line criteria is achieved. 

\pskip

When \bvar{capture\_line} is set to \var{false}, only the capture and
slip radius criteria are applied. A note of caution - setting the
\bvar{capture\_line} parameter to \var{absolute} essentially sets the 
capture and slip radius to zero. If the \bvar{capture\_line} parameter
is subsequently set to anything else (\var{true} or \var{false}), the
capture and slip radius values also need to be explicitly re-set to 
non-zero values. 



%=======================================================================
\subsection{Track-line Following using the \bvar{lead}, \bvar{lead\_damper}, and \bvar{lead\_to\_start} Parameters}
\label{sec_wpt_lead}

By default the waypoint behavior will output a preference for the
heading that is directly toward the next waypoint. By setting the
\bvar{lead} parameter, the behavior will instead output a preference
for the heading that keeps the vehicle closer to the track-line, or
the line between the previous waypoint and the waypoint currently
being driven to.

\vspace{0.15in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=1.0\textwidth]{figs_bhvs/bhv_wpt_track.png}
  \caption{{\bf The track-line mode:} When in track line mode, the
    vehicle steers toward a point o the track line rather than simply
    toward the next waypoint. The steering-point is determined by the
    \vvar{lead} parameter. This is the distance from the perpendicular
    intersection point toward the next waypoint.}
  \label{fig_trackline}
\end{figure}
\vspace{0.15in}

The distance specified by the \bvar{lead} parameter is based on the
perpendicular intersection point on the track-line. This is the point
that would make a perpendicular line to the track-line if the other
point determining the perpendicular line were the current position of
the vehicle. The distance specified by the \bvar{lead} parameter is the
distance from the perpendicular intersection point toward the next
waypoint, and defines an imaginary point on the track-line.  The
behavior outputs a heading preference based on this imaginary steering
point.  If the lead distance is greater than the distance to the next
waypoint along the track-line, the imaginary steering point is simply
the next waypoint.

\pskip

Normally, when trackline following is enabled, it is enabled only
between the first waypoint and all succeess waypoints. When the
parameter \bvar{lead\_to\_start} is set to true, trackline following is
attempted even to the first waypoint, by defining a trackline from the
vehicle's present position when the behavior first enters the running
mode.

\pskip

If the \bvar{lead} parameter is enabled, it may be optionally used in
conjuction with the \bvar{lead\_damper} parameter. This parameter
expresses a distance from the trackline in meters. When the vehicle is
within this distance, the value of the \bvar{lead} parameter is
stretched out toward the next waypoint to soften, or dampen, the
approach to the trackline and reduce overshooting the trackline.

%=======================================================================
\subsection{The \bvar{wptflag} Parameter}
\label{sec_wpt_wpt_flag}

The \bvar{wptflag} parameter allows the user to speicify flags to be 
posted upon the achievement of each waypoint, where waypoint achievement
is defined by the normal means, depending on how the user has configured
the \bvar{capture\_radius}, \bvar{slip\_radius} or \bvar{capture\_line}
parameters. The \bvar{wptflags} are in the same format as idle, end, 
active, or inactive flags defined generally for IvP behaviors, i.e, they
consist of a MOOS variable and value. For example:

\prevblue
\begin{verbatim}
   wptflag = STATION_KEEP=true
\end{verbatim}
\postverb

\noindent
The flags also support a handleful of macro expansions that allow the 
certain information about ownship or the next waypoint to be embedded
in the posting that may not be available until run-time. These macros
are:

\vspace{0.1in}
\begin{packed_itemize}
  \item \var{\$[X] or \$(X)}: Expanded to ownship's x position in
    local coordinates.
  \item \var{\$[Y] or \$(Y)}: Expanded to ownship's x position in
    local coordinates.
  \item \var{\$[NX] or \$(NX)}: Expanded to the x position of the next
    waypoint in local coordinates.
  \item \var{\$[NY] or \$(NY):} Expanded to the y position of the next
    waypoint in local coordinates.
\end{packed_itemize}

\vspace{0.1in}
\noindent
Here are a couple examples of how the \bvar{wptflag} parameter may be
useful in practice.

\pskip

In the first case, in the example provided above, the mission may be
configured to station-keep after arriving at each waypoint. This may
be useful for a surface vehicle with a primary mission of collecting
sensor measurements at periodic points in a survey area corresponding
to waypoints. In this case, another station-keeping behavior is
activated with the \bvar{wptflag} posting, which presumably
temporarily idles the waypoint behavior while measurements are
collected.

\pskip

A second case utilizes the \bvar{wptflag} parameter to post the x-y
position of the next waypoint in the list. 



%=======================================================================
\subsection{Variables Published by the Waypoint Behavior}
\label{sec_wpt_publish}

The waypoint behavior publishes five variables for monitoring the
performance of the behavior as it progresses: \mvar{WPT\_STAT},
\mvar{WPT\_INDEX}, \mvar{CYCLE\_INDEX}, \mvar{VIEW\_POINT},
\mvar{VIEW\_SEGLIST}. The \mvar{WPT\_STAT} contains information
identifying the vehicle, the index of the current waypoint, the type
of hits recorded for each waypoint, the distance to the current
waypoint, and the estimated time of arrival to the current
waypoint. Example output:

\prevgreen
\begin{verbatim}
   WPT_STAT = "vname=alpha,behavior=traverse1,index=0,hits=10/11,dist=43,eta=23"
\end{verbatim}
\postverb

\noindent
The \msvar{"hits=10/11"} component in the above example indicates that, of
the 11 waypoint arrivals achieved so far, 10 of them were achieved by 
meeting the capture radius criteria, and one of them was achieved by 
meeting the nonmonotonic radius criteria.

\pskip

The \mvar{WPT\_INDEX} variable simply publishes the index of the
current waypoint. This is a bit redundant since this information is
also in the \mvar{WPT\_STAT} posting, but this variable is logged as a
numerical variable, not a string, and facilitates the plotting of the
index value as a step function in post mission analysis tools.  The
\mvar{CYCLE\_INDEX} variable publishes the number of times the behavior
has traversed the entire set of waypoints.  The behavior may be
configured to post the information in these three variables using
alternative variables of the user's liking:

\prevbhv
\begin{verbatim}
   post_mapping  = WPT_STAT, MY_WPT_STATUS_VAR 
   post_mapping  = WPT_INDEX, MY_WPT_INDEX_VAR  
   post_mapping  = CYCLE_INDEX, MY_CYCLE_INDEX
\end{verbatim}
\postverb

\noindent
or, to suppress the reports completely:

\prevbhv
\begin{verbatim}
   post_mapping  = WPT_STAT, SILENT
   post_mapping  = WPT_INDEX, SILENT
   post_mapping  = CYCLE_INDEX, SILENT
\end{verbatim}
\postverb

\pskip

\noindent
Further posts to the MOOSDB can be configured to be made at the end of
each cycle, that is, after reaching the last waypoint. Normally, if
the \bvar{repeat} parameter remains at its default value of zero, then
the end of a cycle and completing are identical and endflags can be
used to post the desired information. However, when the behavior is
configured to repeat the set of waypoints one or more times before
completed, the \bvar{cycleflag} parameter may be used to post one or
more variable-value pairs at the end of each cycle.  Likewise, if the
\bvar{repeat} parameter is zero, but the behavior is set with
\bvar{perpetual=true}, the cycle flags will posted each new time that
the behavior completes.

\pskip

The \mvar{VIEW\_POINT} and \mvar{VIEW\_SEGLIST} variables provide
information consumable by a GUI application such as
\app{pMarineViewer} or \app{alogview} for rendering the set of
waypoints traversed by the behavior (\mvar{VIEW\_SEGLIST}) and the
behavior's next waypoint (\mvar{VIEW\_POINT}). These two variables are
responsible for the visual output in the Alpha Example Mission in
Section \ref{sec_alpha} in Figure \ref{alpha_snap_one}.

%------------------------------------------------------------------------
\subsection{The Objective Function Produced by the Waypoint Behavior}
\label{sec_wpt_ivpfunction}

The waypoint behavior produces a new objective function, at each
iteration, over the variables \var{speed} and
\var{course/heading}. The behavior can be configured to generate this
objective function in one of two forms, either by coupling two
independent one-variable functions, or by generating a single coupled
function directly. The functions rendered in Figure \ref{fig_wptof}
are built in the first manner.

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.85\textwidth]{figs_bhvs/wpt_ipf.png}
  \caption{{\bf A waypoint objective function:} The objective function
    produced by the waypoint behavior is defined over possible heading
    and speed values. Depicted here is an objective function favoring
    maneuvers to a waypoint 270 degrees from the current vehicle
    position and favoring speeds closer to the mid-range of capable
    vehicle speeds. Higher speeds are represented farther radially out
    from the center.}
  \label{fig_wptof}
\end{figure}

%=======================================================================
\subsection{Further Clarification on the \bvar{repeat} vs. \bvar{perpetual} Parameter}
\label{sec_repeat_vs_perpetual}

It's worth clarifying the difference in usage and effect between the
\bvar{repeat} parameter, which is specific to the Waypoint behavior,
and the \bvar{perpetual} parameter which is defined for all helm
behaviors. Normally when a behavior completes, it is entered into the
completed stated, never again to be called upon by the helm. See
Section \ref{sec_run_states} for more on behavior run states. It is up
to the behavior implementor to decide what it means to be complete,
and the implentor typically invokes the \func{setComplete()} function
from within the code. See Section \ref{sec_bhv_util_funcs} for more on
this function. In the case of the Waypoint behavior, completion by
default occurs when the vehicle has hit all its waypoints. By setting
\bsvar{perpetual=true} the behavior, upon hitting all its waypoints,
still invokes the \func{setComplete()} function, which causes it to
post its endflags, but it does not enter the completed state. This
feature is used, for example, in the Alpha example mission to allow
the behavior to repeatedly return to the start point and be
re-deployed, and later return to its start point again using the same
Waypoint behavior.

\pskip

The \bvar{repeat} parameter is used to change the criteria for
completion. Whereas the normal criteria for completion is hitting all
waypoints once, using \bsvar{repeat=N} changes the criteria to be
hitting all waypoints \var{N+1} times. A few rules of thumb may be
helpful in keeping things straight:

\begin{itemize}
\item When \bsvar{perpetual=false}, the default setting, the behavior
  will permanently enter the completed state once it has hit all its
  waypoints.

\item When \bsvar{perpetual=true} and the behavior does not post
  endflags leading to its run conditions being unsatisfied, the
  behavior will repeat its waypoints indefinitely.

\item When \bsvar{perpetual=true} and it does indeed post
  endflags that lead to its run conditions being unsatisfied, it will
  remain in a running state until all its waypoints are hit. If the
  \bvar{repeat} parameter is used, it won't post its endflags until it
  has repeated all waypoints the specified number of times. During the
  course of traversal, the \bvar{cycleflag} posts will be made each
  time it has completed the set of waypoints. Upon completion, it will
  post its endflags and reset its cycle counter.

\item By setting \bvar{repeat}\bsvar{=N}, where \bsvar{N&gt;0}, the \bvar{perpetual}
  parameter is automatically set to \var{true}.

\end{itemize}



%=======================================================================
\subsection{Visual Hints Defined for the Waypoint Behavior}
\label{sec_wpt_visual_hints}

Although the primary output of the Waypoint behavior is an IvP
Function, a number of visual properties are also published for
convenience in mission monitoring.  This includes (a) the set of
waypoints, (b) the point the behavior is presently progressing toward,
and (c) the trackpoint, if trackpoint following is enabled. These
visual artifacts have default properties in size and color that may be
altered to the user's preferences. These preferences are configurable
through the \bvar{visual\_hints} parameter. Each parameter below is
used in the following way by example:

\vspace{0.1in}
\begin{fileverb}
 visual_hints = vertex_size=3, edge_size=2
 visual_hints = vertex_color=khaki
\end{fileverb}
\vspace{0.1in}


\begin{packed_itemize}[1]
\item \bvar{vertex\_size}: The size of vertices rendered in the
  loiter polygon. The default is 1.
\item \bvar{edge\_size}: The width of edges rendered in the
  loiter polygon. The default is 1.
\item \bvar{vertex\_color}: The color of vertices rendered in the
  loiter polygon. The default is "dodger\_blue".
\item \bvar{edge\_color}: The color of edges rendered in the loiter
  polygon. The default is "white".
\item \bvar{label\_color}: The color of label for set of waypoints.
  The default is "white".
\item \bvar{nextpt\_color}: The color of the point rendered as the
  present next waypoint. The default is "yellow".
\item \bvar{nextpt\_lcolor}: The color of the label for the point
  rendered as the present next waypoint. The default is "aqua".
\item \bvar{nextpt\_vertex\_size}: The size of the vertex for the point
  rendered as the present next waypoint. The default is 1. 
\end{packed_itemize}

\noindent
Rendering of vertices or the next waypoint may be shut off with a size of zero, 
and labels may be shut off with the special color "invisible". For a list 
of legal colors, see Appendix \ref{app:colormap}.


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