Represents a model of the Earth's magnetic field. More...

#include <qgsmagneticmodel.h>

Public Member Functions
	QgsMagneticModel (const QgsMagneticModel &other)=delete
	QgsMagneticModel (const QString &name, const QString &path=QString(), int maxDegree=-1, int maxOrder=-1)
	Constructor for QgsMagneticModel.
	~QgsMagneticModel ()
QDateTime	dateTime () const
	Returns the date of the magnetic model, if available.
bool	declination (double years, double latitude, double longitude, double height, double &declination) const
	Calculates the declination of the field at a point.
int	degree () const
	Returns the maximum degree of the components of the model.
QString	description () const
	Returns the description of the magnetic model, if available.
QString	directory () const
	Returns the full directory name containing the magnetic model file.
QString	error () const
	Returns a string for the last error encountered by the model.
QString	file () const
	Returns the full file name for the magnetic model.
bool	getComponents (double years, double latitude, double longitude, double height, double &Bx, double &By, double &Bz) const
	Evaluates the components of the geomagnetic field at a point.
bool	getComponentsWithTimeDerivatives (double years, double latitude, double longitude, double height, double &Bx, double &By, double &Bz, double &Bxt, double &Byt, double &Bzt) const
	Evaluates the components of the geomagnetic field at a point, and their time derivatives.
bool	inclination (double years, double latitude, double longitude, double height, double &inclination) const
	Calculates the inclination of the field at a point.
bool	isValid () const
	Returns `true` if the model is valid and can be used.
double	maximumHeight () const
	Returns the maximum height above the ellipsoid (in meters) for which the model should be used.
double	maximumYear () const
	Returns the maximum time (in decimal years) for which the model should be used.
double	minimumHeight () const
	Returns the minimum height above the ellipsoid (in meters) for which the model should be used.
double	minimumYear () const
	Returns the minimum time (in decimal years) for which the model should be used.
QString	name () const
	Returns the name of the magnetic model.
QgsMagneticModel &	operator= (const QgsMagneticModel &other)=delete
int	order () const
	Returns the maximum order of the components of the model.

Static Public Member Functions
static QString	defaultFilePath ()
	Returns the default path used by GeographicLib to search for magnetic models.
static QString	defaultModelName ()
	Returns the name of the default magnetic model used by GeographicLib.
static bool	fieldComponents (double Bx, double By, double Bz, double &H, double &F, double &D, double &I)
	Compute various quantities dependent on a magnetic field.
static bool	fieldComponentsWithTimeDerivatives (double Bx, double By, double Bz, double Bxt, double Byt, double Bzt, double &H, double &F, double &D, double &I, double &Ht, double &Ft, double &Dt, double &It)
	Compute various quantities dependent on a magnetic field and their rates of change.

Detailed Description

Represents a model of the Earth's magnetic field.

Warning: This class is only usable if QGIS was built with GeographicLib support. If not, then QgsNotSupportedException exceptions will be raised when calling the methods for this class.

The Qgis::hasGeographicLib() method can be used to determine if QGIS was built with GeographicLib support.

Since: QGIS 4.0

Definition at line 50 of file qgsmagneticmodel.h.

Constructor & Destructor Documentation

◆ QgsMagneticModel() [1/2]

QgsMagneticModel::QgsMagneticModel	(	const QString &	name,
		const QString &	path = QString(),
		int	maxDegree = -1,
		int	maxOrder = -1 )

Constructor for QgsMagneticModel.

A filename is formed by appending ".wmm" (World Magnetic Model) to the name argument.

If path is specified (and is non-empty), then the associated file is loaded from this path. Otherwise the file path is given by the defaultFilePath().

The associated file must exist and point to a valid magnetic model file. If not, then isValid() will return false and a descriptive error can be retrieved by error().

If maxDegree ≥ 0 and maxOrder < 0, then maxOrder is set to maxDegree. After the model is loaded, the maximum degree and order of the model can be found by the degree() and order() methods.

