Doc: add Projections tutorial (#14285)

geographika · web-flow · commit fd3f16d23880 · 2026-04-12T13:19:58.000+02:00
diff --git a/doc/images/tutorials/NE2_50M_SR_53009.png b/doc/images/tutorials/NE2_50M_SR_53009.png
diff --git a/doc/source/glossary.rst b/doc/source/glossary.rst
@@ -58,6 +58,10 @@ The GDAL glossary contains terms and acronyms found throughout the GDAL document
 
         The date tied to spatial coordinates in a dynamic reference frame, used to account for positional changes over time (e.g., due to tectonic motion).
 
+    Coordinate System
+
+        The mathematical framework that defines how coordinates are measured and represented within a geometric coordinate space.
+
     CPL
 
         Common Portability Library. Part of the C API that provides convenience
@@ -74,8 +78,8 @@ The GDAL glossary contains terms and acronyms found throughout the GDAL document
 
     CRS
 
-        Coordinate Reference System. A system that maps spatial data coordinates to real-world locations,
-        combining a coordinate system with a reference surface like a projection or :term:`ellipsoid`.
+        Coordinate Reference System. Specifies how coordinates correspond to locations on Earth (or other celestial bodies),
+        including the :term:`coordinate system`, :term:`datum`, and, if applicable, a projection.
 
     CSL
 
@@ -87,6 +91,12 @@ The GDAL glossary contains terms and acronyms found throughout the GDAL document
         A command-line tool and library for transferring data with URLs, supporting protocols such as HTTP, HTTPS, FTP, and more.
         Commonly used for testing and interacting with web services.
 
+    Datum
+
+        A model of the Earth that specifies the size and shape of the reference :term:`ellipsoid` and its position and orientation
+        relative to the Earth, providing the basis for a :term:`CRS`. In geodetic datums, this defines horizontal positioning.
+        Vertical datums define a reference surface for height values (e.g., mean sea level or a geoid) used for vertical coordinates in 3D operations.
+
     DEM
 
         Digital Elevation Model. A raster representation of the height of the earth's surface.
diff --git a/doc/source/programs/gdal_bash_completion.rst b/doc/source/programs/gdal_bash_completion.rst
@@ -97,6 +97,7 @@ Examples of completion
 
 .. example::
    :title: Auto-completion of EPSG CRS codes
+   :id: gdal-bash-completion-crs
 
    .. code-block:: console
 
diff --git a/doc/source/programs/gdal_raster_info.rst b/doc/source/programs/gdal_raster_info.rst
@@ -193,3 +193,17 @@ Examples
 
         > gdal raster info https://sentinel-cogs.s3.us-west-2.amazonaws.com/sentinel-s2-l2a-cogs/36/Q/WD/2020/7/S2A_36QWD_20200701_0_L2A/TCI.tif --of=JSON `
         | jq '.metadata.IMAGE_STRUCTURE.LAYOUT == \"COG\"'
+
+.. example::
+   :title: Return the CRS used by the raster using ``jq``
+   :id: gdal-raster-info-crs
+
+   .. tabs::
+
+      .. code-tab:: bash
+
+         gdal raster info in.tif --of json | jq -r '.stac."proj:projjson".id | .authority + ":" + (.code|tostring)'
+
+      .. code-tab:: ps1
+
+         gdal raster info in.tif --of json | jq -r '.stac.\"proj:projjson\".id | .authority + \":\" + (.code|tostring)'
diff --git a/doc/source/programs/gdal_raster_reproject.rst b/doc/source/programs/gdal_raster_reproject.rst
@@ -88,7 +88,7 @@ Program-Specific Options
 
 .. option:: -d, --dst-crs <SRC-CRS>
 
-    Set source spatial reference. If not specified the SRS found in the input
+    Set destination spatial reference. If not specified the SRS found in the input
     dataset will be used.
 
     .. include:: options/srs_def_gdalwarp.rst
diff --git a/doc/source/programs/gdal_vector_edit.rst b/doc/source/programs/gdal_vector_edit.rst
@@ -132,3 +132,13 @@ Examples
    .. code-block:: bash
 
         $ gdal vector edit --crs=EPSG:4326 --geometry-type=POLYGONZM in.gpkg out.gpkg --overwrite
+
+.. example::
+   :title: Apply a CRS to a Shapefile
+
+   If a Shapefile is missing its associated ``.prj`` file, it can be created as follows:
+
+   .. code-block:: bash
+
+        $ gdal vector edit --crs=EPSG:3857 in.shp out.shp
+
diff --git a/doc/source/programs/gdal_vector_reproject.rst b/doc/source/programs/gdal_vector_reproject.rst
@@ -98,3 +98,56 @@ Examples
    .. code-block:: bash
 
         $ gdal vector reproject --dst-crs=EPSG:32632 in.gpkg out.gpkg --overwrite
+
+.. example::
+   :id: gdal-vector-reproject-crs
+   :title: Reproject data using various CRS formats
+
+   The following examples demonstrate different ways to specify a coordinate reference system.
+   Each command reprojects the data to the Web Mercator (EPSG:3857) projection and produces identical output.
+
+   .. code-block:: bash
+
+        # OGC CRS URI
+        $ gdal vector reproject \
+            --dst-crs="http://www.opengis.net/def/crs/EPSG/0/3857" \
+            natural_earth_vector.gpkg --layer=ne_10m_populated_places \
+            places.json --overwrite
+
+        # OGC CRS URN
+        $ gdal vector reproject \
+            --dst-crs="urn:ogc:def:crs:EPSG::3857" \
+            natural_earth_vector.gpkg --layer=ne_10m_populated_places \
+            places.json --overwrite
+
+        # PROJ string (legacy format)
+        $ PROJ4="+proj=merc +a=6378137 +b=6378137 +lat_ts=0 +lon_0=0 +x_0=0 +y_0=0 +k=1 +units=m +nadgrids=@null +wktext +no_defs +type=crs"
+        $ gdal vector reproject \
+            --dst-crs="$PROJ4" \
+            natural_earth_vector.gpkg --layer=ne_10m_populated_places \
+            places.json --overwrite
+
+.. example::
+   :title: Reproject a layer in a GeoPackage to Web Mercator GeoJSON
+
+   The timezone layer cannot be fully reprojected to Web Mercator as the coordinates at the poles fall outside the extent of the Web Mercator bounding-box causing
+   some features to be missing in the output. The following errors are returned:
+
+   .. code-block:: bash
+
+        ERROR 1: Full reprojection failed, but partial is possible if you define OGR_ENABLE_PARTIAL_REPROJECTION configuration option to TRUE
+        ERROR 1: PROJ: webmerc: Invalid latitude
+        ERROR 1: Reprojection failed, err = 2049, further errors will be suppressed on the transform object.
+
+   You can follow the suggestion above and enable ``OGR_ENABLE_PARTIAL_REPROJECTION``.
+   Errors from PROJ relating to invalid coordinates (``ERROR 1: PROJ: webmerc: Invalid latitude``) will still be reported, but all features will be written to the output.
+
+   .. code-block:: bash
+
+        $ gdal vector reproject \
+            --dst-crs=EPSG:3857 \
+            --config OGR_ENABLE_PARTIAL_REPROJECTION=TRUE \
+            natural_earth_vector.gpkg --layer=ne_10m_time_zones \
+            ne_10m_time_zones.json \
+            --overwrite
+
diff --git a/doc/source/substitutions.rst b/doc/source/substitutions.rst
@@ -14,6 +14,7 @@
 .. |Docker| replace:: `Docker <https://www.docker.com/>`__
 .. |gdal-dev| replace:: `gdal-dev <https://lists.osgeo.org/mailman/listinfo/gdal-dev>`__
 .. |OSGeo/gdal| replace:: `OSGeo/gdal <https://github.com/OSGeo/gdal>`__
+.. |OGC| replace:: `OGC <https://www.ogc.org//>`__
 .. |Sphinx| replace:: `Sphinx <https://www.sphinx-doc.org/>`__
 .. |sphinx-autobuild| replace:: `sphinx-autobuild <https://pypi.org/project/sphinx-autobuild/>`__
 .. |about-config-options| replace:: :ref:`Configuration options <configoptions>` can be specified in command-line tools using the syntax ``--config <NAME>=<VALUE>`` or using functions such as :cpp:func:`CPLSetConfigOption` (C) or :py:func:`gdal.config_options<osgeo.gdal.config_options>` (Python).
diff --git a/doc/source/tutorials/index.rst b/doc/source/tutorials/index.rst
@@ -45,12 +45,13 @@ Geographic Network Model
 
    gnm_api_tut
 
-Projections and Spatial Reference Systems tutorial (OSR - OGRSpatialReference)
-------------------------------------------------------------------------------
+Projections / CRS
+-----------------
 
 .. toctree::
    :maxdepth: 1
 
+   reprojecting_data
    osr_api_tut
 
 Workshops
diff --git a/doc/source/tutorials/osr_api_tut.rst b/doc/source/tutorials/osr_api_tut.rst
@@ -26,10 +26,11 @@ WKT2:2015 and WKT2:2018) for describing coordinate systems.
 References and applicable standards
 -----------------------------------
 
