My suggestion is Geo::MagneticVariation or Geo::MagneticAngle. Geo, because that top level exists and contains many related modules; the rest because those are what the Ordnance Survey -- reputedly the best map makers in the world -- call it.

Thank you. I especially appreciate the research put in, and the references supplied.

While Magnetic::Declinationnicely names the module on its own merits, does it fit into a family of otherly-named modules related to positioning or mapping?

Thanks! (real kudos most definitely goes to no_slogan without saying though).

At first, before I got to really play with the code (and I fully admit that the math is so far beyond my comprehension that I can't even describe), I threw the name Magnetic::Declination quickly into the mix with the time I had so I could create a home to build from.

Honestly, it doesn't really fit imho, as it defeats the top level naming structure of the CPAN for not joining into existing which morgon said, along with his statement that "Declination" doesn't fit either because the distribution will provide two functions (inclination as well as declination).

I have not really specifically looked through the CPAN for where it could go. That's why I threw this question here. I'll re-visit this tomorrow, and before I review any further responses, I'll parse the CPAN namespace for top-level names, and we'll all go from there.

Now, since Geo is an existing top level domain, I think Geo::MagneticDeclination would also be very good.

I think magnetic declination is better than magnetic variation (although they mean the same), because it's more clearly a technical term not subject to misunderstandings (variation may be construed as something that varies, or so). (See also https://en.wikipedia.org/wiki/Magnetic_declination.)

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]

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!

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...

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.

And you say that it also calculates inclication, so "Declination" seems to be too specific.

So I'd go with something like "Navigation::Compass" or the like (unless already taken).

I really like your thoughts here, but I personally think that Navigation::Compass is too broad...

This module deals exclusively and deliberately with the magnetic *offsets* that don't align with the true north grid, and realistically doesn't have anything to do with a compass, less a fractional angle that deviates from what perhaps a different module may provide.

What this module does, is spits out a directional difference between true north and magnetic north (as well as inclination deviations, but I digress) that can be applied to a compass heading to ensure when traveling, no matter where you are, the direction that is output is the direction you're supposed to be heading regardless of location.

So, a GPS software says you're to head in X.AB direction per grid north, and this software calculates the magnetic deviation from that. It would be up to the end user to combine these two numbers (addition, essentially) to understand the real magnetic direction they need to travel, which may become X.BC for example. Without the original direction (outside of this module's scope), this module doesn't do anything but produce the deviation itself.

Geo::MagneticDeviation or Geo::Magnetic::Deviation, perhaps? Or Geo::Navigation::Magnetic(::)Deviation

Heading off for the night, but my vote so far is Geo::MagneticVariation as suggested by BrowserUK. He provided a decent amount of reference material in this node that is very informative. I learned a lot from it, including the ways I (mis)use certain terminology.