DOC/projections: Make projection name consistent

[yvonnefroehlich]

Description of proposed changes

Related to the points 3. and 4. of GenericMappingTools/pygmt#3405 (comment).

Currently the projection names are adjusted based on the name used in the projection table.

Related PyGMT PR at GenericMappingTools/pygmt#3407.

Reminders

• Make sure that your code follows our style. Use the other functions/files as a basis.
• Add tests for new features or tests that would have caught the bug that you're fixing.
• Describe changes to function behavior and arguments in a comment below the function declaration.
• If adding new functionality, add a detailed description to the documentation and/or an example.

[joa-quim]

Hmm, lots of changes here. While I agree on dropping the word projection for most (all?) cases, I cannot agree with all proposed changes. For example Mercator projection to Mercator cylindrical (all Mercators are cylindrical), and a few others. Maybe do this in two phases, leaving out on the first step the projection renamings.

[seisman]

https://en.wikipedia.org/wiki/List_of_map_projections

Looking at this wikipedia page, I think "Mercator" is the projection name and "cylindrical" is just the projection property. So I feel we should use the official projection names listed on this Wikipedia page.

[joa-quim]

@WalterHFSmith Walter, do you have opinion on dropping "equal-area" in some projection names?

[WalterHFSmith]

Dear All,
I looked at the Wikipedia page but I am not sure what you are proposing to change.
I think it is perhaps unfortunate or not helpful that the Wikipedia page starts by giving each projection a name, then lists things like properties and types separately. Also that the names are not unique in the sense that one has Mercator, Web Mercator (and in GMT at least) Transverse Mercator and Oblique Mercator.
Mercator is an example of a problem, for parsing names, I suppose, in that "Mercator" without other modifying words could be assumed to mean a conformal and cylindrical development with the cylinder tangent to the Equator, and furthermore, on the Earth, using a development that is conformal for the Ellipsoid rather than a sphere. If we take the idea of being cylindrical and conformal and wrap the paper around another way, then we can have these true properties in Transverse and Oblique aspect but true only for a sphere and not for an ellipsoid.
Equal-Area (Authalic is a synonym for Equal-Area) is a property, and it does not imply a projection type; there can be Azimuthal, Conic, Cylindrical projections which are Equal-Area.
The projection type does not imply having, or not, the property of being Equal-Area. For example, there are both Conformal and Equal-Area conic and cylindrical and azimuthal projections.
Equal-Area cannot be Conformal, and Conformal cannot be Equal-Area, and so these terms imply exclusion of the other. But they don't uniquely name a projection.
It is also possible to develop the sphere or ellipsoid so that the map shows true distance and azimuth from one point at the map center.
Some of these are named for people and some aren't. And among those that are, such as Mercator, their generalization to other aspects isn't always clearly standardized. [Indeed, the problem of a transverse cylindrical that went from Canada across the North Pole to Russia is what originally lead me to put Auxiliary Latitudes into GMT.]

So what is the problem we are trying to solve? A standardization of nomenclature?

[joa-quim]

Thanks Walter. I won't answer what the problem tried to be solved because I'm not sure either. And from what you wrote I deduce that we should not drop the Equal-Area" from names and that instead it should be understood as that the implementation is using Authalic sphere.

In order to see the proposed changes click on the "Files changed" at the top of this page

[yvonnefroehlich]

Thanks @WalterHFSmith for your very detailed comment!

The idea of this PR is to make the projection name consistent between the projection table (https://docs.generic-mapping-tools.org/dev/reference/map-projections.html) and the projection explanations.
The starting point was PyGMT (GenericMappingTools/pygmt#3405, GenericMappingTools/pygmt#3407). We prefer to have the same projection names in the projection table (https://www.pygmt.org/dev/techref/projections.html) and for the projection explanations (https://www.pygmt.org/dev/projections/index.html). Additionally to this, I feel it would be good to make the projection names consistent between the GMT and PyGMT documentation. Thus, I started working on this upstream PR and plan to apply these changes in the same way to the PyGMT documentation.

For example,

• in the table it is "Eckert IV equal area" and "Eckert VI equal area" but the heading later is "Eckert IV and VI projection"
• table "Mercator cylindrical" but heading "Mercator"
• table "Equidistant cylindrical" but heading " Cylindrical equidistant projection"

[joa-quim]

OK, so things are now clear on my mind (mean, opinion).

We should not drop the "equal area" from names in the table as it provides important information. The projection description doesn't have it in the header but has in the description.

We could drop the cylindrical from Mercator but than we have a Equidistant cylindrical and a Equidistant conic. So leave the Mercator as it is now.

Finally the Equidistant cylindrical vs heading Cylindrical equidistant projection case. Here the header should be changed to Equidistant cylindrical projection.

Even the projection word should should stay in the headers. I don't see now any reason why the table (which is a summary) and the headers should be exactly equal.

[WalterHFSmith]

Yvonne and Joaquim,
I am all for standardizing names and making things clear and avoiding confusion.

As far as I know, the only projection known as Mercator is a cylindrical projection, so perhaps one can drop the term "cylindrical" from Mercator, if that helps to standardize the nomenclature.

But note that there are many cylindrical projections (conformal = Mercator, but also equal area and others) and they can be in various aspects (cylinder tangent on any great circle, not necessarily the Equator), so in general we cannot drop "cylindrical" from a name.

Sorry, these comments from me are not much help.

I am glad you are doing this.

Walter

[joa-quim]

I'm fine with this.

[seisman]

Even the projection word should should stay in the headers.

@yvonnefroehlich Please make sure that all headers in doc/rst/source/reference/map-projections.rst end with projection.

[yvonnefroehlich]

Even the projection word should should stay in the headers.

@yvonnefroehlich Please make sure that all headers in doc/rst/source/reference/map-projections.rst end with projection.

I apologise for the delay with this PR, I will try to continue here at the end of the week (or the weekend). Thanks a lot for all yor comments and suggestions so far 🙂!

[yvonnefroehlich]

Even the projection word should should stay in the headers.

@yvonnefroehlich Please make sure that all headers in doc/rst/source/reference/map-projections.rst end with projection.

Done in the commits 8e9d524 (map-projections_.rst) and fd04088 (proj-codes_.rst).

[joa-quim]

Please, no not remove the equal area from headers.

[yvonnefroehlich]

Please, no not remove the equal area from headers.

Done in commit 40930b4.

Hm. At the moment I am a bit lost regarding how I should actually change the projection names to make them more consistent /: .

[joa-quim]

Thanks. The equal area is an information that the projection is using an authalic surface and is important to say in the summary table. On the projections description that information is stated more explicitly (AFAIK).

change the projection names to make them more consistent

Consistent with what? As I mentioned before, in my view, a table summary does not need to be exactly equal the headers in the projections page. But I understand you and confess to be also confused by now. IMO, things like they were served us perfectly during > 30 years (were written by the author) and didn't need any particular change.

[seisman]

I guess we should keep the projection names unchanged. The suggestions below revert most changes.