upoints.point.Point

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

# Class Point

    object --+
             |
            Point

Known Subclasses:
  - trigpoints.Trigpoint
  - , cellid.Cell
  - , tzdata.Zone
  - , gpx._GpxElem
  - , xearth.Xearth
  - , nmea.Fix
  - , nmea.LoranPosition
  - , nmea.Position
  - , nmea.Waypoint
  - , osm.Node
  - , baken.Baken
  - , edist.NumberedPoint

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)