Octave/MATLAB implementation of GeographicLib

Contents:

• Introduction
• Installation
  • Octave installation
  • MATLAB installation
• Function summary
  • Geodesics
  • Projections
  • Grid systems
  • Geoid lookup
  • Geometric transformations
  • Great ellipses
  • Utility
  • Documentation
  • Triaxial routines
• Changes
• Other links

Introduction

This toolbox provides native Octave/MATLAB implementations of a subset of the C++ library, GeographicLib. Key components of this toolbox are

• Geodesics, direct, inverse, area calculations.
• Projections, transverse Mercator, polar stereographic, etc.
• Grid systems, UTM, UPS, MGRS.
• Geoid lookup, egm84, egm96, egm2008 geoids supported.
• Geometric transformations, geocentric, local cartesian.
• Great ellipse, direct, inverse, area calculations.
• Geodesics and coordinate conversions on a triaxial ellipsoid.

(The last two items are not present in the C++ library.) All the functions are vectorized and so offer speeds comparable to compiled C++ code when operating on arrays.

Some common features of these functions:

• Angles (latitude, longitude, azimuth, meridian convergence) are measured in degrees.
• Distances are measured in meters, areas in meters^2.
• Latitudes must lie in [-90, 90]. Latitudes outside this range are treated in NaNs
• The ellipsoid is specified as [a, e], where a = equatorial radius and e = eccentricity. The eccentricity can be pure imaginary to denote a prolate ellipsoid.
• Keep |e| < 0.2 (i.e., |f| <= 1/50) for full double precision accuracy.

There is some overlap between this toolbox and MATLAB's Mapping Toolbox. However, this toolbox offers:

• better accuracy;
• treatment of oblate and prolate ellipsoid;
• guaranteed convergence for geoddistance;
• calculation of area and differential properties of geodesics;
• ellipsoidal versions of the equidistant azimuthal and gnomonic projections.

Licensed under the MIT/X11 License; see LICENSE.txt.

Installation

The toolbox is available from

• SourceForge This includes packages for Octave, geographiclib-octave-M.N.tar.gz, and MATLAB, geographiclib_toolbox-M.N.mltbx. Here M.N stands for the version number, e.g., 2.0. The Octave and MATLAB packages contain exactly the same code; it's just the packaging that is different.

• Octave Packages. This links to the SourceForge download site.

• MATLAB Central. You need to log in to download packages from here. Use SourceForge (see above) if you don't have an account.

Octave installation

Either download the package to your computer and install it in Octave with the commands

pkg install geographiclib-octave-M.N.tar.gz
pkg load geographiclib

Or you can have Octave download and install the package with the commands

pkg install "https://sourceforge.net/projects/geographiclib/files/distrib-Octave/geographiclib-octave-M.N.tar.gz"
pkg load geographiclib

NOTE: in both cases replace M.N by the version number.

Other useful Octave package commands

pkg list                            % list all packages
ver geographiclib                   % list version
pkg describe -verbose geographiclib % list functions
news geographiclib                  % change log
pkg test geographiclib              % run the tests
pkg unload geographiclib            % remove from path
pkg uninstall geographiclib         % uninstall

MATLAB installation

The MATLAB toolbox can be installed via the "Add-Ons" menu item with MATLAB. Alternatively, it can be installed by downloading the package from SourceForge (see above) and using the command

matlab.addons.install geographiclib_toolbox-M.N.mltbx

NOTE: replace M.N by the version number.

Other useful MATLAB toolboxes commands

t = matlab.addons.installedAddons        % list all toolboxes
n = 1;                                   % the row with geographiclib
matlab.addons.uninstall(t.Identifier(n)) % uninstall

Function summary

Geodesics

• geoddistance - Distance between points on an ellipsoid
• geodreckon - Point at specified azimuth, range on an ellipsoid
• geodarea - Surface area of polygon on an ellipsoid

Projections

