<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{uFldObstacleSim: Simulating Obstacles}
\vspace{0.1in}
\labdate{June 2020}
\labdate{July 2021 - minor additions}
\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.UFldObstacleSim}
\wikidoc{bugz=uFldObstacleSim}
\wikidoc{auth=mikerb@mit.edu}

%=================================================================
\section{Overview}
%=================================================================
\label{sec_ufld_obsim}

The \app{uFldObstacleSim} application is a tool for simulating
obstacles, and obstacle sensor output. Ground truth position and size
of obstacles are read from a pre-generated {\em obstacle file}. The
simulation generates information in one of two modes, in one of two
manners:

\begin{packed_itemize}
\item Obstacle polygons are simply published and shared to all
  vehicles, or
\item Simulated sensor data, similar to Lidar points on the obstacle,
  are published and shared to the vehicles. Downstream apps are then
  left with the job of inferring the obstacle from the sensor data.
\end{packed_itemize}

\noindent
When this simulator is operating in the first mode, it publishes information
to the variable \mvar{GIVEN\_OBSTACLE}. In the second mode, it publishes
the information to the variable \mvar{TRACKED\_FEATURE}.

\vspace{0.1in}
\noindent
The simulator also supports two different modes of obstacle
generation:

\begin{packed_itemize}
\item By default, the obstacles are simply read in from the obstacle
  file and never change.
\item A second mode is supported where the obstacles are periodically
  regenerated with the same configuration parameters used for creating
  the original obstacle file.
\end{packed_itemize}

\vspace{0.1in}
\noindent
A key parameter in regeneration is the obstacle region, a polygon
within which all randomly generated obstacles are guaranteed to reside
within. During a simulation, we want to take care that obstacle
regeneration does not take place while any vehicles are in the
obstacle region. Otherwise an obstacle could be generated in a
position currently occupied by, or just in front of a vehicle. The
ensuing unavoidable collision would skew the test results. The
obstacle simulator therefore will monitor vehicle positions and only
regenerate obstacles when all vehicles are a safe distance from the
obstacle region.  The vehicle locations are known to the simulator
from the \mvar{NODE\_REPORT} messages received from the vehicles.

\vspace{0.1in}
\noindent
The setup overview is depicted in Figure \ref{fig_ufos_overview}:

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.55\textwidth]{figures/ufos_overview.png}
  \caption{{\bf The Obstacle Simulator:} The obstacle simulator
    resides on the shoreside and ingests and maintains ground truth
    obstacle state. Information is fed to each connected
    vehicle. Typically the primary consumer on the vehicle side is the
    obstacle manager, \app{pObstacleMgr}.}
\label{fig_ufos_overview}
\end{figure}
\vspace{0.1in}


%=================================================================
\section{A Quick Start Guide to Using uFldObstacleSim}
%=================================================================

To get started, we (a) point you to an example mission using
\app{uFldObstacleSim}, (b) lay out the minimum \app{uFldObstacleSim}
configuration components, i.e., those which do not have default
values, and (c) discuss the structure of a simple obstacle file
representing the ground-truth set of obstacles used by the simulator.

%=================================================================
\subsection{A Working Example Mission - the Bo Alpha Mission}
\label{sec_ufhz_quick_jake}

The example mission is referred to as the Bo Alpha example mission and
may be found and launched in the moos-ivp distribution with:

\vspace{0.2in}
\begin{consoleverb}
 $ cd moos-ivp/ivp/missions/m34_bo_alpha
 $ ./launch.sh 10
\end{consoleverb}
\vspace{0.2in}

