<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{Geometry Utilities}
\vspace{0.1in}
\labdate{June 2018}
\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.Geometry}
\wikidoc{bugz=Geometry}
\wikidoc{auth=mikerb@mit.edu}

%====================================================================
\section{Overview}
%====================================================================
\label{util_geometry}
%\index{Geometry Utilities}

This section discusses a few geometry data structures often used by
the helm and the \app{pMarineViewer} application - convex polygons,
lists of line segments, points, seglrs and vectors. These data
structures are implemented by the classes \var{XYPolygon},
\var{XYSegList}, \var{XYPoint}, \var{XYSeglr} and \var{XYVector}
respectively in the \var{lib\_geometry} module distributed with the
MOOS-IvP software bundle. The implementation of these class
definitions is somewhat shielded from the helm user's perspective, but
they are often involved in parameter settings of for behaviors. So the
issue of how to specify a given geometric structure with a formatted
string is discussed here.

\pskip

Furthermore, the \app{pMarineViewer} application accepts these data
structures for rendering by subscribing to three MOOS variables
\mvar{VIEW\_POLYGON}, \mvar{VIEW\_SEGLIST}, \var{mVIEW\_POINT}, anv
\mvar{VIEW\_VECTOR}. These variables contain a string format
representation of the structure, often with further visual hints on
the color or size of the edges and vertices for rendering. These
variables may originate from any MOOS application, but are also often
posted by helm behaviors to provide visual clues about what is going
on in the vehicle. In the Alpha mission, for example, the waypoint
behavior posted a seglist representing the set of waypoints for which
it was configured, as well as posting a point indicating the next
point on the behavior's list to traverse.

%====================================================================
\section{General Geometric Object Properties}
%====================================================================
\label{sec_xyobj_params}

Each of the four geometric objects, \var{XYPolygon}, \var{XYSegList},
\var{XYPoint}, and \var{XYVector}, are a subclass of the general
\var{XYObject} class, and share certain properties discussed here.

\vspace{0.1in}
\begin{figure}[ht]
  \centering 
  \includegraphics[width=0.4\textwidth]{figures/classes.png}
  \caption{{\bf Class hierarchy:} All geometric objects are subclasses
    of the \vvar{XYObject} class.}
\label{fig_geo_classes}
\end{figure}
\vspace{0.12in}

%====================================================================
\subsection*{Common Properties}

The following properties are defined at the \var{XYObject} level. All
properties may be optionally left undefined by the user.

\begin{itemize}
\item {\em label}: A string that is often rendered in a GUI alongside
  the object rendering. In the \app{pMarineViewer} application, the
  label is also used as a unique identifier and successive receipt of
  geometric objects with the same label will result in the new one
  replacing" the older one. Thus the visual effect of "moving"
  objects is rendered in this way.
\item {\em msg}: A string typically regarded as an alternative to the
  label string when rendering an object. In the \app{pMarineViewer}
  application, if an object has a non-null {\em msg} field, this will
  be used for rendering the label instead of the {\em label} field.
\item {\em type}: A string conveying some information on the type of
  the object from the source application. For example a point may be
  of type "waypoint" or "rendez-vous", and so on. 
\item {\em time}: The time field is a double that may optionally be
  set to indicate when the point was generated, or how long it should
  exist before â€œexpiringâ€, or however an application may wish to
  interpret it.
\item {\em source}: A string representing the source that generated the
  object. This may distinguish MOOS applications or helm behaviors for
  example.
\end{itemize}
  
%====================================================================
\subsection*{Rendering Hint Properties}

The following optional properties are defined at the \var{XYObject}
level for providing hints to applications that may be using them
for rendering. 

\begin{itemize}
\item {\em active}: This is a Boolean that is regarded as \var{true}
  if left unspecified, and is used to indicate whether or not the
  object should be rendered. By setting this value to \var{false} for
  a given object, it would effectively be erased in the
  \app{pMarineViewer} application for example.
\item {\em vertex\_size}: This non-negative floating point value is 
  a hint for how large to draw a vertex point for the given object.
  If left unspecified in the \app{pMarineViewer} application for example,
  the size of the vertex would be determined by the global setting for
  vertices set in the GUI.
