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

Class Points

object --+    
         |    
      list --+
             |
            Points
Known Subclasses:

Class for representing a group of Point objects

Since: 2008-05-02

Instance Methods [hide private]
new list
__init__(self, points=None, parse=False, units='metric')
Initialise a new Points object
str
__repr__(self)
Self-documenting string representation
 
import_locations(self, locations)
Import locations from arguments
list of float
distance(self, method='haversine')
Calculate distances between locations
list of float
bearing(self, format='numeric')
Calculate bearing between locations
list of float
final_bearing(self, format='numeric')
Calculate final bearing between locations
list of 2 tuple of float
inverse(self)
Calculate the inverse geodesic between locations
list of Point instance
midpoint(self)
Calculate the midpoint between locations
list of Point objects within specified range
range(self, location, distance)
Test whether locations are within a given range of the first
 
destination(self, bearing, distance)
Calculate destination locations for given distance and bearings
 
forward(self, bearing, distance)
Calculate destination locations for given distance and bearings
list of datetime.datetime
sunrise(self, date=None, zenith=None)
Calculate sunrise times for locations
list of datetime.datetime
sunset(self, date=None, zenith=None)
Calculate sunset times for locations
list of 2 tuple of datetime.datetime
sun_events(self, date=None, zenith=None)
Calculate sunrise/sunset times for locations
list of str
to_grid_locator(self, precision='square')
Calculate Maidenhead locator for locations

Inherited from list: __add__, __contains__, __delitem__, __delslice__, __eq__, __ge__, __getattribute__, __getitem__, __getslice__, __gt__, __hash__, __iadd__, __imul__, __iter__, __le__, __len__, __lt__, __mul__, __ne__, __new__, __reversed__, __rmul__, __setitem__, __setslice__, append, count, extend, index, insert, pop, remove, reverse, sort

Inherited from object: __delattr__, __reduce__, __reduce_ex__, __setattr__, __str__

Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__init__(self, points=None, parse=False, units='metric')
(Constructor)

 

Initialise a new Points object

>>> Points([Point(52.015, -0.221), Point(53.645, -0.284)])
Points([Point(52.015, -0.221, 'metric', 'degrees', 0),
        Point(53.645, -0.284, 'metric', 'degrees', 0)],
       False, 'metric')
Parameters:
  • points (list of Point objects) - Point objects to wrap
  • parse (bool) - Whether to attempt import of points
  • units (str) - Unit type to be used for distances when parsing string locations
Returns: new list
Overrides: object.__init__

__repr__(self)
(Representation operator)

 

Self-documenting string representation

>>> locations = [Point(0, 0)] * 4
>>> Points(locations)
Points([Point(0.0, 0.0, 'metric', 'degrees', 0),
        Point(0.0, 0.0, 'metric', 'degrees', 0),
        Point(0.0, 0.0, 'metric', 'degrees', 0),
        Point(0.0, 0.0, 'metric', 'degrees', 0)],
       False, 'metric')
Returns: str
String to recreate Points object
Overrides: object.__repr__

import_locations(self, locations)

 

Import locations from arguments

>>> locations = Points()
>>> locations.import_locations(["0;0", "52.015 -0.221"])
>>> locations
Points([Point(0.0, 0.0, 'metric', 'degrees', 0),
        Point(52.015, -0.221, 'metric', 'degrees', 0)],
        False, 'metric')
Parameters:
  • locations (list of str or tuple) - Location identifiers

distance(self, method='haversine')

 

Calculate distances between locations

>>> locations = Points(["52.015;-0.221", "52.168;0.040", "52.855;0.657"],
...                    parse=True)
>>> "%.3f" % sum(locations.distance())
'111.632'
Parameters:
  • method (str) - Method used to calculate distance
Returns: list of float
Distance between points in series

bearing(self, format='numeric')

 

Calculate bearing between locations

>>> locations = Points(["52.015;-0.221", "52.168;0.040", "52.855;0.657"],
...                    parse=True)
>>> map(lambda x: "%.3f" % x, locations.bearing())
['46.242', '28.416']
Parameters:
  • format (str) - Format of the bearing string to return
Returns: list of float
Bearing between points in series

final_bearing(self, format='numeric')

 

Calculate final bearing between locations

>>> locations = Points(["52.015;-0.221", "52.168;0.040", "52.855;0.657"],
...                    parse=True)
>>> map(lambda x: "%.3f" % x, locations.final_bearing())
['46.448', '28.906']
Parameters:
  • format (str) - Format of the bearing string to return
Returns: list of float
Bearing between points in series

inverse(self)

 

Calculate the inverse geodesic between locations