\noindent
This launches the simulation with time warp 10. The time warp may be
adjusted to suit your preference and is bounded above by your
computer's processing capability. After launching and hitting the
deploy button, you should see something similar to Figure
\ref{fig_ufos_bo_alpha}.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.80\textwidth]{figures/m34_bo_alpha.png}
  \caption{{\bf The Bo Alpha Mission:} The Bo Alpha example mission
    involves a two vehicles each traversing East-West through an
    obstacle field created by the simulator. The helm on both vehicles
    is performing obstacle avoidance and COLREGS based collision
    avoidance with the other vehicle. The true obstacle is the inner
    polygon. When the vehicle is actively avoiding the obstacle, the
    true obstacle is rendered more opaque, and the buffer region
    around the obstacle is rendered.}
  \label{fig_ufos_bo_alpha}
  \urlvideox{https://vimeo.com/424523746}{1:01}
\end{figure}

\noindent
There are a few notable components of this simulation that comprise
the nature of the mission:

\begin{packed_itemize}
\item The \app{uFldObstacleSim}: Running on the shoreside, distributes knowledge
  of the obstacles to each vehicle.
\item The \var{obstacles.txt} file read in by the \app{uFldObstacleSim} obstacle simulator.
\item The \app{gen\_obstacles} command-line app that generated the
  \var{obstacles.txt} file, used by the simulator. This app chooses
  random obstacle locations within a polygon and ensures a given
  minimum spacing between obstacles.
\item \app{pObstacleMgr} app running on each vehicle that receives the
  obstacle knowledge from the obstacle simulator and maintains a set
  of known obstacles. It will also generate obstacle alerts which
  result in spawned obstacle avoidance behaviors in the helm.
\end{packed_itemize}
\vspace{0.1in}

\noindent
It may also be worth considering, in Figure \ref{fig_ufos_bo_alpha},
where all the visual artifacts shown in the \app{pMarineViewer}
snapshot are coming from:

\begin{packed_itemize}
\item The \app{uFldObstacleSim} app is publishing the large square
  rectangle, which is the region from which the random obstacles were
  originally chosen from. It is also publishing all five ground-truth
  obstacles. The three north-west obstacles have other things being
  rendered over them, but the two south-east obstacles are the ones
  published by \app{uFldObstacleSim}.
\item The Avoid Obstacle behavior in the helm also publishes the obstacle
  polygon when the behavior is active, but it publishes a request to render
  the polygon with more opacity. Thus the three north-west polygons show
  that at least one of the vehicles is actively avoiding it. The behavior
  also published the buffer polygon around the ground truth obstacle, with
  less opacity. And of course the behavior is also publishing the loiter
  polygon to the far east and west to which each is transiting through
  the obstacle field.
\item Not shown in the figure, but when the two vehicles are close to
  each other and also actively engaging in collision avoidance, each
  vehicle's collision avoidance behavior will render a line between
  vehicles, with color varying with the behavior's priority weight.
\end{packed_itemize}

%=================================================================
\subsection{A Bare-Bones Example uFldObstacleSim Configuration}

Listing \ref{lst_ufos_config} below shows a bare-bones
configuration.  Line 3 names a obstacle file, containing the ground
truth description of objects in the field. This format is described in
Section \ref{sec_ufos_obsfile_simple}, and an example obstacle file is
in the same directory as the Bo Alpha example mission. There are several
more configuration parameters supported by \app{uFldObstacleSim}, but
they all have default values, accepted in this simple simulation. The
other parameter values are discussed later.

\vspace{0.25in}
\begin{listing}{Example bare-bones configuration of \app{uFldObstacleSim}}
\label{lst_ufos_config}
\footnotesize
\begin{verbatim}
 1  ProcessConfig = uFldObstacleSim
 2  {                                                               
 3    obstacle_file = obstacles.txt                                   
 4  }                                                          
\end{verbatim}
\end{listing}
\normalsize
\vspace{0.1in} 

%=================================================================
\subsection{A Simple Obstacle File}
\label{sec_ufos_obsfile_simple}

In the Bo Alpha example mission, two vehicles traverse an obstacle
field comprised of five obstacles. These obstacles were chosen
randomly by the \app{gen\_obstacles} command line utility. The results
were stored in the \var{obstacles.txt} file read in by the obstacle
simulator. This file was named in the obstacle simulator config block
in Listing \ref{lst_ufos_config} above. The \app{gen\_obstacles}
utility will choose obstacles while ensuring (a) each obstacle is
within a given polygon area, and (b) a minimum configurable separation
distance between obstacles.  This command-line tool is discussed in
Section \ref{sec_ufos_gen_obs}.

\vspace{0.1in}

\noindent
An obstacle file is comprised of:

\begin{packed_itemize}
\item The first line, a comment, showing the exact command that generated the file,
\item The command line parameters on a separate line,
\item The polygon for each obstacle, with a unique label.
\end{packed_itemize}

\noindent
The obstacle file for the Bo Alpha mission is given below.

\vspace{0.1in}
\scriptsize
\begin{fileverb}
# gen_obstacles --poly=30,-20:30,-140:120,-140:120,-20 --amt=5 --min_size=1 --max_size=6 \
   --min_range=20 --meter
region    = pts={30,-20:30,-140:120,-140:120,-20}
min_range = 20
min_size  = 6
max_size  = 10
poly = pts={107,-101:112,-106:112,-113:107,-118:100,-118:95,-113:95,-106:100,-101},label=ob_0
poly = pts={50,-30:53,-33:53,-38:50,-42:45,-42:41,-38:41,-33:45,-30},label=ob_1
poly = pts={82,-65:87,-70:87,-76:82,-81:76,-81:71,-76:71,-70:76,-65},label=ob_2
poly = pts={59,-101:64,-105:64,-112:59,-116:53,-116:48,-112:48,-105:53,-101},label=ob_3
poly = pts={107,-38:112,-43:112,-49:107,-54:100,-54:96,-49:96,-43:100,-38},label=ob_4
\end{fileverb}
\normalsize

%=================================================================
\subsection{Generating an Obstacle File}
\label{sec_ufos_gen_obs}

The \app{gen\_obstacles} command line tool will generate a list of
randomly generated obstacle polygons, given a polygon region. The tool will
guarantee that the obstacle will completely reside in the region, and will
guarantee a minimal separation between obstacles.

\vspace{0.1in}
\noindent
For example, the below command will generate the obstacle file shown in the
above section, with the initial five obstacles of the Bo Alpha mission. The
\var{--poly} parameter indicates the obstacle {\em region}. This region must
be convex, and the utility will produces as many obstacles as possible up to
the amount specified with the \var{--amt} parameter. 

\vspace{0.1in}
\begin{consoleverb}
$ gen_obstacles --poly=30,-20:30,-140:120,-140:120,-20 --amt=5 
  --min_size=1 --max_size=6 --min_range=10 --meter 
\end{consoleverb}
\vspace{0.1in}

\noindent
Each obstacle is an octagon with a random radius no smaller than that
given by the \var{--min\_size} parameter, and no greater than that given
by the \var{--max\_size} parameter. The obstacles will be placed with
a guaranteed minimum separation to the other obstacles given by the
\var{--min\_range} parameter. Finally, the \var{--meter} parameter, will
round all obstacle vertices to the nearest meter if desired, instead of
the default value of \var{0.1} meters.




%=================================================================
\section{Dynamic Resetting of Ground Truth Obstacles}
%=================================================================
\label{sec_ufos_reset}

The obstacle manager supports an option to periodically reset the
ground truth size and location of obstacles. This allows simulations
to test against a wider variety of obstacle situations without the
need to re-start the simulation. The dynamic reset capability ensures
that the reset only occurs only when all known vehicles are outside
the obstacle field, to avoid generating a new obstacle too close to
(or on) a vehicle and thus creating an unavoidable collision.

%=================================================================
\subsection{Parameters for Enabling Dynamic Resetting}
\label{sec_ufos_reset_params}

The dynamic reset occurs on a schedule. After an elapsed period of
time, given by the \pvar{reset\_interval} parameter, a reset will
occur as soon as all the vehicles are outside the obstacle region. All
vehicles must be not only outside the obstacle region but also a given
distance away from the obstacle region given by the
\pvar{reset\_range} parameter. Of course, if all vehicles never happen
to be outside the obstacle region simultaneously, then the reset will
never occur. The mission must be otherwise constructed, as with the Bo
Alpha mission, to ensure the vehicles periodically all exit the
obstacle region simultaneously.

\vspace{0.1in}
\noindent
Here is an example setting:

\prevblue
\begin{verbatim}
 reset_interval = 300
 reset_range    = 20
\end{verbatim}
\postverb

\noindent
The \pvar{reset\_interval} units are in seconds, and the
\pvar{reset\_range} units are in meters. The default value for
\pvar{reset\_interval} is -1, indicating that resets are disabled. The
default value for \pvar{reset\_range} is 10 meters.

%=================================================================
\subsection{MOOS Variable for Enabling Dynamic Resetting}
\label{sec_ufos_reset_moos}

If you would like to reset the obstacle field on demand, by poking a MOOS
variable, this can be done. By publishing \mvar{UFOS\_RESET = now}, the
obstacle simulator will schedule an obstacle reset to occur as soon as
possible. As discussed above, the reset will only actually occur as soon
as all vehicles have exited the obstacle region, sufficiently far away
from the obstacle region given by the \pvar{reset\_range} parameter.

%=================================================================
\subsection{Enabling Dynamic Resetting in the Bo Alpha Mission}
\label{sec_ufos_reset_bo_alpha}

Dynamic obstacle resetting is not enabled by default in the Bo Alpha
mission. It can be enabled by launching with the \var{-d} option on the
command line:

\vspace{0.15in}
\begin{consoleverb}
 $ cd moos-ivp/ivp/missions/m34_bo_alpha
 $ ./launch.sh 10 -d
\end{consoleverb}
\vspace{0.15in}

\noindent
This additional flag is supported in the \cmd{launch.sh} script to add
the following two lines to the \app{uFldObstacleSim} configuration
block:

\vspace{0.15in}
\begin{fileverb}
 reset_interval = 100
 reset_range    = 10
\end{fileverb}
\vspace{0.15in}

\noindent
Every 100 seconds, when the two vehicles are at least 10 meters
outside the obstacle region, the obstacles will be reset. Figure
\ref{fig_ufos_dybo} shows two such random obstacle configurations, and
the associated video link shows the dynamic mission in action.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.80\textwidth]{figures/m34_dybo_alpha.png}
  \caption{{\bf The Dynamic Bo Alpha Mission:} The Bo Alpha is launched
    with dynamic obstacle reset enabled. Roughly each time the vehicles
    reach their east west loiter positions, the obstacle simulator reset
    the obstacles. This produces a different challenge each time the
    vehicles traverse through the obstacle field.}
  \label{fig_ufos_dybo}
  \urlvideox{https://vimeo.com/425156397}{0:54}
\end{figure}



%=================================================================
\section{Simulating Sensor Data from Ground Truth Obstacles}
%=================================================================
\label{sec_ufos_dpoints}

The obstacle simulator supports a second mode of distributing obstacle
information to vehicles. In the default mode discussed so far, the
ground truth obstacle position and location are sent directly to the
vehicles in the \mvar{GIVEN\_OBSTACLE} MOOS variable. For the vehicle
there is no guesswork, and obstacle avoidance is conducted with perfect
knowledge of the obstacles.

\vspace{0.1in}
\noindent
In the second mode, the {\em points} mode, the obstacle simulator
generates a steady stream of random points inside the ground truth
obstacles. It then sends these points to the vehicle in the MOOS
variable \mvar{TRACKED\_FEATURE}. Here is an example publication:


\vspace{0.1in}
\mvar{TRACKED\_FEATURE = x=100,y=-49,key=ob\_4}
\vspace{0.1in}

\noindent
The message contains both the point location, and a unique ID
associated with the ground truth obstacle. So this simulatad sensor
data is still pretty artificially simplistic - there are no false
points because all points generated by the simulator do reside within
the ground truth obstacle polygon. And by including a key, clustering
of points is already done and perfect.


%=================================================================
\subsection{Enabling the Points Sensor Data Mode}
\label{sec_ufos_pts_mode}

The {\em points} mode is disabled by default. It is enabled by setting
the \pvar{post\_points} configuration parameter to \var{true}:

\vspace{0.1in}

\pvar{post\_points = true}

\pvar{rate\_points = 5}
\vspace{0.1in}

\noindent
The \pvar{rate\_points} parameter sets the number of points generated,
per obstacle, per iteration of the simulator. The default value is 5.
When the points mode is enabled, the obstacle simulator does not post
the ground truth obstacle information to \mvar{GIVEN\_OBSTACLE}.
However, it is still posted to \mvar{KNOWN\_OBSTACLE}. Typically
uField sharing is configured to {\em not} share \mvar{KNOWN\_OBSTACLE}
to the vehicles. However it may still be useful for other apps in the
shoreside community to have access to ground truth obstacle
information. For example the \app{uFldCollObDetect} app runs in the
shoreside and monitors vehicles for collisions with obstacles, so it
needs access to ground truth obstacle information.

%=================================================================
\subsection{Generation of Simulated Sensor Points}
\label{sec_ufos_sensor_pts}

Simulated sensor points are generated by calculating random line-of-sight
points on the edge of the obstacle polygon from the direction of the vehicle.
Sensor points are generated per vehicle and shared only with the
relevant vehicle as in Figure \ref{fig_ufos_multi_sens}.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.34\textwidth]{figures/multi_sensor.png}
  \caption{{\bf Vehicle-centered line-of-site sensor:} Sensor points are
    based on line of site, with different sensor points generated for each
    vehicle depending on the bearing of the obstacle to the vehicle. This
    is not currently implemented in the \app{uFldObstacleSim} app.}
  \label{fig_ufos_multi_sens}
