diff options
Diffstat (limited to 'docs/source/faq.rst')
| -rw-r--r-- | docs/source/faq.rst | 260 |
1 files changed, 54 insertions, 206 deletions
diff --git a/docs/source/faq.rst b/docs/source/faq.rst index 21fe158b..d6f118ce 100644 --- a/docs/source/faq.rst +++ b/docs/source/faq.rst @@ -10,208 +10,73 @@ FAQ :depth: 3 :backlinks: none - - -Where can I find the list of projections and their arguments? +Which file formats does PROJ support? -------------------------------------------------------------------------------- -:doc:`Here<../operations/projections/index>`. +The :ref:`command line applications <apps>` that come with PROJ only support text +input and output (apart from :program:`proj` which accepts a simple binary data +stream as well). :program:`proj`, :program:`cs2cs` and :program:`cct` expects +text files with one coordinate per line with each coordinate dimension in a +separate column. + +.. note:: -Additionally, the :program:`proj` command itself can report the list of projections -using the ``-lp`` option, the list of ellipsoids with the ``-le`` option, -the list of units with the ``-lu`` option, and the list of built-in datums with -the ``-ld`` option. + If your data is stored in a common geodata file format chances are that + you can use `GDAL <https://gdal.org/>`_ as a frontend to PROJ and transform your data with the + :program:`ogr2ogr` application. -How do I do datum shifts between NAD27 and NAD83? +Can I transform from *abc* to *xyz*? -------------------------------------------------------------------------------- -Using the :program:`cs2cs` application. The following example demonstrates using the -default shift parameters for NAD27 to NAD83: - -:: +Probably. PROJ supports transformations between most coordinate reference systems +registered in the EPSG registry, as well as a number of other coordinate reference +systems. The best way to find out is to test it with the :program:`projinfo` +application. Here's an example checking if there's a transformation between +ETRS89/UTM32N (EPSG:25832) and ETRS89/DKTM1 (EPSG:4093): - % cs2cs +proj=latlong +datum=NAD27 +to +proj=latlong +datum=NAD83 -117 30 +.. code-block:: console -producing: + $ ./projinfo -s EPSG:25832 -t EPSG:4093 -o PROJ + Candidate operations found: 1 + ------------------------------------- + Operation n°1: -:: + unknown id, Inverse of UTM zone 32N + DKTM1, 0 m, World - 117d0'2.901"W 30d0'0.407"N 0.000 + PROJ string: + +proj=pipeline +step +inv +proj=utm +zone=32 +ellps=GRS80 + +step +proj=tmerc +lat_0=0 +lon_0=9 +k=0.99998 +x_0=200000 +y_0=-5000000 +ellps=GRS80 -In order for datum shifting to work properly the various grid shift files must -be available. See below. More details are available in the -section on :doc:`resource files<resource_files>`. +See the :program:`projinfo` :ref:`documentation <projinfo>` for more info on +how to use it. -How do I build/configure PROJ to support datum shifting? +Coordinate reference system *xyz* is not in the EPSG registry, what do I do? -------------------------------------------------------------------------------- -After downloading and unpacking the PROJ source, also download and unpack the -set of datum shift files. See :ref:`download` for instructions how to fetch -and install these files. +Generally PROJ will accept coordinate reference system descriptions in the form +of WKT, WKT2 and PROJ strings. If you are able to describe your desired CRS +in either of those formats there's a good chance that PROJ will be able to make +sense of it. -A default build and install on Unix will normally build knowledge of the -directory where the grid shift files are installed into the PROJ library -(usually ``/usr/local/share/proj``). On Windows the library is normally built -thinking that C:\PROJ\NAD is the installed directory for the grid shift files. -If the built-in concept of the PROJ data directory is incorrect, the :envvar:`PROJ_LIB` -environment variable can be defined with the correct directory. +If it is important to you that a given CRS is added to the EPSG registry, you +should contact your local geodetic authority and ask them to submit the CRS for +inclusion in the registry. -How do I debug problems with NAD27/NAD83 datum shifting? +I found a bug in PROJ, how do I get it fixed? -------------------------------------------------------------------------------- -1. Verify that you have the binary files (e.g. ``/usr/local/share/proj/conus``) - installed on your system. If not, see the previous question. -2. Try a datum shifting operation in relative isolation, such as with the :program:`cs2cs` - command listed above. Do you get reasonable results? If not, it is likely that - the grid shift files aren't being found. Perhaps you need to define - :envvar:`PROJ_LIB`? -3. The :program:`cs2cs` command and the underlying :c:func:`pj_transform()` API know how to do a - grid shift as part of a more complex coordinate transformation; however, it - is imperative that both the source and destination coordinate system be - defined with appropriate datum information. That means that implicitly or - explicitly there must be a ``+datum=`` clause, a ``+nadgrids=`` clause or a - ``+towgs84=`` clause. For instance - ``cs2cs +proj=latlong +datum=NAD27 +to +proj=latlong +ellps=WGS84`` won't work because defining the output - coordinate system as using the ellipse WGS84 isn't the same as defining it - to use the datum WGS84 (use ``+datum=WGS84``). If either the input or output - are not identified as having a datum, the datum shifting (and ellipsoid - change) step is just quietly skipped! -4. The :envvar:`PROJ_DEBUG` environment can be defined (any value) to force extra output - from the PROJ library to stderr (the text console normally) with - information on what data files are being opened and in some cases why a - transformation fails. - - :: - - export PROJ_DEBUG=ON - cs2cs ... - - - .. note:: - ``PROJ_DEBUG`` support is not yet very mature in the PROJ library. - -5. The :option:`-v` flag to :program:`cs2cs` can be useful in establishing more detail on what - parameters are used internally for a coordinate system. This will include - expanding the definition of ``+datum`` clause. - -How do I use EPSG coordinate system codes with PROJ? --------------------------------------------------------------------------------- +Please report bugs that you find to the issue tracker on GitHub. :ref:`Here's how +<add_bug_report>`. -There is somewhat imperfect translation between 2D geographic and projected -coordinate system codes and PROJ descriptions of the coordinate systems -available in the ``epsg`` definition file that normally lives in the ``proj/data`` -directory. If installed (as is the default on Unix), it is possible -to use EPSG numbers like this: - -:: - - - % cs2cs -v +init=epsg:26711 - # ---- From Coordinate System ---- - #Universal Transverse Mercator (UTM) - # Cyl, Sph - # zone= south - # +init=epsg:26711 +proj=utm +zone=11 +ellps=clrk66 +datum=NAD27 +units=m - # +no_defs +nadgrids=conus,ntv1_can.dat - #--- following specified but NOT used - # +ellps=clrk66 - # ---- To Coordinate System ---- - #Lat/long (Geodetic) - # - # +proj=latlong +datum=NAD27 +ellps=clrk66 +nadgrids=conus,ntv1_can.dat - -The ``proj/data/epsg`` file can be browsed and searched for coordinate systems -using a text editor. There are known to be problems with some coordinate -systems. In particular, any coordinate system with odd axes, a non-greenwich prime -meridian, or other quirky characteristics is unlikely to work properly. Caveat Emptor! - -How do I use 3 parameter and 7 parameter datum shifting --------------------------------------------------------------------------------- - -Datum shifts can be approximated with 3 and 7 parameter transformations. Their -use with :program:`cs2cs` is more fully described in the -:ref:`geodetic transformation<cs2cs_specific_options>` section. - -More generically, the :ref:`helmert` can be used with :program:`cct`. +If you know how to program you can also try to fix it yourself. You are welcome +to ask for guidance on one of the :ref:`communication channels <channels>` used +by the project. - -Does PROJ work in different international numeric locales? +How do I contribute to PROJ? -------------------------------------------------------------------------------- -No. PROJ makes extensive use of the :c:func:`sprintf()` and :c:func:`atof()` C functions -internally to translate numeric values. If a locale is in effect that modifies -formatting of numbers, altering the role of commas and periods in numbers, then -PROJ will not work. This problem is common in some European locales. - -On UNIX-like platforms, this problem can be avoided by forcing the use of the -default numeric locale by setting the :envvar:`LC_NUMERIC` environment variable to ``C``. - -:: - - $ export LC_NUMERIC=C - $ proj ... - -.. note:: - - NOTE: Per ticket #49, in PROJ 4.7.0 and later pj_init() operates with locale - overridden to "C" to avoid most locale specific processing for applications - using the API. Command line tools may still have issues. - -Changing Ellipsoid / Why can't I convert from WGS84 to Google Earth / Virtual Globe Mercator? ----------------------------------------------------------------------------------------------- - -The coordinate system definition for Google Earth and Virtual Globe Mercator -is as follows, which uses a sphere as the earth model for the Mercator -projection. - -:: - - +proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 - +x_0=0.0 +y_0=0 +k=1.0 +units=m +no_defs - -But, if you do something like: - -:: - - cs2cs +proj=latlong +datum=WGS84 - +to +proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 - +x_0=0.0 +y_0=0 +k=1.0 +units=m +no_defs - -to convert between WGS84 and Mercator on the sphere there will be substantial -shifts in the Y Mercator coordinates. This is because internally :program:`cs2cs` is -having to adjust the lat/long coordinates from being on the sphere to being on -the WGS84 datum which has a quite differently shaped ellipsoid. - -In this case, and many other cases using spherical projections, the desired -approach is to actually treat the lat/long locations on the sphere as if they -were on WGS84 without any adjustments when using them for converting to other -coordinate systems. The solution is to "trick" PROJ into applying no change -to the lat/long values when going to (and through) WGS84. This can be -accomplished by asking PROJ to use a null grid shift file for switching from -your spherical lat/long coordinates to WGS84. - -:: - - cs2cs +proj=latlong +datum=WGS84 \ - +to +proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 \ - +x_0=0.0 +y_0=0 +k=1.0 +units=m +nadgrids=@null +no_defs - -Note the strategic addition of ``+nadgrids=@null`` to the spherical projection -definition. - -Similar issues apply with many other datasets distributed with projections -based on a spherical earth model, such as many NASA datasets. This coordinate -system is now known by the EPSG code 3857 and has in the past been known as -EPSG:3785 and EPSG:900913. When using this coordinate system with GDAL/OGR it -is helpful to include the +wktext so the exact PROJ string will be preserved -in the WKT representation (otherwise key parameters like ``+nadgrids=@null`` will -be dropped): - -:: - - +proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0 +k=1.0 - +units=m +nadgrids=@null +wktext +no_defs - +Any contributions from the PROJ community is welcome. See :ref:`contributing` for +more details. How do I calculate distances/directions on the surface of the earth? -------------------------------------------------------------------------------- @@ -219,32 +84,15 @@ How do I calculate distances/directions on the surface of the earth? These are called geodesic calculations. There is a page about it here: :ref:`geodesic`. - -What options does PROJ allow for the shape of the Earth (geodesy)? --------------------------------------------------------------------------------- - -See https://github.com/OSGeo/proj.4/blob/master/src/pj_ellps.c -for possible ellipse options. For example, putting ``+ellps=WGS84`` uses -the ``WGS84`` Earth shape. - -What if I want a spherical Earth? --------------------------------------------------------------------------------- - -Use ``+ellps=sphere``. See https://github.com/OSGeo/proj.4/blob/master/src/pj_ellps.c -for the radius used in this case. - -How do I change the radius of the Earth? How do I use PROJ for work on Mars? --------------------------------------------------------------------------------- - -You can supply explicit values for the semi minor and semi major axes instead -of using the symbolic "sphere" value. Eg, if the radius were 2000000m: - -:: - - +proj=laea +lon_0=-40.000000 +lat_0=74.000000 +x_0=1000000 +y_0=1700000 +a=2000000 +b=2000000" - -How do I do False Eastings and False Northings? +What is the best format for describing coordinate reference systems? -------------------------------------------------------------------------------- -Use ``+x_0`` and ``+y_0`` in the projection string. +A coordinate reference system (CRS) can in PROJ be described in several ways: +As PROJ strings, Well-Known Text (WKT) and as spatial reference ID's (such as EPSG +codes). Generally, WKT or SRID's are preferred over PROJ strings as they can +contain more information about a given CRS. Conversions between WKT and PROJ +strings will in most cases cause a loss of information, potentially leading to +erroneous transformations. +For compatibility reasons PROJ supports several WKT dialects +(see :option:`projinfo -o`). If possible WKT2 should be used. |