<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{pickpos: A Tool for Preparing Missions}
\vspace{0.1in}
\labdate{Sep 2023}
\vspace{0.1in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Department of Mechanical Engineering}
\labauth{MIT, Cambridge MA 02139}
\labsrc{project-pavlab/apps/app\_pickpos}
\labtoc{small}
\end{labcover}

\wikidoc{file=IvPTools.PickPos}
\wikidoc{bugz=pickpos}
\wikidoc{auth=mikerb@mit.edu}

%=================================================================
\section{Overview}
%=================================================================
\label{sec_pickpos}
%\index{pickpos}

The \cmd{pickpos} utility is a command-line tool for generating
starting points for simulated vehicles. It can generate points from a
set of points given in a file, or by picking random points from within
one or more convex polygons. The starting heading position can also be
chosen, in a random range, or relative to a given position.  Vehicle
names, group names, vehicle speeds, and vehicle colors may also be
generated.

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

\vspace{0.1in}
\begin{consoleverb}
$ pickpos --amt=4 --polygon="60,-40:60,-160:150,-160"
x=100,y=-139
x=136,y=-146
x=64,y=-103
x=75,y=-73
\end{consoleverb}
\vspace{0.1in}

\noindent
Points will be chosen from the given convex polygon.  Note the
requested amount is 4, and 4 lines were generated.

\vspace{0.1in}
\noindent
This \cmd{pickpos} web page can be opened on most systems from the command
line with \var{pickpos --web}. Running \var{pickpos --help} will also show
the supported command line options.

%=================================================================
\subsection{Motivation and Intended Usage}

The motivation for \cmd{pickpos} is to support simulations of multiple
vehicles. Certain vehicle simulation parameters, such as position,
heading, and speed, may need to be randomized. However, it may be
important to bound the random values. For example, we may want to pick
vehicle positions within a certain region, or set of regions. However,
it may also be important to ensure that no two vehicles are too close
to each other to start with.

\vspace{0.1in}
\noindent
As with the example above, the \cmd{pickpos} output is in the form of
several lines written to the terminal window. The typical usage is to
re-direct this output to a file. 

\vspace{0.1in}
\begin{consoleverb}
$ pickpos --amt=4 --polygon="60,-40:60,-160:150,-160" &gt; positions.txt
$ ls 
positions.txt
$ cat positions.txt
x=100,y=-139
x=136,y=-146
x=64,y=-103
x=75,y=-73
\end{consoleverb}
\vspace{0.1in}

\noindent
The resulting file contains as many lines as prescribed in the \var{--amt=N}
argument. The information in this file may be used by any other tool, but
in our lab, it will likely be ingested within a bash script, into a
bash array:

\vspace{0.1in}
\begin{consoleverb}
VEHPOS=(`cat positions.txt`)
\end{consoleverb}
\vspace{0.1in} 

\noindent
This array can then be used later in the script to assign the Nth vehicle
the starting position found at the Nth position in the array. This strategy
is repeated for other starting features, e.g. the vehicle name, vehicle color.
For example:

\vspace{0.1in}
\begin{consoleverb}
$ pickpos --amt=4 --vnames &gt; vnames.txt
$ ls 
vnames.txt
$ cat vnames.txt
abe
ben
cal
deb
\end{consoleverb}
\vspace{0.1in}

\vspace{0.1in}
\begin{consoleverb}
VNAMES=(`cat vname.txt`)
\end{consoleverb}
\vspace{0.1in} 

%=================================================================
\subsection{Picking Vehicle Locations with Separation}

In the example above, \cmd{pickpos} generated four points within the
specified polygon. The four chosen points are also at least 10 meters
apart. The 10 meter buffer range is the default, and can be overridden
with the \var{--buffer=N} argument.  \cmd{pickpos} will successively
choose a random point in the polygon, each time checking to see if it
satisfies the buffer distance. If not, a new point will be chosen. For
each point, \cmd{pickpos} will retry to satisfy the buffer criteria
up to 1000 times. This can be overridden with the \var{--maxtries=N}
parameter.