\end{figure}
\vspace{0.1in}

\noindent
Recall that each point corresponds to two publications. One
publication, to the variable \mvar{TRACKED\_FEATURE\_ABE}, is
generated and shared only to the vehicle \var{abe}. The other
publication is to the variable \mvar{VIEW\_POINT} which published
locally on the shoreside for the benefit of rendering in a GUI app
such as \app{pMarineViewer}. The color of the points is based on the
color of the vehicle, derived from \mvar{NODE\_REPORT} messsages
received on the shoreside from each vehicle.

\vspace{0.1in}
\noindent
In the event that \app{uFldObstacleSim} is run in a headless simulation,
i.e., no need for visuals, the publication of \mvar{VIEW\_POINT} can
be disabled with the configuration \pvar{post\_visuals=false}. 


%=================================================================
\section{Obstacle Expiration}
%=================================================================
\label{sec_ufos_expire}

There are three notions or reasons why we may want to consider the
{\em expiration} of obstacles.

\begin{packed_itemize}
\item The robot or vehicle has moved far away from the obstacle and we no longer
  care about it, or
\item The obstacle never existed to begin with, but perhaps briefly it
  appeared to exist due to sensor noise, or
\item The obstacle is still close and is real, but perhaps a new identifier was
  mistakenly created for the same obstacle. 