>>> locations = Points(["52.015;-0.221", "52.168;0.040", "52.855;0.657"],
...                    parse=True)
>>> locations.inverse()
[(46.242393198024672, 24.629669163425465),
 (28.416173848453582, 87.002075833085328)]
Returns: list of 2 tuple of float
Bearing and distance between points in series

midpoint(self)

 

Calculate the midpoint between locations

>>> locations = Points(["52.015;-0.221", "52.168;0.040", "52.855;0.657"],
...                    parse=True)
>>> locations.midpoint()
[Point(52.0915720432, -0.0907237539143, 'metric', 'degrees', 0),
 Point(52.5119010509, 0.346088603087, 'metric', 'degrees', 0)]
Returns: list of Point instance
Midpoint between points in series

range(self, location, distance)

 

Test whether locations are within a given range of the first

>>> locations = Points(["52.015;-0.221", "52.168;0.040", "52.855;0.657"],
...                    parse=True)
>>> list(locations.range(Point(52.015, -0.221), 20))
[Point(52.015, -0.221, 'metric', 'degrees', 0)]
Parameters:
  • location (Point) - Location to test range against
  • distance (float) - Distance to test location is within
Returns: list of Point objects within specified range

destination(self, bearing, distance)

 

Calculate destination locations for given distance and bearings

>>> locations = Points(["52.015;-0.221", "52.168;0.040", "52.855;0.657"],
...                    parse=True)
>>> list(locations.destination(42, 240))
[Point(53.5956078217, 2.2141813684, 'metric', 'degrees', 0),
 Point(53.7484691495, 2.48403821375, 'metric', 'degrees', 0),
 Point(54.4348338045, 3.14183478498, 'metric', 'degrees', 0)]
Parameters:
  • bearing (float or coercible to float) - Bearing to move on in degrees
  • distance (float or coercible to float) - Distance in kilometres

forward(self, bearing, distance)

 

Calculate destination locations for given distance and bearings

>>> locations = Points(["52.015;-0.221", "52.168;0.040", "52.855;0.657"],
...                    parse=True)
>>> list(locations.destination(42, 240))
[Point(53.5956078217, 2.2141813684, 'metric', 'degrees', 0),
 Point(53.7484691495, 2.48403821375, 'metric', 'degrees', 0),
 Point(54.4348338045, 3.14183478498, 'metric', 'degrees', 0)]
Parameters:
  • bearing (float or coercible to float) - Bearing to move on in degrees
  • distance (float or coercible to float) - Distance in kilometres

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

 

Calculate sunrise times for locations

>>> locations = Points(["52.015;-0.221", "52.168;0.040", "52.855;0.657"],
...                    parse=True)
>>> import datetime
>>> list(locations.sunrise(datetime.date(2008, 5, 2)))
[datetime.time(4, 28), datetime.time(4, 26), datetime.time(4, 21)]
Parameters:
  • date (datetime.date) - Calculate rise or set for given date
  • zenith (None or str) - Calculate rise/set events, or twilight times
Returns: list of datetime.datetime
The time for the sunrise for each point

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

 

Calculate sunset times for locations

>>> locations = Points(["52.015;-0.221", "52.168;0.040", "52.855;0.657"],
...                    parse=True)
>>> import datetime
>>> list(locations.sunset(datetime.date(2008, 5, 2)))
[datetime.time(19, 29), datetime.time(19, 28), datetime.time(19, 28)]
Parameters:
  • date (datetime.date) - Calculate rise or set for given date
  • zenith (None or str) - Calculate rise/set events, or twilight times
Returns: list of datetime.datetime
The time for the sunset for each point

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

 

Calculate sunrise/sunset times for locations

>>> locations = Points(["52.015;-0.221", "52.168;0.040", "52.855;0.657"],
...                    parse=True)
>>> import datetime
>>> list(locations.sun_events(datetime.date(2008, 5, 2)))
[(datetime.time(4, 28), datetime.time(19, 29)),
 (datetime.time(4, 26), datetime.time(19, 28)),
 (datetime.time(4, 21), datetime.time(19, 28))]
Parameters:
  • date (datetime.date) - Calculate rise or set for given date
  • zenith (None or str) - Calculate rise/set events, or twilight times
Returns: list of 2 tuple of datetime.datetime
The time for the sunrise and sunset events for each point

to_grid_locator(self, precision='square')

 

Calculate Maidenhead locator for locations

>>> locations = Points(["52.015;-0.221", "52.168;0.040", "52.855;0.657"],
...                    parse=True)
>>> list(locations.to_grid_locator("extsquare"))
['IO92va33', 'JO02ae40', 'JO02hu85']
>>> list(locations.to_grid_locator("subsquare"))
['IO92va', 'JO02ae', 'JO02hu']
Parameters:
  • precision (str) - Precision with which generate locator string
Returns: list of str
Maidenhead locator for each point