Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MAGNETICFIELD(1)	    GeographicLib Utilities	      MAGNETICFIELD(1)

NAME
       MagneticField --	compute	the earth's magnetic field

SYNOPSIS
       MagneticField [ -n name ] [ -d dir ] [ -t time |	-c time	lat h ]	[ -r ]
       [ -w ] [	-T tguard ] [ -H hguard	] [ -p prec ] [	-v ] [
       --comment-delimiter commentdelim	] [ --version |	-h | --help ] [
       --input-file infile | --input-string instring ] [ --line-separator
       linesep ] [ --output-file outfile ]

DESCRIPTION
       MagneticField reads in times and	positions on standard input and	prints
       out the geomagnetic field on standard output and, optionally, its rate
       of change.

       The input line is of the	form time lat lon h. time is a date of the
       form 2012-07-03,	a fractional year such as 2012.5, or the string	"now".
       lat and lon are the latitude and	longitude expressed as decimal degrees
       or degrees, minutes, and	seconds; for details on	the allowed formats
       for latitude and	longitude, see the "GEOGRAPHIC COORDINATES" section of
       GeoConvert(1).  h is the	height above the ellipsoid in meters; this is
       optional	and defaults to	zero.  Alternatively, time can be given	on the
       command line as the argument to the -t option, in which case it should
       not be included on the input lines.  Finally, the magnetic field	can be
       computed	at various points on a circle of latitude (constant time, lat,
       and h) via the -c option; in this case only the longitude should	be
       given on	the input lines.

       The output consists of the following 7 items:

	 the declination (the direction	of the horizontal component of
	   the magnetic	field measured clockwise from north) in	degrees,
	 the inclination (the direction	of the magnetic	field measured
	   down	from the horizontal) in	degrees,
	 the horizontal	field in nanotesla (nT),
	 the north component of	the field in nT,
	 the east component of the field in nT,
	 the vertical component	of the field in	nT (down is positive),
	 the total field in nT.

       If the -r option	is given, a second line	is printed giving the rates of
       change of these quantities in degrees/yr	and nT/yr.

       The WGS84 ellipsoid is used, a =	6378137	m, f = 1/298.257223563.

OPTIONS
       -n name
	   use magnetic	field model name instead of the	default	"wmm2015".
	   See "MODELS".

       -d dir
	   read	magnetic models	from dir instead of the	default.  See
	   "MODELS".

       -t time
	   evaluate the	field at time instead of reading the time from the
	   input lines.

       -c time lat h
	   evaluate the	field on a circle of latitude given by time, lat, h
	   instead of reading these quantities from the	input lines.  In this
	   case, MagneticField can calculate the field considerably more
	   quickly.

       -r  toggle whether to report the	rates of change	of the field.

       -w  toggle the longitude	first flag (it starts off); if the flag	is on,
	   then	on input and output, longitude precedes	latitude (except that,
	   on input, this can be overridden by a hemisphere designator,	N, S,
	   E, W).

       -T tguard
	   signal an error if time lies	tguard years (default 50 yr) beyond
	   the range for the model.

       -H hguard
	   signal an error if h	lies hguard meters (default 500000 m) beyond
	   the range for the model.

       -p prec
	   set the output precision to prec (default 1).  Fields are printed
	   with	precision with prec decimal places; angles use prec + 1
	   places.

       -v  print information about the magnetic	model on standard error	before
	   processing the input.

       --comment-delimiter commentdelim
	   set the comment delimiter to	commentdelim (e.g., "#"	or "//").  If
	   set,	the input lines	will be	scanned	for this delimiter and,	if
	   found, the delimiter	and the	rest of	the line will be removed prior
	   to processing and subsequently appended to the output line
	   (separated by a space).

       --version
	   print version and exit.

       -h  print usage,	the default magnetic path and name, and	exit.

       --help
	   print full documentation and	exit.

       --input-file infile
	   read	input from the file infile instead of from standard input; a
	   file	name of	"-" stands for standard	input.

       --input-string instring
	   read	input from the string instring instead of from standard	input.
	   All occurrences of the line separator character (default is a
	   semicolon) in instring are converted	to newlines before the reading
	   begins.

       --line-separator	linesep
	   set the line	separator character to linesep.	 By default this is a
	   semicolon.

       --output-file outfile
	   write output	to the file outfile instead of to standard output; a
	   file	name of	"-" stands for standard	output.

