upstage.geography package#

Submodules#

upstage.geography.conversions module#

Geodetic frame conversions.

class BaseConversions#

Bases: object

Base class for converting in geodetic frames.

R_e = 0.0#

R_p = 0.0#

e = 0.0#

e_2 = 0.0#

classmethod ecef2lla(ecef: list[tuple[float, float, float]], radians_out: bool = False) → list[tuple[float, float, float]]#

Convert ECEF to Lat/Lon/Altitude.

Parameters:

ecef (POSITIONS) – ECEF points
radians_out (bool, optional) – If lat/lon out should be in radians. Defaults to False.

Returns:

Lat/Lon/Altitude

Return type:

POSITIONS

ep = 0.0#

ep_2 = 0.0#

f = 0.0#

classmethod lla2ecef(lla: list[tuple[float, float, float]], input_in_radians: bool = False) → list[tuple[float, float, float]]#

Convert Lat-Lon-Altitude into ECEF.

Parameters:

lla (POSITIONS) – lat/lon/alt data in 3 columns and N rows.
input_in_radians (bool, optional) – If the lat/lon are in radians. Defaults to False.

Returns:

Array of XYZ ECEF values.

Return type:

POSITIONS

class SphericalConversions#

Bases: BaseConversions

Conversions on a spherical globe.

R_e = 6378137.0#

R_p = 6378137.0#

e = 0.0#

e_2 = 0.0#

classmethod ecef2lla(ecef: list[tuple[float, float, float]], radians_out: bool = False) → list[tuple[float, float, float]]#

Convert ECEF to Lat-Lon-Alt.

Parameters:

ecef (POSITIONS) – Points in ECEF
radians_out (bool, optional) – If Lat/Lon out are in radians. Defaults to False.

Returns:

Lat-Lon-Alt points

Return type:

POSITIONS

ep = 0.0#

ep_2 = 0.0#

classmethod lla2ecef(lla: list[tuple[float, float, float]], input_in_radians: bool = False) → list[tuple[float, float, float]]#

Lat-Lon-Alt to ECEF.

Parameters:

lla (POSITIONS) – Lat-Lon-Altitude points
input_in_radians (bool, optional) – If lat/lon are in radians. Defaults to False.

Returns:

ECEF

Return type:

POSITIONS

class WGS84Conversions#

Bases: BaseConversions

WGS84 coordinate conversions.

R_e = 6378137.0#

R_p = 6356752.314245179#

e = 0.08181919084262149#

e_2 = 0.0066943799901413165#

ep = 0.2860405405578403#

ep_2 = 0.006739496742276434#

f = 0.0033528106647474805#

upstage.geography.intersections module#

Functions for finding intersections in geodetics.

class CrossingCondition(kind: str, begin: tuple[float, float, float], end: tuple[float, float, float] | None = None)#

Bases: object

Data about an intersection.

begin: tuple[float, float, float]#

end: tuple[float, float, float] | None = None#

kind: str#

find_crossing_points(start_lla: tuple[float, float, float], finish_lla: tuple[float, float, float], point_lla: tuple[float, float, float], earth: Spherical | WGS84, radius: float, dist_between: float = 9260.0) → list[CrossingCondition]#

Finds the points along a great circle path and a sphere.

The output data provides booleans to state If the start or end are within range/visibility.

Parameters:

start_lla (LAT_LON_ALT) – Starting point (degrees/meters)
finish_lla (LAT_LON_ALT) – Ending point (degrees/meters)
point_lla (LAT_LON_ALT) – Point of sensing (degrees/meters)
earth (Spherical | WGS84) – Earth model
radius (float) – Radius that the sensor can see (meters)
dist_between (float, optional) – Distance to use for segment length (meters). Defaults to 5 nmi (or 9260 meters).

Returns:

A list of data describing the crossover points on the great circle path. It will start with: [“START_INSIDE” or “START_OUT”, start LLA]. Then there will be one or two: [“ENTER” or “EXIT”, LLA, LLA] where the two LLA values are the OUT and IN points as described. It will end with: [“END_INSIDE” or “END_OUT”, end LLA].

Return type:

list[CrossingCondition]

