pickpos: A Tool for Preparing Missions
Maintained by: mikerb@mit.edu Get PDF
src: project-pavlab/apps/app_pickpos
1 Overview
1.1 Motivation and Intended Usage
1.2 Picking Vehicle Locations with Separation
1.3 Picking Vehicle Locations from Multiple Polygons
1.4 Picking Vehicle Locations from a Pre-Set List
1.5 Picking Vehicle Names
1.6 Picking Vehicle Speed
1.7 Picking Vehicle Headings (In a Random Range)
1.8 Picking Vehicle Headings (Relative to a Point)
1.9 Picking Vehicle Colors
1.10 Picking Vehicle Groups
1 Overview
The 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.
Here is an example usage:
$ 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
Points will be chosen from the given convex polygon. Note the requested amount is 4, and 4 lines were generated.
This pickpos web page can be opened on most systems from the command line with pickpos --web. Running pickpos --help will also show the supported command line options.
1.1 Motivation and Intended Usage [top]
The motivation for 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.
As with the example above, the 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.
$ pickpos --amt=4 --polygon="60,-40:60,-160:150,-160" > positions.txt $ ls positions.txt $ cat positions.txt x=100,y=-139 x=136,y=-146 x=64,y=-103 x=75,y=-73
The resulting file contains as many lines as prescribed in the --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:
VEHPOS=(`cat positions.txt`)
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:
$ pickpos --amt=4 --vnames > vnames.txt $ ls vnames.txt $ cat vnames.txt abe ben cal deb
VNAMES=(`cat vname.txt`)
1.2 Picking Vehicle Locations with Separation [top]
In the example above, 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 --buffer=N argument. 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, pickpos will retry to satisfy the buffer criteria up to 1000 times. This can be overridden with the --maxtries=N parameter.
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 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.
If pickpos is run with the --verbose option, the points will be produced along with the min distance from each point to all the other points:
$ 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
Try running the above example with --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.
Note however, the 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 nearest=N component at the end of each line will likely break things further down the road. So it is best to only run --verbose to gauge how well pickpos is handling the current parameters, and then re-run without it.
1.3 Picking Vehicle Locations from Multiple Polygons [top]
If multiple polygons are provided on the command-line, pickpos will generate random points across polygons. For example:
$ pickpos --amt=4 --polygon="60,-40:60,-160:150,-160" \ --polygon="260,-40:260,-160:350,-160" \ --polygon="460,-40:460,-160:550,-160" \
It does not matter if the given polygons overlap. It 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.
Note: The 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.
1.4 Picking Vehicle Locations from a Pre-Set List [top]
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 --posfile argument as follows:
$ pickpos --amt=4 --posfile=file.txt
This presumes that a file has been previously generated, either by hand, with 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 --amt=N argument are greater than the number of lines in the input file, no choices will be made, and pickpos will exit with a value of 1, rather than the normal exit value of 0.
1.5 Picking Vehicle Names [top]
With the --vnames argument, 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 pickpos for generating names ensures the above preferences and provides some consistency across missions.
The first 26 names are three-letter names:
abe,ben,cal,deb,eve,fin,gil,hal,ike,jim,kim,lou,mal,ned,opi,pal,que,ray,
sam,tim,ula,val,wes,xiu,yen,zan
The second set of 26 names are four-letter names:
apia,baka,cary,doha,evie,fahy,galt,hays,iola,jing,kiev,lima,mesa,nuuk,oslo,
pace,quay,rome,sako,troy,ubly,vimy,waco,xane,york,zahl
Note: Currently only 52 unique names are supported. The 53rd name will revert to being abe. This likely will be extended in a future release.
If the user wishes to use a few names in addition to the pre-set list, this can be done as follows:
$ pickpos --amt=5 --vnames=fred,james,bingo fred james bingo deb eve
The explicitly given names will be used first, followed by the normal sequence of names.
To generate names in reverse use the --reverse_names or -r argument in addition to the --vnames argument. pickpos will generate its list by starting from zahl and working backwards.
$ pickpos --amt=5 --vnames -r zahl york xane waco vimy
1.6 Picking Vehicle Speed [top]
Random speed values may be generated with pickpos using the --spd=LOW:HIGH argument. For example:
$ pickpos --amt=5 --spd=2:8 5.4 7 2.4 6.5 7.9
Note that values are rounded to the nearest 0.1. If a different resolution is desired, the -ssnap=N argument will be used. By default N=0.1.
$ pickpos --amt=5 --spd=2:8 --ssnap=0.05 2.15 2.45 4.95 2.6 6.45
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 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.
1.7 Picking Vehicle Headings (In a Random Range) [top]
As with choosing speeds discussed above, random heading values may be generated with pickpos using the --hdg=LOW:HIGH argument. For example:
$ pickpos --amt=5 --hdg=135:225 211 162 144 145 202
If the range of values wraps around true north (zero degrees), then the range to use is [-180,180]. For example to use:
$ pickpos --amt=5 --hdg=-10:10 10 5 354 7 357
NOT:
$ pickpos --amt=5 --hdg=350:10 Unhandled arg: --hdg=350:10
1.8 Picking Vehicle Headings (Relative to a Point) [top]
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. 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:
$ 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
And the following generates a heading directly away from the point (5,5) for each randomly generate point:
$ 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
1.9 Picking Vehicle Colors [top]
With the --colors argument, 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.
There are 30 vehicle colors in the pickpos cache. They are the following:
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
If the user wishes to use a few colors in addition to the pre-set list, these colors will be used first by pickpos, replacing the first N cached colors. This can be done as follows:
$ pickpos --amt=5 --colors=olive,plum olive plum dodger_blue green purple
1.10 Picking Vehicle Groups [top]
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, pickpos can help in generating random or alternating group names. The group name is provided on the command line, for example
$ pickpos --amt=4 --grps=red,blue,blue
Not above that blue was provided twice. This essentially gives blue a 2/3 probability that it will be chosen rather than 1/2 probability.
For command-line buffs, try:
$ pickpos --amt=10000 --grps=red,blue,blue | fgrep blue | wc -l
It should produce a single number, consistently pretty close to 6666.
Sometimes it is useful to generate groups by alternating among the group choices. This can be done by adding the :alt suffix to the list of groups. For example:
$ pickpos --amt=4 --grps=red,blue:alt red blue red blue
If you're curious, add the :alt suffix to the long example above with 10,000 entries. It should always produce exactly 6666.
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 --grps parameter can be used:
$ pickpos --amt=4 --grps=true,false true false false true
Page built from LaTeX source using texwiki, developed at MIT. Errata to issues@moos-ivp.org. Get PDF