Proj¶

pyproj.Proj is functionally equivalent to the proj command line tool in PROJ.

The PROJ docs say:

The `proj` program is limited to converting between geographic and
projection coordinates within one datum.

pyproj.Proj¶

class pyproj.Proj(projparams: Any = None, preserve_units: bool = True, **kwargs)[source]¶

Bases: pyproj.transformer.Transformer

Performs cartographic transformations. Converts from longitude, latitude to native map projection x,y coordinates and vice versa using PROJ (https://proj.org).

srs¶

The string form of the user input used to create the Proj.

Type: str

crs¶

The CRS object associated with the Proj.

Type: pyproj.crs.CRS

__call__(longitude: Any, latitude: Any, inverse: bool = False, errcheck: bool = False, radians: bool = False) → Tuple[Any, Any][source]¶

Calling a Proj class instance with the arguments lon, lat will convert lon/lat (in degrees) to x/y native map projection coordinates (in meters).

Inputs should be doubles (they will be cast to doubles if they are not, causing a slight performance hit).

Works with numpy and regular python array objects, python sequences and scalars, but is fastest for array objects.

Parameters

longitude (scalar or array (numpy or python)) – Input longitude coordinate(s).
latitude (scalar or array (numpy or python)) – Input latitude coordinate(s).
inverse (boolean, optional) – If inverse is True the inverse transformation from x/y to lon/lat is performed. Default is False.
radians (boolean, optional) – If True, will expect input data to be in radians and will return radians if the projection is geographic. Default is False (degrees). This does not work with pyproj 2 and is ignored. It will be enabled again in pyproj 3.
errcheck (boolean, optional) – If True an exception is raised if the errors are found in the process. By default errcheck=False and inf is returned.

Returns

The transformed coordinates.

Return type

Tuple[Any, Any]

__init__(projparams: Any = None, preserve_units: bool = True, **kwargs) → None[source]¶

A Proj class instance is initialized with proj map projection control parameter key/value pairs. The key/value pairs can either be passed in a dictionary, or as keyword arguments, or as a PROJ string (compatible with the proj command). See https://proj.org/operations/projections/index.html for examples of key/value pairs defining different map projections.

Parameters

projparams (int, str, dict, pyproj.CRS) – A PROJ or WKT string, PROJ dict, EPSG integer, or a pyproj.CRS instance.
preserve_units (bool) – If false, will ensure +units=m.
**kwargs – PROJ projection parameters.

Example usage:

>>> from pyproj import Proj
>>> p = Proj(proj='utm',zone=10,ellps='WGS84', preserve_units=False)
>>> x,y = p(-120.108, 34.36116666)
>>> 'x=%9.3f y=%11.3f' % (x,y)
'x=765975.641 y=3805993.134'
>>> 'lon=%8.3f lat=%5.3f' % p(x,y,inverse=True)
'lon=-120.108 lat=34.361'
>>> # do 3 cities at a time in a tuple (Fresno, LA, SF)
>>> lons = (-119.72,-118.40,-122.38)
>>> lats = (36.77, 33.93, 37.62 )
>>> x,y = p(lons, lats)
>>> 'x: %9.3f %9.3f %9.3f' % x
'x: 792763.863 925321.537 554714.301'
>>> 'y: %9.3f %9.3f %9.3f' % y
'y: 4074377.617 3763936.941 4163835.303'
>>> lons, lats = p(x, y, inverse=True) # inverse transform
>>> 'lons: %8.3f %8.3f %8.3f' % lons
'lons: -119.720 -118.400 -122.380'
>>> 'lats: %8.3f %8.3f %8.3f' % lats
'lats:   36.770   33.930   37.620'
>>> p2 = Proj('+proj=utm +zone=10 +ellps=WGS84', preserve_units=False)
>>> x,y = p2(-120.108, 34.36116666)
>>> 'x=%9.3f y=%11.3f' % (x,y)
'x=765975.641 y=3805993.134'
>>> p = Proj("epsg:32667", preserve_units=False)
>>> 'x=%12.3f y=%12.3f (meters)' % p(-114.057222, 51.045)
'x=-1783506.250 y= 6193827.033 (meters)'
>>> p = Proj("epsg:32667")
>>> 'x=%12.3f y=%12.3f (feet)' % p(-114.057222, 51.045)
'x=-5851386.754 y=20320914.191 (feet)'
>>> # test data with radian inputs
>>> p1 = Proj("epsg:4214")
>>> x1, y1 = p1(116.366, 39.867)
>>> f'{x1:.3f} {y1:.3f}'
'116.366 39.867'
>>> x2, y2 = p1(x1, y1, inverse=True)
>>> f'{x2:.3f} {y2:.3f}'
'116.366 39.867'

property accuracy¶

Expected accuracy of the transformation. -1 if unknown.

Type: float

property area_of_use¶

New in version 2.3.0.

Returns: The area of use object with associated attributes.
Return type: AreaOfUse

property definition¶

Definition of the projection.

Type: str

definition_string() → str[source]¶

Returns formal definition string for projection

>>> Proj("epsg:4326").definition_string()
'proj=longlat datum=WGS84 no_defs ellps=WGS84 towgs84=0,0,0'

property description¶

Description of the projection.

Type: str

static from_crs(crs_from: Any, crs_to: Any, skip_equivalent: bool = False, always_xy: bool = False, area_of_interest: Optional[pyproj.aoi.AreaOfInterest] = None) → pyproj.transformer.Transformer ¶

Make a Transformer from a pyproj.crs.CRS or input used to create one.

New in version 2.1.2: skip_equivalent

New in version 2.2.0: always_xy

New in version 2.3.0: area_of_interest

Parameters

crs_from (pyproj.crs.CRS or input used to create one) – Projection of input data.
crs_to (pyproj.crs.CRS or input used to create one) – Projection of output data.
skip_equivalent (bool, optional) – If true, will skip the transformation operation if input and output projections are equivalent. Default is false.
always_xy (bool, optional) – If true, the transform method will accept as input and return as output coordinates using the traditional GIS order, that is longitude, latitude for geographic CRS and easting, northing for most projected CRS. Default is false.
area_of_interest (pyproj.transformer.AreaOfInterest, optional) – The area of interest to help select the transformation.

Returns

Return type

Transformer

static from_pipeline(proj_pipeline: str) → pyproj.transformer.Transformer ¶

Make a Transformer from a PROJ pipeline string.

https://proj.org/operations/pipeline.html

Parameters: proj_pipeline (str) – Projection pipeline string.
Returns
Return type: Transformer

static from_proj(proj_from: Any, proj_to: Any, skip_equivalent: bool = False, always_xy: bool = False, area_of_interest: Optional[pyproj.aoi.AreaOfInterest] = None) → pyproj.transformer.Transformer ¶

Make a Transformer from a pyproj.Proj or input used to create one.

New in version 2.1.2: skip_equivalent

New in version 2.2.0: always_xy

New in version 2.3.0: area_of_interest

Parameters

proj_from (pyproj.Proj or input used to create one) – Projection of input data.
proj_to (pyproj.Proj or input used to create one) – Projection of output data.
skip_equivalent (bool, optional) – If true, will skip the transformation operation if input and output projections are equivalent. Default is false.
always_xy (bool, optional) – If true, the transform method will accept as input and return as output coordinates using the traditional GIS order, that is longitude, latitude for geographic CRS and easting, northing for most projected CRS. Default is false.
area_of_interest (pyproj.transformer.AreaOfInterest, optional) – The area of interest to help select the transformation.

Returns

Return type

Transformer

get_factors(longitude: Any, latitude: Any, radians: bool = False, errcheck: bool = False) → importlib._bootstrap.Factors[source]¶

New in version 2.6.0.

Calculate various cartographic properties, such as scale factors, angular distortion and meridian convergence. Depending on the underlying projection values will be calculated either numerically (default) or analytically.

The function also calculates the partial derivatives of the given coordinate.

Parameters

longitude (scalar or array (numpy or python)) – Input longitude coordinate(s).
latitude (scalar or array (numpy or python)) – Input latitude coordinate(s).
radians (boolean, optional) – If True, will expect input data to be in radians. Default is False (degrees).
errcheck (boolean, optional) – If True an exception is raised if the errors are found in the process. By default errcheck=False and inf is returned.

Returns

Return type

Factors

property has_inverse¶

True if an inverse mapping exists.

Type: bool

property is_network_enabled¶

New in version 3.0.0.

bool:: If the network is enabled.

itransform(points: Any, switch: bool = False, time_3rd: bool = False, radians: bool = False, errcheck: bool = False, direction: Union[pyproj.enums.TransformDirection, str] = <TransformDirection.FORWARD: 'FORWARD'>) → Iterator[Iterable]¶

Iterator/generator version of the function pyproj.Transformer.transform.

New in version 2.1.1: errcheck

New in version 2.2.0: direction

Parameters

points (list) – List of point tuples.
switch (boolean, optional) – If True x, y or lon,lat coordinates of points are switched to y, x or lat, lon. Default is False.
time_3rd (boolean, optional) – If the input coordinates are 3 dimensional and the 3rd dimension is time.
radians (boolean, optional) – If True, will expect input data to be in radians and will return radians if the projection is geographic. Default is False (degrees). Ignored for pipeline transformations.
errcheck (boolean, optional) – If True an exception is raised if the transformation is invalid. By default errcheck=False and an invalid transformation returns inf and no exception is raised.
direction (pyproj.enums.TransformDirection, optional) – The direction of the transform. Default is pyproj.enums.TransformDirection.FORWARD.

Example:

>>> from pyproj import Transformer
>>> transformer = Transformer.from_crs(4326, 2100)
>>> points = [(22.95, 40.63), (22.81, 40.53), (23.51, 40.86)]
>>> for pt in transformer.itransform(points): '{:.3f} {:.3f}'.format(*pt)
'2221638.801 2637034.372'
'2212924.125 2619851.898'
'2238294.779 2703763.736'
>>> pipeline_str = (
...     "+proj=pipeline +step +proj=longlat +ellps=WGS84 "
...     "+step +proj=unitconvert +xy_in=rad +xy_out=deg"
... )
>>> pipe_trans = Transformer.from_pipeline(pipeline_str)
>>> for pt in pipe_trans.itransform([(2.1, 0.001)]):
...     '{:.3f} {:.3f}'.format(*pt)
'2.100 0.001'
>>> transproj = Transformer.from_crs(
...     {"proj":'geocent', "ellps":'WGS84', "datum":'WGS84'},
...     "EPSG:4326",
...     always_xy=True,
... )
>>> for pt in transproj.itransform(
...     [(-2704026.010, -4253051.810, 3895878.820)],
...     radians=True,
... ):
...     '{:.3f} {:.3f} {:.3f}'.format(*pt)
'-2.137 0.661 -20.531'
>>> transprojr = Transformer.from_crs(
...     "EPSG:4326",
...     {"proj":'geocent', "ellps":'WGS84', "datum":'WGS84'},
...     always_xy=True,
... )
>>> for pt in transprojr.itransform(
...     [(-2.137, 0.661, -20.531)],
...     radians=True
... ):
...     '{:.3f} {:.3f} {:.3f}'.format(*pt)
'-2704214.394 -4254414.478 3894270.731'
>>> transproj_eq = Transformer.from_proj(
...     'EPSG:4326',
...     '+proj=longlat +datum=WGS84 +no_defs +type=crs',
...     always_xy=True,
...     skip_equivalent=True
... )
>>> for pt in transproj_eq.itransform([(-2.137, 0.661)]):
...     '{:.3f} {:.3f}'.format(*pt)
'-2.137 0.661'

property name¶

Name of the projection.

Type: str

property operations¶

New in version 2.4.0.

Returns: The operations in a concatenated operation.
Return type: Tuple[CoordinateOperation]

property remarks¶

New in version 2.4.0.

Returns: Remarks about object.
Return type: str

property scope¶

New in version 2.4.0.

Returns: Scope of object.
Return type: str

to_json(pretty: bool = False, indentation: int = 2) → str¶

Convert the projection to a JSON string.

New in version 2.4.0.

Parameters

pretty (bool) – If True, it will set the output to be a multiline string. Defaults to False.
indentation (int) – If pretty is True, it will set the width of the indentation. Default is 2.

Returns

The JSON string.

Return type

str

to_json_dict() → dict¶

Convert the projection to a JSON dictionary.

New in version 2.4.0.

Returns: The JSON dictionary.
Return type: dict

to_latlong() → pyproj.proj.Proj[source]¶: return a new Proj instance which is the geographic (lat/lon) coordinate version of the current projection

to_latlong_def() → Optional[str][source]¶: return the definition string of the geographic (lat/lon) coordinate version of the current projection

to_wkt(version: Union[pyproj.enums.WktVersion, str] = <WktVersion.WKT2_2019: 'WKT2_2019'>, pretty: bool = False)¶

Convert the projection to a WKT string.

Version options:

WKT2_2015
WKT2_2015_SIMPLIFIED
WKT2_2019
WKT2_2019_SIMPLIFIED
WKT1_GDAL
WKT1_ESRI

Parameters

version (pyproj.enums.WktVersion) – The version of the WKT output. Default is pyproj.enums.WktVersion.WKT2_2019.
pretty (bool) – If True, it will set the output to be a multiline string. Defaults to False.

Returns

The WKT string.

Return type

str

transform(xx: Any, yy: Any, zz: Any = None, tt: Any = None, radians: bool = False, errcheck: bool = False, direction: Union[pyproj.enums.TransformDirection, str] = <TransformDirection.FORWARD: 'FORWARD'>) → Any¶

Transform points between two coordinate systems.

New in version 2.1.1: errcheck

New in version 2.2.0: direction

Parameters

xx (scalar or array (numpy or python)) – Input x coordinate(s).
yy (scalar or array (numpy or python)) – Input y coordinate(s).
zz (scalar or array (numpy or python), optional) – Input z coordinate(s).
tt (scalar or array (numpy or python), optional) – Input time coordinate(s).
radians (boolean, optional) – If True, will expect input data to be in radians and will return radians if the projection is geographic. Default is False (degrees). Ignored for pipeline transformations with pyproj 2, but will work in pyproj 3.
errcheck (boolean, optional) – If True an exception is raised if the transformation is invalid. By default errcheck=False and an invalid transformation returns inf and no exception is raised.
direction (pyproj.enums.TransformDirection, optional) – The direction of the transform. Default is pyproj.enums.TransformDirection.FORWARD.

Example:

>>> from pyproj import Transformer
>>> transformer = Transformer.from_crs("epsg:4326", "epsg:3857")
>>> x3, y3 = transformer.transform(33, 98)
>>> f"{x3:.3f}  {y3:.3f}"
'10909310.098  3895303.963'
>>> pipeline_str = (
...     "+proj=pipeline +step +proj=longlat +ellps=WGS84 "
...     "+step +proj=unitconvert +xy_in=rad +xy_out=deg"
... )
>>> pipe_trans = Transformer.from_pipeline(pipeline_str)
>>> xt, yt = pipe_trans.transform(2.1, 0.001)
>>> f"{xt:.3f}  {yt:.3f}"
'2.100  0.001'
>>> transproj = Transformer.from_crs(
...     {"proj":'geocent', "ellps":'WGS84', "datum":'WGS84'},
...     "EPSG:4326",
...     always_xy=True,
... )
>>> xpj, ypj, zpj = transproj.transform(
...     -2704026.010,
...     -4253051.810,
...     3895878.820,
...     radians=True,
... )
>>> f"{xpj:.3f} {ypj:.3f} {zpj:.3f}"
'-2.137 0.661 -20.531'
>>> transprojr = Transformer.from_crs(
...     "EPSG:4326",
...     {"proj":'geocent', "ellps":'WGS84', "datum":'WGS84'},
...     always_xy=True,
... )
>>> xpjr, ypjr, zpjr = transprojr.transform(xpj, ypj, zpj, radians=True)
>>> f"{xpjr:.3f} {ypjr:.3f} {zpjr:.3f}"
'-2704026.010 -4253051.810 3895878.820'
>>> transformer = Transformer.from_proj("epsg:4326", 4326, skip_equivalent=True)
>>> xeq, yeq = transformer.transform(33, 98)
>>> f"{xeq:.0f}  {yeq:.0f}"
'33  98'

pyproj.proj.Factors¶

class pyproj.proj.Factors(meridional_scale, parallel_scale, areal_scale, angular_distortion, meridian_parallel_angle, meridian_convergence, tissot_semimajor, tissot_semiminor, dx_dlam, dx_dphi, dy_dlam, dy_dphi)¶

New in version 2.6.0.

These are the scaling and angular distortion factors.

See PJ_FACTORS documentation # noqa

Parameters

meridional_scale (List[float]) – Meridional scale at coordinate.
parallel_scale (List[float]) – Parallel scale at coordinate.
areal_scale (List[float]) – Areal scale factor at coordinate.
angular_distortion (List[float]) – Angular distortion at coordinate.
meridian_parallel_angle (List[float]) – Meridian/parallel angle at coordinate.
meridian_convergence (List[float]) – Meridian convergence at coordinate. Sometimes also described as grid declination.
tissot_semimajor (List[float]) – Maximum scale factor.
tissot_semiminor (List[float]) – Minimum scale factor.
dx_dlam (List[float]) – Partial derivative of coordinate.
dx_dphi (List[float]) – Partial derivative of coordinate.
dy_dlam (List[float]) – Partial derivative of coordinate.
dy_dphi (List[float]) – Partial derivative of coordinate.

property angular_distortion¶: Alias for field number 3

property areal_scale¶: Alias for field number 2

property dx_dlam¶: Alias for field number 8

property dx_dphi¶: Alias for field number 9

property dy_dlam¶: Alias for field number 10

property dy_dphi¶: Alias for field number 11

property meridian_convergence¶: Alias for field number 5

property meridian_parallel_angle¶: Alias for field number 4

property meridional_scale¶: Alias for field number 0

property parallel_scale¶: Alias for field number 1

property tissot_semimajor¶: Alias for field number 6

property tissot_semiminor¶: Alias for field number 7