Package: compassheadinglib
CompassHeadingLibis a small, dependency-free, pure python library for working with compass headings in terms of comparison and transformation between decimal degree and natural language space. It was originally written as a part ofmgrslibbut was separated out since there is nothing about it that is MGRS specific and because I've been dragging my feet on gettingmgrslibfully tested and loaded to PyPi foryears.CompassHeadingLibfollows theworse is betterdesign philosophy; it's better to have a slower less featureful implementation then no implementation at all. Optimizations will be executed when we have to.LicenseCompassHeadingLibis licensed under the MIT License and offered as is without warranty of any kind, express or implied.InstallationFrom PyPipip install -u compassheadinglibFrom GitDependenciesCompassHeadingLibwas specifically written to have no dependencies. The test suite uses therandomlibrary from Python's Standard Lib.
It was originally written to run on Python 2.7 but is now only tested on Python 3.7+.AssumptionsCompassHeadingLibcurrently assumes the English language. Translations and a scheme to specify language to return will be happily accepted as pull requests.ExampleCompass ObjectCompass(Floatheading, Intorder= 3)Compass.findHeading(Floatheading, Intorder= 3)TypeReturnsObject(based on Dict)HeadingThese functions take a heading between two points as a float (i.e. in decimal degrees) and returns the best matching heading withorderdegree of specificity.Orderis a 1-indexed description of how specific the natural language The higher the order the more specific the heading. At anorderof 1 the decimal degree heading of 80.0 will return a heading object of 'East' while at anorderof 4 it would return 'East by North' heading object.Internally, calling the Compass object directly will silently call it'sfindHeadingmethod.Heading ObjectHeading objects are returned by Compass objects and are not intended to be created by end users.TypeReturnsObjectN/AHeading objects are containers for information about headings that are designed to be comparable to each other (and other python objects) using built-in methods. There are four pieces of information for each heading, each a method of the object:name,abbr,azimuth, andorder. The various built-in comparisons look to different methods (and thus different pieces of the information) as appropriate. For the most part you can safely ignore all this background stuff.Heading.nameTypeReturnsstringstringThe full name of this heading, along the lines of 'North' or 'South by East'.
Note: despite what the festival has told you there is no such heading as 'South by Southwest'.Heading.abbrTypeReturnsstringstringThe abbreviated name of this heading, along the lines of 'N' or 'SbE'Heading.azimuthTypeReturnsfloatfloatThe decimal degree value of this heading. For example; 'West' is 270.0 while 'North-Northeast' is 22.5Heading.orderTypeReturnsintegerintegerOrder defines how specific the heading is. The cardinal directions ('North', 'East', 'South' & 'West') are of order 1 while 'South by East' is order 4. The Compass Headings Reference chart at the end of this document will be more illustrative of this difference.
Put another way: order 1 headings are 90° apart, order 2 headings are 45° apart, order 3 headings are 22.5° apart, and order 4 headings are 11.25° apart. By default this library uses order 3 where ever that value can be specified. Each order includes the headings of that order and all headings of any lower valued orders. Hence order 2 includes all headings labeled order 2 and order 1.When treated as a string the Heading object returns the value for thenamemethod
When treated as a numeric(regardless of int or float) it will return the values for theazimuthmethod.Compass Headings ReferenceHeadingAbbreviationAzimuthOrderNorthN01North by EastNbE11.254North-NortheastNNE22.53Northeast by NorthNEbN33.754NortheastNE452Northeast by EastNEbE56.254East-NortheastENE67.53East by NorthEbN78.754EastE901East by SouthEbS101.254East-SoutheastESE112.53Southeast by EastSEbE123.754SoutheastSE1352Southeast by SouthSEbS146.254South-SoutheastSSE157.53South by EastSbE168.754SouthS1801South by WestSbW191.254South-SouthwestSSW202.53Southwest by SouthSWbS213.754SouthwestSW2252Southwest by WestSWbW236.254West-SouthwestWSW247.53West by SouthWbS258.754WestW2701West by NorthWbN281.254West-NorthwestWNW292.53Northwest by WestNWbW303.754NorthwestNW3152Northwest by NorthNWbN326.254North-NorthwestNNW337.53North by WestNbW348.754