Doc: Projections tutorial

[geographika]

This PR adds a new tutorial on working with CRSs in GDAL. It was hard to define the scope of the tutorial, and I have pages more of notes that may make it to a separate "advanced" page. I'm not 100% happy with it, so open to suggestions and feedback before merging.

Link to preview: https://gdal--14285.org.readthedocs.build/en/14285/tutorials/reprojecting_data.html

Several new examples are added to the various CLI tools. There is some overlap with the older tutorial, but the focus here is on the new CLI and reading the CRS info returned by GDAL.

There is also a fix in one of the parameters in gdal_raster_reproject.rst.
A few notes:

• the full WKT CRS takes up a lot of the gdal info output. I'm guessing 90% of the time users just want to know the EPSG code. Having several EPSG codes included in the output (for example in the CONVERSION block) likely causes some confusion. Would only returning the EPSG code for known / unmodified CRSs be an option?
• The Natural Earth example, with the new CLI tools returns lots of "old" errors e.g. Warning 1: A geometry of type MULTIPOLYGON is inserted into layer ne_10m_admin_0_countries_chn of geometry type POLYGON, which is not normally allowed by the GeoPackage specification, but the driver will however do it. To create a conformant GeoPackage, if using ogr2ogr, the -nlt option can be used to override the layer geometry type. This warning will no longer be emitted for this combination of layer and feature geometry type.

Hopefully there are no inaccuracies in the tutorial - have at it @jjimenezshaw !

[jjimenezshaw]

As many people exchange "coordinate reference system" and "coordinate system", if we use "coordinate system" we should also explain it. Otherwise people will not understand it.

Other option is to not mention "coordinate system" at all, but tell something else in the CRS definition.

[geographika]

I've added a glossary entry for "coordinate system" as best I can, and linked to that

[ctoney]

I read through the rendered preview. Nice work. Thanks, this is a really good addition!

It was hard to define the scope of the tutorial, and I have pages more of notes that may make it to a separate "advanced" page.

That definitely makes sense given the topic. The tutorial hits the right spot IMO. It's introductory and beginner friendly while still providing helpful info and interesting reading for more experienced users. I also like that several links to relevant information are incorporated into a concise tutorial. That gives me one good source I can go to even if I'm just looking for some linked info that I can't remember where it was. Keeping the intro tutorial relatively short makes it more digestible, but you condensed it well to the essentials. That seems like the right model. I would be interested to see it link to the "advanced" page at some point :)

[geographika]

@jjimenezshaw @rouault @ctoney - thanks all for your reviews, and taking the time to read through this. I'll address the comments above in the next few days.

[geographika]

When #14286 and #14303 are merged I'll update to include its usage and switch from draft.

[rouault]

When #14286 and #14303 are merged I'll update to include its usage and switch from draft.

merged

[geographika]

Updated the tutorial to take into account the summary CRS information (added in #14303).

A couple of questions while writing the docs:

    Coordinate Reference System:
      - name: WGS 84
      - ID: EPSG:4326
      - type: Geographic 2D
      - area of use: World, west -180.00, south -90.00, east 180.00, north 90.00
    Data axis to CRS axis mapping: 2,1

I presume -**units: degree** isn't part of the output as it is assumed for a Geographic CRS?

    Coordinate Reference System:
      - name: WGS 84 / Pseudo-Mercator
      - ID: EPSG:3857
      - type: Projected
      - projection type: Popular Visualisation Pseudo-Mercator, Popular Visualisation Pseudo Mercator
      - units: metre
      - area of use: World between 85.06°S and 85.06°N, west -180.00, south -85.06, east 180.00, north 85.06
    Data axis to CRS axis mapping: 1,2

I tried to explain the duplicated "Popular Visualisation Pseudo-Mercator" in the ouput as follows:

• projection type: Popular Visualisation Pseudo-Mercator, Popular Visualisation Pseudo Mercator - this shows both the projection conversion name and the EPSG method name.
  They are identical here because the CRS uses the standard EPSG:1024 Web Mercator method, so both the conversion and method labels resolve to the same projection definition.

Is this correct?

[rouault]

I presume -**units: degree** isn't part of the output as it is assumed for a Geographic CRS?

although that's clearly lazyness of mine. There are ancient times geographic CRS where the units is ... cough cough ... grads. But who cares about les-fromages-qui-puent ? Anyway most of the GDAL interface for such CRS communicates in degree, so let's shut up on those confusing details

Is this correct?

yep, but the best documentation is the one you don't have to write. I'll tune that so we don't emit twice the same info

[rouault]

I'll tune that so we don't emit twice the same inf

#14330