Package upoints :: Module point :: Class Point
[hide private]
[frames] | no frames]

Class Point

object --+
         |
        Point
Known Subclasses:

Simple class for representing a location on a sphere

Since: 0.2.0

Instance Methods [hide private]
 
__init__(self, latitude, longitude, units='metric', angle='degrees', timezone=0)
Initialise a new Point object
 
_set_location(self, ltype, value)
Check supplied location data for validity, and update
dict
__dict__(self)
Emulate __dict__ class attribute for class
str
__repr__(self)
Self-documenting string representation
str
__str__(self, mode='dd')
Pretty printed location string
str
__unicode__(self, mode='dd')
Pretty printed Unicode location string
bool
__eq__(self, other, accuracy=None)
Compare Point objects for equality with optional accuracy amount
bool
__ne__(self, other, accuracy=None)
Compare Point objects for inequality with optional accuracy amount
int
__hash__(self)
Produce an object hash for equality checks
str
to_grid_locator(self, precision='square')
Calculate Maidenhead locator from latitude and longitude
float
distance(self, other, method='haversine')
Calculate the distance from self to other
float
bearing(self, other, format='numeric')
Calculate the initial bearing from self to other
Point instance
midpoint(self, other)
Calculate the midpoint from self to other
float
final_bearing(self, other, format='numeric')
Calculate the final bearing from self to other
Point
destination(self, bearing, distance)
Calculate the destination from self given bearing and distance
datetime.datetime
sunrise(self, date=None, zenith=None)
Calculate the sunrise time for a Point object
datetime.datetime
sunset(self, date=None, zenith=None)
Calculate the sunset time for a Point object
tuple of datetime.datetime
sun_events(self, date=None, zenith=None)
Calculate the sunrise time for a Point object
tuple of float objects
inverse(self, other)
Calculate the inverse geodesic from self to other
Point
forward(self, bearing, distance)
Calculate the destination from self given bearing and distance

Inherited from object: __delattr__, __getattribute__, __new__, __reduce__, __reduce_ex__, __setattr__

Instance Variables [hide private]
  latitude
Location's latitude
  longitude
Locations's longitude
  rad_latitude
Location's latitude in radians
  rad_longitude
Location's longitude in radians
  timezone
Location's offset from UTC in minutes
  units
Type of distance units to be used
Properties [hide private]
  _angle
  _latitude
  _longitude
  _rad_latitude
  _rad_longitude

Inherited from object: __class__

Method Details [hide private]

__init__(self, latitude, longitude, units='metric', angle='degrees', timezone=0)
(Constructor)

 

Initialise a new Point object

>>> Home = Point(52.015, -0.221)
>>> Home = Point(52.015, -0.221, timezone=60) # BST
>>> Home = Point(52.015, -0.221, "US customary")
>>> Home = Point(52.015, -0.221, "nautical")
>>> test = Point(math.pi / 4, math.pi / 2, angle="radians")
>>> test.latitude == 45
True
>>> test.longitude == 90
True
>>> test = Point((50, 20, 10), (-1, -3, -12))
>>> "%.3f" % test.latitude
'50.336'
>>> "%.3f" % test.longitude
'-1.053'
>>> bad_angle = Point(52.015, -0.221, angle=None)
Traceback (most recent call last):
...
ValueError: Unknown angle type `None'
>>> bad_latitude = Point(-92, -0.221)
Traceback (most recent call last):
...
ValueError: Invalid latitude value `-92.000000'
>>> bad_longitude = Point(52.015, 185)
Traceback (most recent call last):
...
ValueError: Invalid longitude value `185.000000'
>>> bad_units = Point(52.015, -0.221, units=None)
Traceback (most recent call last):
...
ValueError: Unknown units type `None'
Parameters:
  • latitude (float or coercible to float, tuple or list) - Location's latitude
  • longitude (float or coercible to float, tuple or list) - Location's longitude
  • angle (str) - Type for specified angles
  • units (str) - Units type to be used for distances
  • timezone (int) - Offset from UTC in minutes
Raises:
  • ValueError - Unknown value for angle
  • ValueError - Unknown value for units
  • ValueError - Invalid value for latitude or longitude
Overrides: object.__init__

__dict__(self)

 

Emulate __dict__ class attribute for class

>>> Home = Point(52.015, -0.221)
>>> sorted(Home.__dict__.items())
[('_angle', 'degrees'), ('_latitude', 52.015000000000001),
 ('_longitude', -0.221), ('_rad_latitude', 0.90783301042485054),
 ('_rad_longitude', -0.0038571776469074684), ('timezone', 0),
 ('units', 'metric')]