\item {\em edge\_size}: This non-negative floating point value is a
  hint for how wide to draw an edge for the given object (if it has
  edges).  If left unspecified in the \app{pMarineViewer} application
  for example, the width of the edge would be determined by the global
  setting for edges set in the GUI.
\item {\em vertex\_color}: This parameter specifies a hint or request
  to draw the vertices in this object in the given color
  specification.  Colors may be specified by any defined color string
  or RGB string value as described in the Colors Appendix.  In
  the \app{pMarineViewer} application, if this hint is not provided
  for received objects, the vertex color would be determined by the
  global setting for vertices set in the GUI. If the color is set to
  \var{"invisible"}, this is effectively a request that the vertex not
  be rendered.
\item {\em edge\_color}: This parameter specifies a hint or request to
  draw the edgees in this object in the given color specification.
  Colors may be specified by any defined color string or RGB string
  value as described in the Colors Appendix.  In the
  \app{pMarineViewer} application, if this hint is not provided for
  received objects, the edge color would be determined by the global
  setting for edges set in the GUI. If the color is set to
  \var{"invisible"}, this is effectively a request that the edge not be
  rendered.
\item {\em label\_color}: This parameter specifies a hint or request
  to draw the label for this object in the given color specification.
  Colors may be specified by any defined color string or RGB string
  value as described in the Colors Appendix.  In the
  \app{pMarineViewer} application, if this hint is not provided for
  received objects, the label color would be determined by the global
  setting for labels set in the GUI. If the color is set to
  \var{"invisible"}, this is effectively a request that label not be
  rendered.
\end{itemize}
  
%====================================================================
\section{Points}
%====================================================================
\label{sec_points}

Points are implemented in the \var{XYPoint} class, and minimally
represent a point in the x-y plane. These objects are used internally
for applications and behaviors, and may also be involved in rendering
in a GUI and therefore may have additional fields to support this as
described in Section \ref{sec_xyobj_params}.

%====================================================================
\subsection{String Representations for Points}
\label{sec_points_strings}
%\index{Geometry Utilities!Points}
%\index{Points}

The only required information for a point specification is its
position in the x-y plane. A third value may optionally be specified
in the z-plane. If $z$ is left unspecified, it will be set to
zero. The standard string representation is a comma-separated list of
param=value pairs like the following examples:

\vspace{0.1in}
\small
\begin{verbatim}
 point   = x=60, y=-40
 point   = x=60, y=-40, z=12
 point   = z=19, y=5, x=23
\end{verbatim}
\normalsize
\vspace{0.1in}

\noindent
Partly for backward compatibility, a very simplified string representation
of a point is also supported:

\vspace{0.1in}
\small
\begin{verbatim}
 point   = 60,-40
 point   = 60, -40, 0
\end{verbatim}
\normalsize
\vspace{0.1in}

\noindent
An example of string representation of point with all the optional
parameters described in Section \ref{sec_xyobj_params} might look 
something like:

\vspace{0.1in}
\small
\begin{verbatim}
 point   = x=60, y=-40, label=home, label_color=red, source=henry, type=waypoint,
           time=30, active=false, vertex_color=white, vertex_size=5, msg=bingo 

\end{verbatim}
\normalsize
\vspace{0.1in}

\noindent
Note that although a few different string formats are supported for
{\em specifying} a point, only a single format is used when a
\var{XYPoint} object is serialized into a string representation. 


%====================================================================
\section{Seglists}
%====================================================================
\label{sec_seglist_strings}
%\index{Geometry Utilities!Seglists}
%\index{Seglists}

Seglists are implemented in the \var{XYSegList} class and are comprised of
an ordered set of vertices, implying line segments between each vertex.
Seglist instances may be used for many things, but perhaps most often used
to represent a set of vehicle waypoints. The geometry library has a number
of basic operations defined for this class such as intersection testing
with other objects, rotation, proximity testing and so on.

%====================================================================
\subsection{Standard String Representation for Seglists}