• tranmerc_fwd - Forward transverse Mercator projection
• tranmerc_inv - Inverse transverse Mercator projection
• polarst_fwd - Forward polar stereographic projection
• polarst_inv - Inverse polar stereographic projection
• eqdazim_fwd - Forward azimuthal equidistant projection
• eqdazim_inv - Inverse azimuthal equidistant projection
• cassini_fwd - Forward Cassini-Soldner projection
• cassini_inv - Inverse Cassini-Soldner projection
• gnomonic_fwd - Forward ellipsoidal gnomonic projection
• gnomonic_inv - Inverse ellipsoidal gnomonic projection

Grid systems

• utmups_fwd - Convert to UTM/UPS system
• utmups_inv - Convert from UTM/UPS system
• mgrs_fwd - Convert UTM/UPS coordinates to MGRS
• mgrs_inv - Convert MGRS to UTM/UPS coordinates

Geoid lookup

• geoid_height - Compute the height of the geoid above the ellipsoid
• geoid_load - Load a geoid model

Geometric transformations

• geocent_fwd - Conversion from geographic to geocentric coordinates
• geocent_inv - Conversion from geocentric to geographic coordinates
• loccart_fwd - Convert geographic to local cartesian coordinates
• loccart_inv - Convert local cartesian to geographic coordinates

Great ellipses

• gedistance - Great ellipse distance on an ellipsoid
• gereckon - Point along great ellipse at given azimuth and range

Utility

• defaultellipsoid - Set/return the default ellipsoid
• ecc2flat - Convert eccentricity to flattening
• flat2ecc - Convert flattening to eccentricity
• linesimp - Simplify 2d or 3d polyline
• geographiclib_test - The test suite for the geographiclib package
• geographiclib_signtest - Another test suite

Documentation

• geoddoc - Geodesics on an ellipsoid of revolution
• projdoc - Projections for an ellipsoid
• gedoc - Great ellipses on an ellipsoid of revolution

The class for triaxial ellipsoids

See also Implementation details for details of some of the algorithms used here.

• triaxial.triaxial - The constructor
• triaxial.carttocart2 - Find the closest point on the ellipsoid
• triaxial.cart2tocart - Find the point above a point on the ellipsoid
• triaxial.cart2toellip - Convert a surface point to ellipsoidal coordinates
• triaxial.elliptocart2 - Convert ellipsoid coordinates to a surface point
• triaxial.carttoellip - Convert cartesian coordinates to ellipsoid
• triaxial.elliptocart - Convert ellipsoidal coordinates to cartesian
• triaxial.cart2togeod - Convert a surface point to geodetic coordinates
• triaxial.carttogeod - Convert a cartesian point to geodetic
• triaxial.geodtocart - Convert geodetic coordinates to cartesian
• triaxial.cart2toparam - Convert a surface point to parametric coordinates
• triaxial.paramtocart2 - Convert parametric coordinates to a surface point
• triaxial.cart2togeocen - Convert a surface point to geocentric coordinates
• triaxial.geocentocart2 - Convert geocentric coordinates to a surface point
• triaxial.convert - General coordinate conversion
• triaxial.cart2rand - Random points on the ellipsoid
• triaxial.reckon - Solve the direct geodesic problem
• triaxial.distance - Solve the inverse geodesic problem
• triaxial.hybrid - Solve the hybrid geodesic problem
• triaxial.cart2norm - Force a point to lie on the ellipsoid
• triaxial.scaled - Return a scaled ellipsoid
• triaxial.cartproj - Plot a curve on the ellipsoid
• triaxial.horizon - Point on the horizon of the ellipsoid
• triaxial.ellipnorm - Reduce ellipsoidal coordinates to standard ranges
• triaxial.ellipflip - Switch ellipsoidal coordinates to the other sheet
• triaxial.demo - Demonstrate geodesics
• triaxial.doc - Summary documentation of triaxial class
• triaxial.tests - Self test

Changes

See the change log. Releases are tagged in git as, e.g., v1.52, v2.0, etc.

Other links

• GeographicLib.
• Implementations in other languages.
• How to install the geoid datasets.
• C. F. F. Karney, Transverse Mercator with an accuracy of a few nanometers, J. Geodesy 85(8), 475–485 (2011); preprint; addenda.
• C. F. F. Karney, Algorithms for geodesics, J. Geodesy 87(1), 43–55 (2013); addenda.
• Implementation details for the triaxial class.