int usage(int retval, bool brief) { if (brief) ( retval ? std::cerr : std::cout ) << "Usage:\n" " MagneticField [ -n name ] [ -d dir ] [ -N Nmax ] [ -M Mmax ] [ -t time\n" " | -c time lat h ] [ -r ] [ -w ] [ -T tguard ] [ -H hguard ] [ -p prec ]\n" " [ -v ] [ --comment-delimiter commentdelim ] [ --version | -h | --help ]\n" " [ --input-file infile | --input-string instring ] [ --line-separator\n" " linesep ] [ --output-file outfile ]\n" "\n" "For full documentation type:\n" " MagneticField --help\n" "or visit:\n" " https://geographiclib.sourceforge.io/1.50.1/MagneticField.1.html\n"; else ( retval ? std::cerr : std::cout ) << "Man page:\n" "NAME\n" " MagneticField -- compute the earth's magnetic field\n" "\n" "SYNOPSIS\n" " MagneticField [ -n name ] [ -d dir ] [ -N Nmax ] [ -M Mmax ] [ -t time\n" " | -c time lat h ] [ -r ] [ -w ] [ -T tguard ] [ -H hguard ] [ -p prec ]\n" " [ -v ] [ --comment-delimiter commentdelim ] [ --version | -h | --help ]\n" " [ --input-file infile | --input-string instring ] [ --line-separator\n" " linesep ] [ --output-file outfile ]\n" "\n" "DESCRIPTION\n" " MagneticField reads in times and positions on standard input and prints\n" " out the geomagnetic field on standard output and, optionally, its rate\n" " of change.\n" "\n" " The input line is of the form time lat lon h. time is a date of the\n" " form 2012-07-03, a fractional year such as 2012.5, or the string \"now\".\n" " lat and lon are the latitude and longitude expressed as decimal degrees\n" " or degrees, minutes, and seconds; for details on the allowed formats\n" " for latitude and longitude, see the \"GEOGRAPHIC COORDINATES\" section of\n" " GeoConvert(1). h is the height above the ellipsoid in meters; this is\n" " optional and defaults to zero. Alternatively, time can be given on the\n" " command line as the argument to the -t option, in which case it should\n" " not be included on the input lines. Finally, the magnetic field can be\n" " computed at various points on a circle of latitude (constant time, lat,\n" " and h) via the -c option; in this case only the longitude should be\n" " given on the input lines.\n" "\n" " The output consists of the following 7 items:\n" "\n" " the declination (the direction of the horizontal component of\n" " the magnetic field measured clockwise from north) in degrees,\n" " the inclination (the direction of the magnetic field measured\n" " down from the horizontal) in degrees,\n" " the horizontal field in nanotesla (nT),\n" " the north component of the field in nT,\n" " the east component of the field in nT,\n" " the vertical component of the field in nT (down is positive),\n" " the total field in nT.\n" "\n" " If the -r option is given, a second line is printed giving the rates of\n" " change of these quantities in degrees/yr and nT/yr.\n" "\n" " The WGS84 ellipsoid is used, a = 6378137 m, f = 1/298.257223563.\n" "\n" "OPTIONS\n" " -n name\n" " use magnetic field model name instead of the default \"wmm2020\".\n" " See \"MODELS\".\n" "\n" " -d dir\n" " read magnetic models from dir instead of the default. See\n" " \"MODELS\".\n" "\n" " -N Nmax\n" " limit the degree of the model to Nmax.\n" "\n" " -M Mmax\n" " limit the order of the model to Mmax.\n" "\n" " -t time\n" " evaluate the field at time instead of reading the time from the\n" " input lines.\n" "\n" " -c time lat h\n" " evaluate the field on a circle of latitude given by time, lat, h\n" " instead of reading these quantities from the input lines. In this\n" " case, MagneticField can calculate the field considerably more\n" " quickly.\n" "\n" " -r toggle whether to report the rates of change of the field.\n" "\n" " -w toggle the longitude first flag (it starts off); if the flag is on,\n" " then on input and output, longitude precedes latitude (except that,\n" " on input, this can be overridden by a hemisphere designator, N, S,\n" " E, W).\n" "\n" " -T tguard\n" " signal an error if time lies tguard years (default 50 yr) beyond\n" " the range for the model.\n" "\n" " -H hguard\n" " signal an error if h lies hguard meters (default 500000 m) beyond\n" " the range for the model.\n" "\n" " -p prec\n" " set the output precision to prec (default 1). Fields are printed\n" " with precision with prec decimal places; angles use prec + 1\n" " places.\n" "\n" " -v print information about the magnetic model on standard error before\n" " processing the input.\n" "\n" " --comment-delimiter commentdelim\n" " set the comment delimiter to commentdelim (e.g., \"#\" or \"//\"). If\n" " set, the input lines will be scanned for this delimiter and, if\n" " found, the delimiter and the rest of the line will be removed prior\n" " to processing and subsequently appended to the output line\n" " (separated by a space).\n" "\n" " --version\n" " print version and exit.\n" "\n" " -h print usage, the default magnetic path and name, and exit.\n" "\n" " --help\n" " print full documentation and exit.\n" "\n" " --input-file infile\n" " read input from the file infile instead of from standard input; a\n" " file name of \"-\" stands for standard input.\n" "\n" " --input-string instring\n" " read input from the string instring instead of from standard input.\n" " All occurrences of the line separator character (default is a\n" " semicolon) in instring are converted to newlines before the reading\n" " begins.\n" "\n" " --line-separator linesep\n" " set the line separator character to linesep. By default this is a\n" " semicolon.\n" "\n" " --output-file outfile\n" " write output to the file outfile instead of to standard output; a\n" " file name of \"-\" stands for standard output.\n" "\n" "MODELS\n" " MagneticField computes the geomagnetic field using one of the following\n" " models\n" "\n" " wmm2010, the World Magnetic Model 2010, which approximates the\n" " main magnetic field for the period 2010-2015. See\n" " https://ngdc.noaa.gov/geomag/WMM/DoDWMM.shtml\n" " wmm2015v2, the World Magnetic Model 2015, which approximates the\n" " main magnetic field for the period 2015-2020. See\n" " https://ngdc.noaa.gov/geomag/WMM/DoDWMM.shtml\n" " wmm2015, a deprecated version of wmm2015v2\n" " wmm2020, the World Magnetic Model 2020, which approximates the\n" " main magnetic field for the period 2020-2025. See\n" " https://ngdc.noaa.gov/geomag/WMM/DoDWMM.shtml\n" " igrf11, the International Geomagnetic Reference Field (11th\n" " generation), which approximates the main magnetic field for\n" " the period 1900-2015. See\n" " https://ngdc.noaa.gov/IAGA/vmod/igrf.html\n" " igrf12, the International Geomagnetic Reference Field (12th\n" " generation), which approximates the main magnetic field for\n" " the period 1900-2020. See\n" " https://ngdc.noaa.gov/IAGA/vmod/igrf.html\n" " emm2010, the Enhanced Magnetic Model 2010, which approximates\n" " the main and crustal magnetic fields for the period 2010-2015.\n" " See https://ngdc.noaa.gov/geomag/EMM/index.html\n" " emm2015, the Enhanced Magnetic Model 2015, which approximates\n" " the main and crustal magnetic fields for the period 2000-2020.\n" " See https://ngdc.noaa.gov/geomag/EMM/index.html\n" " emm2017, the Enhanced Magnetic Model 2017, which approximates\n" " the main and crustal magnetic fields for the period 2000-2022.\n" " See https://ngdc.noaa.gov/geomag/EMM/index.html\n" "\n" " These models approximate the magnetic field due to the earth's core and\n" " (in the case of emm20xx) its crust. They neglect magnetic fields due\n" " to the ionosphere, the magnetosphere, nearby magnetized materials,\n" " electrical machinery, etc.\n" "\n" " By default, the \"wmm2020\" magnetic model is used. This may changed by\n" " setting the environment variable \"GEOGRAPHICLIB_MAGNETIC_NAME\" or with\n" " the -n option.\n" "\n" " The magnetic models will be loaded from a directory specified at\n" " compile time. This may changed by setting the environment variables\n" " \"GEOGRAPHICLIB_MAGNETIC_PATH\" or \"GEOGRAPHICLIB_DATA\", or with the -d\n" " option. The -h option prints the default magnetic path and name. Use\n" " the -v option to ascertain the full path name of the data file.\n" "\n" " Instructions for downloading and installing magnetic models are\n" " available at\n" " .\n" "\n" "ENVIRONMENT\n" " GEOGRAPHICLIB_MAGNETIC_NAME\n" " Override the compile-time default magnetic name of \"wmm2020\". The\n" " -h option reports the value of GEOGRAPHICLIB_MAGNETIC_NAME, if\n" " defined, otherwise it reports the compile-time value. If the -n\n" " name option is used, then name takes precedence.\n" "\n" " GEOGRAPHICLIB_MAGNETIC_PATH\n" " Override the compile-time default magnetic path. This is typically\n" " \"/usr/local/share/GeographicLib/magnetic\" on Unix-like systems and\n" " \"C:/ProgramData/GeographicLib/magnetic\" on Windows systems. The -h\n" " option reports the value of GEOGRAPHICLIB_MAGNETIC_PATH, if\n" " defined, otherwise it reports the compile-time value. If the -d\n" " dir option is used, then dir takes precedence.\n" "\n" " GEOGRAPHICLIB_DATA\n" " Another way of overriding the compile-time default magnetic path.\n" " If it is set (and if GEOGRAPHICLIB_MAGNETIC_PATH is not set), then\n" " $GEOGRAPHICLIB_DATA/magnetic is used.\n" "\n" "ERRORS\n" " An illegal line of input will print an error message to standard output\n" " beginning with \"ERROR:\" and causes MagneticField to return an exit code\n" " of 1. However, an error does not cause MagneticField to terminate;\n" " following lines will be converted. If time or h are outside the\n" " recommended ranges for the model (but inside the ranges increase by\n" " tguard and hguard), a warning is printed on standard error and the\n" " field (which may be inaccurate) is returned in the normal way.\n" "\n" "EXAMPLES\n" " The magnetic field from WMM2020 in Timbuktu on 2020-01-01\n" "\n" " echo 2020-01-01 16:46:33N 3:00:34W 300 | MagneticField -r\n" " => -1.60 12.00 33973.5 33960.3 -948.1 7223.0 34732.8\n" " 0.13 -0.02 21.8 23.9 77.9 -8.4 19.5\n" "\n" " The first two numbers returned are the declination and inclination of\n" " the field. The second line gives the annual change.\n" "\n" "SEE ALSO\n" " GeoConvert(1), geographiclib-get-magnetic(8).\n" "\n" "AUTHOR\n" " MagneticField was written by Charles Karney.\n" "\n" "HISTORY\n" " MagneticField was added to GeographicLib,\n" " , in version 1.15.\n" ; return retval; }