Parameters

name	the name of the model.
path	optional directory for data file. If not specified then defaultFilePath() is used.
maxDegree	if nonnegative, truncate the degree of the model to this value
maxOrder	if nonnegative, truncate the order of the model to this value

Definition at line 44 of file qgsmagneticmodel.cpp.

◆ ~QgsMagneticModel()

QgsMagneticModel::~QgsMagneticModel ( )

default

◆ QgsMagneticModel() [2/2]

QgsMagneticModel::QgsMagneticModel ( const QgsMagneticModel & other )

delete

Member Function Documentation

◆ dateTime()

QDateTime QgsMagneticModel::dateTime ( ) const

Returns the date of the magnetic model, if available.

Exceptions

QgsNotSupportedException if GeographicLib is not available

Definition at line 91 of file qgsmagneticmodel.cpp.

◆ declination()

bool QgsMagneticModel::declination	(	double	years,
		double	latitude,
		double	longitude,
		double	height,
		double &	declination ) const

Calculates the declination of the field at a point.

Note: The latitude and longitude should be specified as a WGS84 coordinate; If calculating both the inclination and declination at the same point it is more efficient to use getComponents() and fieldComponents()

Parameters

years	the time (in fractional years)
latitude	latitude of the point (in decimal degrees)
longitude	longitude of the point (in decimal degrees)
height	height of the point above the ellipsoid (in meters)
declination	magnetic field declination, in degrees east of north

Returns: true if declination was successfully calculated

Exceptions

QgsNotSupportedException if GeographicLib is not available

See also: inclination()

Definition at line 188 of file qgsmagneticmodel.cpp.

◆ defaultFilePath()

QString QgsMagneticModel::defaultFilePath ( )

static

Returns the default path used by GeographicLib to search for magnetic models.

See also: defaultModelName()

Definition at line 26 of file qgsmagneticmodel.cpp.

◆ defaultModelName()

QString QgsMagneticModel::defaultModelName ( )

static

Returns the name of the default magnetic model used by GeographicLib.

See also: defaultFilePath()

Definition at line 35 of file qgsmagneticmodel.cpp.

◆ degree()

int QgsMagneticModel::degree ( ) const

Returns the maximum degree of the components of the model.

Exceptions

QgsNotSupportedException if GeographicLib is not available

See also: order()

Definition at line 170 of file qgsmagneticmodel.cpp.

◆ description()

QString QgsMagneticModel::description ( ) const

Returns the description of the magnetic model, if available.

Exceptions

QgsNotSupportedException if GeographicLib is not available

Definition at line 78 of file qgsmagneticmodel.cpp.

◆ directory()

QString QgsMagneticModel::directory ( ) const

Returns the full directory name containing the magnetic model file.

Exceptions

QgsNotSupportedException if GeographicLib is not available

Definition at line 116 of file qgsmagneticmodel.cpp.

◆ error()

QString QgsMagneticModel::error ( ) const

inline

Returns a string for the last error encountered by the model.

Definition at line 139 of file qgsmagneticmodel.h.

◆ fieldComponents()

bool QgsMagneticModel::fieldComponents	(	double	Bx,
		double	By,
		double	Bz,
		double &	H,
		double &	F,
		double &	D,
		double &	I )

static

Compute various quantities dependent on a magnetic field.

Parameters

Bx	the easterly component of the magnetic field (in nanotesla)
By	the northerly component of the magnetic field (in nanotesla)
Bz	the vertical (up) component of the magnetic field (in nanotesla)
H	the horizontal magnetic field (in nanotesla)
F	the total magnetic field (in nanotesla)
D	the declination of the field (degrees east of north)
I	the inclination of the field (degrees down from horizontal)

Returns: true if the components were successfully calculated

Exceptions

QgsNotSupportedException if GeographicLib is not available

See also: fieldComponentsWithTimeDerivatives()

