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