The only requirement for a seglist specification is one or more vertex
locations in the $x,y$ plane. Values may optionally be specified in the
$z$ plane. If $z$ is left unspecified it will default to zero. The
standard string representation is a comma-separated list of param=value
pairs like the following examples:

\vspace{0.1in}
\small
\begin{verbatim}
 points   = pts={60,-40:60,-160:150,-160:180,-100:150,-40},label=foxtrot,type=top
\end{verbatim}
\normalsize
\vspace{0.1in}

\noindent
By "standard" format we mean it is not only accepted as
initialization input, but is also the format produced when an existing
instance is serialized using the object's \var{string
  XYSeglist::get\_spec()} function. If $z$ values are used, an example
may look like the following which is the same as the above but
associates $z=2$ with each point:

\vspace{0.1in}
\small
\begin{verbatim}
 points = pts={60,-40,2:60,-160,2:150,-160,2:180,-100,2:150,-40,2},label=foxtrot
\end{verbatim}
\normalsize
\vspace{0.1in}

\noindent
An example of a string representation with all the optional parameters
described in Section \ref{sec_xyobj_params} might look something like:

\vspace{0.1in}
\small
\begin{verbatim}
 points = {pts=60,-40,2:60,-160,2:150,-160,2:180,-100,2:150,-40,2},label=foxtrot
          label_color=green, source=henry, type=return_path, time=30, active=false, 
          vertex_color=white, vertex_size=5, edge_size=2, edge_color=red, msg=bingo 
\end{verbatim}
\normalsize

%====================================================================
\subsection{The Lawnmower String Representation for Seglists}
\label{sec_geometry_lawnmower}

Seglists may also be built using the \var{lawnmower} format. The following
is an example:

\vspace{0.1in}
\small
\begin{verbatim}
 points = format=lawnmower, label=foxtrot, x=0, y=40, height=60, width=180,
          lane_width=15, rows=north-south, startx=20, starty=-300, degs=45
\end{verbatim}
\normalsize
\vspace{0.1in}

\noindent
The rotation of the pattern can optionally be specified in
radians. For example, \var{degs=45} is equivalent to
\var{rads=0.785398}. If, for some reason, both are specified, the
seglist will be built using the \var{rads} parameter. 


\vspace{0.15in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.88\textwidth]{figures/lmower_ew_ns.png}
  \caption{{\bf Seglists built with the \vvar{lawnmower} format:} The
    pattern is specified by (a) the location of the center of the
    pattern, (b) the height and width of the pattern, (c) the lane
    width which determines the number of rows, (d) whether the pattern
    rows proceed north-south or east-west, and (e) an optional
    rotation of the pattern.}
\label{fig_segl_lmower}
\end{figure}
\vspace{0.15in}

\noindent
The \var{startx} and \var{starty} parameters name a point in the xy-plane
to influence the starting position of the pattern. The seglist has four
possible starting positions, and chosen starting position will be the position
closest to the (\var{startx}, \var{starty}) position. The \var{startx} and 
\var{starty} parameters are optional and default to zero. Users sometimes may 
which to use a vehicle's present x-y position for these parameters.


%====================================================================
\subsection{Seglists in the pMarineViewer Application}

The \app{pMarineViewer} application registers for the MOOS variable 
\mvar{VIEW\_SEGLIST}. The viewer maintains a list of seglists keyed on the
label field of each incoming seglist. A seglist received with a thus far
unique label will be added to the list of seglists rendered in the 
viewer. A seglist received with a non-unique label will replace the seglist
with the same label in the memory of the viewer. This has the effect
of erasing the old seglist since each iteration of the viewer redraws
everything, the background and all objects, from scratch several times
per second. 

\pskip
The label is the only text rendered with the seglist in
\app{pMarineViewer}.  Since the label is also used as the key, if the
user trys to "update" the label, or use the label to convey changing
information, this may inadvertently result in accumulating multiple
seglists in the viewer, each drawn over one another. Instead, the
\mvar{VIEW\_SEGLIST} may be posted with the message to be posted in the
\var{msg=value} component. When this component is non-null,
\app{pMarineViewer} renders it instead of the contents in the label
component.

%====================================================================
\section{Polygons}
%====================================================================
\label{sec_polygons}