get_intersection_locations(start: tuple[float, float, float], finish: tuple[float, float, float], sphere_center: tuple[float, float, float], radius: float, radius_units: str, earth: WGS84 | Spherical, dist_between: float | None = None, subdivide_levels: list[int] | None = None) → list[CrossingCondition]#

Get the locations and kinds of intersections of a path to a sphere.

Parameters:

start (LAT_LON_ALT) – Starting point (degrees)
finish (LAT_LON_ALT) – Ending point (degrees)
sphere_center (LAT_LON_ALT) – Center of the sensing sphere (not earth, degrees/meters)
radius (float) – Sensor radius
radius_units (str) – Units of the sensor radius
earth (Spherical | WGS84) – Geodetic description
dist_between (float, optional) – Splitting distance for search. Defaults to 9260.0 meters (5 nmi)
subdivide_levels (list[int], optional) – Levels for searching smaller sections. Defaults to None.

Returns:

The intersection type, if any

It will start with:: [“START_INSIDE” or “START_OUT”]
Then there will be one or two:: [“ENTER” or “EXIT”] where the two LLA values are the OUT and IN points as described
It will end with:: [“END_INSIDE” or “END_OUT”]

Return type:

list[CrossingCondition]

upstage.geography.spherical module#

Geographical math using spherical coordinates for Earth.

class Spherical#

Bases: SphericalConversions

Geographical math using spherical coordinates for Earth.

EARTH_RADIUS = 6378137.0#

classmethod bearing(origin: tuple[float, float], destination: tuple[float, float]) → float#

Calculate the forward bearing from origin to destination.

Parameters:

origin (LAT_LON) – Start lat/lon
destination (LAT_LON) – End lat/lon

Returns:

The forward bearing (0 is north)

Return type:

float

classmethod cross_track_distance(origin: tuple[float, float], destination: tuple[float, float], point: tuple[float, float], units: str = 'nmi') → float#

Find the minimum distance from a point to a great circle path.

Parameters:

origin (LAT_LON) – Great circle start
destination (LAT_LON) – Great circle end
point (LAT_LON) – Point to start distance measurement
units (str, optional) – Units for the distance output. Defaults to ‘nmi’.

Returns:

Distance from point to origin->destination great circle

Return type:

float

classmethod cross_track_point(origin: tuple[float, float], destination: tuple[float, float], point: tuple[float, float]) → tuple[float, float]#

Find the point on a great circle that minimizes the distance to another point.

Parameters:

origin (LAT_LON) – Great circle start
destination (LAT_LON) – Great circle end
point (LAT_LON) – Point to start distance measurement

Returns:

Location on great circle closest to a point

Return type:

LAT_LON

classmethod distance(loc1: tuple[float, float], loc2: tuple[float, float], units: str = 'nmi') → float#

Find distance between two points.

Return the great circle distance from the loc1 to another loc2.

Parameters:

loc1 (LAT_LON) – Starting point (degrees)
loc2 (LAT_LON) – Ending point (degrees)
units (str, optional) – Units requested for distance. Defaults to ‘nmi’.

Returns:

Distances in the defined units

Return type:

float

classmethod distance_and_bearing(loc1: tuple[float, float], loc2: tuple[float, float], units: str = 'nmi') → tuple[float, float]#

Find great circle distance and forward bearing between two points.

Parameters:

loc1 (LAT_LON) – Starting point
loc2 (LAT_LON) – Ending point
units (str, optional) – Distance units requested. Defaults to ‘nmi’.

Returns:

Distance and Bearing

Return type:

tuple[float, float]

classmethod ecef_and_geo_linspace(start: tuple[float, float], finish: tuple[float, float], start_alt: float, finish_alt: float, segments: int) → tuple[list[tuple[float, float, float]], list[tuple[float, float, float]]]#

Get an array of spaced points along a greate circle path in ECEF and LLA.

Parameters:

start (LAT_LON) – Start point (lat/lon degrees)
finish (LAT_LON) – End point (lat/lon degrees)
start_alt (float) – Starting altitude (meters)
finish_alt (float) – Ending altitude (meters)
segments (int) – Number of segments to create

Returns:

ECEF coordinates POSITIONS: Lat/Lon/Alt (degrees)

