Feature: Snyder Polyhedral Equal Area projections

[felixpalmer]

• Claude Code supported my development of this PR. See our policy about AI tool use. Use of AI tools must be indicated.
• Tests added
• Added clear title that can be used to generate release notes
• Fully documented, including updating docs/source/*.rst for new API

Background

Please read the updated documentation in docs/source/operations/projections/polyhedral.rst first as well as Snyder's original paper: AN EQUAL-AREA MAP PROJECTION FOR POLYHEDRAL GLOBES (CARTOGRAPHICA Vol 29 No 1 SPRING 1992 pp 10–21)

Back-compatibility with existing isea

Gives same results, with comparisons in test/gie/builtins.gie. I would propose we remove the old isea code, replacing with this implementation.

Architecture

To define a projection a polyhedron and net must be defined. The simplest example is that of the 4-sided tetrahedron along with the net definitions:

• tetrahedron.h specifies a list of 3D vertices and faces indexing those vertices
• tsea.h specifies a list of parents, with 0 as the root

These details are not exposed to the user via the PROJ API, instead they reference them by name, e.g. +proj=tsea +net=star

When building the projection, the following process followed:

• Options parsed and populated into pj_polyhedral_data struct
• polyhedral::load_meshes called with the selected polyhedron and matching net, which:
  • Unfolds the net by starting with the root face and then attaching other faces in a 2D plane
  • Applies a Conway meta operation to cut up the polyhedron and net faces into right-triangles
  • Stores the 2 resulting triangle lists on pj_polyhedral_data
• The Snyder forward and inverse projection is then defined independently between each of these paired triangles

The design is generic and adding polyhedra/nets is straightforward and doesn't require large code updates

Change list

• Snyder projection functions: snyder_fwd & snyder_inv
• Unfolding helpers
• Conway helpers
• Spherical geometry helpers
• Basic 3D vector operation and helpers
• 3 polyhedrons: Tetrahedron, Dodecahedron & Icosahedron and some nets for each
• Tests

Example renders ISEA

Example renders TSEA

Example renders DSEA

[felixpalmer]

@jerstlouis @rouault @sahrk @jjimenezshaw @ldesousa @mikima @busstoptaktik @ppKrauss @thangqd

[jerstlouis]

@felixpalmer Lots of cool stuff here :) Thank you for this!

As discussed in #4389 (comment) , I was also planning to propose a replacement for the current ISEA projection based on a generalized ISEA / RTEA / IVEA method, using a closed-form inverse solution, and address some issues with the current set of parameters.

You've taken that a step further with support for different polyhedron nets (and multiple unfolding setups too!!) which is also very cool. Is this using Snyder's original equations, which did not have a closed-form inverse, or the Slice and Dice approach with closed form inverse? We should discuss :)

I was also going to test some further improvements suggested by @brsr which could potentially fully remove the need for Slerp in the inverse.

Roundtrip test (less than 1nm roundtrip error)

That is quite impressive. Was that tested throughout the globe surface or only for some specific test points?

cc. @mpadillaruiz @ppKrauss

[felixpalmer]

@jerstlouis the equations are from A5, DGGAL and BRSR, as noted in the header. I didn't reference Slice & Dice for the code, but it is possible that the 3 sources did.

I'm open to improvements to the code and equations (e.g. removing the slerp()), one thing I would like to keep is the modular framework I've designed, which makes it easy to add new polyhedra/projections/nets (see my follow-up PRs for how easy it is)

The roundtrip error is just based on a static set of points, you're right that perhaps it is worse if this is expanded across the globe

[jerstlouis]

@felixpalmer In particular, to replace the current isea, we should:

• Have orient_lat, orient_lon and azi parameters that determine the position of the first vertex (with geodetic latitude), and azi as the azimuth to the next vertex (based on whichever polyhedron is chosen), and for the icosahedron net unfolding (ISEA / IVEA / RTEA) the default should be authalic latitude at arctan(golden ratio) converted to geodetic latitude, 11.20 East, and possibly 11.25 E in the case where you specifically request the sphere rather than GRS80 as the ellipsoid for backward compatibility with the current +proj=isea projection.

EDIT: It seems that you already support this with polyhedral::set_orient_from_angles(Q, ISEA_STD_LAT_DEG, ISEA_STD_LON_DEG, IVEA_AZ_DEG);, though as I was saying we should use 11.2 E instead of 11.25 E when the GRS80 ellipsoid is used (which should be the new default, latitude should be ~58.397145907431 N (geodetic).

Would specifying the rhombic triacontahedron solid naturally yield the RTEA projection (as in DGGAL, https://www.mdpi.com/2220-9964/9/5/315, and https://www.tandfonline.com/doi/full/10.1080/17538947.2022.2130459?utm_source=researchgate.net&utm_medium=article ?

I see the special names of Hexakis icosahedron and Decakis dodecahedron that you give to the disdyakis triacontahedron, but based on Snyder's paper specifically, the center of the faces is what is used for tracing the great circles, so the names of the solids would be the Dodecahedron and the Icosahedron (as per the DSEA and ISEA acronyms), right? And for Rhombic Triacontahedron that also naturally yields RT(S)EA. It's a very nice feature to be able to unfold them onto the different nets. Would this unfolding also work on polyhedrons without icosahedral symmetry? The unfolding net needs to have same symmetry as the projection solid?

[felixpalmer]

@jerstlouis could we continue the ISEA discussion here? I've given you access, feel free to update the constants - you understand them better than me. As you say it is already supported by the code.

naturally yield the RTEA projection?

I believe so, the code is designed to be a generic spherical-planar triangle mapper so you would just need to generate the relevant config files. The ISEA PR is a good example of what is required to add a new projection & polyhedron

special names of Hexakis icosahedron and Decakis dodecahedron

Yes I thought a lot about the naming. I settled on this approach as the name tells us which vertex to use as the apex and how many triangles to cut the face into. See the docs for details

For brevity (and following the example set by ISEA) I chose to just use the underlying platonic solid when naming the projection, e.g. DSEA, TSEA etc

Would this unfolding also work on polyhedrons without icosahedral symmetry?

Yes, this PR literally implements TSEA, which is on a (hexakis) tetrahedron. It should also work on other more complex nets, like the truncated icosahedron or even a Myriahedron. The unfolding net just needs to have the same number of triangles. Technically, they don't even need to be connected as a net, you could float them in space separately. And implementing your 5x6 net is as simple as adding a new config file

[jerstlouis]

Yes I thought a lot about the naming. I settled on this approach as the name tells us which vertex to use as the apex and how many triangles to cut the face into.

Yes, but technically these all refer to the same polyhedron, and I wonder if there couldn't be a more explicitly way to describe it, especially if we consider the possibility to specify the polyhedron and the choice of radiating vertex as projection parameters.

For the RTEA configuration, would the name specifying that great circle setup mapping for the d120 be kisrhombic triacontahedron ?

Also of course I'm very curious whether this modularity would help test the Archmidean solids configuration like the Truncated Icosahedron (TISEA / TIVEA), and still map that to the icosahedral net and the 5x6 space :)

[felixpalmer]

RTEA configuration, would the name specifying

I think it should be tetrakis (rhombic) triacontahedron - so a triacontahedron with each face cut into 4

It is true that these all have the same vertices, but by naming them this way you can avoid the whole "radiating vertex" concept as the apex is always in the center of the base polyhedron face (the tip of the kis pyramid)

[jerstlouis]

@felixpalmer Thanks, I am starting to understand how these *kis prefixes work :)

tetrakis rhombic triacontahedron makes sense, kis pyramids with 4 faces on each of the 30 faces of the rhombic triacontahedron. kisrhombic triacontahedron is one of the name of the d120 mentioned on https://en.wikipedia.org/wiki/Disdyakis_triacontahedron and likely just a shorthand for that longer name. And apparently "disdya" means twice two-fold (also 4), so disdyakis triacontahedron, tetrakis rhombic triacontahedron, kisrhombic triacontahedron would all naturally mean the RT(S)EA setup.

[kbevers]

Converted to draft PR to safe-guard against a premature merge. There's a lot going on in this PR request. This looks impressive but from my very superficial first glance it seems as if there's reimplementations of already existing functionality. In particular, my spidey sense is triggered by authalic.h and the python code to create figures for the documentation. Is this Claude spewing out tons of code without consideration for the existing code base?

[jerstlouis]

@kbevers The authalic conversion stuff is something that I pointed out before in the codebase was already duplicated in multiple places, and which would be nice to re-use throughout (in multiple other projections). Also the version in this PR in the current stage I think is not taking into consideration the selected ellipsoid's flattening which it ideally should... trying to work with @felixpalmer on improving a few things.

[felixpalmer]

As noted in the changelist, the render scripts are purely to help reviewers recreate the images. The authalic conversion @jerstlouis already pointed out is likely implemented in a number of places in the codebase and I agree we should be leveraging the existing code. I would love to reduce the amount of code added, I'm aware that it is a lot, @jerstlouis is interested in collaborating on this

[felixpalmer]

@jerstlouis @kbevers I've removed the authalic.h file, replacing it with the built-in pj_authalic_... functions

[jerstlouis]

@brsr @felixpalmer @kbevers

The projection in 1 can be used on its own, independent from any global partitioning scheme. It would have mandatory parameters +lat_1 +lon_1 +lat_2 +lon_2 +lat_3 +lon_3. This is an interesting projection in its own right and is worth making accessible by itself.

Perhaps as a first step we could go back to splitting that more general code for a specific triangle into the common shared src/ tree, where e.g. airocean could re-use it? A future PR could then potentially expose that generic triangle projection requiring three anchor points parameters, if that is deemed useful?

(actually I think it is still split in the last version, but inside polyhedral/, as src/projections/polyhedral/snyder.h ?)

[jerstlouis]

@felixpalmer @kbevers

Would it be possible to update the PROJ scripts to be able to optionally show that red dot where the default projected 0,0 happens to be?

The previous images with the red dot were a very significant improvement showing where that happens to be compared to the previous version (and the images currently in this PR after the recent change). Not having this clearly illustrated is a major pain point in trying to use these projections.

[jerstlouis]

@felixpalmer

Applies a Conway meta operation to cut up the polyhedron and net faces into right-triangles

I don't think the meta operation necessarily results in right triangles? (though for the trigonometric formulation, the math is different as it cannot assume one angle is 90 degrees).
Taking the rhombic triacontahedron (RTEA), I think the meta operation does not yield right-triangles, but the triangles before the full split (splitting the RT faces into 4) yields right triangles (the 120 disdyakis triacontahedron triangles).

Wondering if you made the optimization yet where actually for the typical unfolding the full meta operation is not necessary (you only need it if the net explicitly unfolds the two different parts of the fanned triangles from face center to face vertices into a specially cut-out net -- just the kis operation is otherwise enough). The future custom nets would allow that, but none of the the current hardcoded configurations need that I think (only 12 projection triangles rather than 24 are necessary for the tetrahedron, and only 60 rather than 120 are needed for the dodecahedron and icosahedron)

[felixpalmer]

@brsr thanks for the input and your great work this PR has built on.

Long-term agree the partitioning code should be sharable with airocean / s2 / healpix, but pushing back on adding that here. The PR is already a lot and the cross-projection consolidation is its own design conversation. I've moved vec3.h and vec3_helpers.h (renamed sphere.h) to src/ to address @kbevers's "too much code in src/projections/" point. That gives future shared partitioning a place to pull primitives from, and snyder.h is already standalone, so the lift you're describing is partly done.

@jerstlouis red-dot: agree it's useful UX, but it's a plot.py change rather than just plotdefs, and applies to other projections with non-obvious origins too. One for a follow-up.

I don't think the meta operation necessarily results in right triangles?

If the face is a regular polygon it does. You're right that this won't work for RTEA but let's deal with that in the future if we add that projection

[jerstlouis]

@rouault Does #4758 (comment) mean that this PR could potentially be considered for 9.9.0? Thanks!

[rouault]

I'm +0 on this PR, meaning it looks OK to be merged, but without understanding of the domain. @kbevers ?

[jjimenezshaw]

I want to review this PR. Unfortunately I didn't have time until now (looking at the size of it is not helping).
I see its usefulness. Let's see if I find time this weekend.

About identifying the faces, I had the idea to use a false norting or easting as a prefix per face, as done in EPSG:5649, EPSG:4647 and EPSG:5650 to identify the UTM zone. But it can (must) be done in a later PR.

[jerstlouis]

Thank you @jjimenezshaw !

Regarding the face identification, my preference would be to stick to the numbers used in Figure 4 of Snyder's original 1992 paper -- at least for the polyhedra that are present there (the dodecahedron, icosahedron and truncated icosahedron), and we can extend this to other nets based on the left-to-right, top-to-bottom simple increasing integers.

This PR is indeed incredibly useful:

• It fixes multiple issues identified in Missing areas when using ISEA projection when +orient is "isea" #4389, including correcting precision issues in certain regions, fixing misleading parameters and adding missing parameter support (e.g., azimuth for the inverse),
• It implements proper support for ellipsoids in ISEA which is currently blocking for correctly calculating areas in PostGIS for AddressForAll ( Testing the new PROJ version with DGGS AddressForAll/suporte#86 )
• It provides major performance improvements for the inverse in particular as it implements a closed-form solution rather than an iterative solution, and for both the forward and inverse because it replaces almost all trigonometry with linear algebra (though we will likely have a follow-up PR for further reducing use of trigonometry as per ecere/dggal@8153942 and feat: More efficient equal area projection felixpalmer/a5#108),
• It provides major precision improvements, achieving roundtrip precision around the micrometer scale
• It implements the additional DSEA and TSEA projections, will allow to easily implement IVEA in a follow-up PR which avoids the cusps issues of ISEA (e.g., see Figure B.16 in OGC API - DGGS) while sticking to the icosahedral net that facilitates hexagonal tessellations, as well as to generalize to other polyhedra such as the Truncated Icosahedron described in Snyder's 1992 paper, and to unfold unto other arbitrary nets such as the useful icosahedral/rhombic 5x6 space (see Figure B.1 in OGC API - DGGS), or nets with e.g., contiguous land masses such as the Dymaxion arrangement.

Please note that I also did carefully review this PR, and it is directly related to our on-going paper clarifying and explaining these icosahedral projections together with @ldesousa @mpadillaruiz @brsr and @felixpalmer .

The size of the PR is because it is a rewrite / generalization of these polyhedral projections based on proven implementations in DGGAL/GNOSIS and A5, which are based on additional simplification of Snyder's polyhedral projections described in Slice & Dice, as well as by @brsr, myself and @felixpalmer . Despite this much more general and optimal rewrite, as @felixpalmer pointed out, the total size of the code is still smaller than the current version.

[jjimenezshaw]

The PR looks ok to me. I didn't check the mathematical formulas, but as the final outputs make sense, I expect they are right.

About structs without initialization, I prefer initializing them always. Years later some code is not working "randomly" due to some garbage in the memory. Specially differently in debug and release, that is really annoying.

[jjimenezshaw]

will this code fail reading an "old" string?

[jerstlouis]

As discussed in #4389 (comment), we removed the aperture, resolution and mode parameters, as they have nothing to do with the projection, but with a particular tessellation of the space at some refinement level (and they were not properly documented or tested either).

Besides removing these three parameters, there are a couple other minor breaking changes with the previous strings:

• Since the projection now supports ellipsoids, it defaults to GRS80 like any other projection that does rather than a perfect sphere, so that one needs to explicitly use +ellps=WGS84 +R_A to bring back the old behavior,
• The meaning of +lat_0 and +lon_0 have changed from being the orientation of the icosahedron (which is now properly renamed +orient_lat and +orient_lon) to being the geodetic coordinates of the +x_0 and +y_0 projected point (0,0 by default).

When selecting a spherical ellipsoid (e.g., +ellps=WGS84 +R_A), we have kept the default values for what is now+orient_lat and +orient_lon for backward compatibility. Otherwise, the default +orient_lon is shifted 0.05 degrees West (+orient_lon=11.2 instead of 11.25 E) by default for ISEA to avoid a vertex of the icosahedron falling on land when taking the ellipsoid into consideration (this avoids pentagonal zones on land in hexagonal tessellations at the finer levels).

The +azi parameter is now also properly supported by the inverse.

So:

• If an "old" string uses any of aperture, resolution or mode (other than plane) -- yes it won't work anymore,
• If an "old" string does not already explicitly specify a spherical ellipsoid/radius -- the projection will be very slightly different, taking the GRS80 ellipsoid into account and with the icosahedron orientation shifted by 0.05 degrees West.
• If an "old" string uses +lat_0 or +lon_0 -- the result will be very different as the meaning of those parameters changed completely

[kbevers]

As Javier I've been put of by the size of this PR and have also had other more important (to me) things to do. I'll try to find some time early next week.

[kbevers]

Overall I think the work in this PR is solid although I do have some hesitation based on the complexity of the pull request. Especially as it's from a new contributor. Nothing personal, I have no reason to believe the work isn't good but I don't know what to expect regarding maintenance of this code in the long term.

I am in favour of @brsr's suggestion:

[...] split this pull up into more easily digestible pieces. I think of this pull as having two conceptual parts:

1. Code for a generalized version of the triangular projection described in Snyder's 1988 paper.
2. Code for separating the sphere into specified triangular regions, defining corresponding triangular regions in the plane, and keeping track of which projection object transforms between which pair of spherical and planar triangles.

In particular, I am missing the generalized projection mentioned in 1. Having a general +proj=polyhedral would allow for the doc page docs/source/operations/projections/polyhedral.rst to fall in line with all the other similar doc page. I.e. the page would refer to a specific projection as all the other similar pages do. It has been mentioned previously that such a change is out of scope but I would argue that is the right place to start this change, as it makes the rest of the projections easy work to add, both in terms of code and documentation. I am hesitant to put this in as future work to be done since there's a fair change it will never get done.

[jerstlouis]

@kbevers Thank you for the review.

I don't know what to expect regarding maintenance of this code in the long term.

Aside from the fact that @felixpalmer will likely be around to help maintain this code, as the last contributor to this ISEA projection (adding the inverse support), I support this PR as the way forward, and also commit at the very least to provide guidance and clarify anything to anyone wishing to work on it.

I am in favour of @brsr's suggestion:

This is more or less already implemented with the first part in src/projections/polyhedral/snyder.h, and the second part in src/projections/polyhedral/unfold.h.

It has been mentioned previously that such a change is out of scope but I would argue that is the right place to start this change, as it makes the rest of the projections easy work to add, both in terms of code and documentation.

The underlying code of the general polyhedral projection is there and already re-usable from the code, with the TSEA, ISEA and DSEA projections very simple (the PROJ_HEAD sections in src/projections/polyhedral.cpp together with the corresponding polyhedra and net/ .h definitions. But to make it possible for users to use an arbitrary polyhedral projection without modifying the code, we need a generic way to reference a polyhedron by e.g., name truncated icosahedron, extended Schlafli t{3,5} or extended Wythoff symbols 5 2 | 3, and the ability to provide the net as a list of faces. I suggested something like this, but this would mean additional code and thus a significantly larger PR to review and merge :)

I am hesitant to put this in as future work to be done since there's a fair chance it will never get done.

I would very much like to see it done, so I think the odds are very good. However, if the consensus is that we should make +proj=polyhedral +polyhedron=t{3,5} +net=0,1,2,3,4... work now, so that the polyhedral.rst doc page corresponds to an actual directly usable projection, in order to get this merged, then I guess me and/or @felixpalmer need to have a go at it? :) It would likely require some generic polyhedron construction like Wythoff and net generation/validation logic (that I was actually prototyping when we started discussing this PR), which might turn out be a considerable amount of extra code.

[felixpalmer]

Thanks for the input

I don't know what to expect regarding maintenance

FWIW I have been a maintainer on deck.gl for the last ~5 years and have a personal interest in this projection as it is foundational to a project of mine. Understand your hesitation though, as I'm new here

I am in favour of @brsr's suggestion & I am missing the generalized projection mentioned in 1

Looks like this is the missing piece we need to cleanly land this. In terms of the API, I like what @brsr wrote regarding it being a simple projection that just maps between planar & spherical triangles, without any of the complexity of the nets/polyhedrons. Given that we are just considering a single triangle, it feels off though to call this projection "polyhedral", it is more a building block for a polyhedral projection. I would instead propose "snyder" as this is the core maths that is valuable here. So how about we go with:

+proj=snyder \
  +lon_a=A +lat_a=B +lon_b=C +lat_b=D +lon_c=E +lat_c=F \
  +x_a=G +y_a=H +x_b=I +y_b=J +x_c=K +y_c=L

• Using _a with rather than 1,2,3 to avoid confusion with existing parameters x_0/y_0 (easting/northing) and lat_1/lat_2 (standard parallels)
• x_a, y_a would have default values mapping to ((0,0), (1,0), (0,1))
• polyhedral.rst would become snyder.rst

The generic polyhedral projection you propose @jerstlouis feels like something that could later be built on top - valuable, but separate from what @brsr was asking for based on my reading.

How does this sound to you @kbevers @brsr @jerstlouis?

[kbevers]

@felixpalmer I think that sounds good. I am not familiar enough with the maths here to have useful input, so I hope others chime in if needed.

I am good with using +proj=snyder. What I'm hoping is that +proj=isea can be expressed in terms of +proj=snyder +lon_a=.... Can you confirm if that is the case?

[jerstlouis]

@felixpalmer

valuable, but separate from what @brsr was asking for based on my reading.

My reading was more as I commented above the split you already have with src/projections/polyhedral/snyder.h and src/projections/polyhedral/unfold.h, and the potential to re-use snyder.h (or a more generic name of it) internally in other similar projections, but I may well have misinterpreted it.

I was thinking that exposing +proj=snyder (as an individual triangle) to the end-user might have limited benefit (at least compared to the +proj=polyhedral), but perhaps it is useful, at least within the domain of validity of an individual SDT spherical tri? I'm particularly curious to test wether any given spherical triangle (other than the SDT) still maintain the equal-area property, that could facilitate testing that. I think @brsr mentioned being convinced about that, or even proved that is the case, but when I was looking into all this a while back that was not obvious at all (and both AIs and humans were convincing me otherwise! :))

But I agree that the +proj=polyhedral would be a lot of extra code on top of this PR, so I fully support this switch to +proj=snyder if that addresses the review concerns!

@kbevers

I am good with using +proj=snyder. What I'm hoping is that +proj=isea can be expressed in terms of +proj=snyder +lon_a=.... Can you confirm if that is the case?

For a global map, it unfortunately could only be expressed in terms of 60 or 120 different ones of these projections for polyhedra with full Icosahedral symetry (Ih) such as the dodecahedron and icosahedron. The +proj=snyder that @felixpalmer is suggesting is a more basic tool constrained within a single one of these triangles.

[felixpalmer]

Can you confirm if that is the case?

@kbevers no, as @jerstlouis says the proj string would be enormous and unwieldy as ISEA contains 120 such triangles.

What I'm trying to shield the users from is having to input all those values and instead refer to the whole projection including the polyhedrons using shorthands like isea. The +proj=snyder projection is still useful if people want to operate on the abstraction level of the triangles, rather than the whole globe

I will try and land the +proj=snyder code & docs in the next few days, the needed code is mostly plumbing, all the pieces should be there already.

[kbevers]

@kbevers no, as @jerstlouis says the proj string would be enormous and unwieldy as ISEA contains 120 such triangles.

Okay, I have clearly misunderstood how this all works (re my previous math disclaimer). It's probably not super useful to be able to produce a 120th of a full projection using a hypothetical +proj=snyder. So I don't want to push that further. I saw it as a neat way to generalize these projections as well as deal with the documentation a sensible fashion (basically by saying how a *sea-projection can be expressed by the generic implementation).

So, discarding the idea of +proj=snyder I think the main concern left for me is how to deal with the docs. In it's current state we have a doc page that sticks out a bit from the rest. The text in polyhedral.rst sounds to me like PROJ has a projection called "Polyhedral Snyder Equal Area" but in fact this is a group of projections whose details are described in other doc pages. Actually I think due to the way it's phrased I got lured into thinking this could be a generalized version of tsea, dsea and isea (as expressed previously).

When I go to https://proj.org/en/stable/operations/projections/index.html, I expect to get to the documentation of a specific projection when I click one of the links. I'd like to keep it that way. Probably the path of least resistance is to put polyhedral.rst up a level next to the pipeline operator (and the few other pages at that level). Individual doc pages for tsea, dsea and isea can reference polyhedral.rst without it looking like it's own projection.

[rouault]

Individual doc pages for tsea, dsea and isea can reference polyhedral.rst without it looking like it's own projection.

I wouldn't expose polyhedral.rst at a top level. There might be Sphinx tricks, like using a TOC in the tsea/dsea/isea pages to point to polyhedra.rst. Don't ask me how exactly, I've already forgotten... but I'm pretty sure there's a way. More a potential hint than a requirement. I'm fine with Kristian's suggestion as well

[kbevers]

I am open to suggestions for better solutions. This was just what I could come up with in two minutes. Another way could be to make folder for polyhedral.rst, pipeline.rst, operations_computation.rst and time_dependent_transformations.rst that exists at the same level as projections, transformations and conversions. Not sure what to call it though...

[felixpalmer]

@rouault perhaps you were thinking of the :orphan: metadata field?

Adding this allows us to remove the page from projections/index.html and the ToC, without having to move it to the top level. I've pushed a commit that does this

[jerstlouis]

@kbevers

Actually I think due to the way it's phrased I got lured into thinking this could be a generalized version of tsea, dsea and isea (as expressed previously).

To be clear, the original Snyder 1992 paper is titled "An Equal-Area Map Projection For Polyhedral Globes", and it is applicable to all Platonic solids, to the truncated icosahedron which is an Archimedean solid, and likely also to other Archimedean solids with full icosahedral symmetry (among others). The approach in this PR is better generalized compared to the original paper. So I do believe there is value in what you proposed, but I think it is different from @brsr 's suggestion which was for a given spherical triangle. Internally, this modularization of the code would already allow to re-use it in other projections utilizing the same math. As I said above, this user-facing separate triangle projection might also have some value for an end-user since the spherical triangle might be up to 1/8th of the globe (though I'm not personally 300% convinced that this would achieve equal-area), or for projecting a small region which fits within one of those 1/120th or 1/60th of the actual ISEA/DSEA projections -- but I also agree it's not essential and not pushing for it either.

I understand it might not be desirable to have the separate polyhedral.rst in the docs, so it is good if we can have it hidden from the ToC for now, and when we do add a generic +proj=polyhedral then we can bring it back. @felixpalmer is the general page still accessible from the individual projections now, so that we don't need to duplicate the shared content (general concepts and parameters)? That seems like the ideal solution.

Then when we add the generalized version we can re-enable it at the top level. To make the general version work we just need:

• A way to specify a general polyhedron (based on extended Wythoff, extended Schlafli or by common name) and construct it polyhedra.ec,
• A way to specify the net (we already have this internally as a list of 1-based parent face indices e.g., https://github.com/felixpalmer/PROJ/blob/32e570514af9ed90162462613a972fec086373c2/src/projections/polyhedral/nets/dsea/dsea.h#L38),
• A way to validate that net or automatically unfold onto a valid net nets.ec (this is the most complex part -- I am currently using a stripped down version intersections.ec (737 lines) of our DE9IM intersection engine for this).

I was also suggesting that we automatically infer whether the net refers to the triangles resulting from cutting out a fan from center of faces to vertices (the kis operation e.g., 5 triangles for a pentagonal face) vs. an extra split at the middle from the center (the meta operation e.g., 10 triangles for a pentagonal face) based on the number of indices supplied for the net list. e.g., 120 face indices refer to meta triangles, 60 face indices to the kis triangles. On top of that it would be great to have an embedded implementation of a 2D transform matrix so that we can implement the rhombic/icosahedral symmetry 5x6 space without needing +proj=pipeline (likely yet a separate PR).

I still need to put together a Web version of my demo app for this allowing to visually edit the nets (polyhedral.ec netWindow.ec).

[jerstlouis]

@felixpalmer BTW I still don't think see the star in +proj=tsea +net=star :)
It is not in the list of "Star polygons" here.

Were there any shuriken shaped that way? (I can't see any here -- does it work from an aerodynamics perspective?)

... and on an overly geeky note, I just realized there was an inverted tri-force in the Kingdom of Lorule (the opposite world parallel to Hyrule) in The Legend of Zelda: A Link Between Worlds .

+net=lorule_triforce ? ;)

+net=sierpinski? +net=centered?

Or simply +net=triangle :)

[kbevers]

@jerstlouis

So I do believe there is value in what you proposed

That's neat. I think you should open a separate issue for that for further discussion. You've basically already written it:

To make the general version work we just need:

• A way to specify a general polyhedron (based on extended Wythoff, extended Schlafli or by common name) and construct it polyhedra.ec,
• A way to specify the net (we already have this internally as a list of 1-based parent face indices e.g., https://github.com/felixpalmer/PROJ/blob/32e570514af9ed90162462613a972fec086373c2/src/projections/polyhedral/nets/dsea/dsea.h#L38),
• A way to validate that net or automatically unfold onto a valid net nets.ec (this is the most complex part -- I am currently using a stripped down version intersections.ec (737 lines) of our DE9IM intersection engine for this).

[jerstlouis]

@kbevers

That's neat. I think you should open a separate issue for that for further discussion. You've basically already written it:

Thanks! Exactly, that's why I said the odds are really good that it will happen earlier ;) That's essentially where I've spent the majority of my own efforts related to this PR ;)

I will open a separate issue.