Polygons are implemented in the \var{XYPolygon} class. This
implementation accepts as a valid construction only specifications
that build a convex polygon. Common operations used internally by
behaviors and other applications, such as intersection tests, distance
calculations etc, are greatly simplified and more efficient when
dealing with convex polygons.

%====================================================================
\subsection{Supported String Representation for Polygons}
\label{sec_polygons_strings}

The only requirement for a polygon specification is three or more
vertex locations in the $x,y$ plane constituting a convex
polygon. Values may optionally be specified in the $z$ plane. If $z$
is left unspecified it will default to zero. The standard string
representation is a comma-separated list of param=value pairs like the
following examples:

\small
\begin{verbatim}
      points   = pts={60,-40:60,-160:150,-160:150,-40},label=foxtrot,type=one
\end{verbatim}
\normalsize

\noindent
By "standard" format we mean it is not only accepted as initialization
input, but is also the format produced when an existing instance is
serialized using the object's \var{string XYPolygon::get\_spec()}
function. If $z$ values are used, an example may look like the
following which is the same as the above but associates $z=4$ with
each point:

\small
\begin{verbatim}
 points   = pts={60,-40,4:60,-160,4:150,-160,4:150,-40,4},label=foxtrot,type=one
\end{verbatim}
\normalsize

Polygons are defined by a set of vertices and the simplest way to
specify the points is with a line comprised of a sequence of
colon-separated pairs of comma-separated x-y points in local
coordinates such as:

\small
\begin{verbatim}
  polygon   = 60,-40:60,-160:150,-160:180,-100:150,-40:label,foxtrot
\end{verbatim}
\normalsize

\noindent
If one of the pairs, such as the last one above, contains the keyword
\var{label} on the left, then the value on the right, e.g.,
\var{foxtrot} as above, is the label associated with the polygon.  An
alternative notation for the same polygon is given by the following:

\small
\begin{verbatim}
  polygon   = label=foxtrot, pts={60,-40:60,-160:150,-160:180,-100:150,-40}
\end{verbatim}
\normalsize

\noindent
This is an comma-separated list of equals-separated pairs. The
ordering of the comma-separated components is insignificant. The
points describing the polygon are provided in braces to signify to the
parser that everything in quotes is the right-hand side of the
\var{pts=} component. Both formats are acceptable specifications of a
polygon in a behavior for which there is a \var{polygon} parameter.

%====================================================================
\subsection{A Polygon String Representation using the Radial Format}

Polygons may also be specified by their shape and the shape
parameters. For example, a commonly used polygon is formed by points
of an equal radial distance around a center point. The following is an
example:

\small
\begin{verbatim}
 polygon = format=radial, label=foxtrot, x=0, y=40, radius=60, pts=6, snap=1
\end{verbatim}
\normalsize

\noindent
The \var{snap} component in the above example signifies that the
vertices should be rounded to the nearest 1-meter value. The \var{x}, 
\var{y} parameters specify the middle of the polygon, and \var{radius}
parameters specify the distance from the center for each vertex. The
\var{pts} parameters specifies the number of vertices used, as shown
in Figure \ref{fig_poly_radial}.

\vspace{0.1in}
\begin{figure}[ht]
  \centering 
  \includegraphics[width=0.9\textwidth]{figures/polygons_radial.png}
  \caption{{\bf Polygons built with the \vvar{radial} format:} Radial
    polygons are specified by (a) the location of their center, (b)
    the number of vertices, and (c) the radial distance from the
    center to each vertex. The lighter vertex in each polygon
    indicates the first vertex if traversing in sequence, proceeding
    clockwise.}
\label{fig_poly_radial}
\end{figure}

%====================================================================
\subsection{A Polygon String Representation using the Ellipse Format}

Polygons may also be built using the \var{ellipse} format. The
following is an example:

\small
\begin{verbatim}
 polygon   = label=golf, format=ellipse, x=0, y=40, degs=45, pts=14, snap=1,
             major=100, minor=70
\end{verbatim}
\normalsize

