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: - bearing(order, format='numeric')[source]¶
Calculate bearing between locations.
Parameters: Return type: list of float
Returns: Bearing between points in series
- destination(bearing, distance)[source]¶
Calculate destination locations for given distance and bearings.
Parameters:
- distance(order, method='haversine')[source]¶
Calculate distances between locations.
Parameters: Return type: list of float
Returns: Distance between points in order
- final_bearing(order, format='numeric')[source]¶
Calculate final bearing between locations.
Parameters: Return type: list of float
Returns: Bearing between points in series
- forward(bearing, distance)¶
Calculate destination locations for given distance and bearings.
Parameters:
- 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
- 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 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: 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
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: 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
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: 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: Returns: The time for the given event in the specified timezone
- 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 Return type: list of float Returns: Bearing between points in series
- destination(bearing, distance)[source]¶
Calculate destination locations for given distance and bearings.
Parameters: 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: 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
- 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