Return type:

POSITIONS

classmethod ecef_linspace(start: tuple[float, float], finish: tuple[float, float], start_alt: float, finish_alt: float, segments: int) → list[tuple[float, float, float]]#

Get an array of spaced points along a greate circle path in ECEF.

Parameters:

start (LAT_LON) – Start point (lat/lon degrees)
finish (LAT_LON) – End point (lat/lon degrees)
start_alt (float) – Starting altitude (meters)
finish_alt (float) – Ending altitude (meters)
segments (int) – Number of segments to create

Returns:

ECEF coordinates

Return type:

POSITIONS

classmethod geo_circle(center: tuple[float, float], radius: float, radius_units: str = 'nmi', num_points: int = 10) → list[tuple[float, float]]#

Make an approximate circle by sweeping bearing from a central location.

Altitudes are not considered since they do not affect angular coordinates.

Parameters:

center (LAT_LON) – Center point (degrees)
radius (float) – Radius of the circle
radius_units (str, optional) – Units of the radius. Defaults to ‘nmi’.
num_points (int, optional) – Number of points on the circle. Defaults to 10.

Returns:

Latitude and Longitude (degrees) of the circle

Return type:

list[LAT_LON]

classmethod geo_linspace(start: tuple[float, float], end: tuple[float, float], num_segments: int = 10) → list[tuple[float, float]]#

Make a discrete great circle path between two points.

Altitudes are not considered since they do not affect angular coordinates.

The number of points is the number

Parameters:

start (LAT_LON) – Start point
end (LAT_LON) – End point
num_segments (int, optional) – Number of segments on the path. Defaults to 10.

Returns:

Lattiude and Longitude (degrees)

Return type:

list[LAT_LON]

classmethod geo_linspace_with_ecef(start: tuple[float, float], end: tuple[float, float], num_segments: int = 10) → tuple[list[float], list[float], list[tuple[float, float, float]]]#

Make a discrete great circle path between two points.

Altitudes are not considered since they do not affect angular coordinates.

Latitude and Longitude are all in degrees

Parameters:

start (LAT_LON) – Starting lat/lon (degrees)
end (LAT_LON) – Ending lat/lon (degrees)
num_segments (int, optional) – Number of segments to make. Defaults to 10.

Returns:

Latitude, Longitude, and ECEF points.

Return type:

tuple[list[float], list[float], POSITIONS]

classmethod point_along(origin: tuple[float, float], destination: tuple[float, float], f: float) → tuple[float, float]#

Find the location fractionally along a great circle path.

Parameters:

origin (LAT_LON) – Lat / Lon (degrees)
destination (LAT_LON) – Lat / Lon (degrees)
f (float) – Fraction along the great circle path to get the point at

Returns:

Point between origin and destination (degrees)

Return type:

LAT_LON

classmethod point_from_bearing_dist(point: tuple[float, float], bearing: float, distance: float, distance_units: str = 'nmi') → tuple[float, float]#

Get a Location from a starting point, a bearing, and a distance.

Parameters:

point (LAT_LON) – Starting point (degrees)
bearing (float) – Bearing to travel along (degrees)
distance (float) – Distance to travel
distance_units (str, optional) – Units of the distance. Defaults to ‘nmi’.

Returns:

The point

Return type:

LAT_LON

upstage.geography.wgs84 module#

WGS84 Earth model.

class WGS84#

Bases: WGS84Conversions

Geographical math using elliptical coordinates for Earth.

Based on Vincenty’s methods and WGS84 parameters.

classmethod bearing(loc1: tuple[float, float], loc2: tuple[float, float], tol: float = 1e-12, max_iter: int = 200) → float#

Calculate the forward bearing (in degrees) from loc1 to loc2.

Parameters:

loc1 (LAT_LON) – Starting point (degrees)
loc2 (LAT_LON) – Ending point (degrees)
units (str, optional) – Units requested for distance. Defaults to ‘nmi’.
tol (float, optional) – Calculation convergence tolerance. Defaults to 1e-12
max_iter (int, optional) – Max iterations. Defaults to 200

Returns:

Bearing

Return type:

float

classmethod distance(loc1: tuple[float, float], loc2: tuple[float, float], units: str = 'nmi', tol: float = 1e-12, max_iter: int = 200) → float#

Find distance between two points.

Return the great circle distance from the loc1 to another loc2.

Parameters:

loc1 (LAT_LON) – Starting point (degrees)
loc2 (LAT_LON) – Ending point (degrees)
units (str, optional) – Units requested for distance. Defaults to ‘nmi’.
tol (float, optional) – Calculation convergence tolerance. Defaults to 1e-12
max_iter (int, optional) – Max iterations. Defaults to 200

Returns:

Distances in the defined units

Return type:

float

classmethod distance_and_bearing(loc1: tuple[float, float], loc2: tuple[float, float], units: str = 'nmi', tol: float = 1e-12, max_iter: int = 200) → tuple[float, float]#

Find great circle distance and forward bearing between two points.

Parameters:

loc1 (LAT_LON) – Starting point
loc2 (LAT_LON) – Ending point
units (str, optional) – Distance units requested. Defaults to ‘nmi’.
tol (float, optional) – Calculation convergence tolerance. Defaults to 1e-12
max_iter (int, optional) – Max iterations. Defaults to 200

Returns:

Distance and Bearing

Return type:

tuple[float, float]

Get an array of spaced points along a greate circle path in ECEF and LLA.

Parameters:

start (LAT_LON) – Start point (lat/lon degrees)
finish (LAT_LON) – End point (lat/lon degrees)
start_alt (float) – Starting altitude (meters)
finish_alt (float) – Ending altitude (meters)
segments (int) – Number of segments to create

Returns:

ECEF coordinates list[tuple[float, float, float]]: Lat/Lon/Alt (degrees)

Return type:

POSITIONS

classmethod ecef_linspace(start: tuple[float, float], finish: tuple[float, float], start_alt: float, finish_alt: float, segments: int) → list[tuple[float, float, float]]#

Get an array of spaced points along a greate circle path in ECEF.

Parameters:

start (LAT_LON) – Start point (lat/lon degrees)
finish (LAT_LON) – End point (lat/lon degrees)
start_alt (float) – Starting altitude (meters)
finish_alt (float) – Ending altitude (meters)
segments (int) – Number of segments to create

Returns:

ECEF coordinates

Return type:

POSITIONS

classmethod geo_circle(center: tuple[float, float], radius: float, radius_units: str = 'nmi', num_points: int = 10) → list[tuple[float, float]]#

Make an approximate circle by sweeping bearing from a central location.

Altitudes are not considered since they do not affect angular coordinates.

Parameters:

center (LAT_LON) – Center point (degrees)
radius (float) – Radius of the circle
radius_units (str, optional) – Units of the radius. Defaults to ‘nmi’.
num_points (int, optional) – Number of points on the circle. Defaults to 10.

Returns:

Latitude and Longitude (degrees) of the circle

Return type:

list[LAT_LON]

classmethod geo_linspace(start: tuple[float, float], end: tuple[float, float], num_segments: int = 10) → list[tuple[float, float]]#

Make a discrete great circle path between two points.

Altitudes are not considered since they do not affect angular coordinates.

The number of points is the number

Parameters:

start (LAT_LON) – Start point
end (LAT_LON) – End point
num_segments (int, optional) – Number of segments on the path. Defaults to 10.

Returns:

Lattiude and Longitude (degrees)

Return type:

list[LAT_LON]

classmethod point_from_bearing_dist(point: tuple[float, float], bearing: float, distance: float, distance_units: str = 'nmi', tol: float = 1e-12, max_iter: int = 200) → tuple[float, float]#

Get a Location from a starting point, a bearing, and a distance.

Parameters:

point (LAT_LON) – Starting point (degrees)
bearing (float) – Bearing to travel along (degrees)
distance (float) – Distance to travel
distance_units (str, optional) – Units of the distance. Defaults to ‘nmi’.
tol (float, optional) – Calculation convergence tolerance. Defaults to 1e-12
max_iter (int, optional) – Max iterations. Defaults to 200

Returns:

The point in degrees

Return type:

LAT_LON

Module contents#

Geographical methods for intersections, distances, and locations.