\vspace{0.1in}
\noindent
At some point, based on the polygon size and number of requested
points and buffer distance, it will become impossible to squeeze in
any more points while satisfying the buffer criteria. In this case
\cmd{pickpos} will automatically scale back the buffer distance each
time the maxtries (default is 1000) has failed to produce a point.
On each successive round, the buffer distance will be scaled back to
be 90 per cent of its previous value. 

\vspace{0.1in}
\noindent
If \cmd{pickpos} is run with the \var{--verbose} option, the points will
be produced along with the min distance from each point to all the other
points:


\vspace{0.1in}
\begin{consoleverb}
$ pickpos --amt=4 --polygon="60,-40:60,-160:150,-160" --verbose
x=146,y=-155   nearest=80.40
x=77,y=-93   nearest=14.76
x=76,y=-75   nearest=18.03
x=66,y=-147   nearest=47.04
\end{consoleverb}
\vspace{0.1in}

\noindent
Try running the above example with \var{--amt=50}. Most points will be
at least 10 meters apart, but some have been relaxed. Very few, if any,
will be closer than 8 meters. 

\vspace{0.1in}
\noindent
Note however, the \var{nearest} information on each line will likely
interfere with the consumers of this file. The consumer, at least in
our case, is quite particular about the format of each line, so the
\var{nearest=N} component at the end of each line will likely break
things further down the road. So it is best to only run
\var{--verbose} to gauge how well \cmd{pickpos} is handling the current
parameters, and then re-run without it.

%=================================================================
\subsection{Picking Vehicle Locations from Multiple Polygons}

If multiple polygons are provided on the command-line, \cmd{pickpos}
will generate random points across polygons. For example:

\vspace{0.1in}
\begin{consoleverb}
$ pickpos --amt=4 --polygon="60,-40:60,-160:150,-160" \
                  --polygon="260,-40:260,-160:350,-160" \
                  --polygon="460,-40:460,-160:550,-160" \
\end{consoleverb}
\vspace{0.1in}

\noindent
It does not matter if the given polygons overlap. It {\em does} matter
if the polygon is non-convex. Only individual convex polygons may be
given. However, clearly a non-convex region can be represented by
several convex polygons.

\vspace{0.1in}
\noindent
Note: The \cmd{pickpos} algorithm, when choosing a random point using
multiple polygons, first chooses a random polygon. The weight given to
each polygon is the same. So if you have one polygon that is 100x
bigger than the second one, the distribution of points between the two
will be roughly the same, not 100 to 1.

%=================================================================
\subsection{Picking Vehicle Locations from a Pre-Set List}

If the users wishes to choose random vehicle locations from a pre-set list
of locations stored in a file, this can be done with the \var{--posfile}
argument as follows:

\vspace{0.1in}
\begin{consoleverb}
$ pickpos --amt=4 --posfile=file.txt
\end{consoleverb}
\vspace{0.1in}

\noindent
This presumes that a file has been previously generated, either by
hand, with \cmd{pickpos}, or some other means. Each choice will be a
random choice from the file. No choice will be picked twice, all
choices are unique if the lines in the file are unique. If the number
of choices requested with the \var{--amt=N} argument are greater than
the number of lines in the input file, no choices will be made, and
\cmd{pickpos} will exit with a value of 1, rather than the normal exit
value of 0.



%=================================================================
\subsection{Picking Vehicle Names}

With the \var{--vnames} argument, \cmd{pickpos} will generate a set of
vehicle names. These names are not random. They are from a hard-coded
list of names in alphabetical order. This is handy in certain missions
that are built to launch any number of vehicles. This ensures unique
names across all vehicles. In practice there is a strong preference
for very short, pair-wise distinct, and alphabetical naming. Using
\cmd{pickpos} for generating names ensures the above preferences and
provides some consistency across missions.

\vspace{0.1in}
\noindent
The first 26 names are three-letter names:

\vspace{0.1in}
\noindent
\var{abe,ben,cal,deb,eve,fin,gil,hal,ike,jim,kim,lou,mal,ned,opi,pal,que,ray,} \newline
\noindent
\var{sam,tim,ula,val,wes,xiu,yen,zan}