Definition at line 283 of file qgsmagneticmodel.cpp.

◆ fieldComponentsWithTimeDerivatives()

bool QgsMagneticModel::fieldComponentsWithTimeDerivatives	(	double	Bx,
		double	By,
		double	Bz,
		double	Bxt,
		double	Byt,
		double	Bzt,
		double &	H,
		double &	F,
		double &	D,
		double &	I,
		double &	Ht,
		double &	Ft,
		double &	Dt,
		double &	It )

static

Compute various quantities dependent on a magnetic field and their rates of change.

Parameters

Bx	the easterly component of the magnetic field (in nanotesla)
By	the northerly component of the magnetic field (in nanotesla)
Bz	the vertical (up) component of the magnetic field (in nanotesla)
Bxt	the rate of change of Bx (nT/yr)
Byt	the rate of change of By (nT/yr)
Bzt	the rate of change of Bz (nT/yr)
H	the horizontal magnetic field (in nanotesla)
F	the total magnetic field (in nanotesla)
D	the declination of the field (degrees east of north)
I	the inclination of the field (degrees down from horizontal)
Ht	the rate of change of H (nT/yr)
Ft	the rate of change of F (nT/yr)
Dt	the rate of change of D (degrees/yr)
It	the rate of change of I (degrees/yr)

Returns: true if the components were successfully calculated

Exceptions

QgsNotSupportedException if GeographicLib is not available

See also: fieldComponentsWithTimeDerivatives()

Definition at line 300 of file qgsmagneticmodel.cpp.

◆ file()

QString QgsMagneticModel::file ( ) const

Returns the full file name for the magnetic model.

Exceptions

QgsNotSupportedException if GeographicLib is not available

Definition at line 107 of file qgsmagneticmodel.cpp.

◆ getComponents()

bool QgsMagneticModel::getComponents	(	double	years,
		double	latitude,
		double	longitude,
		double	height,
		double &	Bx,
		double &	By,
		double &	Bz ) const

Evaluates the components of the geomagnetic field at a point.

Note: The latitude and longitude should be specified as a WGS84 coordinate

Parameters

years	the time (in fractional years)
latitude	latitude of the point (in decimal degrees)
longitude	longitude of the point (in decimal degrees)
height	height of the point above the ellipsoid (in meters)
Bx	the easterly component of the magnetic field (in nanotesla).
By	the northerly component of the magnetic field (in nanotesla)
Bz	the vertical (up) component of the magnetic field (in nanotesla)

Returns: true if the components were successfully calculated

Exceptions

QgsNotSupportedException if GeographicLib is not available

See also: getComponentsWithTimeDerivatives()

Definition at line 240 of file qgsmagneticmodel.cpp.

◆ getComponentsWithTimeDerivatives()

bool QgsMagneticModel::getComponentsWithTimeDerivatives	(	double	years,
		double	latitude,
		double	longitude,
		double	height,
		double &	Bx,
		double &	By,
		double &	Bz,
		double &	Bxt,
		double &	Byt,
		double &	Bzt ) const

Evaluates the components of the geomagnetic field at a point, and their time derivatives.

Note: The latitude and longitude should be specified as a WGS84 coordinate

Parameters

years	the time (in fractional years)
latitude	latitude of the point (in decimal degrees)
longitude	longitude of the point (in decimal degrees)
height	height of the point above the ellipsoid (in meters)
Bx	the easterly component of the magnetic field (in nanotesla).
By	the northerly component of the magnetic field (in nanotesla)
Bz	the vertical (up) component of the magnetic field (in nanotesla)
Bxt	the rate of change of Bx (nT/yr)
Byt	the rate of change of By (nT/yr)
Bzt	the rate of change of Bz (nT/yr)

Returns: true if the components were successfully calculated

Exceptions

QgsNotSupportedException if GeographicLib is not available

See also: getComponents()

Definition at line 260 of file qgsmagneticmodel.cpp.