\end{packed_itemize}

\noindent
Each of these things happen in practice, and the downstream apps that
manage and reason about obstacles need to deal with these issues. So
the obstacle simulator has the capability to replicate the expiration
of an obstacle to enable testing of the downstream apps.

\vspace{0.1in}
\noindent
The expiration policy of the two primary obstacle modes of the simulator are
discussed here:

\begin{packed_itemize}
\item The {\em points} mode, where the simulator publishes sensor points in the
  form of the \mvar{TRACKED\_FEATURE} variable, and
\item The {\em ground-truth} mode where the simulator publishes the ground truth
  obstacles in the form of the \mvar{GIVEN\_OBSTACLE} variable.
\end{packed_itemize}




%=================================================================
\subsection{Case 1 - Expiration of Sensor Points}

The simplest of the two modes is the {\em points} mode, perhaps
because elements in a sensor data stream are usually considered to be
ephemeral - as things change, so does the data. In the {\em points}
mode, data is published to the \mvar{TRACKED\_FEATURE} variable. These
postings are regarded as similar to LIDAR points. Although the
simulator generates them randomly on or in the obstacle, they at some
point will either cease, or evolve position, due to:

\begin{packed_itemize}
\item The obstacle goes out of range from the vehicle
\item The obstacle moves or drifts, and thus so do the points
\item The obstacle stops producing points because the simulator deletes the obstacle
\item The obstacle stops producing points because in the real world the obstacle
  actually didn't exist but was perhaps produced by a wave or some other noise