>>> class Test(Point):
...     __slots__ = ("TEST", )
...     def __init__(self, latitude, longitude):
...         super(Test, self).__init__(latitude, longitude)
...         self.TEST = "tested"
>>> a = Test(52.015, -0.221)
>>> sorted(a.__dict__.items())
[('TEST', 'tested'), ('_angle', 'degrees'),
 ('_latitude', 52.015000000000001), ('_longitude', -0.221),
 ('_rad_latitude', 0.90783301042485054),
 ('_rad_longitude', -0.0038571776469074684), ('timezone', 0),
 ('units', 'metric')]
Returns: dict
Object attributes, as would be provided by a class that didn't set __slots__
Decorators:
  • @property

__repr__(self)
(Representation operator)

 

Self-documenting string representation

>>> Point(52.015, -0.221)
Point(52.015, -0.221, 'metric', 'degrees', 0)
Returns: str
String to recreate Point object
Overrides: object.__repr__

__str__(self, mode='dd')
(Informal representation operator)

 

Pretty printed location string

>>> print(Point(52.015, -0.221))
N52.015°; W000.221°
>>> print(Point(52.015, -0.221).__str__(mode="dm"))
52°00.90'N, 000°13.26'W
>>> print(Point(52.015, -0.221).__str__(mode="dms"))
52°00'54"N, 000°13'15"W
>>> print(Point(33.9400, -118.4000).__str__(mode="dms"))
33°56'23"N, 118°24'00"W
>>> print(Point(52.015, -0.221).__str__(mode="locator"))
IO92
Parameters:
  • mode (str) - Coordinate formatting system to use
Returns: str
Human readable string representation of Point object
Raises:
  • ValueError - Unknown value for mode
Overrides: object.__str__

__unicode__(self, mode='dd')

 

Pretty printed Unicode location string

>>> print(Point(52.015, -0.221))
N52.015°; W000.221°
>>> print(Point(52.015, -0.221).__unicode__(mode="dm"))
52°00.90′N, 000°13.26′W
>>> print(Point(52.015, -0.221).__unicode__(mode="dms"))
52°00′54″N, 000°13′15″W
>>> print(Point(33.9400, -118.4000).__unicode__(mode="dms"))
33°56′23″N, 118°24′00″W
>>> print(Point(52.015, -0.221).__unicode__(mode="locator"))
IO92
Parameters:
  • mode (str) - Coordinate formatting system to use
Returns: str
Human readable Unicode representation of Point object
Raises:
  • ValueError - Unknown value for mode

__eq__(self, other, accuracy=None)
(Equality operator)

 

Compare Point objects for equality with optional accuracy amount

>>> Point(52.015, -0.221) == Point(52.015, -0.221)
True
>>> Point(52.015, -0.221) == Point(52.6333, -2.5)
False
>>> Point(52.015, -0.221).__eq__(Point(52.6333, -2.5), 168)
False
>>> Point(52.015, -0.221).__eq__(Point(52.6333, -2.5), 170)
True
Parameters:
  • other (Point instance) - Object to test for equality against
  • accuracy (float or None) - Objects are considered equal if within accuracy units distance of each other
Returns: bool
True if objects are equal

__ne__(self, other, accuracy=None)

 

Compare Point objects for inequality with optional accuracy amount

>>> Point(52.015, -0.221) != Point(52.015, -0.221)
False
>>> Point(52.015, -0.221) != Point(52.6333, -2.5)
True
>>> Point(52.015, -0.221).__ne__(Point(52.6333, -2.5), 168)
True
>>> Point(52.015, -0.221).__ne__(Point(52.6333, -2.5), 170)
False
Parameters:
  • other (Point instance) - Object to test for inequality against
  • accuracy (float or None) -
    Objects are considered equal if within accuracy
    units distance
Returns: bool
True if objects are not equal

__hash__(self)
(Hashing function)

 

Produce an object hash for equality checks

This method returns the hash of the return value from the __str__ method. It guarantees equality for objects that have the same latitude and longitude.

Returns: int
Hash of string representation
Overrides: object.__hash__

See Also: __str__

to_grid_locator(self, precision='square')

 

Calculate Maidenhead locator from latitude and longitude

>>> Home = Point(52.015, -0.221)
>>> Home.to_grid_locator("extsquare")
'IO92va33'
>>> Home.to_grid_locator("subsquare")
'IO92va'
>>> Home.to_grid_locator()
'IO92'
Parameters:
  • precision (str) - Precision with which generate locator string
Returns: str
Maidenhead locator for latitude and longitude

distance(self, other, method='haversine')

 

Calculate the distance from self to other

