LatLon
======
License / Fork Information
--------------------------
::
Copyright (c) 2014-2015 Gen Del Raye
Copyright (c) 2015 Ryan Vennell
This is a derivative, forked from the original work by:
Gen Del Raye <gdelraye@hawaii.edu> and located at:
https://pypi.python.org/pypi/LatLon
Licensed under the GPLv3: http://www.gnu.org/licenses/gpl-3.0.html
The purpose of this fork is to provide full Python3 (and Python2)
support in light of the fact that the original work has no public
repository which can be contributed to or traditionally forked.
Features
--------
Methods for representing geographic coordinates (latitude and longitude) including the ability to:
* Convert lat/lon strings from almost any format into a *LatLon* object (analogous to the datetime
library's *stptime* method)
* Automatically store decimal degrees, decimal minutes, and degree, minute, second information in
a *LatLon* object
* Output lat/lon information into a formatted string (analogous to the datetime library's *strftime*
method)
* Project lat/lon coordinates into some other proj projection
* Calculate distance and heading between lat/lon pairs using either the FAI or WGS84 approximation
* Create a new *LatLon* object by offsetting an initial coordinate by a distance and heading
* Subtracting one *LatLon* object from another creates a *GeoVector* object with distance and heading
attributes (analogous to the datetime library's *timedelta* object)
* Adding or subtracting a *Latlon* object and a *GeoVector* object creates a new *LatLon* object with
the coordinates adjusted by the *GeoVector* object's distance and heading
* *GeoVector* objects can be added, subtracted, multiplied or divided
Installation
------------
*LatLon* has only been tested in Python 2.7
Installation through pip::
$ pip install LatLon23
Installation through pip::
$ pip3 install LatLon23
Requires the following non-standard libraries:
* *pyproj*
Usage Notes
-----------
Usage of *LatLon* is primarily through the class *LatLon*, which is designed to hold a single pair of
*Latitude* and *Longitude* objects. Strings can be converted to *LatLon* objects using the method
*string2latlon*, and to *Latitude* or *Longitude* objects using *string2geocoord*. Alternatively, a LatLon
object can be constructed by subtracting two *LatLon* objects, or adding or subtracting a *Latlon* object
and a *GeoVector* object.
Latitude or Longitude Construction
==================================
Latitude of longitude construction is through the classes *Latitude* and *Longitude*, respectively. You can
pass a latitude or longitude coordinate in any combination of decimal degrees, degrees and minutes, or
degrees minutes and seconds. Alternatively, you can pass a formatted string using the function *string2geocoord*
for a string containing a single latitude or longitude, or *string2latlon* for a pair of strings representing
the latitude and longitude.
String formatting:
==================
*string2latlon* and *string2geocoord* both take a *formatter* string which is loosely modeled on the *format*
keyword used in *datetime's* *strftime* function. Indicator characters (e.g. *H* or *D*) are placed between
a specific separator character (*%*) to specify the way in which a coordinate string is formatted. Possible
values are as follows:
::
*H* is a hemisphere identifier (e.g. N, S, E or W)
*D* is a coordinate in decimal degrees notation (e.g. 5.833)
*d* is a coordinate in degrees notation (e.g. 5)
*M* is a coordinate in decimal minutes notation (e.g. 54.35)
*m* is a coordinate in minutes notation (e.g. 54)
*S* is a coordinate in seconds notation (e.g. 28.93)
Any other characters (e.g. ' ' or ', ') will be treated as a separator between the above components.
All components should be separated by the *%* character. For example, if the coord_str is '5, 52,
59.88_N', the format_str would be 'd%, %m%, %S%_%H'
*Important*
===========
One format that will not currently work is one where the hemisphere identifier and a degree or decimal degree
are not separated by any characters. For example '5 52 59.88 N' is valid whereas '5 52 59.88N' is not.
String output:
==============
Both *LatLon* and *Latitude* and *Longitude* objects include a *to_string()* method for outputting a formatted
coordinate.
Projection:
===========
Use *LatLon.project* to transform geographical coordinates into a chosen projection. Requires that you pass it a
*pyproj* or *basemap* projection.
Distance and Heading Calculation:
=================================
*LatLon* objects have a *distance()* method which accepts a 2nd *LatLon* object as an argument. *distance()* will
calculate the great-circle distance between the two coordinates using the WGS84 ellipsoid by default. To use the
more approximate FAI sphere, set *ellipse* to 'sphere'. Initial and reverse headings (in degrees) can be calculated
in a similar way using the *heading_initial()* and *heading_reverse()* methods. Alternatively, subtracting one
*LatLon* object from another will return a *GeoVector* object with the attributes heading and distance.
Creating a New LatLon Object by Offset from Another One:
========================================================
Use the *offset()* method of *LatLon* objects, which takes an initial heading (in degrees) and distance (in km) to
return a new *LatLon* object at the offset coordinates. Also, you can perform the same operation by adding or
subtracting a LatLon object with a GeoVector object.
Examples
--------
Create a *LatLon* object from coordinates::
>> palmyra = LatLon(Latitude(5.8833), Longitude(-162.0833)) # Location of Palmyra Atoll in decimal degrees
>> palmyra = LatLon(5.8833, -162.0833) # Same thing but simpler!
>> palmyra = LatLon(Latitude(degree = 5, minute = 52, second = 59.88),
>> Longitude(degree = -162, minute = -4.998) # or more complicated!
>> print palmyra.to_string('d% %m% %S% %H') # Print coordinates to degree minute second
('5 52 59.88 N', '162 4 59.88 W')
Create a *Latlon* object from a formatted string::
>> palmyra = string2latlon('5 52 59.88 N', '162 4 59.88 W', 'd% %m% %S% %H')
>> print palmyra.to_string('d%_%M') # Print coordinates as degree minutes separated by underscore
('5_52.998', '-162_4.998')
Perform some calculations::
>> palmyra = LatLon(Latitude(5.8833), Longitude(-162.0833)) # Location of Palmyra Atoll
>> honolulu = LatLon(Latitude(21.3), Longitude(-157.8167)) # Location of Honolulu, HI
>> distance = palmyra.distance(honolulu) # WGS84 distance in km
>> print distance
1766.69130376
>> print palmyra.distance(honolulu, ellipse = 'sphere') # FAI distance in km
1774.77188181
>> initial_heading = palmyra.heading_initial(honolulu) # Heading from Palmyra to Honolulu on WGS84 ellipsoid
>> print initial_heading
14.6907922022
>> hnl = palmyra.offset(initial_heading, distance) # Reconstruct Honolulu based on offset from Palmyra
>> print hnl.to_string('D') # Coordinates of Honolulu
('21.3', '-157.8167')
Manipulate *LatLon* objects using *GeoVectors*::
>> vector = (honolulu - palmyra) * 2 # A GeoVector with 2x the magnitude of a vector from palmyra to honolulu
>> print vector # Print heading and magnitude
14.6907922022 3533.38260751
print palmyra + (vector/2.0) # Recreate the coordinates of Honolulu by adding half of vector to palmyra
21.3, -157.8167
Version
-------
Changelog
=========
**1.0.7 (MARCH/29/2015)**
* Forked from original work: https://pypi.python.org/pypi/LatLon
* Added Python3 support and refactored a bit of the code
* Updated Readme to correct issues and provide proper attribution
* Adding MANIFEST.in
Raw data
{
"_id": null,
"home_page": "https://github.com/hickeroar/LatLon23",
"name": "LatLon23",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "latitude,longitude,decimal degrees,degree minutes,distance",
"author": "Ryan Vennell",
"author_email": "ryan.vennell@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/39/db/fc3b19993095c19eea84793ebb3bcbe3706c693c107f6b49b2ea3d025514/LatLon23-1.0.7.tar.gz",
"platform": "UNKNOWN",
"description": "LatLon\n======\n\nLicense / Fork Information\n--------------------------\n\n::\n\n Copyright (c) 2014-2015 Gen Del Raye\n Copyright (c) 2015 Ryan Vennell\n\n This is a derivative, forked from the original work by:\n Gen Del Raye <gdelraye@hawaii.edu> and located at:\n https://pypi.python.org/pypi/LatLon\n\n Licensed under the GPLv3: http://www.gnu.org/licenses/gpl-3.0.html\n\n The purpose of this fork is to provide full Python3 (and Python2)\n support in light of the fact that the original work has no public\n repository which can be contributed to or traditionally forked.\n\nFeatures\n--------\nMethods for representing geographic coordinates (latitude and longitude) including the ability to:\n\n * Convert lat/lon strings from almost any format into a *LatLon* object (analogous to the datetime\n library's *stptime* method)\n * Automatically store decimal degrees, decimal minutes, and degree, minute, second information in\n a *LatLon* object\n * Output lat/lon information into a formatted string (analogous to the datetime library's *strftime*\n method)\n * Project lat/lon coordinates into some other proj projection\n * Calculate distance and heading between lat/lon pairs using either the FAI or WGS84 approximation\n * Create a new *LatLon* object by offsetting an initial coordinate by a distance and heading\n * Subtracting one *LatLon* object from another creates a *GeoVector* object with distance and heading\n attributes (analogous to the datetime library's *timedelta* object)\n * Adding or subtracting a *Latlon* object and a *GeoVector* object creates a new *LatLon* object with\n the coordinates adjusted by the *GeoVector* object's distance and heading\n * *GeoVector* objects can be added, subtracted, multiplied or divided\n\nInstallation\n------------\n*LatLon* has only been tested in Python 2.7\n\nInstallation through pip::\n\n $ pip install LatLon23\n\nInstallation through pip::\n\n $ pip3 install LatLon23\n\nRequires the following non-standard libraries:\n\n * *pyproj*\n\nUsage Notes\n-----------\nUsage of *LatLon* is primarily through the class *LatLon*, which is designed to hold a single pair of\n*Latitude* and *Longitude* objects. Strings can be converted to *LatLon* objects using the method\n*string2latlon*, and to *Latitude* or *Longitude* objects using *string2geocoord*. Alternatively, a LatLon\nobject can be constructed by subtracting two *LatLon* objects, or adding or subtracting a *Latlon* object\nand a *GeoVector* object.\n\nLatitude or Longitude Construction\n==================================\nLatitude of longitude construction is through the classes *Latitude* and *Longitude*, respectively. You can\npass a latitude or longitude coordinate in any combination of decimal degrees, degrees and minutes, or\ndegrees minutes and seconds. Alternatively, you can pass a formatted string using the function *string2geocoord*\nfor a string containing a single latitude or longitude, or *string2latlon* for a pair of strings representing\nthe latitude and longitude.\n\nString formatting:\n==================\n*string2latlon* and *string2geocoord* both take a *formatter* string which is loosely modeled on the *format*\nkeyword used in *datetime's* *strftime* function. Indicator characters (e.g. *H* or *D*) are placed between\na specific separator character (*%*) to specify the way in which a coordinate string is formatted. Possible\nvalues are as follows:\n\n::\n\n *H* is a hemisphere identifier (e.g. N, S, E or W)\n\n *D* is a coordinate in decimal degrees notation (e.g. 5.833)\n\n *d* is a coordinate in degrees notation (e.g. 5)\n\n *M* is a coordinate in decimal minutes notation (e.g. 54.35)\n\n *m* is a coordinate in minutes notation (e.g. 54)\n\n *S* is a coordinate in seconds notation (e.g. 28.93)\n\n Any other characters (e.g. ' ' or ', ') will be treated as a separator between the above components.\n\n All components should be separated by the *%* character. For example, if the coord_str is '5, 52,\n 59.88_N', the format_str would be 'd%, %m%, %S%_%H'\n\n*Important*\n===========\nOne format that will not currently work is one where the hemisphere identifier and a degree or decimal degree\nare not separated by any characters. For example '5 52 59.88 N' is valid whereas '5 52 59.88N' is not.\n\nString output:\n==============\nBoth *LatLon* and *Latitude* and *Longitude* objects include a *to_string()* method for outputting a formatted\ncoordinate.\n\nProjection:\n===========\nUse *LatLon.project* to transform geographical coordinates into a chosen projection. Requires that you pass it a\n*pyproj* or *basemap* projection.\n\nDistance and Heading Calculation:\n=================================\n*LatLon* objects have a *distance()* method which accepts a 2nd *LatLon* object as an argument. *distance()* will\ncalculate the great-circle distance between the two coordinates using the WGS84 ellipsoid by default. To use the\nmore approximate FAI sphere, set *ellipse* to 'sphere'. Initial and reverse headings (in degrees) can be calculated\nin a similar way using the *heading_initial()* and *heading_reverse()* methods. Alternatively, subtracting one\n*LatLon* object from another will return a *GeoVector* object with the attributes heading and distance.\n\nCreating a New LatLon Object by Offset from Another One:\n========================================================\nUse the *offset()* method of *LatLon* objects, which takes an initial heading (in degrees) and distance (in km) to\nreturn a new *LatLon* object at the offset coordinates. Also, you can perform the same operation by adding or\nsubtracting a LatLon object with a GeoVector object.\n\nExamples\n--------\nCreate a *LatLon* object from coordinates::\n\n >> palmyra = LatLon(Latitude(5.8833), Longitude(-162.0833)) # Location of Palmyra Atoll in decimal degrees\n >> palmyra = LatLon(5.8833, -162.0833) # Same thing but simpler!\n >> palmyra = LatLon(Latitude(degree = 5, minute = 52, second = 59.88),\n >> Longitude(degree = -162, minute = -4.998) # or more complicated!\n >> print palmyra.to_string('d% %m% %S% %H') # Print coordinates to degree minute second\n ('5 52 59.88 N', '162 4 59.88 W')\n\nCreate a *Latlon* object from a formatted string::\n\n >> palmyra = string2latlon('5 52 59.88 N', '162 4 59.88 W', 'd% %m% %S% %H')\n >> print palmyra.to_string('d%_%M') # Print coordinates as degree minutes separated by underscore\n ('5_52.998', '-162_4.998')\n\nPerform some calculations::\n\n >> palmyra = LatLon(Latitude(5.8833), Longitude(-162.0833)) # Location of Palmyra Atoll\n >> honolulu = LatLon(Latitude(21.3), Longitude(-157.8167)) # Location of Honolulu, HI\n >> distance = palmyra.distance(honolulu) # WGS84 distance in km\n >> print distance\n 1766.69130376\n >> print palmyra.distance(honolulu, ellipse = 'sphere') # FAI distance in km\n 1774.77188181\n >> initial_heading = palmyra.heading_initial(honolulu) # Heading from Palmyra to Honolulu on WGS84 ellipsoid\n >> print initial_heading\n 14.6907922022\n >> hnl = palmyra.offset(initial_heading, distance) # Reconstruct Honolulu based on offset from Palmyra\n >> print hnl.to_string('D') # Coordinates of Honolulu\n ('21.3', '-157.8167')\n\nManipulate *LatLon* objects using *GeoVectors*::\n\n >> vector = (honolulu - palmyra) * 2 # A GeoVector with 2x the magnitude of a vector from palmyra to honolulu\n >> print vector # Print heading and magnitude\n 14.6907922022 3533.38260751\n print palmyra + (vector/2.0) # Recreate the coordinates of Honolulu by adding half of vector to palmyra\n 21.3, -157.8167\n\nVersion\n-------\n\nChangelog\n=========\n**1.0.7 (MARCH/29/2015)**\n\n * Forked from original work: https://pypi.python.org/pypi/LatLon\n * Added Python3 support and refactored a bit of the code\n * Updated Readme to correct issues and provide proper attribution\n * Adding MANIFEST.in",
"bugtrack_url": null,
"license": "UNKNOWN",
"summary": "Methods for representing geographic coordinates",
"version": "1.0.7",
"project_urls": {
"Download": "UNKNOWN",
"Homepage": "https://github.com/hickeroar/LatLon23"
},
"split_keywords": [
"latitude",
"longitude",
"decimal degrees",
"degree minutes",
"distance"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "39dbfc3b19993095c19eea84793ebb3bcbe3706c693c107f6b49b2ea3d025514",
"md5": "ae837592d31bf867bac3340193dd508f",
"sha256": "e0ea06eda0ac1dab658fec89ee158c5221948cf147e38724fe50dfbd8a1ff340"
},
"downloads": -1,
"filename": "LatLon23-1.0.7.tar.gz",
"has_sig": false,
"md5_digest": "ae837592d31bf867bac3340193dd508f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 25136,
"upload_time": "2015-03-29T18:09:04",
"upload_time_iso_8601": "2015-03-29T18:09:04.960611Z",
"url": "https://files.pythonhosted.org/packages/39/db/fc3b19993095c19eea84793ebb3bcbe3706c693c107f6b49b2ea3d025514/LatLon23-1.0.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2015-03-29 18:09:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hickeroar",
"github_project": "LatLon23",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "latlon23"
}
JSON