\end{packed_itemize}

\vspace{0.1in}
\noindent
Figure \ref{fig_ufos_pts_expire} conveys the lifespan of sensor points on an
obstacle as a vehicle approaches, passes and leaves behind an obstacle.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.94\textwidth]{figures/point_progression.png}
  \caption{{\bf Expiration of Sensor Points:} Sensor points are generated
    on the edge of the obstacle as the vehicle comes in range (left). As
    long as the vehicle remains in range, regardless of the relative bearing
    from the vehicle to the obstacle, sensor points on the line of site to the
    obstacle will continue to be generated (middle). As the vehicle open
    range to the obstacle the sensor points will cease to be generated (right).}
  \label{fig_ufos_pts_expire}
\end{figure}
\vspace{0.1in}



%=================================================================
\subsection{Case 2 - Expiration of Ground Truth Obstacles}
\label{sec_ufos_duration}

In {\em ground-truth} mode, where the simulator is publishing the
actual obstacle polygon rather than simulated sensor points, the
simulator publishes the polygon information in the form of:

\begin{packed_itemize}
\item \mvar{VIEW\_POLYGON}: for consumption by a GUI app like \app{pMarineViewer}.
\item \mvar{KNOWN\_OBSTACLE}: for consumption by other shoreside apps that need
  access to ground truth obstacles such as \app{uFldCollObDetect}.
\item \mvar{GIVEN\_OBSTACLE}: for sharing to the vehicles and consumption
  by the obstacle manager \app{pObstacleMgr}. 
\end{packed_itemize}

\noindent
In each of these cases, there is a need to "forget" about an obstacle
after time. So each obstacle message contains a \var{duration} field,
in seconds.  While the obstacle is relevant, the obstacle simulator
will periodically publish to these variables, each time with same
duration.  The consumers presumably reset their duration clocks each
time a new message is received. The obstacle simulator will publish only
periodically, but often enough such that the obstacle will endure
indefinitely if the periodic refresh publications continue.

\vspace{0.1in}
\noindent
The \pvar{refresh\_interval} determines how often \app{uFldObstacleSim}
re-publishes the current ground-truth obstacles. A duration is associated
with each obstacle, so typically the refresh should occur before an obstacle
expires (if the goal is persistence). The duration is set with two
parameters, \pvar{min\_duration} and \pvar{max\_duration}. A random duration
will be chosen between these two values.

\vspace{0.1in}
\noindent
The default settings for \pvar{refresh\_interval},  \pvar{min\_duration},
and \pvar{max\_duration} are all \var{-1}. When \pvar{refresh\_interval} is
not set, the obstacle simulator will never refresh (republish) the obstacle
postings unless one or more vertices change. When the obstacle duration is
not set, they we never expire in any of the consumer apps unless they are
cleared or erased via other methods.


