as an Octave package. This is a package for doing geodesic calculations
on the earth ellipsoid and a few other geography-related functions.
It’s all standalone MATLAB-Octave code with no additional dependencies
so it would be nice if it could be added as an Octave package with
Thank you for your potential code contribution. Please compare to the Octave mapping package to see what functionality overlaps if any. You will have a better idea of where your code will fit in after that.
This actually looks pretty cool! (I think; I’m having a little trouble following all the documentation here.)
I see that you’ve included links on the File Exchange description page to the SourceForge site for this GeographicLib library. But those look like links into a larger C++ or multi-language project; it’s not clear to me how that larger library gets transformed into the Matlab/Octave-specific package (or “toolbox”) which is then uploaded to File Exchange. (We usually refer to that as a “binding” layer.) Like, when I go to https://geographiclib.sourceforge.io/ I see the “Matlab/Octave (geodesic and some other routines):” item for Matlab/Octave. But that item just has links to the File Exchange submission and a “viewer.mathworks.com” link to a a summary documentation *.m file for a package or directory.
I’m not sure how all this stuff fits together? Is this Matlab GeographicLib a Matlab binding layer for the main C++ GeographicLib library? Or is it an alternate M-code implementation of it?
I’d say (in a definitely-unofficial capacity) the next steps are:
Yeah, compare it to the existing mapping package like arungiridhar says
Let’s discuss exactly what this project/package is and how it works?
And then if you think it’s worthwhile, create a standard Octave package directory structure for it, like with a inst/ directory and a DESCRIPTION metadata file, so that Octave’s pkg command can work with it. That’s the basics of what you need to do to convert a collection of M-code into an Octave package.
To address just one of your questions. This package is a pure MATLAB +
Octave implementation – no compiling against a C++ or C library is
involved. I agree that the current setup for GeographicLib is confusing
with one git repository serving the implementation in multiple
languages. For that reason, I’ve split the git repository into language
specific components. The octave package is
The main things I can see here are that a) you need a DESCRIPTION metadata file and a couple others, and b) the Octave source code (*.m files) that’s going to be used at run time needs to be in an inst/ subdirectory. That’s what goes on the Octave path when a package is loaded. A src/ directory in an Octave package is usually for C/C++/etc source code that’s going to be compiled into oct-files or MEX-files (binary Octave extensions which implement Octave functions in other languages), and is only used at package installation time. I’m no CMake expert, so I’m not sure what the CMakeLists.txt files are doing here: are they transforming the *.m files in some way (like to embed the package version number), or just providing “install” targets for copying all the stuff to a destination, or… ?
Thanks, these links are helpful. (I was getting lost with old
contradictory links. Can’t these be removed??)
To answer the question from @arungiridhar: what’s the overlap with the
Some functionality has been reimplemented in a more robust way, namely
solution of the direct and inverse geodesic problems. The mapping
package uses a method that fails to converge in some cases. My method
always converges and accuracy is better by a factor of about 1000. In
addition, my routines option compute the area bounded by a geodesic
quadrilateral (whose sides are the equator, two meridians, and a
geodesic). This allows the area of geodesic polygons to be computed.
Some functionality is pretty much the same (ecc2flat, flat2ecc,
computations involving geocentric and locate cartesian coordinates).
GeographicLib offers a variety of map projections. The most important
of these is the transverse Mercator projection. This is used all the
time in many geodetic applications.
The UTM/UPS and MGRS grid systems are supported.
Geoid height lookup is supported (need an exteral data file).
Calculations involving great ellipses are supported
For the most part geographiclib works equally well with prolate
ellipsoids as with oblate ones.
Browsing around the mapping package, it seems that it could use a good
spring clean. Duplicate functionality is provided e.g., in geodeticarc
and vincenty (the first is vectorizes, the second is not). The
treatment of arguments is confusing: e.g., you have to tell geodeticfwd
the units of distance but not its sister function geodeticarc.
geodeticfwd takes separate lat + lon argument. These are bundled
togethed as pt1 and pt2 in geodeticarc. geodeticarc doesn’t catch all
possible errors, so it’s possible a wildly wrong (by 20000 km) result
for the distance is returned.
The approach I suggest taking is for me to submit geographiclib as a
standalone package. Down the road we can discuss ways to consolidate
the two packages.
I do not maintain the mapping package so I cannot comment on a comparison myself. I’ll copy @PhilipN and @siko1056 for their thoughts on having two packages with a partial overlap of functionality.
Regarding documentation pages being out of date, the top of the page should have a banner saying whether the page you’re reading is current or not, and linking to the current version. That is the most viable way to work around search engines picking an old version.
@cffk Thanks for considering the creation of an Octave package
@arungiridhar I do not see any problem with potential duplication. As long as the literal package name is not “mapping”, which is already an existing package, everybody is free to add her package (e.g. “geographiclib”) whenever ready:
I have no issues at all with having another package with mapping tools. I’m all for freedom of choice - for users as well as contributors / developers.
The only thing I would be wary for is function name duplication and as a consequence, shadowing if and when users need a collection of functions distributed over two or more separate packages. That could turn into complicated issues for users and that is something I really want to avoid.
There are several more mapping packages around; e.g., m_map which has several projections options. Same for geodesy packages; several geodesic functions that have been contributed the last years by an anonymous contributor originate from other geodesy packages where they were left w/o e.g., proper docs and input validation.
As to “spring cleaning” - argh you’re stepping on my toes I’ve just made a new release. But seriously, I see & know your points but there are reasons for what the mapping pkg is now. For one, I tend to be a little forgiving for contributors and how they perceive functionality, rather than me imposing a strict vision on how a package should stick together and striving for perfect code - which is a subjective perception anyway.
Thanks for the feedback. (And I realize what a lot of work it is to maintain a big package with multiple contributors.) I’ll have a Octave package ready early next week (I need to attend to some code changes first).
I added various of the metadata files for this package and wire in my
existing tests so that
pkg test geographiclib
Question 1: I don’t see how the use accesses the INDEX file? (It
looks like this plays the role of MATLAB’s Contents.m. Is that the
right way to look at things?)
Question 2: I can’t easily figure out the oldest version of Octave that
this package works for. I’m remembering that at one time you couldn’t
add a row and a column vector (and have it expand to a matrix). If this
is the case, then the version of Octave that introduced with feature
would probably be the earliest supported.
I am able to install the package and run the tests for Octave 8 (dev version). Output below.
octave:1> pkg install https://sourceforge.net/projects/geographiclib/files/distrib-Octave/geographiclib-octave-2.0-alpha.tar.gz
For information about changes from previous versions of the geographiclib package, run 'news geographiclib'.
octave:2> pkg test geographiclib
Testing functions in package 'geographiclib':
Integrated test scripts:
.../geographiclib-2.0-alpha/geographiclib_signtest.m pass 1/1
../geographiclib-2.0-alpha/geographiclib_test.m pass 1/1
Fixed test scripts:
The content of the INDEX file can be inspected only with this command:
>> pkg describe -verbose geographiclib
This toolbox provides native MATLAB implementations of a subset of the C++ library, GeographicLib. Keycomponents of this toolbox are, geodesic, projections, grid systems, geoid lookup geometric transformations.
octave >= 4.0.0
Depended on by:
Otherwise this INDEX has little meaning and can be in general removed and will be auto-generated if you provide a categories field with any content:
The question for a package maintainer should be different: “what is the minimal Octave version you want to support”?
Every Octave user greatly appreciates the availability of packages and enjoys your development effort, even though you will not get to know most of your users and mostly only those having trouble with your work.
When you get confronted with issue reports, it is your package, and most likely only you know what to do. Thus if you plan to support an old Octave version, you should be able to set up the respective test infrastructure.
If you use Docker or Singularity on Linux, one test option for all Octave releases since 4.0.0 is