From 5d22d137b1be282bdc14c1d12ab8f669f58d41a6 Mon Sep 17 00:00:00 2001 From: Charles Karney Date: Mon, 26 Oct 2020 12:44:18 -0400 Subject: Update Mercator projection Introduction ------------ The existing formulation for the Mercator projection is "satisfactory"; it is reasonably accurate. However for a core projection like Mercator, I think we should strive for full double precision accuracy. This commit uses cleaner, more accurate, and faster methods for computing the forward and inverse projections. These use the formulation in terms of hyperbolic functions that are manifestly odd in latitude psi = asinh(tan(phi)) - e * atanh(e * sin(phi)) (phi = latitude; psi = isometric latitude = Mercator y coordinate). Contrast this with the existing formulation psi = log(tan(pi/4 - phi/2)) - e/2 * log((1 + e * sin(phi)) / (1 - e * sin(phi))) where psi(-phi) isn't exactly equal to -psi(phi) and psi(0) isn't guaranteed to be 0. Implementation -------------- There's no particular issue implementing the forward projection, just apply the formulas above. The inverse projection is tricky because there's no closed form solution for the inverse. The existing code for the inverse uses an iterative method from Snyder. This is the usual hokey function iteration, and, as usual, the convergence rate is linear (error reduced by a constant factor on each iteration). This is OK (just) for low accuracy work. But nowadays, something with quadratic convergence (e.g., Newton's method, number of correct digits doubles on each iteration) is preferred (and used here). More on this later. The solution for phi(psi) I use is described in my TM paper and I lifted the specific formulation from GeographicLib's Math::tauf, which uses the same underlying machinery for all conformal projections. It solves for tan(phi) in terms of sinh(psi) which as a near identity mapping is ideal for Newton's method. For comparison I also look at the approach adopted by Poder + Engsager in their TM paper and implemented in etmerc. This uses trigonometric series (accurate to n^6) to convert phi <-> chi. psi is then given by psi = asinh(tan(chi)) Accuracy -------- I tested just the routines for transforming phi <-> psi from merc.cpp and measured the errors (converted to true nm = nanometers) for the forward and inverse mapping. I also included in my analysis the method used by etmerc. This uses a trigonometric series to convert phi <-> chi = atan(sinh(psi)), the conformal latitude. forward inverse max rms max rms old merc 3.60 0.85 2189.47 264.81 etmerc 1.82 0.38 1.42 0.37 new merc 1.83 0.30 2.12 0.31 1 nm is pretty much the absolute limit for accuracy in double precision (1 nm = 10e6 m / 2^53, approximately), and 5 nm is probably the limit on what you should routinely expect. So the old merc inverse is considerably less accurate that it could be. The old merc forward is OK on accuracy -- except that if does not preserve the parity of the projection. The accuracy of etmerc is fine (the truncation error of the 6th order series is small compared with the round-off error). However, situation reverses as the flattening is increased. E.g., at f = 1/150, the max error for the inverse projection is 8 nm. etmerc is OK for terrestrial applications, but couldn't be used for Mars. Timing ------ Here's what I get with g++ -O3 on various Linux machines with recent versions of g++. As always, you should take these with a grain of salt. You might expect the relative timings to vary by 20% or so when switching between compilers/machines. Times per call in ns = nanoseconds. forward inverse old merc 121 360 etmerc 4e-6 1.4 new merc 20 346 The new merc method is 6 times faster at the forward projection and modestly faster at the inverse projection (despite being more accurate). The latter result is because it only take 2 iterations of Newton's method to get full accuracy compared with an average of 5 iterations for the old method to get only um accuracy. A shocking aspect of these timings is how fast etmerc is. Another is that forward etmerc is streaks faster that inverse etmerc (it made be doubt my timing code). Evidently, asinh(tan(chi)) is a lot faster to compute than atan(sinh(psi)). The hesitation about adopting etmerc then comes down to: * the likelihood that Mercator may be used for non-terrestrial bodies; * the question of whether the timing benefits for the etmerc method would be noticeable in a realistic application; * need to duplicate the machinery for evaluating the coefficients for the series and for Clenshaw summation in the current code layout. Ripple effects ============== The Mercator routines used the the Snyder method, pj_tsfn and pj_phi2, are used in other projections. These relate phi to t = exp(-psi) (a rather bizarre choice in my book). I've retrofitted these to use the more accurate methods. These do the "right thing" for phi in [-pi/2, pi/2] , t in [0, inf], and e in [0, 1). NANs are properly handled. Of course, phi = pi/2 in double precision is actually less than pi/2, so cos(pi/2) > 0. So no special handling is needed for pi/2. Even if angles were handled in such a way that 90deg were exactly represented, these routines would still "work", with, e.g., tan(pi/2) -> inf. (A caution: with long doubles = a 64-bit fraction, we have cos(pi/2) < 0; and now we would need to be careful.) As a consequence, there no need for error handling in pj_tsfn; the HUGE_VAL return has gone and, of course, HUGE_VAL is a perfectly legal input to tsfn's inverse, phi2, which would return -pi/2. This "error handling" was only needed for e = 1, a case which is filtered out upstream. I will note that bad argument handling is much more natural using NAN instead of HUGE_VAL. See issue #2376 I've renamed the error condition for non-convergence of the inverse projection from "non-convergent inverse phi2" to "non-convergent sinh(psi) to tan(phi)". Now that pj_tsfn and pj_phi2 now return "better" results, there were some malfunctions in the projections that called them, specifically gstmerc, lcc, and tobmerc. * gstmerc invoked pj_tsfn(phi, sinphi, e) with a value of sinphi that wasn't equal to sin(phi). Disaster followed. I fixed this. I also replaced numerous occurrences of "-1.0 * x" by "-x". (Defining a function with arguments phi and sinphi is asking for trouble.) * lcc incorrectly thinks that the projection isn't defined for standard latitude = +/- 90d. This happens to be false (it reduces to polar stereographic in this limit). The check was whether tsfn(phi) = 0 (which only tested for the north pole not the south pole). However since tsfn(pi/2) now (correctly) returns a nonzero result, this test fails. I now just test for |phi| = pi/2. This is clearer and catches both poles (I'm assuming that the current implementation will probably fail in these cases). * tobmerc similarly thinks that phi close to +/- pi/2 can't be transformed even though psi(pi/2) is only 38. I'm disincline to fight this. However I did tighten up the failure condition (strict equality of |phi| == pi/2). OTHER STUFF =========== Testing ------- builtins.gei: I tightened up the tests for merc (and while I was about it etmerc and tmerc) to reflect full double precision accuracy. My test values are generated with MPFR enabled code and so should be accurate to all digits given. For the record, for GRS80 I use f = 1/298.2572221008827112431628366 in these calculations. pj_phi2_test: many of the tests were bogus testing irrelevant input parameters, like negative values of exp(-psi), and freezing in the arbitrary behavior of phi2. I've reworked most for the tests to be semi-useful. @schwehr can you review. Documentation ------------- I've updated merc.rst to outline the calculation of the inverse projection. phi2.cpp includes detailed notes about applying Newton's method to find tan(phi) in terms of sinh(psi). Future work ----------- lcc needs some tender loving care. It can easily (and should) be modified to allow stdlat = +/- 90 (reduces to polar stereographic), stdlat = 0 and stdlat_1 + stdlat_2 = 0 (reduces to Mercator). A little more elbow grease will allow the treatment of stdlat_1 close to stdlat_2 using divided differences. (See my implementation of the LambertConformalConic class in GeographicLib.) All the places where pj_tsfn and pj_phi2 are called need to be reworked to cut out the use of Snyder's t = exp(-psi() variable and instead use sinh(psi). Maybe include the machinery for series conversions between all auxiliary latitudes as "support functions". Then etmerc could use this (as could mlfn for computing meridional distance). merc could offer the etmerc style projection via chi as an option when the flattening is sufficiently small. --- docs/source/operations/projections/merc.rst | 30 ++++++++++++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/source/operations/projections/merc.rst b/docs/source/operations/projections/merc.rst index 7b6e13da..2107b7b2 100644 --- a/docs/source/operations/projections/merc.rst +++ b/docs/source/operations/projections/merc.rst @@ -158,7 +158,35 @@ Inverse projection \lambda = \frac{x}{k_0 a}; \quad \psi = \frac{y}{k_0 a} The latitude :math:`\phi` is found by inverting the equation for -:math:`\psi` iteratively. +:math:`\psi`. This follows the method given by :cite:`Karney2011tm`. +Start by introducing the conformal latitude + +.. math:: + \chi = \tan^{-1}\sinh\psi + +The tangents of the latitudes :math:`\tau = \tan\phi` and :math:`\tau' = +\tan\chi = \sinh\psi` are related by + +.. math:: + \tau' = \tau \sqrt{1 + \sigma^2} - \sigma \sqrt{1 + \tau^2} + +where + +.. math:: + \sigma = \sinh\bigl(e \tanh^{-1}(e \tau/\sqrt{1 + \tau^2}) \bigr) + +This is obtained by taking the :math:`\sinh` of the equation for +:math:`\psi` and using the multiple argument formula. The equation for +:math:`\tau'` can be solved to give :math:`\tau` using Newton's method +using :math:`\tau = \tau'/(1 - e^2)` as an initial guess and with the +needed derivative given by + +..math:: + \frac{d\tau'}{d\tau} = \frac{1 - e^2}{1 + (1 - e^2)\tau^2} + \sqrt{1 + \tau'^2} \sqrt{1 + \tau^2} + +This converges after no more than 2 iterations. Finally set +:math:`\phi=\tan^{-1}\tau`. Further reading ############### -- cgit v1.2.3 From 1e5acb00a0c0fc2533b9bce2e5803da10ed1d8d6 Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Thu, 8 Oct 2020 20:59:19 +0200 Subject: projinfo / createObjectsFromName(): support returning a datum ensemble --- docs/source/apps/projinfo.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/source/apps/projinfo.rst b/docs/source/apps/projinfo.rst index 05184ef9..a07cf709 100644 --- a/docs/source/apps/projinfo.rst +++ b/docs/source/apps/projinfo.rst @@ -16,7 +16,7 @@ Synopsis ******** | **projinfo** - | [-o formats] [-k crs|operation|datum|ellipsoid] [--summary] [-q] + | [-o formats] [-k crs|operation|datum|ensemble|ellipsoid] [--summary] [-q] | [[--area name_or_code] | [--bbox west_long,south_lat,east_long,north_lat]] | [--spatial-test contains|intersects] | [--crs-extent-use none|both|intersection|smallest] @@ -86,7 +86,7 @@ The following control parameters can appear in any order: .. note:: Before PROJ 6.3.0, WKT1:GDAL was implicitly calling --boundcrs-to-wgs84. This is no longer the case. -.. option:: -k crs|operation|datum|ellipsoid +.. option:: -k crs|operation|datum|ensemble|ellipsoid When used to query a single object with a AUTHORITY:CODE, determines the (k)ind of the object in case there are CRS, coordinate operations or ellipsoids with the same CODE. -- cgit v1.2.3 From c64c209f4abeec7ae4e8cdde8d6c5ba9921354fa Mon Sep 17 00:00:00 2001 From: Martin Steinisch Date: Mon, 2 Nov 2020 23:22:18 +0100 Subject: Correct links to github issues in release notes from 7.1.0 to 7.2.0 --- docs/source/news.rst | 156 +++++++++++++++++++++++++-------------------------- 1 file changed, 78 insertions(+), 78 deletions(-) (limited to 'docs') diff --git a/docs/source/news.rst b/docs/source/news.rst index 4275dd11..65c027f1 100644 --- a/docs/source/news.rst +++ b/docs/source/news.rst @@ -13,72 +13,72 @@ Updates + **Command line tools** * Add multi-line PROJ string export capability, and use it by default in - :program:`projinfo` (unless ``--single-line`` is specified) (`#2381 `_) + :program:`projinfo` (unless ``--single-line`` is specified) (`#2381 `_) + **Coordinate operations** * :ref:`col_urban` projection, implementing a EPSG projection method - used by a number of projected CRS in Colombia (`#2395 `_) + used by a number of projected CRS in Colombia (`#2395 `_) - * :ref:`tinshift` for triangulation-based transformations (`#2344 `_) + * :ref:`tinshift` for triangulation-based transformations (`#2344 `_) - * Added ellipsoidal formulation of :ref:`ortho` (`#2361 `_) + * Added ellipsoidal formulation of :ref:`ortho` (`#2361 `_) + **Database** * Update to EPSG 10.003 and make code base robust to dealing with - WKT CRS with DatumEnsemble (`#2370 `_) + WKT CRS with DatumEnsemble (`#2370 `_) - * Added Finland tinshift operations (`#2392 `_) + * Added Finland tinshift operations (`#2392 `_) * Added transformation from JGD2011 Geographic 3D to JGD2011 - height using GSIGEO2011 (`#2393 `_) + height using GSIGEO2011 (`#2393 `_) * Improve CompoundCRS identification and name morphing in VerticalCRS - with ESRI WKT1 (`#2386 `_) + with ESRI WKT1 (`#2386 `_) * Added OGC:CRS27 and OGC:CRS83 CRS entries for NAD27 and NAD83 - in longitude, latitude order (`#2350 `_) + in longitude, latitude order (`#2350 `_) + **API** - * Added temporal, engineering, and parametric datum :c:type:`PJ_TYPE` enumerations (`#2274 `_) + * Added temporal, engineering, and parametric datum :c:type:`PJ_TYPE` enumerations (`#2274 `_) * Various improvements to context handling (#2329, #2331) * :c:func:`proj_create_vertical_crs_ex()`: add a ``ACCURACY`` option to provide an explicit accuracy, or derive it from the grid name if it is - known (`#2342 `_) + known (`#2342 `_) * :c:func:`proj_crs_create_bound_crs_to_WGS84()`: make it work on verticalCRS/compoundCRS such as EPSG:4326+5773 and - EPSG:4326+3855 (`#2365 `_) + EPSG:4326+3855 (`#2365 `_) - * :cpp:func:`promoteTo3D()`: add a remark with the original CRS identifier (`#2369 `_) + * :cpp:func:`promoteTo3D()`: add a remark with the original CRS identifier (`#2369 `_) - * Added :c:func:`proj_context_clone` (`#2383 `_) + * Added :c:func:`proj_context_clone` (`#2383 `_) Bug fixes --------- -* Avoid core dumps when copying contexts in certain scenarios (`#2324 `_) +* Avoid core dumps when copying contexts in certain scenarios (`#2324 `_) * :c:func:`proj_trans()`: reset errno before attemptying a retry with a new - coordinate operation (`#2353 `_) + coordinate operation (`#2353 `_) * PROJJSON schema corrected to allow prime meridians values with - explicitly stating a unit (degrees assumed) (`#2354 `_) + explicitly stating a unit (degrees assumed) (`#2354 `_) * Adjust :cpp:func:`createBoundCRSToWGS84IfPossible()` and operation filtering - (for POSGAR 2007 to WGS84 issues) (`#2357 `_) + (for POSGAR 2007 to WGS84 issues) (`#2357 `_) -* :cpp:func:`createOperations()`: several fixes affecting NAD83 -> NAD83(2011) (`#2364 `_) +* :cpp:func:`createOperations()`: several fixes affecting NAD83 -> NAD83(2011) (`#2364 `_) * WKT2:2019 import/export: handle DATUM (at top level object) with PRIMEM -* WKT1_ESRI: fix import and export of CompoundCRS (`#2389 `_) +* WKT1_ESRI: fix import and export of CompoundCRS (`#2389 `_) 7.1.1 Release Notes @@ -89,36 +89,36 @@ Bug fixes Updates ------- -* Added various Brazillian grids to the database (`#2277 `_) +* Added various Brazillian grids to the database (`#2277 `_) -* Added geoid file for Canary Islands to the database (`#2312 `_) +* Added geoid file for Canary Islands to the database (`#2312 `_) -* Updated EPSG database to version 9.8.15 (`#2310 `_) +* Updated EPSG database to version 9.8.15 (`#2310 `_) Bug fixes --------- * WKT parser: do not raise warning when parsing a WKT2:2015 TIMECRS - whose TIMEUNIT is at the CS level, and not inside (`#2281 `_) + whose TIMEUNIT is at the CS level, and not inside (`#2281 `_) * Parse '+proj=something_not_latlong +vunits=' without +geoidgrids as a - Projected3D CRS and not a compound CRS with a unknown datum (`#2289 `_) + Projected3D CRS and not a compound CRS with a unknown datum (`#2289 `_) -* C API: Avoid crashing due to missing SANITIZE_CTX() in entry points (`#2293 `_) +* C API: Avoid crashing due to missing SANITIZE_CTX() in entry points (`#2293 `_) -* CMake build: Check "target_clones" before use (`#2297 `_) +* CMake build: Check "target_clones" before use (`#2297 `_) -* PROJ string export of +proj=krovak +czech: make sure we export +czech… (`#2301 `_) +* PROJ string export of +proj=krovak +czech: make sure we export +czech… (`#2301 `_) -* Helmert 2D: do not require a useless +convention= parameter (`#2305 `_) +* Helmert 2D: do not require a useless +convention= parameter (`#2305 `_) -* Fix a few spelling errors ("vgridshit" vs. "vgridshift") (`#2307 `_) +* Fix a few spelling errors ("vgridshit" vs. "vgridshift") (`#2307 `_) -* Fix ability to identify EPSG:2154 as a candidate for 'RGF93_Lambert_93' (`#2316 `_) +* Fix ability to identify EPSG:2154 as a candidate for 'RGF93_Lambert_93' (`#2316 `_) -* WKT importer: tune for Oracle WKT and 'Lambert Conformal Conic' (`#2322 `_) +* WKT importer: tune for Oracle WKT and 'Lambert Conformal Conic' (`#2322 `_) -* Revert compiler generated Fused Multiply Addition optimized routines (`#2328 `_) +* Revert compiler generated Fused Multiply Addition optimized routines (`#2328 `_) @@ -135,7 +135,7 @@ Updates + **New projections** - * Add square conformal projections from libproject (`#2148 `_): + * Add square conformal projections from libproject (`#2148 `_): - :ref:`adams_hemi` @@ -148,117 +148,117 @@ Updates - :ref:`peirce_q` * Adams Square II: map ESRI WKT to PROJ string, and implement iterative - inverse method (`#2157 `_) + inverse method (`#2157 `_) - * Added :ref:`igh_o` projection (`#2226 `_) + * Added :ref:`igh_o` projection (`#2226 `_) - * Add :ref:`wink2` inverse by generic inversion of forward method (`#2243 `_) + * Add :ref:`wink2` inverse by generic inversion of forward method (`#2243 `_) + **Database** * Update to EPSG 9.8.12, ESRI 10.8.1 and import scope and remarks for - conversion (`#2238 `_) (#2267) + conversion (`#2238 `_) (#2267) - * Map the Behrman projection to ``cae`` when converting ESRI CRSes (`#1986 `_) + * Map the Behrman projection to ``cae`` when converting ESRI CRSes (`#1986 `_) - * Support conversion of Flat_Polar_Quartic projection method (`#1987 `_) + * Support conversion of Flat_Polar_Quartic projection method (`#1987 `_) * Register 4 new Austrian height grids (see https://github.com/OSGeo/PROJ-data/pull/13) - and handle 'Vertical Offset by Grid Interpolation (BEV AT)' method (`#1989 `_) + and handle 'Vertical Offset by Grid Interpolation (BEV AT)' method (`#1989 `_) * Add ESRI projection method mappings for Mercator_Variant_A, Mercator_Variant_B - and Transverse_Cylindrical_Equal_Area and various grid mappings (`#2020 `_) (#2195) + and Transverse_Cylindrical_Equal_Area and various grid mappings (`#2020 `_) (#2195) - * Map ESRI Transverse_Mercator_Complex to Transverse Mercator (`#2040 `_) + * Map ESRI Transverse_Mercator_Complex to Transverse Mercator (`#2040 `_) - * Register grids for New Caledonia (see https://github.com/OSGeo/PROJ-data/pull/16) (`#2051 `_) (#2239) + * Register grids for New Caledonia (see https://github.com/OSGeo/PROJ-data/pull/16) (`#2051 `_) (#2239) - * Register NZGD2000 -> ITRF96 transformation for NZGD2000 database (`#2248 `_) + * Register NZGD2000 -> ITRF96 transformation for NZGD2000 database (`#2248 `_) * Register geoid file for UK added - (see https://github.com/OSGeo//PROJ-data/pull/25() (`#2250 `_) + (see https://github.com/OSGeo//PROJ-data/pull/25() (`#2250 `_) - * Register Slovakian geoid transformations with needed code changes (`#2259 `_) + * Register Slovakian geoid transformations with needed code changes (`#2259 `_) - * Register Spanish SPED2ETV2 grid for ED50->ETRS89 (`#2261 `_) + * Register Spanish SPED2ETV2 grid for ED50->ETRS89 (`#2261 `_) + **API** - * Add API function :c:func:`proj_get_units_from_database()` (`#2065 `_) + * Add API function :c:func:`proj_get_units_from_database()` (`#2065 `_) - * Add API function :c:func:`proj_get_suggested_operation()` (`#2068 `_) + * Add API function :c:func:`proj_get_suggested_operation()` (`#2068 `_) - * Add API functions :c:func:`proj_degree_input()` and :c:func:`proj_degree_output()` (`#2144 `_) + * Add API functions :c:func:`proj_degree_input()` and :c:func:`proj_degree_output()` (`#2144 `_) * Moved :c:func:`proj_context_get_url_endpoint()` & :c:func:`proj_context_get_user_writable_directory()` - from ``proj_experimental.h`` to ``proj.h`` (`#2162 `_) + from ``proj_experimental.h`` to ``proj.h`` (`#2162 `_) * :c:func:`createFromUserInput()`: allow compound CRS with the 2 parts given by names, - e.g. 'WGS 84 + EGM96 height' (`#2126 `_) + e.g. 'WGS 84 + EGM96 height' (`#2126 `_) * :c:func:`createOperations()`: when converting CompoundCRS<-->Geographic3DCrs, do not use discard change of ellipsoidal height if a Helmert transformation is - involved (`#2227 `_) + involved (`#2227 `_) + **Optimizations** - * ``tmerc/utm``: add a +algo=auto/evenden_snyder/poder_engsager parameter (`#2030 `_) + * ``tmerc/utm``: add a +algo=auto/evenden_snyder/poder_engsager parameter (`#2030 `_) - * Extended ``tmerc`` (Poder/Engsager): speed optimizations (`#2036 `_) + * Extended ``tmerc`` (Poder/Engsager): speed optimizations (`#2036 `_) - * Approximate ``tmerc`` (Snyder): speed optimizations (`#2039 `_) + * Approximate ``tmerc`` (Snyder): speed optimizations (`#2039 `_) - * :c:func:`pj_phi2()`: speed-up computation (and thus inverse ellipsoidal Mercator and LCC) (`#2052 `_) + * :c:func:`pj_phi2()`: speed-up computation (and thus inverse ellipsoidal Mercator and LCC) (`#2052 `_) - * Inverse ``cart``: speed-up computation by 33% (`#2145 `_) + * Inverse ``cart``: speed-up computation by 33% (`#2145 `_) - * Extended ``tmerc``: speed-up forward path by ~5% (`#2147 `_) + * Extended ``tmerc``: speed-up forward path by ~5% (`#2147 `_) + **Various** - * Follow PDAL's CMake RPATH strategy (`#2009 `_) + * Follow PDAL's CMake RPATH strategy (`#2009 `_) - * WKT import/export: add support for WKT1_ESRI VERTCS synta (`#2024 `_) + * WKT import/export: add support for WKT1_ESRI VERTCS synta (`#2024 `_) - * :program:`projinfo`: add a ``--hide-ballpark`` option (`#2127 `_) + * :program:`projinfo`: add a ``--hide-ballpark`` option (`#2127 `_) - * :program:`gie`: implement a strict mode with `` `` (`#2168 `_) + * :program:`gie`: implement a strict mode with `` `` (`#2168 `_) - * Allow importing WKT1 COMPD_CS with a VERT_DATUM[Ellipsoid,2002] (`#2229 `_) + * Allow importing WKT1 COMPD_CS with a VERT_DATUM[Ellipsoid,2002] (`#2229 `_) - * Add runtime checking that sqlite3 is >= 3.11 (`#2235 `_) + * Add runtime checking that sqlite3 is >= 3.11 (`#2235 `_) Bug fixes --------- * :cpp:func:`createOperations()`: do not remove ballpark transformation if there are only grid - based operations, even if they cover the whole area of use (`#2155 `_) + based operations, even if they cover the whole area of use (`#2155 `_) * :cpp:func:`createFromProjString()`: handle default parameters of '+krovak +type=crs', and - handle ``+czech`` correctly (`#2200 `_) + handle ``+czech`` correctly (`#2200 `_) -* :cpp:func:`ProjectedCRS::identify()`: fix identification of EPSG:3059 (`#2215 `_) +* :cpp:func:`ProjectedCRS::identify()`: fix identification of EPSG:3059 (`#2215 `_) -* Database: add a 'WGS84' alias for the EPSG:4326 CRS (`#2218 `_) +* Database: add a 'WGS84' alias for the EPSG:4326 CRS (`#2218 `_) -* Fixes related to CompoundCRS and BoundCRS (`#2222 `_) +* Fixes related to CompoundCRS and BoundCRS (`#2222 `_) -* Avoid 2 warnings about missing database indices (`#2223 `_) +* Avoid 2 warnings about missing database indices (`#2223 `_) -* Make ``projinfo --3d --boundcrs-to-wgs84`` work better (`#2224 `_) +* Make ``projinfo --3d --boundcrs-to-wgs84`` work better (`#2224 `_) * Many fixes regarding BoundCRS, CompoundCRS, Geographic3D CRS with - non-metre units (`#2234 `_) + non-metre units (`#2234 `_) -* Fix identification of (one of the) ESRI WKT formulations of EPSG:3035 (`#2240 `_) +* Fix identification of (one of the) ESRI WKT formulations of EPSG:3035 (`#2240 `_) -* Avoid using deprecated and removed Windows API function with Mingw32 (`#2246 `_) +* Avoid using deprecated and removed Windows API function with Mingw32 (`#2246 `_) * :cpp:func:`normalizeForVisualization()`: make it switch axis for EPSG:5482 - (RSRGD2000 / RSPS2000) (`#2256 `_) + (RSRGD2000 / RSPS2000) (`#2256 `_) -* Fix access violation in :c:func:`proj_context_get_database_metadata()` (`#2260 `_) +* Fix access violation in :c:func:`proj_context_get_database_metadata()` (`#2260 `_) 7.0.1 Release Notes -- cgit v1.2.3 From 20c987854fb0220cd8cc28278fe5f18279175013 Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Tue, 3 Nov 2020 23:17:02 +0100 Subject: docs/Makefile: restore custom 'html' target Fixes #2408 https://github.com/OSGeo/PROJ/pull/2377 removed our customized 'html' and .doxygen_up_to_date targets. Let's restore them --- docs/Makefile | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/Makefile b/docs/Makefile index b9fa8257..22399302 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -4,18 +4,43 @@ # You can set these variables from the command line, and also # from the environment for the first two. SPHINXOPTS ?= +HTMLOPTS ?= -W SPHINXBUILD ?= sphinx-build SOURCEDIR = source BUILDDIR = build +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source + # Put it first so that "make" without argument is like "make help". help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) .PHONY: help Makefile +.PHONY: clean +clean: + rm -rf $(BUILDDIR)/* + rm -rf .doxygen_up_to_date + +.doxygen_up_to_date: + ../scripts/doxygen.sh + touch .doxygen_up_to_date + +.PHONY: html +html: .doxygen_up_to_date + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(HTMLOPTS) $(BUILDDIR)/html + # Undoes the hack done in scripts/doxygen.sh + @sed "s/io::Convention_/io::Convention/g" < $(BUILDDIR)/html/development/reference/cpp/io.html | sed "s/>Convention_/>Convention/g" | sed "s/_WKT2/WKT2/g" | sed "s/_WKT1/WKT1/g" > $(BUILDDIR)/html/development/reference/cpp/io.html.tmp + @mv $(BUILDDIR)/html/development/reference/cpp/io.html.tmp $(BUILDDIR)/html/development/reference/cpp/io.html + # Undoes the hacks of scripts/generate_breathe_friendly_general_doc.py + @sed "s/namespace <\/em>//g" < $(BUILDDIR)/html/development/reference/cpp/cpp_general.html > $(BUILDDIR)/html/development/reference/cpp/cpp_general.html.tmp + @mv $(BUILDDIR)/html/development/reference/cpp/cpp_general.html.tmp $(BUILDDIR)/html/development/reference/cpp/cpp_general.html + @cp -r ../schemas $(BUILDDIR)/html/schemas + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + + # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -- cgit v1.2.3 From af342bf74cd154b653a0f9d931d4ca17001650b9 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Tue, 10 Nov 2020 14:08:30 +0100 Subject: Allow cct to instantiate operations via object codes or names (#2419) Running cct like cct EPSG:8366 or cct "ITRF2014 to ETRF2014 (1)" is now possible. --- docs/source/apps/cct.rst | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) (limited to 'docs') diff --git a/docs/source/apps/cct.rst b/docs/source/apps/cct.rst index 1d2aef20..df81c571 100644 --- a/docs/source/apps/cct.rst +++ b/docs/source/apps/cct.rst @@ -15,6 +15,33 @@ Synopsis **cct** [**-cIostvz** [args]] *+opt[=arg]* ... file ... +or + + **cct** [**-cIostvz** [args]] {operation_reference} file ... + +Where {operation_reference} is one of the possibilities accepted +by :c:func:`proj_create`, provided it expresses a coordinate operation + +- a proj-string, + - a WKT string, + - an object code (like "EPSG:1671" "urn:ogc:def:coordinateOperation:EPSG::1671"), + - an object name. e.g "ITRF2014 to ETRF2014 (1)". In that case as + uniqueness is not guaranteed, heuristics are applied to determine the appropriate best match. + - a OGC URN combining references for concatenated operations + (e.g. "urn:ogc:def:coordinateOperation,coordinateOperation:EPSG::3895,coordinateOperation:EPSG::1618") + - a PROJJSON string. The jsonschema is at https://proj.org/schemas/v0.2/projjson.schema.json + + .. versionadded:: 8.0.0 + + .. note:: + + Before version 8.0.0 only proj-strings could be used to instantiate + operations in :program:`cct`. + + + + + Description *********** -- cgit v1.2.3 From a8be7bc87c37f802ddd480b55ba0c19613397892 Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Tue, 10 Nov 2020 14:23:09 +0100 Subject: cct.rst: fix indentation --- docs/source/apps/cct.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/source/apps/cct.rst b/docs/source/apps/cct.rst index df81c571..8f138d92 100644 --- a/docs/source/apps/cct.rst +++ b/docs/source/apps/cct.rst @@ -22,7 +22,7 @@ or Where {operation_reference} is one of the possibilities accepted by :c:func:`proj_create`, provided it expresses a coordinate operation -- a proj-string, + - a proj-string, - a WKT string, - an object code (like "EPSG:1671" "urn:ogc:def:coordinateOperation:EPSG::1671"), - an object name. e.g "ITRF2014 to ETRF2014 (1)". In that case as -- cgit v1.2.3 From 6be4e25c66e805218c851d67157e4d1ddc0a761e Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Tue, 10 Nov 2020 14:40:17 +0100 Subject: cct: allow @filename syntax Similarly as for projinfo, allow "cct @filename" to mean read filename and use its content as if it was provided inline. Useful for WKT or PROJJSON And a tiny improvements, when the object definition contains ':', only try proj_create_from_database() if the left part (authority name) matches a known authority, to avoid a warning. --- docs/source/apps/cct.rst | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/source/apps/cct.rst b/docs/source/apps/cct.rst index 8f138d92..b8504b8d 100644 --- a/docs/source/apps/cct.rst +++ b/docs/source/apps/cct.rst @@ -17,9 +17,9 @@ Synopsis or - **cct** [**-cIostvz** [args]] {operation_reference} file ... + **cct** [**-cIostvz** [args]] {object_definition} file ... -Where {operation_reference} is one of the possibilities accepted +Where {object_definition} is one of the possibilities accepted by :c:func:`proj_create`, provided it expresses a coordinate operation - a proj-string, @@ -39,6 +39,15 @@ by :c:func:`proj_create`, provided it expresses a coordinate operation operations in :program:`cct`. +or + + **cct** [**-cIostvz** [args]] {object_reference} file ... + +where {object_reference} is a filename preceded by the '@' character. The +file referenced by the {object_reference} must contain a valid +{object_definition}. + + .. versionadded:: 8.0.0 @@ -185,6 +194,20 @@ Should give results comparable to the classic :program:`proj` command $ echo 12 56 100 2018.0 auxiliary data | cct +proj=merc 1335833.8895 7522963.2411 100.0000 2018.0000 auxiliary data +7. Coordinate operation referenced through its code + +.. code-block:: console + + $ echo 3541657.3778 948984.2343 5201383.5231 2020.5 | cct EPSG:8366 + 3541657.9112 948983.7503 5201383.2482 2020.5000 + +8. Coordinate operation referenced through its name + +.. code-block:: console + + $ echo 3541657.3778 948984.2343 5201383.5231 2020.5 | cct "ITRF2014 to ETRF2014 (1)" + 3541657.9112 948983.7503 5201383.2482 2020.5000 + Background ********** -- cgit v1.2.3 From 9419b42ade1f1d35a61c05f0f7ce9aab2eeff3c7 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Sun, 1 Nov 2020 13:34:32 +0100 Subject: Remove proj_api.h Removes proj_api.h from the public API. The contents of the header file has been moved to proj_internal.h verbatim and any references to proj_api.h has been changed to proj_internal.h. The documentation of proj_api.h has been removed. The only exception to this is the API migration guides which still mention the old API. Fixes #837 --- docs/source/development/index.rst | 5 +- docs/source/development/reference/deprecated.rst | 270 ----------------------- docs/source/development/reference/index.rst | 1 - 3 files changed, 2 insertions(+), 274 deletions(-) delete mode 100644 docs/source/development/reference/deprecated.rst (limited to 'docs') diff --git a/docs/source/development/index.rst b/docs/source/development/index.rst index 85c10c6d..f985279f 100644 --- a/docs/source/development/index.rst +++ b/docs/source/development/index.rst @@ -39,9 +39,8 @@ are maintained in a `separate git repository - - main(int argc, char **argv) { - projPJ pj_merc, pj_latlong; - double x, y; - - if (!(pj_merc = pj_init_plus("+proj=merc +ellps=clrk66 +lat_ts=33")) ) - exit(1); - if (!(pj_latlong = pj_init_plus("+proj=latlong +ellps=clrk66")) ) - exit(1); - while (scanf("%lf %lf", &x, &y) == 2) { - x *= DEG_TO_RAD; - y *= DEG_TO_RAD; - p = pj_transform(pj_latlong, pj_merc, 1, 1, &x, &y, NULL ); - printf("%.2f\t%.2f\n", x, y); - } - exit(0); - } - - -For this program, an input of ``-16 20.25`` would give a result of -``-1495284.21 1920596.79``. - -API Functions -------------- - -pj_transform -============ - -:: - - int pj_transform( projPJ srcdefn, - projPJ dstdefn, - long point_count, - int point_offset, - double *x, - double *y, - double *z ); - - -Transform the x/y/z points from the source coordinate system to the -destination coordinate system. - -``srcdefn``: source (input) coordinate system. - -``dstdefn``: destination (output) coordinate system. - -``point_count``: the number of points to be processed (the size of the -x/y/z arrays). - -``point_offset``: the step size from value to value (measured in -doubles) within the x/y/z arrays - normally 1 for a packed array. May be -used to operate on xyz interleaved point arrays. - -``x``/``y``/``z``: The array of X, Y and Z coordinate values passed as -input, and modified in place for output. The Z may optionally be NULL. - -``return``: The return is zero on success, or a PROJ.4 error code. - -The ``pj_transform()`` function transforms the passed in list of points -from the source coordinate system to the destination coordinate system. -Note that geographic locations need to be passed in radians, not decimal -degrees, and will be returned similarly. The ``z`` array may be passed -as NULL if Z values are not available. - -If there is an overall failure, an error code will be returned from the -function. If individual points fail to transform - for instance due to -being over the horizon - then those x/y/z values will be set to -``HUGE_VAL`` on return. Input values that are ``HUGE_VAL`` will not be -transformed. - - -pj_init_plus -============ - -:: - - projPJ pj_init_plus(const char *definition); - -This function converts a string representation of a coordinate system -definition into a projPJ object suitable for use with other API -functions. On failure the function will return NULL and set pj_errno. -The definition should be of the general form -``+proj=tmerc +lon_0 +datum=WGS84``. Refer to PROJ.4 documentation and -the :ref:`transformation` notes for additional detail. - -Coordinate system objects allocated with ``pj_init_plus()`` should be -deallocated with ``pj_free()``. - - -pj_free -======= - -:: - - void pj_free( projPJ pj ); - -Frees all resources associated with pj. - - -pj_is_latlong -============= - -:: - - int pj_is_latlong( projPJ pj ); - -Returns TRUE if the passed coordinate system is geographic -(``proj=latlong``). - - -pj_is_geocent -============= - -:: - - int pj_is_geocent( projPJ pj );`` - -Returns TRUE if the coordinate system is geocentric (``proj=geocent``). - -pj_get_def -========== - -:: - - char *pj_get_def( projPJ pj, int options);`` - -Returns the PROJ.4 initialization string suitable for use with -``pj_init_plus()`` that would produce this coordinate system, but with -the definition expanded as much as possible (for instance ``+init=`` and -``+datum=`` definitions). - -pj_latlong_from_proj -==================== - -:: - - projPJ pj_latlong_from_proj( projPJ pj_in );`` - -Returns a new coordinate system definition which is the geographic -coordinate (lat/long) system underlying ``pj_in``. - -pj_set_finder -============== - -:: - - void pj_set_finder( const char *(*new_finder)(const char *) );`` - -Install a custom function for finding init and grid shift files. - -pj_set_searchpath -================= - -:: - - void pj_set_searchpath ( int count, const char **path );`` - -Set a list of directories to search for init and grid shift files. - - -pj_deallocate_grids -=================== - -:: - - void pj_deallocate_grids( void );`` - -Frees all resources associated with loaded and cached datum shift grids. - - -pj_strerrno -=========== - -:: - - char *pj_strerrno( int );`` - -Returns the error text associated with the passed in error code. - -pj_get_errno_ref -================ - -:: - - int *pj_get_errno_ref( void );`` - -Returns a pointer to the global pj\_errno error variable. - -pj_get_release -============== - -:: - - const char *pj_get_release( void );`` - -Returns an internal string describing the release version. - -Obsolete Functions -~~~~~~~~~~~~~~~~~~ - -``XY pj_fwd( LP lp, PJ *P );`` - -``LP pj_inv( XY xy, PJ *P );`` - -``projPJ pj_init(int argc, char **argv);`` - -.. _more info: pj_transform - diff --git a/docs/source/development/reference/index.rst b/docs/source/development/reference/index.rst index 1d39b1d0..caa893c3 100644 --- a/docs/source/development/reference/index.rst +++ b/docs/source/development/reference/index.rst @@ -10,4 +10,3 @@ Reference datatypes functions cpp/index.rst - deprecated -- cgit v1.2.3 From 571096201bf2cb1dde8933eb3fb7091e12ebbbe4 Mon Sep 17 00:00:00 2001 From: Nomit Rawat Date: Fri, 20 Nov 2020 21:13:40 +0530 Subject: Update utm.rst Typo --- docs/source/operations/projections/utm.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/source/operations/projections/utm.rst b/docs/source/operations/projections/utm.rst index 82715a02..cbbda09d 100644 --- a/docs/source/operations/projections/utm.rst +++ b/docs/source/operations/projections/utm.rst @@ -6,7 +6,7 @@ Universal Transverse Mercator (UTM) The Universal Transverse Mercator is a system of map projections divided into sixty zones across the globe, with each zone corresponding to 6 degrees of -longigude. +longitude. +---------------------+----------------------------------------------------------+ | **Classification** | Transverse cylindrical, conformal | -- cgit v1.2.3 From d8fe9964bcbc6d1eeaddf6f5d47ca6d444dc8744 Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Sun, 22 Nov 2020 15:08:41 +0100 Subject: Add +proj=topocentric geocentric->topocentric conversion (fixes #500) --- .../ECEF_ENU_Longitude_Latitude_relationships.png | Bin 0 -> 30731 bytes .../ECEF_ENU_Longitude_Latitude_relationships.svg | 348 +++++++++++++++++++++ docs/source/operations/conversions/index.rst | 1 + docs/source/operations/conversions/topocentric.rst | 115 +++++++ 4 files changed, 464 insertions(+) create mode 100644 docs/source/operations/conversions/images/ECEF_ENU_Longitude_Latitude_relationships.png create mode 100644 docs/source/operations/conversions/images/ECEF_ENU_Longitude_Latitude_relationships.svg create mode 100644 docs/source/operations/conversions/topocentric.rst (limited to 'docs') diff --git a/docs/source/operations/conversions/images/ECEF_ENU_Longitude_Latitude_relationships.png b/docs/source/operations/conversions/images/ECEF_ENU_Longitude_Latitude_relationships.png new file mode 100644 index 00000000..224ff738 Binary files /dev/null and b/docs/source/operations/conversions/images/ECEF_ENU_Longitude_Latitude_relationships.png differ diff --git a/docs/source/operations/conversions/images/ECEF_ENU_Longitude_Latitude_relationships.svg b/docs/source/operations/conversions/images/ECEF_ENU_Longitude_Latitude_relationships.svg new file mode 100644 index 00000000..c97ca181 --- /dev/null +++ b/docs/source/operations/conversions/images/ECEF_ENU_Longitude_Latitude_relationships.svg @@ -0,0 +1,348 @@ + + + +Z + + + + + + +Y + + + + + + +X + + + + + + +North + + + + + + +East + + + + + + +Up + + + + + + +ecef + + +ecef + + +ecef + + + +φ + +λ + + \ No newline at end of file diff --git a/docs/source/operations/conversions/index.rst b/docs/source/operations/conversions/index.rst index b0bd0d37..b335c2ac 100644 --- a/docs/source/operations/conversions/index.rst +++ b/docs/source/operations/conversions/index.rst @@ -19,4 +19,5 @@ conversions. pop push set + topocentric unitconvert diff --git a/docs/source/operations/conversions/topocentric.rst b/docs/source/operations/conversions/topocentric.rst new file mode 100644 index 00000000..828ef4e0 --- /dev/null +++ b/docs/source/operations/conversions/topocentric.rst @@ -0,0 +1,115 @@ +.. _topocentric: + +================================================================================ +Geocentric to topocentric conversion +================================================================================ + +.. versionadded:: 8.0.0 + +Convert geocentric coordinates to topocentric coordinates (in the forward path). + ++---------------------+--------------------------------------------------------+ +| **Alias** | topocentric | ++---------------------+--------------------------------------------------------+ +| **Domain** | 3D | ++---------------------+--------------------------------------------------------+ +| **Input type** | Geocentric cartesian coordinates | ++---------------------+--------------------------------------------------------+ +| **Output type** | Topocentric cartesian coordinates | ++---------------------+--------------------------------------------------------+ + +This operation converts geocentric coordinate values (X, Y, Z) to topocentric +(E/East, N/North, U/Up) values. This is also sometimes known as the ECEF (Earth +Centered Earth Fixed) to ENU conversion. + +Topocentric coordinates are expressed in a frame whose East and North axis form +a local tangent plane to the Earth's ellipsoidal surface fixed to a specific +location (the topocentric origin), and the Up axis points upwards along the +normal to that plane. + +.. image:: ./images/ECEF_ENU_Longitude_Latitude_relationships.png + :align: center + :scale: 100% + :alt: ENU coordinate frame + +.. + Source : https://en.wikipedia.org/wiki/Local_tangent_plane_coordinates#/media/File:ECEF_ENU_Longitude_Latitude_relationships.svg + Public domain +.. + +The topocentric origin is a required parameter of the conversion, and can be +expressed either as geocentric coordinates (``X_0``, ``Y_0`` and ``Z_0``) or +as geographic coordinates (``lat_0``, ``lon_0``, ``h_0``). + +When conversion between geographic and topocentric coordinates is desired, the +topocentric conversion must be preceded by the :ref:`cart` conversion to +perform the initial geographic to geocentric coordinates conversion. + +The formulas used come from the "Geocentric/topocentric conversions" paragraph +of :cite:`IOGP2018` + +Usage +################################################################################ + +Convert geocentric coordinates to topocentric coordinates, with the topocentric +origin specified in geocentric coordinates:: + + echo 3771793.968 140253.342 5124304.349 2020 | \ + cct -d 3 +proj=topocentric +ellps=WGS84 +X_0=3652755.3058 +Y_0=319574.6799 +Z_0=5201547.3536 + + -189013.869 -128642.040 -4220.171 2020.0000 + +Convert geographic coordinates to topocentric coordinates, with the topocentric +origin specified in geographic coordinates:: + + echo 2.12955 53.80939444 73 2020 | cct -d 3 +proj=pipeline \ + +step +proj=cart +ellps=WGS84 \ + +step +proj=topocentric +ellps=WGS84 +lon_0=5 +lat_0=55 +h_0=200 + + -189013.869 -128642.040 -4220.171 2020.0000 + + +Parameters +################################################################################ + +.. include:: ../options/ellps.rst + +Topocentric origin described as geocentric coordinates +------------------------------------------------------ + +.. note:: + + The below options are mutually exclusive with the ones to express the origin as geographic coordinates. + +.. option:: +X_0= + + Geocentric X value of the topocentric origin (in metre) + +.. option:: +Y_0= + + Geocentric Y value of the topocentric origin (in metre) + +.. option:: +Z_0= + + Geocentric Z value of the topocentric origin (in metre) + +Topocentric origin described as geographic coordinates +------------------------------------------------------ + +.. note:: + + The below options are mutually exclusive with the ones to express the origin as geocentric coordinates. + +.. option:: +lat_0= + + Latitude of topocentric origin (in degree) + +.. option:: +lon_0= + + Longitude of topocentric origin (in degree) + +.. option:: +h_0= + + Ellipsoidal height of topocentric origin (in metre) + + *Defaults to 0.0.* -- cgit v1.2.3 From 4caf32aedd4da6b1fd1b1ce0e04a1a08dc1e3f33 Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Tue, 24 Nov 2020 19:16:12 +0100 Subject: Add option to allow export of Geographic/Projected 3D CRS in WKT1_GDAL as CompoundCRS with a VerticalCRS being an ellipsoidal height, which is not conformant. But needed for LAS 1.4 that only supports WKT1 --- docs/source/apps/projinfo.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'docs') diff --git a/docs/source/apps/projinfo.rst b/docs/source/apps/projinfo.rst index a07cf709..803c0a65 100644 --- a/docs/source/apps/projinfo.rst +++ b/docs/source/apps/projinfo.rst @@ -23,6 +23,7 @@ Synopsis | [--grid-check none|discard_missing|sort|known_available] | [--pivot-crs always|if_no_direct_transformation|never|{auth:code[,auth:code]*}] | [--show-superseded] [--hide-ballpark] + | [--allow-ellipsoidal-height-as-vertical-crs] | [--boundcrs-to-wgs84] | [--main-db-path path] [--aux-db-path path]* | [--identify] [--3d] @@ -212,6 +213,15 @@ The following control parameters can appear in any order: .. note:: only used for coordinate operation computation +.. option:: --allow-ellipsoidal-height-as-vertical-crs + + .. versionadded:: 8.0 + + Allow to export a geographic or projected 3D CRS as a compound CRS whose + vertical CRS represents the ellipsoidal height. + + .. note:: only used for CRS, and with WKT1:GDAL output format + .. option:: --boundcrs-to-wgs84 When specified, this option researches a coordinate operation from the -- cgit v1.2.3 From 0b4c8b0a76c65d8b1146224bf314cad53e9f6607 Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Sat, 28 Nov 2020 15:51:27 +0100 Subject: cs2cs: add --area and --bbox options to restrict candidate coordinate operations (fixes #2423) --- docs/source/apps/cs2cs.rst | 29 +++++++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/source/apps/cs2cs.rst b/docs/source/apps/cs2cs.rst index e214a5c0..7fe570d9 100644 --- a/docs/source/apps/cs2cs.rst +++ b/docs/source/apps/cs2cs.rst @@ -11,11 +11,15 @@ cs2cs Synopsis ******** - **cs2cs** [**-eEfIlrstvwW** [args]] [*+opt[=arg]* ...] [+to *+opt[=arg]* ...] file ... + **cs2cs** [**-eEfIlrstvwW** [args]] + [[--area name_or_code] | [--bbox west_long,south_lat,east_long,north_lat]] + [*+opt[=arg]* ...] [+to *+opt[=arg]* ...] file ... or - **cs2cs** [**-eEfIlrstvwW** [args]] {source_crs} {target_crs} file ... + **cs2cs** [**-eEfIlrstvwW** [args]] [--area name_or_code] + [[--area name_or_code] | [--bbox west_long,south_lat,east_long,north_lat]] + {source_crs} {target_crs} file ... where {source_crs} or {target_crs} is one of the possibilities accepted by :c:func:`proj_create`, provided it expresses a CRS @@ -144,6 +148,27 @@ The following control parameters can appear in any order: Causes a listing of cartographic control parameters tested for and used by the program to be printed prior to input data. +.. option:: --area name_or_code + + .. versionadded:: 8.0.0 + + Specify an area of interest to restrict the results when researching + coordinate operations between 2 CRS. The area of interest can be specified either + as a name (e.g "Denmark - onshore") or a AUTHORITY:CODE (EPSG:3237) + + This option is mutually exclusive with :option:`--bbox`. + +.. option:: --bbox west_long,south_lat,east_long,north_lat + + .. versionadded:: 8.0.0 + + Specify an area of interest to restrict the results when researching + coordinate operations between 2 CRS. The area of interest is specified as a + bounding box with geographic coordinates, expressed in degrees in a + unspecified geographic CRS. + `west_long` and `east_long` should be in the [-180,180] range, and + `south_lat` and `north_lat` in the [-90,90]. `west_long` is generally lower than + `east_long`, except in the case where the area of interest crosses the antimeridian. .. only:: man -- cgit v1.2.3 From 18ab7ef2e357e0c01464848a6911e754ebca471f Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Wed, 2 Dec 2020 17:12:54 +0100 Subject: cs2cs / proj_create_crs_to_crs_from_pj(): add a --authority switch to control where coordinate operations are looked for (fixes #2442) --- docs/source/apps/cs2cs.rst | 33 ++++++++++++++++--------- docs/source/development/reference/functions.rst | 14 ++++++++++- 2 files changed, 35 insertions(+), 12 deletions(-) (limited to 'docs') diff --git a/docs/source/apps/cs2cs.rst b/docs/source/apps/cs2cs.rst index 7fe570d9..7df8890f 100644 --- a/docs/source/apps/cs2cs.rst +++ b/docs/source/apps/cs2cs.rst @@ -11,15 +11,11 @@ cs2cs Synopsis ******** - **cs2cs** [**-eEfIlrstvwW** [args]] - [[--area name_or_code] | [--bbox west_long,south_lat,east_long,north_lat]] - [*+opt[=arg]* ...] [+to *+opt[=arg]* ...] file ... - -or - - **cs2cs** [**-eEfIlrstvwW** [args]] [--area name_or_code] - [[--area name_or_code] | [--bbox west_long,south_lat,east_long,north_lat]] - {source_crs} {target_crs} file ... + | **cs2cs** [**-eEfIlrstvwW** [args]] + | [[--area ] | [--bbox ]] + | [--authority ] + | ([*+opt[=arg]* ...] [+to *+opt[=arg]* ...] | {source_crs} {target_crs}) + | file ... where {source_crs} or {target_crs} is one of the possibilities accepted by :c:func:`proj_create`, provided it expresses a CRS @@ -148,7 +144,7 @@ The following control parameters can appear in any order: Causes a listing of cartographic control parameters tested for and used by the program to be printed prior to input data. -.. option:: --area name_or_code +.. option:: --area .. versionadded:: 8.0.0 @@ -158,7 +154,7 @@ The following control parameters can appear in any order: This option is mutually exclusive with :option:`--bbox`. -.. option:: --bbox west_long,south_lat,east_long,north_lat +.. option:: --bbox .. versionadded:: 8.0.0 @@ -170,6 +166,21 @@ The following control parameters can appear in any order: `south_lat` and `north_lat` in the [-90,90]. `west_long` is generally lower than `east_long`, except in the case where the area of interest crosses the antimeridian. +.. option:: --authority + + .. versionadded:: 8.0.0 + + This option can be used to restrict the authority of coordinate operations + looked up in the database. When not specified, coordinate + operations from any authority will be searched, with the restrictions set + in the ``authority_to_authority_preference`` database table related to the authority + of the source/target CRS themselves. + If authority is set to ``any``, then coordinate operations from any authority will be searched + If authority is a non-empty string different of ``any``, then coordinate operations + will be searched only in that authority namespace (e.g ``EPSG``). + + This option is mutually exclusive with :option:`--bbox`. + .. only:: man The *+opt* run-line arguments are associated with cartographic diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst index cc29743c..32902916 100644 --- a/docs/source/development/reference/functions.rst +++ b/docs/source/development/reference/functions.rst @@ -182,7 +182,19 @@ paragraph for more details. This is the same as :c:func:`proj_create_crs_to_crs` except that the source and target CRS are passed as PJ* objects which must of the CRS variety. - :param `options`: should be set to NULL currently. + :param `options`: a list of NUL terminated options, or NULL. + + The list of supported options is: + + - AUTHORITY=name: to restrict the authority of coordinate operations + looked up in the database. When not specified, coordinate + ``operations from any authority`` will be searched, with the restrictions set + in the authority_to_authority_preference database table related to the authority + of the source/target CRS themselves. + If authority is set to "any", then coordinate operations from any authority will be searched + If authority is a non-empty string different of ``any``, then coordinate operations + will be searched only in that authority namespace (e.g ``EPSG``). + .. doxygenfunction:: proj_normalize_for_visualization :project: doxygen_api -- cgit v1.2.3 From 29d2542cc37d404b9fdef0effe1e006f8969b1c5 Mon Sep 17 00:00:00 2001 From: Zac Miller Date: Wed, 2 Dec 2020 12:23:28 -0500 Subject: Update isea.rst Clarifying defaults for ISEA. --- docs/source/operations/projections/isea.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/source/operations/projections/isea.rst b/docs/source/operations/projections/isea.rst index adb703a1..73f0af7a 100644 --- a/docs/source/operations/projections/isea.rst +++ b/docs/source/operations/projections/isea.rst @@ -43,7 +43,9 @@ Parameters .. option:: +orient= - Can be set to either ``isea`` or ``pole``. + Can be set to either ``isea`` or ``pole``. See Snyder's Figure 12 for pole orientation :cite:`Snyder1992`. + + *Defaults to isea* .. option:: +azi= @@ -62,6 +64,8 @@ Parameters .. option:: +mode= Can be either ``plane``, ``di``, ``dd`` or ``hex``. + + *Defaults to plane* .. include:: ../options/lon_0.rst -- cgit v1.2.3 From 372b5b74804b1d279c952f4a7811ade3e5815a35 Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Wed, 9 Dec 2020 19:28:13 +0100 Subject: Doc: fix return data type of proj_trans_array() --- docs/source/development/reference/functions.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst index 32902916..df452032 100644 --- a/docs/source/development/reference/functions.rst +++ b/docs/source/development/reference/functions.rst @@ -364,7 +364,7 @@ Coordinate transformation -.. c:function:: size_t proj_trans_array(PJ *P, PJ_DIRECTION direction, size_t n, PJ_COORD *coord) +.. c:function:: int proj_trans_array(PJ *P, PJ_DIRECTION direction, size_t n, PJ_COORD *coord) Batch transform an array of :c:type:`PJ_COORD`. @@ -374,7 +374,7 @@ Coordinate transformation :type `direction`: PJ_DIRECTION :param n: Number of coordinates in :c:data:`coord` :type n: `size_t` - :returns: :c:type:`size_t` 0 if all observations are transformed without error, otherwise returns error number + :returns: :c:type:`int` 0 if all observations are transformed without error, otherwise returns error number Error reporting -- cgit v1.2.3 From acab18920ec25ccbc2affe8bda924ff5f961d30c Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Fri, 11 Dec 2020 21:50:35 +0100 Subject: funtions.rst: fix sphynx syntax --- docs/source/development/reference/functions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/source/development/reference/functions.rst b/docs/source/development/reference/functions.rst index df452032..b37eacdd 100644 --- a/docs/source/development/reference/functions.rst +++ b/docs/source/development/reference/functions.rst @@ -374,7 +374,7 @@ Coordinate transformation :type `direction`: PJ_DIRECTION :param n: Number of coordinates in :c:data:`coord` :type n: `size_t` - :returns: :c:type:`int` 0 if all observations are transformed without error, otherwise returns error number + :returns: `int` 0 if all observations are transformed without error, otherwise returns error number Error reporting -- cgit v1.2.3