%=================================================================
\section{Configuration Parameters of uFldObstacleSim}
%=================================================================
\label{sec_ufos_config_params}

The following parameters are defined for \app{uFldObstacleSim}. For
some parameters, more detailed description are provided in other
sections. Parameters having default values are indicated so.

\vspace{0.15in}
\begin{listing}{Configuration Parameters for \app{uFldObstacleSim}}
\label{lst_ufos_params}
\renewcommand{\arraystretch}{1.1}
\begin{longtable}{rp{0.69\textwidth}} 

  \pvar{obstacle\_file}: &amp; A file with obstacle position and size location.
  Sections \ref{sec_ufos_obsfile_simple} and \ref{sec_ufos_gen_obs}. \\

  \pvar{poly\_vert\_color}: &amp; Color of obstacle polygon vertices. The
  default is \var{"gray50"}. \\

  \pvar{poly\_edge\_color}: &amp; Color of obstacle polygon edges. The
  default is \var{"gray50"}. \\

  \pvar{poly\_fill\_color}: &amp; Color of obstacle polygon interior. The
  default is \var{"white"}. \\

  \pvar{poly\_label\_color}: &amp; Color of obstacle polygon labels. The
  default is \var{"invisible"}. \\

  \pvar{poly\_vert\_size}: &amp; Size of rendered obstacle polygon
  vertices. The default is \var{1}. \\

  \pvar{poly\_edge\_size}: &amp; Size of obstacle
  polygon edges. The default is \var{1}. \\

  \pvar{poly\_transparency}: &amp; Transparency of rendered obstacle
  polygons. The default is \var{0.15}. \\

  \pvar{draw\_region}: &amp; If true, draw the obstacle region. The
  default is \var{true}. \\

  \pvar{region\_edge\_color}: &amp; Color of obstacle polygon edges. The
  default is \var{"gray50"}. \\

  \pvar{region\_edge\_color}: &amp; Color of obstacle region edges. The
  default is \var{"white"}. \\

  \pvar{post\_points}: &amp; If true, sensor points are generated rather
  than ground truth obstacle polygons. The value \var{false}. Section
  \ref{sec_ufos_pts_mode}.  \\

  \pvar{rate\_points}: &amp; When \pvar{post\_points} is \var{true}, this
  parameter sets the rate of point generation. The default is 5
  points, per obstacle, per iteration. Section
  \ref{sec_ufos_pts_mode}.  \\

  \pvar{min\_duration}: &amp; If non-negative, set a random duration for
  each obstacle no lower than this value. The default is -1. Section
  \ref{sec_ufos_duration}. \\

  \pvar{post\_visuals}: &amp; If true, visual posts to \mvar{VIEW\_POINT}
  and \mvar{VIEW\_POLYGON} are generated. The default is true. Section
  \ref{sec_ufos_sensor_pts}. \\

  \pvar{refresh\_interval}: &amp; If non-negative, publications to
  \mvar{GIVEN\_OBSTACLE} will be reposted evern N seconds where N is
  the value of this parameter. The default is -1. Section
  \ref{sec_ufos_duration}. \\

  \pvar{reset\_interval}: &amp; Time, in seconds, between automatic
  reseting of obstacle locations. The default is -1, indicating
  disabled resetting. Section \ref{sec_ufos_reset_params}. \\

  \pvar{reset\_range}: &amp; Distance, in meters, that all vehicles need to be
  outside the obstacle region in order for an obstacle reset to be allowed.
  The default is 10 meters. Section \ref{sec_ufos_reset_params}. \\ 
  
  \pvar{reuse\_ids}: &amp; If \var{false}, each time the obstacle field is
  reset, a unique set of obstacle IDs, i.e., labels, will be generated
  for the newly generated obstacles. The default is
  \var{true}. Section \ref{sec_ufos_reset_params}. \\
  
  \pvar{sensor\_range}: &amp; The range to an obstacle at which simulated LIDAR point will
  be generated. The default is 50. Section \ref{sec_ufos_sensor_pts}. \\
    
\end{longtable}
\end{listing}


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

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

\vspace{0.1in}
\begin{consoleverb}
 $ uFldObstacleSim --example or -e
\end{consoleverb}
\vspace{0.1in}

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

