Mission Elevation Plot and Terrain Analysis
iNav mission altitudes are relative to the HOME (arming) location, which is not part of a mission definition. As a result, the pilot has to be ensure by some other means that the mission will clear any raised elevations on the mission path.
mwptools/samples includes a platform independent script, mwp-plot-elevations.rb, which given a mission file and a home location, will plot the terrain / elevation profile. This uses the Bing Maps online elevation service, so one needs to have an internet connection to perform the analysis. Note that prior to 2018-12-06, the mwp-plot-elevations.rb script was called plot-elevations.rb
In addtion, mwp-plot-elevations.rb can rewrite the mission file with new elevations to provide a specified ground clearance.
As of 2018-12-06, mwp-plot-elevations.rb is integrated into the mwp application. There is a video tutorial
Given the mission shown below:
and knowing that the land rises to the north and west, we can check that we do indeed have adequate clearance with the planned route and elevations:
# for decimal '.' locales
$ mwp-plot-elevations.rb -h 50.9104826,-1.5350745 -p profile.svg west_field.mission
# for decimal ',' locales
$ mwp-plot-elevations.rb -h "50,9104826 -1,5350745" -p profile.svg west_field.mission
where:
-
west_field.missionis the MW-XML mission file (via mwp, ezgui, mission planner for iNav or impload) - the
-h lat,lonoption defines the home position (which may also be set by the environment variableMWP_HOME), the command line having preference. - The graphical output is
profile.svg, via the-poption.
The result from this command is an SVG file, which can be displayed with common image tools (eog, ImageMagick display et al). It can also be converted to a raster image using e.g. rsvg-convert); and is shown below:
The red line represents the planned mission altitudes (which are defined relative to the estimated home location), and the green area represents the terrain. As we can see, we clear the hill (and other terrain), but cannot guarantee that we have LOS to lowest point of the mission, or that we're clear of the trees.
We can also specify a "clearance" option, in the image below this was set to 16m. Where the blue line is above the red line, one should review that the mission elevations are adequate.
It is also possible (see command line options below) to write out a new mission that takes into account the clearance (margin parameter). If we then plot this new mission file, we can see that we are at least margin (in this example 16m) distance clear of the terrain.
Note that the original mission elevations are still taken into account. We can also ignore these, so we end up the absolute clearance distance above the terrain.
$ mwp-plot-elevations.rb nm_west_field.mission -o /tmp/p1.mission --no-mission-alts
The mwp-plot-elevations.rb script has NO dependency on mwp or Linux/FreeBSD, it can just as easily be run on MacOS or MS Windows. It does however has some dependencies:
- ruby (2.0 or later)
- ruby 'gems' (libraries)
- nokogiri
- gnuplot
gnuplot is easily provided (by your distro or from a binary download), and the nokogiri dependency is also easily satisfied by either the distro or Ruby's gem command:
$ apt install ruby-nokogiri
### or ###
> gem install nokogiri
Using the package manager is recommended for non-proprietary operating systems.
On all operating systems, the terrain graph is also plotted interactively, regardless of whether the -p (save SVG plot) option has been specified. The following shows the UI on Windows (it's pretty much the same on other OS).
- 3rd party terrain data is not guaranteed, either as to its absolute accuracy, nor to its coverage.
- Terrain data does not take into account other obstacles (trees, buildings, power lines etc).
- The tool does not faithfully model the vehicle motion. As multi-rotor and fixed-wing have different climb behaviours, this would be quite complex.
- RTH altitude has to specificed if you wish to model it, and assumes 'AT LEAST' behaviour.
$ mwp-plot-elevations.rb --help
Usage: plot-elevations.rb [options] mission_file
mwp-plot-evelations.rb plots a iNav/ MW XML mission file (as generated by "mwp", "ezgui", "mission planner for iNav") against terrain elevation data.
In order to do this, you must have an internet connection, as the elevation data is obtained from the Bing Maps elevation service. You should provide a home location (so home -> WP1 and RTH can then be modelled).
Graphical output is a SVG file and requires "gnuplot" be installed. The output can also be output as a CSV file. If neither a plot file nor an output file is provided, CSV is written to standard output.
The environment variable MWP_HOME if defined, is also consulted for a home location (the -h option takes preference). Setting may also be read from a configuration file; $HOME/.config/mwp/elev-plot, ./.elev-plot.rc or $HOME/.elev-plot.rc.
Options:
-p, --plotfile=FILE Plot file (SVG)
-h, --home=LOCATION Home location as lat,long (or "lat long")
-o, --output=FILE Revised mission
-r, --rth-alt=ALT RTH altitude
-m, --margin=M Clearance Margin (m)
--no-plotting Don't plot anything, at all
--no-mission-alts Don't use extant mission altitudes
As well as specifying options such as home location, clearance margin and RTH altitude on the command line (or as an environment variable), some or all of these options may be set in a configuration file.
mwp-plot-elevations.rb looks for options in one of the following (in order) $HOME/.config/mwp/elev-plot, ./.elev-plot.rc (i.e. current directory) and $HOME/.elev-plot.rc. The configuration file is a simple text file containing key=value pairs. Blank lines and lines beginning with # are ignored; the following example illustrates the recognised keys.
# settings for mwp-plot-elevation.rb
margin = 16
home = 50.910476,-1.535038
# for ',' locales
# home = 50,910476 -1,535038
rth-alt=25
# 'sanity' is the home -> WP1 distance check; default if not set here is 100m
sanity = 200
# Interactive plot, using the above configuration file:
$ mwp-plot-elevations.rb nm_west_field.mission
# Interactive plot. save SVG file
$ mwp-plot-elevations.rb -p /tmp/mission.svg nm_west_field.mission
# Interactive plot. save SVG file, rewrite mission file
$ mwp-plot-elevations.rb -p /tmp/mission.svg -o new_west_field.mission nm_west_field.mission
# Interactive plot. save SVG file, rewrite mission file, override clearance margin (20m)
$ mwp-plot-elevations.rb -p /tmp/mission.svg -o new_west_field.mission -m 20 nm_west_field.mission
# Interactive plot. save SVG file, rewrite mission file,
# override clearance margin (20m), reduce RTH altitude (22m)
$ mwp-plot-elevations.rb -p /tmp/mission.svg -o new_west_field.mission -m 20 -r 22 nm_west_field.mission
Another contrived example ... create a mission in Google Earth (tied to ground), save as KMZ, convert to MWXML mission file with impload (0 altitude). Use mwp-plot-elevations.rb to calculate a safe mission.
# convert the saved KMZ file to a MWXML mission file
$ impload convert /tmp/IOM.kmz /tmp/perwick.mission
# Verify the elevations and clearance with plot-elevations.rb
$ mwp-plot-elevations.rb -h 54.068826,-4.735472 -m 40 /tmp/perwick.mission
Looks OK (well, apart from the flying through the hill, due to impload's default altitude of 20m).
If we specify that a new mission file be generated (-o), the updated mission is also plotted, and we can see that this clears the hill.
mwp-plot-elevations.rb -h 54.068826,-4.735472 -m 40 -o /tmp/perwick-ok.mission /tmp/perwick.mission
It's not yet perfect, we could be more aggressive in reaching just the clearance altitude, but we clear the hill!.