-- `PROJ documentation <https://proj4.org>`_: projection methods and coordinate operations
-- `ISO:19111 and WKT standards <https://proj4.org/development/reference/cpp/cpp_general.html#standards>`_
+- |PROJ| documentation: projection methods and coordinate operations
+- `Spatial Reference <https://spatialreference.org>`_: an extensive database of spatial reference systems in standardized formats like Well-Known Text (WKT) or PROJJSON
+- `ISO:19111 and WKT standards <https://proj.org/development/reference/cpp/cpp_general.html#general_doc_1standards>`_
 - `GeoTIFF Projections Transform List <http://geotiff.maptools.org/proj_list>`_: understanding formulations of projections in WKT for GeoTIFF
-- `EPSG Geodesy web page <http://www.epsg.org>`_ is also a useful resource
+- `EPSG Geodesy web page <https://www.epsg.org>`_ is also a useful resource
 
 Defining a Geographic Coordinate Reference System
 -------------------------------------------------
@@ -172,6 +173,8 @@ This method with options is available in C as the :cpp:func:`OSRExportToWktEx` f
 The :cpp:func:`OGRSpatialReference::importFromWkt` method can be used to set an
 OGRSpatialReference from a WKT CRS definition.
 
+.. _osr_api_tut_axis_order:
+
 CRS and axis order
 ------------------
 
diff --git a/doc/source/tutorials/reprojecting_data.rst b/doc/source/tutorials/reprojecting_data.rst
diff --git a/doc/source/user/cookbook.rst b/doc/source/user/cookbook.rst