\vspace{0.25in}
\begin{listing}{Example configuration for \app{uFldObstacleSim}}
\label{lst_ufos_econfig}
\footnotesize
\begin{verbatim}
 1  =============================================================== 
 2  uFldObstacleSim Example MOOS Configuration                      
 3  ============================================================== 
 4                                                                  
 5  ProcessConfig = uFldObstacleSim                                 
 6  {                                                               
 7    AppTick   = 4                                                 
 8    CommsTick = 4                                                 
 9 
10    obstacle_file    = obstacles.txt                              
11    poly_vert_color  = color    (default is gray50)               
12    poly_edge_color  = color    (default is gray50)               
13    poly_fill_color  = color    (default is white)                
14    poly_label_color = color    (default is invisible)            
15  
16    poly_vert_size    = 1       (default is 1)                    
17    poly_edge_size    = 1       (default is 1)                    
18    poly_transparency = 0.15    (default is 0.15)                 
19  
20    region_edge_color = color   (default is gray50)
21    region_vert_color = color   (default is white )
22 
23   draw_region       = true    (default is true)                 
24   region_edge_color = color   (default is gray50)               
25   region_vert_color = color   (default is white)                
26                         
27   post_points      = true     (default is false)                
28   rate_points      = 5        (default is 5)                    
29   point_size       = 5        (default is 2)                    
30  
31   min_duration     = 10       (default is -1)                   
32   max_duration     = 15       (default is -1)                   
33   refresh_interval = 8        (default is -1)                   
34 
35   reset_interval   = -1       (default is -1)                   
36   reset_range      = 10       (default is 10)                   
37 
38   reuse_ids        = true     (default is true)                 
39   sensor_range     = 50       (default is 50)                   
40
41   app_logging  = true  // {true or file} By default disabled    
42   
43   post_visuals = true  // {true or false} By default true      
44 }                                                
\end{verbatim}
\end{listing}
\normalsize
 
%=================================================================
\section{Publications and Subscriptions for uFldObstacleSim}
%=================================================================
\label{sec_ufos_interface}

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

%=================================================================
\subsection{Variables Published by uFldObstacleSim}
\label{sec_ufhz_pubs}

The primary output of \app{uFldObstcleSim} to the MOOSDB is posting 
of sensor reports, visual cues for the sensor reports, and visual cues
for the hazard objects themselves.

\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. Section
  \ref{sec_ufos_appcast}

\item \mvar{GIVEN\_OBSTACLE}: A ground truth obstacle, same as,
  \mvar{KNOWN\_OBSTACLE}, but published separately. Typically this
  variable will be shared to the the vehicles.

\item \mvar{KNOWN\_OBSTACLE}: A ground truth obstacle, same as,
  \mvar{GIVEN\_OBSTACLE}, but published separately. Typically shoreside
  apps will register for this variable for knowledge of ground truth
  obstacles.

\item \mvar{TRACKED\_FEATURE}: A single point related to a sensor
  measurement related to a ground truth obstacle, and key associated
  with that obstacle.

\item \mvar{VIEW\_POLYGON}: A visual artifact for rendering a
  a ground truth obstacle polygon.
\end{packed_itemize}

\noindent
Example postings:

\prevgreen
\begin{verbatim}
 KNOWN_OBSTACLE  = pts={48,-77:52,-80:52,-86:48,-89:43,-89:39,-86:39,-80:43,-77},  \
                   label=ob_4,duration=5
 GIVEN_OBSTACLE  = pts={48,-77:52,-80:52,-86:48,-89:43,-89:39,-86:39,-80:43,-77},  \
                   label=ob_4,duration=5
 TRACKED_FEATURE = x=100,y=-49,key=ob_4
 VIEW_POLYGON    = pts={48,-77:52,-80:52,-86:48,-89:43,-89:39,-86:39,-80:43,-77},  \
                   label=ob_4,label_color=invisible,edge_color=gray50,vertex_color=gray50, \
                   fill_color=white,vertex_size=1,edge_size=1,fill_transparency=0.15
\end{verbatim}
\postverb

%=================================================================
\subsection{Variables Subscribed for by uFldObstcleSim}
\label{sec_ufhz_subs}

The \app{uFldObstcleSim} application will subscribe for the following
MOOS variables:

\begin{packed_itemize}
\item \mvar{APPCAST\_REQ}: A request to generate and post a new
  apppcast report, with reporting criteria, and expiration. 
\item \mvar{VEHICLE\_CONNECT}: A message from the vehicle indicating
  its presence in the simulation. This will prompt a (re)publication
  and sharing of ground truth obstacles to the vehicle. 
\item \mvar{UFOS\_RESET}: A request to the simulator to reset the
  obstacle field immediately, or as soon as all vehicles have safely
  cleared the obstacle field.  \ref{sec_ufos_reset_moos}.    
