Package: great-circle-calculator
Great Circle CalculatorThis is a collection of equations and formulas that I've been using across my many projects to compute various distances using great circle calculations. The formulas here were adapted into python fromhereandhere.Because I've been using these equations across several projects, I decided to upload this to PyPI for ease of keeping updated and distribution. Feel free to clone, fork, or modify the code as needed.  I believe there are more robust packages out there.  One example isgeodesy.Any questions, feel free to get in touch.How to installClone/download the package to your project or usepip install great-circle-calculator(PyPI)How to useThe convention of this package is for the spatial points to be represented as a tuple of length 2 with longitude being the first element and latitude being the second element, i.e.(lon, lat).Here is an outline of the functions available to you.Librarygreat_circle_calculatorDepending on my needs, I will either import this library asimportgreat_circle_calculator.great_circle_calculatorasgccorfromgreat_circle_calculator.great_circle_calculatorimport*where * can be a specific function (or left as * for all the functions)The functions aredistance_between_points,bearing_at_p1,bearing_at_p2,midpoint,intermediate_point,point_given_start_and_bearingFunctiondistance_between_points()Functiondistance_between_points(p1, p2, unit='meters', haversine=True)computes the distance between two points in the unit given in the unit parameter.  It will calculate the distance using the law of cosines unless the user specifieshaversineto betrue.p1andp2are points (i.e. tuples, lists of length 2) in the form of (lon, lat) in decimal degrees (That is, a tuple of float values, the library cannot handle DMS data).unitis a unit of measurement that can be accessed bygreat_circle_calculator.constants.eligible_units, default is'meters'.haversine=Trueuses thehaversineformula, which is consideered superior for short distances (which is my often use case).  Changing it tohaversine=Falseyeilds thelaw of cosineswhich, typically, will have a quicker computational time.Functionbearing_at_p1()Functionbearing_at_p1(p1, p2)computes the bearing (i.e. course) at p1 given a destination of p2.  Use in conjunction withmidpoint()andintermediate_point()to find the course along the route.  Usebearing_at_p2()to find the bearing at the endpoint,p2.p1andp2are points (i.e. tuples, lists of length 2) in the form of (lon, lat) in decimal degrees.Example to find a course enroute:importgreat_circle_calculator.great_circle_calculatorasgcc""" This code snippit will find the the course at a point p3 which is 20% the way between points p1 and p2"""p1,p2=(lon1,lat1),(lon2,lat2)frac_along_route=0.2course_enroute=gcc.bearing_at_p1(gcc.intermediate_point(p1,p2,frac_along_route),p2)Functionbearing_at_p2Functionbearing_at_p2(p1, p2)computes the bearing (i.e. course) at p2 given a start of p1.  Use in conjunction withmidpoint()andintermediate_point()to find the course along the route.  Usebearing_at_p1()to find the bearing at the starting point,p1.p1andp2are points (i.e. tuples, lists of length 2) in the form of (lon, lat) in decimal degrees.Functionmidpoint()Functionmidpoint(p1, p2)is the half-way point along a great circle path between the two points.p1andp2are points (i.e. tuples, lists of length 2) in the form of (lon, lat) in decimal degrees.  For example, sayp3 = midpoint(p1, p2),distance_between_points(p1, p3) == distance_between_points(p2, p3)Functionintermediate_point()Function intermediate_point(p1, p2, fraction=0.5) an intermediate point along the course laid out byp1top2given the fractional distance.fractionis the fraction of the distance betweenp1andp2, where 0 isp1, 0.5 is equivalent tomidpoint(), and 1 isp2.Functionpoint_given_start_and_bearing()Function point_given_start_and_bearing(p1, course, distance, unit='meters') is given a start pointp1, initial bearingcourse, and distancedistance, this will calculate the destination point bearing travelling along a (shortest distance) great circle arc.unitis a unit of measurement that can be accessed bygreat_circle_calculator.constants.eligible_units, default is'meters'.LibrarycompassThis libaray was created to let me call, sayCompass.eastso I can get 90deg.  I thought it helped with code readability at first, kept it because it might be useful...It has two classes calledCompassSimpleandCompassComplex.CompassComplexis still in the todo list but it contains more information about each compass point.To see the eligble points, seehere.  Simply use the terms in "Compass point", use lower case and underscores where there are spaces or dashes.  Alternatively you may use the "Abbreviation" with the appropriate case to call the same value.To useCompassSimple:importgreat_circle_calculator.CompassSimpleascompassprint(compass.east)# prints 90print(compass.north)# prints 0print(compass.northwest_by_north)# prints 326.250print(compass.SEbE)# Southeast by east, prints 123.750print(compass.SWbS==compass.southwest_by_south)# prints TrueLibrary_constantsThis was created for two purposes:To easily store the radius of the earth in various unitsTo simplify the code in the program so I don't have to callmath.*each time I want sin, cos, etc.To see the available units, call_constants.eligible_unitsand a list of the units that are available will be given.eligible_unitsTo see the available units, call_constants.eligible_unitsand a list of the units that are available will be given.Libraries__conversionand__error_checkingPrivate libraries that convert (__conversion.py) values between radians and degrees as the default option for python's math package is radians.Updated for V1.3.0!The error checking library (__error_checking.py) is used to ensure that the points passed to through the code make sense in the project.  That is, it checks two things.  First, that the point passed to the function is atupleof length 2. If this check fails, aTypeErroris thrown.  The second is that the information contained within the tuple matches the expected range of latitude and longitude. The first element of thetupleshould be the longitude in the range of [-180, 180] and the second element is the latitude in the range of [-90, 90].  If this check fails, but it appears that the user has "flipped" the elements of the point (i.e. (lat, lon) is provided), aValueErroris thrown with information indicating the belief you have flipped the elements of the coordinates.  If this is not true,ValueErroris thrown with a different error message indicating the expected input.Danger ZoneThe function_error_check_point(point, correct_point=False)takes a second argument that I have intentionally made very inaccessible from the PyPI package.  If you would like the program to automatically correct a point it thinks is backwards, clone the package into your program and set this parameter toTrue.And finally...Package last updated Feb 7, 2023.  Readme last updated Feb 7, 2023.Change Log1.3.1 - Put in a line of code when computing the haversine distance to ensure that (due to floating point errors) may be above 11.3.0 - Updated the code in the__error_checking.pyfile to, by default, throw errors rather than try to correct points. Also expanded the error messages here to be more clear.1.2.0 - If the user sends a point that isdecimaldata type, it will convert to a tuple offloattypes.  Updated the readme for clarity1.1.0 - Changedhaversine=Trueas the default fordistance_between_pointsas it more accurately reflects the small distance calculation I am using in my projects.1.0.2 - squished an error in the intermediate function. The number of errors has been embarrassing. I hope you won't judge me too harshly.1.0.1.post1 - includes a domain checker forasin()andacos()because rounding errors can cause the function to be out of range.1.0.post1 - I screwed up the numbering order, still new at this... please ignore.1.0.1 - Fixed an error in the (point_given_start_and_bearing)[#point_given_start_and_bearing]1.0.0 - First Edition, inital commit, etc.