in reply to CPAN distribution naming recommendations

Hi Stevieb

1) Your code is only relevant for users of a magnetic compass. There is already Geo::Compass::Bearing and Geo::Compass::Points.

2) While it's true that the terms "Magnetic Declination" and "Magnetic Variation" are interchangeable, *and* that both Wikipedia and NOAA use the former, I can tell you as a 15-yr licensed sea captain that the term "Magnetic Variation" is far more widely used in my experience.

Furthermore, as you may know, there is a second element that must be considered when plotting a course using a magnetic compass, which is "Magnetic Deviation." Since "Deviation" and "Declination" are such similar words, I'd say that speaks to "Variation" as a better choice. This is particularly true when you consider the ancient formula for calculating magnetic compass course by hand from the true course, which is (I swear) taught with the mnemonic "True Virgins Make Dull Companions": 

T     +   V          =  M         +  D          =  C
True  +   Variation  =  Magnetic  +  Deviation  =  Compass

[download]
As you can see using "Declination" rather than "Variation" would break the mnemonic that's been used ever since the glory days of the British Navy.

I therefore suggest that the best name for the module would be: Geo::Compass::Variation.

(In a perfect world the namespace would be 'Geo::Compass::Magnetic::*' but now that there are already modules for Bearing and Points I think that the "magnetic" is implied.)

Note: I realize that hikers rarely have to deal with compass deviation, as do pilots and mariners, but this module should be useful for all navigators.

Bonus: A second mnemonic for working with compass vs. true course is "West is Best, East is Least" -- which should remind you that you add the variation in the west and subtract it in the east).

Hope this helps!


The way forward always starts with a minimal test.

Replies are listed 'Best First'.
Re^2: CPAN distribution naming recommendations
by stevieb (Canon) on Jun 03, 2017 at 22:48 UTC

    Thanks for the feedback Nick!

    I have to admit that although I've been very proficient at land orienteering most of my life, many of the equations and subtleties I did not understand. As far as variations, I've always been able to calculate that into things using my (to this day) WWII field compass and my topo maps, but doing the math to apply the variations in a digital playground have been very interesting, and I have learned a boatload of new ways to comprehend things.

    The project this is all for is coming along nicely. I have put on the CPAN some GPS-related code already, I'll be uploading this once a name is decided (in fact, I added a series of checks/bounds and tests today, so I'm ready to go) by the original author of the code. If they don't respond by Monday morning, I'll have to choose one. Once I'm done with the Arduino stuff and get this little project packaged, I'm going to port it ALL back to Perl to mix in with my Raspberry Pi work. Although the Pi isn't as field-friendly as an Arduino Trinket, there may still be some use for all of it bundled in a specific grouping of modules, but even if not, everything I've learned started as Perl, and the people in the Perl community, so it's the right thing to do.

    I like your suggestion of Geo::Compass::Variation. It totally fits the bill for the two simple functions the software provides without leaning directly at one of them, and I personally prefer to have only one capital letter in each section of a namespace if possible... it keeps it clean and unambiguous.

    update 2004 hrs EST: Being a land person most of my life and being able to use that knowledge to get from one place in water to the next land area is something I can do in a small scale, I presume that if all the code I'm writing that I'll port back works accurately (Google Compass has been as handy as my physical layout of maps/compass on my living room floor to assume accuracy), I would imagine on a boat/ship with electrical, a Pi, running Perl code could be useful in such situations. It doesn't need to be field light and portable if it's being used in a case that you're not considering weight and size because you're not on foot...

[reply]
[d/l]

      Geo::Compass::Variation works for me, though I suspect that term is more common in the nautical world.

      One technical comment on your code is that it makes more sense for _calculate to return the X,Y,Z magnetic field components and leave the atan2 fiddling to mag_dec and mag_inc. (Maybe mag_dec should have an alias, mag_var.) Since someone might find an interesting use for that information, you might rename _calculate to mag_field and document it as a part of the interface.

      BTW, the technical report has some test data you could use in your module tests.

[reply]

        Thanks no_slogan!

        I'll be out most of the day, so I'll take a look at your recommendations either tonight or tomorrow and get them implemented.

[reply]

In Section Seekers of Perl Wisdom