From 79bb57eecdd7b6cdf0bc34a1cf1705aa9456043d Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Tue, 9 Apr 2019 15:08:32 +0200 Subject: DOC: update line numbers in dev quickstart example --- docs/source/development/quickstart.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'docs/source/development/quickstart.rst') diff --git a/docs/source/development/quickstart.rst b/docs/source/development/quickstart.rst index 960cddbf..267270fb 100644 --- a/docs/source/development/quickstart.rst +++ b/docs/source/development/quickstart.rst @@ -35,7 +35,7 @@ this in detail. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c - :lines: 48 + :lines: 49 :dedent: 4 Next we create the ``PJ`` transformation object ``P`` with the function @@ -51,7 +51,7 @@ details. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c - :lines: 50-52 + :lines: 51-53 :dedent: 4 PROJ uses it's own data structures for handling coordinates. Here we use a @@ -62,17 +62,17 @@ for further details. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c - :lines: 56 + :lines: 57 :dedent: 4 -The coordinate defined above is transformed with ``proj_trans_coord``. For this +The coordinate defined above is transformed with ``proj_trans``. For this a ``PJ`` object, a transformation direction (either forward or inverse) and the coordinate is needed. The transformed coordinate is returned in ``b``. Here the forward (``PJ_FWD``) transformation from geodetic to UTM is made. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c - :lines: 59-60 + :lines: 60-61 :dedent: 4 The inverse transformation (UTM to geodetic) is done similar to above, @@ -80,14 +80,14 @@ this time using ``PJ_INV`` as the direction. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c - :lines: 61-62 + :lines: 62-63 :dedent: 4 Before ending the program the allocated memory needs to be released again: .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c - :lines: 65-66 + :lines: 66-67 :dedent: 4 -- cgit v1.2.3 From fb125618fd18f112ed6f37662b021d07a602ff90 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Wed, 10 Apr 2019 11:38:23 +0200 Subject: DOC: add sphinx links to reference in dev quickstart (#1420) --- docs/source/development/quickstart.rst | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) (limited to 'docs/source/development/quickstart.rst') diff --git a/docs/source/development/quickstart.rst b/docs/source/development/quickstart.rst index 267270fb..b6c5d17c 100644 --- a/docs/source/development/quickstart.rst +++ b/docs/source/development/quickstart.rst @@ -28,7 +28,7 @@ See the :doc:`reference for more info on data types `. :lines: 43-45 :dedent: 4 -For use in multi-threaded programs the ``PJ_CONTEXT`` threading-context is used. +For use in multi-threaded programs the :c:type:`PJ_CONTEXT` threading-context is used. In this particular example it is not needed, but for the sake of completeness it created here. The section on :doc:`threads ` discusses this in detail. @@ -38,15 +38,15 @@ this in detail. :lines: 49 :dedent: 4 -Next we create the ``PJ`` transformation object ``P`` with the function -``proj_create``. ``proj_create`` takes the threading context ``C`` created above, -and a proj-string that defines the desired transformation. Here we transform -from geodetic coordinate to UTM zone 32N. +Next we create the :c:type:`PJ` transformation object ``P`` with the function +:c:func:`proj_create`. :c:func:`proj_create` takes the threading context ``C`` +created above, and a proj-string that defines the desired transformation. +Here we transform from geodetic coordinate to UTM zone 32N. It is recommended to create one threading-context per thread used by the program. -This ensures that all ``PJ`` objects created in the same context will be sharing -resources such as error-numbers and loaded grids. -In case the creation of the ``PJ`` object fails an error message is displayed and -the program returns. See :doc:`errorhandling` for further +This ensures that all :c:type:`PJ` objects created in the same context will be +sharing resources such as error-numbers and loaded grids. +In case the creation of the :c:type:`PJ` object fails an error message is +displayed and the program returns. See :doc:`errorhandling` for further details. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c @@ -55,9 +55,9 @@ details. :dedent: 4 PROJ uses it's own data structures for handling coordinates. Here we use a -``PJ_COORD`` which is easily assigned with the function ``proj_coord``. Note -that the input values are converted to radians with ``proj_torad``. This is -necessary since PROJ is using radians internally. See :doc:`transformations` +:c:type:`PJ_COORD` which is easily assigned with the function :c:func:`proj_coord`. +Note that the input values are converted to radians with :c:func:`proj_torad`. +This is necessary since PROJ is using radians internally. See :doc:`transformations` for further details. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c @@ -65,10 +65,10 @@ for further details. :lines: 57 :dedent: 4 -The coordinate defined above is transformed with ``proj_trans``. For this -a ``PJ`` object, a transformation direction (either forward or inverse) and the -coordinate is needed. The transformed coordinate is returned in ``b``. -Here the forward (``PJ_FWD``) transformation from geodetic to UTM is made. +The coordinate defined above is transformed with :c:func:`proj_trans`. For this +a :c:type:`PJ` object, a transformation direction (either forward or inverse) +and the coordinate is needed. The transformed coordinate is returned in ``b``. +Here the forward (:c:type:`PJ_FWD`) transformation from geodetic to UTM is made. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c @@ -76,7 +76,7 @@ Here the forward (``PJ_FWD``) transformation from geodetic to UTM is made. :dedent: 4 The inverse transformation (UTM to geodetic) is done similar to above, -this time using ``PJ_INV`` as the direction. +this time using :c:type:`PJ_INV` as the direction. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c -- cgit v1.2.3 From a8080f3f17f96449a6c706bfed9ab3d7f9a75e5b Mon Sep 17 00:00:00 2001 From: Even Rouault Date: Fri, 19 Apr 2019 22:53:31 +0200 Subject: Doc: update quickstart with PROJ 6 API (fixes #1403) --- docs/source/development/quickstart.rst | 91 ++++++++++++++++++++++++++++------ 1 file changed, 75 insertions(+), 16 deletions(-) (limited to 'docs/source/development/quickstart.rst') diff --git a/docs/source/development/quickstart.rst b/docs/source/development/quickstart.rst index b6c5d17c..d53d98fd 100644 --- a/docs/source/development/quickstart.rst +++ b/docs/source/development/quickstart.rst @@ -25,7 +25,7 @@ See the :doc:`reference for more info on data types `. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c - :lines: 43-45 + :lines: 43-46 :dedent: 4 For use in multi-threaded programs the :c:type:`PJ_CONTEXT` threading-context is used. @@ -35,13 +35,43 @@ this in detail. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c - :lines: 49 + :lines: 50 :dedent: 4 Next we create the :c:type:`PJ` transformation object ``P`` with the function -:c:func:`proj_create`. :c:func:`proj_create` takes the threading context ``C`` -created above, and a proj-string that defines the desired transformation. -Here we transform from geodetic coordinate to UTM zone 32N. +:c:func:`proj_create_crs_to_crs`. :c:func:`proj_create_crs_to_crs` takes the threading context ``C`` +created above, a string that describes the source coordinate reference system (CRS), +a string that describes the target CRS and an optional description of the area of +use. +The strings for the source or target CRS may be PROJ strings (``+proj=longlat +datum=WGS84``), +CRS identified by their code (``EPSG:4326`` or ``urn:ogc:def:crs:EPSG::4326``) or +by a well-known text (WKT) string ( +:: + + GEOGCRS["WGS 84", + DATUM["World Geodetic System 1984", + ELLIPSOID["WGS 84",6378137,298.257223563, + LENGTHUNIT["metre",1]]], + PRIMEM["Greenwich",0, + ANGLEUNIT["degree",0.0174532925199433]], + CS[ellipsoidal,2], + AXIS["geodetic latitude (Lat)",north, + ORDER[1], + ANGLEUNIT["degree",0.0174532925199433]], + AXIS["geodetic longitude (Lon)",east, + ORDER[2], + ANGLEUNIT["degree",0.0174532925199433]], + USAGE[ + SCOPE["unknown"], + AREA["World"], + BBOX[-90,-180,90,180]], + ID["EPSG",4326]] + +). +The use of PROJ strings to describe a CRS is considered as legacy (one of the +main weakness of PROJ strings is their inability to describe a geodetic datum, +other than the few ones hardcoded in the ``+datum`` parameter). +Here we transform from geographic coordinates to UTM zone 32N. It is recommended to create one threading-context per thread used by the program. This ensures that all :c:type:`PJ` objects created in the same context will be sharing resources such as error-numbers and loaded grids. @@ -51,43 +81,72 @@ details. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c - :lines: 51-53 + :lines: 52-60 :dedent: 4 -PROJ uses it's own data structures for handling coordinates. Here we use a +:c:func:`proj_create_crs_to_crs` creates a transformation object, which accepts +coordinates expressed in the units and axis order of the definition of the +source CRS, and return transformed coordinates in the units and axis order of +the definition of the target CRS. +For almost most geographic CRS, the units will be in most cases degrees (in +rare cases, such as EPSG:4807 / NTF (Paris), this can be grads). For geographic +CRS defined by the EPSG authority, the order of coordinates is latitude first, +longitude second. When using a PROJ string, on contrary the order will be +longitude first, latitude second. +For projected CRS, the units may vary (metre, us-foot, etc..). For projected +CRS defined by the EPSG authority, and with EAST / NORTH directions, the order +might be easting first, northing second, or the reverse. When using a PROJ string, +the order will be easting first, northing second, except if the ``+axis`` +parameter modifies it. + +If for the needs of your software, you want +a uniform axis order (and thus do not care about axis order mandated by the +authority defining the CRS), the :c:func:`proj_normalize_for_visualization` +function can be used to modify the PJ* object returned by +:c:func:`proj_create_crs_to_crs` so that it accepts as input and returns as +output coordinates using the traditional GIS order, that is longitude, latitude +(followed by elevation, time) for geographic CRS and easting, northing for most +projected CRS. + +.. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c + :language: c + :lines: 65-71 + :dedent: 4 + +PROJ uses its own data structures for handling coordinates. Here we use a :c:type:`PJ_COORD` which is easily assigned with the function :c:func:`proj_coord`. -Note that the input values are converted to radians with :c:func:`proj_torad`. -This is necessary since PROJ is using radians internally. See :doc:`transformations` -for further details. +When using +proj=longlat, the order of coordinates is longitude, latitude, +and values are expressed in degrees. If you used instead a EPSG geographic CRS, +like EPSG:4326 (WGS84), it would be latitude, longitude. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c - :lines: 57 + :lines: 76 :dedent: 4 The coordinate defined above is transformed with :c:func:`proj_trans`. For this a :c:type:`PJ` object, a transformation direction (either forward or inverse) and the coordinate is needed. The transformed coordinate is returned in ``b``. -Here the forward (:c:type:`PJ_FWD`) transformation from geodetic to UTM is made. +Here the forward (:c:type:`PJ_FWD`) transformation from geographic to UTM is made. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c - :lines: 60-61 + :lines: 79-80 :dedent: 4 -The inverse transformation (UTM to geodetic) is done similar to above, +The inverse transformation (UTM to geographic) is done similar to above, this time using :c:type:`PJ_INV` as the direction. .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c - :lines: 62-63 + :lines: 81-82 :dedent: 4 Before ending the program the allocated memory needs to be released again: .. literalinclude:: ../../../examples/pj_obs_api_mini_demo.c :language: c - :lines: 66-67 + :lines: 85-86 :dedent: 4 -- cgit v1.2.3