point
¶
point  Classes for working with locations on Earth.

class
upoints.point.
KeyedPoints
(points=None, parse=False, units='metric')[source]¶ Bases:
dict
Class for representing a keyed group of
Point
objects.New in version 0.2.0.
Initialise a new
KeyedPoints
object.Parameters: 
bearing
(order, format='numeric')[source]¶ Calculate bearing between locations.
Parameters:  order (list) – Order to process elements in
 format (str) – Format of the bearing string to return
Returns: Bearing between points in series
Return type: list of float

destination
(bearing, distance)[source]¶ Calculate destination locations for given distance and bearings.
Parameters:

distance
(order, method='haversine')[source]¶ Calculate distances between locations.
Parameters:  order (list) – Order to process elements in
 method (str) – Method used to calculate distance
Returns: Distance between points in
order
Return type: list of float

final_bearing
(order, format='numeric')[source]¶ Calculate final bearing between locations.
Parameters:  order (list) – Order to process elements in
 format (str) – Format of the bearing string to return
Returns: Bearing between points in series
Return type: list of float

forward
(bearing, distance)¶ Calculate destination locations for given distance and bearings.
Parameters:

import_locations
(locations)[source]¶ Import locations from arguments.
Parameters: locations (list of 2tuple of str) – Identifiers and locations

inverse
(order)[source]¶ Calculate the inverse geodesic between locations.
Parameters: order (list) – Order to process elements in Returns:  Bearing and distance between points in
 series
Return type: list of 2tuple of float

midpoint
(order)[source]¶ Calculate the midpoint between locations.
Parameters: order (list) – Order to process elements in Returns: Midpoint between points in series Return type: list of Point

range
(location, distance)[source]¶ Test whether locations are within a given range of the first.
Parameters: Returns: Objects within specified range
Return type: list of Point

sun_events
(date=None, zenith=None)[source]¶ Calculate sunrise/sunset times for locations.
Parameters:  date (datetime.date) – Calculate rise or set for given date
 zenith (str) – Calculate rise/set events, or twilight times
Returns:  The time for the sunrise and
sunset events for each point
Return type: list of 2tuple of datetime.datetime

sunrise
(date=None, zenith=None)[source]¶ Calculate sunrise times for locations.
Parameters:  date (datetime.date) – Calculate sunrise for given date
 zenith (str) – Calculate sunrise events, or end of twilight
Returns: The time for the sunrise for each point
Return type: list of datetime.datetime

sunset
(date=None, zenith=None)[source]¶ Calculate sunset times for locations.
Parameters:  date (datetime.date) – Calculate sunset for given date
 zenith (str) – Calculate sunset events, or start of twilight
Returns: The time for the sunset for each point
Return type: list of datetime.datetime


class
upoints.point.
Point
(latitude, longitude, units='metric', angle='degrees', timezone=0)[source]¶ Bases:
object
Simple class for representing a location on a sphere.
New in version 0.2.0.
Initialise a new
Point
object.Parameters: Raises: ValueError
– Unknown value forangle
ValueError
– Unknown value forunits
ValueError
– Invalid value forlatitude
orlongitude

bearing
(other, format='numeric')[source]¶ Calculate the initial bearing from self to other.
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.Todo
Add Rhumb line calculation
Parameters: Returns: Initial bearing from self to other in degrees
Return type: Raises: ValueError
– Unknown value forformat

destination
(bearing, distance)[source]¶ Calculate the destination from self given bearing and distance.
Parameters: Returns: Location after travelling
distance
alongbearing
Return type:

distance
(other, method='haversine')[source]¶ Calculate the distance from self to other.
As a smoke test this check uses the example from Wikipedia’s Greatcircle distance entry of Nashville International Airport to Los Angeles International Airport, and is correct to within 2 kilometres of the calculation there.
Parameters: Returns: Distance between self and other in
units
Return type: Raises: ValueError
– Unknown value formethod

final_bearing
(other, format='numeric')[source]¶ Calculate the final bearing from self to other.
See also
bearing
Parameters: Returns: Final bearing from self to other in degrees
Return type: Raises: ValueError
– Unknown value forformat

forward
(bearing, distance)¶ Calculate the destination from self given bearing and distance.
Parameters: Returns: Location after travelling
distance
alongbearing
Return type:

