diff options
Diffstat (limited to 'docs/source/faq.rst')
| -rw-r--r-- | docs/source/faq.rst | 327 |
1 files changed, 327 insertions, 0 deletions
diff --git a/docs/source/faq.rst b/docs/source/faq.rst new file mode 100644 index 00000000..a289494c --- /dev/null +++ b/docs/source/faq.rst @@ -0,0 +1,327 @@ +.. _faq: + +****************************************************************************** +FAQ +****************************************************************************** + + +Where can I find the list of projections and their arguments? +-------------------------------------------------------------------------------- + +There is no simple single location to find all the required information. The +!PostScript/PDF documents listed on the [http://trac.osgeo.org/proj/wiki main] +PROJ.4 page under documentation are the authoritative source but projections +and options are spread over several documents in a form more related to their +order of implementation than anything else. + +The '''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. + +The [http://www.remotesensing.org/geotiff/proj_list/ GeoTIFF Projections Pages] +include most of the common PROJ.4 projections, and a definition of the +projection specific options for each. + +* How do I do datum shifts between NAD27 and NAD83? + +While the '''nad2nad''' program can be used in some cases, the '''cs2cs''' is +now the preferred mechanism. The following example demonstrates using the +default shift parameters for NAD27 to NAD83: + + +:: + + % cs2cs +proj=latlong +datum=NAD27 +to +proj=latlong +datum=NAD83 -117 30 + + +producing: + +:: + + 117d0'2.901"W 30d0'0.407"N 0.000 + +In order for datum shifting to work properly the various grid shift files must +be available. See below. More details are available in the +[wiki:GenParms#nadgrids-GridBasedDatumAdjustments General Parameters] document. + +How do I build/configure PROJ.4 to support datum shifting? +-------------------------------------------------------------------------------- + +After downloading and unpacking the PROJ.4 source, also download and unpack the +set of datum shift files. See :ref:`download` for instructions how to fetch +and install these files + +On Windows the extra nadshift target must be used. For instance +``nmake /f makefile.vc nadshift`` in the ``proj/src`` directory. + +A default build and install on Unix will normally build knowledge of the +directory where the grid shift files are installed into the PROJ.4 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.4 data directory is incorrect, the ``PROJ_LIB`` +environment can be defined with the correct directory. + +How do I debug problems with NAD27/NAD83 datum shifting? +-------------------------------------------------------------------------------- + +1. Verify that you have the binary files (eg. /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 cs2cs + command listed above. Do you get reasonable results? If not it is likely + the grid shift files aren't being found. Perhaps you need to define + PROJ_LIB? +3. The cs2cs command and the underlying 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 ``PROJ_DEBUG`` environment can be defined (any value) to force extra output + from the PROJ.4 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.4 library. + +5. The ``-v`` flag to cs2cs can be useful in establishing more detail on what + parameters being 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.4? +-------------------------------------------------------------------------------- + +There is somewhat imperfect translation between 2d geographic and projected +coordinate system codes and PROJ.4 descriptions of the coordinate system +available in the epsg definition file that normally lives in the proj/nad +directory. If installed (it is installed by 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/nad/epsg file can be browsed and searched in a text editor for +coordinate systems. There are known to be problems with some coordinate +systems, and any coordinate systems with odd axes, a non-greenwich prime +meridian or other quirkyness are 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 is more fully described in the +[wiki:GenParms#towgs84-DatumtransformationtoWGS84 towgs84] parameter +discussion. + +Does PROJ.4 work in different international numeric locales? +-------------------------------------------------------------------------------- + +No. PROJ.4 makes extensive use of sprintf() and atof() 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.4 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 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 + overriden 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 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.4 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.4 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 + +Why do I get different results with 4.5.0 and 4.6.0? +-------------------------------------------------------------------------------- + +The default datum application behavior changed with the 4.6.0 release. PROJ.4 +will now only apply a datum shift if both the source and destination coordinate +system have valid datum shift information. + +From the PROJ.4 4.6.0 Release Notes (in NEWS): + * MAJOR: Rework pj_transform() to avoid applying ellipsoid to ellipsoid + transformations as a datum shift when no datum info is available. + + +How do I calculate distances/directions on the surface of the earth? +-------------------------------------------------------------------------------- + +These are called geodesic calculations. There is a page about it here: +[wiki:GeodesicCalculations] + +What is the HEALPix projection and how can I use it? +-------------------------------------------------------------------------------- + +.. figure:: + ../images/rhealpix.png + :scale: 40% + :align: left + +The HEALPix projection is area preserving and can be used with a +spherical and ellipsoidal model. It was initially developed for mapping cosmic +background microwave radiation. The image below is the graphical +representation of the mapping and consists of eight isomorphic triangular +interrupted map graticules. The north and south contains four in which +straight meridians converge polewards to a point and unequally spaced +horizontal parallels. HEALPix provides a mapping in which points of equal +latitude and equally spaced longitude are mapped to points of equal latitude +and equally spaced longitude with the module of the polar interruptions. || + +To run a forward HEALPix projection on a unit sphere model, use the following command: + +:: + + proj +proj=healpix +lon_0=0 +a=1 -E <<EOF + 0 0 + EOF + +Output of the above command. + +:: + + 0 0 0.00 0.00 + +What is the rHEALPix projection and how can I use it? +-------------------------------------------------------------------------------- + +.. figure:: + ../images/healpix.png + :scale: 40% + :align: left + +rHEALPix is a projection based on the HEALPix projection. The implementation +of rHEALPix uses the HEALPix projection. The rHEALPix combines the peaks of +the HEALPix into a square. The square's position can be translated and rotated +across the x-axis which is a noval approach for the rHEALPix projection. The +initial intention of using rHEALPix in the Spatial Computation Engine Science +Collaboration Environment (SCENZGrid). + +To run a inverse rHEALPix projection on a WGS84 ellipsoidal model, use the following command: + +:: + + proj +proj=rhealpix -f '%.2f' -I +lon_0=0 +a=1 +ellps=WGS84 +npole=0 +spole=0 -E <<EOF + 0 0.7853981633974483 + EOF + +Where spole and npole are integers from the range of 0 to 3 inclusive and represent the positions of the north polar and south polar squares. + +Output of above command: + +:: + + 0 0.7853981633974483 0.00 41.94 + +What options does proj.4 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.4 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? +-------------------------------------------------------------------------------- + +Use ``+x_0`` and ``+y_0`` in the projection string. + |