Geod¶
pyproj.Geod¶
- class pyproj.Geod(initstring: str | None = None, **kwargs)[source]¶
Bases:
Geod
performs forward and inverse geodetic, or Great Circle, computations. The forward computation (using the ‘fwd’ method) involves determining latitude, longitude and back azimuth of a terminus point given the latitude and longitude of an initial point, plus azimuth and distance. The inverse computation (using the ‘inv’ method) involves determining the forward and back azimuths and distance given the latitudes and longitudes of an initial and terminus point.
- __init__(initstring: str | None = None, **kwargs) None [source]¶
initialize a Geod class instance.
Geodetic parameters for specifying the ellipsoid can be given in a dictionary ‘initparams’, as keyword arguments, or as as proj geod initialization string.
You can get a dictionary of ellipsoids using
pyproj.get_ellps_map()
or with the variable pyproj.pj_ellps.The parameters of the ellipsoid may also be set directly using the ‘a’ (semi-major or equatorial axis radius) keyword, and any one of the following keywords: ‘b’ (semi-minor, or polar axis radius), ‘e’ (eccentricity), ‘es’ (eccentricity squared), ‘f’ (flattening), or ‘rf’ (reciprocal flattening).
See the proj documentation (https://proj.org) for more information about specifying ellipsoid parameters.
Example usage:
>>> from pyproj import Geod >>> g = Geod(ellps='clrk66') # Use Clarke 1866 ellipsoid. >>> # specify the lat/lons of some cities. >>> boston_lat = 42.+(15./60.); boston_lon = -71.-(7./60.) >>> portland_lat = 45.+(31./60.); portland_lon = -123.-(41./60.) >>> newyork_lat = 40.+(47./60.); newyork_lon = -73.-(58./60.) >>> london_lat = 51.+(32./60.); london_lon = -(5./60.) >>> # compute forward and back azimuths, plus distance >>> # between Boston and Portland. >>> az12,az21,dist = g.inv(boston_lon,boston_lat,portland_lon,portland_lat) >>> f"{az12:.3f} {az21:.3f} {dist:.3f}" '-66.531 75.654 4164192.708' >>> # compute latitude, longitude and back azimuth of Portland, >>> # given Boston lat/lon, forward azimuth and distance to Portland. >>> endlon, endlat, backaz = g.fwd(boston_lon, boston_lat, az12, dist) >>> f"{endlat:.3f} {endlon:.3f} {backaz:.3f}" '45.517 -123.683 75.654' >>> # compute the azimuths, distances from New York to several >>> # cities (pass a list) >>> lons1 = 3*[newyork_lon]; lats1 = 3*[newyork_lat] >>> lons2 = [boston_lon, portland_lon, london_lon] >>> lats2 = [boston_lat, portland_lat, london_lat] >>> az12,az21,dist = g.inv(lons1,lats1,lons2,lats2) >>> for faz, baz, d in list(zip(az12,az21,dist)): ... f"{faz:7.3f} {baz:8.3f} {d:12.3f}" ' 54.663 -123.448 288303.720' '-65.463 79.342 4013037.318' ' 51.254 -71.576 5579916.651' >>> g2 = Geod('+ellps=clrk66') # use proj4 style initialization string >>> az12,az21,dist = g2.inv(boston_lon,boston_lat,portland_lon,portland_lat) >>> f"{az12:.3f} {az21:.3f} {dist:.3f}" '-66.531 75.654 4164192.708'
- fwd(lons: Any, lats: Any, az: Any, dist: Any, radians: bool = False, inplace: bool = False, return_back_azimuth: bool = True) tuple[Any, Any, Any] [source]¶
Forward transformation
Determine longitudes, latitudes and back azimuths of terminus points given longitudes and latitudes of initial points, plus forward azimuths and distances.
Added in version 3.5.0: inplace
Added in version 3.5.0: return_back_azimuth
Accepted numeric scalar or array:
- Parameters:
lons (scalar or array) – Longitude(s) of initial point(s)
lats (scalar or array) – Latitude(s) of initial point(s)
az (scalar or array) – Forward azimuth(s)
dist (scalar or array) – Distance(s) between initial and terminus point(s) in meters
radians (bool, default=False) – If True, the input data is assumed to be in radians. Otherwise, the data is assumed to be in degrees.
inplace (bool, default=False) – If True, will attempt to write the results to the input array instead of returning a new array. This will fail if the input is not an array in C order with the double data type.
return_back_azimuth (bool, default=True) – If True, the third return value will be the back azimuth, Otherwise, it will be the forward azimuth.
- Returns:
scalar or array – Longitude(s) of terminus point(s)
scalar or array – Latitude(s) of terminus point(s)
scalar or array – Back azimuth(s) or Forward azimuth(s)
- fwd_intermediate(lon1: float, lat1: float, azi1: float, npts: int, del_s: float, initial_idx: int = 1, terminus_idx: int = 1, radians: bool = False, flags: ~pyproj.enums.GeodIntermediateFlag = <GeodIntermediateFlag.DEFAULT: 0>, out_lons: ~typing.Any | None = None, out_lats: ~typing.Any | None = None, out_azis: ~typing.Any | None = None, return_back_azimuth: bool | None = None) GeodIntermediateReturn [source]¶
Added in version 3.1.0.
Added in version 3.5.0: return_back_azimuth
Given a single initial point and azimuth, number of points (npts) and delimiter distance between two successive points (del_s), returns a list of longitude/latitude pairs describing npts equally spaced intermediate points along the geodesic between the initial and terminus points.
Example usage:
>>> from pyproj import Geod >>> g = Geod(ellps='clrk66') # Use Clarke 1866 ellipsoid. >>> # specify the lat/lons of Boston and Portland. >>> boston_lat = 42.+(15./60.); boston_lon = -71.-(7./60.) >>> portland_lat = 45.+(31./60.); portland_lon = -123.-(41./60.) >>> az12,az21,dist = g.inv(boston_lon,boston_lat,portland_lon,portland_lat) >>> # find ten equally spaced points between Boston and Portland. >>> npts = 10 >>> del_s = dist/(npts+1) >>> r = g.fwd_intermediate(boston_lon,boston_lat,az12,npts=npts,del_s=del_s) >>> for lon,lat in zip(r.lons, r.lats): f'{lat:.3f} {lon:.3f}' '43.528 -75.414' '44.637 -79.883' '45.565 -84.512' '46.299 -89.279' '46.830 -94.156' '47.149 -99.112' '47.251 -104.106' '47.136 -109.100' '46.805 -114.051' '46.262 -118.924' >>> # test with radians=True (inputs/outputs in radians, not degrees) >>> import math >>> dg2rad = math.radians(1.) >>> rad2dg = math.degrees(1.) >>> r = g.fwd_intermediate( ... dg2rad*boston_lon, ... dg2rad*boston_lat, ... dg2rad*az12, ... npts=npts, ... del_s=del_s, ... radians=True ... ) >>> for lon,lat in zip(r.lons, r.lats): f'{rad2dg*lat:.3f} {rad2dg*lon:.3f}' '43.528 -75.414' '44.637 -79.883' '45.565 -84.512' '46.299 -89.279' '46.830 -94.156' '47.149 -99.112' '47.251 -104.106' '47.136 -109.100' '46.805 -114.051' '46.262 -118.924'
- Parameters:
lon1 (float) – Longitude of the initial point
lat1 (float) – Latitude of the initial point
azi1 (float) – Azimuth from the initial point towards the terminus point
npts (int) – Number of points to be returned (including initial and/or terminus points, if required)
del_s (float) – delimiter distance between two successive points
radians (bool, default=False) – If True, the input data is assumed to be in radians. Otherwise, the data is assumed to be in degrees.
initial_idx (int, default=1) – if initial_idx==0 then the initial point would be included in the output (as the first point)
terminus_idx (int, default=1) – if terminus_idx==0 then the terminus point would be included in the output (as the last point)
flags (GeodIntermediateFlag, default=GeodIntermediateFlag.DEFAULT) –
1st - round/ceil/trunc (see
GeodIntermediateFlag.NPTS_*
)- 2nd - update del_s to the new npts or not
(see
GeodIntermediateFlag.DEL_S_*
)
- 3rd - if out_azis=None, indicates if to save or discard the azimuths
(see
GeodIntermediateFlag.AZIS_*
)
default - round npts, update del_s accordingly, discard azis
out_lons (array,
numpy.ndarray
, optional) – Longitude(s) of the intermediate point(s) If None then buffers would be allocated internnalyout_lats (array,
numpy.ndarray
, optional) – Latitudes(s) of the intermediate point(s) If None then buffers would be allocated internnalyout_azis (array,
numpy.ndarray
, optional) – az12(s) of the intermediate point(s) If None then buffers would be allocated internnaly unless requested otherwise by the flagsreturn_back_azimuth (bool, default=True) – if True, out_azis will store the back azimuth, Otherwise, out_azis will store the forward azimuth.
- Returns:
number of points, distance and output arrays (GeodIntermediateReturn docs)
- Return type:
- geometry_area_perimeter(geometry, radians: bool = False) tuple[float, float] [source]¶
Added in version 2.3.0.
A simple interface for computing the area (meters^2) and perimeter (meters) of a geodesic polygon as a shapely geometry.
Arbitrarily complex polygons are allowed. In the case self-intersecting of polygons the area is accumulated “algebraically”, e.g., the areas of the 2 loops in a figure-8 polygon will partially cancel. There’s no need to “close” the polygon by repeating the first vertex.
Note
lats should be in the range [-90 deg, 90 deg].
Warning
The area returned is signed with counter-clockwise (CCW) traversal being treated as positive. For polygons, holes should use the opposite traversal to the exterior (if the exterior is CCW, the holes/interiors should be CW). You can use shapely.ops.orient to modify the orientation.
If it is a Polygon, it will return the area and exterior perimeter. It will subtract the area of the interior holes. If it is a MultiPolygon or MultiLine, it will return the sum of the areas and perimeters of all geometries.
Example usage:
>>> from pyproj import Geod >>> from shapely.geometry import LineString, Point, Polygon >>> geod = Geod(ellps="WGS84") >>> poly_area, poly_perimeter = geod.geometry_area_perimeter( ... Polygon( ... LineString([ ... Point(1, 1), Point(10, 1), Point(10, 10), Point(1, 10) ... ]), ... holes=[LineString([Point(1, 2), Point(3, 4), Point(5, 2)])], ... ) ... ) >>> f"{poly_area:.0f} {poly_perimeter:.0f}" '944373881400 3979008'
- Parameters:
geometry (
shapely.geometry.BaseGeometry
) – The geometry to calculate the area and perimeter from.radians (bool, default=False) – If True, the input data is assumed to be in radians. Otherwise, the data is assumed to be in degrees.
- Returns:
The geodesic area (meters^2) and perimeter (meters) of the polygon.
- Return type:
- geometry_length(geometry, radians: bool = False) float [source]¶
Added in version 2.3.0.
Returns the geodesic length (meters) of the shapely geometry.
If it is a Polygon, it will return the sum of the lengths along the perimeter. If it is a MultiPolygon or MultiLine, it will return the sum of the lengths.
Example usage:
>>> from pyproj import Geod >>> from shapely.geometry import Point, LineString >>> line_string = LineString([Point(1, 2), Point(3, 4)]) >>> geod = Geod(ellps="WGS84") >>> f"{geod.geometry_length(line_string):.3f}" '313588.397'
- Parameters:
geometry (
shapely.geometry.BaseGeometry
) – The geometry to calculate the length from.radians (bool, default=False) – If True, the input data is assumed to be in radians. Otherwise, the data is assumed to be in degrees.
- Returns:
The total geodesic length of the geometry (meters).
- Return type:
- inv(lons1: Any, lats1: Any, lons2: Any, lats2: Any, radians: bool = False, inplace: bool = False, return_back_azimuth: bool = True) tuple[Any, Any, Any] [source]¶
Inverse transformation
Determine forward and back azimuths, plus distances between initial points and terminus points.
Added in version 3.5.0: inplace
Added in version 3.5.0: return_back_azimuth
Accepted numeric scalar or array:
- Parameters:
lons1 (scalar or array) – Longitude(s) of initial point(s)
lats1 (scalar or array) – Latitude(s) of initial point(s)
lons2 (scalar or array) – Longitude(s) of terminus point(s)
lats2 (scalar or array) – Latitude(s) of terminus point(s)
radians (bool, default=False) – If True, the input data is assumed to be in radians. Otherwise, the data is assumed to be in degrees.
inplace (bool, default=False) – If True, will attempt to write the results to the input array instead of returning a new array. This will fail if the input is not an array in C order with the double data type.
return_back_azimuth (bool, default=True) – If True, the second return value (azi21) will be the back azimuth (flipped 180 degrees), Otherwise, it will also be a forward azimuth.
- Returns:
scalar or array – Forward azimuth(s) (azi12)
scalar or array – Back azimuth(s) or Forward azimuth(s) (azi21)
scalar or array – Distance(s) between initial and terminus point(s) in meters
- inv_intermediate(lon1: float, lat1: float, lon2: float, lat2: float, npts: int = 0, del_s: float = 0, initial_idx: int = 1, terminus_idx: int = 1, radians: bool = False, flags: ~pyproj.enums.GeodIntermediateFlag = <GeodIntermediateFlag.DEFAULT: 0>, out_lons: ~typing.Any | None = None, out_lats: ~typing.Any | None = None, out_azis: ~typing.Any | None = None, return_back_azimuth: bool | None = None) GeodIntermediateReturn [source]¶
Added in version 3.1.0.
Added in version 3.5.0: return_back_azimuth
Given a single initial point and terminus point, and the number of points, returns a list of longitude/latitude pairs describing npts equally spaced intermediate points along the geodesic between the initial and terminus points.
npts and del_s parameters are mutually exclusive:
- if npts != 0:
it calculates the distance between the points by the distance between the initial point and the terminus point divided by npts (the number of intermediate points)
- else:
it calculates the number of intermediate points by dividing the distance between the initial and terminus points by del_s (delimiter distance between two successive points)
Similar to npts(), but with more options.
Example usage:
>>> from pyproj import Geod >>> g = Geod(ellps='clrk66') # Use Clarke 1866 ellipsoid. >>> # specify the lat/lons of Boston and Portland. >>> boston_lat = 42.+(15./60.); boston_lon = -71.-(7./60.) >>> portland_lat = 45.+(31./60.); portland_lon = -123.-(41./60.) >>> # find ten equally spaced points between Boston and Portland. >>> r = g.inv_intermediate(boston_lon,boston_lat,portland_lon,portland_lat,10) >>> for lon,lat in zip(r.lons, r.lats): f'{lat:.3f} {lon:.3f}' '43.528 -75.414' '44.637 -79.883' '45.565 -84.512' '46.299 -89.279' '46.830 -94.156' '47.149 -99.112' '47.251 -104.106' '47.136 -109.100' '46.805 -114.051' '46.262 -118.924' >>> # test with radians=True (inputs/outputs in radians, not degrees) >>> import math >>> dg2rad = math.radians(1.) >>> rad2dg = math.degrees(1.) >>> r = g.inv_intermediate( ... dg2rad*boston_lon, ... dg2rad*boston_lat, ... dg2rad*portland_lon, ... dg2rad*portland_lat, ... 10, ... radians=True ... ) >>> for lon,lat in zip(r.lons, r.lats): f'{rad2dg*lat:.3f} {rad2dg*lon:.3f}' '43.528 -75.414' '44.637 -79.883' '45.565 -84.512' '46.299 -89.279' '46.830 -94.156' '47.149 -99.112' '47.251 -104.106' '47.136 -109.100' '46.805 -114.051' '46.262 -118.924'
- Parameters:
lon1 (float) – Longitude of the initial point
lat1 (float) – Latitude of the initial point
lon2 (float) – Longitude of the terminus point
lat2 (float) – Latitude of the terminus point
npts (int, default=0) – Number of points to be returned npts == 0 if del_s != 0
del_s (float, default=0) – delimiter distance between two successive points del_s == 0 if npts != 0
radians (bool, default=False) – If True, the input data is assumed to be in radians. Otherwise, the data is assumed to be in degrees.
initial_idx (int, default=1) – if initial_idx==0 then the initial point would be included in the output (as the first point)
terminus_idx (int, default=1) – if terminus_idx==0 then the terminus point would be included in the output (as the last point)
flags (GeodIntermediateFlag, default=GeodIntermediateFlag.DEFAULT) –
1st - round/ceil/trunc (see
GeodIntermediateFlag.NPTS_*
)- 2nd - update del_s to the new npts or not
(see
GeodIntermediateFlag.DEL_S_*
)
- 3rd - if out_azis=None, indicates if to save or discard the azimuths
(see
GeodIntermediateFlag.AZIS_*
)
default - round npts, update del_s accordingly, discard azis
out_lons (array,
numpy.ndarray
, optional) – Longitude(s) of the intermediate point(s) If None then buffers would be allocated internnalyout_lats (array,
numpy.ndarray
, optional) – Latitudes(s) of the intermediate point(s) If None then buffers would be allocated internnalyout_azis (array,
numpy.ndarray
, optional) – az12(s) of the intermediate point(s) If None then buffers would be allocated internnaly unless requested otherwise by the flagsreturn_back_azimuth (bool, default=True) – if True, out_azis will store the back azimuth, Otherwise, out_azis will store the forward azimuth.
- Returns:
number of points, distance and output arrays (GeodIntermediateReturn docs)
- Return type:
- line_length(lons: Any, lats: Any, radians: bool = False) float [source]¶
Added in version 2.3.0.
Calculate the total distance between points along a line (meters).
>>> from pyproj import Geod >>> geod = Geod('+a=6378137 +f=0.0033528106647475126') >>> lats = [-72.9, -71.9, -74.9, -74.3, -77.5, -77.4, -71.7, -65.9, -65.7, ... -66.6, -66.9, -69.8, -70.0, -71.0, -77.3, -77.9, -74.7] >>> lons = [-74, -102, -102, -131, -163, 163, 172, 140, 113, ... 88, 59, 25, -4, -14, -33, -46, -61] >>> total_length = geod.line_length(lons, lats) >>> f"{total_length:.3f}" '14259605.611'
- Parameters:
lons (array,
numpy.ndarray
, list, tuple, or scalar) – The longitude points along a line.lats (array,
numpy.ndarray
, list, tuple, or scalar) – The latitude points along a line.radians (bool, default=False) – If True, the input data is assumed to be in radians. Otherwise, the data is assumed to be in degrees.
- Returns:
The total length of the line (meters).
- Return type:
- line_lengths(lons: Any, lats: Any, radians: bool = False) Any [source]¶
Added in version 2.3.0.
Calculate the distances between points along a line (meters).
>>> from pyproj import Geod >>> geod = Geod(ellps="WGS84") >>> lats = [-72.9, -71.9, -74.9] >>> lons = [-74, -102, -102] >>> for line_length in geod.line_lengths(lons, lats): ... f"{line_length:.3f}" '943065.744' '334805.010'
- Parameters:
lons (array,
numpy.ndarray
, list, tuple, or scalar) – The longitude points along a line.lats (array,
numpy.ndarray
, list, tuple, or scalar) – The latitude points along a line.radians (bool, default=False) – If True, the input data is assumed to be in radians. Otherwise, the data is assumed to be in degrees.
- Returns:
The total length of the line (meters).
- Return type:
array,
numpy.ndarray
, list, tuple, or scalar
- npts(lon1: float, lat1: float, lon2: float, lat2: float, npts: int, radians: bool = False, initial_idx: int = 1, terminus_idx: int = 1) list [source]¶
Added in version 3.1.0: initial_idx, terminus_idx
Given a single initial point and terminus point, returns a list of longitude/latitude pairs describing npts equally spaced intermediate points along the geodesic between the initial and terminus points.
Similar to inv_intermediate(), but with less options.
Example usage:
>>> from pyproj import Geod >>> g = Geod(ellps='clrk66') # Use Clarke 1866 ellipsoid. >>> # specify the lat/lons of Boston and Portland. >>> boston_lat = 42.+(15./60.); boston_lon = -71.-(7./60.) >>> portland_lat = 45.+(31./60.); portland_lon = -123.-(41./60.) >>> # find ten equally spaced points between Boston and Portland. >>> lonlats = g.npts(boston_lon,boston_lat,portland_lon,portland_lat,10) >>> for lon,lat in lonlats: f'{lat:.3f} {lon:.3f}' '43.528 -75.414' '44.637 -79.883' '45.565 -84.512' '46.299 -89.279' '46.830 -94.156' '47.149 -99.112' '47.251 -104.106' '47.136 -109.100' '46.805 -114.051' '46.262 -118.924' >>> # test with radians=True (inputs/outputs in radians, not degrees) >>> import math >>> dg2rad = math.radians(1.) >>> rad2dg = math.degrees(1.) >>> lonlats = g.npts( ... dg2rad*boston_lon, ... dg2rad*boston_lat, ... dg2rad*portland_lon, ... dg2rad*portland_lat, ... 10, ... radians=True ... ) >>> for lon,lat in lonlats: f'{rad2dg*lat:.3f} {rad2dg*lon:.3f}' '43.528 -75.414' '44.637 -79.883' '45.565 -84.512' '46.299 -89.279' '46.830 -94.156' '47.149 -99.112' '47.251 -104.106' '47.136 -109.100' '46.805 -114.051' '46.262 -118.924'
- Parameters:
lon1 (float) – Longitude of the initial point
lat1 (float) – Latitude of the initial point
lon2 (float) – Longitude of the terminus point
lat2 (float) – Latitude of the terminus point
npts (int) – Number of points to be returned (including initial and/or terminus points, if required)
radians (bool, default=False) – If True, the input data is assumed to be in radians. Otherwise, the data is assumed to be in degrees.
initial_idx (int, default=1) – if initial_idx==0 then the initial point would be included in the output (as the first point)
terminus_idx (int, default=1) – if terminus_idx==0 then the terminus point would be included in the output (as the last point)
- Returns:
list of (lon, lat) points along the geodesic between the initial and terminus points.
- Return type:
list of tuples
- polygon_area_perimeter(lons: Any, lats: Any, radians: bool = False) tuple[float, float] [source]¶
Added in version 2.3.0.
A simple interface for computing the area (meters^2) and perimeter (meters) of a geodesic polygon.
Arbitrarily complex polygons are allowed. In the case self-intersecting of polygons the area is accumulated “algebraically”, e.g., the areas of the 2 loops in a figure-8 polygon will partially cancel. There’s no need to “close” the polygon by repeating the first vertex. The area returned is signed with counter-clockwise traversal being treated as positive.
Note
lats should be in the range [-90 deg, 90 deg].
Example usage:
>>> from pyproj import Geod >>> geod = Geod('+a=6378137 +f=0.0033528106647475126') >>> lats = [-72.9, -71.9, -74.9, -74.3, -77.5, -77.4, -71.7, -65.9, -65.7, ... -66.6, -66.9, -69.8, -70.0, -71.0, -77.3, -77.9, -74.7] >>> lons = [-74, -102, -102, -131, -163, 163, 172, 140, 113, ... 88, 59, 25, -4, -14, -33, -46, -61] >>> poly_area, poly_perimeter = geod.polygon_area_perimeter(lons, lats) >>> f"{poly_area:.1f} {poly_perimeter:.1f}" '13376856682207.4 14710425.4'
- Parameters:
lons (array,
numpy.ndarray
, list, tuple, or scalar) – An array of longitude values.lats (array,
numpy.ndarray
, list, tuple, or scalar) – An array of latitude values.radians (bool, default=False) – If True, the input data is assumed to be in radians. Otherwise, the data is assumed to be in degrees.
- Returns:
The geodesic area (meters^2) and perimeter (meters) of the polygon.
- Return type:
- class pyproj.geod.GeodIntermediateReturn(npts, del_s, dist, lons, lats, azis)¶
Added in version 3.1.0.
Geod Intermediate Return value (Named Tuple)
- Parameters:
- azis¶
Alias for field number 5
- del_s¶
Alias for field number 1
- dist¶
Alias for field number 2
- lats¶
Alias for field number 4
- lons¶
Alias for field number 3
- npts¶
Alias for field number 0