inverse
(other)[source]¶ Calculate the inverse geodesic from self to other.
Parameters: other (Point) – Location to calculate inverse geodesic to Returns: Bearing and distance from self to other Return type: tuple of float objects

midpoint
(other)[source]¶ Calculate the midpoint from self to other.
See also
bearing
Parameters: other (Point) – Location to calculate midpoint to Returns: Great circle midpoint from self to other Return type: Point

sun_events
(date=None, zenith=None)[source]¶ Calculate the sunrise time for a
Point
object.See also
utils.sun_rise_set
Parameters:  date (datetime.date) – Calculate rise or set for given date
 zenith (str) – Calculate rise/set events, or twilight times
Returns:  The time for the given events in the
specified timezone
Return type: tuple of datetime.datetime

sunrise
(date=None, zenith=None)[source]¶ Calculate the sunrise time for a
Point
object.See also
utils.sun_rise_set
Parameters:  date (datetime.date) – Calculate rise or set for given date
 zenith (str) – Calculate rise/set events, or twilight times
Returns:  The time for the given event in the specified
timezone
Return type:

sunset
(date=None, zenith=None)[source]¶ Calculate the sunset time for a
Point
object.See also
utils.sun_rise_set
Parameters:  date (datetime.date) – Calculate rise or set for given date
 zenith (str) – Calculate rise/set events, or twilight times
Returns:  The time for the given event in the specified
timezone
Return type:

class
upoints.point.
Points
(points=None, parse=False, units='metric')[source]¶ Bases:
list
Class for representing a group of
Point
objects.New in version 0.2.0.
Initialise a new
Points
object.Parameters: 
bearing
(format='numeric')[source]¶ Calculate bearing between locations.
Parameters: format (str) – Format of the bearing string to return Returns: Bearing between points in series Return type: list of float

destination
(bearing, distance)[source]¶ Calculate destination locations for given distance and bearings.
Parameters: Returns: Points shifted by
distance
andbearing
Return type: list of Point

distance
(method='haversine')[source]¶ Calculate distances between locations.
Parameters: method (str) – Method used to calculate distance Returns: Distance between points in series Return type: list of float

final_bearing
(format='numeric')[source]¶ Calculate final bearing between locations.
Parameters: format (str) – Format of the bearing string to return Returns: Bearing between points in series Return type: list of float

forward
(bearing, distance)¶ Calculate destination locations for given distance and bearings.
Parameters: Returns: Points shifted by
distance
andbearing
Return type: list of Point

import_locations
(locations)[source]¶ Import locations from arguments.
Parameters: locations (list of str or tuple) – Location identifiers

inverse
()[source]¶ Calculate the inverse geodesic between locations.
Returns:  Bearing and distance between points in
 series
Return type: list of 2tuple of float

midpoint
()[source]¶ Calculate the midpoint between locations.
Returns: Midpoint between points in series Return type: list of Point

range
(location, distance)[source]¶ Test whether locations are within a given range of
location
.Parameters: Returns: Points within range of the specified location
Return type: list of Point

sun_events
(date=None, zenith=None)[source]¶ Calculate sunrise/sunset times for locations.
Parameters:  date (datetime.date) – Calculate rise or set for given date
 zenith (str) – Calculate rise/set events, or twilight times
Returns:  The time for the sunrise and
sunset events for each point
Return type: list of 2tuple of datetime.datetime

sunrise
(date=None, zenith=None)[source]¶ Calculate sunrise times for locations.
Parameters:  date (datetime.date) – Calculate sunrise for given date
 zenith (str) – Calculate sunrise events, or end of twilight
Returns: The time for the sunrise for each point
Return type: list of datetime.datetime

sunset
(date=None, zenith=None)[source]¶ Calculate sunset times for locations.
Parameters:  date (datetime.date) – Calculate sunset for given date
 zenith (str) – Calculate sunset events, or start of twilight
Returns: The time for the sunset for each point
Return type: list of datetime.datetime


class
upoints.point.
TimedPoint
(latitude, longitude, units='metric', angle='degrees', timezone=0, time=None)[source]¶ Bases:
upoints.point.Point
Class for representing a location with an associated time.
New in version 0.12.0.
Initialise a new
TimedPoint
object.Parameters:  latitude (float, tuple or list) – Location’s latitude
 longitude (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
 time (datetime.datetime) – Time associated with the location