The \var{x}, \var{y} parameters specify the middle of the polygon, the
\var{major} and \var{minor} parameters specify the radial distance of
the major and minor axes. The \var{pts} parameters specifies the
number of vertices used, as shown in Figure \ref{fig_poly_ellipse}.

\vspace{0.08in}
\begin{figure}[ht]
  \centering 
  \includegraphics[width=0.9\textwidth]{figures/polygons_ellipse.png}
  \caption{{\bf Polygons built with the \vvar{ellipse} format:}
    Ellipse polygons are specified by (a) the location of their
    center, (b) the number of vertices, (c) the length of their major
    axis, (d) the length of their minor axis, and (e) the rotation of
    the ellipse.The lighter vertex in each polygon indicates the first
    vertex if traversing in sequence, proceeding clockwise.}
\label{fig_poly_ellipse}
\end{figure}
\vspace{0.15in}

The rotation of the ellipse can optionally be specified in
radians. For example, \var{degs=45} is equivalent to
\var{rads=0.785398}. If, for some reason, both are specified, the
polygon will be built using the \var{rads} parameter. When using the
ellipse format, a minimum \var{pts=4} must be specified.


%====================================================================
\subsection{Optional Polygon Parameters}

Polygons also may have several optional fields associated with them.
The \var{label} field is string that is often rendered with a polygon
in MOOS GUI applications such as the \app{pMarineViewer}. The
\var{label\_color} field represents a color preference for the label
rendering.  The \var{type} and \var{source} fields are additional
string fields for further distinguishing a polygon in applications
that handle them. The \var{active} field is a Boolean that is used in
the \app{pMarineViewer} application to indicate whether the the
polygon should be rendered. The \var{time} field is a double that may
optionally be set to indicate when the polygon was generated, or how
long it should exist before "expiring", or however an application may
wish to interpret it.  The \var{vertex\_color}, \var{edge\_color}, and
\var{vertex\_size} fields represent further rendering preferences. The
following are two equivalent further string representations:

\small
\begin{verbatim}
      polygon = format=radial, x=60, y=-40, radius=60, pts=8, snap=1, label=home, 
                label_color=red, source=henry, type=survey, time=30, active=true, 
                vertex_color=white, vertex_size=5, edge_size=2
      polygon = format,radial:60,-40:radius,60:pts,8:snap,1:label,home:
                label_color,red:source,henry:type,survey:time,30:active,true:
                vertex_color,white:vertex_size,5:edge_size,2
\end{verbatim}
\normalsize

\noindent
The former is a more user-friendly format for specifying a polygon,
perhaps found in a configuration file for example. The latter is the
string representation passed around internally when \var{XYPolygon}
objects are automatically converted to strings and back again in the
code. This format is more likely to be found in log files or seen when
scoping on variables with one of the MOOS scoping tools.


%====================================================================
\section{Seglrs}
%====================================================================
\label{sec_seglrs}

Seglrs are implemented in the \var{XYSeglr} class and are essentially
comprised of list of line segments followed by a ray. They may be used
in certain applications to indicate a ship maneuver.  Minimally each
seglr consists of at least one vertext in the $x,y$ plane (but
typically more, indicating a series of line segments), and the
direction of the ray. They may also be configured with all relevant
drawing hints discussed in Section \ref{sec_xyobj_params}.

%====================================================================
\subsection{String Representations for Seglrs}
\label{sec_seglr_strings}

Seglr objects may be initialized from a string representation, and
converted to a string representation from an existing object. The
following is an example:

\small
\begin{verbatim}
   seglr = pts={5,5:30,10:90,-20},ray=45
\end{verbatim}
\normalsize

\noindent
The following is a string example using many of the general object
fields and drawing hints available:

\small
\begin{verbatim}
   seglr = pts={5,5:30,10:90,-20},ray=45,            &lt;-- defines the seglr
           ray_len=10,head_size=3,                   &lt;-- seglr drawing hints
           label=alpha,edge_color=red,edge_size=2,   &lt;-- general object
           vertex_size=3,vertex_color=green          &lt;--   drawing hints
\end{verbatim}
\normalsize

