`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:	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
Returns:	Bearing between points in series
Return type:	list of float

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
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:	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
Returns:	Bearing and distance between points in series
Return type:	list of 2-tuple 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:	location (Point) – Location to test range against distance (float) – Distance to test location is within
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 2-tuple 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

to_grid_locator(precision='square')[source]¶

Calculate Maidenhead locator for locations.

Parameters:	precision (str) – Precision with which generate locator string
Returns:	Maidenhead locator for each point
Return type:	list of str

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, 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
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
Returns:	Initial bearing from self to other in degrees
Return type:	float
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`
Returns:	Location after travelling `distance` along `bearing`
Return type:	Point

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
Returns:	Distance between self and other in `units`
Return type:	float
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
Returns:	Final bearing from self to other in degrees
Return type:	float
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`
Returns:	Location after travelling `distance` along `bearing`
Return type:	Point

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:

datetime.datetime

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:

datetime.datetime

to_grid_locator(precision='square')[source]¶

Calculate Maidenhead locator from latitude and longitude.

Parameters:	precision (str) – Precision with which generate locator string
Returns:	Maidenhead locator for latitude and longitude
Return type:	str

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) – `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
Returns:	Bearing between points in series
Return type:	list of float

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
Returns:	Points shifted by `distance` and `bearing`
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:	bearing (float) – Bearing to move on in degrees distance (float) – Distance in kilometres
Returns:	Points shifted by `distance` and `bearing`
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 2-tuple 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:	location (Point) – Location to test range against distance (float) – Distance to test location is within
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 2-tuple 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

to_grid_locator(precision='square')[source]¶

Calculate Maidenhead locator for locations.

Parameters:	precision (str) – Precision with which generate locator string
Returns:	Maidenhead locator for each point
Return type:	list of str

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

class upoints.point.TimedPoints(points=None, parse=False, units='metric')[source]¶

Bases: upoints.point.Points

Initialise a new Points object.

Parameters:	points (list of Point) – `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

speed()[source]¶

Calculate speed between Points.

Returns:	Speed between `Point` elements in km/h
Return type:	list of float

point¶

`point`¶