point

point - Classes for working with locations on Earth.

New in version 0.1.0.

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:
  • points (bool) – Point objects to wrap
  • points – Whether to attempt import of points
  • units (str) – Unit type to be used for distances when parsing string locations
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
Return type:

list of float

Returns:

Bearing between points in series

destination(bearing, distance)[source]

Calculate destination locations for given distance and bearings.

Parameters:
  • bearing (float) – Bearing to move on in degrees
  • distance (float) – Distance in kilometres
distance(order, method='haversine')[source]

Calculate distances between locations.

Parameters:
  • order (list) – Order to process elements in
  • method (str) – Method used to calculate distance
Return type:

list of float

Returns:

Distance between points in order

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
Return type:

list of float

Returns:

Bearing between points in series

forward(bearing, distance)

Calculate destination locations for given distance and bearings.

Parameters:
  • bearing (float) – Bearing to move on in degrees
  • distance (float) – Distance in kilometres
import_locations(locations)[source]

Import locations from arguments.

Parameters:locations (list of 2 tuple of str) – Identifiers and locations
inverse(order)[source]

Calculate the inverse geodesic between locations.

Parameters:order (list) – Order to process elements in
Return type:list of 2 tuple of float
Returns:Bearing and distance between points in series
midpoint(order)[source]

Calculate the midpoint between locations.

Parameters:order (list) – Order to process elements in
Return type:list of Point instance
Returns:Midpoint between points in series
range(location, distance)[source]

Test whether locations are within a given range of the first.

Parameters:
  • location (Point) – Location to test range against
  • distance (float) – Distance to test location is within
Return type:

list of Point objects within specified range

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
Return type:

list of 2 tuple of datetime.datetime

Returns:

The time for the sunrise and sunset events for each point

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
Return type:

list of datetime.datetime

Returns:

The time for the sunrise for each point

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
Return type:

list of datetime.datetime

Returns:

The time for the sunset for each point

to_grid_locator(precision='square')[source]

Calculate Maidenhead locator for locations.

Parameters:precision (str) – Precision with which generate locator string
Return type:list of str
Returns:Maidenhead locator for each point
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:
  • latitude (float) – Location’s latitude
  • longitude (float) – 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
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:
  • other (Point) – Location to calculate bearing to
  • format (str) – Format of the bearing string to return
Return type:

float

Returns:

Initial bearing from self to other in degrees

Raises ValueError:
 

Unknown value for format

destination(bearing, distance)[source]

Calculate the destination from self given bearing and distance.

Parameters:
  • bearing (float) – Bearing from self
  • distance (float) – Distance from self in self.units
Return type:

Point

Returns:

Location after travelling distance along bearing

distance(other, method='haversine')[source]

Calculate the distance from self to other.

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.

Parameters:
  • other (Point) – Location to calculate distance to
  • method (str) – Method used to calculate distance
Return type:

float

Returns:

Distance between self and other in units

Raises ValueError:
 

Unknown value for method

final_bearing(other, format='numeric')[source]

Calculate the final bearing from self to other.

See also

bearing()

Parameters:
  • other (Point) – Location to calculate final bearing to
  • format (str) – Format of the bearing string to return
Return type:

float

Returns:

Final bearing from self to other in degrees

Raises ValueError:
 

Unknown value for format

forward(bearing, distance)

Calculate the destination from self given bearing and distance.

Parameters:
  • bearing (float) – Bearing from self
  • distance (float) – Distance from self in self.units
Return type:

Point

Returns:

Location after travelling distance along bearing

inverse(other)[source]

Calculate the inverse geodesic from self to other.

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

Calculate the midpoint from self to other.

See also

bearing()

Parameters:other (Point) – Location to calculate midpoint to
Return type:Point instance
Returns:Great circle midpoint from self to other
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
Return type:

tuple of datetime.datetime

Returns:

The time for the given events in the specified timezone

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
Return type:

datetime.datetime

Returns:

The time for the given event in the specified timezone

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
Return type:

datetime.datetime

Returns:

The time for the given event in the specified timezone

to_grid_locator(precision='square')[source]

Calculate Maidenhead locator from latitude and longitude.

Parameters:precision (str) – Precision with which generate locator string
Return type:str
Returns:Maidenhead locator for latitude and longitude
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:
  • 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
bearing(format='numeric')[source]

Calculate bearing between locations.

Parameters:format (str) – Format of the bearing string to return
Return type:list of float
Returns:Bearing between points in series
destination(bearing, distance)[source]

Calculate destination locations for given distance and bearings.

Parameters:
  • bearing (float) – Bearing to move on in degrees
  • distance (float) – Distance in kilometres
Return type:

list of Point

Returns:

Points shifted by distance and bearing

distance(method='haversine')[source]

Calculate distances between locations.

Parameters:method (str) – Method used to calculate distance
Return type:list of float
Returns:Distance between points in series
final_bearing(format='numeric')[source]

Calculate final bearing between locations.

Parameters:format (str) – Format of the bearing string to return
Return type:list of float
Returns:Bearing between points in series
forward(bearing, distance)

Calculate destination locations for given distance and bearings.

Parameters:
  • bearing (float) – Bearing to move on in degrees
  • distance (float) – Distance in kilometres
Return type:

list of Point

Returns:

Points shifted by distance and bearing

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.

Return type:list of 2 tuple of float
Returns:Bearing and distance between points in series
midpoint()[source]

Calculate the midpoint between locations.

Return type:list of Point instances
Returns:Midpoint between points in series
range(location, distance)[source]

Test whether locations are within a given range of location

Parameters:
  • location (Point) – Location to test range against
  • distance (float) – Distance to test location is within
Return type:

list of Point objects within specified range

Returns:

Points within range of the specified location

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
Return type:

list of 2 tuple of datetime.datetime

Returns:

The time for the sunrise and sunset events for each point

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
Return type:

list of datetime.datetime

Returns:

The time for the sunrise for each point

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
Return type:

list of datetime.datetime

Returns:

The time for the sunset for each point

to_grid_locator(precision='square')[source]

Calculate Maidenhead locator for locations.

Parameters:precision (str) – Precision with which generate locator string
Return type:list of str
Returns:Maidenhead locator for each point
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 – Units type to be used for distances
  • timezone – Offset from UTC in minutes
  • time (datetime.datetime) – Time associated with the location