\vspace{0.1in}
\noindent
The second set of 26 names are four-letter names:

\vspace{0.1in}
\noindent
\var{apia,baka,cary,doha,evie,fahy,galt,hays,iola,jing,kiev,lima,mesa,nuuk,oslo,} \newline
\noindent
\var{pace,quay,rome,sako,troy,ubly,vimy,waco,xane,york,zahl}

\vspace{0.1in}
\noindent
Note: Currently only 52 unique names are supported. The 53rd name will
revert to being \var{abe}.  This likely will be extended in a future
release.

\vspace{0.1in}
\noindent
If the user wishes to use a few names in addition to the pre-set list,
this can be done as follows:

\vspace{0.1in}
\begin{consoleverb}
$ pickpos --amt=5 --vnames=fred,james,bingo
fred
james
bingo
deb
eve
\end{consoleverb}
\vspace{0.1in}

\noindent
The explicitly given names will be used first, followed by the normal
sequence of names.

\vspace{0.1in}
\noindent
To generate names in reverse use the \var{--reverse\_names} or
\var{-r} argument in addition to the \var{--vnames} argument.
\cmd{pickpos} will generate its list by starting from \var{zahl} and
working backwards.

\vspace{0.1in}
\begin{consoleverb}
$ pickpos --amt=5 --vnames -r
zahl
york
xane
waco
vimy
\end{consoleverb}
\vspace{0.1in}

%=================================================================
\subsection{Picking Vehicle Speed}

Random speed values may be generated with \cmd{pickpos} using the
\var{--spd=LOW:HIGH} argument. For example:

\vspace{0.1in}
\begin{consoleverb}
$ pickpos --amt=5 --spd=2:8
5.4
7
2.4
6.5
7.9
\end{consoleverb}
\vspace{0.1in}

\noindent
Note that values are rounded to the nearest 0.1. If a different resolution
is desired, the \var{-ssnap=N} argument will be used. By default N=0.1.

\vspace{0.1in}
\begin{consoleverb}
$ pickpos --amt=5 --spd=2:8 --ssnap=0.05
2.15
2.45
4.95
2.6
6.45
\end{consoleverb}
\vspace{0.1in}

\noindent
There is no reason why this argument cannot be used for generating other
random values in a given range. However, since this switch was originally
created to generate random {\em speeds}, negative values are not supported.
An error will be thrown (a return value of 1) if the LOW value is higher
than the HIGH value. If the LOW value is equal to the HIGH value, that is
fine, and will deterministically generate lines with the LOW/HIGH value.

%=================================================================
\subsection{Picking Vehicle Headings (In a Random Range)}

As with choosing speeds discussed above, random heading values may be
generated with \cmd{pickpos} using the \var{--hdg=LOW:HIGH}
argument. For example:

\vspace{0.1in}
\begin{consoleverb}
$ pickpos --amt=5 --hdg=135:225
211
162
144
145
202
\end{consoleverb}
\vspace{0.1in}

\noindent
If the range of values wraps around true north (zero degrees), then the
range to use is $[-180,180]$. For example to use:

\vspace{0.1in}
\begin{consoleverb}
$ pickpos --amt=5 --hdg=-10:10
10
5
354
7
357
\end{consoleverb}
\vspace{0.1in}

\noindent
NOT:

\vspace{0.1in}
\begin{consoleverb}
$ pickpos --amt=5 --hdg=350:10
Unhandled arg: --hdg=350:10
\end{consoleverb}
\vspace{0.1in}

%=================================================================
\subsection{Picking Vehicle Headings (Relative to a Point)}

Sometime it is useful to choose a heading relative to a given point,
e.g., the center of a polygon, or destination.  This can be done by
specifying the point, and the relative bearing. {\em This mode is
  supported only when also generating random points.}
For example, the following chooses a heading pointing directly toward
the point $(5,5)$ from the randomly generated point:

\vspace{0.1in}
\begin{consoleverb}
$ pickpos --amt=5 --polygon="0,0:10,0:10,10:0,10" --hdg=5,5,0
x=2,y=2,heading=45
x=10,y=9,heading=231
x=9,y=0,heading=321
x=1,y=9,heading=135
x=4,y=6,heading=135
\end{consoleverb}
\vspace{0.1in}

\noindent
And the following generates a heading directly {\em away} from the
point $(5,5)$ for each randomly generate point:

\vspace{0.1in}
\begin{consoleverb}
$ pickpos --amt=5 --polygon="0,0:10,0:10,10:0,10" --hdg=5,5,180
x=4,y=9,heading=346
x=9,y=0,heading=141
x=1,y=0,heading=219
x=9,y=6,heading=76
x=5,y=1,heading=180
\end{consoleverb}
\vspace{0.1in}





%=================================================================
\subsection{Picking Vehicle Colors}

With the \var{--colors} argument, \cmd{pickpos} will generate a set of
vehicle colors. These colors are not random. They are from a
hard-coded list of colors. This is handy in certain missions that are
built to launch any number of vehicles. This ensures unique colors
across all vehicles.

\vspace{0.1in}
\noindent
There are 30 vehicle colors in the \cmd{pickpos} cache. They are the
following:

\vspace{0.1in}
\begin{fileverb}
 1. yellow          16. darkslateblue
 2. red             17. brown
 3. dodger_blue     18. burlywood
 4. green           19. goldenrod
 5. purple          20. ivory
 6. orange          21. khaki
 7. white           22. lime
 8. dark_green      23. peru
 9. dark_red        24. powderblue
10. cyan            25. plum
11. coral           26. sienna
12. brown           27. sandybrown
13. bisque          28. navy
14. white           29. olive
15. pink            30. magenta
\end{fileverb}
\vspace{0.1in}

\noindent
If the user wishes to use a few colors in addition to the pre-set
list, these colors will be used first by \cmd{pickpos}, replacing the 
first N cached colors.  This can be done as follows:

\vspace{0.1in}
\begin{consoleverb}
$ pickpos --amt=5 --colors=olive,plum
olive
plum
dodger_blue
green
purple
\end{consoleverb}
\vspace{0.1in}


%=================================================================
\subsection{Picking Vehicle Groups}

In some mission, the group name matters. Perhaps there is a red-team and blue-team
adversarial mission. Or sometimes there can be ownship(s) vessels, and some number
of other contacts with different autonomy system. In any event, \cmd{pickpos} can
help in generating random or alternating group names. The group name is provided
on the command line, for example

\vspace{0.1in}
\begin{consoleverb}
$ pickpos --amt=4 --grps=red,blue,blue
\end{consoleverb}
\vspace{0.1in}

\noindent
Not above that \var{blue} was provided twice. This essentially gives \var{blue}
a 2/3 probability that it will be chosen rather than 1/2 probability.

\vspace{0.1in}
\noindent
For command-line buffs, try:

\vspace{0.1in}
\begin{consoleverb}
$ pickpos --amt=10000 --grps=red,blue,blue | fgrep blue | wc -l
\end{consoleverb}
\vspace{0.1in}

\noindent
It should produce a single number, consistently pretty close to 6666.

\vspace{0.1in}
\noindent
Sometimes it is useful to generate groups by alternating among the group choices. This can
be done by adding the \var{:alt} suffix to the list of groups. For example:

\vspace{0.1in}
\begin{consoleverb}
$ pickpos --amt=4 --grps=red,blue:alt
red
blue
red
blue
\end{consoleverb}
\vspace{0.1in}

\noindent
If you're curious, add the \var{:alt} suffix to the long example above with 10,000
entries. It should always produce exactly 6666.

\vspace{0.1in}
\noindent
Final note: While this feature was added with idea of generating group
names, this feature can be used for any type of string parameter. For example if
there is a Boolean vehicle configuration parameter, that we'd like to set
randomly, the \var{--grps} parameter can be used:

\vspace{0.1in}
\begin{consoleverb}
$ pickpos --amt=4 --grps=true,false
true
false
false
true
\end{consoleverb}
\vspace{0.1in}

\end{document}

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