I’m interested in contributing my Mathworks package
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
minimum hassle.
Please let me know what the next steps are…
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?
Is this the main SourceForge page for your project? Or is this for the “main” C++ implementation that this is an M-code alternative to? GeographicLib download | SourceForge.net
I’d say (in a definitely-unofficial capacity) the next steps are:
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.If you want an example of how to package some M-code up for distribution as an Octave package (i.e., something the pkg command can work with), have a look at any of the existing packages on Octave Forge, or take a look at my Tablicious package as an example of how to host one on GitHub or another external site: GitHub - apjanke/octave-tablicious: Table (relational, tabular data) implementation for GNU Octave.
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
I’m still massaging this into shape and one of the reasons for the query
about making this an Octave package is that I possibly take care of any
Octave-specific requirements at this stage.
Cool. Looks like you might just need to rearrange the directory structure a bit and add a couple metadata files to turn that into a standard Octave pkg-compatible package?
Have a look at the doco here: Packages (GNU Octave), especially the “Creating Packages” topic at Creating Packages (GNU Octave).
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… ?
Sheesh; those links were to the old Octave 4.x doco. (When you google for Octave doco, it always picks up the old version.) Here’s the links to the current Octave 6.x doco:
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
mapping package?
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:
(mapping pkg maintainer here)
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.
Looking forward to see your new package.
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).
On the question of name shadowing and other compatibility issues.
I use flat2ecc and ecc2flat with the same semantics as the MATLAB and Octave mapping packages. However, I allow negative flattenings in flat2ecc.
I use the MATLAB convention of specifying the ellipsoid by
[equatorial-radius, eccentricity]
whereas the Octave convention is to replace the eccentricity by the flattening.
I’ll document these issues.
Here is the distribution directory on sourceforge
To install the “alpha” version of geographiclib-2.0, do
pkg install https://sourceforge.net/projects/geographiclib/files/distrib-Octave/geographiclib-octave-2.0-alpha.tar.gz
I added various of the metadata files for this package and wire in my
existing tests so that
pkg test geographiclib
does something.
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:
Summary:
PASS 2
FAIL 0
Same results as @arungiridhar for openSUSE 15.3 Octave 6.4.0.
The content of the INDEX file can be inspected only with this command:
>> pkg describe -verbose geographiclib
---
Package name:
geographiclib
Version:
2.0-alpha
Short description:
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.
Depends on:
octave >= 4.0.0
Depended on by:
Status:
Not loaded
---
Provides:
Geodesics
geoddistance
geodreckon
geodarea
Projections
tranmerc_fwd
tranmerc_inv
polarst_fwd
polarst_inv
eqdazim_fwd
eqdazim_inv
cassini_fwd
cassini_inv
gnomonic_fwd
gnomonic_inv
Grid systems
utmups_fwd
utmups_inv
mgrs_fwd
mgrs_inv
Geoid lookup
geoid_height
geoid_load
Geometric transformations
geocent_fwd
geocent_inv
loccart_fwd
loccart_inv
Great ellipses
gedistance
gereckon
Utility
defaultellipsoid
ecc2flat
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
see sub-section “Time travels”.
I’ve released version 2.0 of the Octave/MATLAB package GeographicLib and this now includes a packaging for Octave. User documentation is
and the Octave package is the tar.gz file available at
What’s involved in getting this package uploaded to
Thanks for your help!
Great package
The short answer: finding a new project maintainer for Octave Forge.
The long answer in this thread: Octave Packages: the new Octave Forge - #2 by arungiridhar
For the integration into Octave Packages I can assist you.
Thanks, it would be good to get geographiclib listed on Octave Packages. The package installation command is just
pkg install https://sourceforge.net/projects/geographiclib/files/distrib-Octave/geographiclib-octave-2.0.tar.gz
Let me know what the next step is? A PR on https://github.com/gnu-octave/packages?
Yes a PR on Octave Packages is the next step. For more details here:
If you have any questions, please do not hesitate to ask here or at GitHub
OK, thanks for your help. I’ll look into tackling this in a week or two.