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
offloat
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
offloat
Returns: Distance between points in
order
-
final_bearing
(order, format='numeric')[source]¶ Calculate final bearing between locations.
Parameters: Return type: list
offloat
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 2tuple
ofstr
) – Identifiers and locations
-
inverse
(order)[source]¶ Calculate the inverse geodesic between locations.
Parameters: order (list) – Order to process elements in Return type: list
of 2tuple
offloat
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 instanceReturns: Midpoint between points in series
-
range
(location, distance)[source]¶ Test whether locations are within a given range of the first.
Parameters: Return type: list
ofPoint
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 2tuple
ofdatetime.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
ofdatetime.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
ofdatetime.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
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: 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
alongbearing
-
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: 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: 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
alongbearing
-
inverse
(other)[source]¶ Calculate the inverse geodesic from self to other.
Parameters: other (Point) – Location to calculate inverse geodesic to Return type: tuple
offloat
objectsReturns: 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
instanceReturns: 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
ofdatetime.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
- ValueError – Unknown value for
-
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
offloat
Returns: Bearing between points in series
-
destination
(bearing, distance)[source]¶ Calculate destination locations for given distance and bearings.
Parameters: Return type: list
ofPoint
Returns: Points shifted by
distance
andbearing
-
distance
(method='haversine')[source]¶ Calculate distances between locations.
Parameters: method (str) – Method used to calculate distance Return type: list
offloat
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
offloat
Returns: Bearing between points in series
-
forward
(bearing, distance)¶ Calculate destination locations for given distance and bearings.
Parameters: Return type: list
ofPoint
Returns: Points shifted by
distance
andbearing
-
import_locations
(locations)[source]¶ Import locations from arguments.
Parameters: locations ( list
ofstr
ortuple
) – Location identifiers
-
inverse
()[source]¶ Calculate the inverse geodesic between locations.
Return type: list
of 2tuple
offloat
Returns: Bearing and distance between points in series
-
midpoint
()[source]¶ Calculate the midpoint between locations.
Return type: list
ofPoint
instancesReturns: Midpoint between points in series
-
range
(location, distance)[source]¶ Test whether locations are within a given range of
location
Parameters: Return type: list
ofPoint
objects within specified rangeReturns: 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 2tuple
ofdatetime.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
ofdatetime.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
ofdatetime.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
orlist
) – Location’s latitude - longitude (
float
,tuple
orlist
) – 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
- latitude (
-
class
upoints.point.
TimedPoints
(points=None, parse=False, units='metric')[source]¶ Bases:
upoints.point.Points
Initialise a new
Points
object.Parameters: