1.. _gotchas: 2 3Gotchas/FAQ 4=========== 5 6This is a page for some suggestions, gotchas, and FAQs. 7 8Also see: 9 - :ref:`examples` 10 - :ref:`PROJ FAQ <faq>` 11 12 13What are the best formats to store the CRS information? 14-------------------------------------------------------- 15 16In general, `Well-Known Text (WKT) <https://en.wikipedia.org/wiki/Well-known_text_representation_of_coordinate_reference_systems>`__ 17or `Spatial Reference ID 18(SRID) <https://en.wikipedia.org/wiki/Spatial_reference_system>`__, such as EPSG 19codes, are the preferred formats to describe a CRS. 20 21.. note:: WKT2 is preferred over WKT1. 22 23PROJ strings can be lossy for storing CRS information. 24If you can avoid it, it is best to not use them. 25Additionally, PROJ strings will likely not be supported 26in future major version of PROJ for storing CRS information. 27 28More info: https://proj.org/faq.html#what-is-the-best-format-for-describing-coordinate-reference-systems 29 30 31Axis order changes in PROJ 6+ 32----------------------------- 33- https://proj.org/faq.html#why-is-the-axis-ordering-in-proj-not-consistent 34- See warning at the top of :ref:`transformer` 35- Examples of how to handle it: :ref:`examples` 36- :ref:`min_confidence` 37 38 39`+init=<auth>:<auth_code>` should be replaced with `<auth>:<auth_code>` 40----------------------------------------------------------------------- 41 42The `+init=<auth>:<auth_code>` syntax is deprecated and will be removed 43in future versions of PROJ. Also, if you use the `+init` syntax, 44you may have problems initializing projections when the other syntax works. 45 46.. code-block:: python 47 48 >>> from pyproj import CRS 49 >>> CRS("ESRI:54009") 50 <Projected CRS: ESRI:54009> 51 Name: World_Mollweide 52 Axis Info [cartesian]: 53 - E[east]: Easting (metre) 54 - N[north]: Northing (metre) 55 Area of Use: 56 - name: World 57 - bounds: (-180.0, -90.0, 180.0, 90.0) 58 Coordinate Operation: 59 - name: World_Mollweide 60 - method: Mollweide 61 Datum: World Geodetic System 1984 62 - Ellipsoid: WGS 84 63 - Prime Meridian: Greenwich 64 65 >>> CRS("+init=ESRI:54009") 66 ... 67 pyproj.exceptions.CRSError: Invalid projection: +init=ESRI:54009 +type=crs: (Internal Proj Error: proj_create: cannot expand +init=ESRI:54009 +type=crs) 68 69 70Proj (Not a generic latitude/longitude to projection converter) 71--------------------------------------------------------------- 72 73:class:`pyproj.Proj` is limited to converting between geographic and 74projection coordinates within one datum. If you have coordinates in latitude 75and longitude, and you want to convert it to your projection, it is recommended 76to use the :class:`pyproj.transformer.Transformer` as it takes into account datum 77shifts. 78 79You likely want to start from `EPSG:4326` (WGS84) for coordinates as 80latitude and longitude. 81 82.. code-block:: python 83 84 >>> from pyproj import CRS 85 >>> crs_4326 = CRS("WGS84") 86 >>> crs_4326 87 <Geographic 2D CRS: EPSG:4326> 88 Name: WGS 84 89 Axis Info [ellipsoidal]: 90 - Lat[north]: Geodetic latitude (degree) 91 - Lon[east]: Geodetic longitude (degree) 92 Area of Use: 93 - name: World 94 - bounds: (-180.0, -90.0, 180.0, 90.0) 95 Datum: World Geodetic System 1984 96 - Ellipsoid: WGS 84 97 - Prime Meridian: Greenwich 98 99Then, use the :class:`pyproj.transformer.Transformer` to transform from latitude 100and longitude to your projection as you might have a projection with a different 101datum. 102 103.. code-block:: python 104 105 >>> crs_proj = CRS("EPSG:28992") 106 >>> crs_proj 107 <Projected CRS: EPSG:28992> 108 Name: Amersfoort / RD New 109 Axis Info [cartesian]: 110 - X[east]: Easting (metre) 111 - Y[north]: Northing (metre) 112 Area of Use: 113 - name: Netherlands - onshore. 114 - bounds: (3.2, 50.75, 7.22, 53.7) 115 Coordinate Operation: 116 - name: RD New 117 - method: Oblique Stereographic 118 Datum: Amersfoort 119 - Ellipsoid: Bessel 1841 120 - Prime Meridian: Greenwich 121 >>> crs_proj.datum == crs_4326.datum 122 False 123 >>> from pyproj import Transformer 124 >>> transformer = Transformer.from_crs(crs_4326, crs_proj) 125 >>> transformer.transform(52.067567, 5.068913) 126 (133175.3690698233, 453300.86739169655) 127 128If you use :class:`pyproj.Proj`, it will use the geodetic CRS with 129from the projected CRS with the same datum to do the transformation, 130which may not be what you want. 131 132.. code-block:: python 133 134 >>> from pyproj import Proj 135 >>> Proj('epsg:28992')(5.068913, 52.067567) 136 (133148.22970574044, 453192.24450392975) 137 >>> transg = Transformer.from_crs(crs_proj.geodetic_crs, crs_proj) 138 >>> transg.transform(52.067567, 5.068913) 139 (133148.22970574044, 453192.24450392975) 140 141 142.. _min_confidence: 143 144Why does the EPSG code return when using `EPSG:xxxx` and not with `+init=EPSG:xxxx`? 145------------------------------------------------------------------------------------ 146 147From: https://gis.stackexchange.com/a/326919/144357 148 149 150The reason that the EPSG code does not appear with the CRS initialized with 151the `init=` syntax is that the CRS are different. 152 153.. code-block:: python 154 155 >>> from pyproj import CRS 156 >>> crs_deprecated = CRS(init="epsg:4544") 157 >>> crs = CRS("epsg:4544") 158 >>> crs == crs_deprecated 159 False 160 161Upon further inspection of the `Axis Info` section, you can see that the difference 162is in the **axis order**. 163 164.. code-block:: python 165 166 >>> crs_deprecated 167 <Projected CRS: +init=epsg:4544 +type=crs> 168 Name: CGCS2000 / 3-degree Gauss-Kruger CM 105E 169 Axis Info [cartesian]: 170 - E[east]: Easting (metre) 171 - N[north]: Northing (metre) 172 Area of Use: 173 - name: China - 103.5°E to 106.5°E 174 - bounds: (103.5, 22.5, 106.5, 42.21) 175 Coordinate Operation: 176 - name: Gauss-Kruger CM 105E 177 - method: Transverse Mercator 178 Datum: China 2000 179 - Ellipsoid: CGCS2000 180 - Prime Meridian: Greenwich 181 182 >>> crs 183 <Projected CRS: EPSG:4544> 184 Name: CGCS2000 / 3-degree Gauss-Kruger CM 105E 185 Axis Info [cartesian]: 186 - X[north]: Northing (metre) 187 - Y[east]: Easting (metre) 188 Area of Use: 189 - name: China - 103.5°E to 106.5°E 190 - bounds: (103.5, 22.5, 106.5, 42.21) 191 Coordinate Operation: 192 - name: Gauss-Kruger CM 105E 193 - method: Transverse Mercator 194 Datum: China 2000 195 - Ellipsoid: CGCS2000 196 - Prime Meridian: Greenwich 197 198 199The reason the `min_confidence` parameter in 200:meth:`pyproj.crs.CRS.to_epsg` and :meth:`pyproj.crs.CRS.to_authority` 201exists is because you can initialize a CRS in several different methods and 202some of them do not always coorespond to an EPSG or authortiy code, but it 203can be close enough. 204 205For example, if you have a WKT/PROJ string and you use it to create the CRS instance, 206in most cases you want to be sure that the EPSG code given by to_epsg will give you a 207CRS instance similar to the one created by the WKT/PROJ string. 208However, if an EPSG code does not exist that matches you WKT/PROJ string with 209a `min_confidence` you don't want to get that EPSG code back as it will make 210you think that the WKT/PROJ string and the EPSG code are one and the same when 211they are not. 212 213However, if you are only wanting to get the EPSG code that is closest 214to the PROJ/WKT string, then you can reduce your min_confidence to a 215threshold you are comfortable with. 216 217Here is an example of that: 218 219.. code-block:: python 220 221 >>> crs_deprecated = CRS("+init=epsg:4326") 222 >>> crs_deprecated.to_epsg(100) 223 >>> crs_deprecated.to_epsg(70) 224 >>> crs_deprecated.to_epsg(20) 225 4326 226 >>> crs_latlon = CRS("+proj=latlon") 227 >>> crs_latlon.to_epsg(100) 228 >>> crs_latlon.to_epsg(70) 229 4326 230 >>> crs_epsg = CRS.from_epsg(4326) 231 >>> crs_epsg.to_epsg(100) 232 4326 233 >>> crs_wkt = CRS(crs_epsg.to_wkt()) 234 >>> crs_wkt.to_epsg(100) 235 4326 236 >>> crs_wkt == crs_epsg 237 True 238 >>> crs_epsg == crs_latlon 239 False 240 >>> crs_epsg == crs_deprecated 241 False 242 243 244Internal PROJ Error ... SQLite error on SELECT 245---------------------------------------------- 246 247The PROJ database is based on the EPSG database. With each release, 248there is a good chance that there are database updates. If you have multiple 249versions of PROJ installed on your systems and the search path for 250the data directory becomes mixed up, you may see an error message like: 251`SQLite error on SELECT`. This is likely due to a version of PROJ 252attempting to use an incompatible database. 253 254 255Debugging tips: 256 257- To get data directory being used: :func:`pyproj.datadir.get_data_dir` 258- The order for searching for the data directory can be found in 259 the docstrings of :func:`pyproj.datadir.get_data_dir` 260- To change the data directory: :func:`pyproj.datadir.set_data_dir` 261 262 263.. _upgrade_transformer: 264 265Upgrading to pyproj 2 from pyproj 1 266----------------------------------- 267 268We recommended using the :class:`pyproj.transformer.Transformer` and 269:class:`pyproj.crs.CRS` in place of the :class:`pyproj.Proj` and 270:meth:`pyproj.transformer.transform`. 271 272Also see: 273 - :ref:`examples` 274 - :ref:`optimize_transformations` 275 276.. warning:: :meth:`pyproj.transformer.transform` and :meth:`pyproj.transformer.itransform` 277 are deprecated. 278 279pyproj 1 style: 280 281 >>> from functools import partial 282 >>> from pyproj import Proj, transform 283 >>> proj_4326 = Proj(init="epsg:4326") 284 >>> proj_3857 = Proj(init="epsg:3857") 285 >>> transformer = partial(transform, proj_4326, proj_3857) 286 >>> transformer(12, 12) 287 288 289pyproj 2 style: 290 291 >>> from pyproj import Transformer 292 >>> transformer = Transformer.from_crs("epsg:4326", "epsg:3857") 293 >>> transformer.transform(12, 12) 294