>>> "%i kM" % Point(52.015, -0.221).distance(Point(52.6333, -2.5))
'169 kM'
>>> "%i kM" % Point(52.015, -0.221).distance(Point(52.6333, -2.5),
...                                          method="sloc")
'169 kM'
>>> "%i kM" % Point(52.015, -0.221).distance(Point(52.6333, -2.5),
...                                          method="Invalid")
Traceback (most recent call last):
...
ValueError: Unknown method type `Invalid'

As a smoke test this check uses the example from Wikipedia's Great-circle distance entry of Nashville International Airport to Los Angeles International Airport, and is correct to within 2 kilometres of the calculation there.

>>> to_loc = Point(33.9400, -118.4000)
>>> "%i kM" % Point(36.1200, -86.6700).distance(to_loc)
'2884 kM'
>>> "%i mi" % Point(36.1200, -86.6700, "imperial").distance(to_loc)
'1792 mi'
>>> "%i nmi" % Point(36.1200, -86.6700, "nautical").distance(to_loc)
'1557 nmi'
>>> "%i kM" % Point(36.1200, -86.6700).distance(to_loc, method="sloc")
'2884 kM'
Parameters:
  • other (Point instance) - Location to calculate distance to
  • method (str) - Method used to calculate distance
Returns: float
Distance between self and other in units
Raises:
  • ValueError - Unknown value for method

bearing(self, other, format='numeric')

 

Calculate the initial bearing from self to other

>>> "%i" % Point(52.015, -0.221).bearing(Point(52.6333, -2.5))
'294'
>>> "%i" % Point(52.6333, -2.5).bearing(Point(52.015, -0.221))
'113'
>>> "%i" % Point(36.1200, -86.6700).bearing(Point(33.9400,
...                                               -118.4000))
'274'
>>> "%i" % Point(33.9400, -118.4000).bearing(Point(36.1200,
...                                                -86.6700))
'76'
>>> Point(52.015, -0.221).bearing(Point(52.6333, -2.5),
...                               format="string")
'North-west'
Parameters:
  • other (Point instance) - Location to calculate bearing to
  • format (str) - Format of the bearing string to return
Returns: float
Initial bearing from self to other in degrees
Raises:
  • ValueError - Unknown value for format

Note: Applying common plane Euclidean trigonometry to bearing calculations suggests to us that the bearing between point A to point B is equal to the inverse of the bearing from Point B to Point A, whereas spherical trigonometry is much more fun. If the bearing method doesn't make sense to you when calculating return bearings there are plenty of resources on the web that explain spherical geometry.

To Do: Add Rhumb line calculation

midpoint(self, other)

 

Calculate the midpoint from self to other

>>> Point(52.015, -0.221).midpoint(Point(52.6333, -2.5))
Point(52.3296314054, -1.35253686056, 'metric', 'degrees', 0)
>>> Point(36.1200, -86.6700).midpoint(Point(33.9400, -118.4000))
Point(36.082394919, -102.752173705, 'metric', 'degrees', 0)
Parameters:
  • other (Point instance) - Location to calculate midpoint to
Returns: Point instance
Great circle midpoint from self to other

See Also: bearing

final_bearing(self, other, format='numeric')

 

Calculate the final bearing from self to other

>>> "%i" % Point(52.015, -0.221).final_bearing(Point(52.6333, -2.5))
'293'
>>> "%i" % Point(52.6333, -2.5).final_bearing(Point(52.015, -0.221))
'114'
>>> "%i" % Point(36.1200, -86.6700).final_bearing(Point(33.9400,
...                                                     -118.4000))
'256'
>>> "%i" % Point(33.9400, -118.4000).final_bearing(Point(36.1200,
...                                                      -86.6700))
'94'
>>> Point(52.015, -0.221).bearing(Point(52.6333, -2.5),
...                               format="string")
'North-west'
Parameters:
  • other (Point instance) - Location to calculate final bearing to
  • format (str) - Format of the bearing string to return
Returns: float
Final bearing from self to other in degrees
Raises:
  • ValueError - Unknown value for format

See Also: bearing

destination(self, bearing, distance)

 

Calculate the destination from self given bearing and distance

>>> Point(52.015, -0.221).destination(294, 169)
Point(52.6116387502, -2.50937408195, 'metric', 'degrees', 0)
>>> Home = Point(52.015, -0.221, "imperial")
>>> Home.destination(294, 169 / utils.STATUTE_MILE)
Point(52.6116387502, -2.50937408195, 'metric', 'degrees', 0)
>>> Home = Point(52.015, -0.221, "nautical")
>>> Home.destination(294, 169 / utils.NAUTICAL_MILE)
Point(52.6116387502, -2.50937408195, 'metric', 'degrees', 0)
>>> Point(36.1200, -86.6700).destination(274, 2885)
Point(33.6872799138, -118.327218421, 'metric', 'degrees', 0)
Parameters:
  • bearing (float or coercible to float) - Bearing from self
  • distance (float or coercible to float) - Distance from self in units
Returns: Point
Location after travelling distance along bearing

sunrise(self, date=None, zenith=None)

 

Calculate the sunrise time for a Point object

>>> import datetime
>>> date = datetime.date(2007, 6, 15)
>>> Point(52.015, -0.221).sunrise(date)
datetime.time(3, 40)
>>> Point(52.6333, -2.5).sunrise(date)
datetime.time(3, 45)
>>> Point(36.1200, -86.6700).sunrise(date)
datetime.time(10, 29)
>>> Point(33.9400, -118.4000).sunrise(date)
datetime.time(12, 41)
Parameters:
  • date (datetime.date) - Calculate rise or set for given date
  • zenith (None or str) - Calculate rise/set events, or twilight times
Returns: datetime.datetime
The time for the given event in the specified timezone

See Also: utils.sun_rise_set

sunset(self, date=None, zenith=None)

 

Calculate the sunset time for a Point object

>>> import datetime
>>> date = datetime.date(2007, 6, 15)
>>> Point(52.015, -0.221).sunset(date)
datetime.time(20, 23)
>>> Point(52.6333, -2.5).sunset(date)
datetime.time(20, 36)
>>> Point(36.1200, -86.6700).sunset(date)
datetime.time(1, 5)
>>> Point(33.9400, -118.4000).sunset(date)
datetime.time(3, 6)
Parameters:
  • date (datetime.date) - Calculate rise or set for given date
  • zenith (None or str) - Calculate rise/set events, or twilight times
Returns: datetime.datetime
The time for the given event in the specified timezone

See Also: utils.sun_rise_set

sun_events(self, date=None, zenith=None)

 

Calculate the sunrise time for a Point object

>>> import datetime
>>> date = datetime.date(2007, 6, 15)
>>> Point(52.015, -0.221).sun_events(date)
(datetime.time(3, 40), datetime.time(20, 23))
>>> Point(52.6333, -2.5).sun_events(date)
(datetime.time(3, 45), datetime.time(20, 36))
>>> Point(36.1200, -86.6700).sun_events(date)
(datetime.time(10, 29), datetime.time(1, 5))
>>> Point(33.9400, -118.4000).sun_events(date)
(datetime.time(12, 41), datetime.time(3, 6))
Parameters:
  • date (datetime.date) - Calculate rise or set for given date
  • zenith (None or str) - Calculate rise/set events, or twilight times
Returns: tuple of datetime.datetime
The time for the given events in the specified timezone

See Also: utils.sun_rise_set

inverse(self, other)

 

Calculate the inverse geodesic from self to other

>>> "%i, %i" % Point(52.015, -0.221).inverse(Point(52.6333, -2.5))
'294, 169'
Parameters:
  • other (Point instance) - Location to calculate inverse geodesic to
Returns: tuple of float objects
Bearing and distance from self to other

forward(self, bearing, distance)

 

Calculate the destination from self given bearing and distance

>>> Point(52.015, -0.221).destination(294, 169)
Point(52.6116387502, -2.50937408195, 'metric', 'degrees', 0)
>>> Home = Point(52.015, -0.221, "imperial")
>>> Home.destination(294, 169 / utils.STATUTE_MILE)
Point(52.6116387502, -2.50937408195, 'metric', 'degrees', 0)
>>> Home = Point(52.015, -0.221, "nautical")
>>> Home.destination(294, 169 / utils.NAUTICAL_MILE)
Point(52.6116387502, -2.50937408195, 'metric', 'degrees', 0)
>>> Point(36.1200, -86.6700).destination(274, 2885)
Point(33.6872799138, -118.327218421, 'metric', 'degrees', 0)
Parameters:
  • bearing (float or coercible to float) - Bearing from self
  • distance (float or coercible to float) - Distance from self in units
Returns: Point
Location after travelling distance along bearing

Instance Variable Details [hide private]

latitude

Location's latitude
Get Method:
unreachable(self) - _%s
Set Method:
unreachable(self, value)

longitude

Locations's longitude
Get Method:
unreachable(self) - _%s
Set Method:
unreachable(self, value)

rad_latitude

Location's latitude in radians
Get Method:
unreachable(self) - _%s
Set Method:
unreachable(self, value)

rad_longitude

Location's longitude in radians
Get Method:
unreachable(self) - _%s
Set Method:
unreachable(self, value)