1// -*- text -*- 2/** 3 * \file GeographicLib.dox 4 * \brief Documentation for GeographicLib 5 * 6 * Written by Charles Karney <charles@karney.com> and licensed under the 7 * MIT/X11 License. For more information, see 8 * https://geographiclib.sourceforge.io/ 9 **********************************************************************/ 10namespace GeographicLib { 11/** 12\mainpage GeographicLib library 13\author Charles F. F. Karney (charles@karney.com) 14\version @PROJECT_VERSION@ 15\date 2021-06-22 16 17The documentation for other versions is available at 18<tt>https://geographiclib.sourceforge.io/m.nn/</tt> for versions numbers 19<tt>m.nn</tt> ≥ 1.0. 20 21\section abstract Abstract 22 23GeographicLib is a small set of <a href="annotated.html">C++ 24classes</a> for performing conversions between geographic, UTM, UPS, 25MGRS, geocentric, and local cartesian coordinates, for gravity (e.g., 26EGM2008), geoid height and geomagnetic field (e.g., WMM2020) 27calculations, and for solving geodesic problems. The emphasis is on 28returning accurate results with errors close to round-off (about 5--15 29nanometers). Accurate algorithms for \ref geodesic and \ref 30transversemercator have been developed for this library. The 31functionality of the library can be accessed from user code, from the 32\ref utilities provided, or via the \ref other. Also included is a .NET 33wrapper library <a href="NET/index.html">NETGeographicLib</a> 34which exposes the functionality to .NET applications. For a sample of 35the geodesic capabilities in JavaScript, check out the 36<a href="../scripts/geod-calc.html">online geodesic calculator</a> and 37the script for displaying 38<a href="../scripts/geod-google.html">geodesics in Google Maps</a> 39 40This library is <i>not</i> a general purpose projection library nor does 41it perform datum conversions; instead use 42<a href="https://proj.org">PROJ</a>. On the other 43hand, it does provide the core functionality offered by 44<a href="http://earth-info.nga.mil/GandG/geotrans/">GEOTRANS</a>. 45 46\section download Download 47 48The main project page is at 49- https://sourceforge.net/projects/geographiclib 50. 51The code is available for download at 52- <a href="https://sourceforge.net/projects/geographiclib/files/distrib/GeographicLib-@PROJECT_VERSION@.tar.gz"> 53 GeographicLib-@PROJECT_VERSION@.tar.gz</a> 54- <a href="https://sourceforge.net/projects/geographiclib/files/distrib/GeographicLib-@PROJECT_VERSION@.zip"> 55 GeographicLib-@PROJECT_VERSION@.zip</a> 56. 57as either a compressed tar file (tar.gz) or a zip file. (The two 58archives have identical contents, except that the zip file has DOS 59line endings.) Alternatively you can get the latest release using git 60\verbatim 61 git clone git://git.code.sourceforge.net/p/geographiclib/code geographiclib 62\endverbatim 63Each release is tagged, e.g., with r@PROJECT_VERSION@. There are also 64binary installers available for some platforms. See \ref binaryinst. 65 66GeographicLib is licensed under the 67<a href="https://opensource.org/licenses/MIT">MIT/X11 License</a>; 68see <a href="LICENSE.txt">LICENSE.txt</a> for the terms. 69 70For more information on GeographicLib, see 71- https://geographiclib.sourceforge.io/. 72 73\section citint Citing GeographicLib 74 75When citing GeographicLib, use (adjust the version number and date as 76appropriate) 77- C. F. F. Karney, GeographicLib, Version @PROJECT_VERSION@ (2021-06-22), 78 https://geographiclib.sourceforge.io/@PROJECT_VERSION@ 79 80\section contents Contents 81 - \ref intro 82 - \ref install 83 - \ref start 84 - \ref utilities 85 - \ref organization 86 - \ref other 87 - \ref geoid 88 - \ref gravity 89 - \ref normalgravity 90 - \ref magnetic 91 - \ref geodesic 92 - \ref nearest 93 - \ref triaxial 94 - \ref jacobi 95 - \ref rhumb 96 - \ref greatellipse 97 - \ref transversemercator 98 - \ref geocentric 99 - \ref auxlat 100 - \ref highprec 101 - \ref changes 102 103<center> 104Forward to \ref intro. 105</center> 106 107**********************************************************************/ 108/** 109\page intro Introduction 110 111<center> 112Forward to \ref install. Up to \ref contents. 113</center> 114 115GeographicLib offers a C++ interfaces to a small (but important!) set 116of geographic transformations. It grew out of a desire to improve on 117the <a href="http://earth-info.nga.mil/GandG/geotrans/">GEOTRANS</a> 118package for transforming between geographic and MGRS coordinates. At 119present, GeographicLib provides UTM, UPS, MGRS, geocentric, and local 120cartesian projections, gravity and geomagnetic models, and classes for 121geodesic calculations. 122 123The goals of GeographicLib are: 124 - Accuracy. In most applications the accuracy is close to round-off, 125 about 5 nm (5 nanometers). Even though in many geographic 126 applications 1 cm is considered "accurate enough", there is little 127 penalty in providing much better accuracy. In situations where a 128 faster approximate algorithm is necessary, GeographicLib offers an 129 accurate benchmark to guide the development. 130 - Completeness. For each of the projections included, an attempt is 131 made to provide a complete solution. For example, 132 Geodesic::Inverse works for anti-podal points. 133 Similarly, Geocentric::Reverse will return accurate 134 geodetic coordinates even for points close to the center of the 135 earth. 136 - C++ interface. For the projection methods, this allows encapsulation 137 of the ellipsoid parameters. 138 - Emphasis on projections necessary for analyzing military data. 139 - Uniform treatment of UTM/UPS. The UTMUPS class treats 140 UPS as zone 0. This simplifies conversions between UTM and UPS 141 coordinates, etc. 142 - Well defined and stable conventions for the conversion between 143 UTM/UPS to MGRS coordinates. 144 - Detailed internal documentation on the algorithms. For the most part 145 GeographicLib uses published algorithms and references are given. If 146 changes have been made (usually to improve the numerical accuracy), 147 these are described in the code. 148 149Various \ref utilities are provided with the library. These illustrate 150the use of the library and are useful in their own right. This library 151and the utilities have been tested with C++11 compliant versions of g++ 152under Linux, with Apple LLVM 7.0.2 under Mac OS X, and with MS Visual 153Studio 14 (2015), 15 (2017), and 16 (2019) compiled for 32 bit and 64 154bit on Windows. 155 156MATLAB, JavaScript, and Python interfaces are provided to portions of 157GeographicLib; see \ref other. 158 159The section \ref geodesic documents the method of solving the geodesic 160problem. 161 162The section \ref transversemercator documents various properties of this 163projection. 164 165The bulk of the testing has used geographically relevant values of the 166flattening. Thus, you can expect close to full accuracy for −0.01 167≤ \e f ≤ 0.01 (but note that TransverseMercatorExact is restricted 168to \e f > 0). However, reasonably accurate results can be expected if 169−0.1 ≤ \e f ≤ 0.1. Outside this range, you should attempt 170to verify the accuracy of the routines independently. Two types of 171problems may occur with larger values of <i>f</i>: 172 - Some classes, specifically Geodesic, GeodesicLine, and 173 TransverseMercator, use series expansions using \e f as a small 174 parameter. The accuracy of these routines will degrade as \e f 175 becomes large. 176 - Even when exact formulas are used, many of the classes need to invert 177 the exact formulas (e.g., to invert a projection), typically, using 178 Newton's method. This usually provides an essentially exact 179 inversion. However, the choice of starting guess and the exit 180 conditions have been tuned to cover small values of \e f and the 181 inversion may be incorrect if \e f is large. 182 183Undoubtedly, bugs lurk in this code and in the documentation. Please 184report any you find to charles@karney.com. 185 186<center> 187Forward to \ref install. Up to \ref contents. 188</center> 189 190**********************************************************************/ 191/** 192\page install Installing GeographicLib 193 194<center> 195Back to \ref intro. Forward to \ref start. Up to \ref contents. 196</center> 197 198GeographicLib has been developed under Linux with the g++ compiler, 199under Mac OS X with Xcode, and under Windows with Visual Studio 2015 and 200later. It should compile on any systems with a C++11 compliant 201compiler. First download either 202<a href="https://sourceforge.net/projects/geographiclib/files/distrib/GeographicLib-@PROJECT_VERSION@.tar.gz"> 203GeographicLib-@PROJECT_VERSION@.tar.gz</a> or 204<a href="https://sourceforge.net/projects/geographiclib/files/distrib/GeographicLib-@PROJECT_VERSION@.zip"> 205GeographicLib-@PROJECT_VERSION@.zip</a> (or 206<a href="https://sourceforge.net/projects/geographiclib/files/distrib/GeographicLib-@PROJECT_VERSION@-win32.exe"> 207GeographicLib-@PROJECT_VERSION@-win32.exe</a> or 208<a href="https://sourceforge.net/projects/geographiclib/files/distrib/GeographicLib-@PROJECT_VERSION@-win64.exe"> 209GeographicLib-@PROJECT_VERSION@-win64.exe</a> 210for binary installation under Windows). 211Then pick one of the first five options below: 212- \ref cmake. This is the preferred installation method as it will work 213 on the widest range of platforms. However it requires that you have 214 <a href="https://www.cmake.org">cmake</a> installed. 215- \ref autoconf. This method works for most Unix-like systems, 216 including Linux and Mac OS X. 217- \ref gnu. This is a simple installation method that works with g++ 218 and GNU make on Linux and many Unix platforms. 219- \ref binaryinst. Use this installation method if you only need to use 220 the \ref utilities supplied with GeographicLib. 221- \ref qt. How to compile GeographicLib so that it can be used by Qt 222 programs. 223- \ref maintainer. This describes addition tasks of interest only to 224 the maintainers of this code. 225. 226This section documents only how to install the <i>software</i>. If you 227wish to use GeographicLib to evaluate geoid heights or the earth's 228gravitational or magnetic fields, then you must also install the 229relevant data files. See \ref geoidinst, \ref gravityinst, and \ref 230magneticinst for instructions. 231 232The first two installation methods use two important techniques which 233make software maintenance simpler 234- <b>Out-of-source builds:</b> This means that you create a separate 235 directory for compiling the code. In the description here the 236 directories are called BUILD and are located in the top-level of the 237 source tree. You might want to use a suffix to denote the type of 238 build, e.g., BUILD-vc14 for Visual Studio 14 (2015), or BUILD-shared 239 for a build which creates a shared library. The advantages of 240 out-of-source builds are: 241 - You don't mess up the source tree, so it's easy to "clean up". 242 Indeed the source tree might be on a read-only file system. 243 - Builds for multiple platforms or compilers don't interfere with each 244 other. 245- <b>The library is installed:</b> After compilation, there is a 246 separate <i>install</i> step which copies the headers, libraries, 247 tools, and documentation to a "central" location. You may at this 248 point delete the source and build directories. If you have 249 administrative privileges, you can install GeographicLib for the use 250 of all users (e.g., in /usr/local). Otherwise, you can install it for 251 your personal use (e.g., in $HOME/packages). 252 253\section cmake Installation with cmake 254 255This is the recommended method of installation; however it requires that 256<a href="https://www.cmake.org">cmake</a>, version 3.7.0 or later, be 257installed on your system. This permits GeographicLib to be built either 258as a shared or a static library on a wide variety of systems. cmake can 259also determine the capabilities of your system and adjust the 260compilation of the libraries and examples appropriately. 261 262cmake is available for most computer platforms. On Linux systems cmake 263will typically be one of the standard packages and can be installed by a 264command like 265 \verbatim 266 yum install cmake \endverbatim 267(executed as root). The minimum version of cmake supported for building 268GeographicLib is 3.1.0 (which was released on 2014-12-15). 269 270On other systems, download a binary installer from https://www.cmake.org 271click on download, and save and run the appropriate installer. Run the 272cmake command with no arguments to get help. Other useful tools are 273ccmake and cmake-gui which offer curses and graphical interfaces to 274cmake. Building under cmake depends on whether it is targeting an IDE 275(interactive development environment) or generating Unix-style 276makefiles. The instructions below have been tested with makefiles and 277g++ on Linux and with the Visual Studio IDE on Windows. It is known to 278work also for Visual Studio 2017 Build Tools. 279 280Here are the steps to compile and install GeographicLib: 281- Unpack the source, running one of \verbatim 282 tar xfpz GeographicLib-@PROJECT_VERSION@.tar.gz 283 unzip -q GeographicLib-@PROJECT_VERSION@.zip \endverbatim 284 then enter the directory created with \verbatim 285 cd GeographicLib-@PROJECT_VERSION@ \endverbatim 286- Create a separate build directory and enter it, for example, \verbatim 287 mkdir BUILD 288 cd BUILD \endverbatim 289- Run cmake, pointing it to the source directory (..). On Linux, Unix, 290 and MacOSX systems, the command is \verbatim 291 cmake .. \endverbatim 292 For Windows, the command is typically something like \verbatim 293 cmake -G "Visual Studio 14" -A win32 \ 294 -D CMAKE_INSTALL_PREFIX="C:/Program Files (x86)/GeographicLib-@PROJECT_VERSION@" \ 295 .. 296 cmake -G "Visual Studio 14" -A x64 \ 297 -D CMAKE_INSTALL_PREFIX="C:/Program Files/GeographicLib-@PROJECT_VERSION@" \ 298 ..\endverbatim 299 The definitions of CMAKE_INSTALL_PREFIX point to system directories. 300 You might instead prefer to install to a user directory such as 301 <code>C:/Users/jsmith/projects/GeographicLib-@PROJECT_VERSION@</code>. 302 The settings given above are recommended to ensure that packages that 303 use GeographicLib use the version compiled with the right compiler. 304 If you need to rerun cmake, use \verbatim 305 cmake . \endverbatim 306 possibly including some options via <code>-D</code> (see the next step). 307- cmake allows you to configure how GeographicLib is built and installed by 308 supplying options, for example \verbatim 309 cmake -D CMAKE_INSTALL_PREFIX=/tmp/geographic . \endverbatim 310 The options you might need to change are 311 - <code>COMMON_INSTALL_PATH</code> governs the installation 312 convention. If it is on ON (the Linux default), the installation 313 is to a common directory, e.g., /usr/local. If it is OFF (the 314 Windows default), the installation directory contains the package 315 name, e.g., 316 <code>C:/Program Files/GeographicLib-@PROJECT_VERSION@</code>. The 317 installation directories for the documentation, cmake configuration, 318 Python and MATLAB interfaces all depend on the variable with deeper 319 paths relative to CMAKE_INSTALL_PREFIX being used when it's ON: 320 - cmake configuration: OFF cmake; ON: lib/cmake/GeographicLib; 321 - documentation: OFF: doc/html; ON: share/doc/GeographicLib/html; 322 - JavaScript interface: OFF: node_modules; ON: lib/node_modules; 323 - Python interface: OFF: python; ON: lib/python/site-packages; 324 - MATLAB interface: OFF: matlab; ON: share/matlab. 325 . 326 - <code>CMAKE_INSTALL_PREFIX</code> (default: <code>/usr/local</code> 327 on non-Windows systems, <code>C:/Program Files (x86)/GeographicLib</code> 328 on Windows systems) specifies where the library will be installed. 329 For Windows systems, you might want to use a prefix which includes 330 the compiler version, in order to keep the libraries built with 331 different versions of the compiler in distinct locations. If you 332 just want to try the library to see if it suits your needs, pick, 333 for example, 334 <code>CMAKE_INSTALL_PREFIX</code>=/tmp/geographic. 335 - <code>GEOGRAPHICLIB_DATA</code> (default: 336 /usr/local/share/GeographicLib for non-Windows systems, 337 C:/ProgramData/GeographicLib for Windows systems) specifies the default 338 location for the various datasets for use by Geoid, 339 GravityModel, and MagneticModel. 340 See \ref geoidinst, \ref gravityinst, and \ref magneticinst for more 341 information. 342 - <code>GEOGRAPHICLIB_LIB_TYPE</code> (allowed values: SHARED, STATIC, or 343 BOTH), specifies the types of libraries build. The default is 344 STATIC for Windows and SHARED otherwise. If building GeographicLib 345 for system-wide use, BOTH is recommended, because this provides users 346 with the choice of which library to use. 347 - <code>CMAKE_BUILD_TYPE</code> (default: Release). This 348 flags only affects non-IDE compile environments (like make + g++). 349 The default is actually blank, but this is treated as 350 Release. Choose one of 351 \verbatim 352 Debug 353 Release 354 RelWithDebInfo 355 MinSizeRel 356\endverbatim 357 (With IDE compile environments, you get to select the build type in 358 the IDE.) 359 - <code>GEOGRAPHICLIB_DOCUMENTATION</code> (default: OFF). If set to 360 ON, then html documentation is created from the source files, 361 provided a sufficiently recent version of doxygen can be found. 362 Otherwise, the html documentation will redirect to the appropriate 363 version of the online documentation. 364 - <code>BUILD_NETGEOGRAPHICLIB</code> (default: OFF). If set to ON, 365 build the managed C++ wrapper library 366 <a href="NET/index.html">NETGeographicLib</a>. This only makes 367 sense for Windows systems. 368 - <code>GEOGRAPHICLIB_PRECISION</code> specifies the precision to be 369 used for "real" (i.e., floating point) numbers. Here are the 370 possible values 371 -# float (24-bit precision); typically this is far to inaccurate 372 for geodetic applications. 373 -# double precision (53-bit precision, the default). 374 -# long double (64-bit precision); this does not apply for Visual 375 Studio (long double is the same as double with that compiler). 376 -# quad precision (113-bit precision). 377 -# arbitrary precision. 378 . 379 See \ref highprec for additional information about the last two 380 values. Nearly all the testing has been carried out with doubles 381 and that's the recommended configuration. In particular you should 382 avoid "installing" the library with a precision different from 383 double. 384 - <code>USE_BOOST_FOR_EXAMPLES</code> (default: OFF). If set to ON, 385 then the Boost library is searched for in order to build the 386 NearestNeighbor example. 387 - <code>APPLE_MULTIPLE_ARCHITECTURES</code> (default: OFF). If set to 388 ON, build for i386 and x86_64 and Mac OS X systems. Otherwise, 389 build for the default architecture. 390 - <code>CONVERT_WARNINGS_TO_ERRORS</code> (default: OFF). If set to 391 ON, then compiler warnings are treated as errors. (This happens 392 also if you are a "developer", i.e., if the file 393 <code>tests/CMakeLists.txt</code> is present.) 394 . 395- Build and install the software. In non-IDE environments, run 396 \verbatim 397 make # compile the library and utilities 398 make test # run some tests 399 make install # as root, if CMAKE_INSTALL_PREFIX is a system directory 400\endverbatim 401 Possible additional targets are \verbatim 402 make dist 403 make exampleprograms 404 make netexamples (supported only for Release configuration) \endverbatim 405 On IDE environments, run your IDE (e.g., Visual Studio), load 406 GeographicLib.sln, pick the build type (e.g., Release), and select 407 "Build Solution". If this succeeds, select "RUN_TESTS" to build; 408 finally, select "INSTALL" to install (RUN_TESTS and INSTALL are in 409 the CMakePredefinedTargets folder). Alternatively (for example, if 410 you are using the Visual Studio 2017 Build Tools), you run the Visual 411 Studio compiler from the command line with \verbatim 412 cmake --build . --config Release --target ALL_BUILD 413 cmake --build . --config Release --target RUN_TESTS 414 cmake --build . --config Release --target INSTALL \endverbatim 415 For maximum flexibility, it's a good idea to build and install both 416 the Debug and Release versions of the library (in that order). The 417 installation directories will then contain the release versions of the 418 tools and <i>both</i> versions (debug and release) of the libraries. 419 If you use cmake to configure and build your programs, then the right 420 version of the library (debug vs. release) will automatically be used. 421- The headers, library, and utilities are installed in the 422 include/GeographicLib, lib, and bin directories under 423 <code>CMAKE_INSTALL_PREFIX</code>. (dll dynamic libraries are 424 installed in bin.) For documentation, open in a web browser 425 <a href="index.html"> 426 PREFIX/share/doc/GeographicLib/html/index.html</a>, if 427 COMMON_INSTALL_PATH is ON, or <a href="index.html"> 428 PREFIX/doc/index.html</a>, otherwise. 429- With cmake 3.13 and later, cmake can create the build directory for 430 you. This allows you to configure and run the build on Windows with 431 \verbatim 432 cmake -G "Visual Studio 14" -A x64 -S . -B BUILD 433 cmake --build BUILD --config Release --target ALL_BUILD \endverbatim 434 or on Linux with \verbatim 435 cmake -S . -B BUILD 436 make -C BUILD -j4 \endverbatim 437 438\section autoconf Installation using the autoconfigure tools 439 440The method works on most Unix-like systems including Linux and Mac OS X. 441Here are the steps to compile and install GeographicLib: 442- Unpack the source, running \verbatim 443 tar xfpz GeographicLib-@PROJECT_VERSION@.tar.gz \endverbatim 444 then enter the directory created \verbatim 445 cd GeographicLib-@PROJECT_VERSION@ \endverbatim 446- Create a separate build directory and enter it, for example, \verbatim 447 mkdir BUILD 448 cd BUILD \endverbatim 449- Configure the software, specifying the path of the source directory, 450 with \verbatim 451 ../configure \endverbatim 452- By default GeographicLib will be installed under /usr/local. 453 You can change this with, for example \verbatim 454 ../configure --prefix=/tmp/geographic \endverbatim 455- Compile and install the software with \verbatim 456 make 457 make install \endverbatim 458- The headers, library, and utilities are installed in the 459 include/GeographicLib, lib, and bin directories under 460 <code>prefix</code>. For documentation, open <a href="index.html"> 461 share/doc/GeographicLib/html/index.html</a> in a web browser. 462 463\section gnu Installation with GNU compiler and Make 464 465This method requires the standard GNU suite of tools, in particular make 466and g++. This builds a static library and the examples. 467 468Here are the steps to compile and install GeographicLib: 469- Unpack the source, running \verbatim 470 tar xfpz GeographicLib-@PROJECT_VERSION@.tar.gz \endverbatim 471 then enter the directory created \verbatim 472 cd GeographicLib-@PROJECT_VERSION@ \endverbatim 473- Edit \verbatim 474 include/GeographicLib/Config.h \endverbatim 475 If your C++ compiler does not recognize the long double type 476 (unlikely), insert \code 477 #undef GEOGRAPHICLIB_HAVE_LONG_DOUBLE \endcode 478 If your machine using big endian ordering, then insert \code 479 #define GEOGRAPHICLIB_WORDS_BIGENDIAN 1 \endcode 480- Build and install the software: \verbatim 481 make # compile the library and the tools 482 make install # as root \endverbatim 483 The installation is in directories under /usr/local. You 484 can specify a different installation directory with, for example, 485 \verbatim 486 make PREFIX=/tmp/geographic install \endverbatim 487- The headers, library, and utilities are installed in the 488 include/GeographicLib, lib, and bin directories under 489 <code>PREFIX</code>. For documentation, open <a href="index.html"> 490 share/doc/GeographicLib/html/index.html</a> in a web browser. 491 492\section binaryinst Using a binary installer 493 494Binary installers are available for some platforms 495 496\subsection binaryinstwin Windows 497 498Use this method if you only need to use the GeographicLib utilities. 499The header files and static and shared versions of library are also 500provided; these can only be used by Visual Studio 14 2015 or later (2017 501or 2019) (in either release or debug mode). However, if you plan to use 502the library, it may be advisable to build it with the compiler you are 503using for your own code using \ref cmake. 504 505Download and run 506<a href="https://sourceforge.net/projects/geographiclib/files/distrib/GeographicLib-@PROJECT_VERSION@-win32.exe"> 507GeographicLib-@PROJECT_VERSION@-win32.exe</a> or 508<a href="https://sourceforge.net/projects/geographiclib/files/distrib/GeographicLib-@PROJECT_VERSION@-win64.exe"> 509GeographicLib-@PROJECT_VERSION@-win64.exe</a>: 510 - read the MIT/X11 License agreement, 511 - select whether you want your PATH modified, 512 - select the installation folder, by default 513 C:\\Program Files\\GeographicLib-@PROJECT_VERSION@ or 514 C:\\Program Files (x86)\\GeographicLib-@PROJECT_VERSION@, 515 - select the start menu folder, 516 - and install. 517 . 518(Note that the default installation folder adheres the the convention 519given in \ref cmake.) The start menu will now include links to the 520documentation for the library and for the utilities (and a link for 521uninstalling the library). If you ask for your PATH to be modified, it 522will include 523<code>C:/Program Files{, (x86)}/GeographicLib-@PROJECT_VERSION@/bin</code> 524where the utilities are installed. The headers and library are 525installed in the include/GeographicLib and lib folders. The libraries 526were built using using Visual Studio 14 2015 in release and debug modes. 527The utilities were linked against the release-mode shared library. 528 529<a href="NET/index.html">NETGeographicLib</a> library dlls (release and 530debug) are included with the binary installers; these are linked against 531the shared library for GeographicLib. 532 533Also included are the Python, JavaScript, and MATLAB interfaces. 534 535\subsection binaryinstosx MacOSX 536 537You can install using Homebrew. Follow the directions on 538https://brew.sh/ for installing this package manager. Then type 539\verbatim 540brew install geographiclib \endverbatim 541Now links to GeographicLib are installed under /usr/local. 542 543\subsection binaryinstlin Linux 544 545Some Linux distributions, Fedora, Debian, and Ubuntu, offer 546GeographicLib as a standard package. Typically these will be one or two 547versions behind the latest. 548 549\section qt Building the library for use with Qt 550 551If Qt is using a standard compiler, then build GeographicLib with that 552same compiler (and optimization flags) as Qt. 553 554If you are using the mingw compiler on Windows for Qt, then you need to 555build GeographicLib with mingw. You can accomplish this with cmake 556under cygwin with, for example, \verbatim 557 export PATH="`cygpath c:/QtSDK/mingw/bin`:$PATH" 558 mkdir BUILD 559 cd BUILD 560 cmake -G "MinGW Makefiles" -D CMAKE_INSTALL_PREFIX="C:/Program Files/GeographicLib" .. 561 mingw32-make 562 mingw32-make install \endverbatim 563If cmake complains that sh mustn't be in your path, invoke cmake with 564\verbatim 565 env PATH="$( echo $PATH | tr : '\n' | 566 while read d; do test -f "$d/sh.exe" || echo -n "$d:"; done | 567 sed 's/:$//' )" \ 568 cmake -G "MinGW Makefiles" -D CMAKE_INSTALL_PREFIX="C:/Program Files/GeographicLib" .. 569\endverbatim 570 571\section maintainer Maintainer tasks 572 573Check the code out of git with \verbatim 574 git clone -b master git://git.code.sourceforge.net/p/geographiclib/code geographiclib 575\endverbatim 576Here the "master" branch is checked out. There are three branches in 577the git repository: 578- <b>master</b>: the main branch for code maintenance. Releases are 579 tagged on this branch as, e.g., v@PROJECT_VERSION@. 580- <b>devel</b>: the development branch; changes made here are merged 581 into master. 582- <b>release</b>: the release branch created by unpacking the source 583 releases (git is \e not used to merge changes from the other 584 branches into this branch). This is the \e default branch of the 585 repository (the branch you get if cloning the repository without 586 specifying a branch). This differs from the master branch in that 587 some administrative files are excluded while some intermediate files 588 are included (in order to aid building on as many platforms as 589 possible). Releases are tagged on this branch as, e.g., 590 r@PROJECT_VERSION@. 591. 592The autoconf configuration script and the formatted man pages are not 593checked into master branch of the repository. In order to create the 594autoconf configuration script, run \verbatim 595 sh autogen.sh \endverbatim 596in the top level directory. Provided you are running on a system with 597doxygen, pod2man, and pod2html installed, then you can create the 598documentation and the man pages by building the system using cmake or 599configure. 600 601In the case of cmake, you then run \verbatim 602 make dist \endverbatim 603which will copy the man pages from the build directory back into the 604source tree and package the resulting source tree for distribution as 605\verbatim 606 GeographicLib-@PROJECT_VERSION@.tar.gz 607 GeographicLib-@PROJECT_VERSION@.zip \endverbatim 608Finally, \verbatim 609 make package \endverbatim 610or building PACKAGE in Visual Studio will create a binary installer for 611GeographicLib. For Windows, this requires in the installation of 612<a href="https://nsis.sourceforge.io">NSIS</a>. On Windows, you should 613configure GeographicLib with <code>PACKAGE_DEBUG_LIBS</code>=ON, build both 614Release and Debug versions of the library and finally build PACKAGE in 615Release mode. This will get the release and debug versions of the 616library included in the package. For example, the 64-bit binary 617installer is created with \verbatim 618 cmake -G "Visual Studio 14" -A x64 \ 619 -D GEOGRAPHICLIB_LIB_TYPE=BOTH \ 620 -D PACKAGE_DEBUG_LIBS=ON \ 621 -D BUILD_NETGEOGRAPHICLIB=ON \ 622 .. 623 cmake --build . --config Debug --target ALL_BUILD 624 cmake --build . --config Release --target ALL_BUILD 625 cmake --build . --config Release --target matlabinterface 626 cmake --build . --config Release --target PACKAGE \endverbatim 627 628With configure, run \verbatim 629 make dist-gzip \endverbatim 630which will create the additional files and packages the results ready 631for distribution as \verbatim 632 geographiclib-@PROJECT_VERSION@.tar.gz \endverbatim 633 634Prior to making a release, the script 635<code>tests/test-distribution.sh</code> is run on a Fedora system. This 636checked that the library compiles correctly is multiple configurations. 637In addition it creates a directory and scripts for checking the 638compilation on Windows. 639 640The following Fedora packages are required by 641<code>tests/test-distribution.sh</code> 642- cmake 643- automake 644- autoconf-archive 645- libtool 646- gcc-c++ 647- gcc-gfortran 648- ccache 649- doxygen 650- boost-devel 651- mpfr-devel 652- octave 653- python2 654- python3-sphinx 655- nodejs 656- maven 657. 658 659The following npm packages need to be installed (jshint is just for 660syntax checking) \verbatim 661 npm install -g mocha jsdoc jshint \endverbatim 662The following Fedora package is also useful for syntax checking python 663- pylint 664. 665Installing the python package requires the following \verbatim 666 python3 -m pip install --user --upgrade setuptools wheel twine \endverbatim 667mpreal.h, version 3.6.8 or later, needs to be downloaded from 668https://github.com/advanpix/mpreal and installed in the 669<code>include/</code> directory. (Version 3.6.8 requires also the fixes 670given in pull requests #8 and #10.) For all the tests to be run, 671the following datasets need to be installed 672- geoid models: egm96-5 673- magnetic models: wmm2010 emm2015 674- gravity models: egm2008 grs80 675 676<center> 677Back to \ref intro. Forward to \ref start. Up to \ref contents. 678</center> 679 680**********************************************************************/ 681/** 682\page start Getting started 683 684<center> 685Back to \ref install. Forward to \ref utilities. Up to \ref contents. 686</center> 687 688Much (but not all!) of the useful functionality of GeographicLib is 689available via simple command line utilities. Interfaces to some of them 690are available via the web. See \ref utilities for documentation on 691these. 692 693In order to use GeographicLib from C++ code, you will need to 694- Include the header files for the GeographicLib classes in your code. 695 E.g., \code 696 #include <GeographicLib/LambertConformalConic.hpp> \endcode 697- Include the GeographicLib:: namespace prefix to the GeographicLib classes, 698 or include \code 699 using namespace GeographicLib; \endcode 700 in your code. 701- Finally compile and link your code. You have two options here. 702 - Use cmake to build your package. If you are familiar with cmake 703 this typically will be far the simplest option. 704 - Set the include paths and linking options "manually". 705- Building your code with cmake. In brief, the necessary steps are: 706 - include in your CMakeLists.txt files \verbatim 707 find_package (GeographicLib REQUIRED) 708 add_executable (program source1.cpp source2.cpp) 709 target_link_libraries (program ${GeographicLib_LIBRARIES}) \endverbatim 710 - configure your package, e.g., with \verbatim 711 mkdir BUILD 712 cd BUILD 713 cmake -G "Visual Studio 14" -A x64 \ 714 -D CMAKE_PREFIX_PATH="C:/Program Files" \ 715 -D CMAKE_INSTALL_PREFIX="C:/Program Files/testgeog" \ 716 .. \endverbatim 717 Note that you almost always want to configure and build your code 718 somewhere other than the source directory (in this case, we use the 719 BUILD subdirectory). Also, on Windows, make sure that the version 720 of Visual Studio (14 in the example above) architecture (x64 in the 721 example above) is compatible with that used to build GeographicLib. 722 In this example, it's not necessary to specify 723 <code>CMAKE_PREFIX_PATH</code>, because <code>C:/Program 724 Files</code> is one of the system paths which is searched 725 automatically. 726 - build your package. On Linux and MacOS this usually involves just 727 running make. On Windows, you can load the solution file created by 728 cmake into Visual Studio; alternatively, you can get cmake to run 729 build your code with \verbatim 730 cmake --build . --config Release --target ALL_BUILD \endverbatim 731 You might also want to install your package (using "make install" or 732 build the "INSTALL" target with the command above). 733 - With cmake 3.13 and later, cmake can create the build directory for 734 you. This allows you to configure and run the build on Windows with 735 \verbatim 736 cmake -G "Visual Studio 14" -A x64 \ 737 -D CMAKE_PREFIX_PATH="C:/Program Files" \ 738 -D CMAKE_INSTALL_PREFIX="C:/Program Files/testgeog" \ 739 -S . -B BUILD 740 cmake --build BUILD --config Release --target ALL_BUILD \endverbatim 741 or on Linux with \verbatim 742 cmake -D CMAKE_INSTALL_PREFIX="/tmp/testgeog" \ 743 -S . -B BUILD 744 make -C BUILD -j4 \endverbatim 745 . 746 The most import step is the find_package command. The cmake 747 documentation describes the locations searched by find_package (the 748 appropriate rule for GeographicLib are those for "Config" mode lookups). 749 In brief, the locations that are searched are (from least specific to 750 most specific, i.e., in <i>reverse</i> order) are 751 - under the system paths, i.e., locations such as <code>C:/Program 752 Files</code> and <code>/usr/local</code>); 753 - frequently, it's necessary to search within a "package directory" 754 (or set of directories) for external dependencies; this is given by 755 a (semicolon separated) list of directories specified by the cmake 756 variable <code>CMAKE_PREFIX_PATH</code> (illustrated above); 757 - the package directory for GeographicLib can be overridden with the 758 <i>environment variable</i> <code>GeographicLib_DIR</code> (which is the 759 directory under which GeographicLib is installed); 760 - finally, if you need to point to a particular build of GeographicLib, 761 define the <i>cmake variable</i> <code>GeographicLib_DIR</code>, which 762 specifies the absolute path of the directory containing the 763 configuration file <code>geographiclib-config.cmake</code> (for 764 debugging this may be the top-level <i>build</i> directory, as 765 opposed to <i>installation</i> directory, for GeographicLib). 766 . 767 Typically, specifying nothing or <code>CMAKE_PREFIX_PATH</code> 768 suffices. However the two <code>GeographicLib_DIR</code> variables allow 769 for a specific version to be chosen. On Windows systems (with Visual 770 Studio), find_package will only find versions of GeographicLib built with 771 the right version of the compiler. (If you used a non-cmake method of 772 installing GeographicLib, you can try copying cmake/FindGeographicLib.cmake 773 to somewhere in your <code>CMAKE_MODULE_PATH</code> in order for 774 find_package to work. However, this method has not been thoroughly 775 tested.) 776 777 If GeographicLib is not found, check the values of 778 <code>GeographicLib_CONSIDERED_CONFIGS</code> and 779 <code>GeographicLib_CONSIDERED_VERSIONS</code>; these list the 780 configuration files and corresponding versions which were considered 781 by find_package. 782 783 If GeographicLib is found, then the following cmake variables are set: 784 - <code>GeographicLib_FOUND</code> = 1 785 - <code>GeographicLib_VERSION</code> = @PROJECT_VERSION@ 786 - <code>GeographicLib_INCLUDE_DIRS</code> 787 - <code>GeographicLib_LIBRARIES</code> = one of the following two: 788 - <code>GeographicLib_SHARED_LIBRARIES</code> = GeographicLib::GeographicLib_SHARED 789 - <code>GeographicLib_STATIC_LIBRARIES</code> = GeographicLib::GeographicLib_STATIC 790 - <code>GeographicLib_LIBRARY_DIRS</code> 791 - <code>GeographicLib_BINARY_DIRS</code> 792 - <code>GEOGRAPHICLIB_DATA</code> = value of this compile-time parameter 793 . 794 Either of <code>GeographicLib_SHARED_LIBRARIES</code> or 795 <code>GeographicLib_STATIC_LIBRARIES</code> may be empty, if that version 796 of the library is unavailable. If you require a specific version, 797 SHARED or STATIC, of the library, add a <code>COMPONENTS</code> clause 798 to find_package, e.g., 799 \verbatim 800 find_package (GeographicLib 1.34 REQUIRED COMPONENTS SHARED) \endverbatim 801 causes only packages which include the shared library to be found. If 802 the package includes both versions of the library, then 803 <code>GeographicLib_LIBRARIES</code> is set to the shared version, 804 unless you include \verbatim 805 set (GeographicLib_USE_STATIC_LIBS ON) \endverbatim 806 <i>before</i> the find_package command. You can check whether 807 <code>GeographicLib_LIBRARIES</code> refers to the shared or static 808 library with \verbatim 809 get_target_property(_LIBTYPE ${GeographicLib_LIBRARIES} TYPE) \endverbatim 810 which results in <code>_LIBTYPE</code> being set to 811 <code>SHARED_LIBRARY</code> or <code>STATIC_LIBRARY</code>. 812 On Windows, cmake takes care of linking to the release or debug 813 version of the library as appropriate. (This assumes that the Release 814 and Debug versions of the libraries were built and installed. This is 815 true for the Windows binary installer for GeographicLib version 1.34 and 816 later.) 817- Here are the steps to compile and link your code using GeographicLib 818 "manually". 819 - Tell the compiler where to find the header files. With g++ and with 820 /usr/local specified as the installation directory, 821 this is accomplished with \verbatim 822 g++ -c -g -O3 -I/usr/local/include testprogram.cpp 823 \endverbatim 824 With Visual Studio, specify the include directory in the IDE via, 825 e.g., 826 \verbatim 827 C/C++ -> General -> Additional Include Directories = C:\pkg-vc14-x64\GeographicLib\include 828 \endverbatim 829 - If using the shared (or static) library with Visual Studio, define 830 the macro <code>GEOGRAPHICLIB_SHARED_LIB=1</code> (or 831 <code>0</code>), e.g., 832 \verbatim 833 C/C++ -> Preprocessor -> Preprocessor Definitions = GEOGRAPHICLIB_SHARED_LIB=1 834 \endverbatim 835 This is only needed for Windows systems when both shared and static 836 libraries have been installed. (If you configure your package with 837 cmake, this definition is added automatically.) 838 - Tell the linker the name, Geographic, and location of the 839 library. Using g++ as the linker, you would use \verbatim 840 g++ -g -o testprogram testprogram.o -L/usr/local/lib -lGeographic 841 \endverbatim 842 With Visual Studio, you supply this information in the IDE via, 843 e.g., \verbatim 844 Linker -> Input -> Additional Dependencies = Geographic-i.lib (for shared library) 845 Linker -> Input -> Additional Dependencies = Geographic.lib (for static library) 846 Linker -> General -> Additional Library Directories = C:\pkg-vc14-x64\Geographic\lib 847 \endverbatim 848 Note that the library name is <b>Geographic</b> and not 849 GeographicLib. For the Debug version of your program on Windows 850 add "_d" to the library, e.g., Geographic_d-i.lib or 851 Geographic_d.lib. 852 - Tell the runtime environment where to find the shared library 853 (assuming you compiled %Geographic as a shared library). With g++, 854 this is accomplished by modifying the link line above to read \verbatim 855 g++ -g -o testprogram testprogram.o -Wl,-rpath=/usr/local/lib \ 856 -L/usr/local/lib -lGeographic 857 \endverbatim 858 (There are two other ways to specify the location of shared libraries 859 at runtime: (1) define the environment variable 860 <code>LD_LIBRARY_PATH</code> to be a colon-separated list of 861 directories to search; (2) as <b>root</b>, specify /usr/local/lib as a 862 directory searched by ldconfig(8).) On Windows, you need to ensure 863 that Geographic.dll or Geographic_d.dll is in the same directory as 864 your executable or else include the directory containing the dll in 865 your <code>PATH</code>. 866 - You can also use the pkg-config utility to specify compile and link 867 flags. This requires that pkg-config be installed and that it's 868 configured to search, e.g., /usr/local/lib/pgkconfig; if not, define 869 the environment variable <code>PKG_CONFIG_PATH</code> to include 870 this directory. The compile and link steps under Linux would 871 typically be 872 \verbatim 873 g++ -c -g -O3 `pkg-config --cflags geographiclib` testprogram.cpp 874 g++ -g -o testprogram testprogram.o `pkg-config --libs geographiclib` 875 \endverbatim 876 877Here is a very simple test code, which uses the Geodesic 878class: 879\include example-Geodesic-small.cpp 880This example is <code>examples/example-Geodesic-small.cpp</code>. If you 881compile, link, and run it according to the instructions above, it should 882print out \verbatim 883 5551.76 km \endverbatim 884Here is a complete CMakeList.txt files you can use to build this test 885code using the installed library: \verbatim 886project (geodesictest) 887cmake_minimum_required (VERSION 3.1.0) 888 889find_package (GeographicLib REQUIRED) 890 891if (NOT MSVC) 892 set (CMAKE_INSTALL_RPATH_USE_LINK_PATH TRUE) 893endif () 894 895add_executable (${PROJECT_NAME} example-Geodesic-small.cpp) 896target_link_libraries (${PROJECT_NAME} ${GeographicLib_LIBRARIES}) 897 898if (MSVC) 899 get_target_property (_LIBTYPE ${GeographicLib_LIBRARIES} TYPE) 900 if (_LIBTYPE STREQUAL "SHARED_LIBRARY") 901 # On Windows systems, copy the shared library to build directory 902 add_custom_command (TARGET ${PROJECT_NAME} POST_BUILD 903 COMMAND ${CMAKE_COMMAND} -E 904 copy $<TARGET_FILE:${GeographicLib_LIBRARIES}> ${CMAKE_CFG_INTDIR} 905 COMMENT "Copying shared library for GeographicLib") 906 endif () 907endif () \endverbatim 908 909The next steps are: 910 - Learn about and run the \ref utilities. 911 - Read the section, \ref organization, for an overview of the library. 912 - Browse the <a href="annotated.html">Class List</a> for full documentation 913 on the classes in the library. 914 - Look at the example code in the examples directory. Each file 915 provides a very simple standalone example of using one GeographicLib 916 class. These are included in the descriptions of the classes. 917 - Look at the source code for the utilities in the tools directory for 918 more examples of using GeographicLib from C++ code, e.g., 919 GeodesicProj.cpp is a program to performing various geodesic 920 projections. 921 922Here's a list of some of the abbreviations used here with links to the 923corresponding Wikipedia articles: 924 - <a href="https://en.wikipedia.org/wiki/WGS84"> 925 WGS84</a>, World Geodetic System 1984. 926 - <a href="https://en.wikipedia.org/wiki/Universal_Transverse_Mercator_coordinate_system"> 927 UTM</a>, Universal Transverse Mercator coordinate system. 928 - <a href="https://en.wikipedia.org/wiki/Universal_Polar_Stereographic"> 929 UPS</a>, Universal Polar Stereographic coordinate system. 930 - <a href="https://en.wikipedia.org/wiki/Military_grid_reference_system"> 931 MGRS</a>, Military Grid Reference System. 932 - <a href="https://en.wikipedia.org/wiki/Geoid"> 933 EGM</a>, Earth Gravity Model. 934 - <a href="https://en.wikipedia.org/wiki/World_Magnetic_Model"> 935 WMM</a>, World Magnetic Model. 936 - <a href="https://en.wikipedia.org/wiki/IGRF"> 937 IGRF</a>, International Geomagnetic Reference Field. 938 939<center> 940Back to \ref install. Forward to \ref utilities. Up to \ref contents. 941</center> 942 943**********************************************************************/ 944/** 945\page utilities Utility programs 946 947<center> 948Back to \ref start. Forward to \ref organization. Up to \ref contents. 949</center> 950 951Various utility programs are provided with GeographicLib. These should 952be installed in a directory included in your PATH (e.g., 953/usr/local/bin). These programs are wrapper programs that invoke 954the underlying functionality provided by the library. 955 956The utilities are 957 - <a href="GeoConvert.1.html"> 958 <b>GeoConvert</b></a>: convert geographic coordinates using 959 GeoCoords. See \ref GeoConvert.cpp. 960 - <a href="GeodSolve.1.html"> 961 <b>GeodSolve</b></a>: perform geodesic calculations using 962 Geodesic and GeodesicLine. See \ref GeodSolve.cpp. 963 - <a href="Planimeter.1.html"> 964 <b>Planimeter</b></a>: compute the area of geodesic polygons using 965 PolygonAreaT. See \ref Planimeter.cpp. 966 - <a href="TransverseMercatorProj.1.html"> 967 <b>TransverseMercatorProj</b></a>: convert between geographic 968 and transverse Mercator. This is for testing 969 TransverseMercatorExact and 970 TransverseMercator. See \ref TransverseMercatorProj.cpp. 971 - <a href="CartConvert.1.html"> 972 <b>CartConvert</b></a>: convert geodetic coordinates to geocentric or 973 local cartesian using Geocentric and 974 LocalCartesian. See \ref CartConvert.cpp. 975 - <a href="GeodesicProj.1.html"> 976 <b>GeodesicProj</b></a>: perform projections based on geodesics 977 using AzimuthalEquidistant, Gnomonic, 978 and CassiniSoldner. See \ref GeodesicProj.cpp. 979 - <a href="ConicProj.1.html"> 980 <b>ConicProj</b></a>: perform conic projections using 981 LambertConformalConic and 982 AlbersEqualArea. See \ref ConicProj.cpp. 983 - <a href="GeoidEval.1.html"> 984 <b>GeoidEval</b></a>: look up geoid heights using 985 Geoid. See \ref GeoidEval.cpp. 986 - <a href="Gravity.1.html"> 987 <b>Gravity</b></a>: compute the earth's gravitational field using 988 GravityModel and GravityCircle. See \ref Gravity.cpp. 989 - <a href="MagneticField.1.html"> 990 <b>MagneticField</b></a>: compute the earth's magnetic field using 991 MagneticModel and MagneticCircle. See \ref MagneticField.cpp. 992 - <a href="RhumbSolve.1.html"> 993 <b>RhumbSolve</b></a>: perform rhumb line calculations using Rhumb 994 and RhumbLine. See \ref RhumbSolve.cpp. 995 . 996The documentation for these utilities is in the form of man pages. This 997documentation can be accessed by clicking on the utility name in the 998list above, running the man command on Unix-like systems, or by invoking 999the utility with the <code>\--help</code> option. A brief summary of 1000usage is given by invoking the utility with the <code>-h</code> option. 1001The version of the utility is given by the <code>\--version</code> 1002option. 1003 1004The utilities all accept data on standard input, transform it in some 1005way, and print the results on standard output. This makes the utilities 1006easy to use within scripts to transform tabular data; however they can 1007also be used interactively, often with the input supplied via a pipe, 1008e.g., 1009 - echo 38SMB4488 | GeoConvert -d 1010 1011Online versions of four of these utilities are provided: 1012 - <a href="https://geographiclib.sourceforge.io/cgi-bin/GeoConvert">GeoConvert</a> 1013 - <a href="https://geographiclib.sourceforge.io/cgi-bin/GeodSolve">GeodSolve</a> 1014 - <a href="https://geographiclib.sourceforge.io/cgi-bin/Planimeter">Planimeter</a> 1015 - <a href="https://geographiclib.sourceforge.io/cgi-bin/GeoidEval">GeoidEval</a> 1016 - <a href="https://geographiclib.sourceforge.io/cgi-bin/RhumbSolve">RhumbSolve</a> 1017 1018<center> 1019Back to \ref start. Forward to \ref organization. Up to \ref contents. 1020</center> 1021 1022**********************************************************************/ 1023/** 1024\page organization Code organization 1025 1026<center> 1027Back to \ref utilities. Forward to \ref other. Up to \ref contents. 1028</center> 1029 1030Here is a brief description of the relationship between the various 1031components of GeographicLib. All of these are defined in the 1032GeographicLib namespace. 1033 1034TransverseMercator, PolarStereographic, LambertConformalConic, and 1035AlbersEqualArea provide the basic projections. The constructors for 1036these classes specify the ellipsoid and the forward and reverse 1037projections are implemented as const member functions. 1038TransverseMercator uses Krüger's series which have been extended to 1039sixth order in the square of the eccentricity. PolarStereographic, 1040LambertConformalConic, and AlbersEqualArea use the exact formulas for 1041the projections (e.g., from Snyder). 1042 1043TransverseMercator::UTM and PolarStereographic::UPS are const static 1044instantiations specific for the WGS84 ellipsoid with the UTM and UPS 1045scale factors. (These do \e not add the standard false eastings or 1046false northings for UTM and UPS.) Similarly 1047LambertConformalConic::Mercator is a const static instantiation of this 1048projection for a WGS84 ellipsoid and a standard parallel of 0 (which 1049gives the Mercator projection). AlbersEqualArea::CylindricalEqualArea, 1050AzimuthalEqualAreaNorth, and AzimuthalEqualAreaSouth, likewise provide 1051special cases of the equal area projection. 1052 1053UTMUPS uses TransverseMercator::UTM and PolarStereographic::UPS to 1054perform the UTM and UPS projections. The class offers a uniform 1055interface to UTM and UPS by treating UPS as UTM zone 0. This class 1056stores no internal state and the forward and reverse projections are 1057provided via static member functions. The forward projection offers the 1058ability to override the standard UTM/UPS choice and the UTM zone. 1059 1060MGRS transforms between UTM/UPS coordinates and MGRS. 1061UPS coordinates are handled as UTM zone 0. This class stores no 1062internal state and the forward (UTM/UPS to MGRS) and reverse (MGRS to 1063UTM/UPS) conversions are provided via static member functions. 1064 1065GeoCoords holds a single geographic location which may be 1066specified as latitude and longitude, UTM or UPS, or MGRS. Member 1067functions are provided to convert between coordinate systems and to 1068provide formatted representations of them. 1069<a href="GeoConvert.1.html">GeoConvert</a> is a simple command line 1070utility to provide access to the GeoCoords class. 1071 1072TransverseMercatorExact is a drop in replacement for TransverseMercator 1073which uses the exact formulas, based on elliptic functions, for the 1074projection as given by Lee. 1075<a href="TransverseMercatorProj.1.html">TransverseMercatorProj</a> is a 1076simple command line utility to test to the TransverseMercator and 1077TransverseMercatorExact. 1078 1079Geodesic and GeodesicLine perform geodesic calculations. The 1080constructor for Geodesic specifies the ellipsoid and the direct and 1081inverse calculations are implemented as const member functions. 1082Geocentric::WGS84 is a const static instantiation of Geodesic specific 1083for the WGS84 ellipsoid. In order to perform a series of direct 1084geodesic calculations on a single line, the GeodesicLine class can be 1085used. This packages all the information needed to specify a geodesic. 1086A const member function returns the coordinates a specified distance 1087from the starting point. <a href="GeodSolve.1.html">GeodSolve</a> is a 1088simple command line utility to perform geodesic calculations. 1089PolygonAreaT is a class which compute the area of geodesic polygons 1090using the Geodesic class and <a href="Planimeter.1.html">Planimeter</a> 1091is a command line utility for the same purpose. AzimuthalEquidistant, 1092CassiniSoldner, and Gnomonic are projections based on the Geodesic 1093class. <a href="GeodesicProj.1.html">GeodesicProj</a> is a command line 1094utility to exercise these projections. 1095 1096GeodesicExact and GeodesicLineExact are drop in replacements for 1097Geodesic and GeodesicLine in which the solution is given in terms of 1098elliptic integrals (computed by EllipticFunction). These classes should 1099be used if the absolute value of the flattening exceeds 0.02. The -E 1100option to <a href="GeodSolve.1.html">GeodSolve</a> uses these classes. 1101 1102NearestNeighbor is a header-only class for efficiently \ref nearest of a 1103collection of points where the distance function obeys the triangle 1104inequality. The geodesic distance obeys this condition. 1105 1106Geocentric and LocalCartesian convert between 1107geodetic and geocentric or a local cartesian system. The constructor for 1108specifies the ellipsoid and the forward and reverse projections are 1109implemented as const member functions. Geocentric::WGS84 is a 1110const static instantiation of Geocentric specific for the WGS84 ellipsoid. 1111<a href="CartConvert.1.html">CartConvert</a> is a simple command line 1112utility to provide access to these classes. 1113 1114Geoid evaluates geoid heights by interpolation. This is 1115provided by the operator() member function. 1116<a href="GeoidEval.1.html">GeoidEval</a> is a simple command line 1117utility to provide access to this class. This class requires 1118installation of data files for the various geoid models; see \ref 1119geoidinst for details. 1120 1121Ellipsoid is a class which performs latitude 1122conversions and returns various properties of the ellipsoid. 1123 1124GravityModel evaluates the earth's gravitational field using a 1125particular gravity model. Various member functions return the 1126gravitational field, the gravity disturbance, the gravity anomaly, and 1127the geoid height <a href="Gravity.1.html">Gravity</a> is a simple 1128command line utility to provide access to this class. If the field 1129several points on a circle of latitude are sought then use 1130GravityModel::Circle to return a GravityCircle object whose member 1131functions performs the calculations efficiently. (This is particularly 1132important for high degree models such as EGM2008.) These classes 1133requires installation of data files for the various gravity models; see 1134\ref gravityinst for details. NormalGravity computes the gravity of the 1135so-called level ellipsoid. 1136 1137MagneticModel evaluates the earth's magnetic field using a particular 1138magnetic model. The field is provided by the operator() member 1139function. <a href="MagneticField.1.html">MagneticField</a> is a simple 1140command line utility to provide access to this class. If the field 1141several points on a circle of latitude are sought then use 1142MagneticModel::Circle to return a MagneticCircle object whose operator() 1143member function performs the calculation efficiently. (This is 1144particularly important for high degree models such as emm2010.) These 1145classes requires installation of data files for the various magnetic 1146models; see \ref magneticinst for details. 1147 1148Constants, Math, Utility, DMS, are general utility class which are used 1149internally by the library; in addition EllipticFunction is used by 1150TransverseMercatorExact, Ellipsoid, and GeodesicExact, and 1151GeodesicLineExact; Accumulator is used by PolygonAreaT, and 1152SphericalEngine, CircularEngine, SphericalHarmonic, SphericalHarmonic1, 1153and SphericalHarmonic2 facilitate the summation of spherical harmonic 1154series which is needed by and MagneticModel and MagneticCircle. One 1155important definition is Math::real which is the type used for real 1156numbers. This allows the library to be easily switched to using floats, 1157doubles, or long doubles. However all the testing has been with real 1158set to double and the library should be installed in this way. 1159 1160GeographicLib uniformly represents all angle-like variables (latitude, 1161longitude, azimuth) in terms of degrees. To convert from degrees to 1162radians, multiple the quantity by Math::degree(). To convert from 1163radians to degrees , divide the quantity by Math::degree(). 1164 1165In general, the constructors for the classes in GeographicLib check 1166their arguments and throw GeographicErr exceptions with a 1167explanatory message if these are illegal. The member functions, e.g., 1168the projections implemented by TransverseMercator and 1169PolarStereographic, the solutions to the geodesic problem, etc., 1170typically do <i>not</i> check their arguments; the calling program 1171should ensure that the arguments are legitimate. However, the functions 1172implemented by UTMUPS, MGRS, and GeoCoords do check their arguments and 1173may throw GeographicErr exceptions. Similarly Geoid may 1174throw exceptions on file errors. If a function does throw an exception, 1175then the function arguments used for return values will not have been 1176altered. 1177 1178GeographicLib attempts to act sensibly with NaNs. NaNs in constructors 1179typically throw errors (an exception is GeodesicLine). However, calling 1180the class functions with NaNs as arguments is not an error; NaNs are 1181returned as appropriate. "INV" is treated as an invalid zone 1182designation by UTMUPS. "INVALID" is the corresponding invalid MGRS 1183string (and similarly for GARS, Geohash, and Georef strings). NaNs 1184allow the projection of polylines which are separated by NaNs; in this 1185format they can be easily plotted in MATLAB. 1186 1187A note about portability. For the most part, the code uses standard C++ 1188and should be able to be deployed on any system with a modern C++ 1189compiler. System dependencies come into 1190 - Math -- GeographicLib needs to define functions such 1191 as atanh for systems that lack them. The system dependence will 1192 disappear with the adoption of C++11 because the needed functions are 1193 part of that standard. 1194 - use of long double -- the type is used only for testing. On systems 1195 which lack this data type the cmake and autoconf configuration 1196 methods should detect its absence and omit the code that depends on 1197 it. 1198 - Geoid, GravityModel, and 1199 MagneticModel -- these class uses system-dependent 1200 default paths for looking up the respective datasets. It also relies 1201 on getenv to find the value of the environment variables. 1202 - Utility::readarray reads numerical data from binary 1203 files. This assumes that floating point numbers are in IEEE format. 1204 It attempts to handled the "endianness" of the target platform using 1205 the GEOGRAPHICLIB_WORDS_BIGENDIAN macro (which sets the compile-time 1206 constant Math::bigendian). 1207 1208An attempt is made to maintain backward compatibility with GeographicLib 1209(especially at the level of your source code). Sometimes it's necessary 1210to take actions that depend on what version of GeographicLib is being 1211used; for example, you may want to use a new feature of GeographicLib, 1212but want your code still to work with older versions. In that case, you 1213can test the values of the macros GEOGRAPHICLIB_VERSION_MAJOR, 1214GEOGRAPHICLIB_VERSION_MINOR, and GEOGRAPHICLIB_VERSION_PATCH; these 1215expand to numbers (and the last one is usually 0); these macros appeared 1216starting in version 1.31. There's also a macro 1217GEOGRAPHICLIB_VERSION_STRING which expands to, e.g., 1218"@PROJECT_VERSION@"; this macro has been defined since version 1.9. 1219Since version 1.37, there's also been a macro GEOGRAPHICLIB_VERSION 1220which encodes the version as a single number, e.g, 1003900. Do not rely 1221on this particular packing; instead use the macro 1222GEOGRAPHICLIB_VERSION_NUM(a,b,c) which allows you to compare versions 1223with, e.g., 1224\code 1225#if GEOGRAPHICLIB_VERSION >= GEOGRAPHICLIB_VERSION_NUM(1,37,0) 1226... 1227#endif \endcode 1228 1229<center> 1230Back to \ref utilities. Forward to \ref other. Up to \ref contents. 1231</center> 1232 1233**********************************************************************/ 1234/** 1235\page other Implementations in other languages 1236 1237<center> 1238Back to \ref organization. Forward to \ref geoid. Up to \ref contents. 1239</center> 1240 1241Various subsets of GeographicLib have been implemented in other 1242languages. In some cases, these are available as independent packages. 1243Here is a summary: 1244- C (geodesic routines): 1245 <a href="C/index.html"> 1246 documentation</a>, also included with recent versions of 1247 <a href="https://proj.org"> 1248 PROJ</a>; 1249- Fortran (geodesic routines): 1250 <a href="Fortran/index.html"> 1251 documentation</a>; 1252- Java (geodesic routines): 1253 <a href="https://repo1.maven.org/maven2/net/sf/geographiclib/GeographicLib-Java/"> 1254 Maven Central package</a>, 1255 <a href="java/index.html"> 1256 documentation</a>; 1257- JavaScript (geodesic routines): 1258 <a href="https://www.npmjs.com/package/geographiclib"> 1259 npm package</a>, 1260 <a href="js/index.html"> 1261 documentation</a>; 1262- Python (geodesic routines): 1263 <a href="https://pypi.python.org/pypi/geographiclib"> 1264 PyPI package</a>, 1265 <a href="python/index.html"> 1266 documentation</a>; 1267- MATLAB/Octave (geodesic and some other routines): 1268 <a href="https://www.mathworks.com/matlabcentral/fileexchange/50605"> 1269 MATLAB Central package</a>, 1270 <a href="https://viewer.mathworks.com/?viewer=plain_code&url=https%3A%2F%2Fwww.mathworks.com%2Fmatlabcentral%2Fmlc-downloads%2Fdownloads%2Fsubmissions%2F50605%2Fversions%2F15%2Fcontents%2FContents.m"> 1271 documentation</a>; 1272- C# (.NET wrapper for C++ library): 1273 <a href="NET/index.html"> 1274 documentation</a>. 1275 1276Some more details are available in the following sections 1277- \ref c-fortran 1278- \ref java. 1279- \ref javascript. 1280- \ref python. 1281- \ref matlab. 1282- \ref dotnet. 1283- \ref maxima. 1284- \ref excel. 1285 1286\section c-fortran C and Fortran implementation 1287 1288This includes the geodesic capabilities of GeographicLib. The source 1289code is in the directories <code>legacy/C</code> and 1290<code>legacy/Fortran</code>. These are intended for use in old codes 1291written in these languages and should work any reasonably modern 1292compiler. These implementations are entirely self-contained and do not 1293depend on the rest of GeographicLib. Sample main programs to solve the 1294direct and inverse geodesic problems and to compute polygonal areas are 1295provided. 1296 1297The C library is also included as part of 1298<a href="https://proj.org">PROJ</a> starting with 1299version 4.9.0, where it is used as the computational backend for 1300<a href="https://proj.org/apps/geod.html">geod(1)</a>. 1301 1302For documentation, see 1303 - <a href="C/index.html">C library for geodesics</a>, 1304 - <a href="Fortran/index.html">Fortran library for geodesics</a>. 1305 1306It is also possible to call the C++ version of GeographicLib directly 1307from C and the directory <code>wrapper/C</code> contains a small 1308example, which converts heights above the geoid to heights above the 1309ellipsoid. 1310 1311\section java Java implementation 1312 1313This includes the geodesic capabilities of GeographicLib. The source 1314code is in the directory <code>java</code>. This implementation is 1315entirely self-contained and does not depend on the rest of 1316GeographicLib. Sample main programs to solve the direct and inverse 1317geodesic problems and to compute polygonal areas are provided. 1318 1319This package is available on Maven Central; so if you're using Apache 1320Maven as your build system, you can use this package by including the 1321dependency \verbatim 1322 <dependency> 1323 <groupId>net.sf.geographiclib</groupId> 1324 <artifactId>GeographicLib-Java</artifactId> 1325 <version>@PROJECT_VERSION@</version> 1326 </dependency> 1327 \endverbatim 1328in your <code>pom.xml</code>. 1329 1330For documentation, see 1331 - <a href="java/index.html">Java library for geodesics</a>. 1332 1333\section javascript JavaScript implementation 1334 1335This includes the geodesic capabilities of GeographicLib. The source 1336code is in the directory <code>js</code>. This implementation is 1337entirely self-contained and does not depend on the rest of 1338GeographicLib. 1339 1340The library is available as an 1341<a href="https://www.npmjs.com/package/geographiclib"> 1342 npm package</a>. 1343To install this package, use \verbatim 1344 npm install geographiclib \endverbatim 1345 1346For documentation, see 1347 - <a href="js/index.html">JavaScript library for geodesics</a>. 1348 1349Examples of using this interface are 1350- a <a href="../scripts/geod-calc.html">geodesic calculator</a> showing 1351 the solution of direct and inverse geodesic problem, finding 1352 intermediate points on a geodesic line, and computing the area of a 1353 geodesic polygon; 1354- <a href="../scripts/geod-google.html">displaying geodesics in Google 1355 Maps</a> which shows the geodesic, the geodesic circle, and various 1356 geodesic envelopes. 1357 1358\section python Python implementation 1359 1360This includes the geodesic capabilities of GeographicLib. The source 1361code is in the directory <code>python</code>. This implementation is 1362entirely self-contained and does not depend on the rest of 1363GeographicLib. 1364 1365The library is available as an 1366<a href="https://pypi.python.org/pypi/geographiclib"> 1367 PyPI package</a>. 1368To install this package, use \verbatim 1369 pip install geographiclib \endverbatim 1370 1371For documentation, see 1372 - <a href="python/index.html">Python library for geodesics</a>. 1373 1374It is also possible to call the C++ version of GeographicLib directly 1375from Python and the directory <code>wrapper/python</code> contains a 1376small example, which converts heights above the geoid to heights above 1377the ellipsoid. 1378 1379\section matlab MATLAB and Octave implementations 1380 1381The includes the geodesic capabilities of GeographicLib and 1382implementations of the TransverseMercator, PolarStereographic, 1383AzimuthalEquidistant, CassiniSoldner, Gnomonic, UTMUPS, MGRS, Geocentric, 1384and LocalCartesian classes. In addition, it includes solutions of the 1385direct, inverse, and area problems for \ref greatellipse. Because these 1386functions are all vectorized, their performance is comparable to the C++ 1387routines. The minimum version numbers required are 1388 - MATLAB, version 7.9, 2009b, 1389 - Octave, version 3.4, Feb. 2011. 1390 . 1391In addition, in order to use the geoid routines, Octave needs to have 1392been built with a version of GraphicsMagick which supports 16-bit 1393images. The source code is in the directory 1394<code>matlab/geographiclib</code>. This implementation is entirely 1395self-contained and does not depend on the rest of GeographicLib. 1396 1397The library is available as an MATLAB Central package, 1398<a href="https://www.mathworks.com/matlabcentral/fileexchange/50605"> 1399 GeographicLib toolbox</a>, 1400<a href="https://viewer.mathworks.com/?viewer=plain_code&url=https%3A%2F%2Fwww.mathworks.com%2Fmatlabcentral%2Fmlc-downloads%2Fdownloads%2Fsubmissions%2F50605%2Fversions%2F15%2Fcontents%2FContents.m"> 1401 documentation</a>. 1402 1403A summary of the routines is obtained by \verbatim 1404 help geographiclib \endverbatim 1405 1406Prior to version 1.42, GeographicLib was distributed with some MATLAB 1407functionality offered via compiled interface code. This has now been 1408replaced by native MATLAB wrapper functions in 1409<code>matlab/geographiclib-legacy</code>; these depend on the 1410<a href="https://www.mathworks.com/matlabcentral/fileexchange/50605"> 1411GeographicLib toolbox</a>. 1412A summary of the routines is obtained by \verbatim 1413 help geographiclib-legacy \endverbatim 1414 1415It is also possible to call the C++ version of GeographicLib directly 1416from MATLAB or Octave and the directory <code>wrapper/matlab</code> 1417contains a small example, which solves the inverse geodesic problem for 1418ellipsoids with arbitrary flattening. (This example is taken from the 1419MATLAB interface code which was provided prior to version 1.42.) 1420 1421\section dotnet .NET wrapper 1422 1423This is a comprehensive wrapper library, written and maintained by Scott 1424Heiman, which exposes all of the functionality of GeographicLib to the 1425.NET family of languages. For documentation, see 1426 - <a href="NET/index.html">NETGeographicLib .NET wrapper library</a>. 1427 1428\section maxima Maxima routines 1429 1430Maxima is a free computer algebra system which can be downloaded from 1431http://maxima.sourceforge.net. Maxima was used to generate the series used by 1432TransverseMercator (<a href="tmseries.mac"> tmseries.mac</a>), Geodesic 1433(<a href="geod.mac"> geod.mac</a>), Rhumb (<a href="rhumbarea.mac"> 1434rhumbarea.mac</a>), \ref gearea (<a href="gearea.mac"> gearea.mac</a>), 1435the relation between \ref auxlat (<a href="auxlat.mac"> auxlat.mac</a>), 1436and to generate accurate data for testing (<a href="tm.mac"> tm.mac</a> 1437and <a href="geodesic.mac"> geodesic.mac</a>). The latter uses Maxima's 1438bigfloat arithmetic together with series extended to high order or 1439solutions in terms of elliptic integrals (<a href="ellint.mac"> 1440ellint.mac</a>). These files contain brief instructions on how to use 1441them. 1442 1443\section excel Excel wrapper 1444 1445There is no implementation of the functionality GeographicLib in Visual 1446Basic which would be callable from Excel. However, it <i>is</i> 1447possible to call the C++ library from Visual Basic. The directory 1448<code>wrapper/Excel</code> contains an illustration which allows 1449geodesics and rhumb lines to be computed in Excel. At present this 1450works only on Windows systems. 1451 1452<center> 1453Back to \ref organization. Forward to \ref geoid. Up to \ref contents. 1454</center> 1455 1456**********************************************************************/ 1457/** 1458\page geoid Geoid height 1459 1460<center> 1461Back to \ref other. Forward to \ref gravity. Up to \ref contents. 1462</center> 1463 1464The gravitational equipotential surface approximately coinciding with 1465mean sea level is called the geoid. The Geoid class and 1466the <a href="GeoidEval.1.html">GeoidEval</a> utility evaluate the height 1467of the geoid above the WGS84 ellipsoid. This can be used to convert 1468heights above mean sea level to heights above the WGS84 ellipsoid. 1469Because the normal to the ellipsoid differs from the normal to the geoid 1470(the direction of a plumb line) there is a slight ambiguity in the 1471measurement of heights; however for heights up to 10 km this ambiguity 1472is only 1 mm. 1473 1474The geoid is usually approximated by an "earth gravity model" (EGM). 1475The models published by the NGA are: 1476- <b>EGM84</b>: 1477 https://earth-info.nga.mil/index.php?dir=wgs84&action=wgs84#tab_egm84 1478- <b>EGM96</b>: 1479 https://earth-info.nga.mil/index.php?dir=wgs84&action=wgs84#tab_egm96 1480- <b>EGM2008</b>: 1481 https://earth-info.nga.mil/index.php?dir=wgs84&action=wgs84#tab_egm2008 1482. 1483Geoid offers a uniform way to handle all 3 geoids at a variety of grid 1484resolutions. (In contrast, the software tools that NGA offers are 1485different for each geoid, and the interpolation programs are different 1486for each grid resolution. In addition these tools are written in 1487Fortran with is nowadays difficult to integrate with other software.) 1488 1489The height of the geoid above the ellipsoid, \e N, is sometimes called 1490the geoid undulation. It can be used to convert a height above the 1491ellipsoid, \e h, to the corresponding height above the geoid (the 1492orthometric height, roughly the height above mean sea level), \e H, 1493using the relations 1494 1495 \e h = \e N + \e H; \e H = −\e N + \e h. 1496 1497Unlike other components of GeographicLib, there is a appreciable error 1498in the results obtained (at best, the RMS error is 1 mm). However the 1499class provides methods to report the maximum and RMS errors in the 1500results. The class also returns the gradient of the geoid. This can be 1501used to estimate the direction of a plumb line relative to the WGS84 1502ellipsoid. 1503 1504The GravityModel class calculates geoid heights using the 1505underlying gravity model. This is slower then Geoid but 1506considerably more accurate. This class also can accurately compute all 1507the components of the acceleration due to gravity (and hence the 1508direction of plumb line). 1509 1510Go to 1511 - \ref geoidinst 1512 - \ref geoidformat 1513 - \ref geoidinterp 1514 - \ref geoidcache 1515 - \ref testgeoid 1516 1517\section geoidinst Installing the geoid datasets 1518 1519The geoid heights are computed using interpolation into a rectangular 1520grid. The grids are read from data files which have been are computed 1521using the NGA synthesis programs in the case of the EGM84 and EGM96 1522models and using the NGA binary gridded data files in the case of 1523EGM2008. These data files are available for download: 1524<center> 1525<table> 1526<caption>Available geoid data files</caption> 1527<tr> 1528 <th rowspan="2">name <th rowspan="2">geoid <th rowspan="2">grid 1529 <th rowspan="2">size\n(MB) 1530 <th colspan="3"><center>Download Links (size, MB)</center></th> 1531<tr> 1532 <th>tar file</th> 1533 <th>Windows\n installer</th> 1534 <th>zip file</th> 1535<tr> 1536 <td>egm84-30 1537 <td>EGM84 1538 <td><center>30'</center> 1539 <td><center>0.6</center> 1540 <td><center> 1541 <a href="https://sourceforge.net/projects/geographiclib/files/geoids-distrib/egm84-30.tar.bz2"> 1542 link</a> (0.5)</center> 1543 <td><center> 1544 <a href="https://sourceforge.net/projects/geographiclib/files/geoids-distrib/egm84-30.exe"> 1545 link</a> (0.8)</center> 1546 <td><center> 1547 <a href="https://sourceforge.net/projects/geographiclib/files/geoids-distrib/egm84-30.zip"> 1548 link</a> (0.5)</center> 1549<tr> 1550 <td>egm84-15 1551 <td>EGM84 1552 <td><center>15'</center> 1553 <td><center>2.1</center> 1554 <td><center> 1555 <a href="https://sourceforge.net/projects/geographiclib/files/geoids-distrib/egm84-15.tar.bz2"> 1556 link</a> (1.5)</center> 1557 <td><center> 1558 <a href="https://sourceforge.net/projects/geographiclib/files/geoids-distrib/egm84-15.exe"> 1559 link</a> (1.9)</center> 1560 <td><center> 1561 <a href="https://sourceforge.net/projects/geographiclib/files/geoids-distrib/egm84-15.zip"> 1562 link</a> (2.0)</center> 1563<tr> 1564 <td>egm96-15 1565 <td>EGM96 1566 <td><center>15'</center> 1567 <td><center>2.1</center> 1568 <td><center> 1569 <a href="https://sourceforge.net/projects/geographiclib/files/geoids-distrib/egm96-15.tar.bz2"> 1570 link</a> (1.5)</center> 1571 <td><center> 1572 <a href="https://sourceforge.net/projects/geographiclib/files/geoids-distrib/egm96-15.exe"> 1573 link</a> (1.9)</center> 1574 <td><center> 1575 <a href="https://sourceforge.net/projects/geographiclib/files/geoids-distrib/egm96-15.zip"> 1576 link</a> (2.0)</center> 1577<tr> 1578 <td>egm96-5 1579 <td>EGM96 1580 <td><center>5'</center> 1581 <td><center> 19</center> 1582 <td><center> 1583 <a href="https://sourceforge.net/projects/geographiclib/files/geoids-distrib/egm96-5.tar.bz2"> 1584 link</a> (11)</center> 1585 <td><center> 1586 <a href="https://sourceforge.net/projects/geographiclib/files/geoids-distrib/egm96-5.exe"> 1587 link</a> (11)</center> 1588 <td><center> 1589 <a href="https://sourceforge.net/projects/geographiclib/files/geoids-distrib/egm96-5.zip"> 1590 link</a> (17)</center> 1591<tr> 1592 <td>egm2008-5 1593 <td>EGM2008 1594 <td><center>5'</center> 1595 <td><center> 19</center> 1596 <td><center> 1597 <a href="https://sourceforge.net/projects/geographiclib/files/geoids-distrib/egm2008-5.tar.bz2"> 1598 link</a> (11)</center> 1599 <td><center> 1600 <a href="https://sourceforge.net/projects/geographiclib/files/geoids-distrib/egm2008-5.exe"> 1601 link</a> (11)</center> 1602 <td><center> 1603 <a href="https://sourceforge.net/projects/geographiclib/files/geoids-distrib/egm2008-5.zip"> 1604 link</a> (17)</center> 1605<tr> 1606 <td>egm2008-2_5 1607 <td>EGM2008 1608 <td><center>2.5'</center> 1609 <td><center> 75</center> 1610 <td><center> 1611 <a href="https://sourceforge.net/projects/geographiclib/files/geoids-distrib/egm2008-2_5.tar.bz2"> 1612 link</a> (35)</center> 1613 <td><center> 1614 <a href="https://sourceforge.net/projects/geographiclib/files/geoids-distrib/egm2008-2_5.exe"> 1615 link</a> (33)</center> 1616 <td><center> 1617 <a href="https://sourceforge.net/projects/geographiclib/files/geoids-distrib/egm2008-2_5.zip"> 1618 link</a> (65)</center> 1619<tr> 1620 <td>egm2008-1 1621 <td>EGM2008 1622 <td><center>1'</center> 1623 <td><center>470</center> 1624 <td><center> 1625 <a href="https://sourceforge.net/projects/geographiclib/files/geoids-distrib/egm2008-1.tar.bz2"> 1626 link</a> (170)</center> 1627 <td><center> 1628 <a href="https://sourceforge.net/projects/geographiclib/files/geoids-distrib/egm2008-1.exe"> 1629 link</a> (130)</center> 1630 <td><center> 1631 <a href="https://sourceforge.net/projects/geographiclib/files/geoids-distrib/egm2008-1.zip"> 1632 link</a> (390)</center> 1633</table> 1634</center> 1635The "size" column is the size of the uncompressed data and it also 1636gives the memory requirements for caching the entire dataset using the 1637Geoid::CacheAll method. 1638At a minimum you should install egm96-5 and either egm2008-1 or 1639egm2008-2_5. Many applications use the EGM96 geoid, however the use of 1640EGM2008 is growing. (EGM84 is rarely used now.) 1641 1642For Linux and Unix systems, GeographicLib provides a shell script 1643geographiclib-get-geoids (typically installed in /usr/local/sbin) which 1644automates the process of downloading and installing the geoid data. For 1645example 1646\verbatim 1647 geographiclib-get-geoids best # to install egm84-15, egm96-5, egm2008-1 1648 geographiclib-get-geoids -h # for help 1649\endverbatim 1650This script should be run as a user with write access to the 1651installation directory, which is typically 1652/usr/local/share/GeographicLib (this can be overridden with the -p 1653flag), and the data will then be placed in the "geoids" subdirectory. 1654 1655Windows users should download and run the Windows installers. These 1656will prompt for an installation directory with the default being 1657\verbatim 1658 C:/ProgramData/GeographicLib 1659\endverbatim 1660(which you probably should not change) and the data is installed in the 1661"geoids" sub-directory. (The second directory name is an alternate name 1662that Windows 7 uses for the "Application Data" directory.) 1663 1664Otherwise download \e either the tar.bz2 file \e or the zip file (they 1665have the same contents). If possible use the tar.bz2 files, since these 1666are compressed about 2 times better than the zip file. To unpack these, 1667run, for example 1668\verbatim 1669 mkdir -p /usr/local/share/GeographicLib 1670 tar xofjC egm96-5.tar.bz2 /usr/local/share/GeographicLib 1671 tar xofjC egm2008-2_5.tar.bz2 /usr/local/share/GeographicLib 1672 etc. 1673\endverbatim 1674and, again, the data will be placed in the "geoids" subdirectory. 1675 1676However you install the geoid data, all the datasets should 1677be installed in the same directory. Geoid and 1678<a href="GeoidEval.1.html">GeoidEval</a> uses a compile time default to 1679locate the datasets. This is 1680- /usr/local/share/GeographicLib/geoids, for non-Windows systems 1681- C:/ProgramData/GeographicLib/geoids, for Windows systems 1682. 1683consistent with the examples above. This may be overridden at run-time 1684by defining the GEOGRAPHICLIB_GEOID_PATH or the GEOGRAPHICLIB_DATA 1685environment variables; see Geoid::DefaultGeoidPath() for 1686details. Finally, the path may be set using the optional second 1687argument to the Geoid constructor or with the "-d" flag 1688to <a href="GeoidEval.1.html">GeoidEval</a>. Supplying the "-h" flag to 1689<a href="GeoidEval.1.html">GeoidEval</a> reports the default geoid path 1690for that utility. The "-v" flag causes GeoidEval to report the full 1691path name of the data file it uses. 1692 1693\section geoidformat The format of the geoid data files 1694 1695The gridded data used by the Geoid class is stored in 169616-bit PGM files. Thus the data for egm96-5 might be stored in the file 1697- /usr/local/share/GeographicLib/geoids/egm96-5.pgm 1698. 1699PGM simple graphic format with the following properties 1700- it is well documented 1701 <a href="http://netpbm.sourceforge.net/doc/pgm.html">here</a>; 1702- there are no separate "little-endian" and "big-endian" versions; 1703- it uses 1 or 2 bytes per pixel; 1704- pixels can be randomly accessed; 1705- comments can be added to the file header; 1706- it is sufficiently simple that it can be easily read without using the 1707 <a href="http://netpbm.sourceforge.net/doc/libnetpbm.html">libnetpbm</a> 1708 library (and thus we avoid adding a software dependency to 1709 GeographicLib). 1710. 1711The major drawback of this format is that since there are only 65535 1712possible pixel values, the height must be quantized to 3 mm. However, 1713the resulting quantization error (up to 1.5 mm) is typically smaller 1714than the linear interpolation errors. The comments in the header for 1715egm96-5 are 1716\verbatim 1717 # Geoid file in PGM format for the GeographicLib::Geoid class 1718 # Description WGS84 EGM96, 5-minute grid 1719 # URL https://earth-info.nga.mil/index.php?dir=wgs84&action=wgs84#tab_egm96 1720 # DateTime 2009-08-29 18:45:03 1721 # MaxBilinearError 0.140 1722 # RMSBilinearError 0.005 1723 # MaxCubicError 0.003 1724 # RMSCubicError 0.001 1725 # Offset -108 1726 # Scale 0.003 1727 # Origin 90N 0E 1728 # AREA_OR_POINT Point 1729 # Vertical_Datum WGS84 1730\endverbatim 1731Of these lines, the Scale and Offset lines are required and define the 1732conversion from pixel value to height (in meters) using \e height = 1733\e offset + \e scale \e pixel. The Geoid constructor also reads the 1734Description, DateTime, and error lines (if present) and stores the 1735resulting data so that it can be returned by 1736Geoid::Description, Geoid::DateTime, 1737Geoid::MaxError, and Geoid::RMSError 1738methods. The other lines serve as additional documentation but are not 1739used by this class. Accompanying egm96-5.pgm (and similarly with the 1740other geoid data files) are two files egm96-5.wld and 1741egm96-5.pgm.aux.xml. The first is an ESRI "world" file and the second 1742supplies complete projection metadata for use by 1743<a href="http://www.gdal.org">GDAL</a>. Neither of these files is read 1744by Geoid. 1745 1746You can use gdal_translate to convert the data files to a standard 1747GeoTiff, e.g., with 1748\verbatim 1749 gdal_translate -ot Float32 -scale 0 65000 -108 87 egm96-5.pgm egm96-5.tif 1750\endverbatim 1751The arguments to -scale here are specific to the Offset and Scale 1752parameters used in the pgm file (note 65000 * 0.003 − 108 = 87). 1753You can check these by running <a href="GeoidEval.1.html">GeoidEval</a> 1754with the "-v" option. 1755 1756Here is a sample script which uses GDAL to create a 1-degree 1757squared grid of geoid heights at 3" resolution (matching DTED1) by 1758bilinear interpolation. 1759\verbatim 1760 #! /bin/sh 1761 lat=37 1762 lon=067 1763 res=3 # resolution in seconds 1764 TEMP=`mktemp junkXXXXXXXXXX` # temporary file for GDAL 1765 gdalwarp -q -te `echo $lon $lat $res | awk '{ 1766 lon = $1; lat = $2; res = $3; 1767 printf "%.14f %.14f %.14f %.14f", 1768 lon -0.5*res/3600, lat -0.5*res/3600, 1769 lon+1+0.5*res/3600, lat+1+0.5*res/3600; 1770 }'` -ts $((3600/res+1)) $((3600/res+1)) -r bilinear egm96-5.tif $TEMP 1771 gdal_translate -quiet \ 1772 -mo AREA_OR_POINT=Point \ 1773 -mo Description="WGS84 EGM96, $res-second grid" \ 1774 -mo Vertical_Datum=WGS84 \ 1775 -mo Tie_Point_Location=pixel_corner \ 1776 $TEMP e$lon-n$lat.tif 1777 rm -f $TEMP 1778\endverbatim 1779 1780Because the pgm files are uncompressed, they can take up a lot of disk 1781space. Some compressed formats compress in tiles and so might be 1782compatible with the requirement that the data can be randomly accessed. 1783In particular gdal_translate can be used to convert the pgm files to 1784compressed tiff files with 1785\verbatim 1786gdal_translate -co COMPRESS=LZW -co PREDICTOR=2 -co TILED=YES \ 1787 –a_offset -108 -a_scale 0.003 \ 1788 egmyy-g.pgm egmyy-g.tif 1789\endverbatim 1790(The <code>-a_offset</code> and <code>-a_scale</code> options were 1791introduced in gdal_translate version 2.3.) The resulting files sizes 1792are 1793\verbatim 1794 pgm tif 1795 egm84-30 0.6 MB 0.5 MB 1796 egm84-15 2.1 MB 1.4 MB 1797 egm96-15 2.1 MB 1.5 MB 1798 egm96-5 19 MB 8.5 MB 1799 egm2008-5 19 MB 9.8 MB 1800 egm2008-2_5 75 MB 28 MB 1801 egm2008-1 470 MB 97 MB 1802\endverbatim 1803Currently, there are no plans for GeographicLib to support this 1804compressed format. 1805 1806The Geoid class only handles world-wide geoid models. The pgm provides 1807geoid height postings on grid of points with uniform spacing in latitude 1808(row) and longitude (column). If the dimensions of the pgm file are 1809\e h × \e w, then latitude (resp. longitude) spacing is 1810−180°/(\e h − 1) (resp. 360°/\e w), with the (0,0) 1811pixel given the value at φ = 90°, λ = 0°. Models 1812covering a limited area will need to be "inserted" into a world-wide 1813grid before being accessible to the Geoid class. 1814 1815\section geoidinterp Interpolating the geoid data 1816 1817Geoid evaluates the geoid height using bilinear or cubic 1818interpolation. 1819 1820The bilinear interpolation is based on the values at the 4 corners of 1821the enclosing cell. The interpolated height is a continuous function of 1822position; however the gradient has discontinuities are cell boundaries. 1823The quantization of the data files exacerbates the errors in the 1824gradients. 1825 1826The cubic interpolation is a least-squares fit to the values on a 182712-point stencil with weights as follows: 1828\verbatim 1829 . 1 1 . 1830 1 2 2 1 1831 1 2 2 1 1832 . 1 1 . 1833\endverbatim 1834The cubic is constrained to be independent of longitude when evaluating 1835the height at one of the poles. Cubic interpolation is considerably 1836more accurate than bilinear interpolation; however, in this 1837implementation there are small discontinuities in the heights are cell 1838boundaries. The over-constrained cubic fit slightly reduces the 1839quantization errors on average. 1840 1841The algorithm for the least squares fit is taken from, F. H. Lesh, 1842<a href="https://doi.org/10.1145/368424.368443">Multi-dimensional 1843least-squares polynomial curve fitting</a>, CACM 2, 29--30 (1959). 1844This algorithm is not part of Geoid; instead it is implemented as 1845<a href="https://en.wikipedia.org/wiki/Maxima_(software)">Maxima</a> 1846code which is used to precompute the matrices to convert the function 1847values on the stencil into the coefficients from the cubic polynomial. 1848This code is included as a comment in Geoid.cpp. 1849 1850The interpolation methods are quick and give good accuracy. Here is a 1851summary of the combined quantization and interpolation errors for the 1852heights. 1853<center><table> 1854<caption>Interpolation and quantization errors for geoid heights</caption> 1855<tr> 1856 <th rowspan="2">name 1857 <th rowspan="2">geoid 1858 <th rowspan="2">grid 1859 <th colspan="2"><center>bilinear error</center></th> 1860 <th colspan="2"><center>cubic error</center></th> 1861<tr> 1862 <th><center>max</center><th><center>rms</center> 1863 <th><center>max</center><th><center>rms</center> 1864<tr> 1865 <td>egm84-30 <td>EGM84 <td><center>30' </center> 1866 <td><center>1.546 m</center><td><center>70 mm</center> 1867 <td><center>0.274 m</center><td><center>14 mm</center> 1868<tr> 1869 <td>egm84-15 <td>EGM84 <td><center>15' </center> 1870 <td><center>0.413 m</center><td><center>18 mm</center> 1871 <td><center>0.021 m</center><td><center>1.2 mm</center> 1872<tr> 1873 <td>egm96-15 <td>EGM96 <td><center>15' </center> 1874 <td><center>1.152 m</center><td><center>40 mm</center> 1875 <td><center>0.169 m</center><td><center>7.0 mm</center> 1876<tr> 1877 <td>egm96-5 <td>EGM96 <td><center> 5' </center> 1878 <td><center>0.140 m</center><td><center>4.6 mm</center> 1879 <td><center>0.0032 m</center><td><center>0.7 mm</center> 1880<tr> 1881 <td>egm2008-5 <td>EGM2008<td><center> 5' </center> 1882 <td><center>0.478 m</center><td><center>12 mm</center> 1883 <td><center>0.294 m</center><td><center>4.5 mm</center> 1884<tr> 1885 <td>egm2008-2_5<td>EGM2008<td><center> 2.5'</center> 1886 <td><center>0.135 m</center><td><center>3.2 mm</center> 1887 <td><center>0.031 m</center><td><center>0.8 mm</center> 1888<tr> 1889 <td>egm2008-1 <td>EGM2008<td><center> 1' </center> 1890 <td><center>0.025 m</center><td><center>0.8 mm</center> 1891 <td><center>0.0022 m</center><td><center>0.7 mm</center> 1892</table></center> 1893The errors are with respect to the specific NGA earth gravity model 1894(not to any "real" geoid). The RMS values are obtained using 5 million 1895uniformly distributed random points. The maximum values are obtained by 1896evaluating the errors using a different grid with points at the 1897centers of the original grid. (The RMS difference between EGM96 and 1898EGM2008 is about 0.5 m. The RMS difference between EGM84 and EGM96 is 1899about 1.5 m.) 1900 1901The errors in the table above include the quantization errors that arise 1902because the height data that Geoid uses are quantized to 19033 mm. If, instead, Geoid were to use data files without 1904such quantization artifacts, the overall error would be reduced <i>but 1905only modestly</i> as shown in the following table, where only the 1906changed rows are included and where the changed entries are given in 1907bold: 1908<center><table> 1909<caption>Interpolation (only!) errors for geoid heights</caption> 1910<tr> 1911 <th rowspan="2">name 1912 <th rowspan="2">geoid 1913 <th rowspan="2">grid 1914 <th colspan="2"><center>bilinear error</center></th> 1915 <th colspan="2"><center>cubic error</center></th> 1916<tr> 1917 <th><center>max</center><th><center>rms</center> 1918 <th><center>max</center><th><center>rms</center> 1919<tr> 1920 <td>egm96-5 <td>EGM96 <td><center> 5' </center> 1921 <td><center>0.140 m</center><td><center>4.6 mm</center> 1922 <td><center><b>0.0026 m</b></center><td><center><b>0.1 mm</b></center> 1923<tr> 1924 <td>egm2008-2_5<td>EGM2008<td><center> 2.5'</center> 1925 <td><center>0.135 m</center><td><center>3.2 mm</center> 1926 <td><center>0.031 m</center><td><center><b>0.4 mm</b></center> 1927<tr> 1928 <td>egm2008-1 <td>EGM2008<td><center> 1' </center> 1929 <td><center>0.025 m</center><td><center><b>0.6 mm</b></center> 1930 <td><center><b>0.0010 m</b></center><td><center><b>0.011 mm</b></center> 1931</table></center> 1932 1933\section geoidcache Caching the geoid data 1934 1935A simple way of calling Geoid is as follows 1936\code 1937 #include <GeographicLib/Geoid.hpp> 1938 #include <iostream> 1939 ... 1940 GeographicLib::Geoid g("egm96-5"); 1941 double lat, lon; 1942 while (std::cin >> lat >> lon) 1943 std::cout << g(lat, lon) << "\n"; 1944 ... 1945\endcode 1946 1947The first call to g(lat, lon) causes the data for the stencil points (4 1948points for bilinear interpolation and 12 for cubic interpolation) to be 1949read and the interpolated value returned. A simple 0th-order caching 1950scheme is provided by default, so that, if the second and subsequent 1951points falls within the same grid cell, the data values are not reread 1952from the file. This is adequate for most interactive use and also 1953minimizes disk accesses for the case when a continuous track is being 1954followed. 1955 1956If a large quantity of geoid calculations are needed, the calculation 1957can be sped up by preloading the data for a rectangular block with 1958Geoid::CacheArea or the entire dataset with 1959Geoid::CacheAll. If the requested points lie within the 1960cached area, the cached data values are used; otherwise the data is read 1961from disk as before. Caching all the data is a reasonable choice for 1962the 5' grids and coarser. Caching all the data for the 1' grid will 1963require 0.5 GB of RAM and should only be used on systems with sufficient 1964memory. 1965 1966The use of caching does not affect the values returned. Because of the 1967caching and the random file access, this class is \e not normally thread 1968safe; i.e., a single instantiation cannot be safely used by multiple 1969threads. If multiple threads need to calculate geoid heights, there are 1970two alternatives: 1971 - they should all construct thread-local instantiations. 1972 - Geoid should be constructed with \e threadsafe = true. 1973 This causes all the data to be read at the time of construction (and 1974 if this fails, an exception is thrown), the data file to be closed 1975 and the single-cell caching to be turned off. The resulting object 1976 may then be shared safely between threads. 1977 1978\section testgeoid Test data for geoids 1979 1980A test set for the geoid models is available at 1981 - <a href="https://sourceforge.net/projects/geographiclib/files/testdata/GeoidHeights.dat.gz"> 1982 GeoidHeights.dat.gz</a> 1983 . 1984This is about 11 MB (compressed). This test set consists of a set of 1985500000 geographic coordinates together with the corresponding geoid 1986heights according to various earth gravity models. 1987 1988Each line of the test set gives 6 space delimited numbers 1989 - latitude (degrees, exact) 1990 - longitude (degrees, exact) 1991 - EGM84 height (meters, accurate to 1 μm) 1992 - EGM96 height (meters, accurate to 1 μm) 1993 - EGM2008 height (meters, accurate to 1 μm) 1994 . 1995The latitude and longitude are all multiples of 10<sup>−6</sup> 1996deg and should be regarded as exact. The geoid heights are computed 1997using the harmonic NGA synthesis programs, where the programs were 1998compiled (with gfortran) and run under Linux. In the case of the 1999EGM2008 program, a <code>SAVE</code> statement needed to be added to 2000subroutine <code>latf</code>, in order for the program to compile 2001correctly with a stack-based compiler. Similarly the EGM96 code 2002requires a <code>SAVE</code> statement in subroutine 2003<code>legfdn</code>. 2004 2005<center> 2006Back to \ref other. Forward to \ref gravity. Up to \ref contents. 2007</center> 2008 2009**********************************************************************/ 2010/** 2011\page gravity Gravity models 2012 2013<center> 2014Back to \ref geoid. Forward to \ref normalgravity. Up to \ref contents. 2015</center> 2016 2017GeographicLib can compute the earth's gravitational field with an earth 2018gravity model using the GravityModel and GravityCircle classes and with 2019the <a href="Gravity.1.html">Gravity</a> utility. These models expand 2020the gravitational potential of the earth as sum of spherical harmonics. 2021The models also specify a reference ellipsoid, relative to which geoid 2022heights and gravity disturbances are measured. Underlying all these 2023models is <i>normal gravity</i> which is the exact solution for an 2024idealized rotating ellipsoidal body. This is implemented with the 2025NormalGravity class and some notes on are provided in section \ref 2026normalgravity 2027 2028Go to 2029 - \ref gravityinst 2030 - \ref gravityformat 2031 - \ref gravitynga 2032 - \ref gravitygeoid 2033 - \ref gravityatmos 2034 - \ref gravityparallel 2035 - \ref normalgravity (now on its own page) 2036 2037The supported models are 2038 - <b>egm84</b>, the 2039 <a href="https://earth-info.nga.mil/index.php?dir=wgs84&action=wgs84#tab_egm84"> 2040 Earth Gravity Model 1984</a>, which includes terms up to degree 180. 2041 - <b>egm96</b>, the 2042 <a href="https://earth-info.nga.mil/index.php?dir=wgs84&action=wgs84#tab_egm96"> 2043 Earth Gravity Model 1996</a>, which includes terms up to degree 360. 2044 - <b>egm2008</b>, the 2045 <a href="https://earth-info.nga.mil/index.php?dir=wgs84&action=wgs84#tab_egm2008"> 2046 Earth Gravity Model 2008</a>, which includes terms up to degree 2190. 2047 See also <a href="https://doi.org/10.1029/2011JB008916"> Pavlis et 2048 al. (2012)</a> 2049 - <b>wgs84</b>, the 2050 <a href="https://web.archive.org/web/20161214054445/http://earth-info.nga.mil/GandG/publications/tr8350.2/tr8350_2.html"> 2051 WGS84 Reference Ellipsoid</a>. This is just reproduces the normal 2052 gravitational field for the reference ellipsoid. This includes the 2053 zonal coefficients up to order 20. Usually NormalGravity::WGS84() 2054 should be used instead. 2055 - <b>grs80</b>, the 2056 GRS80 Reference Ellipsoid. This is just reproduces the normal 2057 gravitational field for the GRS80 ellipsoid. This includes the 2058 zonal coefficients up to order 20. Usually NormalGravity::GRS80() 2059 should be used instead. 2060 2061See 2062 - W. A. Heiskanen and H. Moritz, Physical Geodesy (Freeman, San 2063 Francisco, 1967). 2064 . 2065for more information. 2066 2067<b>Acknowledgment:</b> I would like to thank Mathieu Peyréga for 2068sharing EGM_Geoid_CalculatorClass from his Geo library with me. His 2069implementation was the first I could easily understand and he and I 2070together worked through some of the issues with overflow and underflow 2071the occur while performing high-degree spherical harmonic sums. 2072 2073\section gravityinst Installing the gravity models 2074 2075These gravity models are available for download: 2076<center> 2077<table> 2078<caption>Available gravity models</caption> 2079<tr> 2080 <th rowspan="2">name <th rowspan="2">max\n degree 2081 <th rowspan="2">size\n(kB) 2082 <th colspan="3"><center>Download Links (size, kB)</center></th> 2083<tr> 2084 <th>tar file</th> 2085 <th>Windows\n installer</th> 2086 <th>zip file</th> 2087<tr> 2088 <td>egm84 2089 <td><center>180</center> 2090 <td><center>27</center> 2091 <td><center> 2092 <a href="https://sourceforge.net/projects/geographiclib/files/gravity-distrib/egm84.tar.bz2"> 2093 link</a> (26)</center> 2094 <td><center> 2095 <a href="https://sourceforge.net/projects/geographiclib/files/gravity-distrib/egm84.exe"> 2096 link</a> (55)</center> 2097 <td><center> 2098 <a href="https://sourceforge.net/projects/geographiclib/files/gravity-distrib/egm84.zip"> 2099 link</a> (26)</center> 2100<tr> 2101 <td>egm96 2102 <td><center>360</center> 2103 <td><center>2100</center> 2104 <td><center> 2105 <a href="https://sourceforge.net/projects/geographiclib/files/gravity-distrib/egm96.tar.bz2"> 2106 link</a> (2100)</center> 2107 <td><center> 2108 <a href="https://sourceforge.net/projects/geographiclib/files/gravity-distrib/egm96.exe"> 2109 link</a> (2300)</center> 2110 <td><center> 2111 <a href="https://sourceforge.net/projects/geographiclib/files/gravity-distrib/egm96.zip"> 2112 link</a> (2100)</center> 2113<tr> 2114 <td>egm2008 2115 <td><center>2190</center> 2116 <td><center>76000</center> 2117 <td><center> 2118 <a href="https://sourceforge.net/projects/geographiclib/files/gravity-distrib/egm2008.tar.bz2"> 2119 link</a> (75000)</center> 2120 <td><center> 2121 <a href="https://sourceforge.net/projects/geographiclib/files/gravity-distrib/egm2008.exe"> 2122 link</a> (72000)</center> 2123 <td><center> 2124 <a href="https://sourceforge.net/projects/geographiclib/files/gravity-distrib/egm2008.zip"> 2125 link</a> (73000)</center> 2126<tr> 2127 <td>wgs84 2128 <td><center>20</center> 2129 <td><center>1</center> 2130 <td><center> 2131 <a href="https://sourceforge.net/projects/geographiclib/files/gravity-distrib/wgs84.tar.bz2"> 2132 link</a> (1)</center> 2133 <td><center> 2134 <a href="https://sourceforge.net/projects/geographiclib/files/gravity-distrib/wgs84.exe"> 2135 link</a> (30)</center> 2136 <td><center> 2137 <a href="https://sourceforge.net/projects/geographiclib/files/gravity-distrib/wgs84.zip"> 2138 link</a> (1)</center> 2139</table> 2140</center> 2141The "size" column is the size of the uncompressed data. 2142 2143For Linux and Unix systems, GeographicLib provides a shell script 2144geographiclib-get-gravity (typically installed in /usr/local/sbin) 2145which automates the process of downloading and installing the gravity 2146models. For example 2147\verbatim 2148 geographiclib-get-gravity all # to install egm84, egm96, egm2008, wgs84 2149 geographiclib-get-gravity -h # for help 2150\endverbatim 2151This script should be run as a user with write access to the 2152installation directory, which is typically 2153/usr/local/share/GeographicLib (this can be overridden with the -p 2154flag), and the data will then be placed in the "gravity" subdirectory. 2155 2156Windows users should download and run the Windows installers. These 2157will prompt for an installation directory with the default being 2158\verbatim 2159 C:/ProgramData/GeographicLib 2160\endverbatim 2161(which you probably should not change) and the data is installed in the 2162"gravity" sub-directory. (The second directory name is an alternate name 2163that Windows 7 uses for the "Application Data" directory.) 2164 2165Otherwise download \e either the tar.bz2 file \e or the zip file (they 2166have the same contents). To unpack these, run, for example 2167\verbatim 2168 mkdir -p /usr/local/share/GeographicLib 2169 tar xofjC egm96.tar.bz2 /usr/local/share/GeographicLib 2170 tar xofjC egm2008.tar.bz2 /usr/local/share/GeographicLib 2171 etc. 2172\endverbatim 2173and, again, the data will be placed in the "gravity" subdirectory. 2174 2175However you install the gravity models, all the datasets should be 2176installed in the same directory. GravityModel and 2177<a href="Gravity.1.html">Gravity</a> uses a compile time default to 2178locate the datasets. This is 2179- /usr/local/share/GeographicLib/gravity, for non-Windows systems 2180- C:/ProgramData/GeographicLib/gravity, for Windows systems 2181. 2182consistent with the examples above. This may be overridden at run-time 2183by defining the GEOGRAPHICLIB_GRAVITY_PATH or the GEOGRAPHICLIB_DATA 2184environment variables; see 2185GravityModel::DefaultGravityPath() for details. Finally, 2186the path may be set using the optional second argument to the 2187GravityModel constructor or with the "-d" flag to 2188<a href="Gravity.1.html">Gravity</a>. Supplying the "-h" flag to 2189<a href="Gravity.1.html">Gravity</a> reports the default path for 2190gravity models for that utility. The "-v" flag causes Gravity to report 2191the full path name of the data file it uses. 2192 2193\section gravityformat The format of the gravity model files 2194 2195The constructor for GravityModel reads a file called 2196NAME.egm which specifies various properties for the gravity model. It 2197then opens a binary file NAME.egm.cof to obtain the coefficients of the 2198spherical harmonic sum. 2199 2200The first line of the .egm file must consist of "EGMF-v" where EGMF 2201stands for "Earth Gravity Model Format" and v is the version number of 2202the format (currently "1"). 2203 2204The rest of the File is read a line at a time. A # character and 2205everything after it are discarded. If the result is just white space it 2206is discarded. The remaining lines are of the form "KEY WHITESPACE 2207VALUE". In general, the KEY and the VALUE are case-sensitive. 2208 2209GravityModel only pays attention to the following 2210keywords 2211 - keywords that affect the field calculation, namely: 2212 - <b>ModelRadius</b> (required), the normalizing radius for the model 2213 in meters. 2214 - <b>ReferenceRadius</b> (required), the equatorial radius \e a for 2215 the reference ellipsoid meters. 2216 - <b>ModelMass</b> (required), the mass constant \e GM for the model 2217 in meters<sup>3</sup>/seconds<sup>2</sup>. 2218 - <b>ReferenceMass</b> (required), the mass constant \e GM for the 2219 reference ellipsoid in meters<sup>3</sup>/seconds<sup>2</sup>. 2220 - <b>AngularVelocity</b> (required), the angular velocity ω for 2221 the model \e and the reference ellipsoid in rad 2222 seconds<sup>−1</sup>. 2223 - <b>Flattening</b>, the flattening of the reference ellipsoid; this 2224 can be given a fraction, e.g., 1/298.257223563. One of 2225 <b>Flattening</b> and <b>DynamicalFormFactor</b> is required. 2226 - <b>DynamicalFormFactor</b>, the dynamical form factor 2227 <i>J</i><sub>2</sub> for the reference ellipsoid. One of 2228 <b>Flattening</b> and <b>DynamicalFormFactor</b> is required. 2229 - <b>HeightOffset</b> (default 0), the constant height offset 2230 (meters) added to obtain the geoid height. 2231 - <b>CorrectionMultiplier</b> (default 1), the multiplier for the 2232 "zeta-to-N" correction terms for the geoid height to convert them 2233 to meters. 2234 - <b>Normalization</b> (default full), the normalization used for the 2235 associated Legendre functions (full or schmidt). 2236 - <b>ID</b> (required), 8 printable characters which serve as a 2237 signature for the .egm.cof file (they must appear as the first 8 2238 bytes of this file). 2239 . 2240 The parameters <b>ModelRadius</b>, <b>ModelMass</b>, and 2241 <b>AngularVelocity</b> apply to the gravity model, while 2242 <b>ReferenceRadius</b>, <b>ReferenceMass</b>, <b>AngularVelocity</b>, 2243 and either <b>Flattening</b> or <b>DynamicalFormFactor</b> 2244 characterize the reference ellipsoid. <b>AngularVelocity</b> 2245 (because it can be measured precisely) is the same for the gravity 2246 model and the reference ellipsoid. <b>ModelRadius</b> is merely a 2247 scaling parameter for the gravity model and there's no requirement 2248 that it be close to the equatorial radius of the earth (although 2249 that's typically how it is chosen). <b>ModelMass</b> and 2250 <b>ReferenceMass</b> need not be the same and, indeed, they are 2251 slightly difference for egm2008. As a result the disturbing 2252 potential \e T has a 1/\e r dependence at large distances. 2253 - keywords that store data that the user can query: 2254 - <b>Name</b>, the name of the model. 2255 - <b>Description</b>, a more descriptive name of the model. 2256 - <b>ReleaseDate</b>, when the model was created. 2257 - keywords that are examined to verify that their values are valid: 2258 - <b>ByteOrder</b> (default little), the order of bytes in the 2259 .egm.cof file. Only little endian is supported at present. 2260 . 2261Other keywords are ignored. 2262 2263The coefficient file NAME.egm.cof is a binary file in little endian 2264order. The first 8 bytes of this file must match the ID given in 2265NAME.egm. This is followed by 2 sets of spherical harmonic 2266coefficients. The first of these gives the gravity potential and the 2267second gives the zeta-to-N corrections to the geoid height. The format 2268for each set of coefficients is: 2269 - \e N, the maximum degree of the sum stored as a 4-byte signed integer. 2270 This must satisfy \e N ≥ −1. 2271 - \e M, the maximum order of the sum stored as a 4-byte signed integer. 2272 This must satisfy \e N ≥ \e M ≥ −1. 2273 - <i>C</i><sub><i>nm</i></sub>, the coefficients of the cosine 2274 coefficients of the sum in column (i.e., \e m) major order. There 2275 are (\e M + 1) (2\e N - \e M + 2) / 2 elements which are stored as 2276 IEEE doubles (8 bytes). For example for \e N = \e M = 3, there are 2277 10 coefficients arranged as 2278 <i>C</i><sub>00</sub>, 2279 <i>C</i><sub>10</sub>, 2280 <i>C</i><sub>20</sub>, 2281 <i>C</i><sub>30</sub>, 2282 <i>C</i><sub>11</sub>, 2283 <i>C</i><sub>21</sub>, 2284 <i>C</i><sub>31</sub>, 2285 <i>C</i><sub>22</sub>, 2286 <i>C</i><sub>32</sub>, 2287 <i>C</i><sub>33</sub>. 2288 - <i>S</i><sub><i>nm</i></sub>, the coefficients of the sine 2289 coefficients of the sum in column (i.e., \e m) major order starting 2290 at \e m = 1. There are \e M (2\e N - \e M + 1) / 2 elements which 2291 are stored as IEEE doubles (8 bytes). For example for \e N = \e M = 2292 3, there are 6 coefficients arranged as 2293 <i>S</i><sub>11</sub>, 2294 <i>S</i><sub>21</sub>, 2295 <i>S</i><sub>31</sub>, 2296 <i>S</i><sub>22</sub>, 2297 <i>S</i><sub>32</sub>, 2298 <i>S</i><sub>33</sub>. 2299 . 2300Although the coefficient file is in little endian order, GeographicLib 2301can read it on big endian machines. It can only be read on machines 2302which store doubles in IEEE format. 2303 2304As an illustration, here is egm2008.egm: 2305\verbatim 2306EGMF-1 2307# An Earth Gravity Model (Format 1) file. For documentation on the 2308# format of this file see 2309# https://geographiclib.sourceforge.io/html/gravity.html#gravityformat 2310Name egm2008 2311Publisher National Geospatial Intelligence Agency 2312Description Earth Gravity Model 2008 2313URL https://earth-info.nga.mil/index.php?dir=wgs84&action=wgs84#tab_egm2008 2314ReleaseDate 2008-06-01 2315ConversionDate 2011-11-19 2316DataVersion 1 2317ModelRadius 6378136.3 2318ModelMass 3986004.415e8 2319AngularVelocity 7292115e-11 2320ReferenceRadius 6378137 2321ReferenceMass 3986004.418e8 2322Flattening 1/298.257223563 2323HeightOffset -0.41 2324 2325# Gravitational and correction coefficients taken from 2326# EGM2008_to2190_TideFree and Zeta-to-N_to2160_egm2008 from 2327# the egm2008 distribution. 2328ID EGM2008A 2329\endverbatim 2330 2331The code to produce the coefficient files for the wgs84 and grs80 models 2332is 2333\include make-egmcof.cpp 2334 2335\section gravitynga Comments on the NGA harmonic synthesis code 2336 2337GravityModel attempts to reproduce the results of NGA's 2338harmonic synthesis code for EGM2008, hsynth_WGS84.f. Listed here are 2339issues that I encountered using the NGA code: 2340 -# A compiler which allocates local variables on the stack produces an 2341 executable with just returns NaNs. The problem here is a missing 2342 <code>SAVE</code> statement in subroutine <code>latf</code>. 2343 -# Because the model and references masses for egm2008 differ (by about 2344 1 part in 10<sup>9</sup>), there should be a 1/\e r contribution to 2345 the disturbing potential \e T. However, this term is set to zero in 2346 hsynth_WGS84 (effectively altering the normal potential). This 2347 shifts the surface \e W = <i>U</i><sub>0</sub> outward by about 2348 5 mm. Note too that the reference ellipsoid is no longer a 2349 level surface of the effective normal potential. 2350 -# Subroutine <code>radgrav</code> computes the ellipsoidal coordinate 2351 β incorrectly. This leads to small errors in the deflection 2352 of the vertical, ξ and η, when the height above the 2353 ellipsoid, \e h, is non-zero (about 10<sup>−7</sup> arcsec at 2354 \e h = 400 km). 2355 -# There are several expressions which will return inaccurate results 2356 due to cancellation. For example, subroutine <code>grs</code> 2357 computes the flattening using \e f = 1 − sqrt(1 − 2358 <i>e</i><sup>2</sup>). Much better is to use \e f = 2359 <i>e</i><sup>2</sup>/(1 + sqrt(1 − <i>e</i><sup>2</sup>)). The 2360 expressions for \e q and \e q' in <code>grs</code> and 2361 <code>radgrav</code> suffer from similar problems. The resulting 2362 errors are tiny (about 50 pm in the geoid height); however, given 2363 that's there's essentially no cost to using more accurate 2364 expressions, it's preferable to do so. 2365 -# hsynth_WGS84 returns an "undefined" value for \e xi and \e eta at the 2366 poles. Better would be to return the value obtained by taking the 2367 limit \e lat → ± 90°. 2368 . 2369Issues 1--4 have been reported to the authors of hsynth_WGS84. 2370Issue 1 is peculiar to Fortran and is not encountered in C++ code and 2371GravityModel corrects issues 3--5. On issue 2, 2372GravityModel neglects the 1/\e r term in \e T in 2373GravityModel::GeoidHeight and 2374GravityModel::SphericalAnomaly in order to produce 2375results which match NGA's for these quantities. On the other hand, 2376GravityModel::Disturbance and 2377GravityModel::T <i>do</i> include this term. 2378 2379\section gravitygeoid Details of the geoid height and anomaly calculations 2380 2381Ideally, the geoid represents a surface of constant gravitational 2382potential which approximates mean sea level. In reality some 2383approximations are taken in determining this surface. The steps taking 2384by GravityModel in computing the geoid height are 2385described here (in the context of EGM2008). This mimics NGA's code 2386hsynth_WGS84 closely because most users of EGM2008 use the gridded data 2387generated by this code (e.g., Geoid) and it is desirable 2388to use a consistent definition of the geoid height. 2389 - The model potential is band limited; the minimum wavelength that is 2390 represented is 360°/2160 = 10' (i.e., about 10NM or 2391 18.5km). The maximum degree for the spherical harmonic sum is 2190; 2392 however the model was derived using ellipsoidal harmonics of degree 2393 and order 2160 and the degree was increased to 2190 in order to 2394 capture the ellipsoidal harmonics faithfully with spherical 2395 harmonics. 2396 - The 1/\e r term is omitted from the \e T (this is issue 2 in \ref 2397 gravitynga). This moves the equipotential surface by about 5mm. 2398 - The surface \e W = <i>U</i><sub>0</sub> is determined by Bruns' 2399 formula, which is roughly equivalent to a single iteration of 2400 Newton's method. The RMS error in this approximation is about 1.5mm 2401 with a maximum error of about 10 mm. 2402 - The model potential is only valid above the earth's surface. A 2403 correction therefore needs to be included where the geoid lies 2404 beneath the terrain. This is NGA's "zeta-to-N" correction, which is 2405 represented by a spherical harmonic sum of degree and order 2160 (and 2406 so it misses short wavelength terrain variations). In addition, it 2407 entails estimating the isostatic equilibrium of the earth's crust. 2408 The correction lies in the range [−5.05 m, 0.05 m], 2409 however for 99.9% of the earth's surface the correction is less than 2410 10 mm in magnitude. 2411 - The resulting surface lies above the observed mean sea level, 2412 so −0.41m is added to the geoid height. (Better would be to change 2413 the potential used to define the geoid; but this would only change 2414 the result by about 2mm.) 2415 . 2416A useful discussion of the problems with defining a geoid is given by 2417Dru A. Smith in 2418<a href="https://www.ngs.noaa.gov/PUBS_LIB/EGM96_GEOID_PAPER/egm96_geoid_paper.html"> 2419There is no such thing as "The" EGM96 geoid: Subtle points on the use of 2420a global geopotential model</a>, IGeS Bulletin No. 8, International 2421Geoid Service, Milan, Italy, pp. 17--28 (1998). 2422 2423GravityModel::GeoidHeight reproduces the results of the 2424several NGA codes for harmonic synthesis with the following maximum 2425discrepancies: 2426 - egm84 = 1.1mm. This is probably due to inconsistent parameters for the 2427 reference ellipsoid in the NGA code. (In particular, the value of 2428 mass constant excludes the atmosphere; however, it's not clear 2429 whether the other parameters have been correspondingly adjusted.) 2430 Note that geoid heights predicted by egm84 differ from those of more 2431 recent gravity models by about 1 meter. 2432 - egm96 = 23nm. 2433 - egm2008 = 78pm. After addressing some of the issues alluded to in 2434 issue 4 in \ref gravitynga, the maximum discrepancy becomes 23pm. 2435 2436The formula for the gravity anomaly vector involves computing gravity 2437and normal gravity at two different points (with the displacement 2438between the points unknown <i>ab initio</i>). Since the gravity anomaly 2439is already a small quantity it is sometimes acceptable to employ 2440approximations that change the quantities by \e O(\e f). The NGA code 2441uses the spherical approximation described by Heiskanen and Moritz, 2442Sec. 2-14 and GravityModel::SphericalAnomaly uses the 2443same approximation for compatibility. In this approximation, the 2444gravity disturbance <b>delta</b> = <b>grad</b> \e T is calculated. 2445Here, \e T once again excludes the 1/\e r term (this is issue 2 in \ref 2446gravitynga and is consistent with the computation of the geoid height). 2447Note that <b>delta</b> compares the gravity and the normal gravity at 2448the \e same point; the gravity anomaly vector is then found by 2449estimating the gradient of the normal gravity in the limit that the 2450earth is spherically symmetric. <b>delta</b> is expressed in \e 2451spherical coordinates as \e deltax, \e deltay, \e deltaz where, for 2452example, \e deltaz is the \e radial component of <b>delta</b> (not the 2453component perpendicular to the ellipsoid) and \e deltay is similarly 2454slightly different from the usual northerly component. The components 2455of the anomaly are then given by 2456 - gravity anomaly, \e Dg01 = \e deltaz − 2<i>T</i>/\e R, where \e R 2457 distance to the center of the earth; 2458 - northerly component of the deflection of the vertical, \e xi = − 2459 <i>deltay</i>/\e gamma, where \e gamma is the magnitude of the normal 2460 gravity; 2461 - easterly component of the deflection of the vertical, \e eta = − 2462 <i>deltax</i>/\e gamma. 2463 . 2464NormalGravity computes the normal gravity accurately and 2465avoids issue 3 of \ref gravitynga. Thus while 2466GravityModel::SphericalAnomaly reproduces the results for 2467\e xi and \e eta at \e h = 0, there is a slight discrepancy if \e h is 2468non-zero. 2469 2470\section gravityatmos The effect of the mass of the atmosphere 2471 2472All of the supported models use WGS84 for the reference ellipsoid. This 2473has (see 2474<a href="https://web.archive.org/web/20161214054445/https://earth-info.nga.mil/GandG/publications/tr8350.2/wgs84fin.pdf"> 2475TR8350.2</a>, table 3.1) 2476 - \e a = 6378137 m 2477 - \e f = 1/298.257223563 2478 - ω = 7292115 × 10<sup>−11</sup> rad 2479 s<sup>−1</sup> 2480 - \e GM = 3986004.418 × 10<sup>8</sup> m<sup>3</sup> 2481 s<sup>−2</sup>. 2482 . 2483The value of \e GM includes the mass of the atmosphere and so strictly 2484only applies above the earth's atmosphere. Near the surface of the 2485earth, the value of \e g will be less (in absolute value) than the value 2486predicted by these models by about δ\e g = (4π<i>G</i>/\e 2487g) \e A = 8.552 × 10<sup>−11</sup> \e 2488A m<sup>2</sup>/kg, where \e G is the gravitational constant, \e g 2489is the earth's gravity, and \e A is the pressure of the atmosphere. At 2490sea level we have \e A = 101.3 kPa, and δ\e g = 24918.7 × 10<sup>−6</sup> m s<sup>−2</sup>, 2492approximately. (In other words the effect is about 1 part in a 2493million; by way of comparison, buoyancy effects are about 100 times 2494larger.) 2495 2496\section gravityparallel Geoid heights on a multi-processor system 2497 2498The egm2008 model includes many terms (over 2 million spherical 2499harmonics). For that reason computations using this model may be slow; 2500for example it takes about 78 ms to compute the geoid height at a single 2501point. There are two ways to speed up this computation: 2502 - Use a GravityCircle to compute the geoid height at 2503 several points on a circle of latitude. This reduces the cost per 2504 point to about 92 μs (a reduction by a factor of over 800). 2505 - Compute the values on several circles of latitude in parallel. One 2506 of the simplest ways of doing this is with 2507 <a href="https://www.openmp.org"> OpenMP</a>; on an 8-processor system, 2508 this can speed up the computation by another factor of 8. 2509 . 2510Both of these techniques are illustrated by the following code, 2511which computes a table of geoid heights on 2512a regular grid and writes on the result in a 2513<a href="https://vdatum.noaa.gov/docs/gtx_info.html#dev_gtx_binary">.gtx</a> 2514file. On an 8-processor Intel 3.0 GHz machine using OpenMP 2515(-DHAVE_OPENMP=1), it takes about 10 minutes of elapsed time to compute 2516the geoid height for EGM2008 on a 1' grid. (Without these 2517optimizations, the computation would have taken about 50 days!) 2518\include GeoidToGTX.cpp 2519 2520cmake will add in support for OpenMP for 2521<code>examples/GeoidToGTX.cpp</code>, if it is available. 2522 2523<center> 2524Back to \ref geoid. Forward to \ref normalgravity. Up to \ref contents. 2525</center> 2526 2527**********************************************************************/ 2528/** 2529\page normalgravity Normal gravity 2530 2531<center> 2532Back to \ref gravity. Forward to \ref magnetic. Up to \ref contents. 2533</center> 2534 2535The NormalGravity class computes "normal gravity" which refers to the 2536exact (classical) solution of an idealised system consisting of an 2537ellipsoid of revolution with the following properties: 2538 - \e M the mass interior to the ellipsoid, 2539 - \e a the equatorial radius, 2540 - \e b the polar semi-axis, 2541 - ω the rotation rate about the polar axis. 2542 . 2543(N.B. The mass always appears in the combination \e GM, with units 2544m<sup>3</sup>/s<sup>2</sup>, where \e G is the gravtitational constant.) 2545The distribution of the mass \e M within the ellipsoid is such that the 2546surface of the ellipsoid is at a constant normal potential where the 2547normal potential is the sum of the gravitational potential (due to the 2548gravitational attraction) and the centrifugal potential (due to the 2549rotation). The resulting field exterior to the ellipsoid is called 2550<i>normal gravity</i> and was found by Somigliana (1929). Because the 2551potential is constant on the ellipsoid it is sometimes referred to as 2552the <i>level ellipsoid</i>. 2553 2554Go to 2555 - \ref normalgravcoords 2556 - \ref normalgravpot 2557 - \ref normalgravmass 2558 - \ref normalgravsurf 2559 - \ref normalgravmean 2560 - \ref normalgravj2 2561 2562References: 2563 - C. Somigliana, Teoria generale del campo gravitazionale dell'ellissoide 2564 di rotazione, Mem. Soc. Astron. Ital, <b>4</b>, 541--599 (1929). 2565 - W. A. Heiskanen and H. Moritz, Physical Geodesy (Freeman, San 2566 Francisco, 1967), Secs. 1-19, 2-7, 2-8 (2-9, 2-10), 6-2 (6-3). 2567 - B. Hofmann-Wellenhof, H. Moritz, Physical Geodesy (Second edition, 2568 Springer, 2006). https://doi.org/10.1007/978-3-211-33545-1 2569 - H. Moritz, Geodetic Reference System 1980, J. Geodesy 54(3), 395--405 2570 (1980). https://doi.org/10.1007/BF02521480 2571 - H. Moritz, The Figure of the Earth (Wichmann, 1990). 2572 - M. Chasles, Solution nouvelle du problème de l’attraction d’un 2573 ellipsoïde hétérogène sur un point 2574 exterieur, Jour. Liouville 5, 465--488 (1840), Note 2. 2575 http://sites.mathdoc.fr/JMPA/PDF/JMPA_1840_1_5_A41_0.pdf 2576 2577\section normalgravcoords Ellipsoidal coordinates 2578 2579Two set of formulas are presented: those of Heiskanen and Moritz (1967) 2580which are applicable to an oblate ellipsoid and a second set where the 2581variables are distinguished with primes which apply to a prolate 2582ellipsoid. The primes are omitted from those variables which are the 2583same in the two cases. In the text, the parenthetical "alt." clauses 2584apply to prolate ellipsoids. 2585 2586Cylindrical coordinates \f$ R,Z \f$ are expressed in terms of 2587ellipsoidal coordinates 2588\f[ 2589\begin{align} 2590 R &= \sqrt{u^2 + E^2} \cos\beta = u' \cos\beta,\\ 2591 Z &= u \sin\beta = \sqrt{u'^2 + E'^2} \sin\beta, 2592\end{align} 2593\f] 2594where 2595\f[ 2596\begin{align} 2597 E^2 = a^2 - b^2,&{} \qquad u^2 = u'^2 + E'^2,\\ 2598 E'^2 = b^2 - a^2,&{} \qquad u'^2 = u^2 + E^2. 2599\end{align} 2600\f] 2601Surfaces of constant \f$ u \f$ (or \f$ u' \f$) are confocal ellipsoids. 2602The surface \f$ u = 0 \f$ (alt. \f$ u' = 0 \f$) corresponds to the 2603focal disc of diameter \f$ 2E \f$ (alt. focal rod of length 2604\f$ 2E' \f$). The level ellipsoid is given by \f$ u = b \f$ 2605(alt. \f$ u' = a \f$). On the level ellipsoid, \f$ \beta \f$ is the 2606familiar parametric latitude. 2607 2608In writing the potential and the gravity, it is useful to introduce the 2609functions 2610\f[ 2611\begin{align} 2612 Q(z) &= \frac1{2z^3} 2613 \biggl[\biggl(1 + \frac3{z^2}\biggr)\tan^{-1}z - \frac3z\biggr],\\ 2614 Q'(z') &= \frac{(1+z'^2)^{3/2}}{2z'^3} 2615 \biggl[\biggl(2 + \frac3{z'^2}\biggr)\sinh^{-1}z' - 2616 \frac{3\sqrt{1+z'^2}}{z'}\biggr],\\ 2617 H(z) &= \biggl(3Q(z)+z\frac{dQ(z)}{dz}\biggr)(1+z^2)\\ 2618 &= \frac1{z^4}\biggl[3(1+z^2) 2619 \biggl(1-\frac{\tan^{-1}z}z\biggr)-z^2\biggr],\\ 2620 H'(z') &= \frac{3Q'(z')}{1+z'^2}+z'\frac{dQ'(z')}{dz'}\\ 2621 &= \frac{1+z'^2}{z'^4} 2622 \biggl[3\biggl(1-\frac{\sqrt{1+z'^2}\sinh^{-1}z'}{z'}\biggr) 2623 +z'^2\biggr]. 2624\end{align} 2625\f] 2626The function arguments are \f$ z = E/u \f$ 2627(alt. \f$ z' = E'/u' \f$) and the unprimed and primed quantities are 2628related by 2629\f[ 2630\begin{align} 2631Q'(z') = Q(z),&{} \qquad H'(z') = H(z),\\ 2632z'^2 = -\frac{z^2}{1 + z^2},&{} \qquad z^2 = -\frac{z'^2}{1 + z'^2}. 2633\end{align} 2634\f] 2635The functions \f$ q(u) \f$ and \f$ q'(u) \f$ used by Heiskanen and 2636Moritz are given by 2637\f[ 2638 q(u) = \frac{E^3}{u^3}Q\biggl(\frac Eu\biggr),\qquad 2639 q'(u) = \frac{E^2}{u^2}H\biggl(\frac Eu\biggr). 2640\f] 2641The functions \f$ Q(z) \f$, \f$ Q'(z') \f$, \f$ H(z) \f$, and 2642\f$ H'(z') \f$ are more convenient for use in numerical codes because 2643they are finite in the spherical limit \f$ E \rightarrow 0 \f$, i.e., 2644\f$ Q(0) = Q'(0) = \frac2{15} \f$, and \f$ H(0) = H'(0) = \frac25 \f$. 2645 2646\section normalgravpot The normal potential 2647 2648The normal potential is the sum of three components, a mass term, a 2649quadrupole term and a centrifugal term, 2650\f[ U = U_m + U_q + U_r. \f] 2651The mass term is 2652\f[ U_m = \frac {GM}E \tan^{-1}\frac Eu 2653 = \frac {GM}{E'} \sinh^{-1}\frac{E'}{u'}; \f] 2654the quadrupole term is 2655\f[ 2656\begin{align} 2657 U_q &= \frac{\omega^2}2 \frac{a^2 b^3}{u^3} \frac{Q(E/u)}{Q(E/b)} 2658 \biggl(\sin^2\beta-\frac13\biggr)\\ 2659 &= \frac{\omega^2}2 \frac{a^2 b^3}{(u'^2+E'^2)^{3/2}} 2660 \frac{Q'(E'/u')}{Q'(E'/a)} 2661 \biggl(\sin^2\beta-\frac13\biggr); 2662\end{align} 2663\f] 2664finally, the rotational term is 2665\f[ 2666U_r = \frac{\omega^2}2 R^2 2667 = \frac{\omega^2}2 (u^2 + E^2) \cos^2\beta 2668 = \frac{\omega^2}2 u'^2 \cos^2\beta. 2669\f] 2670 2671\f$ U_m \f$ and \f$ U_q \f$ are both gravitational potentials (due to 2672mass within the ellipsoid). The total mass contributing to \f$ U_m \f$ 2673is \f$ M \f$; the total mass contributing to \f$ U_q \f$ vanishes (far 2674from the ellipsoid, the \f$ U_q \f$ decays inversely as the cube of the 2675distance). 2676 2677\f$ U_m \f$ and \f$ U_q + U_r \f$ are separately both constant on the 2678level ellipsoid. \f$ U_m \f$ is the normal potential for a massive 2679non-rotating ellipsoid. \f$ U_q + U_r \f$ is the potential for a 2680massless rotating ellipsoid. Combining all the terms, \f$ U \f$ is the 2681normal potential for a massive rotating ellipsoid. 2682 2683The figure shows normal gravity for the case \f$ GM = 1 \f$, 2684\f$ a = 1 \f$, \f$ b = 0.8 \f$, \f$ \omega = 0.3 \f$. The level 2685ellipsoid is shown in red. Contours of constant gravity potential are 2686shown in blue; the contour spacing is constant outside the ellipsoid and 2687equal to 1/20 of the difference between the potentials on the ellipsoid 2688and at the geostationary point (\f$ R = 2.2536 \f$, \f$ Z = 0 \f$); 2689inside the ellipsoid the contour spacing is 5 times greater. The green 2690lines are stream lines for the gravity; these are spaced at intervals of 269110° in parametric latitude on the surface of the ellipsoid. The 2692normal gravity is continued into the level ellipsoid under the 2693assumption that the mass is concentrated on the focal disc, shown in 2694black. 2695 2696\image html normal-gravity-potential-1.svg "Normal gravity" 2697 2698\section normalgravmass The mass distribution 2699 2700Typically, the normal potential, \f$ U \f$, is only of interest for 2701outside the ellipsoid \f$ u \ge b \f$ (alt. \f$ u' \ge a \f$). In 2702planetary applications, an open problem is finding a mass distribution 2703which is in hydrostatic equilibrium (the mass density is non-negative 2704and a non-decreasing function of the potential interior to the 2705ellipsoid). 2706 2707However it is possible to give singular mass distributions consistent 2708with the normal potential. 2709 2710For a non-rotating body, the potential \f$ U = U_m \f$ is generated by a 2711sandwiching the mass \f$ M \f$ uniformly between the level ellipsoid 2712with semi-axes \f$ a \f$ and \f$ b \f$ and a close <i>similar</i> 2713ellipsoid with semi-axes \f$ (1-\epsilon)a \f$ and 2714\f$ (1-\epsilon)b \f$. Chasles (1840) extends a theorem of Newton to 2715show that the field interior to such an ellipsoidal shell vanishes. 2716Thus the potential on the ellipsoid is constant, i.e., it is indeed a 2717level ellipsoid. This result also holds for a non-rotating triaxial 2718ellipsoid. 2719 2720Observing that \f$ U_m \f$ and \f$ U_q \f$ as defined above obey 2721\f$ \nabla^2 U_m = \nabla^2 U_q = 0 \f$ everywhere for \f$ u > 0 \f$ 2722(alt. \f$ u' > 0 \f$), we see that these potentials correspond to 2723masses concentrated at \f$ u = 0 \f$ (alt. \f$ u' = 0 \f$). 2724 2725In the oblate case, \f$ U_m \f$ is generated by a massive disc at 2726\f$ Z = 0 \f$, \f$ R < E \f$, with mass density (mass per unit area) \f$ 2727\rho_m \f$ and moments of inertia about the equatorial (resp. polar) 2728axis of \f$ A_m \f$ (resp. \f$ C_m \f$) given by 2729\f[ 2730\begin{align} 2731\rho_m &= \frac M{2\pi E\sqrt{E^2 - R^2}},\\ 2732A_m &= \frac {ME^2}3, \\ 2733C_m &= \frac {2ME^2}3, \\ 2734C_m-A_m &= \frac {ME^2}3. 2735\end{align} 2736\f] 2737This mass distribution is the same as that produced by projecting a 2738uniform spheric shell of mass \f$ M \f$ and radius \f$ E \f$ onto the 2739equatorial plane. 2740 2741In the prolate case, \f$ U_m \f$ is generated by a massive rod at \f$ R 2742= 0 \f$, \f$ Z < E' \f$ and now the mass density \f$ \rho'_m \f$ has 2743units mass per unit length, 2744\f[ 2745\begin{align} 2746\rho'_m &= \frac M{2E'},\\ 2747A_m &= \frac {ME'^2}3, \\ 2748C_m &= 0, \\ 2749C_m-A_m &= -\frac {ME'^2}3. 2750\end{align} 2751\f] 2752This mass distribution is the same as that produced by projecting a 2753uniform spheric shell of mass \f$ M \f$ and radius \f$ E' \f$ onto the 2754polar axis. 2755 2756Similarly, \f$ U_q \f$ is generated in the oblate case by 2757\f[ 2758\begin{align} 2759\rho_q &= \frac{a^2 b^3 \omega^2}G 2760 \frac{2E^2 - 3R^2}{6\pi E^5 \sqrt{E^2 - R^2} Q(E/b)}, \\ 2761A_q &= -\frac{a^2 b^3 \omega^2}G \frac2{45\,Q(E/b)}, \\ 2762C_q &= -\frac{a^2 b^3 \omega^2}G \frac4{45\,Q(E/b)}, \\ 2763C_q-A_q &= -\frac{a^2 b^3 \omega^2}G \frac2{45\,Q(E/b)}. 2764\end{align} 2765\f] 2766The corresponding results for a prolate ellipsoid are 2767\f[ 2768\begin{align} 2769\rho_q' &= \frac{a^2 b^3 \omega^2}G 2770 \frac{3Z^2 - E'^2}{12\,E'^5 Q'(E'/a)}, \\ 2771A_q &= \frac{a^2 b^3 \omega^2}G \frac2{45\,Q'(E'/a)}, \\ 2772C_q &= 0, \\ 2773C_q-A_q &= -\frac{a^2 b^3 \omega^2}G \frac2{45\,Q'(E'/a)}. 2774\end{align} 2775\f] 2776 2777Summing up the mass and quadrupole terms, we have 2778\f[ 2779\begin{align} 2780A &= A_m + A_q, \\ 2781C &= C_m + C_q, \\ 2782J_2 & = \frac{C - A}{Ma^2}, 2783\end{align} 2784\f] 2785where \f$ J_2 \f$ is the <i>dynamical form factor</i>. 2786 2787\section normalgravsurf The surface gravity 2788 2789Each term in the potential contributes to the gravity on the surface of 2790the ellipsoid 2791\f[ 2792\gamma = \gamma_m + \gamma_q + \gamma_r; 2793\f] 2794These are the components of gravity normal to the ellipsoid and, by 2795convention, \f$ \gamma \f$ is positive downwards. The tangential 2796components of the total gravity and that due to \f$ U_m \f$ vanish. 2797Those tangential components of the gravity due to \f$ U_q \f$ and \f$ 2798U_r \f$ cancel one another. 2799 2800The gravity \f$ \gamma \f$ has the following dependence on latitude 2801\f[ 2802\begin{align} 2803\gamma &= \frac{b\gamma_a\cos^2\beta + a\gamma_b\sin^2\beta} 2804 {\sqrt{b^2\cos^2\beta + a^2\sin^2\beta}}\\ 2805 &= \frac{a\gamma_a\cos^2\phi + b\gamma_b\sin^2\phi} 2806 {\sqrt{a^2\cos^2\phi + b^2\sin^2\phi}}, 2807\end{align} 2808\f] 2809and the individual components, \f$ \gamma_m \f$, \f$ \gamma_q \f$, and 2810\f$ \gamma_r \f$, have the same dependence on latitude. The equatorial 2811and polar gravities are 2812\f[ 2813\begin{align} 2814\gamma_a &= \gamma_{ma} + \gamma_{qa} + \gamma_{ra},\\ 2815\gamma_b &= \gamma_{mb} + \gamma_{qb} + \gamma_{rb}, 2816\end{align} 2817\f] 2818where 2819\f[ 2820\begin{align} 2821\gamma_{ma} &= \frac{GM}{ab},\qquad \gamma_{mb} = \frac{GM}{a^2},\\ 2822\gamma_{qa} &= -\frac{\omega^2 a}6 \frac{H(E/b)}{Q(E/b)} 2823 = -\frac{\omega^2 a}6 \frac{H'(E'/a)}{Q'(E'/a)},\\ 2824\gamma_{qb} &= -\frac{\omega^2 b}3 \frac{H(E/b)}{Q(E/b)} 2825 = -\frac{\omega^2 b}3 \frac{H'(E'/a)}{Q'(E'/a)},\\ 2826\gamma_{ra} &= -\omega^2 a,\qquad \gamma_{rb} = 0. 2827\end{align} 2828\f] 2829 2830\section normalgravmean The mean gravity 2831 2832Performing an average of the surface gravity over the area of the 2833ellipsoid gives 2834\f[ 2835\langle \gamma \rangle = \frac {4\pi a^2 b}A 2836 \biggl(\frac{2\gamma_a}{3a} + \frac{\gamma_b}{3b}\biggr), 2837\f] 2838where \f$ A \f$ is the area of the ellipsoid 2839\f[ 2840\begin{align} 2841 A &= 2\pi\biggl( a^2 + ab\frac{\sinh^{-1}(E/b)}{E/b} \biggr)\\ 2842 &= 2\pi\biggl( a^2 + b^2\frac{\tan^{-1}(E'/a)}{E'/a} \biggr). 2843\end{align} 2844\f] 2845 2846The contributions to the mean gravity are 2847\f[ 2848\begin{align} 2849\langle \gamma_m \rangle &= \frac{4\pi}A GM, \\ 2850\langle \gamma_q \rangle &= 0 \quad \text{(as expected)}, \\ 2851\langle \gamma_r \rangle &= -\frac{4\pi}A \frac{2\omega^2 a^2b}3,\\ 2852\end{align} 2853\f] 2854resulting in 2855\f[ 2856\langle \gamma \rangle = \frac{4\pi}A 2857 \biggl(GM - \frac{2\omega^2 a^2b}3\biggr). 2858\f] 2859 2860\section normalgravj2 Possible values of the dynamical form factor 2861 2862The solution for the normal gravity is well defined for arbitrary 2863\f$ M \f$, \f$ \omega \f$, \f$ a > 0\f$, and \f$ f < 1 \f$. (Note that 2864arbitrary oblate and prolate ellipsoids are possible, although 2865hydrostatic equilibrium would not result in a prolate ellipsoid.) 2866However, it is much easier to measure the dynamical form factor 2867\f$ J_2 \f$ (from the motion of artificial satellites) than the 2868flattening \f$ f \f$. (Note too that \f$ GM \f$ is typically 2869measured from from satellite or astronomical observations and so it 2870includes the mass of the atmosphere.) 2871 2872So a question for the software developer is: given values of \f$ M > 0\f$, 2873\f$ \omega \f$, and \f$ a > 0 \f$, what are the allowed values of 2874\f$ J_2 \f$? We restrict the question to \f$ M > 0 \f$. The 2875(unphysical) case \f$ M = 0 \f$ is problematic because \f$ M \f$ appears 2876in the denominator in the definition of \f$ J_2 \f$. In the (also 2877unphysical) case \f$ M < 0 \f$, a given \f$ J_2 \f$ can result from two 2878distinct values of \f$ f \f$. 2879 2880Holding \f$ M > 0\f$, \f$ \omega \f$, and \f$ a > 0 \f$ fixed and 2881varying \f$ f \f$ from \f$ -\infty \f$ to \f$ 1 \f$, we find that 2882\f$ J_2 \f$ monotonically increases from \f$ -\infty \f$ to 2883\f[ 2884\frac13 - \frac8{45\pi} \frac{\omega^2 a^3}{GM}. 2885\f] 2886Thus any value of \f$ J_2 \f$ less that this value is permissible (but 2887some of these values may be unphysical). In obtaining this limiting 2888value, we used the result 2889\f$ Q(z \rightarrow \infty) \rightarrow \pi/(4 z^3) \f$. The value 2890\f[ 2891J_2 = -\frac13 \frac{\omega^2 a^3}{GM} 2892\f] 2893results in a sphere (\f$ f = 0 \f$). 2894 2895<center> 2896Back to \ref gravity. Forward to \ref magnetic. Up to \ref contents. 2897</center> 2898 2899**********************************************************************/ 2900/** 2901\page magnetic Magnetic models 2902 2903<center> 2904Back to \ref normalgravity. Forward to \ref geodesic. Up to \ref contents. 2905</center> 2906 2907GeographicLib can compute the earth's magnetic field by a magnetic 2908model using the MagneticModel and 2909MagneticCircle classes and with the 2910<a href="MagneticField.1.html">MagneticField</a> utility. These models 2911expand the internal magnetic potential of the earth as sum of spherical 2912harmonics. They neglect magnetic fields due to the ionosphere, the 2913magnetosphere, nearby magnetized materials, electric machinery, etc. 2914Users of MagneticModel are advised to read the 2915<a href="https://www.ngdc.noaa.gov/IAGA/vmod/igrfhw.html">"Health 2916Warning"</a> this is provided with igrf11. Although the advice is 2917specific to igrf11, many of the comments apply to all magnetic field 2918models. 2919 2920The supported models are 2921 - <b>wmm2010</b>, the 2922 <a href="https://ngdc.noaa.gov/geomag/WMM/DoDWMM.shtml"> World 2923 Magnetic Model 2010</a>, which approximates the main magnetic field 2924 for the period 2010--2015. 2925 - <b>wmm2015v2</b>, the 2926 <a href="https://ngdc.noaa.gov/geomag/WMM/DoDWMM.shtml"> World 2927 Magnetic Model 2015</a>, which approximates the main magnetic field 2928 for the period 2015--2020. 2929 - <b>wmm2015</b>, a deprecated version of wmm2015v2. 2930 - <b>wmm2020</b>, the 2931 <a href="https://ngdc.noaa.gov/geomag/WMM/DoDWMM.shtml"> World 2932 Magnetic Model 2020</a>, which approximates the main magnetic field 2933 for the period 2020--2025. 2934 - <b>igrf11</b>, the 2935 <a href="https://ngdc.noaa.gov/IAGA/vmod/igrf.html">International 2936 Geomagnetic Reference Field (11th generation)</a>, which approximates 2937 the main magnetic field for the period 1900--2015. 2938 - <b>igrf12</b>, the 2939 <a href="https://ngdc.noaa.gov/IAGA/vmod/igrf.html">International 2940 Geomagnetic Reference Field (12th generation)</a>, which approximates 2941 the main magnetic field for the period 1900--2020. 2942 - <b>igrf13</b>, the 2943 <a href="https://ngdc.noaa.gov/IAGA/vmod/igrf.html">International 2944 Geomagnetic Reference Field (13th generation)</a>, which approximates 2945 the main magnetic field for the period 1900--2025. 2946 - <b>emm2010</b>, the 2947 <a href="https://ngdc.noaa.gov/geomag/EMM/index.html"> Enhanced 2948 Magnetic Model 2010</a>, which approximates the main and crustal 2949 magnetic fields for the period 2010--2015. 2950 - <b>emm2015</b>, the 2951 <a href="https://ngdc.noaa.gov/geomag/EMM/index.html"> Enhanced 2952 Magnetic Model 2015</a>, which approximates the main and crustal 2953 magnetic fields for the period 2000--2020. 2954 - <b>emm2017</b>, the 2955 <a href="https://ngdc.noaa.gov/geomag/EMM/index.html"> Enhanced 2956 Magnetic Model 2017</a>, which approximates the main and crustal 2957 magnetic fields for the period 2000--2022. 2958 2959Go to 2960 - \ref magneticinst 2961 - \ref magneticformat 2962 2963\section magneticinst Installing the magnetic field models 2964 2965These magnetic models are available for download: 2966<center> 2967<table> 2968<caption>Available magnetic models</caption> 2969<tr> 2970 <th rowspan="2">name <th rowspan="2">max\n degree 2971 <th rowspan="2">time\n interval 2972 <th rowspan="2">size\n(kB) 2973 <th colspan="3"><center>Download Links (size, kB)</center></th> 2974<tr> 2975 <th>tar file</th> 2976 <th>Windows\n installer</th> 2977 <th>zip file</th> 2978<tr> 2979 <td>wmm2010 2980 <td><center>12</center> 2981 <td><center>2010--2015</center> 2982 <td><center>3</center> 2983 <td><center> 2984 <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/wmm2010.tar.bz2"> 2985 link</a> (2)</center> 2986 <td><center> 2987 <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/wmm2010.exe"> 2988 link</a> (300)</center> 2989 <td><center> 2990 <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/wmm2010.zip"> 2991 link</a> (2)</center> 2992<tr> 2993 <td>wmm2015 2994 <td><center>12</center> 2995 <td><center>2015--2020</center> 2996 <td><center>3</center> 2997 <td><center> 2998 <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/wmm2015.tar.bz2"> 2999 link</a> (2)</center> 3000 <td><center> 3001 <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/wmm2015.exe"> 3002 link</a> (300)</center> 3003 <td><center> 3004 <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/wmm2015.zip"> 3005 link</a> (2)</center> 3006<tr> 3007 <td>wmm2015v2 3008 <td><center>12</center> 3009 <td><center>2015--2020</center> 3010 <td><center>3</center> 3011 <td><center> 3012 <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/wmm2015v2.tar.bz2"> 3013 link</a> (2)</center> 3014 <td><center> 3015 <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/wmm2015v2.exe"> 3016 link</a> (300)</center> 3017 <td><center> 3018 <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/wmm2015v2.zip"> 3019 link</a> (2)</center> 3020<tr> 3021 <td>wmm2020 3022 <td><center>12</center> 3023 <td><center>2020--2025</center> 3024 <td><center>3</center> 3025 <td><center> 3026 <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/wmm2020.tar.bz2"> 3027 link</a> (2)</center> 3028 <td><center> 3029 <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/wmm2020.exe"> 3030 link</a> (1390)</center> 3031 <td><center> 3032 <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/wmm2020.zip"> 3033 link</a> (2)</center> 3034<tr> 3035 <td>igrf11 3036 <td><center>13</center> 3037 <td><center>1900--2015</center> 3038 <td><center>25</center> 3039 <td><center> 3040 <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/igrf11.tar.bz2"> 3041 link</a> (7)</center> 3042 <td><center> 3043 <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/igrf11.exe"> 3044 link</a> (310)</center> 3045 <td><center> 3046 <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/igrf11.zip"> 3047 link</a> (8)</center> 3048<tr> 3049 <td>igrf12 3050 <td><center>13</center> 3051 <td><center>1900--2020</center> 3052 <td><center>26</center> 3053 <td><center> 3054 <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/igrf12.tar.bz2"> 3055 link</a> (7)</center> 3056 <td><center> 3057 <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/igrf12.exe"> 3058 link</a> (310)</center> 3059 <td><center> 3060 <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/igrf12.zip"> 3061 link</a> (8)</center> 3062<tr> 3063 <td>igrf13 3064 <td><center>13</center> 3065 <td><center>1900--2025</center> 3066 <td><center>28</center> 3067 <td><center> 3068 <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/igrf13.tar.bz2"> 3069 link</a> (7)</center> 3070 <td><center> 3071 <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/igrf13.exe"> 3072 link</a> (1420)</center> 3073 <td><center> 3074 <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/igrf13.zip"> 3075 link</a> (8)</center> 3076<tr> 3077 <td>emm2010 3078 <td><center>739</center> 3079 <td><center>2010--2015</center> 3080 <td><center>4400</center> 3081 <td><center> 3082 <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/emm2010.tar.bz2"> 3083 link</a> (3700)</center> 3084 <td><center> 3085 <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/emm2010.exe"> 3086 link</a> (3000)</center> 3087 <td><center> 3088 <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/emm2010.zip"> 3089 link</a> (4100)</center> 3090<tr> 3091 <td>emm2015 3092 <td><center>729</center> 3093 <td><center>2000--2020</center> 3094 <td><center>4300</center> 3095 <td><center> 3096 <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/emm2015.tar.bz2"> 3097 link</a> (660)</center> 3098 <td><center> 3099 <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/emm2015.exe"> 3100 link</a> (990)</center> 3101 <td><center> 3102 <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/emm2015.zip"> 3103 link</a> (1030)</center> 3104<tr> 3105 <td>emm2017 3106 <td><center>790</center> 3107 <td><center>2000--2022</center> 3108 <td><center>5050</center> 3109 <td><center> 3110 <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/emm2017.tar.bz2"> 3111 link</a> (1740)</center> 3112 <td><center> 3113 <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/emm2017.exe"> 3114 link</a> (1700)</center> 3115 <td><center> 3116 <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/emm2017.zip"> 3117 link</a> (2750)</center> 3118</table> 3119</center> 3120The "size" column is the size of the uncompressed data. <b>N.B.</b>, the 3121wmm2015 model is <b>deprecated</b>; use wmm2015v2 instead. 3122 3123For Linux and Unix systems, GeographicLib provides a shell script 3124geographiclib-get-magnetic (typically installed in /usr/local/sbin) 3125which automates the process of downloading and installing the magnetic 3126models. For example 3127\verbatim 3128 geographiclib-get-magnetic all # install all available models 3129 geographiclib-get-magnetic -h # for help 3130\endverbatim 3131This script should be run as a user with write access to the 3132installation directory, which is typically 3133/usr/local/share/GeographicLib (this can be overridden with the -p 3134flag), and the data will then be placed in the "magnetic" subdirectory. 3135 3136Windows users should download and run the Windows installers. These 3137will prompt for an installation directory with the default being 3138\verbatim 3139 C:/ProgramData/GeographicLib 3140\endverbatim 3141(which you probably should not change) and the data is installed in the 3142"magnetic" sub-directory. (The second directory name is an alternate name 3143that Windows 7 uses for the "Application Data" directory.) 3144 3145Otherwise download \e either the tar.bz2 file \e or the zip file (they 3146have the same contents). To unpack these, run, for example 3147\verbatim 3148 mkdir -p /usr/local/share/GeographicLib 3149 tar xofjC wmm2020.tar.bz2 /usr/local/share/GeographicLib 3150 tar xofjC emm2010.tar.bz2 /usr/local/share/GeographicLib 3151 etc. 3152\endverbatim 3153and, again, the data will be placed in the "magnetic" subdirectory. 3154 3155However you install the magnetic models, all the datasets should be 3156installed in the same directory. MagneticModel and 3157<a href="MagneticField.1.html">MagneticField</a> uses a compile time 3158default to locate the datasets. This is 3159- /usr/local/share/GeographicLib/magnetic, for non-Windows systems 3160- C:/ProgramData/GeographicLib/magnetic, for Windows systems 3161. 3162consistent with the examples above. This may be overridden at run-time 3163by defining the GEOGRAPHICLIB_MAGNETIC_PATH or the GEOGRAPHIC_DATA 3164environment variables; see 3165MagneticModel::DefaultMagneticPath() for details. 3166Finally, the path may be set using the optional second argument to the 3167MagneticModel constructor or with the "-d" flag to 3168<a href="MagneticField.1.html">MagneticField</a>. Supplying the "-h" 3169flag to 3170<a href="MagneticField.1.html">MagneticField</a> reports the default 3171path for magnetic models for that utility. The "-v" flag causes 3172MagneticField to report the full path name of the data file it uses. 3173 3174\section magneticformat The format of the magnetic model files 3175 3176The constructor for MagneticModel reads a file called 3177NAME.wmm which specifies various properties for the magnetic model. It 3178then opens a binary file NAME.wmm.cof to obtain the coefficients of the 3179spherical harmonic sum. 3180 3181The first line of the .wmm file must consist of "WMMF-v" where WMMF 3182stands for "World Magnetic Model Format" and v is the version number of 3183the format (currently "2"). 3184 3185The rest of the File is read a line at a time. A # character and 3186everything after it are discarded. If the result is just white space it 3187is discarded. The remaining lines are of the form "KEY WHITESPACE 3188VALUE". In general, the KEY and the VALUE are case-sensitive. 3189 3190MagneticModel only pays attention to the following 3191keywords 3192 - keywords that affect the field calculation, namely: 3193 - <b>Radius</b> (required), the normalizing radius of the model in 3194 meters. 3195 - <b>NumModels</b> (default 1), the number of models. WMM2020 3196 consists of a single model giving the magnetic field and its time 3197 variation at 2020. IGRF12 consists of 24 models for 1900 thru 2015 3198 at 5 year intervals. The time variation is given only for the last 3199 model to allow extrapolation beyond 2015. For dates prior to 2015, 3200 linear interpolation is used. 3201 - <b>NumConstants</b> (default 0), the number of time-independent 3202 terms; this can be 0 or 1. This keyword was introduced in format 3203 version 2 (GeographicLib version 1.43) to support the EMM2015 and 3204 later models. This model includes long wavelength time-varying 3205 components of degree 15. This is supplemented by a short 3206 wavelength time-independent component with much higher degree. 3207 - <b>Epoch</b> (required), the time origin (in fractional years) for 3208 the first model. 3209 - <b>DeltaEpoch</b> (default 1), the interval between models in years 3210 (only relevant for NumModels > 1). 3211 - <b>Normalization</b> (default schmidt), the normalization used for 3212 the associated Legendre functions (schmidt or full). 3213 - <b>ID</b> (required), 8 printable characters which serve as a 3214 signature for the .wmm.cof file (they must appear as the first 8 3215 bytes of this file). 3216 - keywords that store data that the user can query: 3217 - <b>Name</b>, the name of the model. 3218 - <b>Description</b>, a more descriptive name of the model. 3219 - <b>ReleaseDate</b>, when the model was created. 3220 - <b>MinTime</b>, the minimum date at which the model should be used. 3221 - <b>MaxTime</b>, the maximum date at which the model should be used. 3222 - <b>MinHeight</b>, the minimum height above the ellipsoid for which 3223 the model should be used. 3224 - <b>MaxHeight</b>, the maximum height above the ellipsoid for which 3225 the model should be used. 3226 . 3227 MagneticModel does not enforce the restrictions 3228 implied by last four quantities. However, 3229 <a href="MagneticField.1.html">MagneticField</a> issues a warning if 3230 these limits are exceeded. 3231 - keywords that are examined to verify that their values are valid: 3232 - <b>Type</b> (default linear), the type of the model. "linear" 3233 means that the time variation is piece-wise linear (either using 3234 interpolation between the field at two dates or using the field and 3235 its first derivative with respect to time). This is the only type 3236 of model supported at present. 3237 - <b>ByteOrder</b> (default little), the order of bytes in the 3238 .wmm.cof file. Only little endian is supported at present. 3239 . 3240Other keywords are ignored. 3241 3242The coefficient file NAME.wmm.cof is a binary file in little endian 3243order. The first 8 bytes of this file must match the ID given in 3244NAME.wmm. This is followed by NumModels + 1 sets of spherical harmonic 3245coefficients. The first NumModels of these model the magnetic field at 3246Epoch + \e i * DeltaEpoch for 0 ≤ \e i < NumModels. The last set of 3247coefficients model the rate of change of the magnetic field at Epoch + 3248(NumModels − 1) * DeltaEpoch. The format for each set of coefficients 3249is: 3250 - \e N, the maximum degree of the sum stored as a 4-byte signed integer. 3251 This must satisfy \e N ≥ −1. 3252 - \e M, the maximum order of the sum stored as a 4-byte signed integer. 3253 This must satisfy \e N ≥ \e M ≥ −1. 3254 - <i>C</i><sub><i>nm</i></sub>, the coefficients of the cosine 3255 coefficients of the sum in column (i.e., \e m) major order. There 3256 are (\e M + 1) (2\e N − \e M + 2) / 2 elements which are stored 3257 as IEEE doubles (8 bytes). For example for \e N = \e M = 3, there 3258 are 10 coefficients arranged as 3259 <i>C</i><sub>00</sub>, 3260 <i>C</i><sub>10</sub>, 3261 <i>C</i><sub>20</sub>, 3262 <i>C</i><sub>30</sub>, 3263 <i>C</i><sub>11</sub>, 3264 <i>C</i><sub>21</sub>, 3265 <i>C</i><sub>31</sub>, 3266 <i>C</i><sub>22</sub>, 3267 <i>C</i><sub>32</sub>, 3268 <i>C</i><sub>33</sub>. 3269 - <i>S</i><sub><i>nm</i></sub>, the coefficients of the sine 3270 coefficients of the sum in column (i.e., \e m) major order starting 3271 at \e m = 1. There are \e M (2\e N − \e M + 1) / 2 elements 3272 which are stored as IEEE doubles (8 bytes). For example for \e N = 3273 \e M = 3, there are 6 coefficients arranged as 3274 <i>S</i><sub>11</sub>, 3275 <i>S</i><sub>21</sub>, 3276 <i>S</i><sub>31</sub>, 3277 <i>S</i><sub>22</sub>, 3278 <i>S</i><sub>32</sub>, 3279 <i>S</i><sub>33</sub>. 3280 . 3281Although the coefficient file is in little endian order, GeographicLib 3282can read it on big endian machines. It can only be read on machines 3283which store doubles in IEEE format. 3284 3285As an illustration, here is igrf11.wmm: 3286\verbatim 3287WMMF-1 3288# A World Magnetic Model (Format 1) file. For documentation on the 3289# format of this file see 3290# https://geographiclib.sourceforge.io/html/magnetic.html#magneticformat 3291Name igrf11 3292Description International Geomagnetic Reference Field 11th Generation 3293URL https://ngdc.noaa.gov/IAGA/vmod/igrf.html 3294Publisher National Oceanic and Atmospheric Administration 3295ReleaseDate 2009-12-15 3296DataCutOff 2009-10-01 3297ConversionDate 2011-11-04 3298DataVersion 1 3299Radius 6371200 3300NumModels 23 3301Epoch 1900 3302DeltaEpoch 5 3303MinTime 1900 3304MaxTime 2015 3305MinHeight -1000 3306MaxHeight 600000 3307 3308# The coefficients are stored in a file obtained by appending ".cof" to 3309# the name of this file. The coefficients were obtained from IGRF11.COF 3310# in the geomag70 distribution. 3311ID IGRF11-A 3312\endverbatim 3313 3314<center> 3315Back to \ref normalgravity. Forward to \ref geodesic. Up to \ref contents. 3316</center> 3317 3318**********************************************************************/ 3319/** 3320\page geodesic Geodesics on an ellipsoid of revolution 3321 3322<center> 3323Back to \ref magnetic. Forward to \ref nearest. Up to \ref contents. 3324</center> 3325 3326Geodesic and GeodesicLine provide accurate 3327solutions to the direct and inverse geodesic problems. The 3328<a href="GeodSolve.1.html">GeodSolve</a> utility provides an interface 3329to these classes. AzimuthalEquidistant implements the 3330azimuthal equidistant projection in terms of geodesics. 3331CassiniSoldner implements a transverse cylindrical 3332equidistant projection in terms of geodesics. The 3333<a href="GeodesicProj.1.html">GeodesicProj</a> utility provides an 3334interface to these projections. 3335 3336The algorithms used by Geodesic and GeodesicLine are based on a Taylor 3337expansion of the geodesic integrals valid when the flattening \e f is 3338small. GeodesicExact and GeodesicLineExact evaluate the integrals 3339exactly (in terms of incomplete elliptic integrals). For the WGS84 3340ellipsoid, the series solutions are about 2--3 times faster and 2--3 3341times more accurate (because it's easier to control round-off errors 3342with series solutions); thus Geodesic and GeodesicLine are recommended 3343for most geodetic applications. However, in applications where the 3344absolute value of \e f is greater than about 0.02, the exact classes 3345should be used. 3346 3347Go to 3348 - \ref testgeod 3349 - \ref geodseries 3350 - \ref geodellip 3351 - \ref meridian 3352 - \ref geodshort 3353 . 3354For some background information on geodesics on triaxial ellipsoids, see 3355\ref triaxial. 3356 3357References: 3358 - F. W. Bessel, 3359 <a href="https://doi.org/10.1002/asna.201011352">The calculation 3360 of longitude and latitude from geodesic measurements (1825)</a>, 3361 Astron. Nachr. 331(8), 852--861 (2010); 3362 translated by C. F. F. Karney and R. E. Deakin; preprint: 3363 <a href="https://arxiv.org/abs/0908.1824">arXiv:0908.1824</a>. 3364 - F. R. Helmert, 3365 <a href="https://doi.org/10.5281/zenodo.32050"> 3366 Mathematical and Physical Theories of Higher Geodesy, Part 1 (1880)</a>, 3367 Aeronautical Chart and Information Center (St. Louis, 1964), 3368 Chaps. 5--7. 3369 - J. Danielsen, 3370 The area under the geodesic, 3371 Survey Review 30(232), 61--66 (1989). 3372 DOI: <a href="https://doi.org/10.1179/003962689791474267"> 3373 10.1179/003962689791474267</a> 3374 - C. F. F. Karney, 3375 <a href="https://doi.org/10.1007/s00190-012-0578-z"> 3376 Algorithms for geodesics</a>, 3377 J. Geodesy 87(1), 43--55 (2013); 3378 DOI: <a href="https://doi.org/10.1007/s00190-012-0578-z"> 3379 10.1007/s00190-012-0578-z</a>; 3380 addenda: <a href="https://geographiclib.sourceforge.io/geod-addenda.html"> 3381 geod-addenda.html</a>; 3382 resource page: 3383 <a href="https://geographiclib.sourceforge.io/geod.html"> geod.html</a>. 3384 - A collection of some papers on geodesics is available at 3385 https://geographiclib.sourceforge.io/geodesic-papers/biblio.html 3386 - The wikipedia page, 3387 <a href="https://en.wikipedia.org/wiki/Geodesics_on_an_ellipsoid"> 3388 Geodesics on an ellipsoid</a>. 3389 3390\section testgeod Test data for geodesics 3391 3392A test set a geodesics is available at 3393 - <a href="https://sourceforge.net/projects/geographiclib/files/testdata/GeodTest.dat.gz"> 3394 GeodTest.dat.gz</a> 3395 - C. F. F. Karney, <i>Test set for geodesics</i> (2010), <br> 3396 DOI: <a href="https://doi.org/10.5281/zenodo.32156"> 3397 10.5281/zenodo.32156</a>. 3398 . 3399This is about 39 MB (compressed). This consists of a set of geodesics 3400for the WGS84 ellipsoid. A subset of this (consisting of 1/50 of the 3401members — about 690 kB, compressed) is available at 3402 - <a href="https://sourceforge.net/projects/geographiclib/files/testdata/GeodTest-short.dat.gz"> 3403 GeodTest-short.dat.gz</a> 3404 3405Each line of the test set gives 10 space delimited numbers 3406 - latitude at point 1, \e lat1 (degrees, exact) 3407 - longitude at point 1, \e lon1 (degrees, always 0) 3408 - azimuth at point 1, \e azi1 (clockwise from north in degrees, exact) 3409 - latitude at point 2, \e lat2 (degrees, accurate to 3410 10<sup>−18</sup> deg) 3411 - longitude at point 2, \e lon2 (degrees, accurate to 3412 10<sup>−18</sup> deg) 3413 - azimuth at point 2, \e azi2 (degrees, accurate to 3414 10<sup>−18</sup> deg) 3415 - geodesic distance from point 1 to point 2, \e s12 (meters, exact) 3416 - arc distance on the auxiliary sphere, \e a12 (degrees, accurate to 3417 10<sup>−18</sup> deg) 3418 - reduced length of the geodesic, \e m12 (meters, accurate to 0.1 pm) 3419 - the area under the geodesic, \e S12 (m<sup>2</sup>, accurate to 3420 1 mm<sup>2</sup>) 3421 . 3422These are computed using as direct geodesic calculations with the given 3423\e lat1, \e lon1, \e azi1, and \e s12. The distance \e s12 always 3424corresponds to an arc length \e a12 ≤ 180°, so the given 3425geodesics give the shortest paths from point 1 to point 2. For 3426simplicity and without loss of generality, \e lat1 is chosen in 3427[0°, 90°], \e lon1 is taken to be zero, \e azi1 is 3428chosen in [0°, 180°]. Furthermore, \e lat1 and \e 3429azi1 are taken to be multiples of 10<sup>−12</sup> deg and \e s12 3430is a multiple of 0.1 μm in [0 m, 20003931.4586254 m]. 3431This results in \e lon2 in [0°, 180°] and \e azi2 in [0°, 3432180°]. 3433 3434The direct calculation uses an expansion of the geodesic equations 3435accurate to <i>f</i><sup>30</sup> (approximately 1 part in 10<sup>50</sup>) 3436and is computed with with 3437<a href="https://en.wikipedia.org/wiki/Maxima_(software)">Maxima</a>'s 3438bfloats and fpprec set to 100 (so the errors in the data are probably 34391/2 of the values quoted above). 3440 3441The contents of the file are as follows: 3442 - 100000 entries randomly distributed 3443 - 50000 entries which are nearly antipodal 3444 - 50000 entries with short distances 3445 - 50000 entries with one end near a pole 3446 - 50000 entries with both ends near opposite poles 3447 - 50000 entries which are nearly meridional 3448 - 50000 entries which are nearly equatorial 3449 - 50000 entries running between vertices (\e azi1 = \e azi2 = 90°) 3450 - 50000 entries ending close to vertices 3451 . 3452(a total of 500000 entries). The values for \e s12 for the geodesics 3453running between vertices are truncated to a multiple of 0.1 pm and this 3454is used to determine point 2. 3455 3456This data can be fed to the <a href="GeodSolve.1.html">GeodSolve</a> 3457utility as follows 3458 - Direct from point 1: 3459\verbatim 3460 gunzip -c GeodTest.dat.gz | cut -d' ' -f1,2,3,7 | ./GeodSolve 3461\endverbatim 3462 This should yield columns 4, 5, 6, and 9 of the test set. 3463 - Direct from point 2: 3464\verbatim 3465 gunzip -c GeodTest.dat.gz | cut -d' ' -f4,5,6,7 | 3466 sed "s/ \([^ ]*$\)/ -\1/" | ./GeodSolve 3467\endverbatim 3468 (The sed command negates the distance.) This should yield columns 1, 3469 2, and 3, and the negative of column 9 of the test set. 3470 - Inverse between points 1 and 2: 3471\verbatim 3472 gunzip -c GeodTest.dat.gz | cut -d' ' -f1,2,4,5 | ./GeodSolve -i 3473\endverbatim 3474 This should yield columns 3, 6, 7, and 9 of the test set. 3475 . 3476Add, e.g., "-p 6", to the call to GeodSolve to change the precision of 3477the output. Adding "-f" causes GeodSolve to print 12 fields specifying 3478the geodesic; these include the 10 fields in the test set plus the 3479geodesic scales \e M12 and \e M21 which are inserted between \e m12 and 3480\e S12. 3481 3482Code for computing arbitrarily accurate geodesics in maxima is available 3483in <a href="geodesic.mac"> geodesic.mac</a> (this depends on 3484<a href="ellint.mac"> ellint.mac</a> and uses the series computed by 3485<a href="geod.mac"> geod.mac</a>). This solve both the direct and 3486inverse geodesic problems and offers the ability to solve the problems 3487either using series expansions (similar to Geodesic) or in terms of 3488elliptic integrals (similar to GeodesicExact). 3489 3490\section geodseries Expansions for geodesics 3491 3492We give here the series expansions for the various geodesic integrals 3493valid to order <i>f</i><sup>10</sup>. In this release of the code, we 3494use a 6th-order expansions. This is sufficient to maintain accuracy for 3495doubles for the SRMmax ellipsoid (\e a = 6400 km, \e f = 1/150). 3496However, the preprocessor macro GEOGRAPHICLIB_GEODESIC_ORDER can be used 3497to select an order from 3 thru 8. (If using long doubles, with a 64-bit 3498fraction, the default order is 7.) The series expanded to order 3499<i>f</i><sup>30</sup> are given in <a href="geodseries30.html"> 3500geodseries30.html</a>. 3501 3502In the formulas below ^ indicates exponentiation (<i>f</i>^3 = 3503<i>f</i><sup>3</sup>) and / indicates real division (3/5 = 0.6). The 3504equations need to be converted to Horner form, but are here left in 3505expanded form so that they can be easily truncated to lower order. 3506These expansions were obtained using the Maxima code, 3507<a href="geod.mac">geod.mac</a>. 3508 3509In the expansions below, we have 3510 - \f$ \alpha \f$ is the azimuth 3511 - \f$ \alpha_0 \f$ is the azimuth at the equator crossing 3512 - \f$ \lambda \f$ is the longitude measured from the equator crossing 3513 - \f$ \sigma \f$ is the spherical arc length 3514 - \f$ \omega = \tan^{-1}(\sin\alpha_0\tan\sigma) \f$ is the spherical longitude 3515 - \f$ a \f$ is the equatorial radius 3516 - \f$ b \f$ is the polar semi-axis 3517 - \f$ f \f$ is the flattening 3518 - \f$ e^2 = f(2 - f) \f$ 3519 - \f$ e'^2 = e^2/(1-e^2) \f$ 3520 - \f$ k^2 = e'^2 \cos^2\alpha_0 = 4 \epsilon / (1 - \epsilon)^2 \f$ 3521 - \f$ n = f / (2 - f) \f$ 3522 - \f$ c^2 = a^2/2 + b^2/2 (\tanh^{-1}e)/e \f$ 3523 - \e ep2 = \f$ e'^2 \f$ 3524 - \e k2 = \f$ k^2 \f$ 3525 - \e eps = \f$ \epsilon = k^2 / (\sqrt{1 + k^2} + 1)^2\f$ 3526 3527The formula for distance is 3528\f[ 3529 \frac sb = I_1(\sigma) 3530\f] 3531where 3532\f[ 3533\begin{align} 3534 I_1(\sigma) &= A_1\bigl(\sigma + B_1(\sigma)\bigr) \\ 3535 B_1(\sigma) &= \sum_{j=1} C_{1j} \sin 2j\sigma 3536\end{align} 3537\f] 3538and 3539\verbatim 3540A1 = (1 + 1/4 * eps^2 3541 + 1/64 * eps^4 3542 + 1/256 * eps^6 3543 + 25/16384 * eps^8 3544 + 49/65536 * eps^10) / (1 - eps); 3545\endverbatim 3546\verbatim 3547C1[1] = - 1/2 * eps 3548 + 3/16 * eps^3 3549 - 1/32 * eps^5 3550 + 19/2048 * eps^7 3551 - 3/4096 * eps^9; 3552C1[2] = - 1/16 * eps^2 3553 + 1/32 * eps^4 3554 - 9/2048 * eps^6 3555 + 7/4096 * eps^8 3556 + 1/65536 * eps^10; 3557C1[3] = - 1/48 * eps^3 3558 + 3/256 * eps^5 3559 - 3/2048 * eps^7 3560 + 17/24576 * eps^9; 3561C1[4] = - 5/512 * eps^4 3562 + 3/512 * eps^6 3563 - 11/16384 * eps^8 3564 + 3/8192 * eps^10; 3565C1[5] = - 7/1280 * eps^5 3566 + 7/2048 * eps^7 3567 - 3/8192 * eps^9; 3568C1[6] = - 7/2048 * eps^6 3569 + 9/4096 * eps^8 3570 - 117/524288 * eps^10; 3571C1[7] = - 33/14336 * eps^7 3572 + 99/65536 * eps^9; 3573C1[8] = - 429/262144 * eps^8 3574 + 143/131072 * eps^10; 3575C1[9] = - 715/589824 * eps^9; 3576C1[10] = - 2431/2621440 * eps^10; 3577\endverbatim 3578 3579The function \f$ \tau(\sigma) = s/(b A_1) = \sigma + B_1(\sigma) \f$ 3580may be inverted by series reversion giving 3581\f[ 3582 \sigma(\tau) = \tau + \sum_{j=1} C'_{1j} \sin 2j\sigma 3583\f] 3584where 3585\verbatim 3586C1'[1] = + 1/2 * eps 3587 - 9/32 * eps^3 3588 + 205/1536 * eps^5 3589 - 4879/73728 * eps^7 3590 + 9039/327680 * eps^9; 3591C1'[2] = + 5/16 * eps^2 3592 - 37/96 * eps^4 3593 + 1335/4096 * eps^6 3594 - 86171/368640 * eps^8 3595 + 4119073/28311552 * eps^10; 3596C1'[3] = + 29/96 * eps^3 3597 - 75/128 * eps^5 3598 + 2901/4096 * eps^7 3599 - 443327/655360 * eps^9; 3600C1'[4] = + 539/1536 * eps^4 3601 - 2391/2560 * eps^6 3602 + 1082857/737280 * eps^8 3603 - 2722891/1548288 * eps^10; 3604C1'[5] = + 3467/7680 * eps^5 3605 - 28223/18432 * eps^7 3606 + 1361343/458752 * eps^9; 3607C1'[6] = + 38081/61440 * eps^6 3608 - 733437/286720 * eps^8 3609 + 10820079/1835008 * eps^10; 3610C1'[7] = + 459485/516096 * eps^7 3611 - 709743/163840 * eps^9; 3612C1'[8] = + 109167851/82575360 * eps^8 3613 - 550835669/74317824 * eps^10; 3614C1'[9] = + 83141299/41287680 * eps^9; 3615C1'[10] = + 9303339907/2972712960 * eps^10; 3616\endverbatim 3617 3618The reduced length is given by 3619\f[ 3620\begin{align} 3621 \frac mb &= \sqrt{1 + k^2 \sin^2\sigma_2} \cos\sigma_1 \sin\sigma_2 \\ 3622 &\quad {}-\sqrt{1 + k^2 \sin^2\sigma_1} \sin\sigma_1 \cos\sigma_2 \\ 3623 &\quad {}-\cos\sigma_1 \cos\sigma_2 \bigl(J(\sigma_2) - J(\sigma_1)\bigr) 3624\end{align} 3625\f] 3626where 3627\f[ 3628\begin{align} 3629 J(\sigma) &= I_1(\sigma) - I_2(\sigma) \\ 3630 I_2(\sigma) &= A_2\bigl(\sigma + B_2(\sigma)\bigr) \\ 3631 B_2(\sigma) &= \sum_{j=1} C_{2j} \sin 2j\sigma 3632\end{align} 3633\f] 3634\verbatim 3635A2 = (1 - 3/4 * eps^2 3636 - 7/64 * eps^4 3637 - 11/256 * eps^6 3638 - 375/16384 * eps^8 3639 - 931/65536 * eps^10) / (1 + eps); 3640\endverbatim 3641\verbatim 3642C2[1] = + 1/2 * eps 3643 + 1/16 * eps^3 3644 + 1/32 * eps^5 3645 + 41/2048 * eps^7 3646 + 59/4096 * eps^9; 3647C2[2] = + 3/16 * eps^2 3648 + 1/32 * eps^4 3649 + 35/2048 * eps^6 3650 + 47/4096 * eps^8 3651 + 557/65536 * eps^10; 3652C2[3] = + 5/48 * eps^3 3653 + 5/256 * eps^5 3654 + 23/2048 * eps^7 3655 + 191/24576 * eps^9; 3656C2[4] = + 35/512 * eps^4 3657 + 7/512 * eps^6 3658 + 133/16384 * eps^8 3659 + 47/8192 * eps^10; 3660C2[5] = + 63/1280 * eps^5 3661 + 21/2048 * eps^7 3662 + 51/8192 * eps^9; 3663C2[6] = + 77/2048 * eps^6 3664 + 33/4096 * eps^8 3665 + 2607/524288 * eps^10; 3666C2[7] = + 429/14336 * eps^7 3667 + 429/65536 * eps^9; 3668C2[8] = + 6435/262144 * eps^8 3669 + 715/131072 * eps^10; 3670C2[9] = + 12155/589824 * eps^9; 3671C2[10] = + 46189/2621440 * eps^10; 3672\endverbatim 3673 3674The longitude is given in terms of the spherical longitude by 3675\f[ 3676\lambda = \omega - f \sin\alpha_0 I_3(\sigma) 3677\f] 3678where 3679\f[ 3680\begin{align} 3681 I_3(\sigma) &= A_3\bigl(\sigma + B_3(\sigma)\bigr) \\ 3682 B_3(\sigma) &= \sum_{j=1} C_{3j} \sin 2j\sigma 3683\end{align} 3684\f] 3685and 3686\verbatim 3687A3 = 1 - (1/2 - 1/2*n) * eps 3688 - (1/4 + 1/8*n - 3/8*n^2) * eps^2 3689 - (1/16 + 3/16*n + 1/16*n^2 - 5/16*n^3) * eps^3 3690 - (3/64 + 1/32*n + 5/32*n^2 + 5/128*n^3 - 35/128*n^4) * eps^4 3691 - (3/128 + 5/128*n + 5/256*n^2 + 35/256*n^3 + 7/256*n^4) * eps^5 3692 - (5/256 + 15/1024*n + 35/1024*n^2 + 7/512*n^3) * eps^6 3693 - (25/2048 + 35/2048*n + 21/2048*n^2) * eps^7 3694 - (175/16384 + 35/4096*n) * eps^8 3695 - 245/32768 * eps^9; 3696\endverbatim 3697\verbatim 3698C3[1] = + (1/4 - 1/4*n) * eps 3699 + (1/8 - 1/8*n^2) * eps^2 3700 + (3/64 + 3/64*n - 1/64*n^2 - 5/64*n^3) * eps^3 3701 + (5/128 + 1/64*n + 1/64*n^2 - 1/64*n^3 - 7/128*n^4) * eps^4 3702 + (3/128 + 11/512*n + 3/512*n^2 + 1/256*n^3 - 7/512*n^4) * eps^5 3703 + (21/1024 + 5/512*n + 13/1024*n^2 + 1/512*n^3) * eps^6 3704 + (243/16384 + 189/16384*n + 83/16384*n^2) * eps^7 3705 + (435/32768 + 109/16384*n) * eps^8 3706 + 345/32768 * eps^9; 3707C3[2] = + (1/16 - 3/32*n + 1/32*n^2) * eps^2 3708 + (3/64 - 1/32*n - 3/64*n^2 + 1/32*n^3) * eps^3 3709 + (3/128 + 1/128*n - 9/256*n^2 - 3/128*n^3 + 7/256*n^4) * eps^4 3710 + (5/256 + 1/256*n - 1/128*n^2 - 7/256*n^3 - 3/256*n^4) * eps^5 3711 + (27/2048 + 69/8192*n - 39/8192*n^2 - 47/4096*n^3) * eps^6 3712 + (187/16384 + 39/8192*n + 31/16384*n^2) * eps^7 3713 + (287/32768 + 47/8192*n) * eps^8 3714 + 255/32768 * eps^9; 3715C3[3] = + (5/192 - 3/64*n + 5/192*n^2 - 1/192*n^3) * eps^3 3716 + (3/128 - 5/192*n - 1/64*n^2 + 5/192*n^3 - 1/128*n^4) * eps^4 3717 + (7/512 - 1/384*n - 77/3072*n^2 + 5/3072*n^3 + 65/3072*n^4) * eps^5 3718 + (3/256 - 1/1024*n - 71/6144*n^2 - 47/3072*n^3) * eps^6 3719 + (139/16384 + 143/49152*n - 383/49152*n^2) * eps^7 3720 + (243/32768 + 95/49152*n) * eps^8 3721 + 581/98304 * eps^9; 3722C3[4] = + (7/512 - 7/256*n + 5/256*n^2 - 7/1024*n^3 + 1/1024*n^4) * eps^4 3723 + (7/512 - 5/256*n - 7/2048*n^2 + 9/512*n^3 - 21/2048*n^4) * eps^5 3724 + (9/1024 - 43/8192*n - 129/8192*n^2 + 39/4096*n^3) * eps^6 3725 + (127/16384 - 23/8192*n - 165/16384*n^2) * eps^7 3726 + (193/32768 + 3/8192*n) * eps^8 3727 + 171/32768 * eps^9; 3728C3[5] = + (21/2560 - 9/512*n + 15/1024*n^2 - 7/1024*n^3 + 9/5120*n^4) * eps^5 3729 + (9/1024 - 15/1024*n + 3/2048*n^2 + 57/5120*n^3) * eps^6 3730 + (99/16384 - 91/16384*n - 781/81920*n^2) * eps^7 3731 + (179/32768 - 55/16384*n) * eps^8 3732 + 141/32768 * eps^9; 3733C3[6] = + (11/2048 - 99/8192*n + 275/24576*n^2 - 77/12288*n^3) * eps^6 3734 + (99/16384 - 275/24576*n + 55/16384*n^2) * eps^7 3735 + (143/32768 - 253/49152*n) * eps^8 3736 + 33/8192 * eps^9; 3737C3[7] = + (429/114688 - 143/16384*n + 143/16384*n^2) * eps^7 3738 + (143/32768 - 143/16384*n) * eps^8 3739 + 429/131072 * eps^9; 3740C3[8] = + (715/262144 - 429/65536*n) * eps^8 3741 + 429/131072 * eps^9; 3742C3[9] = + 2431/1179648 * eps^9; 3743\endverbatim 3744 3745The formula for area between the geodesic and the equator is given in 3746Sec. 6 of <a href="https://doi.org/10.1007/s00190-012-0578-z"> 3747Algorithms for geodesics</a> in terms of \e S, 3748\f[ 3749S = c^2 \alpha + e^2 a^2 \cos\alpha_0 \sin\alpha_0 I_4(\sigma) 3750\f] 3751where 3752\f[ 3753I_4(\sigma) = \sum_{j=0} C_{4j} \cos(2j+1)\sigma 3754\f] 3755In the paper, this was expanded in \f$ e'^2 \f$ and \f$ k^2 \f$. 3756However, the series converges faster for eccentric ellipsoids if the 3757expansion is in \f$ n \f$ and \f$ \epsilon \f$. The series to order 3758\f$ f^{10} \f$ becomes 3759\verbatim 3760C4[0] = + (2/3 - 4/15*n + 8/105*n^2 + 4/315*n^3 + 16/3465*n^4 + 20/9009*n^5 + 8/6435*n^6 + 28/36465*n^7 + 32/62985*n^8 + 4/11305*n^9) 3761 - (1/5 - 16/35*n + 32/105*n^2 - 16/385*n^3 - 64/15015*n^4 - 16/15015*n^5 - 32/85085*n^6 - 112/692835*n^7 - 128/1616615*n^8) * eps 3762 - (2/105 + 32/315*n - 1088/3465*n^2 + 1184/5005*n^3 - 128/3465*n^4 - 3232/765765*n^5 - 1856/1616615*n^6 - 6304/14549535*n^7) * eps^2 3763 + (11/315 - 368/3465*n - 32/6435*n^2 + 976/4095*n^3 - 154048/765765*n^4 + 368/11115*n^5 + 5216/1322685*n^6) * eps^3 3764 + (4/1155 + 1088/45045*n - 128/1287*n^2 + 64/3927*n^3 + 2877184/14549535*n^4 - 370112/2078505*n^5) * eps^4 3765 + (97/15015 - 464/45045*n + 4192/153153*n^2 - 88240/969969*n^3 + 31168/1322685*n^4) * eps^5 3766 + (10/9009 + 4192/765765*n - 188096/14549535*n^2 + 23392/855855*n^3) * eps^6 3767 + (193/85085 - 6832/2078505*n + 106976/14549535*n^2) * eps^7 3768 + (632/1322685 + 3456/1616615*n) * eps^8 3769 + 107/101745 * eps^9; 3770C4[1] = + (1/45 - 16/315*n + 32/945*n^2 - 16/3465*n^3 - 64/135135*n^4 - 16/135135*n^5 - 32/765765*n^6 - 112/6235515*n^7 - 128/14549535*n^8) * eps 3771 - (2/105 - 64/945*n + 128/1485*n^2 - 1984/45045*n^3 + 256/45045*n^4 + 64/109395*n^5 + 128/855855*n^6 + 2368/43648605*n^7) * eps^2 3772 - (1/105 - 16/2079*n - 5792/135135*n^2 + 3568/45045*n^3 - 103744/2297295*n^4 + 264464/43648605*n^5 + 544/855855*n^6) * eps^3 3773 + (4/1155 - 2944/135135*n + 256/9009*n^2 + 17536/765765*n^3 - 3053056/43648605*n^4 + 1923968/43648605*n^5) * eps^4 3774 + (1/9009 + 16/19305*n - 2656/153153*n^2 + 65072/2078505*n^3 + 526912/43648605*n^4) * eps^5 3775 + (10/9009 - 1472/459459*n + 106112/43648605*n^2 - 204352/14549535*n^3) * eps^6 3776 + (349/2297295 + 28144/43648605*n - 32288/8729721*n^2) * eps^7 3777 + (632/1322685 - 44288/43648605*n) * eps^8 3778 + 43/479655 * eps^9; 3779C4[2] = + (4/525 - 32/1575*n + 64/3465*n^2 - 32/5005*n^3 + 128/225225*n^4 + 32/765765*n^5 + 64/8083075*n^6 + 32/14549535*n^7) * eps^2 3780 - (8/1575 - 128/5775*n + 256/6825*n^2 - 6784/225225*n^3 + 4608/425425*n^4 - 128/124355*n^5 - 5888/72747675*n^6) * eps^3 3781 - (8/1925 - 1856/225225*n - 128/17325*n^2 + 42176/1276275*n^3 - 2434816/72747675*n^4 + 195136/14549535*n^5) * eps^4 3782 + (8/10725 - 128/17325*n + 64256/3828825*n^2 - 128/25935*n^3 - 266752/10392525*n^4) * eps^5 3783 - (4/25025 + 928/3828825*n + 292288/72747675*n^2 - 106528/6613425*n^3) * eps^6 3784 + (464/1276275 - 17152/10392525*n + 83456/72747675*n^2) * eps^7 3785 + (1168/72747675 + 128/1865325*n) * eps^8 3786 + 208/1119195 * eps^9; 3787C4[3] = + (8/2205 - 256/24255*n + 512/45045*n^2 - 256/45045*n^3 + 1024/765765*n^4 - 256/2909907*n^5 - 512/101846745*n^6) * eps^3 3788 - (16/8085 - 1024/105105*n + 2048/105105*n^2 - 1024/51051*n^3 + 4096/373065*n^4 - 1024/357357*n^5) * eps^4 3789 - (136/63063 - 256/45045*n + 512/1072071*n^2 + 494336/33948915*n^3 - 44032/1996995*n^4) * eps^5 3790 + (64/315315 - 16384/5360355*n + 966656/101846745*n^2 - 868352/101846745*n^3) * eps^6 3791 - (16/97461 + 14848/101846745*n + 74752/101846745*n^2) * eps^7 3792 + (5024/33948915 - 96256/101846745*n) * eps^8 3793 - 1744/101846745 * eps^9; 3794C4[4] = + (64/31185 - 512/81081*n + 1024/135135*n^2 - 512/109395*n^3 + 2048/1247103*n^4 - 2560/8729721*n^5) * eps^4 3795 - (128/135135 - 2048/405405*n + 77824/6891885*n^2 - 198656/14549535*n^3 + 8192/855855*n^4) * eps^5 3796 - (512/405405 - 2048/530145*n + 299008/130945815*n^2 + 280576/43648605*n^3) * eps^6 3797 + (128/2297295 - 2048/1438965*n + 241664/43648605*n^2) * eps^7 3798 - (17536/130945815 + 1024/43648605*n) * eps^8 3799 + 2944/43648605 * eps^9; 3800C4[5] = + (128/99099 - 2048/495495*n + 4096/765765*n^2 - 6144/1616615*n^3 + 8192/4849845*n^4) * eps^5 3801 - (256/495495 - 8192/2807805*n + 376832/53348295*n^2 - 8192/855855*n^3) * eps^6 3802 - (6784/8423415 - 432128/160044885*n + 397312/160044885*n^2) * eps^7 3803 + (512/53348295 - 16384/22863555*n) * eps^8 3804 - 16768/160044885 * eps^9; 3805C4[6] = + (512/585585 - 4096/1422135*n + 8192/2078505*n^2 - 4096/1322685*n^3) * eps^6 3806 - (1024/3318315 - 16384/9006855*n + 98304/21015995*n^2) * eps^7 3807 - (103424/189143955 - 8192/4203199*n) * eps^8 3808 - 1024/189143955 * eps^9; 3809C4[7] = + (1024/1640925 - 65536/31177575*n + 131072/43648605*n^2) * eps^7 3810 - (2048/10392525 - 262144/218243025*n) * eps^8 3811 - 84992/218243025 * eps^9; 3812C4[8] = + (16384/35334585 - 131072/82447365*n) * eps^8 3813 - 32768/247342095 * eps^9; 3814C4[9] = + 32768/92147055 * eps^9; 3815\endverbatim 3816 3817\section geodellip Geodesics in terms of elliptic integrals 3818 3819GeodesicExact and GeodesicLineExact solve the geodesic problem using 3820elliptic integrals. The formulation of geodesic in terms of incomplete 3821elliptic integrals is given in 3822 - C. F. F. Karney, 3823 <a href="https://arxiv.org/abs/1102.1215v1">Geodesics 3824 on an ellipsoid of revolution</a>, 3825 Feb. 2011; preprint 3826 <a href="https://arxiv.org/abs/1102.1215v1">arxiv:1102.1215v1</a>. 3827 . 3828It is most convenient to use the form derived for a prolate ellipsoid in 3829Appendix D. For an oblate ellipsoid this results in elliptic integrals 3830with an imaginary modulus. However, the integrals themselves are real 3831and the algorithms used to compute the elliptic integrals handles the 3832case of an imaginary modulus using real arithmetic. 3833 3834The key relations used by GeographicLib are 3835\f[ 3836 \begin{align} 3837 \frac sb &= E(\sigma, ik), \\ 3838 \lambda &= (1 - f) \sin\alpha_0 G(\sigma, \cos^2\alpha_0, ik) \\ 3839 &= \chi 3840 - \frac{e'^2}{\sqrt{1+e'^2}}\sin\alpha_0 H(\sigma, -e'^2, ik), \\ 3841 J(\sigma) &= k^2 D(\sigma, ik), 3842 \end{align} 3843\f] 3844where \f$ \chi \f$ is a modified spherical longitude given by 3845\f[ 3846\tan\chi = \sqrt{\frac{1+e'^2}{1+k^2\sin^2\sigma}}\tan\omega, 3847\f] 3848and 3849\f[ 3850 \begin{align} 3851 D(\phi,k) &= \int_0^\phi 3852 \frac{\sin^2\theta}{\sqrt{1 - k^2\sin^2\theta}}\,d\theta\\ 3853 &=\frac{F(\phi, k) - E(\phi, k)}{k^2},\\ 3854 G(\phi,\alpha^2,k) &= \int_0^\phi 3855 \frac{\sqrt{1 - k^2\sin^2\theta}}{1 - \alpha^2\sin^2\theta}\,d\theta\\ 3856 &=\frac{k^2}{\alpha^2}F(\phi, k) 3857 +\biggl(1-\frac{k^2}{\alpha^2}\biggr)\Pi(\phi, \alpha^2, k),\\ 3858 H(\phi, \alpha^2, k) 3859 &= \int_0^\phi 3860 \frac{\cos^2\theta}{(1-\alpha^2\sin^2\theta)\sqrt{1-k^2\sin^2\theta}} 3861 \,d\theta \\ 3862 &= 3863 \frac1{\alpha^2} F(\phi, k) + 3864 \biggl(1 - \frac1{\alpha^2}\biggr) \Pi(\phi, \alpha^2, k), 3865 \end{align} 3866\f] 3867and \f$F(\phi, k)\f$, \f$E(\phi, k)\f$, \f$D(\phi, k)\f$, and 3868\f$\Pi(\phi, \alpha^2, k)\f$, are incomplete elliptic integrals (see 3869https://dlmf.nist.gov/19.2.ii). The formula for \f$ s \f$ and the 3870first expression for \f$ \lambda \f$ are given by Legendre (1811) and 3871are the most common representation of geodesics in terms of elliptic 3872integrals. The second (equivalent) expression for \f$ \lambda \f$, 3873which was given by Cayley (1870), is useful in that the elliptic 3874integral is relegated to a small correction term. This form allows 3875the longitude to be computed more accurately and is used in 3876GeographicLib. (The equivalence of the two expressions for \f$ 3877\lambda \f$ follows from https://dlmf.nist.gov/19.7.E8.) 3878 3879Nominally, GeodesicExact and GeodesicLineExact will give "exact" results 3880for any value of the flattening. However, the geographic latitude is a 3881distorted measure of distance from the equator with very eccentric 3882ellipsoids and this introducing an irreducible representational error in 3883the algorithms in this case. It is therefore recommended to restrict 3884the use of these classes to <i>b</i>/\e a ∈ [0.01, 100] or \e f 3885∈ [−99, 0.99]. Note that GeodesicExact still uses a series 3886expansion for the area \e S12. However the series is taken out to 30th 3887order and gives accurate results for <i>b</i>/\e a ∈ [1/2, 2]; the 3888accuracy is about 8 decimal digits for <i>b</i>/\e a ∈ [1/4, 4]. 3889Additional work planned for this aspect of the geodesic problem: 3890- formulate the area integral \e S12 in terms of elliptic integrals; 3891- generate accurate test geodesics for highly eccentric ellipsoids so 3892 that the roundoff errors can be quantified. 3893 3894Thomas (1952) and Rollins (2010) use a different independent variable 3895for geodesics, \f$\theta\f$ instead of \f$\sigma\f$, where \f$ 3896\tan\theta = \sqrt{1 + k^2} \tan\sigma \f$. The corresponding 3897expressions for \f$ s \f$ and \f$ \lambda \f$ are given here for 3898completeness: 3899\f[ 3900\begin{align} 3901\frac sb &= \sqrt{1-k'^2} \Pi(\theta, k'^2, k'), \\ 3902\lambda &= (1-f) \sqrt{1-k'^2} \sin\alpha_0 \Pi(\theta, k'^2/e^2, k'), 3903\end{align} 3904\f] 3905where \f$ k' = k/\sqrt{1 + k^2} \f$. The expression for \f$ s \f$ 3906can be written in terms of elliptic integrals of the second kind and 3907Cayley's technique can be used to subtract out the leading order 3908behavior of \f$ \lambda \f$ to give 3909\f[ 3910\begin{align} 3911\frac sb &=\frac1{\sqrt{1-k'^2}} 3912 \biggl( E(\theta, k') - 3913 \frac{k'^2 \sin\theta \cos\theta}{\sqrt{1-k'^2\sin^2\theta}} \biggr), \\ 3914\lambda &= \psi + (1-f) \sqrt{1-k'^2} \sin\alpha_0 3915\bigl( F(\theta, k') - \Pi(\theta, e^2, k') \bigr), 3916\end{align} 3917\f] 3918where 3919\f[ 3920\begin{align} 3921\tan\psi &= \sqrt{\frac{1+k^2\sin^2\sigma}{1+e'^2}}\tan\omega \\ 3922 &= \sqrt{\frac{1-e^2}{1+k^2\cos^2\theta}}\sin\alpha_0\tan\theta. 3923\end{align} 3924\f] 3925The tangents of the three "longitude-like" angles are in geometric 3926progression, \f$ \tan\chi/\tan\omega = \tan\omega/\tan\psi \f$. 3927 3928\section meridian Parameters for the meridian 3929 3930The formulas for \f$ s \f$ given in the previous section are the same as 3931those for the distance along a meridian for an ellipsoid with equatorial 3932radius \f$ a \sqrt{1 - e^2 \sin^2\alpha_0} \f$ and polar semi-axis \f$ b 3933\f$. Here is a list of possible ways of expressing the meridian 3934distance in terms of elliptic integrals using the notation: 3935- \f$ a \f$, equatorial axis, 3936- \f$ b \f$, polar axis, 3937- \f$ e = \sqrt{(a^2 - b^2)/a^2} \f$, eccentricity, 3938- \f$ e' = \sqrt{(a^2 - b^2)/b^2} \f$, second eccentricity, 3939- \f$ \phi = \mathrm{am}(u, e) \f$, the geographic latitude, 3940- \f$ \phi' = \mathrm{am}(v', ie') = \pi/2 - \phi \f$, 3941 the geographic colatitude, 3942- \f$ \beta = \mathrm{am}(v, ie') \f$, the parametric latitude 3943 (\f$ \tan^2\beta = (1 - e^2) \tan^2\phi \f$), 3944- \f$ \beta' = \mathrm{am}(u', e) = \pi/2 - \beta \f$, 3945 the parametric colatitude, 3946- \f$ M \f$, the length of a quarter meridian (equator to pole), 3947- \f$ y \f$, the distance along the meridian (measured from the equator). 3948- \f$ y' = M -y \f$, the distance along the meridian (measured from the pole). 3949. 3950The eccentricities \f$ (e, e') \f$ are real (resp. imaginary) for 3951oblate (resp. prolate) ellipsoids. The elliptic variables \f$(u, 3952u')\f$ and \f$(v, v')\f$ are defined by 3953- \f$ u = F(\phi, e) ,\quad u' = F(\beta', e) \f$ 3954- \f$ v = F(\beta, ie') ,\quad v' = F(\phi', ie') \f$, 3955. 3956and are linearly related by 3957- \f$ u + u' = K(e) ,\quad v + v' = K(ie') \f$ 3958- \f$ v = \sqrt{1-e^2} u ,\quad u = \sqrt{1+e'^2} v \f$. 3959. 3960The cartesian coordinates for the meridian \f$ (x, z) \f$ are given by 3961\f[ 3962\begin{align} 3963 x &= a \cos\beta = a \cos\phi / \sqrt{1 - e^2 \sin^2\phi} \\ 3964 &= a \sin\beta' = (a^2/b) \sin\phi' / \sqrt{1 + e'^2 \sin^2\phi'} \\ 3965 &= a \,\mathrm{cn}(v, ie) = a \,\mathrm{cd}(u, e) \\ 3966 &= a \,\mathrm{sn}(u', e) = (a^2/b) \,\mathrm{sd}(v', ie'), 3967\end{align} 3968\f] 3969\f[ 3970\begin{align} 3971 z &= b \sin\beta = (b^2/a) \sin\phi / \sqrt{1 - e^2 \sin^2\phi} \\ 3972 &= b \cos\beta' = b \cos\phi' / \sqrt{1 + e'^2 \sin^2\phi'} \\ 3973 &= b \,\mathrm{sn}(v, ie) = (b^2/a) \,\mathrm{sd}(u, e) \\ 3974 &= b \,\mathrm{cn}(u', e) = b \,\mathrm{cd}(v', ie'). 3975\end{align} 3976\f] 3977The distance along the meridian can be expressed variously as 3978\f[ 3979\begin{align} 3980 y &= b \int \sqrt{1 + e'^2 \sin^2\beta}\, d\beta 3981 = b E(\beta, ie') \\ 3982 &= \frac{b^2}a \int \frac1{(1 - e^2 \sin^2\phi)^{3/2}}\, d\phi 3983 = \frac{b^2}a \Pi(\phi, e^2, e) \\ 3984 &= a \biggl(E(\phi, e) - 3985 \frac{e^2\sin\phi \cos\phi}{\sqrt{1 - e^2\sin^2\phi}}\biggr) \\ 3986 &= b \int \mathrm{dn}^2(v, ie')\, dv 3987 = \frac{b^2}a \int \mathrm{nd}^2(u, e)\, du 3988 = \cal E(v, ie'), 3989\end{align} 3990\f] 3991\f[ 3992\begin{align} 3993 y' &= a \int \sqrt{1 - e^2 \sin^2\beta'}\, d\beta' 3994 = a E(\beta', e) \\ 3995 &= \frac{a^2}b \int \frac1{(1 + e'^2 \sin^2\phi')^{3/2}}\, d\phi' 3996 = \frac{a^2}b \Pi(\phi', -e'^2, ie') \\ 3997 &= b \biggl(E(\phi', ie') + 3998 \frac{e'^2\sin\phi' \cos\phi'}{\sqrt{1 + e'^2\sin^2\phi'}}\biggr) \\ 3999 &= a \int \mathrm{dn}^2(u', e)\, du' 4000 = \frac{a^2}b \int \mathrm{nd}^2(v', ie')\, dv' 4001 = \cal E(u', e), 4002\end{align} 4003\f] 4004with the quarter meridian distance given by 4005\f[ 4006 M = aE(e) = bE(ie') = (b^2/a)\Pi(e^2,e) = (a^2/b)\Pi(-e'^2,ie'). 4007\f] 4008(Here \f$ E, F, \Pi \f$ are elliptic integrals defined in 4009https://dlmf.nist.gov/19.2.ii. \f$ \cal E, \mathrm{am}, \mathrm{sn}, 4010\mathrm{cn}, \mathrm{sd}, \mathrm{cd}, \mathrm{dn}, \mathrm{nd} \f$ are 4011Jacobi elliptic functions defined in https://dlmf.nist.gov/22.2 and 4012https://dlmf.nist.gov/22.16.) 4013 4014There are several considerations in the choice of independent variable 4015for evaluate the meridian distance 4016- The use of an imaginary modulus (namely, \f$ ie' \f$, above) is of no 4017 practical concern. The integrals are real in this case and modern 4018 methods (GeographicLib uses the method given in 4019 https://dlmf.nist.gov/19.36.i) for computing integrals handles this 4020 case using just real arithmetic. 4021- If the "natural" origin is the equator, choose one of \f$ \phi, \beta, 4022 u, v \f$ (this might be preferred in geodesy). If it's the pole, 4023 choose one of the complementary quantities \f$ \phi', \beta', u', v' 4024 \f$ (this might be preferred by mathematicians). 4025- Applying these formulas to the geodesic problems, \f$ \beta \f$ 4026 becomes the arc length, \f$ \sigma \f$, on the auxiliary sphere. This 4027 is the traditional method of solution used by Legendre (1806), Oriani 4028 (1806), Bessel (1825), Helmert (1880), Rainsford (1955), Thomas 4029 (1970), Vincenty (1975), Rapp (1993), and so on. Many of the 4030 solutions in terms of elliptic functions use one of the elliptic 4031 variables (\f$ u \f$ or \f$ v \f$), see, for example, Jacobi (1855), 4032 Halphen (1888), Forsyth (1896). In the context of geodesics \f$ 4033 \phi \f$ becomes Thomas' variable \f$ \theta \f$; this is used by 4034 Thomas (1952) and Rollins (2010) in their formulation of the 4035 geodesic problem (see the previous section). 4036- For highly eccentric ellipsoids the variation of the meridian with 4037 respect to \f$ \beta \f$ is considerably "better behaved" than other 4038 choices (see the figure below). The choice of \f$ \phi \f$ is 4039 probably a poor one in this case. 4040. 4041GeographicLib uses the geodesic generalization of 4042\f$ y = b E(\beta, ie') \f$, namely \f$ s = b E(\sigma, ik) \f$. See 4043\ref geodellip. 4044 4045\image html meridian-measures.png "Comparison of meridian measures" 4046 4047\section geodshort Short geodesics 4048 4049Here we describe Bowring's method for solving the inverse geodesic 4050problem in the limit of short geodesics and contrast it with the great 4051circle solution using Bessel's auxiliary sphere. References: 4052 - B. R. Bowring, The Direct and Inverse Problems for Short Geodesic 4053 Lines on the Ellipsoid, Surveying and Mapping 41(2), 135--141 (1981). 4054 - R. H. Rapp, 4055 <a href="https://hdl.handle.net/1811/24333"> 4056 Geometric Geodesy, Part I</a>, Ohio State Univ. (1991), Sec. 6.5. 4057 4058Bowring considers the conformal mapping of the ellipsoid to a sphere of 4059radius \f$ R \f$ such that circles of latitude and meridians are 4060preserved (and hence the azimuth of a line is preserved). Let \f$ 4061(\phi, \lambda) \f$ and \f$ (\phi', \lambda') \f$ be the latitude and 4062longitude on the ellipsoid and sphere respectively. Define isometric 4063latitudes for the sphere and the ellipsoid as 4064\f[ 4065\begin{align} 4066 \psi' &= \sinh^{-1} \tan \phi', \\ 4067 \psi &= \sinh^{-1} \tan \phi - e \tanh^{-1}(e \sin\phi). 4068\end{align} 4069\f] 4070The most general conformal mapping satisfying Bowring's conditions is 4071\f[ 4072\psi' = A \psi + K, \quad \lambda' = A \lambda, 4073\f] 4074where \f$ A \f$ and \f$ K \f$ are constants. (In fact a constant can be 4075added to the equation for \f$ \lambda' \f$, but this does affect the 4076analysis.) The scale of this mapping is 4077\f[ 4078m(\phi) = \frac{AR}{\nu}\frac{\cos\phi'}{\cos\phi}, 4079\f] 4080where \f$ \nu = a/\sqrt{1 - e^2\sin^2\phi} \f$ is the transverse radius 4081of curvature. (Note that in Bowring's Eq. (10), \f$ \phi \f$ should be 4082replaced by \f$ \phi' \f$.) The mapping from the ellipsoid to the sphere 4083depends on three parameters \f$ R, A, K \f$. These will be selected to 4084satisfy certain conditions at some representative latitude \f$ \phi_0 4085\f$. Two possible choices are given below. 4086 4087\subsection bowring Bowring's method 4088 4089Bowring (1981) requires that 4090\f[ 4091m(\phi_0) = 1,\quad 4092\left.\frac{dm(\phi)}{d\phi}\right|_{\phi=\phi_0} = 0,\quad 4093\left.\frac{d^2m(\phi)}{d\phi^2}\right|_{\phi=\phi_0} = 0, 4094\f] 4095i.e, \f$m\approx 1\f$ in the vicinity of \f$\phi = \phi_0\f$. 4096This gives 4097\f[ 4098\begin{align} 4099R &= \frac{\sqrt{1 + e'^2}}{B^2} a, \\ 4100A &= \sqrt{1 + e'^2 \cos^4\phi_0}, \\ 4101\tan\phi'_0 &= \frac1B \tan\phi_0, 4102\end{align} 4103\f] 4104where \f$ e' = e/\sqrt{1-e^2} \f$ is the second eccentricity, \f$ B = 4105\sqrt{1+e'^2\cos^2\phi_0} \f$, and \f$ K \f$ is defined implicitly by 4106the equation for \f$\phi'_0\f$. The radius \f$ R \f$ is the (Gaussian) 4107mean radius of curvature of the ellipsoid at \f$\phi_0\f$ (so near 4108\f$\phi_0\f$ the ellipsoid can be deformed to fit the sphere snugly). 4109The third derivative of \f$ m \f$ is given by 4110\f[ 4111\left.\frac{d^3m(\phi)}{d\phi^3}\right|_{\phi=\phi_0} = 4112\frac{-2e'^2\sin2\phi_0}{B^4}. 4113\f] 4114 4115The method for solving the inverse problem between two nearby points \f$ 4116(\phi_1, \lambda_1) \f$ and \f$ (\phi_2, \lambda_2) \f$ is as follows: 4117Set \f$\phi_0 = (\phi_1 + \phi_2)/2\f$. Compute \f$ R, A, \phi'_0 \f$, 4118and hence find \f$ (\phi'_1, \lambda'_1) \f$ and \f$ (\phi'_2, 4119\lambda'_2) \f$. Finally, solve for the great circle on a sphere of 4120radius \f$ R \f$; the resulting distance and azimuths are good 4121approximations for the corresponding quantities for the ellipsoidal 4122geodesic. 4123 4124Consistent with the accuracy of this method, we can compute 4125\f$\phi'_1\f$ and \f$\phi'_2\f$ using a Taylor expansion about 4126\f$\phi_0\f$. This also avoids numerical errors that arise from 4127subtracting nearly equal quantities when using the equation for 4128\f$\phi'\f$ directly. Write \f$\Delta \phi = \phi - \phi_0\f$ and 4129\f$\Delta \phi' = \phi' - \phi'_0\f$; then we have 4130\f[ 4131\Delta\phi' \approx 4132\frac{\Delta\phi}B \biggl[1 + 4133\frac{\Delta\phi}{B^2}\frac{e'^2}2 4134 \biggl(3\sin\phi_0\cos\phi_0 + 4135 \frac{\Delta\phi}{B^2} 4136 \bigl(B^2 - \sin^2\phi_0(2 - 3 e'^2 \cos^2\phi_0)\bigr)\biggr)\biggr], 4137\f] 4138where the error is \f$O(f\Delta\phi^4)\f$. 4139This is essentially Bowring's method. Significant differences between 4140this result, "Bowring (improved)", compared to Bowring's paper, "Bowring 4141(original)", are: 4142 - Bowring elects to use \f$\phi_0 = \phi_1\f$. This simplifies the 4143 calculations somewhat but increases the error by about a factor of 4144 4. 4145 - Bowring's expression for \f$ \Delta\phi' \f$ is only accurate in the 4146 limit \f$ e' \rightarrow 0 \f$. 4147 . 4148In fact, arguably, the highest order \f$O(f\Delta\phi^3)\f$ terms should 4149be dropped altogether. Their inclusion does result in a better estimate 4150for the distance. However, if your goal is to generate both accurate 4151distances \e and accurate azimuths, then \f$\Delta\phi\f$ needs to be 4152restricted sufficiently to allow these terms to be dropped to give the 4153"Bowring (truncated)" method. 4154 4155With highly eccentric ellipsoids, the parametric latitude \f$ \beta \f$ 4156is a better behaved independent variable to use. In this case, \f$ 4157\phi_0 \f$ is naturally defined using \f$\beta_0 = (\beta_1 + 4158\beta_2)/2\f$ and in terms of \f$\Delta\beta = \beta - \beta_0\f$, we 4159have 4160\f[ 4161\Delta\phi' \approx 4162\frac{\Delta\beta}{B'} \biggl[1 + 4163\frac{\Delta\beta}{B'^2}\frac{e'^2}2 4164 \biggl(\sin\beta_0\cos\beta_0 + 4165 \frac{\Delta\beta}{3B'^2} 4166 \bigl( \cos^2\beta_0 - \sin^2\beta_0 B'^2\bigr) 4167\biggr)\biggr], 4168\f] 4169where \f$B' = \sqrt{1+e'^2\sin^2\beta_0} = \sqrt{1+e'^2}/B\f$, and the 4170error once again is \f$O(f\Delta\phi^4)\f$. This is the "Bowring 4171(using \f$\beta\f$)" method. 4172 4173\subsection auxsphere Bessel's auxiliary sphere 4174 4175GeographicLib's uses the auxiliary sphere method of Legendre, Bessel, 4176and Helmert. For short geodesics, this is equivalent to picking 4177\f$ R, A, K \f$ so that 4178\f[ 4179m(\phi_0) = 1,\quad 4180\left.\frac{dm(\phi)}{d\phi}\right|_{\phi=\phi_0} = 0,\quad 4181\tan\phi'_0 = (1 - f) \tan\phi_0. 4182\f] 4183Bowring's requirement that the second derivative of \f$m\f$ vanish has 4184been replaced by the last relation which states that \f$\phi'_0 = 4185\beta_0\f$, the parametric latitude corresponding to \f$\phi_0\f$. This 4186gives 4187\f[ 4188\begin{align} 4189R &= B'(1-f)a, \\ 4190A &= \frac1{B'(1-f)}, \\ 4191\left.\frac{d^2m(\phi)}{d\phi^2}\right|_{\phi=\phi_0} &= 4192-e^2B'^2\sin^2\phi_0. 4193\end{align} 4194\f] 4195 4196Similar to Bowring's method, we can compute \f$\phi'_1\f$ and 4197\f$\phi'_2\f$ using a Taylor expansion about \f$\beta_0\f$. This results 4198in the simple expression 4199\f[ 4200\Delta\phi' \approx \Delta\beta, 4201\f] 4202where the error is \f$O(f\Delta\beta^2)\f$. 4203 4204\subsection shorterr Estimating the accuracy 4205 4206In assessing the accuracy of these methods we use two metrics: 4207 - The absolute error in the distance. 4208 - The consistency of the predicted azimuths. Imagine starting 4209 ellipsoidal geodesics at \f$ (\phi_1, \lambda_1) \f$ and \f$ (\phi_2, 4210 \lambda_2) \f$ with the predicted azimuths. What is the distance 4211 between them when they are extended a distance \f$ a \f$ beyond the 4212 second point? 4213 . 4214(The second metric is much more stringent.) We may now compare the 4215methods by asking for a bound to the length of a geodesic which ensures 4216that the one or other of the errors fall below 1 mm (an "engineering" 4217definition of accurate) or 1 nm (1 nanometer, about the round-off 4218limit). 4219 4220<center> 4221<table> 4222<caption>Maximum distance that can be used in various methods for 4223computing short geodesics while keeping the errors within prescribed 4224bounds</caption> 4225<tr> 4226 <th rowspan="2">method 4227 <th colspan="2"><center>distance metric</center></th> 4228 <th colspan="2"><center>azimuth metric</center></th> 4229<tr> 4230 <th>1 mm error</th> 4231 <th>1 nm error</th> 4232 <th>1 mm error</th> 4233 <th>1 nm error</th> 4234<tr> 4235 <td>Bowring (original) 4236 <td><center>87 km</center> 4237 <td><center>870 m</center> 4238 <td><center>35 km</center> 4239 <td><center>350 m</center> 4240<tr> 4241 <td>Bowring (improved) 4242 <td><center>180 km</center> 4243 <td><center>1.8 km</center> 4244 <td><center>58 km</center> 4245 <td><center>580 m</center> 4246<tr> 4247 <td>Bowring (truncated) 4248 <td><center>52 km</center> 4249 <td><center>520 m</center> 4250 <td><center>52 km</center> 4251 <td><center>520 m</center> 4252<tr> 4253 <td>Bowring (using \f$\beta\f$) 4254 <td><center>380 km</center> 4255 <td><center>24 km</center> 4256 <td><center>60 km</center> 4257 <td><center>600 m</center> 4258<tr> 4259 <td>Bessel's aux. sphere 4260 <td><center>42 km</center> 4261 <td><center>420 m</center> 4262 <td><center>1.7 km</center> 4263 <td><center>1.7 m</center> 4264</table> 4265</center> 4266 4267For example, if you're only interested in measuring distances and an 4268accuracy of 1 mm is sufficient, then Bowring's improved method can 4269be used for distances up to 180 km. On the other hand, 4270GeographicLib uses Bessel's auxiliary sphere and we require both the 4271distance and the azimuth to be accurate, so the great circle 4272approximation can only be used for distances less than 1.7 m. The 4273reason that GeographicLib does not use Bowring's method is that the 4274information necessary for auxiliary sphere method is already available 4275as part of the general solution and, as much as possible, we allow all 4276geodesics to be computed by the general method. 4277 4278<center> 4279Back to \ref magnetic. Forward to \ref nearest. Up to \ref contents. 4280</center> 4281 4282**********************************************************************/ 4283/** 4284\page nearest Finding nearest neighbors 4285 4286<center> 4287Back to \ref geodesic. Forward to \ref triaxial. Up to \ref contents. 4288</center> 4289 4290The problem of finding the maritime boundary defined by the "median 4291line" is discussed in Section 14 of 4292 - C. F. F. Karney, 4293 <a href="https://arxiv.org/abs/1102.1215v1">Geodesics 4294 on an ellipsoid of revolution</a>, 4295 Feb. 2011; preprint 4296 <a href="https://arxiv.org/abs/1102.1215v1">arxiv:1102.1215v1</a>. 4297 . 4298Figure 14 shows the median line which is equidistant from Britain and 4299mainland Europe. Determining the median line involves finding, for any 4300given \e P, the closest points on the coast of Britain and on the coast 4301of mainland Europe. The operation of finding the closest in a set of 4302points is usually referred to as the <i>nearest neighbor</i> problem and 4303the NearestNeighbor class implements an efficient algorithm for solving 4304it. 4305 4306The NearestNeighbor class implements nearest-neighbor calculations using 4307the vantage-point tree described by 4308- J. K. Uhlmann, 4309 <a href="https://doi.org/10.1016/0020-0190(91)90074-r"> 4310 Satisfying general proximity/similarity queries with metric trees</a>, 4311 Information Processing Letters 40 175--179 (1991). 4312- P. N. Yianilos, 4313 <a href="http://pnylab.com/pny/papers/vptree/vptree/"> 4314 Data structures and algorithms for nearest neighbor search in general 4315 metric spaces</a>, Proc. 4th ACM-SIAM Symposium on Discrete Algorithms, 4316 (SIAM, 1993). pp. 311--321. 4317 4318Given a set of points \e x, \e y, \e z, …, in some space and a 4319distance function \e d satisfying the metric conditions, 4320\f[ 4321\begin{align} 4322 d(x,y) &\ge 0,\\ 4323 d(x,y) &= 0, \ \text{iff $x = y$},\\ 4324 d(x,y) &= d(y,x),\\ 4325 d(x,z) &\le d(x,y) + d(y,z), 4326\end{align} 4327\f] 4328the vantage-point (VP) tree provides an efficient way of determining 4329nearest neighbors. The geodesic distance (implemented by the Geodesic 4330class) satisfies these metric conditions, while the great ellipse 4331distance and the rhumb line distance <i>do not</i> (they do not satisfy 4332the last condition, the triangle inequality). Typically the cost of 4333constructing a VP tree of \e N points is \e N log \e N, while the cost 4334of a query is log \e N. Thus a VP tree should be used in situations 4335where \e N is large and at least log \e N queries are to be made. The 4336condition, \e N is large, means that \f$ N \gg 2^D \f$, where \e D is 4337the dimensionality of the space. 4338 4339- This implementation includes Yianilos' upper and lower bounds for the 4340 inside and outside sets. This helps limit the number of searches 4341 (compared to just using the median distance). 4342- Rather than do a depth-first or breath-first search on the tree, the 4343 nodes to be processed are put on a priority queue with the nodes most 4344 likely to contain close points processed first. Frequently, this allows 4345 nodes lower down on the priority queue to be skipped. 4346- This technique also allows non-exhaustive searchs to be performed (to 4347 answer questions such as "are there any points within 1km of the query 4348 point?). 4349- When building the tree, the first vantage point is (arbitrarily) 4350 chosen as the middle element of the set. Thereafter, the points 4351 furthest from the parent vantage point in both the inside and outside 4352 sets are selected as the children's vantage points. This information 4353 is already available from the computation of the upper and lower 4354 bounds of the children. This choice seems to lead to a reasonably 4355 optimized tree. 4356- The leaf nodes can contain a bucket of points (instead of just a vantage 4357 point). 4358- Coincident points are allowed in the set; these are treated as distinct 4359 points. 4360 4361The figure below shows the construction of the VP tree for the points 4362making up the coastlines of Britain and Ireland (about 5000 points shown 4363in blue). The set of points is recursively split into 2 equal "inside" 4364and "outside" subsets based on the distance from a "vantage point". The 4365boundaries between the inside and outside sets are shown as green 4366circular arcs (arcs of geodesic circles). At each stage, the newly 4367added vantage points are shown as red dots and the vantage points for 4368the next stage are shown as red plus signs. The data is shown in the 4369Cassini-Soldner projection with a central meridian of 5°W. 4370 4371\image html vptree.gif "Vantage-point tree" 4372 4373<center> 4374Back to \ref geodesic. Forward to \ref triaxial. Up to \ref contents. 4375</center> 4376 4377**********************************************************************/ 4378/** 4379\page triaxial Geodesics on a triaxial ellipsoid 4380 4381<center> 4382Back to \ref nearest. Forward to \ref jacobi. Up to \ref contents. 4383</center> 4384 4385Jacobi (1839) showed that the problem of geodesics on a triaxial 4386ellipsoid (with 3 unequal axes) can be reduced to quadrature. Despite 4387this, the detailed behavior of the geodesics is not very well known. In 4388this section, I briefly give Jacobi's solution and illustrate the 4389behavior of the geodesics and outline an algorithm for the solution of 4390the inverse problem. 4391 4392See also 4393 - The wikipedia page, 4394 <a href="https://en.wikipedia.org/wiki/Geodesics_on_an_ellipsoid#Geodesics_on_a_triaxial_ellipsoid"> 4395 Geodesics on a triaxial ellipsoid</a>. 4396 4397Go to 4398 - \ref triaxial-coords 4399 - \ref triaxial-jacobi 4400 - \ref triaxial-survey 4401 - \ref triaxial-stab 4402 - \ref triaxial-inverse 4403 4404<b>NOTES</b> 4405 -# A triaxial ellipsoid approximates the earth only slightly better 4406 than an ellipsoid of revolution. If you are really considering 4407 measuring distances on the earth using a triaxial ellipsoid, you 4408 should also be worrying about the shape of the geoid, which 4409 essentially makes the geodesic problem a hopeless mess; see, for 4410 example, <a href="https://arxiv.org/abs/1112.3231"> Waters 4411 (2011)</a>. 4412 -# There is nothing new in this section. It is just an exercise in 4413 exploring Jacobi's solution. My interest here is in generating long 4414 geodesics with the correct long-time behavior. Arnold gives a 4415 nice qualitative description of the solution in <i>Mathematical 4416 Methods of Classical Mechanics</i> (2nd edition, Springer, 1989), 4417 pp. 264--266. 4418 -# Possible reasons this problem might, nevertheless, be of interest 4419 are: 4420 - It is the first example of a dynamical system which has a 4421 non-trivial constant of motion. As such, Jacobi's paper generated 4422 a lot of excitement and was followed by many papers elaborating 4423 his solution. In particular, the unstable behavior of one of the 4424 closed geodesics of the ellipsoid, is an early example of a system 4425 with a positive Lyapunov exponent (one of the essential 4426 ingredients for chaotic behavior in dynamical systems). 4427 - Knowledge of ellipsoidal coordinates (used by Jacobi) might be 4428 useful in other areas of geodesy. 4429 - Geodesics which pass through the pole on an ellipsoid of revolution 4430 represent a degenerate class (they are all closed and all pass 4431 through the opposite pole). It is of interest to see how this 4432 degeneracy is broken with a surface with a more general shape. 4433 - Similarly, it is of interest to see how the Mercator projection of 4434 the ellipsoid generalizes; this is another problem addressed by 4435 Jacobi. 4436 -# My interest in this problem was piqued by Jean-Marc Baillard. I put 4437 him onto Jacobi's solution without having looked at it in detail 4438 myself; and he quickly implemented the solution for an HP-41 4439 calculator(!) which is posted 4440 <a href="http://hp41programs.yolasite.com/geod3axial.php"> here</a>. 4441 -# I do not give full citations of the papers here. You can find these 4442 in the 4443 <a href="https://geographiclib.sourceforge.io/geodesic-papers/biblio.html"> 4444 Geodesic Bibliography</a>; this includes links to online 4445 versions of the papers. 4446 -# An alternative to exploring geodesics using Jacobi's solution is to 4447 integrate the equations for the geodesics directly. This is the 4448 approach taken by 4449 <a href="http://www.math.harvard.edu/~knill/caustic/"> 4450 Oliver Knill and Michael Teodorescu</a>. However it is difficult to 4451 ensure that the long time behavior is correctly modeled with such an 4452 approach. 4453 -# At this point, I have no plans to add the solution of triaxial 4454 geodesic problem to GeographicLib. 4455 -# If you only want to learn about geodesics on a biaxial ellipsoid (an 4456 ellipsoid of revolution), then see \ref geodesic or the paper 4457 - C. F. F. Karney, 4458 <a href="https://doi.org/10.1007/s00190-012-0578-z"> 4459 Algorithms for geodesics</a>, 4460 J. Geodesy 87(1), 43--55 (2013); 4461 DOI: <a href="https://doi.org/10.1007/s00190-012-0578-z"> 4462 10.1007/s00190-012-0578-z</a>; 4463 addenda: <a href="https://geographiclib.sourceforge.io/geod-addenda.html"> 4464 geod-addenda.html</a>. 4465 4466\section triaxial-coords Triaxial coordinate systems 4467 4468Consider the ellipsoid defined by 4469\f[ 4470 f = \frac{X^2}{a^2} + \frac{Y^2}{b^2} + \frac{Z^2}{c^2} = 1, 4471\f] 4472where, without loss of generality, \f$ a \ge b \ge c \gt 0\f$. A 4473point on the surface is specified by a latitude and longitude. The \e 4474geographical latitude and longitude \f$(\phi, \lambda)\f$ are defined by 4475\f[ 4476 \frac{\nabla f}{\left| \nabla f\right|} = \left( 4477\begin{array}{c} \cos\phi \cos\lambda \\ \cos\phi \sin\lambda \\ \sin\phi 4478\end{array}\right). 4479\f] 4480The \e parametric latitude and longitude \f$(\phi', \lambda')\f$ are 4481defined by 4482\f[ 4483\begin{align} 4484 X &= a \cos\phi' \cos\lambda', \\ 4485 Y &= b \cos\phi' \sin\lambda', \\ 4486 Z &= c \sin\phi'. 4487\end{align} 4488\f] 4489Jacobi employed the \e ellipsoidal latitude and longitude \f$(\beta, 4490\omega)\f$ defined by 4491\f[ 4492\begin{align} 4493 X &= a \cos\omega 4494 \frac{\sqrt{a^2 - b^2\sin^2\beta - c^2\cos^2\beta}} 4495 {\sqrt{a^2 - c^2}}, \\ 4496 Y &= b \cos\beta \sin\omega, \\ 4497 Z &= c \sin\beta 4498 \frac{\sqrt{a^2\sin^2\omega + b^2\cos^2\omega - c^2}} 4499 {\sqrt{a^2 - c^2}}. 4500\end{align} 4501\f] 4502Grid lines of constant \f$\beta\f$ and \f$\omega\f$ are given in Fig. 1. 4503 4504<center> 4505<img src="https://upload.wikimedia.org/wikipedia/commons/b/bd/Triaxial_ellipsoid_coordinate_system.svg" 4506width=419 height=397 alt="Geodesic grid on a triaxial ellipsoid"> 4507Fig. 1 4508</center>\n 4509Fig. 1: 4510The ellipsoidal grid. The blue (resp. green) lines are lines of constant 4511\f$\beta\f$ (resp. \f$\omega\f$); the grid spacing is 10°. Also 4512shown in red are two of the principal sections of the ellipsoid, defined 4513by \f$x = 0\f$ and \f$z = 0\f$. The third principal section, \f$y = 45140\f$, is covered by the lines \f$\beta = \pm 90^\circ\f$ and \f$\omega = 451590^\circ \pm 90^\circ\f$. These lines meet at four umbilical points (two 4516of which are visible in this figure) where the principal radii of 4517curvature are equal. The parameters of the ellipsoid are \f$a = 45181.01\f$, \f$b = 1\f$, \f$c = 0.8\f$, and it is viewed in an orthographic 4519projection from a point above \f$\phi = 40^\circ\f$, \f$\lambda = 452030^\circ\f$. These parameters were chosen to accentuate the ellipsoidal 4521effects on geodesics (relative to those on the earth) while still 4522allowing the connection to an ellipsoid of revolution to be made. 4523 4524The grid lines of the ellipsoid coordinates are "lines of curvature" on 4525the ellipsoid, i.e., they are parallel to the direction of principal 4526curvature (Monge, 1796). They are also intersections of the ellipsoid 4527with confocal systems of hyperboloids of one and two sheets (Dupin, 45281813). Finally they are geodesic ellipses and hyperbolas defined using 4529two adjacent umbilical points. For example, the lines of constant 4530\f$\beta\f$ in Fig. 1 can be generated with the familiar string 4531construction for ellipses with the ends of the string pinned to the two 4532umbilical points. 4533 4534The element of length on the ellipsoid in ellipsoidal coordinates is 4535given by 4536\f[ 4537\begin{align} 4538\frac{ds^2}{(a^2-b^2)\sin^2\omega+(b^2-c^2)\cos^2\beta} &= 4539\frac{b^2\sin^2\beta+c^2\cos^2\beta} 4540 {a^2-b^2\sin^2\beta-c^2\cos^2\beta} 4541 d\beta^2 \\ 4542&\qquad+ 4543\frac{a^2\sin^2\omega+b^2\cos^2\omega} 4544 {a^2\sin^2\omega+b^2\cos^2\omega-c^2} 4545 d\omega^2. 4546\end{align} 4547\f] 4548 4549The torus \f$(\omega, \beta) \in [-\pi,\pi] \times [-\pi,\pi]\f$ covers 4550the ellipsoid twice. In order to facilitate passing to the limit of an 4551oblate ellipsoid, we may regard as the principal sheet \f$[-\pi,\pi] 4552\times [-\frac12\pi,\frac12\pi]\f$ and insert branch cuts at 4553\f$\beta=\pm\frac12\pi\f$. The rule for switching sheets is 4554\f[ 4555\begin{align} 4556\omega & \rightarrow -\omega,\\ 4557\beta & \rightarrow \pi-\beta,\\ 4558\alpha & \rightarrow \pi+\alpha, 4559\end{align} 4560\f] 4561where \f$\alpha\f$ is the heading of a path, relative to a line of 4562constant \f$\omega\f$. 4563 4564In the limit \f$b\rightarrow a\f$ (resp. \f$b\rightarrow c\f$), the 4565umbilic points converge on the \f$z\f$ (resp. \f$x\f$) axis and an 4566oblate (resp. prolate) ellipsoid is obtained with \f$\beta\f$ 4567(resp. \f$\omega\f$) becoming the standard parametric latitude and 4568\f$\omega\f$ (resp. \f$\beta\f$) becoming the standard longitude. The 4569sphere is a non-uniform limit, with the position of the umbilic points 4570depending on the ratio \f$(a-b)/(b-c)\f$. 4571 4572Inter-conversions between the three different latitudes and longitudes 4573and the cartesian coordinates are simple algebraic exercises. 4574 4575\section triaxial-jacobi Jacobi's solution 4576 4577Solving the geodesic problem for an ellipsoid of revolution is, from the 4578mathematical point of view, trivial; because of symmetry, geodesics have 4579a constant of the motion (analogous to the angular momentum) which was 4580found by Clairaut (1733). By 1806 (with the work of Legendre, Oriani, 4581et al.), there was a complete understanding of the qualitative behavior 4582of geodesics on an ellipsoid of revolution. 4583 4584On the other hand, geodesics on a triaxial ellipsoid have no obvious 4585constant of the motion and thus represented a challenging "unsolved" 4586problem in the first half of the nineteenth century. Jacobi discovered 4587that the geodesic equations are separable if they are expressed in 4588ellipsoidal coordinates. You can get an idea of the importance Jacobi 4589attached to his discovery from the 4590<a href="https://books.google.com/books?id=_09tAAAAMAAJ&pg=PA385"> 4591letter</a> he wrote to his friend and neighbor Bessel: 4592<blockquote> The day before yesterday, I reduced to quadrature the 4593problem of geodesic lines on an <i>ellipsoid with three unequal 4594axes</i>. They are the simplest formulas in the world, Abelian 4595integrals, which become the well known elliptic integrals if 2 axes are 4596set equal.\n 4597Königsberg, 28th Dec. '38. 4598</blockquote> 4599 4600On the same day he wrote a similar letter to the editor of Compte Rendus 4601and his result was published in J. Crelle in (1839) with a French 4602translation (from German) appearing in J. Liouville in (1841). 4603 4604Here is the solution, exactly as given by Jacobi 4605<a href="https://books.google.com/books?id=Rh8GAAAAYAAJ&pg=PA268"> here</a> 4606(with minor changes in notation): 4607\f[ 4608\begin{align} 4609\delta &= \int \frac 4610{\sqrt{b^2\sin^2\beta + c^2\cos^2\beta}\,d\beta} 4611{\sqrt{a^2 - b^2\sin^2\beta - c^2\cos^2\beta} 4612 \sqrt{(b^2-c^2)\cos^2\beta - \gamma}}\\ 4613&\quad - 4614\int \frac 4615{\sqrt{a^2\sin^2\omega + b^2\cos^2\omega}\,d\omega} 4616{\sqrt{a^2\sin^2\omega + b^2\cos^2\omega - c^2} 4617 \sqrt{(a^2-b^2)\sin^2\omega + \gamma}} 4618\end{align} 4619\f] 4620As Jacobi notes "a function of the angle \f$\beta\f$ equals a 4621function of the angle \f$\omega\f$. These two functions are just 4622Abelian integrals…" Two constants \f$\delta\f$ and \f$\gamma\f$ 4623appear in the solution. Typically \f$\delta\f$ is zero if the lower 4624limits of the integrals are taken to be the starting point of the geodesic 4625and the direction of the geodesics is determined by \f$\gamma\f$. 4626However for geodesics that start at an umbilical points, we have \f$\gamma 4627= 0\f$ and \f$\delta\f$ determines the direction at the umbilical point. 4628Incidentally the constant \f$\gamma\f$ may be expressed as 4629\f[ 4630\gamma = (b^2-c^2)\cos^2\beta\sin^2\alpha-(a^2-b^2)\sin^2\omega\cos^2\alpha 4631\f] 4632where \f$\alpha\f$ is the angle the geodesic makes with lines of 4633constant \f$\omega\f$. In the limit \f$b\rightarrow a\f$, this reduces 4634to \f$\cos\beta\sin\alpha = \text{const.}\f$, the familiar Clairaut 4635relation. A nice derivation of Jacobi's result is given by Darboux 4636(1894) <a href="https://books.google.com/books?id=hGMSAAAAIAAJ&pg=PA9"> 4637§§583--584</a> where he gives the solution found by Liouville 4638(1846) for general quadratic surfaces. In this formulation, the 4639distance along the geodesic, \f$s\f$, is also found using 4640\f[ 4641\begin{align} 4642\frac{ds}{(b^2-c^2)\cos^2\beta + (a^2-b^2)\sin^2\omega} 4643&= \frac 4644{\sqrt{b^2\sin^2\beta + c^2\cos^2\beta}\,d\beta} 4645{\sqrt{a^2 - b^2\sin^2\beta - c^2\cos^2\beta} 4646 \sqrt{(b^2-c^2)\cos^2\beta - \gamma}}\\ 4647&= \frac 4648{\sqrt{a^2\sin^2\omega + b^2\cos^2\omega}\,d\omega} 4649{\sqrt{a^2\sin^2\omega + b^2\cos^2\omega - c^2} 4650 \sqrt{(a^2-b^2)\sin^2\omega + \gamma}} 4651\end{align} 4652\f] 4653An alternative expression for the distance is 4654\f[ 4655\begin{align} 4656ds 4657&= \frac 4658{\sqrt{b^2\sin^2\beta + c^2\cos^2\beta} 4659 \sqrt{(b^2-c^2)\cos^2\beta - \gamma}\,d\beta} 4660{\sqrt{a^2 - b^2\sin^2\beta - c^2\cos^2\beta}}\\ 4661&\quad {}+ \frac 4662{\sqrt{a^2\sin^2\omega + b^2\cos^2\omega} 4663 \sqrt{(a^2-b^2)\sin^2\omega + \gamma}\,d\omega} 4664{\sqrt{a^2\sin^2\omega + b^2\cos^2\omega - c^2}} 4665\end{align} 4666\f] 4667 4668Jacobi's solution is a convenient way to compute geodesics on an 4669ellipsoid. Care must be taken with the signs of the square roots (which 4670are determined by the initial azimuth of the geodesic). Also if 4671\f$\gamma \gt 0\f$ (resp. \f$\gamma \lt 0\f$), then the \f$\beta\f$ 4672(resp. \f$\omega\f$) integrand diverges. The integrand can be 4673transformed into a finite one by a change of variable, e.g., 4674\f$\sin\beta = \sin\sigma \sqrt{1 - \gamma/(b^2-c^2)}\f$. The resulting 4675integrals are periodic, so the behavior of an arbitrarily long geodesic 4676is entirely captured by tabulating the integrals over a single period. 4677 4678The situation is more complicated if \f$\gamma = 0\f$ (corresponding to 4679umbilical geodesics). Both integrands have simple poles at the umbilical 4680points. However, this behavior may be subtracted from the integrands to 4681yield (for example) the sum of a term involving 4682\f$\tanh^{-1}\sin\beta\f$ and a finite integral. Since both integrals 4683contain similar logarithmic singularities they can be equated (thus 4684fixing the ratio \f$\cos\beta/\sin\omega\f$ at the umbilical point) and 4685connection formulas can be found which allow the geodesic to be followed 4686through the umbilical point. The study of umbilical geodesics was of 4687special interest to a group of Irish mathematicians in the 1840's and 46881850's, including Michael and William Roberts (twins!), Hart, Graves, 4689and Salmon. 4690 4691\section triaxial-survey Survey of triaxial geodesics 4692 4693Before delving into the nature of geodesics on a triaxial geodesic, it 4694is worth reviewing geodesics on an ellipsoid of revolution. There are 4695two classes of simple closed geodesics (i.e., geodesics which close on 4696themselves without intersection): the equator and all the meridians. 4697All other geodesics oscillate between two equal and opposite circles of 4698latitude; but after completing a full oscillation in latitude these fall 4699slightly short (for an oblate ellipsoid) of completing a full circuit in 4700longitude. 4701 4702Turning to the triaxial case, we find that there are only 3 simple 4703closed geodesics, the three principal sections of the ellipsoid given by 4704\f$x = 0\f$, \f$y = 0\f$, and \f$z = 0\f$. To survey the other 4705geodesics, it is convenient to consider geodesics which intersect the 4706middle principal section, \f$y = 0\f$, at right angles. Such geodesics 4707are shown in Figs. 2--6, where I use the same ellipsoid parameters as in 4708Fig. 1 and the same viewing direction. In addition, the three principal 4709ellipses are shown in red in each of these figures. 4710 4711If the starting point is \f$\beta_1 \in (-90^\circ, 90^\circ)\f$, 4712\f$\omega_1 = 0\f$, and \f$\alpha_1 = 90^\circ\f$, then the geodesic 4713encircles the ellipsoid in a "circumpolar" sense. The geodesic 4714oscillates north and south of the equator; on each oscillation it 4715completes slightly less that a full circuit around the ellipsoid 4716resulting in the geodesic filling the area bounded by the two latitude 4717lines \f$\beta = \pm \beta_1\f$. Two examples are given in 4718Figs. 2 and 3. Figure 2 shows practically the same behavior as for an 4719oblate ellipsoid of revolution (because \f$a \approx b\f$). However, if 4720the starting point is at a higher latitude (Fig. 3) the distortions 4721resulting from \f$a \ne b\f$ are evident. 4722 4723<center> 4724<img src="https://upload.wikimedia.org/wikipedia/commons/a/a9/Circumpolar_geodesic_on_a_triaxial_ellipsoid_case_A.svg" 4725width=419 height=397 alt="Example of a circumpolar geodesic on a 4726triaxial ellipsoid"> 4727Fig. 2 4728</center>\n 4729Fig. 2: 4730Example of a circumpolar geodesic on a triaxial ellipsoid. The starting 4731point of this geodesic is \f$\beta_1 = 45.1^\circ\f$, \f$\omega_1 = 47320^\circ\f$, and \f$\alpha_1 = 90^\circ\f$. 4733 4734<center> 4735<img src="https://upload.wikimedia.org/wikipedia/commons/f/f3/Circumpolar_geodesic_on_a_triaxial_ellipsoid_case_B.svg" 4736width=419 height=397 alt="Another example of a circumpolar geodesic on a 4737triaxial ellipsoid"> 4738Fig. 3 4739</center>\n 4740Fig. 3: 4741Another example of a circumpolar geodesic on a triaxial ellipsoid. The 4742starting point of this geodesic is \f$\beta_1 = 87.48^\circ\f$, \f$\omega_1 = 47430^\circ\f$, and \f$\alpha_1 = 90^\circ\f$. 4744 4745If the starting point is \f$\beta_1 = 90^\circ\f$, \f$\omega_1 \in 4746(0^\circ, 180^\circ)\f$, and \f$\alpha_1 = 180^\circ\f$, then the geodesic 4747encircles the ellipsoid in a "transpolar" sense. The geodesic 4748oscillates east and west of the ellipse \f$x = 0\f$; on each oscillation 4749it completes slightly more that a full circuit around the ellipsoid 4750resulting in the geodesic filling the area bounded by the two longitude 4751lines \f$\omega = \omega_1\f$ and \f$\omega = 180^\circ - \omega_1\f$. 4752If \f$a = b\f$, all meridians are geodesics; the effect of \f$a \ne b\f$ 4753causes such geodesics to oscillate east and west. Two examples are 4754given in Figs. 4 and 5. 4755 4756<center> 4757<img src="https://upload.wikimedia.org/wikipedia/commons/8/83/Transpolar_geodesic_on_a_triaxial_ellipsoid_case_A.svg" 4758width=419 height=397 alt="Example of a transpolar geodesic on a 4759triaxial ellipsoid"> 4760Fig. 4 4761</center>\n 4762Fig. 4: 4763Example of a transpolar geodesic on a triaxial ellipsoid. The 4764starting point of this geodesic is \f$\beta_1 = 90^\circ\f$, \f$\omega_1 = 476539.9^\circ\f$, and \f$\alpha_1 = 180^\circ\f$. 4766 4767<center> 4768<img src="https://upload.wikimedia.org/wikipedia/commons/9/9c/Transpolar_geodesic_on_a_triaxial_ellipsoid_case_B.svg" 4769width=419 height=397 alt="Another example of a transpolar geodesic on a 4770triaxial ellipsoid"> 4771Fig. 5 4772</center>\n 4773Fig. 5: 4774Another example of a transpolar geodesic on a triaxial ellipsoid. The 4775starting point of this geodesic is \f$\beta_1 = 90^\circ\f$, \f$\omega_1 = 47769.966^\circ\f$, and \f$\alpha_1 = 180^\circ\f$. 4777 4778If the starting point is \f$\beta_1 = 90^\circ\f$, \f$\omega_1 = 47790^\circ\f$ (an umbilical point), and \f$\alpha_1 = 135^\circ\f$ (the 4780geodesic leaves the ellipse \f$y = 0\f$ at right angles), then the 4781geodesic repeatedly intersects the opposite umbilical point and returns to 4782its starting point. However on each circuit the angle at which it 4783intersects \f$y = 0\f$ becomes closer to \f$0^\circ\f$ or 4784\f$180^\circ\f$ so that asymptotically the geodesic lies on the ellipse 4785\f$y = 0\f$. This is shown in Fig. 6. Note that a single geodesic does 4786not fill an area on the ellipsoid. 4787 4788<center> 4789<img src="https://upload.wikimedia.org/wikipedia/commons/e/e5/Unstable_umbilical_geodesic_on_a_triaxial_ellipsoid.svg" 4790width=419 height=397 alt="Example of an umbilical geodesic on a 4791triaxial ellipsoid"> 4792Fig. 6 4793</center>\n 4794Fig. 6: 4795Example of an umbilical geodesic on a triaxial ellipsoid. The 4796starting point of this geodesic is \f$\beta_1 = 90^\circ\f$, \f$\omega_1 = 47970^\circ\f$, and \f$\alpha_1 = 135^\circ\f$ and the geodesics is followed 4798forwards and backwards until it lies close to the plane \f$y = 0\f$ in 4799both directions. 4800 4801Umbilical geodesics enjoy several interesting properties. 4802 - Through any point on the ellipsoid, there are two umbilical geodesics. 4803 - The geodesic distance between opposite umbilical points is the same 4804 regardless of the initial direction of the geodesic. 4805 - Whereas the closed geodesics on the ellipses \f$x = 0\f$ and \f$z = 4806 0\f$ are stable (an geodesic initially close to and nearly parallel to 4807 the ellipse remains close to the ellipse), the closed geodesic on the 4808 ellipse \f$y = 0\f$, which goes through all 4 umbilical points, is \e 4809 unstable. If it is perturbed, it will swing out of the plane \f$y = 4810 0\f$ and flip around before returning to close to the plane. (This 4811 behavior may repeat depending on the nature of the initial 4812 perturbation.). 4813 4814\section triaxial-stab The stability of closed geodesics 4815 4816The stability of the three simple closed geodesics can be determined by 4817examining the properties of Jacobi's solution. In particular the 4818unstable behavior of umbilical geodesics was shown by Hart (1849). 4819However an alternative approach is to use the equations that Gauss 4820(1828) gives for a perturbed geodesic 4821\f[ 4822\frac {d^2m}{ds^2} + Km = 0 4823\f] 4824where \f$m\f$ is the distance of perturbed geodesic from a reference 4825geodesic and \f$K\f$ is the Gaussian curvature of the surface. If the 4826reference geodesic is closed, then this is a linear homogeneous 4827differential equation with periodic coefficients. In fact it's a 4828special case of Hill's equation which can be treated using Floquet 4829theory, see <a href="https://dlmf.nist.gov/28.29">DLMF, §28.29</a>. 4830Using the notation of §3 of 4831<a href="https://doi.org/10.1007/s00190-012-0578-z"> Algorithms for 4832geodesics</a>, the stability is determined by computing the reduced 4833length \f$m_{12}\f$ and the geodesic scales \f$M_{12}, M_{21}\f$ over 4834half the perimeter of the ellipse and determining the eigenvalues 4835\f$\lambda_{1,2}\f$ of 4836\f[ 4837{\cal M} = \left(\begin{array}{cc} 4838M_{12} & m_{12}\\ 4839-\frac{1 - M_{12}M_{21}}{m_{12}} & M_{21} 4840\end{array}\right). 4841\f] 4842Because \f$\mathrm{det}\,{\cal M} = 1\f$, the eigenvalues are determined 4843by \f$\mathrm{tr}\,{\cal M}\f$. In particular if 4844\f$\left|\mathrm{tr}\,{\cal M}\right| < 2\f$, we have 4845\f$\left|\lambda_{1,2}\right| = 1\f$ and the solution is stable; if 4846\f$\left|\mathrm{tr}\,{\cal M}\right| > 2\f$, one of 4847\f$\left|\lambda_{1,2}\right|\f$ is larger than unity and the solution 4848is (exponentially) unstable. In the transition case, 4849\f$\left|\mathrm{tr}\,{\cal M}\right| = 2\f$, the solution is stable 4850provided that the off-diagonal elements of \f${\cal M}\f$ are zero; 4851otherwise the solution is linearly unstable. 4852 4853The exponential instability of the geodesic on the ellipse \f$y = 0\f$ 4854is confirmed by this analysis and results from the resonance between the 4855natural frequency of the equation for \f$m\f$ and the driving frequency 4856when \f$b\f$ lies in \f$(c, a)\f$. If \f$b\f$ is equal to either of the 4857other axes (and the triaxial ellipsoid degenerates to an ellipsoid of 4858revolution), then the solution is linearly unstable. (For example, a 4859geodesic is which is close to a meridian on an oblate ellipsoid, slowly 4860moves away from that meridian.) 4861 4862\section triaxial-inverse The inverse problem 4863 4864In order to solve the inverse geodesic problem, it helps to have an 4865understanding of the properties of all the geodesics emanating from a 4866single point \f$(\beta_1, \omega_1)\f$. 4867 - If the point is an umbilical point, all the lines meet at the 4868 opposite umbilical point. 4869 - Otherwise, the first envelope of the geodesics is a 4-pointed 4870 astroid. The cusps of the astroid lie on either \f$\beta = - 4871 \beta_1\f$ or \f$\omega = \omega_1 + \pi\f$; see 4872 <a href="https://doi.org/10.1080/10586458.2003.10504515"> Sinclair 4873 (2003)</a>. 4874 - All geodesics intersect (or, in the case of \f$\alpha_1 = 0\f$ or 4875 \f$\pi\f$, touch) the line \f$\omega = \omega_1 + \pi\f$. 4876 - All geodesics intersect (or, in the case of \f$\alpha_1 = 4877 \pm\pi/2\f$, touch) the line \f$\beta = -\beta_1\f$. 4878 - Two geodesics with azimuths \f$\pm\alpha_1\f$ first intersect on 4879 \f$\omega = \omega_1 + \pi\f$ and their lengths to the point of 4880 intersection are equal. 4881 - Two geodesics with azimuths \f$\alpha_1\f$ and \f$\pi-\alpha_1\f$ 4882 first intersect on \f$\beta = -\beta_1\f$ and their lengths to the 4883 point of intersection are equal. 4884 . 4885(These assertions follow directly from the equations for the geodesics; 4886some of them are somewhat surprising given the asymmetries of the 4887ellipsoid.) Consider now terminating the geodesics from \f$(\beta_1, 4888\omega_1)\f$ at the point where they first intersect (or touch) the line 4889\f$\beta = -\beta_1\f$. To focus the discussion, take \f$\beta_1 \le 48900\f$. 4891 - The geodesics completely fill the portion of the ellipsoid satisfying 4892 \f$\beta \le -\beta_1\f$. 4893 - None of geodesics intersect any other geodesics. 4894 - Any initial portion of these geodesics is a shortest path. 4895 - Each geodesic intersects the line \f$\beta = \beta_2\f$, where 4896 \f$\beta_1 < \beta_2 < -\beta_1\f$, exactly once. 4897 - For a given \f$\beta_2\f$, this defines a continuous monotonic 4898 mapping of the circle of azimuths \f$\alpha_1\f$ to the circle of 4899 longitudes \f$\omega_2\f$. 4900 - If \f$\beta_2 = \pm \beta_1\f$, then the previous two assertions need 4901 to be modified similarly to the case for an ellipsoid of revolution. 4902 4903These properties show that the inverse problem can be solved using 4904techniques similar to those employed for an ellipsoid of revolution (see 4905§4 of 4906<a href="https://doi.org/10.1007/s00190-012-0578-z"> Algorithms for 4907geodesics</a>). 4908 - If the points are opposite umbilical points, an arbitrary 4909 \f$\alpha_1\f$ may be chosen. 4910 - If the points are neighboring umbilical points, the shortest path 4911 lies on the ellipse \f$y = 0\f$. 4912 - If only one point is an umbilicial point, the azimuth at the 4913 non-umbilical point is found using the generalization of Clairaut's 4914 equation (given above) with \f$\gamma = 0\f$. 4915 - Treat the cases where the geodesic might follow a line of constant 4916 \f$\beta\f$. There are two such cases: (a) the points lie on 4917 the ellipse \f$z = 0\f$ on a general ellipsoid and (b) the 4918 points lie on an ellipse whose major axis is the \f$x\f$ axis on a 4919 prolate ellipsoid (\f$a = b > c\f$). Determine the reduced length 4920 \f$m_{12}\f$ for the geodesic which is the shorter path along the 4921 ellipse. If \f$m_{12} \ge 0\f$, then this is the shortest path on 4922 the ellipsoid; otherwise proceed to the general case (next). 4923 - Swap the points, if necessary, so that the first point is the one 4924 closest to a pole. Estimate \f$\alpha_1\f$ (by some means) and solve 4925 the \e hybrid problem, i.e., determine the longitude \f$\omega_2\f$ 4926 corresponding to the first intersection of the geodesic with \f$\beta 4927 = \beta_2\f$. Adjust \f$\alpha_1\f$ so that the value of 4928 \f$\omega_2\f$ matches the given \f$\omega_2\f$ (there is a single 4929 root). If a sufficiently close solution can be found, Newton's 4930 method can be employed since the necessary derivative can be 4931 expressed in terms of the reduced length \f$m_{12}\f$. 4932 4933The shortest path found by this method is unique unless: 4934 - The length of the geodesic vanishes \f$s_{12}=0\f$, in which case any 4935 constant can be added to the azimuths. 4936 - The points are opposite umbilical points. In this case, 4937 \f$\alpha_1\f$ can take on any value and \f$\alpha_2\f$ needs to be 4938 adjusted to maintain the value of \f$\tan\alpha_1 / \tan\alpha_2\f$. 4939 Note that \f$\alpha\f$ increases by \f$\pm 90^\circ\f$ as the 4940 geodesic passes through an umbilical point, depending on whether the 4941 geodesic is considered as passing to the right or left of the point. 4942 Here \f$\alpha_2\f$ is the \e forward azimuth at the second umbilical 4943 point, i.e., its azimuth immediately \e after passage through the 4944 umbilical point. 4945 - \f$\beta_1 + \beta_2 = 0\f$ and \f$\cos\alpha_1\f$ and 4946 \f$\cos\alpha_2\f$ have opposite signs. In this case, there another 4947 shortest geodesic with azimuths \f$\pi - \alpha_1\f$ and 4948 \f$\pi - \alpha_2\f$. 4949 4950\section triaxial-conformal Jacobi's conformal projection 4951 4952This material is now on its own page; see \ref jacobi. 4953 4954<center> 4955Back to \ref nearest. Forward to \ref jacobi. Up to \ref contents. 4956</center> 4957 4958**********************************************************************/ 4959/** 4960\page jacobi Jacobi's conformal projection 4961 4962<center> 4963Back to \ref triaxial. Forward to \ref rhumb. Up to \ref contents. 4964</center> 4965 4966In addition to solving the geodesic problem for the triaxial ellipsoid, 4967Jacobi (1839) briefly mentions the problem of the conformal projection 4968of ellipsoid. He covers this in greater detail in 4969<a href="https://books.google.com/books?id=ryEOAAAAQAAJ&pg=PA212"> 4970<i>Vorlesungen über Dynamik</i>, §28</a>, which is now 4971available in an <a href="https://www.worldcat.org/oclc/440645889"> 4972English translation: Lectures on Dynamics</a> 4973(<a href="https://geographiclib.sourceforge.io/jacobi-errata.html"> 4974errata</a>). 4975 4976\section jacobi-conformal Conformal projection 4977 4978It is convenient to rotate Jacobi's ellipsoidal coordinate system so 4979that \f$(X,Y,Z)\f$ are respectively the middle, large, and small axes of 4980the ellipsoid. The longitude \f$\omega\f$ is shifted so that 4981\f$(\beta=0,\omega=0)\f$ is the point \f$(b,0,0)\f$. The coordinates 4982are thus defined by 4983\f[ 4984\begin{align} 4985 X &= b \cos\beta \cos\omega, \\ 4986 Y &= a \sin\omega 4987 \frac{\sqrt{a^2 - b^2\sin^2\beta - c^2\cos^2\beta}} 4988 {\sqrt{a^2 - c^2}}, \\ 4989 Z &= c \sin\beta 4990 \frac{\sqrt{a^2\cos^2\omega + b^2\sin^2\omega - c^2}} 4991 {\sqrt{a^2 - c^2}}. 4992\end{align} 4993\f] 4994After this change, the large principal ellipse is the equator, 4995\f$\beta=0\f$, while the small principal ellipse is the prime meridian, 4996\f$\omega=0\f$. The four umbilic points, \f$\left|\omega\right| = 4997\left|\beta\right| = \frac12\pi\f$, lie on middle principal ellipse in 4998the plane \f$X=0\f$. 4999 5000Jacobi gives the following conformal mapping of the triaxial ellipsoid 5001onto a plane 5002\f[ 5003\begin{align} 5004x &= \frac{\sqrt{a^2-c^2}}b \int \frac 5005{\sqrt{a^2 \cos^2\omega + b^2 \sin^2\omega}} 5006{\sqrt{a^2 \cos^2\omega + b^2 \sin^2\omega - c^2}}\, d\omega, \\ 5007y &= \frac{\sqrt{a^2-c^2}}b \int \frac 5008{\sqrt{b^2 \sin^2\beta + c^2 \cos^2\beta}} 5009{\sqrt{a^2 - b^2 \sin^2\beta - c^2 \cos^2\beta}}\, d\beta. 5010\end{align} 5011\f] 5012The scale of the projection is 5013\f[ 5014k = \frac{\sqrt{a^2-c^2}} 5015{b\sqrt{a^2 \cos^2\omega + b^2 (\sin^2\omega-\sin^2\beta) - c^2 \cos^2\beta}}. 5016\f] 5017I have scaled the Jacobi's projection by a constant factor, 5018\f[ 5019\frac{\sqrt{a^2-c^2}}{2b}, 5020\f] 5021so that it reduces to the familiar formulas in the case of an oblate ellipsoid. 5022 5023\section jacobi-elliptic The projection in terms of elliptic integrals 5024 5025The projection may be expressed in terms of elliptic integrals, 5026\f[ 5027\begin{align} 5028x&=(1+e_a^2)\,\Pi(\omega',-e_a^2, \cos\nu),\\ 5029y&=(1-e_c^2)\,\Pi(\beta' , e_c^2, \sin\nu),\\ 5030k&=\frac{\sqrt{e_a^2+e_c^2}}{b\sqrt{e_a^2\cos^2\omega+e_c^2\cos^2\beta}}, 5031\end{align} 5032\f] 5033where 5034\f[ 5035\begin{align} 5036e_a &= \frac{\sqrt{a^2-b^2}}b, \qquad 5037e_c = \frac{\sqrt{b^2-c^2}}b, \\ 5038\tan\omega' &= \frac ba \tan\omega = \frac 1{\sqrt{1+e_a^2}} \tan\omega, \\ 5039\tan\beta' &= \frac bc \tan\beta = \frac 1{\sqrt{1-e_c^2}} \tan\beta, \\ 5040\tan\nu &= \frac ac \frac{\sqrt{b^2-c^2}}{\sqrt{a^2-b^2}} 5041=\frac{e_c}{e_a}\frac{\sqrt{1+e_a^2}}{\sqrt{1-e_c^2}}, 5042\end{align} 5043\f] 5044\f$\nu\f$ is the geographic latitude of the umbilic point at \f$\beta = 5045\omega = \frac12\pi\f$ (the angle a normal at the umbilic point makes 5046with the equatorial plane), and \f$\Pi(\phi,\alpha^2,k)\f$ is the 5047elliptic integral of the third kind, https://dlmf.nist.gov/19.2.E7. This 5048allows the projection to be numerically computed using 5049EllipticFunction::Pi(real phi) const. 5050 5051Nyrtsov, et al., 5052 - M. V. Nyrtsov, M. E. Flies, M. M. Borisov, P. J. Stooke, 5053 <a href="https://doi.org/10.1007/978-3-642-32618-9_17"> 5054 Jacobi conformal projection of the triaxial ellipsoid: new projection 5055 for mapping of small celestial bodies,</a> in 5056 <i>Cartography from Pole to Pole</i> 5057 (Springer, 2014), pp. 235--246. 5058 . 5059also expressed the projection in terms of elliptic integrals. 5060However, their expressions don't allow the limits of ellipsoids of 5061revolution to be readily recovered. The relations 5062https://dlmf.nist.gov/19.7.E5 can be used to put their results in the 5063form given here. 5064 5065\section jacobi-properties Properties of the projection 5066 5067\f$x\f$ (resp. \f$y\f$) depends on \f$\omega\f$ (resp. \f$\beta\f$) 5068alone, so that latitude-longitude grid maps to straight lines in the 5069projection. In this sense, the Jacobi projection is the natural 5070generalization of the Mercator projection for the triaxial ellipsoid. 5071(See below for the limit \f$a\rightarrow b\f$, which makes this 5072connection explicit.) 5073 5074In the general case (all the axes are different), the scale diverges 5075only at the umbilic points. The behavior of these singularities is 5076illustrated by the complex function 5077\f[ 5078f(z;e) = \cosh^{-1}(z/e) - \log(2/e). 5079\f] 5080For \f$e > 0\f$, this function has two square root singularities at 5081\f$\pm e\f$, corresponding to the two northern umbilic points. 5082Plotting contours of its real (resp. imaginary) part gives the 5083behavior of the lines of constant latitude (resp. longitude) near the 5084north pole in Fig. 1. If we pass to the limit \f$e\rightarrow 0\f$, 5085then \f$ f(z;e)\rightarrow\log z\f$, and the two branch points merge 5086yielding a stronger (logarithmic) singularity at \f$z = 0\f$, 5087concentric circles of latitude, and radial lines of longitude. 5088 5089Again in the general case, the extents of \f$x\f$ and \f$y\f$ are 5090finite, 5091\f[ 5092\begin{align} 5093x\bigl(\tfrac12\pi\bigr) &=(1+e_a^2)\,\Pi(-e_a^2, \cos\nu),\\ 5094y\bigl(\tfrac12\pi\bigr) &=(1-e_c^2)\,\Pi(e_c^2, \sin\nu), 5095\end{align} 5096\f] 5097where \f$\Pi(\alpha^2,k)\f$ is the complete elliptic integral of the 5098third kind, https://dlmf.nist.gov/19.2.E8. 5099 5100In particular, if we substitute values appropriate for the earth, 5101\f[ 5102\begin{align} 5103a&=(6378137+35)\,\mathrm m,\\ 5104b&=(6378137-35)\,\mathrm m,\\ 5105c&=6356752\,\mathrm m,\\ 5106\end{align} 5107\f] 5108we have 5109\f[ 5110\begin{align} 5111x\bigl({\textstyle\frac12}\pi\bigr) &= 1.5720928 = \hphantom{0}90.07428^\circ,\\ 5112y\bigl({\textstyle\frac12}\pi\bigr) &= 4.2465810 = 243.31117^\circ.\\ 5113\end{align} 5114\f] 5115 5116The projection may be inverted (to give \f$\omega\f$ in terms of \f$x\f$ 5117and \f$\beta\f$ in terms of \f$y\f$) by using Newton's method to find 5118the root of, for example, \f$x(\omega) - x_0 = 0\f$. The derivative of 5119the elliptic integral is, of course, just given by its defining 5120relation. 5121 5122If rhumb lines are defined as curves with a constant bearing relative 5123to the ellipsoid coordinates, then these are straight lines in the 5124Jacobi projection. A rhumb line which passes over an umbilic point 5125immediately retraces its path. A rhumb line which crosses the line 5126joining the two northerly umbilic points starts traveling south with 5127a reversed heading (e.g., a NE heading becomes a SW heading). This 5128behavior is preserved in the limit \f$a\rightarrow b\f$ (although the 5129longitude becomes indeterminate in this limit). 5130 5131\section jacobi-limiting Limiting cases 5132 5133<b>Oblate ellipsoid</b>, \f$a\rightarrow b\f$. The coordinate system 5134is 5135\f[ 5136\begin{align} 5137 X &= b \cos\beta \cos\omega, \\ 5138 Y &= b \cos\beta \sin\omega, \\ 5139 Z &= c \sin\beta. 5140\end{align} 5141\f] 5142Thus \f$\beta\f$ (resp. \f$\beta'\f$) is the parametric 5143(resp. geographic) latitude and \f$\omega=\omega'\f$ is the longitude; 5144the quantity \f$e_c\f$ is the eccentricity of the ellipsoid. 5145Using https://dlmf.nist.gov/19.6.E12 and https://dlmf.nist.gov/19.2.E19 5146the projection reduces to the normal Mercator projection for an oblate 5147ellipsoid, 5148\f[ 5149\begin{align} 5150x &= \omega,\\ 5151y &= \sinh^{-1}\tan\beta' 5152- e_c \tanh^{-1}(e_c\sin\beta'),\\ 5153k &= \frac1{b\cos\beta}. 5154\end{align} 5155\f] 5156 5157<b>Prolate ellipsoid</b>, \f$c\rightarrow b\f$. The coordinate system 5158is 5159\f[ 5160\begin{align} 5161 X &= b \cos\omega \cos\beta, \\ 5162 Y &= a \sin\omega, \\ 5163 Z &= b \cos\omega \sin\beta. 5164\end{align} 5165\f] 5166Thus \f$\omega\f$ (resp. \f$\omega'\f$) now plays the role of the 5167parametric (resp. geographic) latitude and while \f$\beta=\beta'\f$ is 5168the longitude. Using https://dlmf.nist.gov/19.6.E12 5169https://dlmf.nist.gov/19.2.E19 and https://dlmf.nist.gov/19.2.E18 the 5170projection reduces to similar expressions with the roles of \f$\beta\f$ 5171and \f$\omega\f$ switched, 5172\f[ 5173\begin{align} 5174x &= \sinh^{-1}\tan\omega' 5175+ e_a 5176 \tan^{-1}(e_a\sin\omega'),\\ 5177y &= \beta,\\ 5178k &= \frac1{b\cos\omega}. 5179\end{align} 5180\f] 5181 5182<b>Sphere</b>, \f$a\rightarrow b\f$ and \f$c\rightarrow b\f$. This is a 5183non-uniform limit depending on the parameter \f$\nu\f$, 5184\f[ 5185\begin{align} 5186 X &= b \cos\omega \cos\beta, \\ 5187 Y &= b \sin\omega \sqrt{1 - \sin^2\nu\sin^2\beta}, \\ 5188 Z &= b \sin\beta \sqrt{1 - \cos^2\nu\sin^2\omega}. 5189\end{align} 5190\f] 5191Using https://dlmf.nist.gov/19.6.E13 the projection can be put in terms 5192of the elliptic integral of the first kind, https://dlmf.nist.gov/19.2.E4 5193\f[ 5194\begin{align} 5195x &= F(\omega, \cos\nu), \\ 5196y &= F(\beta, \sin\nu), \\ 5197k &= \frac1{b \sqrt{\cos^2\nu\cos^2\omega + \sin^2\nu\cos^2\beta}}, 5198\end{align} 5199\f] 5200Obtaining the limit of a sphere via an oblate (resp. prolate) ellipsoid 5201corresponds to setting \f$\nu = \frac12\pi\f$ (resp. \f$\nu 5202=0\f$). In these limits, the elliptic integral reduces to elementary 5203functions https://dlmf.nist.gov/19.6.E7 and https://dlmf.nist.gov/19.6.E8 5204\f[ 5205\begin{align} 5206F(\phi, 0) &= \phi, \\ 5207F(\phi, 1) &= \mathop{\mathrm{gd}}\nolimits^{-1}\phi = \sinh^{-1}\tan\phi. 5208\end{align} 5209\f] 5210The spherical limit gives the projection found by É. Guyou in 5211 - <a href="https://books.google.com/books?id=saBDAQAAIAAJ&pg=PA308"> 5212 Sur un nouveau système de projection de la sphère</a>, 5213 Comptes Rendus 102(6), 308--310 (1886). 5214 - <a href="https://books.google.com/books?id=VjU8AQAAMAAJ&pg=PA16"> 5215 Nouveau système de projection de la sphère: 5216 généralisation de la projection de Mercator</a>, 5217 Annales Hydrographiques (2nd series) 9, 16--35 (1887). 5218 . 5219who apparently derived it without realizing that it is just a special 5220case of the projection Jacobi had given some 40 years earlier. Guyou's 5221name is usually associated with the particular choice, 5222\f$\nu=\frac14\pi\f$, in which case the hemisphere 5223\f$\left|\omega\right|\le\frac12\pi\f$ is mapped into a square. 5224However, by varying \f$\nu\in[0,\frac12\pi]\f$ the hemisphere can be 5225mapped into a rectangle with any aspect ratio, \f$K(\cos\nu) : 5226K(\sin\nu)\f$, where \f$K(k)\f$ is the complete elliptic integral of 5227the first find, https://dlmf.nist.gov/19.2.E8. 5228 5229\section jacobi-sphere Conformal mapping of an ellipsoid to a sphere 5230 5231An essential tool in deriving conformal projections of an ellipsoid of 5232revolution is the conformal mapping of the ellipsoid onto a sphere. 5233This allows conformal projections of the sphere to be generalized to the 5234case of an ellipsoid of revolution. This conformal mapping is obtained 5235by using the ellipsoidal Mercator projection to map the ellipsoid to 5236the plane and then using the spherical Mercator projection to map the 5237plane onto the sphere. 5238 5239A similar construction is possible for a triaxial ellipsoid. Map each 5240octant of the ellipsoid onto a rectangle using the Jacobi projection. 5241The aspect ratio of this rectangle is 5242\f[ 5243(1+e_a^2)\,\Pi(-e_a^2, \cos\nu) : 5244(1-e_c^2)\,\Pi( e_c^2, \sin\nu). 5245\f] 5246Find the value of \f$\nu'\f$ such that this ratio equals 5247\f[ 5248K(\cos\nu') : K(\sin\nu'). 5249\f] 5250Map the rectangle onto the equivalent octant of the sphere using Guyou's 5251projection with parameter \f$\nu = \nu'\f$. This reduces to the 5252standard construction in the limit of an ellipsoid of revolution. 5253 5254\section jacobi-implementation An implementation of the projection 5255 5256The JacobiConformal class provides an implementation of the Jacobi 5257conformal projection is given here. <b>NOTE:</b> This is just sample 5258code. It is not part of GeographicLib itself. 5259 5260<center> 5261Back to \ref triaxial. Forward to \ref rhumb. Up to \ref contents. 5262</center> 5263 5264**********************************************************************/ 5265/** 5266\page rhumb Rhumb lines 5267 5268<center> 5269Back to \ref jacobi. Forward to \ref greatellipse. Up to \ref contents. 5270</center> 5271 5272The Rhumb and RhumbLine classes together with the 5273<a href="RhumbSolve.1.html">RhumbSolve</a> utility perform rhumb line 5274calculations. A rhumb line (also called a loxodrome) is a line of 5275constant azimuth on the surface of the ellipsoid. It is important for 5276historical reasons because sailing with a constant compass heading is 5277simpler than sailing the shorter geodesic course; see Osborne (2013). 5278The formulation of the problem on an ellipsoid is covered by Smart 5279(1946) and Carlton-Wippern (1992). Computational approaches are given 5280by Williams (1950) and Bennett (1996). My interest in this problem was 5281piqued by Botnev and Ustinov (2014) who discuss various techniques to 5282improve the accuracy of rhumb line calculations. The items of interest 5283here are: 5284 - Review of accurate formulas for the auxiliary latitudes. 5285 - The calculation of the area under a rhumb line. 5286 - Using divided differences to compute \f$\mu_{12}/\psi_{12}\f$ 5287 maintaining full accuracy. Two cases are treated: 5288 - If \f$f\f$ is small, Krüger's series for the transverse 5289 Mercator projection relate \f$\chi\f$ and \f$\mu\f$. 5290 - For arbitrary \f$f\f$, the divided difference formula for 5291 incomplete elliptic integrals of the second relates \f$\beta\f$ and 5292 \f$\mu\f$. 5293 . 5294 - Extending Clenshaw summation to compute the divided difference of a 5295 trigonometric sum. 5296 5297Go to 5298 - \ref rhumbform 5299 - \ref rhumblat 5300 - \ref rhumbarea 5301 - \ref divideddiffs 5302 - \ref dividedclenshaw 5303 5304References: 5305 - G. G. Bennett, 5306 <a href="https://doi.org/10.1017/S0373463300013151"> 5307 Practical Rhumb Line Calculations on the Spheroid</a> 5308 J. Navigation 49(1), 112--119 (1996). 5309 - F. W. Bessel, 5310 <a href="https://doi.org/10.1002/asna.201011352">The calculation 5311 of longitude and latitude from geodesic measurements (1825)</a>, 5312 Astron. Nachr. 331(8), 852--861 (2010); 5313 translated by C. F. F. Karney and R. E. Deakin; preprint: 5314 <a href="https://arxiv.org/abs/0908.1824">arXiv:0908.1824</a>. 5315 - V.A. Botnev, S.M. Ustinov, 5316 <a href="http://ntv.spbstu.ru/fulltext/T3.198.2014_05.PDF"> 5317 Metody resheniya pryamoy i obratnoy geodezicheskikh zadach s vysokoy 5318 tochnost'yu 5319 </a> (Methods for direct and inverse geodesic problems 5320 solving with high precision), St. Petersburg State Polytechnical 5321 University Journal 3(198), 49--58 (2014). 5322 - K. C. Carlton-Wippern 5323 <a href="https://doi.org/10.1017/S0373463300010791"> 5324 On Loxodromic Navigation</a>, 5325 J. Navigation 45(2), 292--297 (1992). 5326 - K. E. Engsager and K. Poder, 5327 <a href="http://icaci.org/files/documents/ICC_proceedings/ICC2007/documents/doc/THEME 2/oral 1/2.1.2 A HIGHLY ACCURATE WORLD WIDE ALGORITHM FOR THE TRANSVE.doc"> 5328 A highly accurate world wide algorithm for the 5329 transverse Mercator mapping (almost)</a>, 5330 Proc. XXIII Intl. Cartographic Conf. (ICC2007), Moscow (2007). 5331 - F. R. Helmert, 5332 <a href="https://doi.org/10.5281/zenodo.32050"> 5333 Mathematical and Physical Theories of Higher Geodesy, Part 1 (1880)</a>, 5334 Aeronautical Chart and Information Center (St. Louis, 1964), 5335 Chaps. 5--7. 5336 - W. M. Kahan and R. J. Fateman, 5337 <a href="https://www.cs.berkeley.edu/~fateman/papers/divdiff.pdf"> 5338 Symbolic computation of divided differences</a>, 5339 SIGSAM Bull. 33(3), 7--28 (1999) 5340 DOI: <a href="https://doi.org/10.1145/334714.334716"> 5341 10.1145/334714.334716</a>. 5342 - C. F. F. Karney, 5343 <a href="https://doi.org/10.1007/s00190-011-0445-3"> 5344 Transverse Mercator with an accuracy of a few nanometers</a>, 5345 J. Geodesy 85(8), 475--485 (Aug. 2011); 5346 addenda: <a href="https://geographiclib.sourceforge.io/tm-addenda.html"> 5347 tm-addenda.html</a>; 5348 preprint: 5349 <a href="https://arxiv.org/abs/1002.1417"> arXiv:1002.1417</a>; 5350 resource page: 5351 <a href="https://geographiclib.sourceforge.io/tm.html"> tm.html</a>. 5352 - C. F. F. Karney, 5353 <a href="https://doi.org/10.1007/s00190-012-0578-z"> 5354 Algorithms for geodesics</a>, 5355 J. Geodesy 87(1), 43--55 (2013); 5356 DOI: <a href="https://doi.org/10.1007/s00190-012-0578-z"> 5357 10.1007/s00190-012-0578-z</a>; 5358 addenda: <a href="https://geographiclib.sourceforge.io/geod-addenda.html"> 5359 geod-addenda.html</a>; 5360 resource page: 5361 <a href="https://geographiclib.sourceforge.io/geod.html"> geod.html</a>. 5362 - L. Krüger, 5363 <a href="https://doi.org/10.2312/GFZ.b103-krueger28"> Konforme 5364 Abbildung des Erdellipsoids in der Ebene</a> (Conformal mapping of 5365 the ellipsoidal earth to the plane), Royal Prussian Geodetic Institute, 5366 New Series 52, 172 pp. (1912). 5367 - P. Osborne, 5368 <a href="https://doi.org/10.5281/zenodo.35392"> 5369 The Mercator Projections</a> (2013), §2.5 and §6.5; 5370 DOI: <a href="https://doi.org/10.5281/zenodo.35392"> 5371 10.5281/zenodo.35392</a>. 5372 - W. M. Smart 5373 <a href="https://doi.org/10.1093/mnras/106.2.124"> 5374 On a Problem in Navigation</a> 5375 MNRAS 106(2), 124--127 (1946). 5376 - J. E. D. Williams 5377 <a href="https://doi.org/10.1017/S0373463300045549"> 5378 Loxodromic Distances on the Terrestrial Spheroid Journal</a>, 5379 J. Navigation 3(2), 133--140 (1950) 5380 5381\section rhumbform Formulation of the rhumb line problem 5382 5383The rhumb line can formulated in terms of three types of latitude, the 5384isometric latitude \f$\psi\f$ (this serves to define the course of rhumb 5385lines), the rectifying latitude \f$\mu\f$ (needed for computing 5386distances along rhumb lines), and the parametric latitude \f$\beta\f$ 5387(needed for dealing with rhumb lines that run along a parallel). These 5388are defined in terms of the geographical latitude \f$\phi\f$ by 5389\f[ 5390\begin{align} 5391 \frac{d\psi}{d\phi} &= \frac{\rho}R, \\ 5392 \frac{d\mu}{d\phi} &= \frac{\pi}{2M}\rho, \\ 5393\end{align} 5394\f] 5395where \f$\rho\f$ is the meridional radius of curvature, \f$R = 5396a\cos\beta\f$ is the radius of a circle of latitude, and \f$M\f$ is the 5397length of a quarter meridian (from the equator to the pole). 5398 5399Rhumb lines are straight in the Mercator projection, which maps a point 5400with geographical coordinates \f$ (\phi,\lambda) \f$ on the ellipsoid to 5401a point \f$ (\psi,\lambda) \f$. The azimuth \f$\alpha_{12}\f$ of a 5402rhumb line from \f$ (\phi_1,\lambda_1) \f$ to \f$ (\phi_2,\lambda_2) \f$ 5403is thus given by 5404\f[ 5405\tan\alpha_{12} = \frac{\lambda_{12}}{\psi_{12}}, 5406\f] 5407where the quadrant of \f$\alpha_{12}\f$ is determined by the signs of 5408the numerator and denominator of the right-hand side, \f$\lambda_{12} = 5409\lambda_2 - \lambda_1\f$, \f$\psi_{12} = \psi_2 - \psi_1\f$, and, 5410typically, \f$\lambda_{12}\f$ is reduced to the range \f$[-\pi,\pi]\f$ 5411(thus giving the course of the <i>shortest</i> rhumb line). 5412 5413The distance is given by 5414\f[ 5415\begin{align} 5416s_{12} &= \frac {2M}{\pi} \mu_{12} \sec\alpha_{12} \\ 5417 &= \frac {2M}{\pi} 5418\frac{\mu_{12}}{\psi_{12}} \sqrt{\lambda_{12}^2 + \psi_{12}^2}, 5419\end{align} 5420\f] 5421where \f$\mu_{12} = \mu_2 - \mu_1\f$. This relation is indeterminate if 5422\f$\phi_1 = \phi_2\f$, so we take the limits 5423\f$\psi_{12}\rightarrow0\f$ and \f$\mu_{12}\rightarrow0\f$ and apply 5424L'Hôpital's rule to yield 5425\f[ 5426\begin{align} 5427 s_{12} &= \frac {2M}{\pi} \frac{d\mu}{d\psi} \left|\lambda_{12}\right|\\ 5428&=a \cos\beta \left|\lambda_{12}\right|, 5429\end{align} 5430\f] 5431where the last relation is given by the defining equations for 5432\f$\psi\f$ and \f$\mu\f$. 5433 5434This provides a complete solution for rhumb lines. This formulation 5435entirely encapsulates the ellipsoidal shape of the earth via the 5436\ref auxlat; thus in the Rhumb class, the ellipsoidal 5437generalization is handled by the Ellipsoid class where the auxiliary 5438latitudes are defined. 5439 5440\section rhumblat Determining the auxiliary latitudes 5441 5442Here we brief develop the necessary formulas for the \ref auxlat. 5443 5444<b>Isometric latitude:</b> The equation for \f$\psi\f$ can be integrated 5445to give 5446\f[ 5447\psi = \sinh^{-1}\tan\phi - e\tanh^{-1}(e \sin\phi), 5448\f] 5449where \f$e = \sqrt{f(2-f)}\f$ is the eccentricity of the ellipsoid. To 5450invert this equation (to give \f$\phi\f$ in terms of \f$\psi\f$), it is 5451convenient to introduce the variables \f$\tau=\tan\phi\f$ and \f$\tau' = 5452\tan\chi = \sinh\psi\f$ (\f$\chi\f$ is the conformal latitude) which are 5453related by (Karney, 2011) 5454\f[ 5455\begin{align} 5456\tau' &= \tau \sqrt{1 + \sigma^2} - \sigma \sqrt{1 + \tau^2}, \\ 5457\sigma &= \sinh\bigl(e \tanh^{-1}(e \tau/\sqrt{1 + \tau^2}) \bigr). 5458\end{align} 5459\f] 5460The equation for \f$\tau'\f$ can be inverted to give \f$\tau\f$ in terms 5461of \f$\tau'\f$ using Newton's method with \f$\tau_0 = \tau'/(1-e^2)\f$ 5462as a starting guess; and, of course, \f$\phi\f$ and \f$\psi\f$ are then 5463given by 5464\f[ 5465\begin{align} 5466\phi &= \tan^{-1}\tau,\\ 5467\psi &= \sinh^{-1}\tau'. 5468\end{align} 5469\f] 5470This allows conversions to and from \f$\psi\f$ to be carried out for any 5471value of the flattening \f$f\f$; these conversions are implemented by 5472Ellipsoid::IsometricLatitude and Ellipsoid::InverseIsometricLatitude. 5473(For prolate ellipsoids, \f$f\f$ is negative and \f$e\f$ is imaginary, 5474and the equation for \f$\sigma\f$ needs to be recast in terms of the 5475tangent function.) 5476 5477For small values of \f$f\f$, Engsager and Poder (2007) express 5478\f$\chi\f$ as a trigonometric series in \f$\phi\f$. This series can be 5479reverted to give a series for \f$\phi\f$ in terms of \f$\chi\f$. Both 5480series can be efficiently evaluated using Clenshaw summation and this 5481provides a fast non-iterative way of making the conversions. 5482 5483<b>Parametric latitude:</b> This is given by 5484\f[ 5485\tan\beta = (1-f)\tan\phi, 5486\f] 5487which allows rapid and accurate conversions; these conversions are 5488implemented by Ellipsoid::ParametricLatitude and 5489Ellipsoid::InverseParametricLatitude. 5490 5491<b>Rectifying latitude:</b> Solving for distances on the meridian is 5492naturally carried out in terms of the parametric latitude instead of the 5493geographical latitude. This leads to a simpler elliptic integral which 5494is easier to evaluate and to invert. Helmert (1880, §5.11) notes 5495that the series for meridian distance in terms of \f$\beta\f$ converge 5496faster than the corresponding ones in terms of \f$\phi\f$. 5497 5498In terms of \f$\beta\f$, the rectifying latitude is given by 5499\f[ 5500\mu = \frac{\pi}{2E(ie')} E(\beta,ie'), 5501\f] 5502where \f$e'=e/\sqrt{1-e^2}\f$ is the second eccentricity and \f$E(k)\f$ 5503and \f$E(\phi,k)\f$ are the complete and incomplete elliptic integrals 5504of the second kind; see https://dlmf.nist.gov/19.2.ii. These can be 5505evaluated accurately for arbitrary flattening using the method given in 5506https://dlmf.nist.gov/19.36.i. To find \f$\beta\f$ in terms of 5507\f$\mu\f$, Newton's method can be used (noting that \f$dE(\phi,k)/d\phi 5508= \sqrt{1 - k^2\sin^2\phi}\f$); for a starting guess use \f$\beta_0 = 5509\mu\f$ (or use the first terms in the reverted series; see below). 5510These conversions are implemented by Ellipsoid::RectifyingLatitude and 5511Ellipsoid::InverseRectifyingLatitude. 5512 5513If the flattening is small, \f$\mu\f$ can be expressed as a series in 5514various ways. The most economical series is in terms of the third 5515flattening \f$ n = f/(2-f)\f$ and was found by Bessel (1825); see 5516Eq. 5.5.7 of Helmert (1880). Helmert (1880, Eq. 5.6.8) also gives the 5517reverted series (finding \f$\beta\f$ given \f$\mu\f$). These series are 5518used by the Geodesic class where the coefficients are \f$C_{1j}\f$ and 5519\f$C_{1j}'\f$; see Eqs. (18) and (21) of Karney (2013) and \ref 5520geodseries. (Make the replacements, \f$\sigma\rightarrow\beta\f$, 5521\f$\tau\rightarrow\mu\f$, \f$\epsilon\rightarrow n\f$, to convert the 5522notation of the geodesic problem to the problem at hand.) The series 5523are evaluated by Clenshaw summation. 5524 5525These relations allow inter-conversions between the various latitudes 5526\f$\phi\f$, \f$\psi\f$, \f$\chi\f$, \f$\beta\f$, \f$\mu\f$ to be carried 5527out simply and accurately. The approaches using series apply only if 5528\f$f\f$ is small. The others apply for arbitrary values of \f$f\f$. 5529 5530\section rhumbarea The area under a rhumb line 5531 5532The area between a rhumb line and the equator is given by 5533\f[ 5534S_{12} = \int_{\lambda_1}^{\lambda_2} c^2 \sin\xi \,d\lambda, 5535\f] 5536where \f$c\f$ is the authalic radius and \f$\xi\f$ is the authalic 5537latitude. Express \f$\sin\xi\f$ in terms of the conformal latitude 5538\f$\chi\f$ and expand as a series in the third flattening \f$n\f$. This 5539can be expressed in terms of powers of \f$\sin\chi\f$. Substitute 5540\f$\sin\chi=\tanh\psi\f$, where \f$\psi\f$ is the isometric latitude. 5541For a rhumb line we have 5542\f[ 5543\begin{align} 5544\psi &= m(\lambda-\lambda_0),\\ 5545m &= \frac{\psi_2 - \psi_1}{\lambda_2 - \lambda_1}. 5546\end{align} 5547\f] 5548Performing the integral over \f$\lambda\f$ gives 5549\f[ 5550S_{12} = c^2 \lambda_{12} \left<\sin\xi\right>_{12}, 5551\f] 5552where \f$\left<\sin\xi\right>_{12}\f$ is the mean value of \f$\sin\xi\f$ 5553given by 5554\f[ 5555\begin{align} 5556\left<\sin\xi\right>_{12} &= \frac{S(\chi_2) - S(\chi_1)}{\psi_2 - \psi_1},\\ 5557S(\chi) &= \log\sec\chi + \sum_{l=1} R_l\cos(2l\chi), 5558\end{align} 5559\f] 5560\f$\log\f$ is the natural logarithm, and \f$R_l = O(n^l)\f$ is given as 5561a series in \f$n\f$ below. In the spherical limit, the sum vanishes. 5562 5563Note the simple way that longitude enters into the expression for the 5564area. In the limit \f$\chi_2 \rightarrow \chi_1\f$, we can apply 5565l'Hôpital's rule 5566\f[ 5567\left<\sin\xi\right>_{12} 5568\rightarrow \frac{dS(\chi_1)/d\chi_1}{\sec\chi_1} 5569=\sin\xi_1, 5570\f] 5571as expected. 5572 5573In order to maintain accuracy, particularly for rhumb lines which nearly 5574follow a parallel, evaluate \f$\left<\sin\xi\right>_{12}\f$ using 5575divided differences (see the \ref divideddiffs "next section") and use 5576Clenshaw summation to evaluate the sum (see the \ref dividedclenshaw 5577"last section"). 5578 5579Here is the series expansion accurate to 10th order, found by the Maxima 5580script <a href="rhumbarea.mac">rhumbarea.mac</a>: 5581 5582\verbatim 5583R[1] = - 1/3 * n 5584 + 22/45 * n^2 5585 - 356/945 * n^3 5586 + 1772/14175 * n^4 5587 + 41662/467775 * n^5 5588 - 114456994/638512875 * n^6 5589 + 258618446/1915538625 * n^7 5590 - 1053168268/37574026875 * n^8 5591 - 9127715873002/194896477400625 * n^9 5592 + 33380126058386/656284056553125 * n^10; 5593R[2] = - 2/15 * n^2 5594 + 106/315 * n^3 5595 - 1747/4725 * n^4 5596 + 18118/155925 * n^5 5597 + 51304574/212837625 * n^6 5598 - 248174686/638512875 * n^7 5599 + 2800191349/14801889375 * n^8 5600 + 10890707749202/64965492466875 * n^9 5601 - 3594078400868794/10719306257034375 * n^10; 5602R[3] = - 31/315 * n^3 5603 + 104/315 * n^4 5604 - 23011/51975 * n^5 5605 + 1554472/14189175 * n^6 5606 + 114450437/212837625 * n^7 5607 - 8934064508/10854718875 * n^8 5608 + 4913033737121/21655164155625 * n^9 5609 + 591251098891888/714620417135625 * n^10; 5610R[4] = - 41/420 * n^4 5611 + 274/693 * n^5 5612 - 1228489/2027025 * n^6 5613 + 3861434/42567525 * n^7 5614 + 1788295991/1550674125 * n^8 5615 - 215233237178/123743795175 * n^9 5616 + 95577582133463/714620417135625 * n^10; 5617R[5] = - 668/5775 * n^5 5618 + 1092376/2027025 * n^6 5619 - 3966679/4343625 * n^7 5620 + 359094172/10854718875 * n^8 5621 + 7597613999411/3093594879375 * n^9 5622 - 378396252233936/102088631019375 * n^10; 5623R[6] = - 313076/2027025 * n^6 5624 + 4892722/6081075 * n^7 5625 - 1234918799/834978375 * n^8 5626 - 74958999806/618718975875 * n^9 5627 + 48696857431916/9280784638125 * n^10; 5628R[7] = - 3189007/14189175 * n^7 5629 + 930092876/723647925 * n^8 5630 - 522477774212/206239658625 * n^9 5631 - 2163049830386/4331032831125 * n^10; 5632R[8] = - 673429061/1929727800 * n^8 5633 + 16523158892/7638505875 * n^9 5634 - 85076917909/18749059875 * n^10; 5635R[9] = - 39191022457/68746552875 * n^9 5636 + 260863656866/68746552875 * n^10; 5637R[10] = - 22228737368/22915517625 * n^10; 5638\endverbatim 5639 5640\section divideddiffs Use of divided differences 5641 5642Despite our ability to compute latitudes accurately, the way that 5643distances enter into the solution involves the ratio 5644\f$\mu_{12}/\psi_{12}\f$; the numerical calculation of this term is 5645subject to catastrophic round-off errors when \f$\phi_1\f$ and 5646\f$\phi_2\f$ are close. A simple solution, suggested by Bennett (1996), 5647is to extend the treatment of rhumb lines along parallels to this case, 5648i.e., to replace the ratio by the derivative evaluated at the midpoint. 5649However this is not entirely satisfactory: you have to pick the 5650transition point where the derivative takes over from the ratio of 5651differences; and, near this transition point, many bits of accuracy will 5652be lost (I estimate that about 1/3 of bits are lost, leading to errors 5653on the order of 0.1 mm for double precision). Note too that this 5654problem crops up even in the spherical limit. 5655 5656It turns out that we can do substantially better than this and maintain 5657full double precision accuracy. Indeed Botnev and Ustinov provide 5658formulas which allow \f$\mu_{12}/\psi_{12}\f$ to be computed accurately 5659(but the formula for \f$\mu_{12}\f$ applies only for small flattening). 5660 5661Here I give a more systematic treatment using the algebra of <i>divided 5662differences</i>. Many readers will be already using this technique, 5663e.g., when writing, for example, 5664\f[ 5665 \frac{\sin(2x) - \sin(2y)}{x-y} = 2\frac{\sin(x-y)}{x-y}\cos(x+y). 5666\f] 5667However, Kahan and Fateman (1999) provide an extensive set of rules 5668which allow the technique to be applied to a wide range of problems. 5669(The classes LambertConformalConic and AlbersEqualArea use this 5670technique to improve the accuracy.) 5671 5672To illustrate the technique, consider the relation between \f$\psi\f$ 5673and \f$\chi\f$, 5674\f[ 5675 \psi = \sinh^{-1}\tan\chi. 5676\f] 5677The divided difference operator is defined by 5678\f[ 5679 \Delta[f](x,y) = 5680\begin{cases} 5681df(x)/dx, & \text{if $x=y$,} \\ 5682\displaystyle\frac{f(x)-f(y)}{x-y}, & \text{otherwise.} 5683\end{cases} 5684\f] 5685Many of the rules for differentiation apply to divided differences; in 5686particular, we can use the chain rule to write 5687\f[ 5688\frac{\psi_1 - \psi_2}{\chi_1 - \chi_2} 5689= \Delta[\sinh^{-1}](\tan\chi_1,\tan\chi_2) \times 5690 \Delta[\tan](\chi_1,\chi_2). 5691\f] 5692 5693Kahan and Fateman catalog the divided difference formulas for all the 5694elementary functions. In this case, we need 5695\f[ 5696\begin{align} 5697\Delta[\tan](x,y) &= \frac{\tan(x-y)}{x-y} (1 + \tan x\tan y),\\ 5698\Delta[\sinh^{-1}](x,y) &= \frac1{x-y} 5699\sinh^{-1}\biggl(\frac{(x-y)(x+y)}{x\sqrt{1+y^2}+y\sqrt{1+x^2}}\biggr). 5700\end{align} 5701\f] 5702The crucial point in these formulas is that the right hand sides can be 5703evaluated accurately even if \f$x-y\f$ is small. (I've only included 5704the basic results here; Kahan and Fateman supplement these with the 5705derivatives if \f$x-y\f$ vanishes or the direct ratios if \f$x-y\f$ is 5706not small.) 5707 5708To complete the computation of \f$\mu_{12}/\psi_{12}\f$, we now need 5709\f$(\mu_1 - \mu_2)/(\chi_1 - \chi_2)\f$, i.e., we need the divided 5710difference of the function that converts the conformal latitude to 5711rectifying latitude. We could go through the chain of relations between 5712these quantities. However, we can take a short cut and recognize that 5713this function was given as a trigonometric series by Krüger (1912) 5714in his development of the transverse Mercator projection. This is also 5715given by Eqs. (5) and (35) of Karney (2011) with the replacements 5716\f$\zeta \rightarrow \mu\f$ and \f$\zeta' \rightarrow \chi\f$. The 5717coefficients appearing in this series and the reverted series Eqs. (6) 5718and (36) are already computed by the TransverseMercator class. The 5719series can be readily converted to divided difference form (see the 5720example at the beginning of this section) and Clenshaw summation can be 5721used to evaluate it (see below). 5722 5723The approach of using the series for the transverse Mercator projection 5724limits the applicability of the method to \f$\left|f\right|\lt 0.01\f$. 5725If we want to extend the method to arbitrary flattening we need to 5726compute \f$\Delta[E](x,y;k)\f$. The necessary relation is the "addition 5727theorem" for the incomplete elliptic integral of the second kind given 5728in https://dlmf.nist.gov/19.11.E2. This can be converted in the 5729following divided difference formula 5730\f[ 5731\Delta[E](x,y;k) 5732=\begin{cases} 5733\sqrt{1 - k^2\sin^2x}, & \text{if $x=y$,} \\ 5734\displaystyle \frac{E(x,k)-E(y,k)}{x-y}, & \text{if $xy \le0$,}\\ 5735\displaystyle 5736\biggl(\frac{E(z,k)}{\sin z} - k^2 \sin x \sin y\biggr)\frac{\sin z}{x-y}, 5737&\text{otherwise,} 5738\end{cases} 5739\f] 5740where the angle \f$z\f$ is given by 5741\f[ 5742\begin{align} 5743\sin z &= \frac{2t}{1 + t^2},\quad\cos z = \frac{(1-t)(1+t)}{1 + t^2},\\ 5744t &= 5745\frac{(x-y)\Delta[\sin](x,y)} 5746{\sin x\sqrt{1 - k^2\sin^2y} + \sin y\sqrt{1 - k^2\sin^2x}} 5747\frac{\sin x + \sin y}{\cos x + \cos y}. 5748\end{align} 5749\f] 5750We also need to apply the divided difference formulas to the conversions 5751from \f$\phi\f$ to \f$\beta\f$ and \f$\phi\f$ to \f$\psi\f$; but these 5752all involve elementary functions and the techniques given in Kahan and 5753Fateman can be used. 5754 5755The end result is that the Rhumb class allows the computation of all 5756rhumb lines for any flattening with full double precision accuracy (the 5757maximum error is about 10 nanometers). I've kept the implementation 5758simple, which results in rather a lot of repeated evaluations of 5759quantities. However, in this case, the need for clarity trumps the 5760desire for speed. 5761 5762\section dividedclenshaw Clenshaw evaluation of differenced sums 5763 5764The use of 5765<a href="https://en.wikipedia.org/wiki/Clenshaw_algorithm#Meridian_arc_length_on_the_ellipsoid"> 5766Clenshaw summation</a> for summing series of the form, 5767\f[ 5768g(x) = \sum_{k=1}^N c_k \sin kx, 5769\f] 5770is well established. However when computing divided differences, we are 5771interested in evaluating 5772\f[ 5773g(x)-g(y) = \sum_{k=1}^N 2 c_k 5774\sin\bigl({\textstyle\frac12}k(x-y)\bigr) 5775\cos\bigl({\textstyle\frac12}k(x+y)\bigr). 5776\f] 5777Clenshaw summation can be used in this case if we simultaneously compute 5778\f$g(x)+g(y)\f$ and perform a matrix summation, 5779\f[ 5780\mathsf G(x,y) = \begin{bmatrix} 5781(g(x) + g(y)) / 2\\ 5782(g(x) - g(y)) / (x - y) 5783\end{bmatrix} = \sum_{k=1}^N c_k \mathsf F_k(x,y), 5784\f] 5785where 5786\f[ 5787\mathsf F_k(x,y)= 5788\begin{bmatrix} 5789 \cos kd \sin kp\\ 5790 {\displaystyle\frac{\sin kd}d} \cos kp 5791\end{bmatrix}, 5792\f] 5793\f$d=\frac12(x-y)\f$, \f$p=\frac12(x+y)\f$, and, in the limit 5794\f$d\rightarrow0\f$, \f$(\sin kd)/d \rightarrow k\f$. The first element 5795of \f$\mathsf G(x,y)\f$ is the average value of \f$g\f$ and the second 5796element, the divided difference, is the average slope. \f$\mathsf 5797F_k(x,y)\f$ satisfies the recurrence relation 5798\f[ 5799 \mathsf F_{k+1}(x,y) = 5800 \mathsf A(x,y) \mathsf F_k(x,y) - \mathsf F_{k-1}(x,y), 5801\f] 5802where 5803\f[ 5804 \mathsf A(x,y) = 2\begin{bmatrix} 5805 \cos d \cos p & -d\sin d \sin p \\ 5806- {\displaystyle\frac{\sin d}d} \sin p & \cos d \cos p 5807\end{bmatrix}, 5808\f] 5809and \f$\lim_{d\rightarrow0}(\sin d)/d = 1\f$. The standard Clenshaw 5810algorithm can now be applied to yield 5811\f[ 5812\begin{align} 5813\mathsf B_{N+1} &= \mathsf B_{N+2} = \mathsf 0, \\ 5814\mathsf B_k &= \mathsf A \mathsf B_{k+1} - \mathsf B_{k+2} + 5815c_k \mathsf I, \qquad\text{for $N\ge k \ge 1$},\\ 5816\mathsf G(x,y) &= \mathsf B_1 \mathsf F_1(x,y), 5817\end{align} 5818\f] 5819where \f$\mathsf B_k\f$ are \f$2\times2\f$ matrices. The divided 5820difference \f$\Delta[g](x,y)\f$ is given by the second element of 5821\f$\mathsf G(x,y)\f$. 5822 5823The same basic recursion applies to the more general case, 5824\f[ 5825g(x) = \sum_{k=0}^N c_k \sin\bigl( (k+k_0)x + x_0\bigr). 5826\f] 5827For example, the sum area arising in the computation of geodesic areas, 5828\f[ 5829\sum_{k=0}^N c_k\cos\bigl((2k+1)\sigma) 5830\f] 5831is given by \f$x=2\sigma\f$, \f$x_0=\frac12\pi\f$, \f$k_0=\frac12\f$. 5832Again we consider the matrix sum, 5833\f[ 5834\mathsf G(x,y) = \begin{bmatrix} 5835(g(x) + g(y)) / 2\\ 5836(g(x) - g(y)) / (x - y) 5837\end{bmatrix} = \sum_{k=0}^N c_k \mathsf F_k(x,y), 5838\f] 5839where 5840\f[ 5841\mathsf F_k(x,y)= 5842\begin{bmatrix} 5843 \cos\bigl( (k+k_0)d \bigr) \sin \bigl( (k+k_0)p + x_0 \bigr)\\ 5844 {\displaystyle\frac{\sin\bigl( (k+k_0)d \bigr)}d} 5845 \cos \bigl( (k+k_0)p + x_0 \bigr) 5846\end{bmatrix}. 5847\f] 5848The recursion for \f$\mathsf B_k\f$ is identical to the previous case; 5849in particular, the expression for \f$\mathsf A(x,y)\f$ remains 5850unchanged. The result for the sum is 5851\f[ 5852\mathsf G(x,y) = 5853 (c_0\mathsf I - \mathsf B_2) \mathsf F_0(x,y) 5854 + \mathsf B_1 \mathsf F_1(x,y). 5855\f] 5856 5857<center> 5858Back to \ref jacobi. Forward to \ref greatellipse. Up to \ref contents. 5859</center> 5860 5861**********************************************************************/ 5862/** 5863\page greatellipse Great Ellipses 5864 5865<center> 5866Back to \ref rhumb. Forward to \ref transversemercator. Up to \ref contents. 5867</center> 5868 5869Great ellipses are sometimes proposed (Williams, 1996; Pallikaris & 5870Latsas, 2009) as alternatives to geodesics for the purposes of 5871navigation. This is predicated on the assumption that solving the 5872geodesic problems is complex and costly. These assumptions are no 5873longer true, and geodesics should normally be used in place of great 5874ellipses. This is discussed in more detail in \ref gevsgeodesic. 5875 5876Solutions of the great ellipse problems implemented for MATLAB and 5877Octave are provided by 5878 - gedoc: briefly describe the routines 5879 - gereckon: solve the direct great ellipse problem 5880 - gedistance: solve the inverse great ellipse problem 5881 . 5882At this time, there is C++ support in GeographicLib for great 5883ellipses. 5884 5885References: 5886 - P. D. Thomas, 5887 <a href="https://apps.dtic.mil/docs/citations/AD0627893"> 5888 Mathematical Models for Navigation Systems</a>, 5889 TR-182 (U.S. Naval Oceanographic Office, 1965). 5890 - B. R. Bowring, 5891 <a href="https://doi.org/10.1007/BF02521760"> 5892 The direct and inverse solutions for the great elliptic line on the 5893 reference ellipsoid</a>, Bull. Geod. 58, 101--108 (1984). 5894 - M. A. Earle, 5895 A vector solution for navigation on a great ellipse, 5896 J. Navigation 53(3), 473--481 (2000). 5897 - M. A. Earle, 5898 <a href="https://doi.org/10.1017/S037346330800475X"> 5899 Vector solutions for azimuth</a>, 5900 J. Navigation 61(3), 537--545 (2008). 5901 - C. F. F. Karney, 5902 <a href="https://doi.org/10.1007/s00190-012-0578-z"> 5903 Algorithms for geodesics</a>, J. Geodesy 87(1), 43--55 (2013); 5904 addenda: <a href="https://geographiclib.sourceforge.io/geod-addenda.html"> 5905 geod-addenda.html</a>. 5906 - A. Pallikaris & G. Latsas, 5907 <a href="https://doi.org/1017/S0373463309005323"> 5908 New algorithm for great elliptic sailing (GES)</a>, 5909 J. Navigation 62(3), 493--507 (2009). 5910 - A. Pallikaris, L. Tsoulos, & D. Paradissis, 5911 New meridian arc formulas for sailing calculations in navigational 5912 GIS, International Hydrographic Review, 24--34 (May 2009). 5913 - L. E. Sjöberg, 5914 <a href="https://doi.org/10.2478/v10156-011-0040-9"> 5915 Solutions to the direct and inverse navigation problems on the great 5916 ellipse</a>, J. Geodetic Science 2(3), 200--205 (2012). 5917 - R. Williams, 5918 <a href="https://doi.org/10.1017/S0373463300013333"> 5919 The Great Ellipse on the Surface of the Spheroid</a>, 5920 J. Navigation 49(2), 229--234 (1996). 5921 - T. Vincenty, 5922 <a href="https://www.ngs.noaa.gov/PUBS_LIB/inverse.pdf"> 5923 Direct and Inverse Solutions of Geodesics on the Ellipsoid with 5924 Application of Nested Equations</a>, 5925 Survey Review 23(176), 88--93 (1975). 5926 - Wikipedia page, <a href="https://en.wikipedia.org/wiki/Great_ellipse"> 5927 Great ellipse</a>. 5928 5929Go to 5930 - \ref geformulation 5931 - \ref gearea 5932 - \ref gevsgeodesic 5933 5934\section geformulation Solution of great ellipse problems 5935 5936Adopt the usual notation for the ellipsoid: equatorial semi-axis 5937\f$a\f$, polar semi-axis \f$b\f$, flattening \f$f = (a-b)/a\f$, 5938eccentricity \f$e = \sqrt{f(2-f)}\f$, second eccentricity \f$e' = 5939e/(1-f)\f$, and third flattening \f$n=(a-b)/(a+b)=f/(2-f)\f$. 5940 5941There are several ways in which an ellipsoid can be mapped into a sphere 5942converting the great ellipse into a great circle. The simplest ones 5943entail scaling the ellipsoid in the \f$\hat z\f$ direction, the 5944direction of the axis of rotation, scaling the ellipsoid radially, or a 5945combination of the two. 5946 5947One such combination (scaling by \f$a^2/b\f$ in the \f$\hat z\f$ 5948direction, following by a radial scaling to the sphere) preserves the 5949geographical latitude \f$\phi\f$. This enables a great ellipse to be 5950plotted on a chart merely by determining way points on the corresponding 5951great circle and transferring them directly on the chart. In this 5952exercise the flattening of the ellipsoid can be <i>ignored</i>! 5953 5954Bowring (1984), Williams (1996), Earle (2000, 2008) and Pallikaris & 5955Latsas (2009), scale the ellipsoid radially onto a sphere preserving the 5956geocentric latitude \f$\theta\f$. More convenient than this is to scale 5957the ellipsoid along \f$\hat z\f$ onto the sphere, as is done by 5958Thomas (1965) and Sjöberg (2012), thus preserving the parametric 5959latitude \f$\beta\f$. The advantage of this "parametric" mapping is 5960that Bessel's rapidly converging series for meridian arc in terms of 5961parametric latitude can be used (a possibility that is overlooked by 5962Sjöberg). 5963 5964The full parametric mapping is: 5965 - The geographic latitude \f$\phi\f$ on the ellipsoid maps to the 5966 parametric latitude \f$\beta\f$ on the sphere, 5967 where 5968 \f[a\tan\beta = b\tan\phi.\f] 5969 - The longitude \f$\lambda\f$ is unchanged. 5970 - The azimuth \f$\alpha\f$ on the ellipsoid maps to an azimuth 5971 \f$\gamma\f$ on the sphere where 5972 \f[ 5973 \begin{align} 5974 \tan\alpha &= \frac{\tan\gamma}{\sqrt{1-e^2\cos^2\beta}}, \\ 5975 \tan\gamma &= \frac{\tan\alpha}{\sqrt{1+e'^2\cos^2\phi}}, 5976 \end{align} 5977 \f] 5978 and the quadrants of \f$\alpha\f$ and \f$\gamma\f$ are the same. 5979 - Positions on the great circle of radius \f$a\f$ are parametrized by 5980 arc length \f$\sigma\f$ measured from the northward crossing of the 5981 equator. The great ellipse has semi-axes \f$a\f$ and 5982 \f$b'=a\sqrt{1-e^2\cos^2\gamma_0}\f$, where \f$\gamma_0\f$ is the 5983 great-circle azimuth at the northward equator crossing, and 5984 \f$\sigma\f$ is the parametric angle on the ellipse. [In contrast, 5985 the ellipse giving distances on a geodesic has semi-axes 5986 \f$b\sqrt{1+e'^2\cos^2\alpha_0}\f$ and \f$b\f$.] 5987 . 5988To determine the distance along the ellipse in terms of \f$\sigma\f$ and 5989vice versa, the series for distance \f$s\f$ and for \f$\tau\f$ given in 5990\ref geodseries can be used. The direct and inverse great ellipse 5991problems are now simply solved by mapping the problem to the sphere, 5992solving the resulting great circle problem, and mapping this back onto 5993the ellipsoid. 5994 5995\section gearea The area under a great ellipse 5996 5997The area between the segment of a great ellipse and the equator can be 5998found by very similar methods to those used for geodesic areas; see 5999<a href="https://doi.org/10.1179/003962689791474267"> Danielsen 6000(1989)</a>. The notation here is similar to that employed by 6001<a href="https://doi.org/10.1007/s00190-012-0578-z"> Karney 6002(2013)</a>. 6003\f[ 6004\begin{align} 6005S_{12} &= S(\sigma_2) - S(\sigma_1) \\ 6006S(\sigma) &= c^2\gamma + e^2 a^2 \cos\gamma_0 \sin\gamma_0 I_4(\sigma)\\ 6007c^2 &= {\textstyle\frac12}\bigl(a^2 + b^2 (\tanh^{-1}e)/e\bigr) 6008\end{align} 6009\f] 6010\f[ 6011I_4(\sigma) = - \sqrt{1+e'^2}\int 6012\frac{r(e'^2) - r(k^2\sin^2\sigma)}{e'^2 - k^2\sin^2\sigma} 6013\frac{\sin\sigma}2 \,d\sigma 6014\f] 6015\f[ 6016\begin{align} 6017k &= e' \cos\gamma_0,\\ 6018r(x) &= \sqrt{1+x} + (\sinh^{-1}\sqrt x)/\sqrt x. 6019\end{align} 6020\f] 6021Expand in terms of the third flattening of the ellipsoid, \f$n\f$, and the 6022third flattening of the great ellipse, \f$\epsilon=(a-b')/(a+b')\f$, by 6023substituting 6024\f[ 6025\begin{align} 6026e'&=\frac{2\sqrt n}{1-n},\\ 6027k&=\frac{1+n}{1-n} \frac{2\sqrt{\epsilon}}{1+\epsilon}, 6028\end{align} 6029\f] 6030to give 6031\f[ 6032I_4(\sigma) = \sum_{l = 0}^\infty G_{4l}\cos \bigl((2l+1)\sigma\bigr). 6033\f] 6034Compared to the area under a geodesic, we have 6035- \f$\gamma\f$ and \f$\gamma_0\f$ instead of \f$\alpha\f$ and 6036 \f$\alpha_0\f$. In both cases, these are azimuths on the auxiliary 6037 sphere; however, for the geodesic, they are also the azimuths on the 6038 ellipsoid. 6039- \f$r(x) = \bigl(1+t(x)\bigr)/\sqrt{1+x}\f$ instead of \f$t(x)\f$ with 6040 a balancing factor of \f$\sqrt{1+e'^2}\f$ appearing in front of the 6041 integral. These changes are because expressing 6042 \f$\sin\phi\,d\lambda\f$ in terms of \f$\sigma\f$ is a little more 6043 complicated with great ellipses. (Don't worry about the addition of 6044 \f$1\f$ to \f$t(x)\f$; that's immaterial.) 6045- the factors involving \f$n\f$ in the expression for \f$k\f$ in terms 6046 of \f$\epsilon\f$. This is because \f$k\f$ is defined in terms of 6047 \f$e'\f$, whereas it is \f$e\cos\gamma_0\f$ that plays the role of the 6048 eccentricity for the great ellipse. 6049 6050Here is the series expansion accurate to 10th order, found by 6051<a href="gearea.mac">gearea.mac</a>: 6052 6053\verbatim 6054G4[0] = + (1/6 + 7/30 * n + 8/105 * n^2 + 4/315 * n^3 + 16/3465 * n^4 + 20/9009 * n^5 + 8/6435 * n^6 + 28/36465 * n^7 + 32/62985 * n^8 + 4/11305 * n^9) 6055 - (3/40 + 12/35 * n + 589/840 * n^2 + 1063/1155 * n^3 + 14743/15015 * n^4 + 14899/15015 * n^5 + 254207/255255 * n^6 + 691127/692835 * n^7 + 1614023/1616615 * n^8) * eps 6056 + (67/280 + 7081/5040 * n + 5519/1320 * n^2 + 6417449/720720 * n^3 + 708713/45045 * n^4 + 2700154/109395 * n^5 + 519037063/14549535 * n^6 + 78681626/1616615 * n^7) * eps^2 6057 - (29597/40320 + 30013/5280 * n + 33759497/1441440 * n^2 + 100611307/1441440 * n^3 + 16639623457/98017920 * n^4 + 3789780779/10581480 * n^5 + 1027832503/1511640 * n^6) * eps^3 6058 + (357407/147840 + 19833349/823680 * n + 61890679/480480 * n^2 + 97030756063/196035840 * n^3 + 2853930388817/1862340480 * n^4 + 15123282583393/3724680960 * n^5) * eps^4 6059 - (13200233/1537536 + 306285589/2882880 * n + 26279482199/37340160 * n^2 + 3091446335399/931170240 * n^3 + 93089556575647/7449361920 * n^4) * eps^5 6060 + (107042267/3294720 + 253176989449/522762240 * n + 57210830762263/14898723840 * n^2 + 641067300459403/29797447680 * n^3) * eps^6 6061 - (51544067373/398295040 + 38586720036247/17027112960 * n + 104152290127363/4966241280 * n^2) * eps^7 6062 + (369575321823/687964160 + 1721481081751393/158919720960 * n) * eps^8 6063 - 10251814360817/4445306880 * eps^9; 6064G4[1] = + (1/120 + 4/105 * n + 589/7560 * n^2 + 1063/10395 * n^3 + 14743/135135 * n^4 + 14899/135135 * n^5 + 254207/2297295 * n^6 + 691127/6235515 * n^7 + 1614023/14549535 * n^8) * eps 6065 - (53/1680 + 847/4320 * n + 102941/166320 * n^2 + 1991747/1441440 * n^3 + 226409/90090 * n^4 + 3065752/765765 * n^5 + 24256057/4157010 * n^6 + 349229428/43648605 * n^7) * eps^2 6066 + (4633/40320 + 315851/332640 * n + 5948333/1441440 * n^2 + 11046565/864864 * n^3 + 9366910279/294053760 * n^4 + 23863367599/349188840 * n^5 + 45824943037/349188840 * n^6) * eps^3 6067 - (8021/18480 + 39452953/8648640 * n + 3433618/135135 * n^2 + 29548772933/294053760 * n^3 + 44355142973/139675536 * n^4 + 4771229132843/5587021440 * n^5) * eps^4 6068 + (2625577/1537536 + 5439457/247104 * n + 353552588953/2352430080 * n^2 + 405002114215/558702144 * n^3 + 61996934629789/22348085760 * n^4) * eps^5 6069 - (91909777/13178880 + 2017395395921/18819440640 * n + 51831652526149/59594895360 * n^2 + 1773086701957889/357569372160 * n^3) * eps^6 6070 + (35166639971/1194885120 + 26948019211109/51081338880 * n + 7934238355871/1596291840 * n^2) * eps^7 6071 - (131854991623/1031946240 + 312710596037369/119189790720 * n) * eps^8 6072 + 842282436291/1481768960 * eps^9; 6073G4[2] = + (1/560 + 29/2016 * n + 1027/18480 * n^2 + 203633/1441440 * n^3 + 124051/450450 * n^4 + 1738138/3828825 * n^5 + 98011493/145495350 * n^6 + 4527382/4849845 * n^7) * eps^2 6074 - (533/40320 + 14269/110880 * n + 908669/1441440 * n^2 + 15253627/7207200 * n^3 + 910103119/163363200 * n^4 + 2403810527/193993800 * n^5 + 746888717/30630600 * n^6) * eps^3 6075 + (2669/36960 + 2443153/2882880 * n + 1024791/200200 * n^2 + 10517570057/490089600 * n^3 + 164668999127/2327925600 * n^4 + 1826633124599/9311702400 * n^5) * eps^4 6076 - (5512967/15375360 + 28823749/5765760 * n + 31539382001/871270400 * n^2 + 1699098121381/9311702400 * n^3 + 287618085731/398361600 * n^4) * eps^5 6077 + (22684703/13178880 + 25126873327/896163840 * n + 10124249914577/42567782400 * n^2 + 836412216748957/595948953600 * n^3) * eps^6 6078 - (3259030001/398295040 + 2610375232847/17027112960 * n + 2121882247763/1418926080 * n^2) * eps^7 6079 + (13387413913/343982080 + 939097138279/1135140864 * n) * eps^8 6080 - 82722916855/444530688 * eps^9; 6081G4[3] = + (5/8064 + 23/3168 * n + 1715/41184 * n^2 + 76061/480480 * n^3 + 812779/1782144 * n^4 + 9661921/8953560 * n^5 + 40072069/18106088 * n^6) * eps^3 6082 - (409/59136 + 10211/109824 * n + 46381/73920 * n^2 + 124922951/43563520 * n^3 + 12524132449/1241560320 * n^4 + 30022391821/1022461440 * n^5) * eps^4 6083 + (22397/439296 + 302399/384384 * n + 461624513/74680320 * n^2 + 1375058687/41385344 * n^3 + 4805085120841/34763688960 * n^4) * eps^5 6084 - (14650421/46126080 + 17533571183/3136573440 * n + 1503945368767/29797447680 * n^2 + 43536234862451/139054755840 * n^3) * eps^6 6085 + (5074867067/2788065280 + 479752611137/13243310080 * n + 1228808683449/3310827520 * n^2) * eps^7 6086 - (12004715823/1203937280 + 17671119291563/79459860480 * n) * eps^8 6087 + 118372499107/2222653440 * eps^9; 6088G4[4] = + (7/25344 + 469/109824 * n + 13439/411840 * n^2 + 9282863/56010240 * n^3 + 37558503/59121920 * n^4 + 44204289461/22348085760 * n^5) * eps^4 6089 - (5453/1317888 + 58753/823680 * n + 138158857/224040960 * n^2 + 191056103/53209728 * n^3 + 712704605341/44696171520 * n^4) * eps^5 6090 + (28213/732160 + 331920271/448081920 * n + 2046013913/283785216 * n^2 + 11489035343/241274880 * n^3) * eps^6 6091 - (346326947/1194885120 + 11716182499/1891901440 * n + 860494893431/12770334720 * n^2) * eps^7 6092 + (750128501/386979840 + 425425087409/9287516160 * n) * eps^8 6093 - 80510858479/6667960320 * eps^9; 6094G4[5] = + (21/146432 + 23/8320 * n + 59859/2263040 * n^2 + 452691/2687360 * n^3 + 21458911/26557440 * n^4) * eps^5 6095 - (3959/1464320 + 516077/9052160 * n + 51814927/85995520 * n^2 + 15444083489/3611811840 * n^3) * eps^6 6096 + (1103391/36208640 + 120920041/171991040 * n + 18522863/2263040 * n^2) * eps^7 6097 - (92526613/343982080 + 24477436759/3611811840 * n) * eps^8 6098 + 1526273559/740884480 * eps^9; 6099G4[6] = + (11/133120 + 1331/696320 * n + 145541/6615040 * n^2 + 46863487/277831680 * n^3) * eps^6 6100 - (68079/36208640 + 621093/13230080 * n + 399883/680960 * n^2) * eps^7 6101 + (658669/26460160 + 186416197/277831680 * n) * eps^8 6102 - 748030679/2963537920 * eps^9; 6103G4[7] = + (143/2785280 + 11011/7938048 * n + 972829/52093440 * n^2) * eps^7 6104 - (434863/317521920 + 263678129/6667960320 * n) * eps^8 6105 + 185257501/8890613760 * eps^9; 6106G4[8] = + (715/21168128 + 27313/26148864 * n) * eps^8 6107 - 1838551/1778122752 * eps^9; 6108G4[9] = + 2431/104595456 * eps^9; 6109\endverbatim 6110 6111\section gevsgeodesic Great ellipses vs geodesics 6112 6113Some papers advocating the use of great ellipses for navigation exhibit 6114a prejudice against the use of geodesics. These excerpts from 6115Pallikaris, Tsoulos, & Paradissis (2009) give the flavor 6116 - … it is required to adopt realistic accuracy standards in order not 6117 only to eliminate the significant errors of the spherical model but 6118 also to avoid the exaggerated and unrealistic requirements of sub 6119 meter accuracy. 6120 - Calculation of shortest sailings paths on the ellipsoid by a geodetic 6121 inverse method involve formulas that are much too complex. 6122 - Despite the fact that contemporary computers are fast enough to 6123 handle more complete geodetic formulas of sub meter accuracy, a basic 6124 principle for the design of navigational systems is the avoidance of 6125 unnecessary consumption of computing power. 6126 . 6127This prejudice was probably due to the fact that the most well-known 6128algorithms for geodesics, by Vincenty (1975), come with some 6129"asterisks": 6130 - no derivation was given (although they follow in a straightforward 6131 fashion from classic 19th century methods); 6132 - the accuracy is "only" 0.5 mm or so, surely good enough for most 6133 applications, but still a reason for a user to worry and a spur to 6134 numerous studies "validating" the algorithms; 6135 - no indication is given for how to extend the series to improve the 6136 accuracy; 6137 - there was a belief in some quarters (erroneous!) that the Vincenty 6138 algorithms could not be used to compute waypoints; 6139 - the algorithm for the inverse problem fails to converge for some 6140 inputs. 6141 . 6142These problems meant that users were reluctant to bundle the algorithms 6143into a library and treat them as a part of the software infrastructure 6144(much as you might regard the computation of \f$\sin x\f$ as a given). 6145In particular, I regard the last issue, lack of convergence of the 6146inverse solution, as fatal. Even though the problem only arises for 6147nearly antipodal points, it means all users of the library must have 6148some way to handle this problem. 6149 6150For these reasons, substitution of a great ellipse for the geodesic 6151makes some sense. The solution of the great ellipse is, in principle, 6152no more difficult than solving for the great circle and, for paths of 6153less then 10000 km, the error in the distance is less than 615413.5 m. 6155 6156Now (2014), however, the situation has reversed. The algorithms given 6157by Karney (2013)—and used in GeographicLib since 61582009—explicitly resolve the issues with Vincenty's algorithm. The 6159geodesic problem is conveniently bundled into a library. Users can call 6160this with an assurance of an accurate result much as they would when 6161evaluating \f$\sin x\f$. On the other hand, great ellipses come with 6162their own set of asterisks: 6163 - To the extent that they are regarded as approximations to geodesics, 6164 the errors need to be quantified, the limits of allowable use 6165 documented, etc. 6166 - The user is now left with decisions on when to trust the results and 6167 to find alternative solutions if necessary. 6168 - Even though the great ellipse is no more that 13.5 m longer than 6169 a 10000 km geodesic, the path of the great ellipse can deviate 6170 from the geodesic by as much as 8.3 km. This disqualifies great 6171 ellipses from use in congested air corridors where the 6172 <a href="https://en.wikipedia.org/wiki/Strategic_lateral_offset_procedure"> 6173 strategic lateral offset procedure</a> is in effect and in any 6174 situation which demands coordination in the routes of vessels. 6175 - Because geodesics obey the triangle inequality, while great ellipses 6176 do not, the solutions for realistic navigational problems, e.g., 6177 determining the time of closest approach of two vessels, are often 6178 simpler in terms of geodesics. 6179 6180To address some other of the objections in the quotes from Pallikaris et 6181al. given above: 6182 - "exaggerated and unrealistic requirements of sub meter accuracy": The 6183 geodesic algorithms allow full double precision accuracy at 6184 essentially no cost. This is because Clenshaw summation allows 6185 additional terms to be added to the series without the need for 6186 addition trigonometric evaluations. Full accuracy is important to 6187 maintain because it allows the results to be used reliably in more 6188 complex problems (e.g., in the determination of maritime boundaries). 6189 - "unnecessary consumption of computing power": The solution of the 6190 inverse geodesic problem takes 2.3 μs; multiple points on a 6191 geodesic can be computed at a rate of one point per 0.4 μs. 6192 The actual power consumed in these calculations is minuscule compared 6193 to the power needed to drive the display of a navigational computer. 6194 - "formulas that are much too complex": There's no question that the 6195 solution of the geodesic problem is more complex than for great 6196 ellipses. However this complexity is only an issue when 6197 <b>implementing</b> the algorithms. For the <b>end user</b>, 6198 navigational software employing geodesics is <b>less</b> complex 6199 compared with that employing great ellipses. Here is what the user 6200 needs to know about the geodesic solution: 6201 <blockquote>"The shortest path is found."</blockquote> 6202 And here is the corresponding documentation for great ellipses: 6203 <blockquote>"A path which closely approximates the shortest path is 6204 found. Provided that the distance is less than 10000 km, the 6205 error in distance is no more than 14 m and the deviation the 6206 route from that of the shortest path is no more than 9 km. 6207 These bounds apply to the WGS84 ellipsoid. The deviation of the path 6208 means that it should be used with caution when planning routes. In 6209 addition, great ellipses do not obey the triangle inequality; this 6210 disqualifies them from use in some applications."</blockquote> 6211 6212Having all the geodesic functions bundled up into a reliable "black box" 6213enables users to concentrate on how to solve problems using geodesics 6214(instead of figuring out how to solve for the geodesics). A wide range 6215of problems (intersection of paths, the path for an interception, the 6216time of closest approach, median lines, tri-points, etc.) are all 6217amenable to simple and fast solutions in terms of geodesics. 6218 6219<center> 6220Back to \ref rhumb. Forward to \ref transversemercator. Up to \ref contents. 6221</center> 6222 6223**********************************************************************/ 6224/** 6225\page transversemercator Transverse Mercator projection 6226 6227<center> 6228Back to \ref greatellipse. Forward to \ref geocentric. Up to \ref contents. 6229</center> 6230 6231TransverseMercator and TransverseMercatorExact provide accurate 6232implementations of the transverse Mercator projection. The 6233<a href="TransverseMercatorProj.1.html">TransverseMercatorProj</a> 6234utility provides an interface to these classes. 6235 6236Go to 6237 - \ref testmerc 6238 - \ref tmseries 6239 - \ref tmfigures 6240 6241References: 6242 - L. Krüger, 6243 <a href="https://doi.org/10.2312/GFZ.b103-krueger28"> Konforme 6244 Abbildung des Erdellipsoids in der Ebene</a> (Conformal mapping of 6245 the ellipsoidal earth to the plane), Royal Prussian Geodetic Institute, 6246 New Series 52, 172 pp. (1912). 6247 - L. P. Lee, 6248 Conformal Projections Based on Elliptic Functions, 6249 (B. V. Gutsell, Toronto, 1976), 128pp., 6250 ISBN: 0919870163 6251 (Also appeared as: 6252 Monograph 16, Suppl. No. 1 to Canadian Cartographer, Vol 13). 6253 Part V, pp. 67--101, 6254 <a href="https://doi.org/10.3138/X687-1574-4325-WM62">Conformal 6255 Projections Based On Jacobian Elliptic Functions</a>. 6256 - C. F. F. Karney, 6257 <a href="https://doi.org/10.1007/s00190-011-0445-3"> 6258 Transverse Mercator with an accuracy of a few nanometers</a>, 6259 J. Geodesy 85(8), 475--485 (Aug. 2011); 6260 addenda: <a href="https://geographiclib.sourceforge.io/tm-addenda.html"> 6261 tm-addenda.html</a>; 6262 preprint: 6263 <a href="https://arxiv.org/abs/1002.1417"> arXiv:1002.1417</a>; 6264 resource page: 6265 <a href="https://geographiclib.sourceforge.io/tm.html"> tm.html</a>. 6266 . 6267The algorithm for TransverseMercator is based on 6268Krüger (1912); that for TransverseMercatorExact is 6269based on Lee (1976). 6270 6271See <a href="https://geographiclib.sourceforge.io/tm-grid.kmz" 6272type="application/vnd.google-earth.kmz"> tm-grid.kmz</a>, for an 6273illustration of the exact transverse Mercator grid in Google Earth. 6274 6275\section testmerc Test data for the transverse Mercator projection 6276 6277A test set for the transverse Mercator projection is available at 6278 - <a href="https://sourceforge.net/projects/geographiclib/files/testdata/TMcoords.dat.gz"> 6279 TMcoords.dat.gz</a> 6280 - C. F. F. Karney, <i>Test data for the transverse Mercator projection</i> 6281 (2009), <br> 6282 DOI: <a href="https://doi.org/10.5281/zenodo.32470"> 6283 10.5281/zenodo.32470</a>. 6284 . 6285This is about 17 MB (compressed). This test set consists of a set of 6286geographic coordinates together with the corresponding transverse 6287Mercator coordinates. The WGS84 ellipsoid is used, with central 6288meridian 0°, central scale factor 0.9996 (the UTM value), 6289false easting = false northing = 0 m. 6290 6291Each line of the test set gives 6 space delimited numbers 6292 - latitude (degrees, exact) 6293 - longitude (degrees, exact — see below) 6294 - easting (meters, accurate to 0.1 pm) 6295 - northing (meters, accurate to 0.1 pm) 6296 - meridian convergence (degrees, accurate to 10<sup>−18</sup> deg) 6297 - scale (accurate to 10<sup>−20</sup>) 6298 . 6299The latitude and longitude are all multiples of 10<sup>−12</sup> 6300deg and should be regarded as exact, except that longitude = 630182.63627282416406551 should be interpreted as exactly (1 − \e e) 630290°. These results are computed using Lee's formulas with 6303<a href="https://en.wikipedia.org/wiki/Maxima_(software)">Maxima</a>'s 6304bfloats and fpprec set to 80 (so the errors in the data are probably 1/2 6305of the values quoted above). The Maxima code, 6306<a href="tm.mac">tm.mac</a> and <a href="ellint.mac">ellint.mac</a>, 6307was used to prepare this data set is included in the distribution; you 6308will need to have Maxima installed to use this code. The comments at 6309the top of <a href="tm.mac">tm.mac</a> illustrate how to run it. 6310 6311The contents of the file are as follows: 6312 - 250000 entries randomly distributed in lat in [0°, 90°], lon 6313 in [0°, 90°]; 6314 - 1000 entries randomly distributed on lat in [0°, 90°], lon = 6315 0°; 6316 - 1000 entries randomly distributed on lat = 0°, lon in [0°, 6317 90°]; 6318 - 1000 entries randomly distributed on lat in [0°, 90°], lon = 6319 90°; 6320 - 1000 entries close to lat = 90° with lon in [0°, 90°]; 6321 - 1000 entries close to lat = 0°, lon = 0° with lat ≥ 6322 0°, lon ≥ 0°; 6323 - 1000 entries close to lat = 0°, lon = 90° with lat ≥ 6324 0°, lon ≤ 90°; 6325 - 2000 entries close to lat = 0°, lon = (1 − \e e) 90° 6326 with lat ≥ 0°; 6327 - 25000 entries randomly distributed in lat in [−89°, 6328 0°], lon in [(1 − \e e) 90°, 90°]; 6329 - 1000 entries randomly distributed on lat in [−89°, 0°], 6330 lon = 90°; 6331 - 1000 entries randomly distributed on lat in [−89°, 0°], 6332 lon = (1 − \e e) 90°; 6333 - 1000 entries close to lat = 0°, lon = 90° (lat < 0°, lon 6334 ≤ 90°); 6335 - 1000 entries close to lat = 0°, lon = (1 − \e e) 90° 6336 (lat < 0°, lon ≤ (1 − \e e) 90°); 6337 . 6338(a total of 287000 entries). The entries for lat < 0° and 6339lon in [(1 − \e e) 90°, 90°] use the "extended" 6340domain for the transverse Mercator projection explained in Sec. 5 of 6341Karney (2011). The first 6342258000 entries have lat ≥ 0° and are suitable for testing 6343implementations following the standard convention. 6344 6345\section tmseries Series approximation for transverse Mercator 6346 6347Krüger (1912) gives a 4th-order approximation to the transverse 6348Mercator projection. This is accurate to about 200 nm (200 6349nanometers) within the UTM domain. Here we present the series 6350extended to 10th order. By default, TransverseMercator 6351uses the 6th-order approximation. The preprocessor macro 6352GEOGRAPHICLIB_TRANSVERSEMERCATOR_ORDER can be used to select an order 6353from 4 thru 8. The series expanded to order <i>n</i><sup>30</sup> are 6354given in <a href="tmseries30.html"> tmseries30.html</a>. 6355 6356In the formulas below ^ indicates exponentiation (<i>n</i>^3 = 6357<i>n</i>*<i>n</i>*<i>n</i>) and / indicates real division (3/5 = 0.6). 6358The equations need to be converted to Horner form, but are here left in 6359expanded form so that they can be easily truncated to lower order in \e 6360n. Some of the integers here are not representable as 32-bit integers 6361and will need to be included as 64-bit integers. 6362 6363\e A in Krüger, p. 12, eq. (5) 6364\verbatim 6365 A = a/(n + 1) * (1 + 1/4 * n^2 6366 + 1/64 * n^4 6367 + 1/256 * n^6 6368 + 25/16384 * n^8 6369 + 49/65536 * n^10); 6370\endverbatim 6371 6372γ in Krüger, p. 21, eq. (41) 6373\verbatim 6374alpha[1] = 1/2 * n 6375 - 2/3 * n^2 6376 + 5/16 * n^3 6377 + 41/180 * n^4 6378 - 127/288 * n^5 6379 + 7891/37800 * n^6 6380 + 72161/387072 * n^7 6381 - 18975107/50803200 * n^8 6382 + 60193001/290304000 * n^9 6383 + 134592031/1026432000 * n^10; 6384alpha[2] = 13/48 * n^2 6385 - 3/5 * n^3 6386 + 557/1440 * n^4 6387 + 281/630 * n^5 6388 - 1983433/1935360 * n^6 6389 + 13769/28800 * n^7 6390 + 148003883/174182400 * n^8 6391 - 705286231/465696000 * n^9 6392 + 1703267974087/3218890752000 * n^10; 6393alpha[3] = 61/240 * n^3 6394 - 103/140 * n^4 6395 + 15061/26880 * n^5 6396 + 167603/181440 * n^6 6397 - 67102379/29030400 * n^7 6398 + 79682431/79833600 * n^8 6399 + 6304945039/2128896000 * n^9 6400 - 6601904925257/1307674368000 * n^10; 6401alpha[4] = 49561/161280 * n^4 6402 - 179/168 * n^5 6403 + 6601661/7257600 * n^6 6404 + 97445/49896 * n^7 6405 - 40176129013/7664025600 * n^8 6406 + 138471097/66528000 * n^9 6407 + 48087451385201/5230697472000 * n^10; 6408alpha[5] = 34729/80640 * n^5 6409 - 3418889/1995840 * n^6 6410 + 14644087/9123840 * n^7 6411 + 2605413599/622702080 * n^8 6412 - 31015475399/2583060480 * n^9 6413 + 5820486440369/1307674368000 * n^10; 6414alpha[6] = 212378941/319334400 * n^6 6415 - 30705481/10378368 * n^7 6416 + 175214326799/58118860800 * n^8 6417 + 870492877/96096000 * n^9 6418 - 1328004581729009/47823519744000 * n^10; 6419alpha[7] = 1522256789/1383782400 * n^7 6420 - 16759934899/3113510400 * n^8 6421 + 1315149374443/221405184000 * n^9 6422 + 71809987837451/3629463552000 * n^10; 6423alpha[8] = 1424729850961/743921418240 * n^8 6424 - 256783708069/25204608000 * n^9 6425 + 2468749292989891/203249958912000 * n^10; 6426alpha[9] = 21091646195357/6080126976000 * n^9 6427 - 67196182138355857/3379030566912000 * n^10; 6428alpha[10]= 77911515623232821/12014330904576000 * n^10; 6429\endverbatim 6430 6431β in Krüger, p. 18, eq. (26*) 6432\verbatim 6433 beta[1] = 1/2 * n 6434 - 2/3 * n^2 6435 + 37/96 * n^3 6436 - 1/360 * n^4 6437 - 81/512 * n^5 6438 + 96199/604800 * n^6 6439 - 5406467/38707200 * n^7 6440 + 7944359/67737600 * n^8 6441 - 7378753979/97542144000 * n^9 6442 + 25123531261/804722688000 * n^10; 6443 beta[2] = 1/48 * n^2 6444 + 1/15 * n^3 6445 - 437/1440 * n^4 6446 + 46/105 * n^5 6447 - 1118711/3870720 * n^6 6448 + 51841/1209600 * n^7 6449 + 24749483/348364800 * n^8 6450 - 115295683/1397088000 * n^9 6451 + 5487737251099/51502252032000 * n^10; 6452 beta[3] = 17/480 * n^3 6453 - 37/840 * n^4 6454 - 209/4480 * n^5 6455 + 5569/90720 * n^6 6456 + 9261899/58060800 * n^7 6457 - 6457463/17740800 * n^8 6458 + 2473691167/9289728000 * n^9 6459 - 852549456029/20922789888000 * n^10; 6460 beta[4] = 4397/161280 * n^4 6461 - 11/504 * n^5 6462 - 830251/7257600 * n^6 6463 + 466511/2494800 * n^7 6464 + 324154477/7664025600 * n^8 6465 - 937932223/3891888000 * n^9 6466 - 89112264211/5230697472000 * n^10; 6467 beta[5] = 4583/161280 * n^5 6468 - 108847/3991680 * n^6 6469 - 8005831/63866880 * n^7 6470 + 22894433/124540416 * n^8 6471 + 112731569449/557941063680 * n^9 6472 - 5391039814733/10461394944000 * n^10; 6473 beta[6] = 20648693/638668800 * n^6 6474 - 16363163/518918400 * n^7 6475 - 2204645983/12915302400 * n^8 6476 + 4543317553/18162144000 * n^9 6477 + 54894890298749/167382319104000 * n^10; 6478 beta[7] = 219941297/5535129600 * n^7 6479 - 497323811/12454041600 * n^8 6480 - 79431132943/332107776000 * n^9 6481 + 4346429528407/12703122432000 * n^10; 6482 beta[8] = 191773887257/3719607091200 * n^8 6483 - 17822319343/336825216000 * n^9 6484 - 497155444501631/1422749712384000 * n^10; 6485 beta[9] = 11025641854267/158083301376000 * n^9 6486 - 492293158444691/6758061133824000 * n^10; 6487 beta[10]= 7028504530429621/72085985427456000 * n^10; 6488\endverbatim 6489 6490The high-order expansions for α and β were produced by the 6491Maxima program <a href="tmseries.mac"> tmseries.mac</a> (included in the 6492distribution). To run, start Maxima and enter 6493\verbatim 6494 load("tmseries.mac")$ 6495\endverbatim 6496Further instructions are included at the top of the file. 6497 6498\section tmfigures Figures from paper on transverse Mercator projection 6499 6500This section gives color versions of the figures in 6501 - C. F. F. Karney, 6502 <a href="https://doi.org/10.1007/s00190-011-0445-3"> 6503 Transverse Mercator with an accuracy of a few nanometers</a>, 6504 J. Geodesy 85(8), 475--485 (Aug. 2011); 6505 addenda: <a href="https://geographiclib.sourceforge.io/tm-addenda.html"> 6506 tm-addenda.html</a>; 6507 preprint: 6508 <a href="https://arxiv.org/abs/1002.1417"> arXiv:1002.1417</a>; 6509 resource page: 6510 <a href="https://geographiclib.sourceforge.io/tm.html"> tm.html</a>. 6511 6512\b NOTE: 6513The numbering of the figures matches that in the paper cited above. The 6514figures in this section are relatively small in order to allow them to 6515be displayed quickly. Vector versions of these figures are available in 6516<a href="https://geographiclib.sourceforge.io/tm-figs.pdf" 6517type="application/pdf"> tm-figs.pdf</a>. This allows you to magnify the 6518figures to show the details more clearly. 6519 6520\image html gauss-schreiber-graticule-a.png "Fig. 1(a)" 6521Fig. 1(a): 6522The graticule for the spherical transverse Mercator projection. 6523The equator lies on \e y = 0. 6524Compare this with Lee, Fig. 1 (right), which shows the graticule for 6525half a sphere, but note that in his notation \e x and \e y have switched 6526meanings. The graticule for the ellipsoid differs from that for a 6527sphere only in that the latitude lines have shifted slightly. (The 6528conformal transformation from an ellipsoid to a sphere merely relabels 6529the lines of latitude.) This projection places the point latitude = 65300°, longitude = 90° at infinity. 6531 6532\image html gauss-krueger-graticule-a.png "Fig. 1(b)" 6533Fig. 1(b): 6534The graticule for the Gauss-Krüger transverse Mercator projection. 6535The equator lies on \e y = 0 for longitude < 81°; beyond 6536this, it arcs up to meet \e y = 1. Compare this with Lee, Fig. 45 6537(upper), which shows the graticule for the International Ellipsoid. Lee, 6538Fig. 46, shows the graticule for the entire ellipsoid. This projection 6539(like the Thompson projection) projects the ellipsoid to a finite area. 6540 6541\image html thompson-tm-graticule-a.png "Fig. 1(c)" 6542Fig. 1(c): 6543The graticule for the Thompson transverse Mercator projection. The 6544equator lies on \e y = 0 for longitude < 81°; at longitude = 654581°, it turns by 120° and heads for \e y = 1. 6546Compare this with Lee, Fig. 43, which shows the graticule for the 6547International Ellipsoid. Lee, Fig. 44, shows the graticule for the 6548entire ellipsoid. This projection (like the Gauss-Krüger 6549projection) projects the ellipsoid to a finite area. 6550 6551\image html gauss-krueger-error.png "Fig. 2" 6552Fig. 2: 6553The truncation error for the series for the Gauss-Krüger transverse 6554Mercator projection. The blue curves show the truncation error for the 6555order of the series \e J = 2 (top) thru \e J = 12 (bottom). The red 6556curves show the combined truncation and round-off errors for 6557 - float and \e J = 4 (top) 6558 - double and \e J = 6 (middle) 6559 - long double and \e J = 8 (bottom) 6560 6561\image html gauss-krueger-graticule.png "Fig. 3(a)" 6562Fig. 3(a): 6563The graticule for the extended domain. The blue lines show 6564latitude and longitude at multiples of 10°. The green lines 6565show 1° intervals for longitude in [80°, 90°] and latitude in 6566[−5°, 10°]. 6567 6568\image html gauss-krueger-convergence-scale.png "Fig. 3(b)" 6569Fig. 3(b): 6570The convergence and scale for the Gauss-Krüger 6571transverse Mercator projection in the extended domain. The blue lines 6572emanating from the top left corner (the north pole) are lines of 6573constant convergence. Convergence = 0° is given by the 6574dog-legged line joining the points (0,1), (0,0), (1.71,0), 6575(1.71,−∞). 6576Convergence = 90° is given by the line y = 1. The other 6577lines show multiples of 10° between 0° and 657890°. The other blue, the green and the black lines show 6579scale = 1 thru 2 at intervals of 0.1, 2 thru 15 at intervals of 1, and 658015 thru 35 at intervals of 5. Multiples of 5 are shown in black, 6581multiples of 1 are shown in blue, and the rest are shown in green. 6582Scale = 1 is given by the line segment (0,0) to (0,1). The red line 6583shows the equator between lon = 81° and 90°. The 6584scale and convergence at the branch point are 1/\e e = 10 and 65850°, respectively. 6586 6587\image html thompson-tm-graticule.png "Fig. 3(c)" 6588Fig. 3(c): 6589The graticule for the Thompson transverse Mercator 6590projection for the extended domain. The range of the projection is the 6591rectangular region shown 6592 - 0 ≤ \e u ≤ K(<i>e</i><sup>2</sup>), 6593 0 ≤ \e v ≤ K(1 − <i>e</i><sup>2</sup>) 6594 . 6595The coloring of the lines is the same as Fig. 3(a), except that latitude 6596lines extended down to −10° and a red line has been added 6597showing the line \e y = 0 for \e x > 1.71 in the Gauss-Krüger 6598projection (Fig. 3(a)). The extended Thompson projection figure has 6599reflection symmetry on all the four sides of Fig. 3(c). 6600 6601<center> 6602Back to \ref greatellipse. Forward to \ref geocentric. Up to \ref contents. 6603</center> 6604 6605**********************************************************************/ 6606/** 6607\page geocentric Geocentric coordinates 6608 6609<center> 6610Back to \ref transversemercator. Forward to \ref auxlat. Up to \ref contents. 6611</center> 6612 6613The implementation of Geocentric::Reverse is adapted from 6614 - H. Vermeille, 6615 <a href="https://doi.org/10.1007/s00190-002-0273-6"> 6616 Direct transformation from geocentric coordinates to geodetic 6617 coordinates</a>, J. Geodesy 76, 451--454 (2002). 6618 6619This provides a closed-form solution but can't directly be applied close to 6620the center of the earth. Several changes have been made to remove this 6621restriction and to improve the numerical accuracy. Now the method is 6622accurate for all inputs (even if \e h is infinite). The changes are 6623described in Appendix B of 6624 - C. F. F. Karney, 6625 <a href="https://arxiv.org/abs/1102.1215v1">Geodesics 6626 on an ellipsoid of revolution</a>, 6627 Feb. 2011; preprint 6628 <a href="https://arxiv.org/abs/1102.1215v1">arxiv:1102.1215v1</a>. 6629 . 6630Vermeille similarly updated his method in 6631 - H. Vermeille, 6632 <a href="https://doi.org/10.1007/s00190-010-0419-x"> 6633 An analytical method to transform geocentric into 6634 geodetic coordinates</a>, J. Geodesy 85, 105--117 (2011). 6635 6636The problems encountered near the center of the ellipsoid are: 6637 - There's a potential division by zero in the definition of \e s. The 6638 equations are easily reformulated to avoid this problem. 6639 - <i>t</i><sup>3</sup> may be negative. This is OK; we just take the 6640 real root. 6641 - The solution for \e t may be complex. However this leads to 3 real roots 6642 for <i>u</i>/\e r. It's then just a matter of picking the one that computes 6643 the geodetic result which minimizes |<i>h</i>| and which avoids large 6644 round-off errors. 6645 - Some of the equations result in a large loss of accuracy due to 6646 subtracting nearly equal quantities. E.g., \e k = sqrt(\e u + \e v + 6647 <i>w</i><sup>2</sup>) − \e w is inaccurate if \e u + \e v is small; 6648 we can fix this by writing \e k = (\e u + \e v)/(sqrt(\e u + \e v + 6649 <i>w</i><sup>2</sup>) + \e w). 6650 6651The error is computed as follows. Write a version of 6652Geocentric::WGS84.Forward which uses long doubles (including using long 6653doubles for the WGS84 parameters). Generate random (long double) 6654geodetic coordinates (\e lat0, \e lon0, \e h0) and use the "long double" 6655WGS84.Forward to obtain the corresponding (long double) geocentric 6656coordinates (\e x0, \e y0, \e z0). [We restrict \e h0 so that \e h0 6657≥ − \e a (1 − <i>e</i><sup>2</sup>) / sqrt(1 − 6658<i>e</i><sup>2</sup> sin<sup>2</sup>\e lat0), which ensures that (\e 6659lat0, \e lon0, \e h0) is the principal geodetic inverse of (\e x0, \e 6660y0, \e z0).] Because the forward calculation is numerically stable and 6661because long doubles (on Linux systems using g++) provide 11 bits 6662additional accuracy (about 3.3 decimal digits), we regard this set of 6663test data as exact. 6664 6665Apply the double version of WGS84.Reverse to (\e x0, \e y0, \e z0) to 6666compute the approximate geodetic coordinates (\e lat1, \e lon1, \e h1). 6667Convert (\e lat1 − \e lat0, \e lon1 − \e lon0) to a 6668distance, \e ds, on the surface of the ellipsoid and define \e err = 6669hypot(\e ds, \e h1 − \e h0). For |<i>h0</i>| < 5000 km, we 6670have \e err < 7 nm (7 nanometers). 6671 6672This methodology is not very useful very far from the globe, because the 6673absolute errors in the approximate geodetic height become large, or 6674within 50 km of the center of the earth, because of errors in 6675computing the approximate geodetic latitude. To illustrate the second 6676issue, the maximum value of \e err for \e h0 < 0 is about 80 mm. 6677The error is maximum close to the circle given by geocentric coordinates 6678satisfying hypot(\e x, \e y) = \e a <i>e</i><sup>2</sup> (= 667942.7 km), \e z = 0. (This is the center of meridional curvature 6680for \e lat = 0.) The geodetic latitude for these points is \e lat = 0. 6681However, if we move 1 nm towards the center of the earth, the 6682geodetic latitude becomes 0.04", a distance of 1.4 m from the 6683equator. If, instead, we move 1 nm up, the geodetic latitude 6684becomes 7.45", a distance of 229 m from the equator. In light of 6685this, Reverse does quite well in this vicinity. 6686 6687To obtain a practical measure of the error for the general case we define 6688- <i>err</i><sub>h</sub> = |\e h1 − <i>h0</i>| / max(1, \e h0 / \e a) 6689- for \e h0 > 0, <i>err</i><sub>out</sub> = \e ds 6690- for \e h0 < 0, apply the long double version of WGS84.Forward to (\e 6691 lat1, \e lon1, \e h1) to give (\e x1, \e y1, \e z1) and compute 6692 <i>err</i><sub>in</sub> = hypot(\e x1 − \e x0, \e y1 − \e 6693 y0, \e z1 − \e z0). 6694. 6695We then find <i>err</i><sub>h</sub> < 8 nm, 6696<i>err</i><sub>out</sub> < 4 nm, and <i>err</i><sub>in</sub> < 66977 nm (1 nm = 1 nanometer). 6698 6699The testing has been confined to the WGS84 ellipsoid. The method will 6700work for all ellipsoids used in terrestrial geodesy. However, the 6701central region, which leads to multiple real roots for the cubic 6702equation in Reverse, pokes outside the ellipsoid (at the poles) for 6703ellipsoids with \e e > 1/sqrt(2); Reverse has not been analyzed for this 6704case. Similarly ellipsoids which are very nearly spherical may yield 6705inaccurate results due to underflow; in the other hand, the case of the 6706sphere, \e f = 0, is treated specially and gives accurate results. 6707 6708Other comparable methods are K. M. Borkowski, 6709<a href="https://doi.org/10.1007/BF00643807"> Transformation 6710of geocentric to geodetic coordinates without approximations</a>, 6711Astrophys. Space Sci. 139, 1--4 (1987) 6712(<a href="https://doi.org/10.1007/BF00656995"> erratum</a>) 6713and T. Fukushima, 6714<a href="https://doi.org/10.1007/s001900050271"> Fast transform from 6715geocentric to geodetic coordinates</a>, J. Geodesy 73, 603--610 (1999). 6716However the choice of independent variables in these methods leads 6717to a loss of accuracy for points near the equatorial plane. 6718 6719<center> 6720Back to \ref transversemercator. Forward to \ref auxlat. Up to \ref contents. 6721</center> 6722 6723**********************************************************************/ 6724/** 6725\page auxlat Auxiliary latitudes 6726 6727<center> 6728Back to \ref geocentric. Forward to \ref highprec. Up to \ref contents. 6729</center> 6730 6731Go to 6732 - \ref auxlatformula 6733 - \ref auxlattable 6734 - \ref auxlaterror 6735 6736Six latitudes are used by GeographicLib: 6737- φ, the (geographic) latitude; 6738- β, the parametric latitude; 6739- θ, the geocentric latitude; 6740- μ, the rectifying latitude; 6741- χ, the conformal latitude; 6742- ξ, the authalic latitude. 6743. 6744The last five of these are called <i>auxiliary latitudes</i>. These 6745quantities are all defined in the 6746<a href="https://en.wikipedia.org/wiki/Latitude#Auxiliary_latitudes"> 6747Wikipedia article on latitudes</a>. The Ellipsoid class contains 6748methods for converting all of these and the geographic latitude. 6749 6750In addition there's the isometric latitude, ψ, defined by ψ = 6751gd<sup>−1</sup>χ = sinh<sup>−1</sup> tanχ and 6752χ = gdψ = tan<sup>−1</sup> sinhψ. This is not an 6753angle-like variable (for example, it diverges at the poles) and so we 6754don't treat it further here. However conversions between ψ and any 6755of the auxiliary latitudes is easily accomplished via an intermediate 6756conversion to χ. 6757 6758The relations between φ, β, and θ are all simple 6759elementary functions. The latitudes χ and ξ can be expressed as 6760elementary functions of φ; however, these functions can only be 6761inverted iteratively. The rectifying latitude μ as a function of 6762φ (or β) involves the incomplete elliptic integral of the 6763second kind (which is not an elementary function) and this needs to be 6764inverted iteratively. The Ellipsoid class evaluates all the auxiliary 6765latitudes (and the corresponding inverse relations) in terms of their 6766basic definitions. 6767 6768An alternative method of evaluating these auxiliary latitudes is in 6769terms of trigonometric series. This offers some advantages: 6770- these series give a uniform way of expressing any latitude in terms of 6771 any other latitude; 6772- the evaluation may be faster, particularly if 6773 <a href="https://en.wikipedia.org/wiki/Clenshaw_algorithm#Meridian_arc_length_on_the_ellipsoid"> 6774 Clenshaw summation</a> is used; 6775- provided that the flattening is sufficiently small, the result may be 6776 more accurate (because the round-off errors are smaller). 6777 6778Here we give the complete matrix of relations between all six latitudes; 6779there are 30 (= 6 × 5) such relations. These 6780expansions complement the work of 6781- O. S. Adams, 6782 <a href="https://docs.lib.noaa.gov/rescue/cgs_specpubs/QB275U35no671921.pdf"> 6783 Latitude developments connected with geodesy and cartography</a>, 6784 Spec. Pub. 67 (US Coast and Geodetic Survey, 1921). 6785- P. Osborne, 6786 <a href="https://dx.doi.org/10.5281/zenodo.35392"> 6787 The Mercator Projections</a> (2013), Chap. 5. 6788- S. Orihuela, 6789 <a href="https://sites.google.com/site/geodesiafich/funciones_latitud.pdf"> 6790 Funciones de Latitud</a> (2013). 6791. 6792Here, the expansions are in terms of the third flattening <i>n</i> = 6793(<i>a</i> − <i>b</i>)/(<i>a</i> + <i>b</i>). 6794This choice of expansion parameter results in expansions in which half 6795the coefficients vanish for all relations between φ, β, 6796θ, and μ. In addition, the expansions converge for |<i>n</i>| 6797< 1 or <i>b</i>/<i>a</i> ∈ (0, ∞). These expansions 6798were obtained with the the maxima code, <a 6799href="auxlat.mac">auxlat.mac</a>. 6800 6801Adams (1921) uses the eccentricity squared <i>e</i><sup>2</sup> as the 6802expansion parameter, but the resulting series only converge for 6803|<i>e</i><sup>2</sup>| < 1 or <i>b</i>/<i>a</i> ∈ 6804(0, √2). In addition, it is shown in \ref auxlaterror, that 6805the errors when the series are truncated are much worse than for the 6806corresponding series in \e n. 6807 6808\b NOTE: The assertions about convergence above are too optimistic. 6809Some of the series do indeed converge for |<i>n</i>| < 1. However 6810others have a smaller radius of convergence. More on this later… 6811 6812\section auxlatformula Series approximations for conversions 6813 6814Here are the relations between φ, β, θ, and μ carried 6815out to 4th order in <i>n</i>: 6816\f[ 6817\begin{align} 6818\beta-\phi&=\textstyle{} 6819-n\sin 2\phi 6820+\frac{1}{2}n^{2}\sin 4\phi 6821-\frac{1}{3}n^{3}\sin 6\phi 6822+\frac{1}{4}n^{4}\sin 8\phi 6823-\ldots\\ 6824\phi-\beta&=\textstyle{} 6825+n\sin 2\beta 6826+\frac{1}{2}n^{2}\sin 4\beta 6827+\frac{1}{3}n^{3}\sin 6\beta 6828+\frac{1}{4}n^{4}\sin 8\beta 6829+\ldots\\ 6830\theta-\phi&=\textstyle{} 6831-\bigl(2n-2n^{3}\bigr)\sin 2\phi 6832+\bigl(2n^{2}-4n^{4}\bigr)\sin 4\phi 6833-\frac{8}{3}n^{3}\sin 6\phi 6834+4n^{4}\sin 8\phi 6835-\ldots\\ 6836\phi-\theta&=\textstyle{} 6837+\bigl(2n-2n^{3}\bigr)\sin 2\theta 6838+\bigl(2n^{2}-4n^{4}\bigr)\sin 4\theta 6839+\frac{8}{3}n^{3}\sin 6\theta 6840+4n^{4}\sin 8\theta 6841+\ldots\\ 6842\theta-\beta&=\textstyle{} 6843-n\sin 2\beta 6844+\frac{1}{2}n^{2}\sin 4\beta 6845-\frac{1}{3}n^{3}\sin 6\beta 6846+\frac{1}{4}n^{4}\sin 8\beta 6847-\ldots\\ 6848\beta-\theta&=\textstyle{} 6849+n\sin 2\theta 6850+\frac{1}{2}n^{2}\sin 4\theta 6851+\frac{1}{3}n^{3}\sin 6\theta 6852+\frac{1}{4}n^{4}\sin 8\theta 6853+\ldots\\ 6854\mu-\phi&=\textstyle{} 6855-\bigl(\frac{3}{2}n-\frac{9}{16}n^{3}\bigr)\sin 2\phi 6856+\bigl(\frac{15}{16}n^{2}-\frac{15}{32}n^{4}\bigr)\sin 4\phi 6857-\frac{35}{48}n^{3}\sin 6\phi 6858+\frac{315}{512}n^{4}\sin 8\phi 6859-\ldots\\ 6860\phi-\mu&=\textstyle{} 6861+\bigl(\frac{3}{2}n-\frac{27}{32}n^{3}\bigr)\sin 2\mu 6862+\bigl(\frac{21}{16}n^{2}-\frac{55}{32}n^{4}\bigr)\sin 4\mu 6863+\frac{151}{96}n^{3}\sin 6\mu 6864+\frac{1097}{512}n^{4}\sin 8\mu 6865+\ldots\\ 6866\mu-\beta&=\textstyle{} 6867-\bigl(\frac{1}{2}n-\frac{3}{16}n^{3}\bigr)\sin 2\beta 6868-\bigl(\frac{1}{16}n^{2}-\frac{1}{32}n^{4}\bigr)\sin 4\beta 6869-\frac{1}{48}n^{3}\sin 6\beta 6870-\frac{5}{512}n^{4}\sin 8\beta 6871-\ldots\\ 6872\beta-\mu&=\textstyle{} 6873+\bigl(\frac{1}{2}n-\frac{9}{32}n^{3}\bigr)\sin 2\mu 6874+\bigl(\frac{5}{16}n^{2}-\frac{37}{96}n^{4}\bigr)\sin 4\mu 6875+\frac{29}{96}n^{3}\sin 6\mu 6876+\frac{539}{1536}n^{4}\sin 8\mu 6877+\ldots\\ 6878\mu-\theta&=\textstyle{} 6879+\bigl(\frac{1}{2}n+\frac{13}{16}n^{3}\bigr)\sin 2\theta 6880-\bigl(\frac{1}{16}n^{2}-\frac{33}{32}n^{4}\bigr)\sin 4\theta 6881-\frac{5}{16}n^{3}\sin 6\theta 6882-\frac{261}{512}n^{4}\sin 8\theta 6883-\ldots\\ 6884\theta-\mu&=\textstyle{} 6885-\bigl(\frac{1}{2}n+\frac{23}{32}n^{3}\bigr)\sin 2\mu 6886+\bigl(\frac{5}{16}n^{2}-\frac{5}{96}n^{4}\bigr)\sin 4\mu 6887+\frac{1}{32}n^{3}\sin 6\mu 6888+\frac{283}{1536}n^{4}\sin 8\mu 6889+\ldots\\ 6890\end{align} 6891\f] 6892 6893Here are the remaining relations (including χ and ξ) carried out 6894to 3rd order in <i>n</i>: 6895\f[ 6896\begin{align} 6897\chi-\phi&=\textstyle{} 6898-\bigl(2n-\frac{2}{3}n^{2}-\frac{4}{3}n^{3}\bigr)\sin 2\phi 6899+\bigl(\frac{5}{3}n^{2}-\frac{16}{15}n^{3}\bigr)\sin 4\phi 6900-\frac{26}{15}n^{3}\sin 6\phi 6901+\ldots\\ 6902\phi-\chi&=\textstyle{} 6903+\bigl(2n-\frac{2}{3}n^{2}-2n^{3}\bigr)\sin 2\chi 6904+\bigl(\frac{7}{3}n^{2}-\frac{8}{5}n^{3}\bigr)\sin 4\chi 6905+\frac{56}{15}n^{3}\sin 6\chi 6906+\ldots\\ 6907\chi-\beta&=\textstyle{} 6908-\bigl(n-\frac{2}{3}n^{2}\bigr)\sin 2\beta 6909+\bigl(\frac{1}{6}n^{2}-\frac{2}{5}n^{3}\bigr)\sin 4\beta 6910-\frac{1}{15}n^{3}\sin 6\beta 6911+\ldots\\ 6912\beta-\chi&=\textstyle{} 6913+\bigl(n-\frac{2}{3}n^{2}-\frac{1}{3}n^{3}\bigr)\sin 2\chi 6914+\bigl(\frac{5}{6}n^{2}-\frac{14}{15}n^{3}\bigr)\sin 4\chi 6915+\frac{16}{15}n^{3}\sin 6\chi 6916+\ldots\\ 6917\chi-\theta&=\textstyle{} 6918+\bigl(\frac{2}{3}n^{2}+\frac{2}{3}n^{3}\bigr)\sin 2\theta 6919-\bigl(\frac{1}{3}n^{2}-\frac{4}{15}n^{3}\bigr)\sin 4\theta 6920-\frac{2}{5}n^{3}\sin 6\theta 6921-\ldots\\ 6922\theta-\chi&=\textstyle{} 6923-\bigl(\frac{2}{3}n^{2}+\frac{2}{3}n^{3}\bigr)\sin 2\chi 6924+\bigl(\frac{1}{3}n^{2}-\frac{4}{15}n^{3}\bigr)\sin 4\chi 6925+\frac{2}{5}n^{3}\sin 6\chi 6926+\ldots\\ 6927\chi-\mu&=\textstyle{} 6928-\bigl(\frac{1}{2}n-\frac{2}{3}n^{2}+\frac{37}{96}n^{3}\bigr)\sin 2\mu 6929-\bigl(\frac{1}{48}n^{2}+\frac{1}{15}n^{3}\bigr)\sin 4\mu 6930-\frac{17}{480}n^{3}\sin 6\mu 6931-\ldots\\ 6932\mu-\chi&=\textstyle{} 6933+\bigl(\frac{1}{2}n-\frac{2}{3}n^{2}+\frac{5}{16}n^{3}\bigr)\sin 2\chi 6934+\bigl(\frac{13}{48}n^{2}-\frac{3}{5}n^{3}\bigr)\sin 4\chi 6935+\frac{61}{240}n^{3}\sin 6\chi 6936+\ldots\\ 6937\xi-\phi&=\textstyle{} 6938-\bigl(\frac{4}{3}n+\frac{4}{45}n^{2}-\frac{88}{315}n^{3}\bigr)\sin 2\phi 6939+\bigl(\frac{34}{45}n^{2}+\frac{8}{105}n^{3}\bigr)\sin 4\phi 6940-\frac{1532}{2835}n^{3}\sin 6\phi 6941+\ldots\\ 6942\phi-\xi&=\textstyle{} 6943+\bigl(\frac{4}{3}n+\frac{4}{45}n^{2}-\frac{16}{35}n^{3}\bigr)\sin 2\xi 6944+\bigl(\frac{46}{45}n^{2}+\frac{152}{945}n^{3}\bigr)\sin 4\xi 6945+\frac{3044}{2835}n^{3}\sin 6\xi 6946+\ldots\\ 6947\xi-\beta&=\textstyle{} 6948-\bigl(\frac{1}{3}n+\frac{4}{45}n^{2}-\frac{32}{315}n^{3}\bigr)\sin 2\beta 6949-\bigl(\frac{7}{90}n^{2}+\frac{4}{315}n^{3}\bigr)\sin 4\beta 6950-\frac{83}{2835}n^{3}\sin 6\beta 6951-\ldots\\ 6952\beta-\xi&=\textstyle{} 6953+\bigl(\frac{1}{3}n+\frac{4}{45}n^{2}-\frac{46}{315}n^{3}\bigr)\sin 2\xi 6954+\bigl(\frac{17}{90}n^{2}+\frac{68}{945}n^{3}\bigr)\sin 4\xi 6955+\frac{461}{2835}n^{3}\sin 6\xi 6956+\ldots\\ 6957\xi-\theta&=\textstyle{} 6958+\bigl(\frac{2}{3}n-\frac{4}{45}n^{2}+\frac{62}{105}n^{3}\bigr)\sin 2\theta 6959+\bigl(\frac{4}{45}n^{2}-\frac{32}{315}n^{3}\bigr)\sin 4\theta 6960-\frac{524}{2835}n^{3}\sin 6\theta 6961-\ldots\\ 6962\theta-\xi&=\textstyle{} 6963-\bigl(\frac{2}{3}n-\frac{4}{45}n^{2}+\frac{158}{315}n^{3}\bigr)\sin 2\xi 6964+\bigl(\frac{16}{45}n^{2}-\frac{16}{945}n^{3}\bigr)\sin 4\xi 6965-\frac{232}{2835}n^{3}\sin 6\xi 6966+\ldots\\ 6967\xi-\mu&=\textstyle{} 6968+\bigl(\frac{1}{6}n-\frac{4}{45}n^{2}-\frac{817}{10080}n^{3}\bigr)\sin 2\mu 6969+\bigl(\frac{49}{720}n^{2}-\frac{2}{35}n^{3}\bigr)\sin 4\mu 6970+\frac{4463}{90720}n^{3}\sin 6\mu 6971+\ldots\\ 6972\mu-\xi&=\textstyle{} 6973-\bigl(\frac{1}{6}n-\frac{4}{45}n^{2}-\frac{121}{1680}n^{3}\bigr)\sin 2\xi 6974-\bigl(\frac{29}{720}n^{2}-\frac{26}{945}n^{3}\bigr)\sin 4\xi 6975-\frac{1003}{45360}n^{3}\sin 6\xi 6976-\ldots\\ 6977\xi-\chi&=\textstyle{} 6978+\bigl(\frac{2}{3}n-\frac{34}{45}n^{2}+\frac{46}{315}n^{3}\bigr)\sin 2\chi 6979+\bigl(\frac{19}{45}n^{2}-\frac{256}{315}n^{3}\bigr)\sin 4\chi 6980+\frac{248}{567}n^{3}\sin 6\chi 6981+\ldots\\ 6982\chi-\xi&=\textstyle{} 6983-\bigl(\frac{2}{3}n-\frac{34}{45}n^{2}+\frac{88}{315}n^{3}\bigr)\sin 2\xi 6984+\bigl(\frac{1}{45}n^{2}-\frac{184}{945}n^{3}\bigr)\sin 4\xi 6985-\frac{106}{2835}n^{3}\sin 6\xi 6986-\ldots\\ 6987\end{align} 6988\f] 6989 6990\section auxlattable Series approximations in tabular form 6991 6992Finally, this is a listing of all the coefficients for the expansions 6993carried out to 8th order in <i>n</i>. Here's how to interpret this 6994data: the 5th line for φ − θ is <tt>[32/5, 0, 6995-32, 0]</tt>; this means that the coefficient of sin(10θ) is 6996[(32/5)<i>n</i><sup>5</sup> − 699732<i>n</i><sup>7</sup> + <i>O</i>(<i>n</i><sup>9</sup>)]. 6998<p>β − φ:<br><tt><small> 6999 [-1, 0, 0, 0, 0, 0, 0, 0]<br> 7000 [1/2, 0, 0, 0, 0, 0, 0]<br> 7001 [-1/3, 0, 0, 0, 0, 0]<br> 7002 [1/4, 0, 0, 0, 0]<br> 7003 [-1/5, 0, 0, 0]<br> 7004 [1/6, 0, 0]<br> 7005 [-1/7, 0]<br> 7006 [1/8]<br> 7007</small></tt> 7008<p>φ − β:<br><tt><small> 7009 [1, 0, 0, 0, 0, 0, 0, 0]<br> 7010 [1/2, 0, 0, 0, 0, 0, 0]<br> 7011 [1/3, 0, 0, 0, 0, 0]<br> 7012 [1/4, 0, 0, 0, 0]<br> 7013 [1/5, 0, 0, 0]<br> 7014 [1/6, 0, 0]<br> 7015 [1/7, 0]<br> 7016 [1/8]<br> 7017</small></tt> 7018<p>θ − φ:<br><tt><small> 7019 [-2, 0, 2, 0, -2, 0, 2, 0]<br> 7020 [2, 0, -4, 0, 6, 0, -8]<br> 7021 [-8/3, 0, 8, 0, -16, 0]<br> 7022 [4, 0, -16, 0, 40]<br> 7023 [-32/5, 0, 32, 0]<br> 7024 [32/3, 0, -64]<br> 7025 [-128/7, 0]<br> 7026 [32]<br> 7027</small></tt> 7028<p>φ − θ:<br><tt><small> 7029 [2, 0, -2, 0, 2, 0, -2, 0]<br> 7030 [2, 0, -4, 0, 6, 0, -8]<br> 7031 [8/3, 0, -8, 0, 16, 0]<br> 7032 [4, 0, -16, 0, 40]<br> 7033 [32/5, 0, -32, 0]<br> 7034 [32/3, 0, -64]<br> 7035 [128/7, 0]<br> 7036 [32]<br> 7037</small></tt> 7038<p>θ − β:<br><tt><small> 7039 [-1, 0, 0, 0, 0, 0, 0, 0]<br> 7040 [1/2, 0, 0, 0, 0, 0, 0]<br> 7041 [-1/3, 0, 0, 0, 0, 0]<br> 7042 [1/4, 0, 0, 0, 0]<br> 7043 [-1/5, 0, 0, 0]<br> 7044 [1/6, 0, 0]<br> 7045 [-1/7, 0]<br> 7046 [1/8]<br> 7047</small></tt> 7048<p>β − θ:<br><tt><small> 7049 [1, 0, 0, 0, 0, 0, 0, 0]<br> 7050 [1/2, 0, 0, 0, 0, 0, 0]<br> 7051 [1/3, 0, 0, 0, 0, 0]<br> 7052 [1/4, 0, 0, 0, 0]<br> 7053 [1/5, 0, 0, 0]<br> 7054 [1/6, 0, 0]<br> 7055 [1/7, 0]<br> 7056 [1/8]<br> 7057</small></tt> 7058<p>μ − φ:<br><tt><small> 7059 [-3/2, 0, 9/16, 0, -3/32, 0, 57/2048, 0]<br> 7060 [15/16, 0, -15/32, 0, 135/2048, 0, -105/4096]<br> 7061 [-35/48, 0, 105/256, 0, -105/2048, 0]<br> 7062 [315/512, 0, -189/512, 0, 693/16384]<br> 7063 [-693/1280, 0, 693/2048, 0]<br> 7064 [1001/2048, 0, -1287/4096]<br> 7065 [-6435/14336, 0]<br> 7066 [109395/262144]<br> 7067</small></tt> 7068<p>φ − μ:<br><tt><small> 7069 [3/2, 0, -27/32, 0, 269/512, 0, -6607/24576, 0]<br> 7070 [21/16, 0, -55/32, 0, 6759/4096, 0, -155113/122880]<br> 7071 [151/96, 0, -417/128, 0, 87963/20480, 0]<br> 7072 [1097/512, 0, -15543/2560, 0, 2514467/245760]<br> 7073 [8011/2560, 0, -69119/6144, 0]<br> 7074 [293393/61440, 0, -5962461/286720]<br> 7075 [6459601/860160, 0]<br> 7076 [332287993/27525120]<br> 7077</small></tt> 7078<p>μ − β:<br><tt><small> 7079 [-1/2, 0, 3/16, 0, -1/32, 0, 19/2048, 0]<br> 7080 [-1/16, 0, 1/32, 0, -9/2048, 0, 7/4096]<br> 7081 [-1/48, 0, 3/256, 0, -3/2048, 0]<br> 7082 [-5/512, 0, 3/512, 0, -11/16384]<br> 7083 [-7/1280, 0, 7/2048, 0]<br> 7084 [-7/2048, 0, 9/4096]<br> 7085 [-33/14336, 0]<br> 7086 [-429/262144]<br> 7087</small></tt> 7088<p>β − μ:<br><tt><small> 7089 [1/2, 0, -9/32, 0, 205/1536, 0, -4879/73728, 0]<br> 7090 [5/16, 0, -37/96, 0, 1335/4096, 0, -86171/368640]<br> 7091 [29/96, 0, -75/128, 0, 2901/4096, 0]<br> 7092 [539/1536, 0, -2391/2560, 0, 1082857/737280]<br> 7093 [3467/7680, 0, -28223/18432, 0]<br> 7094 [38081/61440, 0, -733437/286720]<br> 7095 [459485/516096, 0]<br> 7096 [109167851/82575360]<br> 7097</small></tt> 7098<p>μ − θ:<br><tt><small> 7099 [1/2, 0, 13/16, 0, -15/32, 0, 509/2048, 0]<br> 7100 [-1/16, 0, 33/32, 0, -1673/2048, 0, 2599/4096]<br> 7101 [-5/16, 0, 349/256, 0, -2989/2048, 0]<br> 7102 [-261/512, 0, 963/512, 0, -43531/16384]<br> 7103 [-921/1280, 0, 5545/2048, 0]<br> 7104 [-6037/6144, 0, 16617/4096]<br> 7105 [-19279/14336, 0]<br> 7106 [-490925/262144]<br> 7107</small></tt> 7108<p>θ − μ:<br><tt><small> 7109 [-1/2, 0, -23/32, 0, 499/1536, 0, -14321/73728, 0]<br> 7110 [5/16, 0, -5/96, 0, 6565/12288, 0, -201467/368640]<br> 7111 [1/32, 0, -77/128, 0, 2939/4096, 0]<br> 7112 [283/1536, 0, -4037/7680, 0, 1155049/737280]<br> 7113 [1301/7680, 0, -19465/18432, 0]<br> 7114 [17089/61440, 0, -442269/286720]<br> 7115 [198115/516096, 0]<br> 7116 [48689387/82575360]<br> 7117</small></tt> 7118<p>χ − φ:<br><tt><small> 7119 [-2, 2/3, 4/3, -82/45, 32/45, 4642/4725, -8384/4725, 1514/1323]<br> 7120 [5/3, -16/15, -13/9, 904/315, -1522/945, -2288/1575, 142607/42525]<br> 7121 [-26/15, 34/21, 8/5, -12686/2835, 44644/14175, 120202/51975]<br> 7122 [1237/630, -12/5, -24832/14175, 1077964/155925, -1097407/187110]<br> 7123 [-734/315, 109598/31185, 1040/567, -12870194/1216215]<br> 7124 [444337/155925, -941912/184275, -126463/72765]<br> 7125 [-2405834/675675, 3463678/467775]<br> 7126 [256663081/56756700]<br> 7127</small></tt> 7128<p>φ − χ:<br><tt><small> 7129 [2, -2/3, -2, 116/45, 26/45, -2854/675, 16822/4725, 189416/99225]<br> 7130 [7/3, -8/5, -227/45, 2704/315, 2323/945, -31256/1575, 141514/8505]<br> 7131 [56/15, -136/35, -1262/105, 73814/2835, 98738/14175, -2363828/31185]<br> 7132 [4279/630, -332/35, -399572/14175, 11763988/155925, 14416399/935550]<br> 7133 [4174/315, -144838/6237, -2046082/31185, 258316372/1216215]<br> 7134 [601676/22275, -115444544/2027025, -2155215124/14189175]<br> 7135 [38341552/675675, -170079376/1216215]<br> 7136 [1383243703/11351340]<br> 7137</small></tt> 7138<p>χ − β:<br><tt><small> 7139 [-1, 2/3, 0, -16/45, 2/5, -998/4725, -34/4725, 1384/11025]<br> 7140 [1/6, -2/5, 19/45, -22/105, -2/27, 1268/4725, -12616/42525]<br> 7141 [-1/15, 16/105, -22/105, 116/567, -1858/14175, 1724/51975]<br> 7142 [17/1260, -8/105, 2123/14175, -26836/155925, 115249/935550]<br> 7143 [-1/105, 128/4455, -424/6237, 140836/1216215]<br> 7144 [149/311850, -31232/2027025, 210152/4729725]<br> 7145 [-499/225225, 30208/6081075]<br> 7146 [-68251/113513400]<br> 7147</small></tt> 7148<p>β − χ:<br><tt><small> 7149 [1, -2/3, -1/3, 38/45, -1/3, -3118/4725, 4769/4725, -25666/99225]<br> 7150 [5/6, -14/15, -7/9, 50/21, -247/270, -14404/4725, 193931/42525]<br> 7151 [16/15, -34/21, -5/3, 17564/2835, -36521/14175, -1709614/155925]<br> 7152 [2069/1260, -28/9, -49877/14175, 2454416/155925, -637699/85050]<br> 7153 [883/315, -28244/4455, -20989/2835, 48124558/1216215]<br> 7154 [797222/155925, -2471888/184275, -16969807/1091475]<br> 7155 [2199332/225225, -1238578/42525]<br> 7156 [87600385/4540536]<br> 7157</small></tt> 7158<p>χ − θ:<br><tt><small> 7159 [0, 2/3, 2/3, -2/9, -14/45, 1042/4725, 18/175, -1738/11025]<br> 7160 [-1/3, 4/15, 43/45, -4/45, -712/945, 332/945, 23159/42525]<br> 7161 [-2/5, 2/105, 124/105, 274/2835, -1352/945, 13102/31185]<br> 7162 [-55/126, -16/105, 21068/14175, 1528/4725, -2414843/935550]<br> 7163 [-22/45, -9202/31185, 20704/10395, 60334/93555]<br> 7164 [-90263/155925, -299444/675675, 40458083/14189175]<br> 7165 [-8962/12285, -3818498/6081075]<br> 7166 [-4259027/4365900]<br> 7167</small></tt> 7168<p>θ − χ:<br><tt><small> 7169 [0, -2/3, -2/3, 4/9, 2/9, -3658/4725, 76/225, 64424/99225]<br> 7170 [1/3, -4/15, -23/45, 68/45, 61/135, -2728/945, 2146/1215]<br> 7171 [2/5, -24/35, -46/35, 9446/2835, 428/945, -95948/10395]<br> 7172 [83/126, -80/63, -34712/14175, 4472/525, 29741/85050]<br> 7173 [52/45, -2362/891, -17432/3465, 280108/13365]<br> 7174 [335882/155925, -548752/96525, -48965632/4729725]<br> 7175 [51368/12285, -197456/15795]<br> 7176 [1461335/174636]<br> 7177</small></tt> 7178<p>χ − μ:<br><tt><small> 7179 [-1/2, 2/3, -37/96, 1/360, 81/512, -96199/604800, 5406467/38707200, -7944359/67737600]<br> 7180 [-1/48, -1/15, 437/1440, -46/105, 1118711/3870720, -51841/1209600, -24749483/348364800]<br> 7181 [-17/480, 37/840, 209/4480, -5569/90720, -9261899/58060800, 6457463/17740800]<br> 7182 [-4397/161280, 11/504, 830251/7257600, -466511/2494800, -324154477/7664025600]<br> 7183 [-4583/161280, 108847/3991680, 8005831/63866880, -22894433/124540416]<br> 7184 [-20648693/638668800, 16363163/518918400, 2204645983/12915302400]<br> 7185 [-219941297/5535129600, 497323811/12454041600]<br> 7186 [-191773887257/3719607091200]<br> 7187</small></tt> 7188<p>μ − χ:<br><tt><small> 7189 [1/2, -2/3, 5/16, 41/180, -127/288, 7891/37800, 72161/387072, -18975107/50803200]<br> 7190 [13/48, -3/5, 557/1440, 281/630, -1983433/1935360, 13769/28800, 148003883/174182400]<br> 7191 [61/240, -103/140, 15061/26880, 167603/181440, -67102379/29030400, 79682431/79833600]<br> 7192 [49561/161280, -179/168, 6601661/7257600, 97445/49896, -40176129013/7664025600]<br> 7193 [34729/80640, -3418889/1995840, 14644087/9123840, 2605413599/622702080]<br> 7194 [212378941/319334400, -30705481/10378368, 175214326799/58118860800]<br> 7195 [1522256789/1383782400, -16759934899/3113510400]<br> 7196 [1424729850961/743921418240]<br> 7197</small></tt> 7198<p>ξ − φ:<br><tt><small> 7199 [-4/3, -4/45, 88/315, 538/4725, 20824/467775, -44732/2837835, -86728/16372125, -88002076/13956067125]<br> 7200 [34/45, 8/105, -2482/14175, -37192/467775, -12467764/212837625, -895712/147349125, -2641983469/488462349375]<br> 7201 [-1532/2835, -898/14175, 54968/467775, 100320856/1915538625, 240616/4209975, 8457703444/488462349375]<br> 7202 [6007/14175, 24496/467775, -5884124/70945875, -4832848/147349125, -4910552477/97692469875]<br> 7203 [-23356/66825, -839792/19348875, 816824/13395375, 9393713176/488462349375]<br> 7204 [570284222/1915538625, 1980656/54729675, -4532926649/97692469875]<br> 7205 [-496894276/1915538625, -14848113968/488462349375]<br> 7206 [224557742191/976924698750]<br> 7207</small></tt> 7208<p>φ − ξ:<br><tt><small> 7209 [4/3, 4/45, -16/35, -2582/14175, 60136/467775, 28112932/212837625, 22947844/1915538625, -1683291094/37574026875]<br> 7210 [46/45, 152/945, -11966/14175, -21016/51975, 251310128/638512875, 1228352/3007125, -14351220203/488462349375]<br> 7211 [3044/2835, 3802/14175, -94388/66825, -8797648/10945935, 138128272/147349125, 505559334506/488462349375]<br> 7212 [6059/4725, 41072/93555, -1472637812/638512875, -45079184/29469825, 973080708361/488462349375]<br> 7213 [768272/467775, 455935736/638512875, -550000184/147349125, -1385645336626/488462349375]<br> 7214 [4210684958/1915538625, 443810768/383107725, -2939205114427/488462349375]<br> 7215 [387227992/127702575, 101885255158/54273594375]<br> 7216 [1392441148867/325641566250]<br> 7217</small></tt> 7218<p>ξ − β:<br><tt><small> 7219 [-1/3, -4/45, 32/315, 34/675, 2476/467775, -70496/8513505, -18484/4343625, 29232878/97692469875]<br> 7220 [-7/90, -4/315, 74/2025, 3992/467775, 53836/212837625, -4160804/1915538625, -324943819/488462349375]<br> 7221 [-83/2835, 2/14175, 7052/467775, -661844/1915538625, 237052/383107725, -168643106/488462349375]<br> 7222 [-797/56700, 934/467775, 1425778/212837625, -2915326/1915538625, 113042383/97692469875]<br> 7223 [-3673/467775, 390088/212837625, 6064888/1915538625, -558526274/488462349375]<br> 7224 [-18623681/3831077250, 41288/29469825, 155665021/97692469875]<br> 7225 [-6205669/1915538625, 504234982/488462349375]<br> 7226 [-8913001661/3907698795000]<br> 7227</small></tt> 7228<p>β − ξ:<br><tt><small> 7229 [1/3, 4/45, -46/315, -1082/14175, 11824/467775, 7947332/212837625, 9708931/1915538625, -5946082372/488462349375]<br> 7230 [17/90, 68/945, -338/2025, -16672/155925, 39946703/638512875, 164328266/1915538625, 190673521/69780335625]<br> 7231 [461/2835, 1102/14175, -101069/467775, -255454/1563705, 236067184/1915538625, 86402898356/488462349375]<br> 7232 [3161/18900, 1786/18711, -189032762/638512875, -98401826/383107725, 110123070361/488462349375]<br> 7233 [88868/467775, 80274086/638512875, -802887278/1915538625, -200020620676/488462349375]<br> 7234 [880980241/3831077250, 66263486/383107725, -296107325077/488462349375]<br> 7235 [37151038/127702575, 4433064236/18091198125]<br> 7236 [495248998393/1302566265000]<br> 7237</small></tt> 7238<p>ξ − θ:<br><tt><small> 7239 [2/3, -4/45, 62/105, 778/4725, -193082/467775, -4286228/42567525, 53702182/212837625, 182466964/8881133625]<br> 7240 [4/45, -32/315, 12338/14175, 92696/467775, -61623938/70945875, -32500616/273648375, 367082779691/488462349375]<br> 7241 [-524/2835, -1618/14175, 612536/467775, 427003576/1915538625, -663111728/383107725, -42668482796/488462349375]<br> 7242 [-5933/14175, -8324/66825, 427770788/212837625, 421877252/1915538625, -327791986997/97692469875]<br> 7243 [-320044/467775, -9153184/70945875, 6024982024/1915538625, 74612072536/488462349375]<br> 7244 [-1978771378/1915538625, -46140784/383107725, 489898512247/97692469875]<br> 7245 [-2926201612/1915538625, -42056042768/488462349375]<br> 7246 [-2209250801969/976924698750]<br> 7247</small></tt> 7248<p>θ − ξ:<br><tt><small> 7249 [-2/3, 4/45, -158/315, -2102/14175, 109042/467775, 216932/2627625, -189115382/1915538625, -230886326/6343666875]<br> 7250 [16/45, -16/945, 934/14175, -7256/155925, 117952358/638512875, 288456008/1915538625, -11696145869/69780335625]<br> 7251 [-232/2835, 922/14175, -25286/66825, -7391576/54729675, 478700902/1915538625, 91546732346/488462349375]<br> 7252 [719/4725, 268/18711, -67048172/638512875, -67330724/383107725, 218929662961/488462349375]<br> 7253 [14354/467775, 46774256/638512875, -117954842/273648375, -129039188386/488462349375]<br> 7254 [253129538/1915538625, 2114368/34827975, -178084928947/488462349375]<br> 7255 [13805944/127702575, 6489189398/54273594375]<br> 7256 [59983985827/325641566250]<br> 7257</small></tt> 7258<p>ξ − μ:<br><tt><small> 7259 [1/6, -4/45, -817/10080, 1297/18900, 7764059/239500800, -9292991/302702400, -25359310709/1743565824000, 39534358147/2858202547200]<br> 7260 [49/720, -2/35, -29609/453600, 35474/467775, 36019108271/871782912000, -14814966289/245188944000, -13216941177599/571640509440000]<br> 7261 [4463/90720, -2917/56700, -4306823/59875200, 3026004511/30648618000, 99871724539/1569209241600, -27782109847927/250092722880000]<br> 7262 [331799/7257600, -102293/1871100, -368661577/4036032000, 2123926699/15324309000, 168979300892599/1600593426432000]<br> 7263 [11744233/239500800, -875457073/13621608000, -493031379277/3923023104000, 1959350112697/9618950880000]<br> 7264 [453002260127/7846046208000, -793693009/9807557760, -145659994071373/800296713216000]<br> 7265 [103558761539/1426553856000, -53583096419057/500185445760000]<br> 7266 [12272105438887727/128047474114560000]<br> 7267</small></tt> 7268<p>μ − ξ:<br><tt><small> 7269 [-1/6, 4/45, 121/1680, -1609/28350, -384229/14968800, 12674323/851350500, 7183403063/560431872000, -375027460897/125046361440000]<br> 7270 [-29/720, 26/945, 16463/453600, -431/17325, -31621753811/1307674368000, 1117820213/122594472000, 30410873385097/2000741783040000]<br> 7271 [-1003/45360, 449/28350, 3746047/119750400, -32844781/1751349600, -116359346641/3923023104000, 151567502183/17863765920000]<br> 7272 [-40457/2419200, 629/53460, 10650637121/326918592000, -13060303/766215450, -317251099510901/8002967132160000]<br> 7273 [-1800439/119750400, 205072597/20432412000, 146875240637/3923023104000, -2105440822861/125046361440000]<br> 7274 [-59109051671/3923023104000, 228253559/24518894400, 91496147778023/2000741783040000]<br> 7275 [-4255034947/261534873600, 126430355893/13894040160000]<br> 7276 [-791820407649841/42682491371520000]<br> 7277</small></tt> 7278<p>ξ − χ:<br><tt><small> 7279 [2/3, -34/45, 46/315, 2458/4725, -55222/93555, 2706758/42567525, 16676974/30405375, -64724382148/97692469875]<br> 7280 [19/45, -256/315, 3413/14175, 516944/467775, -340492279/212837625, 158999572/1915538625, 85904355287/37574026875]<br> 7281 [248/567, -15958/14175, 206834/467775, 4430783356/1915538625, -7597644214/1915538625, 2986003168/37574026875]<br> 7282 [16049/28350, -832976/467775, 62016436/70945875, 851209552/174139875, -375566203/39037950]<br> 7283 [15602/18711, -651151712/212837625, 3475643362/1915538625, 5106181018156/488462349375]<br> 7284 [2561772812/1915538625, -10656173804/1915538625, 34581190223/8881133625]<br> 7285 [873037408/383107725, -5150169424688/488462349375]<br> 7286 [7939103697617/1953849397500]<br> 7287</small></tt> 7288<p>χ − ξ:<br><tt><small> 7289 [-2/3, 34/45, -88/315, -2312/14175, 27128/93555, -55271278/212837625, 308365186/1915538625, -17451293242/488462349375]<br> 7290 [1/45, -184/945, 6079/14175, -65864/155925, 106691108/638512875, 149984636/1915538625, -101520127208/488462349375]<br> 7291 [-106/2835, 772/14175, -14246/467775, 5921152/54729675, -99534832/383107725, 10010741462/37574026875]<br> 7292 [-167/9450, -5312/467775, 75594328/638512875, -35573728/273648375, 1615002539/75148053750]<br> 7293 [-248/13365, 2837636/638512875, 130601488/1915538625, -3358119706/488462349375]<br> 7294 [-34761247/1915538625, -3196/3553875, 46771947158/488462349375]<br> 7295 [-2530364/127702575, -18696014/18091198125]<br> 7296 [-14744861191/651283132500]<br> 7297</small></tt> 7298 7299\section auxlaterror Truncation errors 7300 7301There are two sources of error when using these series. The truncation 7302error arises from retaing terms up to a certain order in \e n; it is the 7303absolute difference between the value of the truncated series compared 7304with the exact latitude (evaluated with exact arithmetic). In addition, 7305using standard double-precision arithmetic entails accumulating 7306round-off errors so that at the end of a complex calculation a few of 7307the trailing bits of the result are wrong. 7308 7309Here's a table of the truncation errors. The errors are given in "units 7310in the last place (ulp)" where 1 ulp = 2<sup>−53</sup> radian = 73116.4 × 10<sup>−15</sup> degree = 2.3 × 731210<sup>−11</sup> arcsecond which is a measure of the round-off 7313error for double precision. Here is some rough guidance on how to 7314interpret these errors: 7315- if the truncation error is less than 1 ulp, then round-off errors 7316 dominate; 7317- if the truncation error is greater than 8 ulp, then truncation errors 7318 dominate; 7319- otherwise, round-off and truncation errors are comparable. 7320. 7321The truncation errors are given accurate to 2 significant figures. 7322 7323<center> 7324<table> 7325<caption>Auxiliary latitude truncation errors (ulp)</caption> 7326<tr> 7327<th rowspan="2"> expression 7328<th colspan="2"> [<i>f</i> = 1/150, order = 6] 7329<th colspan="2"> [<i>f</i> = 1/297, order = 5] 7330<tr> 7331<th> <i>n</i> series <th> <i>e</i><sup>2</sup> series 7332<th> <i>n</i> series <th> <i>e</i><sup>2</sup> series 7333<tr><td> β − φ <td><tt><center> 0.0060 </center></tt><td><tt><center> 28 </center></tt><td><tt><center> 0.035 </center></tt><td><tt><center> 41 </center></tt> 7334<tr><td> φ − β <td><tt><center> 0.0060 </center></tt><td><tt><center> 28 </center></tt><td><tt><center> 0.035 </center></tt><td><tt><center> 41 </center></tt> 7335<tr><td> θ − φ <td><tt><center> 2.9 </center></tt><td><tt><center> 82 </center></tt><td><tt><center> 6.0 </center></tt><td><tt><center> 120 </center></tt> 7336<tr><td> φ − θ <td><tt><center> 2.9 </center></tt><td><tt><center> 82 </center></tt><td><tt><center> 6.0 </center></tt><td><tt><center> 120 </center></tt> 7337<tr><td> θ − β <td><tt><center> 0.0060 </center></tt><td><tt><center> 28 </center></tt><td><tt><center> 0.035 </center></tt><td><tt><center> 41 </center></tt> 7338<tr><td> β − θ <td><tt><center> 0.0060 </center></tt><td><tt><center> 28 </center></tt><td><tt><center> 0.035 </center></tt><td><tt><center> 41 </center></tt> 7339<tr><td> μ − φ <td><tt><center> 0.037 </center></tt><td><tt><center> 41 </center></tt><td><tt><center> 0.18 </center></tt><td><tt><center> 60 </center></tt> 7340<tr><td> φ − μ <td><tt><center> 0.98 </center></tt><td><tt><center> 59 </center></tt><td><tt><center> 2.3 </center></tt><td><tt><center> 84 </center></tt> 7341<tr><td> μ − β <td><tt><center> 0.00069 </center></tt><td><tt><center> 5.8 </center></tt><td><tt><center> 0.0024 </center></tt><td><tt><center> 9.6 </center></tt> 7342<tr><td> β − μ <td><tt><center> 0.13 </center></tt><td><tt><center> 12 </center></tt><td><tt><center> 0.35 </center></tt><td><tt><center> 19 </center></tt> 7343<tr><td> μ − θ <td><tt><center> 0.24 </center></tt><td><tt><center> 30 </center></tt><td><tt><center> 0.67 </center></tt><td><tt><center> 40 </center></tt> 7344<tr><td> θ − μ <td><tt><center> 0.099 </center></tt><td><tt><center> 23 </center></tt><td><tt><center> 0.23 </center></tt><td><tt><center> 33 </center></tt> 7345<tr><td> χ − φ <td><tt><center> 0.78 </center></tt><td><tt><center> 43 </center></tt><td><tt><center> 2.1 </center></tt><td><tt><center> 64 </center></tt> 7346<tr><td> φ − χ <td><tt><center> 9.0 </center></tt><td><tt><center> 71 </center></tt><td><tt><center> 17 </center></tt><td><tt><center> 100 </center></tt> 7347<tr><td> χ − β <td><tt><center> 0.018 </center></tt><td><tt><center> 3.7 </center></tt><td><tt><center> 0.11 </center></tt><td><tt><center> 6.4 </center></tt> 7348<tr><td> β − χ <td><tt><center> 1.7 </center></tt><td><tt><center> 16 </center></tt><td><tt><center> 3.4 </center></tt><td><tt><center> 24 </center></tt> 7349<tr><td> χ − θ <td><tt><center> 0.18 </center></tt><td><tt><center> 31 </center></tt><td><tt><center> 0.56 </center></tt><td><tt><center> 43 </center></tt> 7350<tr><td> θ − χ <td><tt><center> 0.87 </center></tt><td><tt><center> 23 </center></tt><td><tt><center> 1.9 </center></tt><td><tt><center> 32 </center></tt> 7351<tr><td> χ − μ <td><tt><center> 0.022 </center></tt><td><tt><center> 0.56 </center></tt><td><tt><center> 0.11 </center></tt><td><tt><center> 0.91 </center></tt> 7352<tr><td> μ − χ <td><tt><center> 0.31 </center></tt><td><tt><center> 1.2 </center></tt><td><tt><center> 0.86 </center></tt><td><tt><center> 2.0 </center></tt> 7353<tr><td> ξ − φ <td><tt><center> 0.015 </center></tt><td><tt><center> 39 </center></tt><td><tt><center> 0.086 </center></tt><td><tt><center> 57 </center></tt> 7354<tr><td> φ − ξ <td><tt><center> 0.34 </center></tt><td><tt><center> 53 </center></tt><td><tt><center> 1.1 </center></tt><td><tt><center> 75 </center></tt> 7355<tr><td> ξ − β <td><tt><center> 0.00042 </center></tt><td><tt><center> 6.3 </center></tt><td><tt><center> 0.0039 </center></tt><td><tt><center> 10 </center></tt> 7356<tr><td> β − ξ <td><tt><center> 0.040 </center></tt><td><tt><center> 10 </center></tt><td><tt><center> 0.15 </center></tt><td><tt><center> 15 </center></tt> 7357<tr><td> ξ − θ <td><tt><center> 0.28 </center></tt><td><tt><center> 28 </center></tt><td><tt><center> 0.75 </center></tt><td><tt><center> 38 </center></tt> 7358<tr><td> θ − ξ <td><tt><center> 0.040 </center></tt><td><tt><center> 23 </center></tt><td><tt><center> 0.11 </center></tt><td><tt><center> 33 </center></tt> 7359<tr><td> ξ − μ <td><tt><center> 0.015 </center></tt><td><tt><center> 0.79 </center></tt><td><tt><center> 0.058 </center></tt><td><tt><center> 1.5 </center></tt> 7360<tr><td> μ − ξ <td><tt><center> 0.0043 </center></tt><td><tt><center> 0.54 </center></tt><td><tt><center> 0.018 </center></tt><td><tt><center> 1.1 </center></tt> 7361<tr><td> ξ − χ <td><tt><center> 0.60 </center></tt><td><tt><center> 1.9 </center></tt><td><tt><center> 1.5 </center></tt><td><tt><center> 3.6 </center></tt> 7362<tr><td> χ − ξ <td><tt><center> 0.023 </center></tt><td><tt><center> 0.53 </center></tt><td><tt><center> 0.079 </center></tt><td><tt><center> 0.92 </center></tt> 7363</table> 7364</center> 7365 7366\if SKIP 7367 0 beta phi ,0.0060!,28!!!,!0.035!,!41!!! 7368 1 phi beta ,0.0060!,28!!!,!0.035!,!41!!! 7369 2 theta phi ,2.9!!!!,82!!!,!6.0!!!,120!!! 7370 3 phi theta,2.9!!!!,82!!!,!6.0!!!,120!!! 7371 4 theta beta ,0.0060!,28!!!,!0.035!,!41!!! 7372 5 beta theta,0.0060!,28!!!,!0.035!,!41!!! 7373 6 mu phi ,0.037!!,41!!!,!0.18!!,!60!!! 7374 7 phi mu ,0.98!!!,59!!!,!2.3!!!,!84!!! 7375 8 mu beta ,0.00069,!5.8!,!0.0024,!!9.6! 7376 9 beta mu ,0.13!!!,12!!!,!0.35!!,!19!!! 737710 mu theta,0.24!!!,30!!!,!0.67!!,!40!!! 737811 theta mu ,0.099!!,23!!!,!0.23!!,!33!!! 737912 chi phi ,0.78!!!,43!!!,!2.1!!!,!64!!! 738013 phi chi ,9.0!!!!,71!!!,17!!!!!,100!!! 738114 chi beta ,0.018!!,!3.7!,!0.11!!,!!6.4! 738215 beta chi ,1.7!!!!,16!!!,!3.4!!!,!24!!! 738316 chi theta,0.18!!!,31!!!,!0.56!!,!43!!! 738417 theta chi ,0.87!!!,23!!!,!1.9!!!,!32!!! 738518 chi mu ,0.022!!,!0.56,!0.11!!,!!0.91 738619 mu chi ,0.31!!!,!1.2!,!0.86!!,!!2.0! 738720 xi phi ,0.015!!,39!!!,!0.086!,!57!!! 738821 phi xi ,0.34!!!,53!!!,!1.1!!!,!75!!! 738922 xi beta ,0.00042,!6.3!,!0.0039,!10!!! 739023 beta xi ,0.040!!,10!!!,!0.15!!,!15!!! 739124 xi theta,0.28!!!,28!!!,!0.75!!,!38!!! 739225 theta xi ,0.040!!,23!!!,!0.11!!,!33!!! 739326 xi mu ,0.015!!,!0.79,!0.058!,!!1.5! 739427 mu xi ,0.0043!,!0.54,!0.018!,!!1.1! 739528 xi chi ,0.60!!!,!1.9!,!1.5!!!,!!3.6! 739629 chi xi ,0.023!!,!0.53,!0.079!,!!0.92 7397\endif 7398 7399The 2nd and 3rd columns show the results for the SRMmax ellipsoid, \e f 7400= 1/150, retaining 6th order terms in the series expansion. The 4th and 74015th columns show the results for the International ellipsoid, \e f = 74021/297, retaining 5th order terms in the series expansion. The 2nd and 74034th columns give the errors for the series expansions in terms of \e n 7404given in this section (appropriately truncated). The 3rd and 5th 7405columns give the errors when the series are reexpanded in terms of 7406<i>e</i><sup>2</sup> = 4\e n/(1 + \e n)<sup>2</sup> and truncated 7407retaining the <i>e</i><sup>12</sup> and <i>e</i><sup>10</sup> terms 7408respectively. 7409 7410Some observations: 7411- For production use, the 6th order series in \e n are recommended. For 7412 \e f = 1/150, the resulting errors are close to the round-off limit. 7413 The errors in the 6th order series scale as <i>f</i><sup>7</sup>; so 7414 the errors with \e f = 1/297 are about 120 times smaller. 7415- It's inadvisable to use the 5th order series in \e n; this order is 7416 barely acceptable for \e f = 1/297 and the errors grow as 7417 <i>f</i><sup>6</sup> as \e f is increased. 7418- In all cases, the expansions in terms of <i>e</i><sup>2</sup> are 7419 considerably less accurate than the corresponding series in \e n. 7420- For every series converting between φ and any of θ, μ, 7421 χ, or ξ, the series where β is substituted for φ is 7422 more accurate. Considering that the transformation between φ and 7423 β is so simple, tanβ = (1 - \e f) tanφ, it sometimes 7424 makes sense to use β internally as the basic measure of latitude. 7425 (This is the case with geodesic calculations.) 7426 7427<center> 7428Back to \ref geocentric. Forward to \ref highprec. Up to \ref contents. 7429</center> 7430 7431**********************************************************************/ 7432/** 7433\page highprec Support for high precision arithmetic 7434 7435<center> 7436Back to \ref auxlat. Forward to \ref changes. Up to \ref contents. 7437</center> 7438 7439One of the goals with the algorithms in GeographicLib is to deliver 7440accuracy close to the limits for double precision. In order to develop 7441such algorithms it is very useful to be have accurate test data. For 7442this purpose, I used Maxima's bfloat capability, which support arbitrary 7443precision floating point arithmetic. As of version 1.37, such 7444high-precision test data can be generated directly by GeographicLib by 7445compiling it with <code>GEOGRAPHICLIB_PRECISION</code> equal to 4 or 5. 7446 7447Here's what you should know: 7448 - This is mainly for use for algorithm developers. It's not 7449 recommended for installation for all users on a system. 7450 - Configuring with <code>-D GEOGRAPHICLIB_PRECISION=4</code> gives quad 7451 precision (113-bit precision) via boost::multiprecision::float128; 7452 this requires: 7453 - <a href="https://www.boost.org"> Boost</a>, version 1.64 or later, 7454 - the quadmath library (the package names are libquadmath 7455 and libquadmath-devel), 7456 - the use of g++. 7457 - Configuring with <code>-D GEOGRAPHICLIB_PRECISION=5</code> gives 7458 arbitrary precision via mpfr::mpreal; this requires: 7459 - <a href="https://www.mpfr.org"> MPFR</a>, version 3.0 or later, 7460 - <a href="http://www.holoborodko.com/pavel/mpfr"> MPFR C++</a> 7461 (version 3.6.8, dated 2020-10-29, or later; version 3.6.8 also 7462 requires the fixes given in pull requests #8 and #10), 7463 - a compiler which supports the explicit cast operator (e.g., g++ 4.5 7464 or later, Visual Studio 12 2013 or later). 7465 - MPFR, MPFR C++, and Boost all come with their own licenses. Be sure 7466 to respect these. 7467 - The indicated precision is used for <b>all</b> floating point 7468 arithmetic. Thus, you can't compare the results of different 7469 precisions within a single invocation of a program. Instead, you can 7470 create a file of accurate test data at a high precision and use this 7471 to test the algorithms at double precision. 7472 - With MPFR, the precision should be set (using Utility::set_digits) 7473 just once before any other GeographicLib routines are called. 7474 Calling this function after other GeographicLib routines will lead to 7475 inconsistent results (because the precision of some constants like 7476 Math::pi() is set when the functions are first called). 7477 - All the \ref utilities call Utility::set_digits() (with no 7478 arguments). This causes the precision (in bits) to be determined by 7479 the <code>GEOGRAPHICLIB_DIGITS</code> environment variable. If this 7480 is not defined the precision is set to 256 bits (about 77 decimal 7481 digits). 7482 - The accuracy of most calculations should increase as the precision 7483 increases (and typically only a few bits of accuracy should be lost). 7484 We can distinguish 4 sources of error: 7485 - Round-off errors; these are reliably reduced when the precision is 7486 increased. For the most part, the algorithms used by GeographicLib 7487 are carefully tuned to minimize round-off errors, so that only a 7488 few bits of accuracy are lost. 7489 - Convergence errors due to not iterating certain algorithms to 7490 convergence. However, all iterative methods used by GeographicLib 7491 converge quadratically (the number of correct digits doubles on 7492 each iteration) so that full convergence is obtained for 7493 "reasonable" precisions (no more than, say, 100 decimal digits or 7494 about 340 bits). An exception is thrown if the convergence 7495 criterion is not met when using high precision arithmetic. 7496 - Truncation errors. Some classes (namely, Geodesic and 7497 TransverseMercator) use series expansion to approximate the true 7498 solution. Additional terms in the series are used for high 7499 precision, however there's always a finite truncation error which 7500 varies as some power of the flattening. On the other hand, 7501 GeodesicExact and TransverseMercatorExact are somewhat slower 7502 classes offering the same functionality implemented with 7503 EllipticFunction. These classes provide arbitrary accuracy. 7504 (However, a caveat is that the evaluation of the area in 7505 GeodesicExact still uses a series (albeit of considerably higher 7506 order). So the area calculations are always have a finite 7507 truncation error.) 7508 - Quantization errors. Geoid, GravityModel, and MagneticModel all 7509 depend on external data files. The coefficient files for 7510 GravityModel and MagneticModel store the coefficients as IEEE 7511 doubles (and perhaps these coefficients can be regarded as exact). 7512 However, with Geoid, the data files for the geoid heights are 7513 quantized at 3mm leading to an irreducible ±1.5mm 7514 quantization error. On the other hand, all the physical constants 7515 used by GeographicLib, e.g., the flattening of the WGS84 ellipsoid, 7516 are evaluated as exact decimal numbers. 7517 - Where might high accuracy be important? 7518 - checking the truncation error of series approximations; 7519 - checking for excessive round-off errors (typically due to subtraction); 7520 - checking the round-off error in computing areas of many-sided polygons; 7521 - checking the summation of high order spherical harmonic expansions 7522 (where underflow and overflow may also be a problem). 7523 - Because only a tiny number of people will be interested in using this 7524 facility: 7525 - the cmake support for the required libraries is rudimentary; 7526 - however geographiclib-config.cmake does export 7527 <code>GEOGRAPHICLIB_PRECISION</code> and 7528 <code>GEOGRAPHICLIB_HIGHPREC_LIBRARIES</code>, the libraries 7529 providing the support for high-precision arithmetic; 7530 - support for the C++11 mathematical functions and the explicit cast 7531 operator is required; 7532 - quad precision is only available on Linux; 7533 - mpfr has been mostly tested on Linux (but it works on Windows with 7534 Visual Studio 12 and MacOS too). 7535 7536The following steps needed to be taken 7537 7538 - Phase 1, make sure you can switch easily between double, float, and 7539 long double. 7540 - use <code>\#include <cmath></code> instead of <code>\#include 7541 <math.h></code>; 7542 - use, e.g., <code>std::sqrt</code> instead of <code>sqrt</code> in 7543 header files (similarly for <code>sin</code>, <code>cos</code>, 7544 <code>atan2</code>, etc.); 7545 - use <code>using namespace std;</code> and plain <code>sqrt</code>, 7546 etc., in code files; 7547 - express all convergence criteria in terms of\code 7548 numeric_limits<double>::epsilon() \endcode 7549 etc., instead of using "magic constants", such as 1.0e-15; 7550 - use <code>typedef double real;</code> and replace all occurrences of 7551 <code>double</code> by <code>real</code>; 7552 - write all literals by, e.g., <code>real(0.5)</code>. Some 7553 constants might need the L suffix, e.g., <code>real f = 7554 1/real(298.257223563L)</code> (but see below); 7555 - Change the typedef of <code>real</code> to <code>float</code> or 7556 <code>long double</code>, compile, and test. In this way, the 7557 library can be run with any of the three basic floating point 7558 types. 7559 - If you want to run the library with multiple floating point types 7560 within a single executable, then make all your classes take a 7561 template parameter specifying the floating-point type and 7562 instantiate your classes with the floating-point types that you 7563 plan to use. I did not take this approach with GeographicLib 7564 because double precision is suitable for the vast majority of 7565 applications and turning all the classes into templates classes 7566 would end up needlessly complicating (and bloating) the library. 7567 7568 - Phase 2, changes to support arbitrary, but fixed, precision 7569 - Use, e.g., \code 7570 typedef boost::multiprecision::float128 real; \endcode 7571 - Change <code>std::sqrt(...)</code>, etc. to \code 7572 using std::sqrt; 7573 sqrt(...) \endcode 7574 (but note that <code>std::max</code> can stay). It's only necessary 7575 to do this in header files (code files already have <code>using 7576 namespace std;</code>). 7577 - In the case of boost's multiprecision numbers, the C++11 7578 mathematical functions need special treatment, see Math.hpp. 7579 - If necessary, use series with additional terms to improve the 7580 accuracy. 7581 - Replace slowly converging root finding methods with rapidly 7582 converging methods. In particular, the simple iterative method to 7583 determine the flattening from the dynamical form factor in 7584 NormalGravity converged too slowly; this was replaced by Newton's 7585 method. 7586 - If necessary, increase the maximum allowed iteration count in root 7587 finding loops. Also throw an exception of the maximum iteration 7588 count is exceeded. 7589 - Write literal constants in a way that works for any precision, e.g., 7590 \code 7591 real f = 1/( real(298257223563LL) / 1000000000 ); \endcode 7592 [Note that \code 7593 real f = 1/( 298 + real(257223563) / 1000000000 ); \endcode 7594 and <code>1/real(298.257223563L)</code> are susceptible to 7595 double rounding errors. We normally want to avoid such errors when 7596 real is a double.] 7597 - For arbitrary constants, you might have to resort to macros \code 7598 #if GEOGRAPHICLIB_PRECISION == 1 7599 #define REAL(x) x##F 7600 #elif GEOGRAPHICLIB_PRECISION == 2 7601 #define REAL(x) x 7602 #elif GEOGRAPHICLIB_PRECISION == 3 7603 #define REAL(x) x##L 7604 #elif GEOGRAPHICLIB_PRECISION == 4 7605 #define REAL(x) x##Q 7606 #else 7607 #define REAL(x) real(#x) 7608 #endif \endcode 7609 and then use \code 7610 real f = 1/REAL(298.257223563); \endcode 7611 - Perhaps use local static declarations to avoid the overhead of 7612 reevaluating constants, e.g., \code 7613 static inline real pi() { 7614 using std::atan2; 7615 // pi is computed just once 7616 static const real pi = atan2(real(0), real(-1)); 7617 return pi; 7618 } \endcode 7619 This is <b>not</b> necessary for built-in floating point types, 7620 since the atan2 function will be evaluated at compile time. 7621 - In Utility::readarray and Utility::writearray, arrays of reals were 7622 treated as plain old data. This assumption now no longer holds and 7623 these functions needed special treatment. 7624 - volatile declarations don't apply. 7625 7626 - Phase 3, changes to support arbitrary precision which can be set at 7627 runtime. 7628 - The big change now is that the precision is not known at compile 7629 time. All static initializations which involve floating point 7630 numbers need to be eliminated. 7631 - Some static variables (e.g., tolerances which are expressed in 7632 terms of <code>numeric_limits<double>\::epsilon()</code>) 7633 were made member variables and so initialized when the 7634 constructor was called. 7635 - Some simple static real arrays (e.g., the interpolating stencils 7636 for Geoid) were changed into integer arrays. 7637 - Some static variables where converted to static functions similar 7638 to the definition of pi() above. 7639 - All the static instances of classes where converted as follows 7640 \code 7641 // declaration 7642 static const Geodesic WGS84; 7643 // definition 7644 const Geodesic Geodesic::WGS84(Constants::WGS84_a(), 7645 Constants::WGS84_f()); 7646 // use 7647 const Geodesic& geod = Geodesic::WGS84; \endcode 7648 becomes \code 7649 // declaration 7650 static const Geodesic& WGS84(); 7651 // definition 7652 const Geodesic& Geodesic::WGS84() { 7653 static const Geodesic wgs84(Constants::WGS84_a(), 7654 Constants::WGS84_f()); 7655 return wgs84; 7656 static const Geodesic& WGS84(); 7657 } 7658 // use 7659 const Geodesic& geod = Geodesic::WGS84(); \endcode 7660 This is the so-called 7661 <a href="https://isocpp.org/wiki/faq/ctors#static-init-order-on-first-use"> 7662 "construct on first use idiom"</a>. This is the most disruptive 7663 of the changes since it requires a different calling convention 7664 in user code. However the old static initializations were 7665 invoked every time a code linking to GeographicLib was started, 7666 even if the objects were not subsequently used. The new method 7667 only initializes the static objects if they are used. 7668 . 7669 - <code>numeric_limits<double>\::digits</code> is no longer a 7670 compile-time constant. It becomes 7671 <code>numeric_limits<double>\::digits()</code>. 7672 - Depending on the precision cos(π/2) might be negative. 7673 Similarly atan(tan(π/2)) may evaluate to −π/2. 7674 GeographicLib already handled this, because this happens with long 7675 doubles (64 bits in the fraction). 7676 - The precision needs to be set in each thread in a multi-processing 7677 applications (for an example, see 7678 <code>examples/GeoidToGTX.cpp</code>). 7679 - Passing numbers to functions by value incurs a substantially higher 7680 overhead than with doubles. This could be avoided by passing such 7681 arguments by reference. This was <b>not</b> done here because it 7682 would junk up the code to benefit a narrow application. 7683 - The constants in GeodesicExact, e.g., 831281402884796906843926125, 7684 can't be specified as long doubles nor long longs (since they have 7685 more than 64 significant bits): 7686 - first tried macro which expanded to a string (see the macro REAL 7687 above); 7688 - now use inline function to combine two long long ints each with at 7689 most 52 significant bits; 7690 - also needed to simplify one routine in GeodesicExact which took 7691 inordinately long (15 minutes) to compile using g++; 7692 - but Visual Studio 12 then complained (with an 7693 internal compiler error</a> presumably due to overly aggressive 7694 whole-file optimization); fixed by splitting one function into a 7695 separate file. 7696 7697<center> 7698Back to \ref auxlat. Forward to \ref changes. Up to \ref contents. 7699</center> 7700 7701**********************************************************************/ 7702/** 7703\page changes Change log 7704 7705<center> 7706Back to \ref highprec. Up to \ref contents. 7707</center> 7708 7709List of versions in reverse chronological order together with a brief 7710list of changes. (Note: Old versions of the library use a year-month 7711style of numbering. Now, the library uses a major and minor version 7712number.) Recent versions of GeographicLib are available at 7713<a href="https://sourceforge.net/projects/geographiclib/files/distrib/"> 7714https://sourceforge.net/projects/geographiclib/files/distrib/</a>. 7715Older versions are in 7716<a href="https://sourceforge.net/projects/geographiclib/files/distrib/archive/"> 7717https://sourceforge.net/projects/geographiclib/files/distrib/archive/</a>. 7718 7719The corresponding documentation for these versions is obtained by 7720clicking on the “Version <i>m.nn</i>” links below. Some of 7721the links in the documentation of older versions may be out of date (in 7722particular the links for the source code will not work if the code has 7723been migrated to the archive subdirectory). All the releases are 7724available as tags “r<i>m.nn</i>” in the the "release" branch 7725of the 7726<a href="https://sourceforge.net/p/geographiclib/code/ci/release/tree/"> 7727git repository for GeographicLib</a>. 7728 7729\if SKIP 7730 - TODO: Planned updates 7731 - Change templating in PolygonArea so that the AddPoint and AddEdge 7732 methods are templated instead of the class itself. This would 7733 allow a polygon to contain a mixture of geodesic and rhumb-line 7734 edges. 7735 - Generalize Geoid, UTMUPS, MGRS, GeoCoords to handle non-WGS84 7736 ellipsoids. 7737 - Add GreatEllipse class. 7738 - Implement Geodesic + TM + PolarStereographic on Jets. 7739 - Template versions of Gnomonic and AzimuthalEquidistant so that they 7740 can use either Geodesic and GeodesicExact. Use typedefs so that 7741 Geodesic::Line points to GeodesicLine. 7742 - Split DMS stuff from main JavaScript package. 7743 - Add C++ tests not dependent on utility programs. 7744 - Add information on radius of convergence for aux latitude series. 7745 - Check Geocentric::Reverse for accuracy for extreme ellipsoids, \e e 7746 > 1/sqrt(2). 7747 - Check Visual Studo "code analysis" results (from Analize VS 7748 menu). Probably an awful lot of false positives. 7749 - Fix cmake files so that they play nice with vcpkg: 7750 - Allow only some components to be built. 7751 - Allow tools, cmake install directories, etc., to be set. 7752 - Compute relative paths from bin to lib directories. 7753 - Install dll in tools directory. 7754 - Use BUILD_SHARED_LIBS instead of GEOGRAPHICLIB_LIB_TYPE. 7755 - Maybe segregate more tasks into a MAINTAINER mode. 7756 - Add Math routine for Clenshaw summation; may AuxiliaryLatitude 7757 class for conversions via the series? 7758\endif 7759 7760 - <a href="https://geographiclib.sourceforge.io/1.52">Version 1.52</a> 7761 (released 2021-06-22) 7762 - Add MagneticModel::FieldGeocentric and 7763 MagneticCircle::FieldGeocentric to return the field in geocentric 7764 coordinates (thanks to Marcelo Banik de Padua). 7765 - Document realistic errors for PolygonAreaT and 7766 <a href="Planimeter.1.html">Planimeter</a>. 7767 - Geodesic routines: be more aggressive in preventing negative \e s12 7768 and \e m12 for short lines (all languages). 7769 - Fix bug in AlbersEqualArea for extreme prolate ellipsoids (plus 7770 general cleanup in the code). 7771 - Thanks to Thomas Warner, a sample of wrapping the C++ library, so 7772 it's accessible in Excel, is given in <code>wrapper/Excel</code>. 7773 - Minor changes 7774 - Work around inaccuracies in hypot routines in Visual Studio 7775 (win32), Python, and JavaScript. 7776 - Initialize reference argument to remquo (C++ and C). 7777 - Get ready to retire unused _exact in RhumbLine. 7778 - Declare RhumbLine copy constructor "= default". 7779 - Use C++11 "= delete" idiom to delete copy assignment and copy 7780 constructors in RhumbLine, Geoid, GravityModel, MagneticModel. 7781 - Fix MGRS::Forward to work around aggressive optimization leading to 7782 incorrect rounding. 7783 - Fix plain makefiles, Makefile.mk, so that PREFIX is handled 7784 properly. 7785 - Make cmake's GeographicLib_LIBRARIES point to namespace versions. 7786 - <b>NOTE:</b> In the next version (tentatively 2.0), I plan to split 7787 up the git repository and the packaging of GeographicLib into 7788 separate entities for each language. This will simplify 7789 development and deployment of the library. 7790 - <b>WARNING:</b> The .NET version of GeographicLib will not be 7791 supported in the next version. 7792 . 7793 - <a href="https://geographiclib.sourceforge.io/1.51">Version 1.51</a> 7794 (released 2020-11-22) 7795 - C++11 compiler required for C++ library. As a consequence: 7796 - The workaround implementations for C++11 routines (Math::hypot, 7797 Math::expm1, Math::log1p, Math::asinh, Math::atanh, 7798 Math::copysign, Math::cbrt, Math::remainder, Math::remquo, 7799 Math::round, Math::lround, Math::fma, Math::isfinite, and 7800 Math::isnan) are now deprecated. Just use the versions in the 7801 std:: namespace instead. 7802 - SphericalEngine class, fix the namespace for using streamoff. 7803 - Some templated functions, e.g., Math::degree(), now have default 7804 template parameters, T = Math::real. 7805 - C99 compiler required for C library. 7806 - Reduce memory footprint in Java implementation. 7807 - New form of Utility::ParseLine to allow the syntax "KEY = VAL". 7808 - Add International Geomagnetic Reference Field (13th generation), 7809 igrf13, which approximates the main magnetic field of the earth for 7810 the period 1900--2025. 7811 - More symbols allowed with DMS decoding in C++, JS, and cgi-bin 7812 packages; see DMS::Decode. 7813 - Fix bug in cgi-bin argument processing which causes "+" to be 7814 misinterpreted. 7815 - Required minium version of CMake is now 3.7.0 (released 7816 2016-11-11). This is to work around a bug in find_package for 7817 cmake 3.4 and 3.5. 7818 . 7819 - <a href="https://geographiclib.sourceforge.io/1.50.1">Version 1.50.1</a> 7820 (released 2019-12-13) 7821 - Add the World Magnetic Model 2020, wmm2020, covering the period 7822 2020--2025. This is now the model returned by 7823 MagneticModel::DefaultMagneticName and is default magnetic model 7824 for <a href="MagneticField.1.html">MagneticField</a> (replacing 7825 wmm2015v2 which is only valid thru the end of 2019). 7826 - Include float instantiations of those templated Math functions 7827 which migrated to Math.cpp in version 1.50. 7828 - <b>WARNING:</b> The <i>next</i> version of GeographicLib will 7829 require a C++11 compliant compiler. This means that the minimum 7830 version of Visual Studio will be Visual Studio 14 2015. (This 7831 repeats the warning given with version 1.50. It didn't apply to 7832 this version because this is a minor update.) 7833 . 7834 - <a href="https://geographiclib.sourceforge.io/1.50">Version 1.50</a> 7835 (released 2019-09-24) 7836 - BUG fixes: 7837 - Java + JavaScript implementations of PolygonArea::TestEdge counted 7838 the pole encirclings wrong. 7839 - Fix typo in JavaScript implementation which affected unsigned 7840 areas. 7841 - Adding edges to a polygon counted pole encirclings inconsistent 7842 with the way the adding point counted them. This might have 7843 caused an incorrect result if a polygon vertex had longitude = 0. 7844 This affected all implementations except Fortran and MATLAB). 7845 - GARS::Forward: fix BUG in handling of longitude = ±180°. 7846 - Fix bug in Rhumb class and 7847 <a href="RhumbSolve.1.html">RhumbSolve(1)</a> utiity which caused 7848 incorrect area to be reported if an endpoint is at a pole. 7849 Thanks to Natalia Sabourova for reporting this. 7850 - Fix bug in MATLAB routine mgrs_inv which resulted in incorrect 7851 results for UPS zones with prec = −1. 7852 - In geodreckon.m geoddistance.m, suppress (innocuous) "warning: 7853 division by zero" messages from Octave. 7854 - In python implementation, work around problems caused by sin(inf) 7855 and fmod(inf) raising exceptions. 7856 - Geoid class, fix the use of streamoff. 7857 - The PolygonArea class, the 7858 <a href="Planimeter.1.html">Planimeter</a> utility, and their 7859 equivalents in C, Fortran, MATLAB, Java, JavaScript, Python, and 7860 Maxima can now handle arbitrarily complex polygons. In the case of 7861 self-intersecting polygons the area is accumulated "algebraically", 7862 e.g., the areas of the 2 loops in a figure-8 polygon will partially 7863 cancel. 7864 - Changes in gravity and magnetic model handling 7865 - SphericalEngine::coeff::readcoeffs takes new optional argument 7866 \e truncate. 7867 - The constructors for GravityModel and MagneticModel allow the 7868 maximum degree and order to be specified. The array of 7869 coefficients will then be truncated if necessary. 7870 - GravityModel::Degree(), GravityModel::Order(), 7871 MagneticModel::Degree(), MagneticModel::Order() return the 7872 maximum degree and order of all the components of a GravityModel 7873 or MagneticModel. 7874 - <a href="Gravity.1.html">Gravity</a> and 7875 <a href="MagneticField.1.html">MagneticField</a> utilities 7876 accept -N and -M options to to allow the maximum degree and order 7877 to be specified. 7878 - The <a href="GeodSolve.1.html">GeodSolve</a> allows fractional 7879 distances to be entered as fractions (with the <code>-F</code> 7880 flag). 7881 - MajorRadius() methods are now called EquatorialRadius() for the 7882 C++, Java, and .NET libraries. "Equatorial" is more descriptive in 7883 the case of prolate ellipsoids. MajorRadius() is retained for 7884 backward compatibility for C++ and Java but is deprecated. 7885 - Minimum version updates: 7886 - CMake = 3.1.0, released 2014-12-15. 7887 - Minimum g++ version = 4.8.0, released 2013-03-22. 7888 - Visual Studio 10 2010 (haven't been able to check Visual Studio 7889 2008 for a long time). 7890 - <b>WARNING:</b> The <i>next</i> version of GeographicLib will 7891 require a C++11 compliant compiler. This means that the minimum 7892 version of Visual Studio will be Visual Studio 14 2015. 7893 - Minimum boost version = 1.64 needed for GEOGRAPHICLIB_PRECISION = 7894 4. 7895 - Java = 1.6; this allows the removal of epsilon, min, hypot, 7896 log1p, copysign, cbrt from GeoMath. 7897 - CMake updates: 7898 - Fine tune Visual Studio compatibility check in 7899 find_package(GeographicLib); this allows GeographicLib compiled 7900 with Visual Studio 14 2015 to be used with a project compiled 7901 with Visual Studio 15 2017 and 16 2019. 7902 - Suppress warnings with dotnet build. 7903 - Change CMake target names and add an interface library (thanks to 7904 Matthew Woehlke). 7905 - Remove pre-3.1.0 cruft and update the documentation to remove the 7906 need to call include_dirctories. 7907 - Add _d suffix to example and test programs. 7908 - Changer installation path for binary installer to the Windows 7909 default. 7910 - Add support for Intel compiler (for C++, C, Fortran). This 7911 entails supplying the <code>-fp-model precise</code> flag to 7912 prevent the compiler from incorrectly simplying <code>(a + b) + 7913 c</code> and <code>0.0 + x</code>. 7914 - Add version 2 of the World Magnetic Model 2015, wmm2015v2. This 7915 is now the default magnetic model for 7916 <a href="MagneticField.1.html">MagneticField</a> (replacing wmm2015 7917 which is now deprecated). Coming in 2019-12: the wmm2020 model. 7918 - The -f flag in the scripts geographiclib-get-geoids, 7919 geographiclib-get-gravity, and geographiclib-get-magnetic, allows 7920 you to load new models (not yet in the set defined by "all"). This 7921 is in addition to its original role of allowing you to overwrite 7922 existing models. 7923 - Changes in math function support: 7924 - Move some of the functionality from Math.hpp to Math.cpp to make 7925 compilation of package which depend on GeographicLib less 7926 sensitive to the current compiler environment. 7927 - Add Math::remainder, Math::remquo, Math::round, and Math::lround. 7928 Also add implementations of remainder, remquo to C 7929 implementation. 7930 - Math::cbrt, Math::atanh, and Math::asinh now preserve the sign of 7931 −0. (Also: C, Java, JavaScript, Python, MATLAB. Not 7932 necessary: Fortran because sign is a built-in function.) 7933 - JavaScript: fall back to Math.hypot, Math.cbrt, Math.log1p, 7934 Math.atanh if they are available. 7935 - When parsing DMS strings ignore various non-breaking spaces (C++ 7936 and JavaScript). 7937 - Improve code coverage in the tests of geodesic algorithms (C++, C, 7938 Java, JavaScript, Python, MATLAB, Fortran). 7939 - Old deprecated NormalGravity::NormalGravity constructor removed. 7940 - Additions to the documentation: 7941 - add documentation links to ge{distance,reckon}.m; 7942 - clarify which solution is returned for Geocentric::Reverse. 7943 . 7944 - <a href="https://geographiclib.sourceforge.io/1.49">Version 1.49</a> 7945 (released 2017-10-05) 7946 - Add the Enhanced Magnetic Model 2017, emm2017. This is valid for 7947 2000 thru the end of 2021. 7948 - Avoid potential problems with the order of initializations in DMS, 7949 GARS, Geohash, Georef, MGRS, OSGB, SphericalEngine; this only would 7950 have been an issue if GeographicLib objects were instantiated 7951 globally. Now no GeographicLib initialization code should be run 7952 prior to the entry of main(). 7953 - To support the previous fix, add an overload, 7954 Utility::lookup(const char* s, char c). 7955 - NearestNeighbor::Search throws an error if \e pts is the wrong size 7956 (instead of merely returning no results). 7957 - Use complex arithmetic for Clenshaw sums in TransverseMercator and 7958 tranmerc_{fwd,inv}.m. 7959 - Changes in cmake support: 7960 - fix compiler flags for GEOGRAPHICLIB_PRECISION = 4; 7961 - add CONVERT_WARNINGS_TO_ERRORS option (default OFF), if ON then 7962 compiler warnings are treated as errors. 7963 - Fix warnings about implicit conversions of doubles to bools in C++, 7964 C, and JavaScript packages. 7965 - Binary installers for Windows now use Visual Studio 14 2015. 7966 . 7967 - <a href="https://geographiclib.sourceforge.io/1.48">Version 1.48</a> 7968 (released 2017-04-09) 7969 - The "official" URL for GeographicLib is now 7970 https://geographiclib.sourceforge.io (instead of 7971 http://geographiclib.sourceforge.net). 7972 - The default range for longitude and azimuth is now 7973 (−180°, 180°], instead of [−180°, 7974 180°). This was already the case for the C++ library; now the 7975 change has been made to the other implementations (C, Fortran, 7976 Java, JavaScript, Python, MATLAB, and Maxima). 7977 - Changes to NearestNeighbor: 7978 - fix BUG in reading a NearestNeighbor object from a stream which 7979 sometimes incorrectly caused a "Bad index" exception to be 7980 thrown; 7981 - add NearestNeighbor::operator<<, NearestNeighbor::operator>>, 7982 NearestNeighbor::swap, std::swap(GeographicLib::NearestNeighbor&, 7983 GeographicLib::NearestNeighbor&); 7984 - Additions to the documentation: 7985 - add documentation on \ref nearest; 7986 - \ref normalgravity documentation is now on its own page and now 7987 has an illustrative figure; 7988 - document the \ref auxlaterror in the series for auxiliary 7989 latitudes. 7990 - Fix BUGS in MATLAB function geodreckon with mixed scalar and array 7991 arguments. 7992 - Workaround bug in math.fmod for Python 2.7 on 32-bit Windows 7993 machines. 7994 - Changes in cmake support: 7995 - add USE_BOOST_FOR_EXAMPLES option (default OFF), if ON search for 7996 Boost libraries for building examples; 7997 - add APPLE_MULTIPLE_ARCHITECTURES option (default OFF), if ON 7998 build for both i386 and x86_64 on Mac OS X systems; 7999 - don't add flag for C++11 for g++ 6.0 (since it's not needed). 8000 - Fix compiler warnings with Visual Studio 2017 and for the C 8001 library. 8002 . 8003 - <a href="https://geographiclib.sourceforge.io/1.47">Version 1.47</a> 8004 (released 2017-02-15) 8005 - Add NearestNeighbor class. 8006 - Improve accuracy of area calculation (fixing a flaw introduced in 8007 version 1.46); fix applied in Geodesic, GeodesicExact, and the 8008 implementations in C, Fortran, Java, JavaScript, Python, MATLAB, 8009 and Maxima. 8010 - Generalize NormalGravity to allow oblate and prolate ellipsoids. 8011 As a consequence a new form of constructor, 8012 NormalGravity::NormalGravity, has been introduced and the old 8013 form is now <b>deprecated</b> (and because the signatures of the two 8014 constructors are similar, the compiler will warn about the use of 8015 the old one). 8016 - Changes in Math class: 8017 - Math::sincosd, Math::sind, Math::cosd only return −0 for 8018 the case sin(−0); 8019 - Math::atan2d and Math::AngNormalize return results in 8020 (−180°, 180°]; this may affect the longitudes and 8021 azimuth returned by several other functions. 8022 - Add Utility::trim() and Utility::val<T>(); Utility::num<T>() is now 8023 <b>deprecated</b>. 8024 - Changes in cmake support: 8025 - remove support of PACKAGE_PATH and INSTALL_PATH in cmake 8026 configuration; 8027 - fix to FindGeographicLib.cmake to make it work on Debian systems; 8028 - use $<TARGET_PDB_FILE:tgt> (cmake version ≥ 3.1); 8029 - use NAMESPACE for exported targets; 8030 - geographiclib-config.cmake exports GEOGRAPHICLIB_DATA, 8031 GEOGRAPHICLIB_PRECISION, and GeographicLib_HIGHPREC_LIBRARIES. 8032 - Add pkg-config support for cmake and autoconf builds. 8033 - Minor fixes: 8034 - fix the order of declarations in C library, incorporating the 8035 patches in version 1.46.1; 8036 - fix the packaging of the Python library, incorporating the 8037 patches in version 1.46.3; 8038 - restrict junit dependency in the Java package to testing scope 8039 (thanks to Mick Killianey); 8040 - various behind-the-scenes fixes to EllipticFunction; 8041 - fix documentation and default install location for Windows binary 8042 installers; 8043 - fix clang compiler warnings in GeodesicExactC4 and 8044 TransverseMercator. 8045 . 8046 - <a href="https://geographiclib.sourceforge.io/1.46">Version 1.46</a> 8047 (released 2016-02-15) 8048 - The following BUGS have been fixed: 8049 - the -w flag to <a href="Planimeter.1.html">Planimeter(1)</a> was 8050 being ignored; 8051 - in the Java package, the wrong longitude was being returned with 8052 direct geodesic calculation with a negative distance when 8053 starting point was at a pole (this bug was introduced in version 8054 1.44); 8055 - in the JavaScript package, PolygonArea.TestEdge contained a 8056 misspelling of a variable name and other typos (problem found by 8057 threepointone). 8058 - INCOMPATIBLE CHANGES: 8059 - make the -w flag (to swap the default order of latitude and 8060 longitude) a toggle for all \ref utilities; 8061 - the -a option to <a href="GeodSolve.1.html">GeodSolve(1)</a> now 8062 toggles (instead of sets) arc mode; 8063 - swap order \e coslon and \e sinlon arguments in CircularEngine 8064 class. 8065 - Remove deprecated functionality: 8066 - remove gradient calculation from the Geoid class and 8067 <a href="GeoidEval.1.html">GeoidEval(1)</a> (this was inaccurate 8068 and of dubious utility); 8069 - remove reciprocal flattening functions, InverseFlattening in many 8070 classes and Constants::WGS84_r(); stop treating flattening > 1 8071 as the reciprocal flattening in constructors; 8072 - remove DMS::Decode(string), DMS::DecodeFraction, 8073 EllipticFunction:m, EllipticFunction:m1, Math::extradigits, 8074 Math::AngNormalize2, PolygonArea::TestCompute; 8075 - stop treating LONG_NOWRAP as an alias for LONG_UNROLL in 8076 Geodesic (and related classes) and Rhumb; 8077 - stop treating full/schmidt as aliases for FULL/SCHMIDT in 8078 SphericalEngine (and related classes); 8079 - remove qmake project file src/GeographicLib.pro because QtCreator 8080 can handle cmake projects now; 8081 - remove deprecated Visual Studio 2005 project and solution files. 8082 - Changes to GeodesicLine and GeodesicLineExact classes; these 8083 changes (1) simplify the process of computing waypoints on a 8084 geodesic given two endpoints and (2) allow a GeodesicLine to be 8085 defined which is consistent with the solution of the inverse 8086 problem (in particular Geodesic::InverseLine the specification of 8087 south-going lines which pass the poles in a westerly direction by 8088 setting sin α<sub>1</sub> = −0): 8089 - the class stores the distance \e s13 and arc length \e a13 to a 8090 reference point 3; by default these quantities are NaNs; 8091 - GeodesicLine::SetDistance (and GeodesicLine::SetArc) specify the 8092 distance (and arc length) to point 3; 8093 - GeodesicLine::Distance (and GeodesicLine::Arc) return the 8094 distance (and arc length) to point 3; 8095 - new methods Geodesic::InverseLine and Geodesic::DirectLine return 8096 a GeodesicLine with the reference point 3 defined as point 2 of 8097 the corresponding geodesic calculation; 8098 - these changes are also included in the C, Java, JavaScript, and 8099 Python packages. 8100 - Other changes to the geodesic routines: 8101 - more accurate solution of the inverse problem when longitude 8102 difference is close to 180° (also in C, Fortran, Java, 8103 JavaScript, Python, MATLAB, and Maxima packages); 8104 - more accurate calculation of lon2 in the inverse calculation with 8105 LONG_UNROLL (also in Java, JavaScript, Python packages). 8106 - Changes to <a href="GeodSolve.1.html">GeodSolve(1)</a> utility: 8107 - the -I and -D options now specify geodesic line calculation via 8108 the standard inverse or direct geodesic problems; 8109 - rename -l flag to -L to parallel the new -I and -D flags (-l is 8110 is retained for backward compatibility but is <b>deprecated</b>), 8111 and similarly for <a href="GeodSolve.1.html">RhumbSolve(1)</a>; 8112 - the -F flag (in conjunction with the -I or -D flags) specifies that 8113 distances read on standard input are fractions of \e s13 or \e 8114 a13; 8115 - the -a option now toggles arc mode (noted above); 8116 - the -w option now toggles longitude first mode (noted above). 8117 - Changes to Math class: 8118 - Math::copysign added; 8119 - add overloaded version of Math::AngDiff which returns the error 8120 in the difference. This allows a more accurate treatment of 8121 inverse geodesic problem when \e lon12 is close to 180°; 8122 - Math::AngRound now converts tiny negative numbers to −0 8123 (instead of +0), however −0 is still converted to +0. 8124 - Add -S and -T options to 8125 <a href="GeoConvert.1.html">GeoConvert(1)</a>. 8126 - Add <a href="https://www.sphinx-doc.org/en/master/">Sphinx</a> 8127 documentation for Python package. 8128 - Samples of wrapping the C++ library, so it's accessible in other 8129 languages, are given in <code>wrapper/C</code>, 8130 <code>wrapper/python</code>, and <code>wrapper/matlab</code>. 8131 - Binary installers for Windows now use Visual Studio 12 2013. 8132 - Remove top-level pom.xml from release (it was specific to SRI). 8133 - A reminder: because of the JavaScript changes introduced in version 8134 1.45, you should remove the following installation directories from 8135 your system: 8136 - Windows: ${CMAKE_INSTALL_PREFIX}/doc/scripts 8137 - Others: ${CMAKE_INSTALL_PREFIX}/share/doc/GeographicLib/scripts 8138 . 8139 - <a href="https://geographiclib.sourceforge.io/1.45">Version 1.45</a> 8140 (released 2015-09-30) 8141 - Fix BUG in solution of inverse geodesic caused by misbehavior of 8142 some versions of Visual Studio on Windows (fmod(−0.0, 360.0) 8143 returns +0.0 instead of −0.0) and Octave (sind(−0.0) 8144 returns +0.0 instead of −0.0). These bugs were exposed 8145 because max(−0.0, +0.0) returns −0.0 for some 8146 languages. 8147 - Geodesic::Inverse now correctly returns NaNs if one of the 8148 latitudes is a NaN. 8149 - Changes to JavaScript package: 8150 - thanks to help from Yurij Mikhalevich, it is a now a 8151 <a href="https://nodejs.org">node</a> package that can be 8152 installed with <a href="https://www.npmjs.com">npm</a>; 8153 - make install now installs the node package in 8154 <code>lib/node_modules/geographiclib</code>; 8155 - add unit tests using mocha; 8156 - add documentation via <a href="http://usejsdoc.org">JSDoc</a>; 8157 - fix bug Geodesic.GenInverse (this bug, introduced in version 8158 1.44, resulted in the wrong azimuth being reported for points at 8159 the pole). 8160 - Changes to Java package: 8161 - add implementation of ellipsoidal Gnomonic projection (courtesy 8162 of Sebastian Mattheis); 8163 - add unit tests using JUnit; 8164 - Math.toRadians and Math.toDegrees are used instead of 8165 GeoMath.degree (which is now removed), as a result… 8166 - Java version 1.2 (released 1998-12) or later is now required. 8167 - Changes to Python package: 8168 - add unit tests using the unittest framework; 8169 - fixed bug in normalization of the area. 8170 - Changes to MATLAB package: 8171 - fix array size mismatch in geoddistance by avoiding calls to 8172 subfunctions with zero-length arrays; 8173 - fix tranmerc_{fwd,inv} so that they work with arrays and 8174 mixed array/scalar arguments; 8175 - work around Octave problem which causes mgrs_fwd to return 8176 garbage with prec = 10 or 11; 8177 - add geographiclib_test.m to run a test suite. 8178 - Behavior of substituting 1/\e f for \e f if \e f > 1 is now 8179 <b>deprecated</b>. This behavior has been removed from the 8180 JavaScript, C, and Python implementations (it was never 8181 documented). Maxima, MATLAB, and Fortran implementations never 8182 included this behavior. 8183 - Other changes: 8184 - fix bug, introduced in version 1.42, in the C++ implementation to 8185 the computation of area which causes NaNs to be returned in the 8186 case of a sphere; 8187 - fixed bug, introduced in version 1.44, in the detection of C++11 8188 math functions in configure.ac; 8189 - throw error on non-convergence in Gnomonic::Reverse if 8190 GEOGRAPHICLIB_PRECISION > 3; 8191 - add geod_polygon_clear to C library; 8192 - turn illegal latitudes into NaNs for Fortran library; 8193 - add test suites for the C and Fortran libraries. 8194 . 8195 - <a href="https://geographiclib.sourceforge.io/1.44">Version 1.44</a> 8196 (released 2015-08-14) 8197 - Various changes to improve accuracy, e.g., by minimizing round-off 8198 errors: 8199 - Add Math::sincosd, Math::sind, Math::cosd which take their 8200 arguments in degrees. These functions do exact range reduction 8201 and thus they obey exactly the elementary properties of the 8202 trigonometric functions, e.g., sin 9° = cos 81° = − 8203 sin 123456789°. 8204 - Math::AngNormalize now works for any angles, instead of angles in 8205 the range [−540°, 540°); the function 8206 Math::AngNormalize2 is now <b>deprecated</b>. 8207 - This means that there is now no restriction on longitudes and 8208 azimuths; any values can be used. 8209 - Improve the accuracy of Math::atan2d. 8210 - DMS::Decode avoids unnecessary round-off errors; thus 7:33:36 and 8211 7.56 result in identical values. DMS::Encode rounds ties to 8212 even. These changes have also been made to DMS.js. 8213 - More accurate rounding in MGRS::Reverse and mgrs_inv.m; this 8214 change only makes a difference at sub-meter precisions. 8215 - With MGRS::Forward and mgrs_fwd.m, ensure that digits in lower 8216 precision results match those at higher precision; as a result, 8217 strings of trailing 9s are less likely to be generated. This 8218 change only makes a difference at sub-meter precisions. 8219 - Replace the series for <i>A</i><sub>2</sub> in the Geodesic class 8220 with one with smaller truncation errors. 8221 - Geodesic::Inverse sets \e s12 to zero for coincident points at 8222 pole (instead of returning a tiny quantity). 8223 - Math::LatFix returns its argument if it is in [−90°, 8224 90°]; if not, it returns NaN. 8225 - Using Math::LatFix, routines which don't check their arguments 8226 now interpret a latitude outside the legal range of 8227 [−90°, 90°] as a NaN; such routines will return 8228 NaNs instead of finite but incorrect results; <b>caution</b>: 8229 code that (dangerously) relied on the "reasonable" results being 8230 returned for values of the latitude outside the allowed range 8231 will now malfunction. 8232 - All the \ref utilities accept the -w option to swap the 8233 latitude-longitude order on input and output (and where appropriate 8234 on the command-line arguments). CartConvert now accepts the -p 8235 option to set the precision; now all of the utilities except 8236 GeoidEval accept -p. 8237 - Add classes for GARS, the Global Area Reference System, and for 8238 Georef, the World Geographic Reference System. 8239 - Changes to DMS::Decode and DMS.js: 8240 - tighten up the rules: 8241 - 30:70.0 and 30:60 are illegal (minutes and second must be 8242 strictly less than 60), however 8243 - 30:60.0 and 30:60. are legal (floating point 60 is OK, since it 8244 might have been generated by rounding 59.99…); 8245 - generalize a+b concept, introduced in version 1.42, to any number 8246 of pieces; thus 8+0:40-0:0:10 is interpreted as 8:39:50. 8247 - Documentation fixes: 8248 - update man pages to refer to 8249 <a href="GeoConvert.1.html">GeoConvert(1)</a> on handling of 8250 geographic coordinates; 8251 - document limitations of the series used for TransverseMercator; 8252 - hide the documentation of the computation of the gradient of the 8253 geoid height (now <b>deprecated</b>) in the Geoid class; 8254 - warn about the possible misinterpretation of 7.0E+1 by 8255 DMS::Decode; 8256 - \e swaplatlong optional argument of DMS::DecodeLatLon and 8257 various functions in the GeoCoords class is now called \e 8258 longfirst; 8259 - require Doxygen 1.8.7 or later. 8260 - More systematic treatment of version numbers: 8261 - Python: \__init\__.py defines \__version\__ and \__version_info\__; 8262 - JavaScript: 8263 - Math.js defines Constants.version and Constants.version_string; 8264 - version number included as comment in packed script 8265 geographiclib.js; 8266 - <a href="../scripts/geod-calc.html">geod-calc.html</a> and 8267 <a href="../scripts/geod-google.html">geod-google.html</a> 8268 report the version number; 8269 - https://geographiclib.sourceforge.io/scripts/ gives access to 8270 earlier versions of geographiclib.js as 8271 geographiclib-<i>m.nn</i>.js; 8272 - Fortran: add geover subroutine to return version numbers; 8273 - Maxima: geodesic.mac defines geod_version; 8274 - CGI scripts: these report the version numbers of the utilities. 8275 - BUG FIXES: 8276 - NormalGravity now works properly for a sphere (\e omega = \e f = 8277 \e J2 = 0), instead of returning NaNs (problem found by htallon); 8278 - CassiniSoldner::Forward and cassini_fwd.m now returns the correct 8279 azimuth for points at the pole. 8280 - MATLAB-specific fixes: 8281 - mgrs_fwd now treats treats prec > 11 as prec = 11; 8282 - illegal letter combinations are now correctly detected by 8283 mgrs_inv; 8284 - fixed bug where mgrs_inv returned the wrong results for prec = 0 8285 strings and center = 0; 8286 - mgrs_inv now decodes prec = 11 strings properly; 8287 - routines now return array results with the right shape; 8288 - routines now properly handle mixed scalar and array arguments. 8289 - Add Accumulator<T>::operator*=(T y). 8290 - Geohash uses "invalid" instead of "nan" when the latitude or 8291 longitude is a nan. 8292 . 8293 - <a href="https://geographiclib.sourceforge.io/1.43">Version 1.43</a> 8294 (released 2015-05-23) 8295 - Add the Enhanced Magnetic Model 2015, emm2015. This is valid for 8296 2000 thru the end of 2019. This required some changes in the 8297 MagneticModel and MagneticCircle classes; so this model cannot be 8298 used with versions of GeographicLib prior to 1.43. 8299 - Fix BLUNDER in PolarStereographic constructor introduced in version 8300 1.42. This affected UTMUPS conversions for UPS which could be 8301 incorrect by up to 0.5 km. 8302 - Changes in the LONG_NOWRAP option (added in version 1.39) in the 8303 Geodesic and GeodesicLine classes: 8304 - The option is now called LONG_UNROLL (a less negative sounding 8305 term); the original name, LONG_NOWRAP, is retained for backwards 8306 compatibility. 8307 - There were two bad BUGS in the implementation of this capability: 8308 (a) it gave <i>incorrect</i> results for west-going 8309 geodesics; (b) the option was <i>ignored</i> if used 8310 directly via the GeodesicLine class. The first bug affected the 8311 implementations in all languages. The second affected the 8312 implementation in C++ (GeodesicLine and GeodesicLineExact), 8313 JavaScript, Java, C, Python. These bugs have now been FIXED. 8314 - The <a href="GeodSolve.1.html">GeodSolve</a> utility now accepts 8315 a -u option, which turns on the LONG_UNROLL treatment. With this 8316 option <code>lon1</code> is reported as entered and 8317 <code>lon2</code> is given such that <code>lon2</code> − 8318 <code>lon1</code> indicates how often and in what sense the 8319 geodesic has encircled the earth. (This option also affects the 8320 value of longitude reported when an inverse calculation is run 8321 with the -f option.) 8322 - The inverse calculation with the JavaScript and Python libraries 8323 similarly sets <code>lon1</code> and <code>lon2</code> in output 8324 dictionary respecting the LONG_UNROLL flag. 8325 - The online version of 8326 <a href="https://geographiclib.sourceforge.io/cgi-bin/GeodSolve">GeodSolve</a> 8327 now offers an option to unroll the longitude. 8328 - To support these changes DMS::DecodeLatLon no longer reduces the 8329 longitude to the range [−180°, 180°) and 8330 Math::AngRound now coverts −0 to +0. 8331 - Add Math::polyval (also to C, Java, JavaScript, Fortran, Python 8332 versions of the library; this is a built-in function for 8333 MATLAB/Octave). This evaluates a polynomial using Horner's method. 8334 The Maxima-generated code fragments for the evaluation of series in 8335 the Geodesic, TransverseMercator, and Rhumb classes and MATLAB 8336 routines for great ellipses have been replaced by Maxima-generated 8337 arrays of polynomial coefficients which are used as input to 8338 Math::polyval. 8339 - Add MGRS::Check() to verify that \e a, \e f, 8340 <i>k</i><sub>UTM</sub>, and <i>k</i><sub>UPS</sub> are consistent 8341 with the assumptions in the UTMUPS and MGRS classes. This is 8342 invoked with <code>GeoConvert \--version</code>. (This function 8343 was added to document and check the assumptions used in the UTMUPS 8344 and MGRS classes in case they are extended to deal with ellipsoids 8345 other than WS84.) 8346 - MATLAB function mgrs_inv now takes an optional \e center argument 8347 and strips white space from both beginning and end of the string. 8348 - Minor internal changes: 8349 - GeodSolve sets the geodesic mask so that unnecessary calculations 8350 are avoided; 8351 - some routines have migrated into a math class for the Python, 8352 Java, and JavaScript libraries. 8353 - A reminder: because of changes in the installation directories for 8354 non-Windows systems introduced in version 1.42, you should remove 8355 the following directories from your system: 8356 - ${CMAKE_INSTALL_PREFIX}/share/cmake/GeographicLib* 8357 - ${CMAKE_INSTALL_PREFIX}/libexec/GeographicLib/matlab 8358 . 8359 - <a href="https://geographiclib.sourceforge.io/1.42">Version 1.42</a> 8360 (released 2015-04-28) 8361 - DMS::Decode allows a single addition or subtraction operation, 8362 e.g., 70W+0:0:15. This affects the GeoCoords class and the 8363 utilities (which use the DMS class for reading coordinates). 8364 - Add Math::norm, Math::AngRound, Math::tand, Math::atan2d, 8365 Math::eatanhe, Math::taupf, Math::tauf, Math::fma and remove 8366 duplicated (but private) functionality from other classes. 8367 - On non-Windows systems, the cmake config-style find_package files 8368 are now installed under ${CMAKE_INSTALL_PREFIX}/lib${LIB_SUFFIX} 8369 instead of ${CMAKE_INSTALL_PREFIX}/share, because the files are 8370 architecture-specific. This change will let 32-bit and 64-bit 8371 versions coexist on the same machine (in lib and lib64). You 8372 should remove the versions in the old "share" location. 8373 - MATLAB changes: 8374 - provide native MATLAB implementations for compiled interface 8375 functions, see \ref matlab; 8376 - the compiled MATLAB interface is now <b>deprecated</b> and so the 8377 MATLAB_COMPILER option in the cmake build has been removed; 8378 - reorganize directories, so that 8379 - matlab/geographiclib contains the native matlab code; 8380 - matlab/geographiclib-legacy contains wrapper functions to mimic 8381 the previous compiled functionality; 8382 - the installed MATLAB code mirrors this layout, but the parent 8383 installation directory on non-Windows systems is 8384 ${CMAKE_INSTALL_PREFIX}/share (instead of 8385 ${CMAKE_INSTALL_PREFIX}/libexec), because the files are now 8386 architecture independent; 8387 - matlab/geographiclib is now packaged and distributed as 8388 MATLAB File Exchange package 8389 <a href="https://www.mathworks.com/matlabcentral/fileexchange/50605"> 8390 50605</a> (this supersedes three earlier MATLAB packages); 8391 - point fix for geodarea.m to correct bug in area of polygons which 8392 encircle a pole multiple times (released as version 1.41.1 of 8393 MATLAB File Exchange package 39108, 2014-04-22). 8394 - artifactId for Java package changed from GeographicLib to 8395 GeographicLib-Java and the package is now deployed to 8396 Maven Central (thanks to Chris Bennight for help on this). 8397 - Fix autoconf mismatch of version numbers (which were inconsistent 8398 in versions 1.40 and 1.41). 8399 - Mark the computation of the gradient of the geoid height in the 8400 Geoid class and the <a href="GeoidEval.1.html">GeoidEval</a> 8401 utility as <b>deprecated</b>. 8402 - Work around the boost-quadmath bug with setprecision(0). 8403 - Deprecate use of Visual Studio 2005 "-vc8" project files in the 8404 windows directory. 8405 . 8406 - <a href="https://geographiclib.sourceforge.io/1.41">Version 1.41</a> 8407 (released 2015-03-09) 8408 - Fix bug in Rhumb::Inverse (with \e exact = true) and related 8409 functions which causes the wrong distance to be reported if one of 8410 the end points is at a pole. Thanks to Thomas Murray for reporting 8411 this. 8412 - Add International Geomagnetic Reference Field (12th generation), 8413 igrf12, which approximates the main magnetic field of the earth for 8414 the period 1900--2020. 8415 - Split information about \ref jacobi to a separate section and 8416 include more material. 8417 . 8418 - <a href="https://geographiclib.sourceforge.io/1.40">Version 1.40</a> 8419 (released 2014-12-18) 8420 - Add the World Magnetic Model 2015, wmm2015. This is now the 8421 default magnetic model for 8422 <a href="MagneticField.1.html">MagneticField</a> (replacing wmm2010 8423 which is valid thru the end of 2014). 8424 - Geodesic::Inverse didn't return NaN if one of the longitudes was a 8425 NaN (bug introduced in version 1.25). Fixed in the C++, Java, 8426 JavaScript, C, Fortran, and Python implementations of the geodesic 8427 routines. This bug was not present in the MATLAB version. 8428 - Fix bug in Utility::readarray and Utility::writearray which caused 8429 an exception in debug mode with zero-sized arrays. 8430 - Fix BLUNDER in OSGB::GridReference (found by kalderami) where the 8431 wrong result was returned if the easting or northing was negative. 8432 - OSGB::GridReference now returns "INVALID" if either coordinate is 8433 NaN. Similarly a grid reference starting with "IN" results in NaNs 8434 for the coordinates. 8435 - Default constructor for GeoCoords corresponds to an undefined 8436 position (latitude and longitude = NaN), instead of the north pole. 8437 - Add an online version of <a href="RhumbSolve.1.html">RhumbSolve</a> 8438 at https://geographiclib.sourceforge.io/cgi-bin/RhumbSolve. 8439 - Additions to the documentation: 8440 - documentation on \ref triaxial-conformal; 8441 - a page on \ref auxlat (actually, this was added in version 1.39); 8442 - document the use of two single quotes to stand for a double quote 8443 in DMS (this feature was introduced in version 1.13). 8444 - The MATLAB function, geographiclibinterface, which compiles the 8445 wrapper routines for MATLAB now works with MATLAB on a Mac. 8446 . 8447 - <a href="https://geographiclib.sourceforge.io/1.39">Version 1.39</a> 8448 (released 2014-11-11) 8449 - GeographicLib usually normalizes longitudes to the range 8450 [−180°, 180°). However, when solving the direct 8451 geodesic and rhumb line problems, it is sometimes necessary to know 8452 how many lines the line encircled the earth by returning the 8453 longitude "unwrapped". So the following changes have been made: 8454 - add a LONG_NOWRAP flag to \e mask enums for the \e outmask 8455 arguments for Geodesic, GeodesicLine, Rhumb, and RhumbLine; 8456 - similar changes have been made to the Python, JavaScript, and 8457 Java implementations of the geodesic routines; 8458 - for the C, Fortran, and MATLAB implementations the \e arcmode 8459 argument to the routines was generalized to allow a combination 8460 of ARCMODE and LONG_NOWRAP bits; 8461 - the Maxima version now returns the longitude unwrapped. 8462 . 8463 These changes were necessary to fix the PolygonAreaT::AddEdge (see 8464 the next item). 8465 - Changes in area calculations: 8466 - fix BUG in PolygonAreaT::AddEdge (also in C, Java, JavaScript, 8467 and Python implementations) which sometimes causes the wrong area 8468 to be returned if the edge spanned more than 180°; 8469 - add area calculation to the Rhumb and RhumbLine classes and the 8470 <a href="RhumbSolve.1.html">RhumbSolve</a> utility (see \ref 8471 rhumbarea); 8472 - add PolygonAreaRhumb typedef for PolygonAreaT<Rhumb>; 8473 - add -R option to <a href="Planimeter.1.html">Planimeter</a> to use 8474 PolygonAreaRhumb (and -G option for the default geodesic polygon); 8475 - fix BLUNDER in area calculation in MATLAB routine geodreckon; 8476 - add area calculation to MATLAB/Octave routines for great ellipses 8477 (see \ref gearea). 8478 - Fix bad BUG in Geohash::Reverse; this was introduced in version 8479 1.37 and affected all platforms where unsigned longs are 32-bits. 8480 Thanks to Christian Csar for reporting and diagnosing this. 8481 - Binary installers for Windows are now built with Visual Studio 11 8482 2012 (instead of Visual Studio 10 2010). Compiled MATLAB support 8483 still with version 2013a (64-bit). 8484 - Update GeographicLib.pro for builds with qmake to include all the 8485 source files. 8486 - Cmake updates: 8487 - include cross-compiling checks in cmake config file; 8488 - improve the way unsuitable versions are reported; 8489 - include_directories (${GeographicLib_INCLUDE_DIRS}) is no longer 8490 necessary with cmake 2.8.11 or later. 8491 - legacy/Fortran now includes drop-in replacements for the geodesic 8492 utilities from the NGS. 8493 - geographiclib-get-{geoids,gravity,magnetic} with no arguments now 8494 print the usage instead of loading the minimal sets. 8495 - Utility::date(const std::string&, int&, int&, int&) and hence the 8496 <a href="MagneticField.1.html">MagneticField</a> utility accepts 8497 the string "now" as a legal time (meaning today). 8498 . 8499 - <a href="https://geographiclib.sourceforge.io/1.38">Version 1.38</a> 8500 (released 2014-10-02) 8501 - On MacOSX, the installed package is relocatable (for cmake version 8502 2.8.12 and later). 8503 - On Mac OSX, GeographicLib can be installed using homebrew. 8504 - In cmake builds under Windows, set the output directories so that 8505 binaries and shared libraries are together. 8506 - Accept the minus sign as a synonym for - in DMS.{cpp,js}. 8507 - The cmake configuration file geographiclib-depends.cmake has been 8508 renamed to geographiclib-targets.cmake. 8509 - MATLAB/Octave routines for great ellipses added; see \ref 8510 greatellipse. 8511 - Provide man pages for geographiclib-get-{geoids,gravity,magnetic}. 8512 . 8513 - <a href="https://geographiclib.sourceforge.io/1.37">Version 1.37</a> 8514 (released 2014-08-08) 8515 - Add \ref highprec. 8516 - <b>INCOMPATIBLE CHANGE</b>: the static instantiations of various 8517 classes for the WGS84 ellipsoid have been changed to a 8518 <a href="https://isocpp.org/wiki/faq/ctors#static-init-order-on-first-use"> 8519 "construct on first use idiom"</a>. This avoids a lot of wasteful 8520 initialization before the user's code starts. Unfortunately it 8521 means that existing source code that relies on any of the following 8522 static variables will need to be changed to a function call: 8523 - AlbersEqualArea::AzimuthalEqualAreaNorth 8524 - AlbersEqualArea::AzimuthalEqualAreaSouth 8525 - AlbersEqualArea::CylindricalEqualArea 8526 - Ellipsoid::WGS84 8527 - Geocentric::WGS84 8528 - Geodesic::WGS84 8529 - GeodesicExact::WGS84 8530 - LambertConformalConic::Mercator 8531 - NormalGravity::GRS80 8532 - NormalGravity::WGS84 8533 - PolarStereographic::UPS 8534 - TransverseMercator::UTM 8535 - TransverseMercatorExact::UTM 8536 . 8537 Thus, occurrences of, for example, \code 8538 const Geodesic& geod = Geodesic::WGS84; // version 1.36 and earlier 8539 \endcode 8540 need to be changed to \code 8541 const Geodesic& geod = Geodesic::WGS84(); // version 1.37 and later 8542 \endcode 8543 (note the parentheses!); alternatively use \code 8544 // works with all versions 8545 const Geodesic geod(Constants::WGS84_a(), Constants::WGS84_a()); \endcode 8546 - Incompatible change: the environment variables 8547 <code>{GEOID,GRAVITY,MAGNETIC}_{NAME,PATH}</code> are now prefixed 8548 with <code>GEOGRAPHICLIB_</code>. 8549 - Incompatible change for Windows XP: retire the Windows XP common 8550 data path. If you're still using Windows XP, then you might have 8551 to move the folder <code>C:\\Documents and Settings\\All 8552 Users\\Application Data\\GeographicLib</code> to 8553 <code>C:\\ProgramData\\GeographicLib</code>. 8554 - All macro names affecting the compilation now start with 8555 <code>GEOGRAPHICLIB_</code>; this applies to 8556 <code>GEOID_DEFAULT_NAME</code>, <code>GRAVITY_DEFAULT_NAME</code>, 8557 <code>MAGNETIC_DEFAULT_NAME</code>, <code>PGM_PIXEL_WIDTH</code>, 8558 <code>HAVE_LONG_DOUBLE</code>, <code>STATIC_ASSERT</code>, 8559 <code>WORDS_BIGENDIAN</code>. 8560 - Changes to PolygonArea: 8561 - introduce PolygonAreaT which takes a geodesic class as a parameter; 8562 - PolygonArea and PolygonAreaExact are typedef'ed to 8563 PolygonAreaT<Geodesic> and PolygonAreaT<GeodesicExact>; 8564 - add -E option to <a href="Planimeter.1.html">Planimeter</a> to use 8565 PolygonAreaExact; 8566 - add -Q option to <a href="Planimeter.1.html">Planimeter</a> to 8567 calculate the area on the authalic sphere. 8568 - Add -p option to <a href="Planimeter.1.html">Planimeter</a>, 8569 <a href="ConicProj.1.html">ConicProj</a>, 8570 <a href="GeodesicProj.1.html">GeodesicProj</a>, 8571 <a href="TransverseMercatorProj.1.html">TransverseMercatorProj</a>. 8572 - Add Rhumb and RhumbLine classes and the 8573 <a href="RhumbSolve.1.html">RhumbSolve</a> utility; see \ref rhumb 8574 for more information. 8575 - Minor changes to NormalGravity: 8576 - add NormalGravity::J2ToFlattening and NormalGravity::FlatteningToJ2; 8577 - use Newton's method to determine \e f from \e J2; 8578 - in constructor, allow \e omega = 0 (i.e., treat the spherical case). 8579 - Add grs80 GravityModel, see \ref gravity. 8580 - Make geographiclib-get-{geoids,gravity,magnetic} scripts work on MacOS. 8581 - Minor changes: 8582 - simplify cross-platform support for C++11 mathematical functions; 8583 - change way area coefficients are given in GeodesicExact to improve 8584 compile times; 8585 - enable searching the online documentation; 8586 - add macros <code>GEOGRAPHICLIB_VERSION</code> and 8587 <code>GEOGRAPHICLIB_VERSION_NUM</code>; 8588 - add solution and project files for Visual Studio Express 2010. 8589 . 8590 - <a href="https://geographiclib.sourceforge.io/1.36">Version 1.36</a> 8591 (released 2014-05-13) 8592 - Changes to comply with NGA's prohibition of the use of the 8593 upper-case letters N/S to designate the hemisphere when displaying 8594 UTM/UPS coordinates: 8595 - UTMUPS::DecodeZone allows north/south as hemisphere 8596 designators (in addition to n/s); 8597 - UTMUPS::EncodeZone now encodes the hemisphere in 8598 <i>lower case</i> (to distinguish this use from a grid zone 8599 designator); 8600 - UTMUPS::EncodeZone takes an optional parameter \e 8601 abbrev to indicate whether to use n/s or north/south as the 8602 hemisphere designator; 8603 - GeoCoords::UTMUPSRepresentation and 8604 GeoCoords::AltUTMUPSRepresentation similarly accept 8605 the \e abbrev parameter; 8606 - <a href="GeoConvert.1.html">GeoConvert</a> uses the 8607 flags -a and -l to govern whether UTM/UPS output uses n/s 8608 (the -a flag) or north/south (the -l flag) to denote the 8609 hemisphere; 8610 - Fixed a bug what allowed +3N to be accepted as an alternative UTM 8611 zone designation (instead of 3N). 8612 . 8613 <b>WARNING:</b> The use of lower case n/s for the hemisphere might 8614 cause compatibility problems. However DecodeZone has always 8615 accepted either case; so the issue will only arise with other 8616 software reading the zone information. To avoid possible 8617 misinterpretation of the zone designator, consider calling 8618 EncodeZone with \e abbrev = false and GeoConvert with -l, so that 8619 north/south are used to denote the hemisphere. 8620 - MGRS::Forward with \e prec = −1 will produce a grid 8621 zone designation. Similarly MGRS::Reverse will 8622 decode a grid zone designation (and return \e prec = −1). 8623 - Stop using the throw() declaration specification which is 8624 deprecated in C++11. 8625 - Add missing std:: qualifications to copy in LocalCartesion and 8626 Geocentric headers (bug found by Clemens). 8627 . 8628 - <a href="https://geographiclib.sourceforge.io/1.35">Version 1.35</a> 8629 (released 2014-03-13) 8630 - Fix blunder in UTMUPS::EncodeEPSG (found by Ben 8631 Adler). 8632 - MATLAB wrapper routines geodesic{direct,inverse,line} switch to 8633 "exact" routes if |<i>f</i>| > 0.02. 8634 - GeodSolve.cgi allows ellipsoid to be set (and uses the -E option 8635 for <a href="GeodSolve.1.html">GeodSolve</a>). 8636 - Set title in HTML versions of man pages for the \ref utilities. 8637 - Changes in cmake support: 8638 - add _d to names of executables in debug mode of Visual Studio; 8639 - add support for Android (cmake-only), thanks to Pullan Yu; 8640 - check CPACK version numbers supplied on command line; 8641 - configured version of project-config.cmake.in is 8642 project-config.cmake (instead of geographiclib-config.cmake), to 8643 prevent find_package incorrectly using this file; 8644 - fix tests with multi-line output; 8645 - this release includes a file, pom.xml, which is used by an 8646 experimental build system (based on maven) at SRI. 8647 . 8648 - <a href="https://geographiclib.sourceforge.io/1.34">Version 1.34</a> 8649 (released 2013-12-11) 8650 - Many changes in cmake support: 8651 - minimum version of cmake needed increased to 2.8.4 (which was 8652 released in 2011-02); 8653 - allow building both shared and static libraries with <code>-D 8654 GEOGRAPHICLIB_LIB_TYPE=BOTH</code>; 8655 - both shared and static libraries (Release plus Debug) included in 8656 binary installer; 8657 - find_package uses COMPONENTS and GeographicLib_USE_STATIC_LIBS to 8658 select the library to use; 8659 - find_package version checking allows nmake and Visual Studio 8660 generators to interoperate on Windows; 8661 - find_package (GeographicLib …) requires that GeographicLib be 8662 capitalized correctly; 8663 - on Unix/Linux, don't include the version number in directory for 8664 the cmake configuration files; 8665 - defaults for GEOGRAPHICLIB_DOCUMENTATION and 8666 BUILD_NETGEOGRAPHICLIB are now OFF; 8667 - the GEOGRAPHICLIB_EXAMPLES configuration parameter is no longer 8668 used; cmake always configures to build the examples, but they are 8669 not built by default (instead build targets: exampleprograms and 8670 netexamples); 8671 - matlab-all target renamed to matlabinterface; 8672 - the configuration parameters PACKAGE_PATH and INSTALL_PATH are 8673 now deprecated (use CMAKE_INSTALL_PREFIX instead); 8674 - on Linux, the installed package is relocatable; 8675 - on MacOSX, the installed utilities can find the shared library. 8676 - Use a more precise value for OSGB::CentralScale(). 8677 - Add Arc routines to Python interface. 8678 - The Geod utility has been removed; the same functionality lives on 8679 with <a href="GeodSolve.1.html">GeodSolve</a> (introduced in 8680 version 1.30). 8681 . 8682 - <a href="https://geographiclib.sourceforge.io/1.33">Version 1.33</a> 8683 (released 2013-10-08) 8684 - Add <a href="NET/index.html">NETGeographic .NET wrapper library</a> 8685 (courtesy of Scott Heiman). 8686 - Make inspector functions in Ellipsoid const. 8687 - Add Accumulator.cpp to instantiate Accumulator. 8688 - Defer some of the initialization of OSGB to when it 8689 is first called. 8690 - Fix bug in autoconf builds under MacOS. 8691 . 8692 - <a href="https://geographiclib.sourceforge.io/1.32">Version 1.32</a> 8693 (released 2013-07-12) 8694 - Generalize C interface for polygon areas to allow vertices to be 8695 specified incrementally. 8696 - Fix way flags for C++11 support are determined. 8697 . 8698 - <a href="https://geographiclib.sourceforge.io/1.31">Version 1.31</a> 8699 (released 2013-07-01) 8700 - Changes breaking binary compatibility (source compatibility is 8701 maintained): 8702 - overloaded versions of DMS::Encode, 8703 EllipticFunction::EllipticFunction, and 8704 GeoCoords::DMSRepresentation, have been eliminated 8705 by the use of optional arguments; 8706 - correct the declaration of first arg to 8707 UTMUPS::DecodeEPSG. 8708 - FIX BUG in GravityCircle constructor (found by 8709 Mathieu Peyréga) which caused bogus results for the gravity 8710 disturbance and gravity anomaly vectors. (This only affected 8711 calculations using GravityCircle. GravityModel calculations did 8712 not suffer from this bug.) 8713 - Improvements to the build: 8714 - add macros GEOGRAPHICLIB_VERSION_{MAJOR,MINOR,PATCH} to Config.h; 8715 - fix documentation for new version of perlpod; 8716 - improving setting of runtime path for Unix-like systems with cmake; 8717 - install PDB files when compiling with Visual Studio to aid 8718 debugging; 8719 - Windows binary release now uses MATLAB R2013a (64-bit) and 8720 uses the -largeArrayDims option. 8721 - fixes to the way the MATLAB interface routines are built (thanks 8722 to Phil Miller and Chris F.). 8723 - Changes to the geodesic routines: 8724 - add \ref java of the geodesic routines (thanks to Skip Breidbach 8725 for the maven support); 8726 - FIX BUG: avoid altering input args in Fortran implementation; 8727 - more systematic treatment of very short geodesic; 8728 - fixes to Python port so that they work with version 3.x, in 8729 addition to 2.x (courtesy of Amato); 8730 - accumulate the perimeter and area of polygons via a double-wide 8731 accumulator in Fortran, C, and MATLAB implementations (this is 8732 already included in the other implementations); 8733 - port PolygonArea::AddEdge and 8734 PolygonArea::TestEdge to JavaScript and Python 8735 interfaces; 8736 - include documentation on \ref geodshort. 8737 - Unix scripts for downloading datasets, 8738 geographiclib-get-{geoids,gravity,magnetic}, skip already download 8739 models by default, unless the -f flag is given. 8740 - FIX BUGS: meridian convergence and scale returned by 8741 TransverseMercatorExact was wrong at a pole. 8742 - Improve efficiency of MGRS::Forward by avoiding the 8743 calculation of the latitude if possible (adapting an idea of Craig 8744 Rollins). 8745 - Fixes to the way the MATLAB interface routines are built (thanks to 8746 Phil Miller and Chris F.). 8747 . 8748 - <a href="https://geographiclib.sourceforge.io/1.30">Version 1.30</a> 8749 (released 2013-02-27) 8750 - Changes to geodesic routines: 8751 - FIX BUG in fail-safe mechanisms in Geodesic::Inverse; 8752 - the command line utility Geod is now called 8753 <a href="GeodSolve.1.html">GeodSolve</a>; 8754 - allow addition of polygon edges in PolygonArea; 8755 - add full Maxima implementation of geodesic algorithms. 8756 . 8757 - <a href="https://geographiclib.sourceforge.io/1.29">Version 1.29</a> 8758 (released 2013-01-16) 8759 - Changes to allow compilation with libc++ (courtesy of Kal Conley). 8760 - Add description of \ref triaxial to documentation. 8761 - Update journal reference for "Algorithms for geodesics". 8762 . 8763 - <a href="https://geographiclib.sourceforge.io/1.28">Version 1.28</a> 8764 (released 2012-12-11) 8765 - Changes to geodesic routines: 8766 - compute longitude difference exactly; 8767 - hence FIX BUG in area calculations for polygons with vertices very 8768 close to the prime meridian; 8769 - FIX BUG is geoddistance.m where the value of m12 was wrong for 8770 meridional geodesics; 8771 - add MATLAB implementations of the geodesic projections; 8772 - remove unneeded special code for geodesics which start at a pole; 8773 - include polygon area routine in C and Fortran implementations; 8774 - add doxygen documentation for C and Fortran libraries. 8775 . 8776 - <a href="https://geographiclib.sourceforge.io/1.27">Version 1.27</a> 8777 (released 2012-11-29) 8778 - Changes to geodesic routines: 8779 - add native MATLAB implementations: geoddistance.m, geodreckon.m, 8780 geodarea.m; 8781 - add C and Fortran implementations; 8782 - improve the solution of the direct problem so that the series 8783 solution is accurate to round off for |<i>f</i>| < 1/50; 8784 - tighten up the convergence criteria for solution of the inverse 8785 problem; 8786 - no longer signal failures of convergence with NaNs (a slightly 8787 less accurate answer is returned instead). 8788 - Fix DMS::Decode double rounding BUG. 8789 - On MacOSX platforms with the cmake configuration, universal 8790 binaries are built. 8791 . 8792 - <a href="https://geographiclib.sourceforge.io/1.26">Version 1.26</a> 8793 (released 2012-10-22) 8794 - Replace the series used for geodesic areas by one with better 8795 convergence (this only makes an appreciable difference if 8796 |<i>f</i>| > 1/150). 8797 . 8798 - <a href="https://geographiclib.sourceforge.io/1.25">Version 1.25</a> 8799 (released 2012-10-16) 8800 - Changes to geodesic calculations: 8801 - restart Newton's method in Geodesic::Inverse when it goes awry; 8802 - back up Newton's method with the bisection method; 8803 - Geodesic::Inverse now converges for any value of \e f; 8804 - add GeodesicExact and GeodesicLineExact which are formulated in 8805 terms of elliptic integrals and thus yield accurate results even 8806 for very eccentric ellipsoids; 8807 - the -E option to <a href="GeodSolve.1.html">Geod</a> invokes these 8808 exact classes. 8809 - Add functionality to EllipticFunction: 8810 - add all the traditional elliptic integrals; 8811 - remove restrictions on argument range for incomplete elliptic integrals; 8812 - allow imaginary modulus for elliptic integrals and elliptic functions; 8813 - make interface to the symmetric elliptic integrals public. 8814 - Allow Ellipsoid to be copied. 8815 - Changes to the build tools: 8816 - cmake uses folders in Visual Studio to reduce clutter; 8817 - allow precision of reals to be set in cmake; 8818 - fail gracefully in the absence of pod documentation tools; 8819 - remove support for maintainer tasks in Makefile.mk; 8820 - upgrade to automake 1.11.6 to fix the "make distcheck" security 8821 vulnerability; see 8822 https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2012-3386 8823 . 8824 - <a href="https://geographiclib.sourceforge.io/1.24">Version 1.24</a> 8825 (released 2012-09-22) 8826 - Allow the specification of the hemisphere in UTM coordinates in 8827 order to provide continuity across the equator: 8828 - add UTMUPS::Transfer; 8829 - add GeoCoords::UTMUPSRepresentation(bool, int) and 8830 GeoCoords::AltUTMUPSRepresentation(bool, int); 8831 - use the hemisphere letter in, e.g., 8832 <a href="GeoConvert.1.html">GeoConvert</a> -u -z 31n. 8833 - Add UTMUPS::DecodeEPSG and 8834 UTMUPS::EncodeEPSG. 8835 - cmake changes: 8836 - restore support for cmake 2.4.x; 8837 - explicitly check version of doxygen. 8838 - Fix building under cygwin. 8839 - Document restrictions on \e f in \ref intro. 8840 - Fix Python interface to work with version 2.6.x. 8841 . 8842 - <a href="https://geographiclib.sourceforge.io/1.23">Version 1.23</a> 8843 (released 2012-07-17) 8844 - Documentation changes: 8845 - remove html documentation from distribution and use web links if 8846 doxygen is not available; 8847 - use doxygen tags to document exceptions; 8848 - begin migrating the documentation to using Greek letters where 8849 appropriate (requires doxygen 1.8.1.2 or later). 8850 - Add Math::AngNormalize and 8851 Math::AngNormalize2; the allowed range for longitudes 8852 and azimuths widened to [−540°, 540°). 8853 - DMS::Decode understands more unicode symbols. 8854 - Geohash uses geohash code "nan" to stand for not a 8855 number. 8856 - Add Ellipsoid::NormalCurvatureRadius. 8857 - Various fixes in LambertConformalConic, 8858 TransverseMercator, 8859 PolarStereographic, and Ellipsoid to 8860 handle reverse projections of points near infinity. 8861 - Fix programming blunder in LambertConformalConic::Forward 8862 (incorrect results were returned if the tangent latitude was 8863 negative). 8864 . 8865 - <a href="https://geographiclib.sourceforge.io/1.22">Version 1.22</a> 8866 (released 2012-05-27) 8867 - Add Geohash and Ellipsoid classes. 8868 - FIX BUG in AlbersEqualArea for very prolate 8869 ellipsoids (<i>b</i><sup>2</sup> > 2 <i>a</i><sup>2</sup>). 8870 - cmake changes: 8871 - optionally use PACKAGE_PATH and INSTALL_PATH to determine 8872 CMAKE_INSTALL_PREFIX; 8873 - use COMMON_INSTALL_PATH to determine layout of installation 8874 directories; 8875 - as a consequence, the installation paths for the documentation, 8876 and Python and MATLAB interfaces are shortened for Windows; 8877 - zip source distribution now uses DOS line endings; 8878 - the tests work in debug mode for Windows; 8879 - default setting of GEOGRAPHICLIB_DATA does not depend on 8880 CMAKE_INSTALL_PREFIX; 8881 - add a cmake configuration for build tree. 8882 . 8883 - <a href="https://geographiclib.sourceforge.io/1.21">Version 1.21</a> 8884 (released 2012-04-25) 8885 - Support colon-separated DMS output: 8886 - DMS::Encode and 8887 GeoCoords::DMSRepresentation generalized; 8888 - <a href="GeoConvert.1.html">GeoConvert</a> and 8889 <a href="GeodSolve.1.html">Geod</a> now accept a -: option. 8890 - <a href="GeoidEval.1.html">GeoidEval</a> does not print the gradient 8891 of the geoid height by default (because it's subject to large 8892 errors); give the -g option to get the gradient printed. 8893 - Work around optimization BUG in Geodesic::Inverse 8894 with tdm mingw g++ version 4.6.1. 8895 - autoconf fixed to ensure that that out-of-sources builds work; 8896 document this as the preferred method of using autoconf. 8897 - cmake tweaks: 8898 - simplify the configuration of doxygen; 8899 - allow the MATLAB compiler to be specified with the 8900 MATLAB_COMPILER option. 8901 . 8902 - <a href="https://geographiclib.sourceforge.io/1.20">Version 1.20</a> 8903 (released 2012-03-23) 8904 - cmake tweaks: 8905 - improve find_package's matching of compiler versions; 8906 - CMAKE_INSTALL_PREFIX set from CMAKE_PREFIX_PATH if available; 8907 - add "x64" to the package name for the 64-bit binary installer; 8908 - fix cmake warning with Visual Studio Express. 8909 - Fix SphericalEngine to deal with aggressive iterator 8910 checking by Visual Studio. 8911 - Fix transcription BUG is Geodesic.js. 8912 . 8913 - <a href="https://geographiclib.sourceforge.io/1.19">Version 1.19</a> 8914 (released 2012-03-13) 8915 - Slight improvement in Geodesic::Inverse for very 8916 short lines. 8917 - Fix argument checking tests in MGRS::Forward. 8918 - Add \--comment-delimiter and \--line-separator options to the \ref 8919 utilities. 8920 - Add installer for 64-bit Windows; the compiled MATLAB interface is 8921 supplied with the Windows 64-bit installer only. 8922 . 8923 - <a href="https://geographiclib.sourceforge.io/1.18">Version 1.18</a> 8924 (released 2012-02-18) 8925 - Improve documentation on configuration with cmake. 8926 - cmake's find_package ensures that the compiler versions match on Windows. 8927 - Improve documentation on compiling MATLAB interface. 8928 - Binary installer for Windows installs under C:/pkg-vc10 by default. 8929 . 8930 - <a href="https://geographiclib.sourceforge.io/1.17">Version 1.17</a> 8931 (released 2012-01-21) 8932 - Work around optimization BUG in Geodesic::Inverse 8933 with g++ version 4.4.0 (mingw). 8934 - Fix BUG in argument checking with OSGB::GridReference. 8935 - Fix missing include file in SphericalHarmonic2. 8936 - Add simple examples of usage for each class. 8937 - Add internal documentation to the cmake configuration files. 8938 . 8939 - <a href="https://geographiclib.sourceforge.io/1.16">Version 1.16</a> 8940 (released 2011-12-07) 8941 - Add calculation of the earth's gravitational field: 8942 - add NormalGravity GravityModel and 8943 GravityCircle classes; 8944 - add command line utility 8945 <a href="Gravity.1.html">Gravity</a>; 8946 - add \ref gravity; 8947 - add Constants::WGS84_GM(), Constants::WGS84_omega(), and 8948 similarly for GRS80. 8949 - Build uses GEOGRAPHICLIB_DATA to specify a common parent directory 8950 for geoid, gravity, and magnetic data (instead of 8951 GEOGRAPHICLIB_GEOID_PATH, etc.); similarly, 8952 <a href="GeoidEval.1.html">GeoidEval</a>, 8953 <a href="Gravity.1.html">Gravity</a>, and 8954 <a href="MagneticField.1.html">MagneticField</a>, look at the 8955 environment variable GEOGRAPHICLIB_DATA to locate the data. 8956 - Spherical harmonic software changes: 8957 - capitalize enums SphericalHarmonic::FULL and 8958 SphericalHarmonic::SCHMIDT (the lower case names 8959 are retained but deprecated); 8960 - optimize the sum by using a static table of square roots which is 8961 updated by SphericalEngine::RootTable; 8962 - avoid overflow for high degree models. 8963 - Magnetic software fixes: 8964 - fix documentation BUG in MagneticModel::Circle; 8965 - make MagneticModel constructor explicit; 8966 - provide default MagneticCircle constructor; 8967 - add additional inspector functions to 8968 MagneticCircle; 8969 - add -c option to <a href="MagneticField.1.html">MagneticField</a>; 8970 - default height to zero in 8971 <a href="MagneticField.1.html">MagneticField</a>. 8972 . 8973 - <a href="https://geographiclib.sourceforge.io/1.15">Version 1.15</a> 8974 (released 2011-11-08) 8975 - Add calculation of the earth's magnetic field: 8976 - add MagneticModel and MagneticCircle 8977 classes; 8978 - add command line utility 8979 <a href="MagneticField.1.html">MagneticField</a>; 8980 - add \ref magnetic; 8981 - add \ref magneticinst; 8982 - add \ref magneticformat; 8983 - add classes SphericalEngine, 8984 CircularEngine, SphericalHarmonic, 8985 SphericalHarmonic1, and 8986 SphericalHarmonic2. which sum spherical harmonic 8987 series. 8988 - Add Utility class to support I/O and date 8989 manipulation. 8990 - Cmake configuration includes a _d suffix on the library built in 8991 debug mode. 8992 - For the Python package, include manifest and readme files; don't 8993 install setup.py for non-Windows systems. 8994 - Include Doxygen tag file in distribution as doc/html/Geographic.tag. 8995 . 8996 - <a href="https://geographiclib.sourceforge.io/1.14">Version 1.14</a> 8997 (released 2011-09-30) 8998 - Ensure that geographiclib-config.cmake is relocatable. 8999 - Allow more unicode symbols to be used in DMS::Decode. 9000 - Modify <a href="GeoidEval.1.html">GeoidEval</a> so that it can be 9001 used to convert the height datum for LIDAR data. 9002 - Modest speed-up of Geodesic::Inverse. 9003 - Changes in Python interface: 9004 - FIX BUG in transcription of Geodesic::Inverse; 9005 - include setup.py for easy installation; 9006 - Python only distribution is available at 9007 https://pypi.python.org/pypi/geographiclib 9008 - Supply a minimal Qt qmake project file for library 9009 src/Geographic.pro. 9010 . 9011 - <a href="https://geographiclib.sourceforge.io/1.13">Version 1.13</a> 9012 (released 2011-08-13) 9013 - Changes to I/O: 9014 - allow : (colon) to be used as a DMS separator in 9015 DMS::Decode(const std::string&, flag&); 9016 - also accept Unicode symbols for degrees, minutes, and seconds 9017 (coded as UTF-8); 9018 - provide optional \e swaplatlong argument to various 9019 DMS and GeoCoords functions to make 9020 longitude precede latitude; 9021 - <a href="GeoConvert.1.html">GeoConvert</a> now has a -w option to 9022 make longitude precede latitude on input and output; 9023 - include a JavaScript version of DMS. 9024 - Slight improvement in starting guess for solution of geographic 9025 latitude in terms of conformal latitude in TransverseMercator, 9026 TransverseMercatorExact, and LambertConformalConic. 9027 - For most classes, get rid of const member variables so that the 9028 default copy assignment works. 9029 - Put Math and Accumulator in their own 9030 header files. 9031 - Remove unused "fast" Accumulator method. 9032 - Reorganize the \ref python. 9033 - Withdraw some deprecated routines. 9034 - cmake changes: 9035 - include FindGeographic.cmake in distribution; 9036 - building with cmake creates and installs 9037 geographiclib-config.cmake; 9038 - better support for building a shared library under Windows. 9039 . 9040 - <a href="https://geographiclib.sourceforge.io/1.12">Version 1.12</a> 9041 (released 2011-07-21) 9042 - Change license to MIT/X11. 9043 - Add PolygonArea class and equivalent MATLAB function. 9044 - Provide JavaScript and Python implementations of geodesic routines. 9045 - Fix Windows installer to include runtime dlls for MATLAB. 9046 - Fix (innocuous) unassigned variable in Geodesic::GenInverse. 9047 - Geodesic routines in MATLAB return a12 as first column of aux return 9048 value (incompatible change). 9049 - A couple of code changes to enable compilation with Visual 9050 Studio 2003. 9051 . 9052 - <a href="https://geographiclib.sourceforge.io/1.11">Version 1.11</a> 9053 (released 2011-06-27) 9054 - Changes to <a href="Planimeter.1.html">Planimeter</a>: 9055 - add -l flag to <a href="Planimeter.1.html">Planimeter</a> for polyline 9056 calculations; 9057 - trim precision of area to 3 decimal places; 9058 - FIX BUG with pole crossing edges (due to compiler optimization). 9059 - <a href="GeodSolve.1.html">Geod</a> no longer reports the reduced 9060 length by default; however the -f flag still reports this and in 9061 addition gives the geodesic scales and the geodesic area. 9062 - FIX BUGS (compiler-specific) in inverse geodesic calculations. 9063 - FIX BUG: accommodate tellg() returning −1 at end of string. 9064 - Change way flattening of the ellipsoid is specified: 9065 - constructors take \e f argument which is taken to be the 9066 flattening if \e f < 1 and the inverse flattening otherwise 9067 (this is a compatible change for spheres and oblate ellipsoids, but it 9068 is an INCOMPATIBLE change for prolate ellipsoids); 9069 - the -e arguments to the \ref utilities are handled similarly; in 9070 addition, simple fractions, e.g., 1/297, can be used for the 9071 flattening; 9072 - introduce Constants::WGS84_f() for the WGS84 9073 flattening (and deprecate Constants::WGS84_r() for the inverse 9074 flattening); 9075 - most classes have a Flattening() member function; 9076 - InverseFlattening() has been deprecated (and now returns inf for a 9077 sphere, instead of 0). 9078 . 9079 - <a href="https://geographiclib.sourceforge.io/1.10">Version 1.10</a> 9080 (released 2011-06-11) 9081 - Improvements to MATLAB/Octave interface: 9082 - add {geocentric,localcartesian}{forward,reverse}; 9083 - make geographiclibinterface more general; 9084 - install the source for the interface; 9085 - cmake compiles the interface if ENABLE_MATLAB=ON; 9086 - include compiled interface with Windows binary installer. 9087 - Fix various configuration issues 9088 - autoconf did not install Config.h; 9089 - cmake installed in man/man1 instead of share/man/man1; 9090 - cmake did not set the rpath on the tools. 9091 . 9092 - <a href="https://geographiclib.sourceforge.io/1.9">Version 1.9</a> 9093 (released 2011-05-28) 9094 - FIX BUG in area returned by 9095 <a href="Planimeter.1.html">Planimeter</a> for pole encircling polygons. 9096 - FIX BUG in error message reported when DMS::Decode reads the string 9097 "5d.". 9098 - FIX BUG in AlbersEqualArea::Reverse (lon0 not being used). 9099 - Ensure that all exceptions thrown in the \ref utilities are caught. 9100 - Avoid using catch within DMS. 9101 - Move Accumulator class from Planimeter.cpp to 9102 Constants.hpp. 9103 - Add Math::sq<T>. 9104 - Simplify \ref geoidinst 9105 - add geographiclib-get-geoids for Unix-like systems; 9106 - add installers for Windows. 9107 - Provide cmake support: 9108 - build binary installer for Windows; 9109 - include regression tests; 9110 - add \--input-string, \--input-file, \--output-file options to the 9111 \ref utilities to support tests. 9112 - Rename utility EquidistantTest as <a href="GeodesicProj.1.html"> 9113 GeodesicProj</a> and TransverseMercatorTest as 9114 <a href="TransverseMercatorProj.1.html"> TransverseMercatorProj</a>. 9115 - Add <a href="ConicProj.1.html"> ConicProj</a>. 9116 - Reverse the initial sense of the -s option for 9117 <a href="Planimeter.1.html"> Planimeter</a>. 9118 - Migrate source from subversion to git. 9119 . 9120 - <a href="https://geographiclib.sourceforge.io/1.8">Version 1.8</a> 9121 (released 2011-02-22) 9122 - Optionally return rotation matrix from Geocentric and 9123 LocalCartesian. 9124 - For the \ref utilities, supply man pages, -h prints the synopsis, 9125 \--help prints the man page, \--version prints the version. 9126 - Use accurate summation in <a href="Planimeter.1.html">Planimeter</a>. 9127 - Add 64-bit targets for Visual Studio 2010. 9128 - Use templates for defining math functions and some constants. 9129 - Geoid updates 9130 - Add Geoid::DefaultGeoidPath and 9131 Geoid::DefaultGeoidName; 9132 - <a href="GeoidEval.1.html">GeoidEval</a> uses environment variable 9133 GEOGRAPHICLIB_GEOID_NAME as the default geoid; 9134 - Add \--msltohae and \--haetomsl as 9135 <a href="GeoidEval.1.html">GeoidEval</a> options (and don't 9136 document the single hyphen versions). 9137 - Remove documentation that duplicates papers on transverse Mercator 9138 and geodesics. 9139 . 9140 - <a href="https://geographiclib.sourceforge.io/1.7">Version 1.7</a> 9141 (released 2010-12-21) 9142 - FIX BUG in scale returned by LambertConformalConic::Reverse. 9143 - Add AlbersEqualArea projection. 9144 - Library created by Visual Studio is Geographic.lib instead of 9145 GeographicLib.lib (compatible with makefiles). 9146 - Make classes NaN aware. 9147 - Use cell arrays for MGRS strings in MATLAB. 9148 - Add solution/project files for Visual Studio 2010 (32-bit only). 9149 - Use C++11 static_assert and math functions, if available. 9150 . 9151 - <a href="https://geographiclib.sourceforge.io/1.6">Version 1.6</a> 9152 (released 2010-11-23) 9153 - FIX BUG introduced in Geoid in version 1.5 (found by 9154 Dave Edwards). 9155 . 9156 - <a href="https://geographiclib.sourceforge.io/1.5">Version 1.5</a> 9157 (released 2010-11-19) 9158 - Improve area calculations for small polygons. 9159 - Add -s and -r flags to <a href="Planimeter.1.html">Planimeter</a>. 9160 - Improve the accuracy of LambertConformalConic using 9161 divided differences. 9162 - FIX BUG in meridian convergence returned by 9163 LambertConformalConic::Forward. 9164 - Add optional threadsafe parameter to Geoid 9165 constructor. WARNING: This changes may break binary compatibility 9166 with previous versions of GeographicLib. However, the library is 9167 source compatible. 9168 - Add OSGB. 9169 - MATLAB and Octave interfaces to UTMUPS, 9170 MGRS, Geoid, Geodesic 9171 provided. 9172 - Minor changes 9173 - explicitly turn on optimization in Visual Studio 2008 projects; 9174 - add missing dependencies in some Makefiles; 9175 - move pi() and degree() from Constants to 9176 Math; 9177 - introduce Math::extended type to aid testing; 9178 - add Math::epi() and Math::edegree(). 9179 - fixes to compile under cygwin; 9180 - tweak expression used to find latitude from conformal latitude. 9181 . 9182 - <a href="https://geographiclib.sourceforge.io/1.4">Version 1.4</a> 9183 (released 2010-09-12) 9184 - Changes to Geodesic and GeodesicLine: 9185 - FIX BUG in Geodesic::Inverse with prolate ellipsoids; 9186 - add area computations to Geodesic::Direct and Geodesic::Inverse; 9187 - add geodesic areas to geodesic test set; 9188 - make GeodesicLine constructor public; 9189 - change longitude series in Geodesic into Helmert-like form; 9190 - ensure that equatorial geodesics have cos(alpha0) = 0 identically; 9191 - generalize interface for Geodesic and GeodesicLine; 9192 - split GeodesicLine and Geodesic into different files; 9193 - signal convergence failure in Geodesic::Inverse with NaNs; 9194 - deprecate one function in Geodesic and two functions in 9195 GeodesicLine; 9196 - deprecate -n option for <a href="GeodSolve.1.html">Geod</a>. 9197 . 9198 <b>WARNING</b>: These changes may break binary compatibility with 9199 previous versions of GeographicLib. However, the library is 9200 source compatible (with the proviso that 9201 GeographicLib/GeodesicLine.hpp may now need to be included). 9202 - Add the <a href="Planimeter.1.html">Planimeter</a> utility for 9203 computing the areas of geodesic polygons. 9204 - Improve iterative solution of Gnomonic::Reverse. 9205 - Add Geoid::ConvertHeight. 9206 - Add -msltohae, -haetomsl, and -z options to 9207 <a href="GeoidEval.1.html">GeoidEval</a>. 9208 - Constructors check that minor radius is positive. 9209 - Add overloaded Forward and Reverse functions to the projection 9210 classes which don't return the convergence (or azimuth) and scale. 9211 - Document function parameters and return values consistently. 9212 . 9213 - <a href="https://geographiclib.sourceforge.io/1.3">Version 1.3</a> 9214 (released 2010-07-21) 9215 - Add Gnomonic, the ellipsoid generalization of the 9216 gnomonic projection. 9217 - Add -g and -e options to 9218 <a href="GeodesicProj.1.html">EquidistantTest</a>. 9219 - Use fixed-point notation for output from 9220 <a href="CartConvert.1.html">CartConvert</a>, 9221 <a href="GeodesicProj.1.html">EquidistantTest</a>, 9222 <a href="TransverseMercatorProj.1.html">TransverseMercatorTest</a>. 9223 - PolarStereographic: 9224 - Improved conversion to conformal coordinates; 9225 - Fix bug with scale at opposite pole; 9226 - Complain if latitude out of range in SetScale. 9227 - Add Math::NaN(). 9228 - Add long double version of hypot for Windows. 9229 - Add EllipticFunction::E(real). 9230 - Update references to Geotrans in MGRS documentation. 9231 - Speed up tmseries.mac. 9232 . 9233 - <a href="https://geographiclib.sourceforge.io/1.2">Version 1.2</a> 9234 (released 2010-05-21) 9235 - FIX BUGS in Geodesic, 9236 - wrong azimuth returned by Direct if point 2 is on a pole; 9237 - Inverse sometimes fails with very close points. 9238 - Improve calculation of scale in CassiniSoldner, 9239 - add GeodesicLine::Scale, 9240 GeodesicLine::EquatorialAzimuth, and 9241 GeodesicLine::EquatorialArc; 9242 - break friend connection between CassiniSoldner and Geodesic. 9243 - Add DMS::DecodeAngle and 9244 DMS::DecodeAzimuth. Extend 9245 DMS::Decode and DMS::Encode to deal 9246 with distances. 9247 - Code and documentation changes in Geodesic and 9248 Geocentric for consistency with 9249 the forthcoming paper on geodesics. 9250 - Increase order of series using in Geodesic to 6 (full 9251 accuracy maintained for ellipsoid flattening < 0.01). 9252 - Macro __NO_LONG_DOUBLE_MATH to disable use of long double. 9253 - Correct declaration of Math::isfinite to return a bool. 9254 - Changes in the \ref utilities, 9255 - improve error reporting when parsing command line arguments; 9256 - accept latitudes and longitudes in decimal degrees or degrees, 9257 minutes, and seconds, with optional hemisphere designators; 9258 - <a href="GeoConvert.1.html">GeoConvert</a> -z accepts zone or 9259 zone+hemisphere; 9260 - <a href="GeoidEval.1.html">GeoidEval</a> accepts any of the input 9261 formats used by <a href="GeoConvert.1.html">GeoConvert</a>; 9262 - <a href="CartConvert.1.html">CartConvert</a> allows the ellipsoid 9263 to be specified with -e. 9264 . 9265 - <a href="https://geographiclib.sourceforge.io/1.1">Version 1.1</a> 9266 (released 2010-02-09) 9267 - FIX BUG (introduced in 2009-03) in EllipticFunction::E(sn,cn,dn). 9268 - Increase accuracy of scale calculation in TransverseMercator and 9269 TransverseMercatorExact. 9270 - Code and documentation changes for consistency with 9271 <a href="https://arxiv.org/abs/1002.1417">arXiv:1002.1417</a> 9272 . 9273 - <a href="https://geographiclib.sourceforge.io/1.0">Version 1.0</a> 9274 (released 2010-01-07) 9275 - Add autoconf configuration files. 9276 - BUG FIX: Improve initial guess for Newton's method in 9277 PolarStereographic::Reverse. (Previously this failed to converge 9278 when the co-latitude exceeded about 130 deg.) 9279 - Constructors for TransverseMercator, TransverseMercatorExact, 9280 PolarStereographic, Geocentric, and Geodesic now check for obvious 9281 problems with their arguments and throw an exception if necessary. 9282 - Most classes now include inspector functions such as MajorRadius() 9283 so that you can determine how instances were constructed. 9284 - Add LambertConformalConic class. 9285 - Add PolarStereographic::SetScale to allow the 9286 latitude of true scale to be specified. 9287 - Add solution and project files for Visual Studio 2008. 9288 - Add GeographicErr for exceptions. 9289 - Geoid changes: 9290 - BUG FIX: fix typo in Geoid::Cache which could cause 9291 a segmentation fault in some cases when the cached area spanned 9292 the prime meridian. 9293 - Include sufficient edge data to allow heights to be returned for 9294 cached area without disk reads; 9295 - Add inspector functions to query the extent of the cache. 9296 . 9297 - <a href="https://geographiclib.sourceforge.io/2009-11">Version 2009-11</a> 9298 (released 2009-11-03) 9299 - Allow specification of "closest UTM zone" in UTMUPS 9300 and <a href="GeoConvert.1.html">GeoConvert</a> (via -t option). 9301 - Utilities now complain is there are too many tokens on input lines. 9302 - Include real-to-real versions of DMS::Decode and 9303 DMS::Encode. 9304 - More house-cleaning changes: 9305 - Ensure that functions which return results through reference 9306 arguments do not alter the arguments when an exception is thrown. 9307 - Improve accuracy of MGRS::Forward. 9308 - Include more information in some error messages. 9309 - Improve accuracy of inverse hyperbolic functions. 9310 - Fix the way Math functions handle different precisions. 9311 . 9312 - <a href="https://geographiclib.sourceforge.io/2009-10">Version 2009-10</a> 9313 (released 2009-10-18) 9314 - Change web site to https://geographiclib.sourceforge.io 9315 - Several house-cleaning changes: 9316 - Change from the a flat directory structure to a more easily 9317 maintained one. 9318 - Introduce Math class for common mathematical functions (in 9319 Constants.hpp). 9320 - Use Math::real as the type for all real quantities. By default this 9321 is typedef'ed to double; and the library should be installed this 9322 way. 9323 - Eliminate const reference members of AzimuthalEquidistant, 9324 CassiniSoldner and LocalCartesian so that they may be copied. 9325 - Make several constructors explicit. Disallow some constructors. 9326 Disallow copy constructor/assignment for Geoid. 9327 - Document least squares formulas in Geoid.cpp. 9328 - Use unsigned long long for files positions of geoid files in Geoid. 9329 - Introduce optional mgrslimits argument in UTMUPS::Forward and 9330 UTMUPS::Reverse to enforce stricter MGRS limits on eastings and 9331 northings. 9332 - Add 64-bit targets in Visual Studio project files. 9333 . 9334 - <a href="https://geographiclib.sourceforge.io/2009-09">Version 2009-09</a> 9335 (released 2009-09-01) 9336 - Add Geoid and 9337 <a href="GeoidEval.1.html">GeoidEval</a> utility. 9338 . 9339 - <a href="https://geographiclib.sourceforge.io/2009-08">Version 2009-08</a> 9340 (released 2009-08-14) 9341 - Add CassiniSoldner class and 9342 <a href="GeodesicProj.1.html">EquidistantTest</a> utility. 9343 - Fix bug in Geodesic::Inverse where NaNs were 9344 sometimes returned. 9345 - INCOMPATIBLE CHANGE: AzimuthalEquidistant now returns the reciprocal 9346 of the azimuthal scale instead of the reduced length. 9347 - Add -n option to <a href="GeoConvert.1.html">GeoConvert</a>. 9348 . 9349 - <a href="https://geographiclib.sourceforge.io/2009-07">Version 2009-07</a> 9350 (released 2009-07-16) 9351 - Speed up the series inversion code in tmseries.mac and geod.mac. 9352 - Reference Borkowski in section on \ref geocentric. 9353 . 9354 - <a href="https://geographiclib.sourceforge.io/2009-06">Version 2009-06</a> 9355 (released 2009-06-01) 9356 - Add routines to decode and encode zone+hemisphere to UTMUPS. 9357 - Clean up code in Geodesic. 9358 . 9359 - <a href="https://geographiclib.sourceforge.io/2009-05">Version 2009-05</a> 9360 (released 2009-05-01) 9361 - Improvements to Geodesic: 9362 - more economical series expansions, 9363 - return reduced length (as does the 9364 <a href="GeodSolve.1.html">Geod</a> utility), 9365 - improved calculation of starting point for inverse method, 9366 - use reduced length to give derivative for Newton's method. 9367 - Add AzimuthalEquidistant class. 9368 - Make Geocentric, TransverseMercator, 9369 and PolarStereographic classes work with prolate 9370 ellipsoids. 9371 - <a href="CartConvert.1.html">CartConvert</a> checks its inputs more 9372 carefully. 9373 - Remove reference to defunct Constants.cpp from GeographicLib.vcproj. 9374 . 9375 - <a href="https://geographiclib.sourceforge.io/2009-04">Version 2009-04</a> 9376 (released 2009-04-01) 9377 - Use compile-time constants to select the order of series in 9378 TransverseMercator. 9379 - 2x unroll of Clenshaw summation to avoid data shuffling. 9380 - Simplification of EllipticFunction::E. 9381 - Use STATIC_ASSERT for compile-time checking of constants. 9382 - Improvements to Geodesic: 9383 - compile-time option to change order of series used, 9384 - post Maxima code for generating the series, 9385 - tune the order of series for double, 9386 - improvements in the selection of starting points for Newton's 9387 method, 9388 - accept and return spherical arc lengths, 9389 - works with both oblate and prolate ellipsoids, 9390 - add -a, -e, -b options to the <a href="GeodSolve.1.html">Geod</a> 9391 utility. 9392 . 9393 - <a href="https://geographiclib.sourceforge.io/2009-03">Version 2009-03</a> 9394 (released 2009-03-01) 9395 - Add Geodesic and the 9396 <a href="GeodSolve.1.html">Geod</a> utility. 9397 - Declare when no exceptions are thrown by functions. 9398 - Minor changes to DMS class. 9399 - Use invf = 0 to mean a sphere in constructors to some classes. 9400 - The makefile creates a library and includes an install target. 9401 - Rename ECEF to Geocentric, ECEFConvert 9402 to <a href="CartConvert.1.html">CartConvert</a>. 9403 - Use inline functions to define constant doubles in Constants.hpp. 9404 . 9405 - <a href="https://geographiclib.sourceforge.io/2009-02">Version 2009-02</a> 9406 (released 2009-01-30) 9407 - Fix documentation of constructors (flattening → inverse 9408 flattening). 9409 - Use std versions of math functions. 9410 - Add ECEF and LocalCartesian classes 9411 and the ECEFConvert utility. 9412 - Gather the documentation on the \ref utilities onto one page. 9413 . 9414 - <a href="https://geographiclib.sourceforge.io/2009-01">Version 2009-01</a> 9415 (released 2009-01-12) 9416 - First proper release of library. 9417 - More robust TransverseMercatorExact: 9418 - Introduce \e extendp version of constructor, 9419 - Test against extended test data, 9420 - Optimize starting positions for Newton's method, 9421 - Fix behavior near all singularities, 9422 - Fix order dependence in C++ start-up code, 9423 - Improved method of computing scale and convergence. 9424 - Documentation on transverse Mercator projection. 9425 - Add MGRS, UTMUPS, etc. 9426 . 9427 - Version 2008-09 9428 - Ad hoc posting of information on the transverse Mercator projection. 9429 9430<center> 9431Back to \ref highprec. Up to \ref contents. 9432</center> 9433**********************************************************************/ 9434} 9435