MODELS
       MagneticField computes the geomagnetic field using one of the following
       models

	   wmm2010, the	World Magnetic Model 2010, which approximates the
	     main magnetic field for the period	2010-2015.  See
	     http://ngdc.noaa.gov/geomag/WMM/DoDWMM.shtml
	   wmm2015, the	World Magnetic Model 2015, which approximates the
	     main magnetic field for the period	2015-2020.  See
	     http://ngdc.noaa.gov/geomag/WMM/DoDWMM.shtml
	   igrf11, the International Geomagnetic Reference Field (11th
	     generation), which	approximates the main magnetic field for
	     the period	1900-2015.  See
	     http://ngdc.noaa.gov/IAGA/vmod/igrf.html
	   igrf12, the International Geomagnetic Reference Field (12th
	     generation), which	approximates the main magnetic field for
	     the period	1900-2020.  See
	     http://ngdc.noaa.gov/IAGA/vmod/igrf.html
	   emm2010, the	Enhanced Magnetic Model	2010, which approximates
	     the main and crustal magnetic fields for the period 2010-2015.
	     See http://ngdc.noaa.gov/geomag/EMM/index.html
	   emm2015, the	Enhanced Magnetic Model	2015, which approximates
	     the main and crustal magnetic fields for the period 2000-2020.
	     See http://ngdc.noaa.gov/geomag/EMM/index.html

       These models approximate	the magnetic field due to the earth's core and
       (in the case of emm2010)	its crust.  They neglect magnetic fields due
       to the ionosphere, the magnetosphere, nearby magnetized materials,
       electrical machinery, etc.

       By default, the "wmm2015" magnetic model	is used.  This may changed by
       setting the environment variable	"GEOGRAPHICLIB_MAGNETIC_NAME" or with
       the -n option.

       The magnetic models will	be loaded from a directory specified at
       compile time.  This may changed by setting the environment variables
       "GEOGRAPHICLIB_MAGNETIC_PATH" or	"GEOGRAPHICLIB_DATA", or with the -d
       option.	The -h option prints the default magnetic path and name.  Use
       the -v option to	ascertain the full path	name of	the data file.

       Instructions for	downloading and	installing magnetic models are
       available at
       <http://geographiclib.sourceforge.net/html/magnetic.html#magneticinst>.

ENVIRONMENT
       GEOGRAPHICLIB_MAGNETIC_NAME
	   Override the	compile-time default magnetic name of "wmm2015".  The
	   -h option reports the value of GEOGRAPHICLIB_MAGNETIC_NAME, if
	   defined, otherwise it reports the compile-time value.  If the -n
	   name	option is used,	then name takes	precedence.

       GEOGRAPHICLIB_MAGNETIC_PATH
	   Override the	compile-time default magnetic path.  This is typically
	   "/usr/local/share/GeographicLib/magnetic" on	Unix-like systems and
	   "C:/ProgramData/GeographicLib/magnetic" on Windows systems.	The -h
	   option reports the value of GEOGRAPHICLIB_MAGNETIC_PATH, if
	   defined, otherwise it reports the compile-time value.  If the -d
	   dir option is used, then dir	takes precedence.

       GEOGRAPHICLIB_DATA
	   Another way of overriding the compile-time default magnetic path.
	   If it is set	(and if	GEOGRAPHICLIB_MAGNETIC_PATH is not set), then
	   $GEOGRAPHICLIB_DATA/magnetic	is used.

ERRORS
       An illegal line of input	will print an error message to standard	output
       beginning with "ERROR:" and causes MagneticField	to return an exit code
       of 1.  However, an error	does not cause MagneticField to	terminate;
       following lines will be converted.  If time or h	are outside the
       recommended ranges for the model	(but inside the	ranges increase	by
       tguard and hguard), a warning is	printed	on standard error and the
       field (which may	be inaccurate) is returned in the normal way.

EXAMPLES
       The magnetic field from WMM2015 in Timbuktu on 2016-01-01

	   echo	2016-01-01 16:46:33N 3:00:34W 300 | MagneticField -r
	   => -2.12 12.15 33871.9 33848.7 -1251.4 7293.9 34648.3
	      0.09 -0.08 31.8 33.8 53.7	-41.4 22.3

       The first two numbers returned are the declination and inclination of
       the field.  The second line gives the annual change.

SEE ALSO
       GeoConvert(1), geographiclib-get-magnetic(8).

AUTHOR
       MagneticField was written by Charles Karney.

HISTORY
       MagneticField was added to GeographicLib,
       <http://geographiclib.sourceforge.net>, in version 1.15.

GeographicLib 1.46		  2016-02-14		      MAGNETICFIELD(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | MODELS | ENVIRONMENT | ERRORS | EXAMPLES | SEE ALSO | AUTHOR | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=MagneticField&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help