Command line interface¶
The GeoModel package also provides a command line interface that can be used to:
- display information about the:
- GeoModels version and GeographicLib library version
- platform and environment info
- data directory and installed model data
- install model data that are used by the GeoModels and by the underlying GeographicLib library to perform geographic models computations
- import magnetic field spherical harmonics coefficients for IGRF format
- run the test suite
Invocation¶
The GeoModels package provides a script named geomodels-cli which can be run as follows:
$ geomodels-cli [OPTIONS] ARGS
An alternative invocation method is:
$ python3 -m geomodels [OPTIONS] ARGS
Main command line interface¶
The online help of the main command line interface can be obtained as follows:
$ geomodels-cli -h
usage: geomodels [-h] [--version]
[--loglevel {DEBUG,INFO,WARNING,ERROR,CRITICAL}]
[-q] [-v] [--debug]
{info,install-data,import-igrf,test} ...
Command Line Interface (CLI) for the geomodels package.
optional arguments:
-h, --help show this help message and exit
--version show program's version number and exit
--loglevel {DEBUG,INFO,WARNING,ERROR,CRITICAL}
logging level (default: WARNING)
-q, --quiet suppress standard output messages, only
errors are printed to screen (set
"loglevel" to "ERROR")
-v, --verbose print verbose output messages (set
"loglevel" to "INFO")
--debug print debug messages (set "loglevel" to
"DEBUG")
sub-commands:
{info,install-data,test}
info Provide information about the platform,
library versions and
install-data Download and install the data necessary for
models computation.
import-igrf import magnetic field data from igrf text format.
test run the test suite for the geomodels
package.
Note
Please note that options for logging level configuration shall precede the sub-command name and specific sub-command options, e.g.:
$ geomodels-cli --debug test
Example output:
$ geomodels-cli --version
geomodels v1.0.0
Info tool¶
The online help of the “info” tool:
$ geomodels-cli info -h
usage: geomodels info [-h] [-d DATADIR] [-a] [--data]
Provide information about the platform, library versions and
installed data.
optional arguments:
-h, --help show this help message and exit
-d DATADIR, --datadir DATADIR
specifies where the model data are stored
(default: '/usr/local/share/GeographicLib').
-a, --all show both versions and platform info and
also information about installed data
--data show info about installed data
Sample output:
$ geomodels-cli info --all
geomodels version: 1.0.0
GeographicLib version: 1.50.1
Python version: 3.7.5
Platform: Linux-5.3.0-26-generic-x86_64-with-Ubuntu-19.10-eoan
Byte-ordering: little
Default encoding: utf-8
Default FS encoding: utf-8
Default locale: (it_IT, UTF-8)
data directory: 'data/'
* model: geoids ('data/geoids')
EGM84_30 - NOT INSTALLED
EGM84_15 - NOT INSTALLED
EGM96_15 - NOT INSTALLED
EGM96_5 - INSTALLED
EGM2008_5 - NOT INSTALLED
EGM2008_2_5 - NOT INSTALLED
EGM2008_1 - NOT INSTALLED
* model: gravity ('data/gravity')
EGM84 - NOT INSTALLED
EGM96 - INSTALLED
EGM2008 - NOT INSTALLED
WGS84 - NOT INSTALLED
* model: magnetic ('data/magnetic')
WMM2010 - NOT INSTALLED
WMM2015 - INSTALLED
WMM2020 - INSTALLED
IGRF11 - NOT INSTALLED
IGRF12 - INSTALLED
EMM2010 - NOT INSTALLED
EMM2015 - NOT INSTALLED
EMM2017 - NOT INSTALLED
Install data tool¶
The online help of the “install-data” tool:
$ geomodels-cli install-data -h
usage: geomodels install-data [-h] [-b BASE_URL] [-d DATADIR]
{all,minimal,recommended,geoids,
gravity, magnetic,egm84-30,egm84-15,
egm96-15,egm96-5, egm2008-5,
egm2008-2_5,egm2008-1,egm84,egm96,
egm2008,wgs84,wmm2010,wmm2015,
wmm2020,igrf11, igrf12,emm2010,
emm2015,emm2017}
Download and install the data necessary for models computation.
GeoModels uses external data to perform geoid, gravity and magnetic
field computations. It is possible to install different subsets of
data:
`minimal` only data for the default model of each kind
(geoid, gravity and magnetic field) are installed,
`recommended` install the `minimal` set of data (see above) plus
few additional and commonly used data (it is guaranteed that the
`recommended` subset always includes all data that are necessary to
run the test suite),
`all` install all available data (about 670MB of disk space
required),
`geoids` install data for all supported geoids,
`gravity` install data for all supported gravity models,
`magnetic` install data for all supported magnetic field models.
Additionally the it is possible to install data for a single model.
positional arguments:
{all,minimal,recommended,geoids,gravity,magnetic,egm84-30,
egm84-15,egm96-15,egm96-5,egm2008-5,egm2008-2_5,egm2008-1,egm84,
egm96,egm2008, wgs84,wmm2010,wmm2015,wmm2020,igrf11,igrf12,
emm2010,emm2015,emm2017}
model(s) to be installed
optional arguments:
-h, --help show this help message and exit
-b BASE_URL, --base-url BASE_URL
specifies the base URL for the download
(default:
'https://downloads.sourceforge.net/project/geographiclib').
-d DATADIR, --datadir DATADIR
specifies where the datasets should be
stored (default:
'/usr/local/share/GeographicLib').
Import IGRF data tool¶
The online help of the “import-igrf” tool:
$ python3 -m geomodels import-igrf -h
usage: geomodels-cli import-igrf [-h] [-o OUTPATH] [--force] path
Import magnetic field data from IGRF text format.
positional arguments:
path path or URL of the IGRF text file
optional arguments:
-h, --help show this help message and exit
-o OUTPATH, --outpath OUTPATH
specifies the output data path (default:
"/usr/share/GeographicLib/magnetic").
--force overwrite existing files (default: False).
Test tool¶
The online help of the “test” tool:
$ geomodels-cli test -h
usage: geomodels test [-h] [-d DATADIR] [--verbosity VERBOSITY]
[--failfast]
Run the test suite for the geomodels package.
optional arguments:
-h, --help show this help message and exit
-d DATADIR, --datadir DATADIR
specifies where the model data are stored
(default: '/usr/local/share/GeographicLib').
--verbosity VERBOSITY
verbosity level for the unittest runner
(default: 1).
--failfast stop the test run on the first error or
failure (default: False).
Sample output:
$ geomodels-cli test
geomodels version: 1.0.0
GeographicLib version: 1.50.1
Python version: 3.7.5
Platform: Linux-5.3.0-26-generic-x86_64-with-Ubuntu-19.10-eoan
Byte-ordering: little
Default encoding: utf-8
Default FS encoding: utf-8
Default locale: (it_IT, UTF-8)
............................................................................
............................................................................
........
----------------------------------------------------------------------
Ran 160 tests in 0.450s
OK