A small, pure-python library for converting 360-decimal-degree headings (like 90.756) into human-friendly names and concepts (like 'Northeast' or 'Southeast by East').
Project description
CompassHeadingLib is 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 of mgrslib
but was separated out since there is nothing about it that is MGRS specific and because I've been dragging my feet on getting mgrslib
fully tested and loaded to PyPi for years.
CompassHeadingLib follows the worse is better design philosophy; it's better to have a slower less featureful implementation then no implementation at all. Optimizations will be executed when we have to.
License
CompassHeadingLib is licensed under the MIT License and offered as is without warranty of any kind, express or implied.
Installation
From PyPi
pip install -u compassheadinglib
From Git
Dependencies
CompassHeadingLib was specifically written to have no dependencies. The test suite uses the random
library from Python's Standard Lib.
It was originally written to run on Python 2.7 but is now only tested on Python 3.7+.
Assumptions
CompassHeadingLib currently assumes the English language. Translations and a scheme to specify language to return will be happily accepted as pull requests.
Example
Compass Object
Compass(Float heading, Int order = 3)
Compass.findHeading(Float heading, Int order = 3)
Type | Returns |
---|---|
Object(based on Dict) | Heading |
These functions take a heading between two points as a float (i.e. in decimal degrees) and returns the best matching heading with order
degree of specificity. Order
is a 1-indexed description of how specific the natural language The higher the order the more specific the heading. At an order
of 1 the decimal degree heading of 80.0 will return a heading object of 'East' while at an order
of 4 it would return 'East by North' heading object.
Internally, calling the Compass object directly will silently call it's findHeading
method.
Heading Object
Heading objects are returned by Compass objects and are not intended to be created by end users.
Type | Returns |
---|---|
Object | N/A |
Heading 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
, and order
. 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.name
Type | Returns |
---|---|
string | string |
The 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.abbr
Type | Returns |
---|---|
string | string |
The abbreviated name of this heading, along the lines of 'N' or 'SbE'
Heading.azimuth
Type | Returns |
---|---|
float | float |
The decimal degree value of this heading. For example; 'West' is 270.0 while 'North-Northeast' is 22.5
Heading.order
Type | Returns |
---|---|
integer | integer |
Order 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 the name
method
When treated as a numeric(regardless of int or float) it will return the values for the azimuth
method.
Compass Headings Reference
Heading | Abbreviation | Azimuth | Order |
---|---|---|---|
North | N | 0 | 1 |
North by East | NbE | 11.25 | 4 |
North-Northeast | NNE | 22.5 | 3 |
Northeast by North | NEbN | 33.75 | 4 |
Northeast | NE | 45 | 2 |
Northeast by East | NEbE | 56.25 | 4 |
East-Northeast | ENE | 67.5 | 3 |
East by North | EbN | 78.75 | 4 |
East | E | 90 | 1 |
East by South | EbS | 101.25 | 4 |
East-Southeast | ESE | 112.5 | 3 |
Southeast by East | SEbE | 123.75 | 4 |
Southeast | SE | 135 | 2 |
Southeast by South | SEbS | 146.25 | 4 |
South-Southeast | SSE | 157.5 | 3 |
South by East | SbE | 168.75 | 4 |
South | S | 180 | 1 |
South by West | SbW | 191.25 | 4 |
South-Southwest | SSW | 202.5 | 3 |
Southwest by South | SWbS | 213.75 | 4 |
Southwest | SW | 225 | 2 |
Southwest by West | SWbW | 236.25 | 4 |
West-Southwest | WSW | 247.5 | 3 |
West by South | WbS | 258.75 | 4 |
West | W | 270 | 1 |
West by North | WbN | 281.25 | 4 |
West-Northwest | WNW | 292.5 | 3 |
Northwest by West | NWbW | 303.75 | 4 |
Northwest | NW | 315 | 2 |
Northwest by North | NWbN | 326.25 | 4 |
North-Northwest | NNW | 337.5 | 3 |
North by West | NbW | 348.75 | 4 |
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for compassheadinglib-0.0.1-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3a27889de160921d8e8611db580a6c38f9569cb278ba573bbccc53c61880a2ec |
|
MD5 | ba49818c478792384491f07b5b1a1895 |
|
BLAKE2b-256 | f2b2801c32e0eb1d9089aee5fa05ef57584d90e0246cffec5582fd0d19d845f5 |