\noindent
The parameters, \var{ray\_len=10} and \var{"head\_size=3"}, are
drawing hints unique to the seglr object and refers to how big the
arrow head should be rendered and how long the ray should be
rendered. They are given in meters, and the default is
\var{ray\_len=10} and \var{head\_size=3}.


%====================================================================
\subsection{Seglrs in the pMarineViewer Application}

The \app{pMarineViewer} application registers for the MOOS variable 
\mvar{VIEW\_SEGLR}. The viewer maintains a list of seglrs keyed on the
label field of each incoming seglr. A seglr received with a thus far
unique label will be added to the list of seglrs rendered in the 
viewer. A seglr received with a non-unique label will replace the seglr
with the same label in the memory of the viewer. This has the effect
of erasing the old seglr since each iteration of the viewer redraws
everything, the background and all objects, from scratch several times
per second. 

\pskip
The \mvar{VIEW\_VECTOR} may be posted with the message label, to be
posted just beyond the arrow head. This is done with the \var{msg}
component of the posting.  For example:

\vspace{0.15in}
\begin{verbatim}
  VIEW_SEGLR = pts={5,5:30,10:90,-20},ray=45,ray_len=10,head_size=3,  \
               label=alpha,edge_color=red,edge_size=2,msg=alpha
\end{verbatim}


%====================================================================
\section{Vectors}
%==================================================================== 
\label{sec_vectors}

Vectors are implemented in the \var{XYVector} class and are essentially
comprised of a location, direction and magnitude. They may be used in
certain applications dealing with simulated or sensed forces, or simply
used in a GUI application to render current fields or an instantaneous
vehicle pose and trajectory. Minimally each vector consists of a location
in the $x,y$ plane and a direction and magnitude. They may also be
configured with all relevant drawing hints discussed in Section
\ref{sec_xyobj_params}.


%==================================================================== 
\subsection{String Representations for Vectors}
\label{sec_vector_strings}

Vector objects may be initialized from a string representation, and
converted to a string representation from an existing object. The
following is an example:

\small
\begin{verbatim}
      vector = x=5,y=10,ang=45,mag=20
\end{verbatim}
\normalsize

\noindent
Alternatively, instead of expressing the vector in terms of its
direction and magnitude, it may also be given in terms of its
magnitude in both the $x$ and $y$ direction. The following vector is
nearly identical, modulo rounding errors, to the above configured
vector:

\small
\begin{verbatim}
      vector = x=5,y=10,xdot=12.142,ydot=12.142
\end{verbatim}
\normalsize

\noindent
When a vector object is serialized to a string by invoking the
object's native serialization function, the first of the two above
formats will be used. The following is a string example using many of
the general object fields and drawing hints available:

\small
\begin{verbatim}
      vector = x=5,y=10,ang=45,mag=20,label=pingu,source=simulator,type=wind,
               vertex_size=2,vertex_color=red,edge_color=red,edge_size=2,head_size=12
\end{verbatim}
\normalsize

\noindent
The last parameter, \var{"head\_size=12"}, is a drawing hint unique to
the vector object and refers to how big the arrow head should be
rendered. If left unspecified, it may simply be rendered at whatever
size the GUI application uses by default.

%==================================================================== 
\subsection{Vectors in the pMarineViewer Application}

The \app{pMarineViewer} application registers for the MOOS variable 
\mvar{VIEW\_VECTOR}. The viewer maintains a list of vectors keyed on the
label field of each incoming vector. A vector received with a thus far
unique label will be added to the list of vectors rendered in the 
viewer. A vector received with a non-unique label will replace the vector
with the same label in the memory of the viewer. This has the effect
of erasing the old vector since each iteration of the viewer redraws
everything, the background and all objects, from scratch several times
per second. 

\pskip
The label is the only text rendered with the vector in
\app{pMarineViewer}.  Since the label is also used as the key, if the
user trys to "update" the label, or use the label to convey changing
information, this may inadvertently result in accumulating multiple
vectors in the viewer, each drawn over one another. Instead, the
\mvar{VIEW\_VECTOR} may be posted with the message to be posted in the
\var{msg=value} component. When this component is non-null,
\app{pMarineViewer} renders it instead of the contents in the label
component.

\end{document}

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