◆ inclination()

bool QgsMagneticModel::inclination	(	double	years,
		double	latitude,
		double	longitude,
		double	height,
		double &	inclination ) const

Calculates the inclination of the field at a point.

Note: The latitude and longitude should be specified as a WGS84 coordinate; If calculating both the inclination and declination at the same point it is more efficient to use getComponents() and fieldComponents()

Parameters

years	the time (in fractional years)
latitude	latitude of the point (in decimal degrees)
longitude	longitude of the point (in decimal degrees)
height	height of the point above the ellipsoid (in meters)
inclination	magnetic field inclination, in degrees down from horizontal

Returns: true if inclination was successfully calculated

Exceptions

QgsNotSupportedException if GeographicLib is not available

See also: declination()

Definition at line 214 of file qgsmagneticmodel.cpp.

◆ isValid()

bool QgsMagneticModel::isValid ( ) const

Returns true if the model is valid and can be used.

Exceptions

QgsNotSupportedException if GeographicLib is not available

See also: error()

Definition at line 69 of file qgsmagneticmodel.cpp.

◆ maximumHeight()

double QgsMagneticModel::maximumHeight ( ) const

Returns the maximum height above the ellipsoid (in meters) for which the model should be used.

Exceptions

QgsNotSupportedException if GeographicLib is not available

See also: minimumHeight()

Definition at line 143 of file qgsmagneticmodel.cpp.

◆ maximumYear()

double QgsMagneticModel::maximumYear ( ) const

Returns the maximum time (in decimal years) for which the model should be used.

Exceptions

QgsNotSupportedException if GeographicLib is not available

See also: minimumYear()

Definition at line 161 of file qgsmagneticmodel.cpp.

◆ minimumHeight()

double QgsMagneticModel::minimumHeight ( ) const

Returns the minimum height above the ellipsoid (in meters) for which the model should be used.

Exceptions

QgsNotSupportedException if GeographicLib is not available

See also: maximumHeight()

Definition at line 134 of file qgsmagneticmodel.cpp.

◆ minimumYear()

double QgsMagneticModel::minimumYear ( ) const

Returns the minimum time (in decimal years) for which the model should be used.

Exceptions

QgsNotSupportedException if GeographicLib is not available

See also: maximumYear()

Definition at line 152 of file qgsmagneticmodel.cpp.

◆ name()

QString QgsMagneticModel::name ( ) const

Returns the name of the magnetic model.

Exceptions

QgsNotSupportedException if GeographicLib is not available

Definition at line 125 of file qgsmagneticmodel.cpp.

◆ operator=()

QgsMagneticModel & QgsMagneticModel::operator= ( const QgsMagneticModel & other )

delete

◆ order()

int QgsMagneticModel::order ( ) const

Returns the maximum order of the components of the model.

Exceptions

QgsNotSupportedException if GeographicLib is not available

See also: degree()

Definition at line 179 of file qgsmagneticmodel.cpp.

The documentation for this class was generated from the following files:

/build/qgis-3.99.0+git20260124+a8882ad4560+99sid/src/core/qgsmagneticmodel.h
/build/qgis-3.99.0+git20260124+a8882ad4560+99sid/src/core/qgsmagneticmodel.cpp

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ QgsMagneticModel() [1/2]

◆ ~QgsMagneticModel()

◆ QgsMagneticModel() [2/2]

Member Function Documentation

◆ dateTime()

◆ declination()

◆ defaultFilePath()

◆ defaultModelName()

◆ degree()

◆ description()

◆ directory()

◆ error()

◆ fieldComponents()

◆ fieldComponentsWithTimeDerivatives()

◆ file()

◆ getComponents()

◆ getComponentsWithTimeDerivatives()

◆ inclination()

◆ isValid()

◆ maximumHeight()

◆ maximumYear()

◆ minimumHeight()

◆ minimumYear()

◆ name()

◆ operator=()

◆ order()