\item \mvar{NODE\_REPORT}: A report on a vehicle location and status.

\end{packed_itemize}

\noindent
Example postings:

\prevgreen
\begin{verbatim}
 UFOS_RESET = true
 VEHICLE_CONNECT = true
\end{verbatim}
\postverb

%=================================================================
\subsection*{Command Line Usage of uFldObstcleSim}
\label{sec_ufos_cmdline}

The \app{uFldObstcleSim} application is typically launched as a part
of a batch of processes by \app{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:

\vspace{0.1in}
\begin{consoleverb}
 $ uFldObstacleSim --help or -h
\end{consoleverb}
\vspace{0.1in}

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

\vspace{0.1in}
\begin{listing}{Command line usage for the \app{UFldObstacleSim} tool}
\label{lst_ufos_usage}
\footnotesize
\begin{verbatim}
  1  ==========================================================
  2  Usage: uFldObstcleSim file.moos [OPTIONS]               
  3  ==========================================================
  4                                                            
  5  Options:                                                  
  6    --alias=&lt;ProcessName&gt;                                
  7        Launch uFldObstcleSim with the given process      
  8        name rather than uFldObstcleSim.                  
  9    --example, -e                                           
 10        Display example MOOS configuration block.           
 11    --help, -h                                              
 12        Display this help message.                          
 13    --interface, -i                                         
 14        Display MOOS publications and subscriptions.        
 15    --version,-v                                            
 16        Display release version of uFldObstcleSim.        
 17    --verbose=&lt;setting&gt;                                  
 18        Set verbosity. true or false (default)              
 19                                                            
 20  Note: If argv[2] does not otherwise match a known option, 
 21        then it will be interpreted as a run alias. This is 
 22        to support pAntler launching conventions.           
\end{verbatim}
\end{listing}
\normalsize
 
%=================================================================
\section{Terminal and AppCast Output}
%=================================================================
\label{sec_ufos_appcast}

The \app{UFldObstacleSim} application produces some useful
information to the terminal and identical content through
appcasting. An example is shown in Listing \ref{lst_ufos_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(204)} indicates there are no configuration or run warnings,
and the current iteration of \app{UFldObstacleSim} is 204. Lines 5-9
show the obstacle file configuration. Lines 10-12 indicate whether
ground truth obstacles or simulate sensor points will be generated.
Lines 13-15 indicate the range of random durations associated with
each obstacle. Lines 16-18 indicate whether the simulator will
periodically reset the obstacle locations and if so, how often.

\vspace{0.1in}
\noindent
Lines 20-28 reveal the current state of the simulator. Lines 21-22
show how many times the polygon obstacles have been posted as viewable
polygons and how many times as given polygons respectively. Lines 23-28
show the state with respect to possibly resetting the obstacles. Line 24
shows the distance between the obstacle region to the closest vehicle. The
zero in this case indicates that one or more vehicles are inside the
obstacle region. Lines 25-28 show the progress toward potentially resetting
the obstacles. 

\vspace{0.1in}
\noindent
Lines 31-38 show key information related to each obstacle. Column 3 will
show total simulated sensor points published per obstacle, if in the
{\em points} mode. Column 4 will be used when given obstacles are published,
and incremented each time they are published.

\vspace{0.2in}
\begin{listing}{Example \app{UFldObstacleSim} console output}
\label{lst_ufos_appcast}
\footnotesize
\begin{verbatim}
 1  ===================================================================
 2  uFldObstacleSim shoreside                                  0/0(204)
 3  ===================================================================
 4  ================================
 5  Config (Obstacles) 
 6    Obstacles: 5
 7    MinRange:  20
 8    MinSize:   6
 9    MaxSize:   10
10  Config (Points)  
11    Post Points:   false
12    Rate Points:   5
13  Config (Duration) 
14    Min Duration: 400.0
15    Max Duration: 500.0
16  Config (Reset)  
17    Reset Range:  10
18    Reset_Interv: -1
19  ================================
20  State               
21    Viewables Posted: 1
22    Obstacles Posted: 2
23  State (resetting)   
24    Min Poly Range: 0
25    Reset Pending:  false
26    Newly Exited :  false
27    Reset Tstamp :  23867167818
28    Reset Total  :  0
29  
30  
31  Obs   Obs       Points     Given    
32  Key   Duration  Published  Published
33  ----  --------  ---------  ---------
34  ob_0  468.1     0          2        
35  ob_1  470.1     0          2        
36  ob_2  478.2     0          2        
37  ob_3  451.7     0          2        
38  ob_4  445.3     0          2        
\end{verbatim}
\end{listing}
\normalsize

\end{document}

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