Feature: Snyder Polyhedral Equal Area projections

docs/source/operations/options/azi.rst

@@ -0,0 +1,5 @@
+.. option:: +azi=<value>
+
+    Azimuth from the polyhedron's first vertex to its second, in degrees.
+    Together with ``+orient_lat`` and ``+orient_lon`` this fully constrains
+    the 3D pose of the polyhedron on the sphere.

docs/source/operations/options/lat_0_polyhedral.rst

@@ -0,0 +1,18 @@
+.. option:: +lat_0=<value>
+
+    Geodetic latitude of the geographic point that should land at the
+    projected origin ``(0, 0)``. Used together with ``+lon_0``; the pair
+    translates the projected output without rotating the polyhedron.
+    ``+x_0`` / ``+y_0`` are applied on top of this translation.
+
+    When unset, the projected origin falls on the unfold's root face
+    instead (its centroid in general, or its bounding-box centre for
+    ``+proj=isea``) rather than at a fixed lat / lon.
+
+    .. note::
+        The default convention is to interpret this value as decimal degrees. To
+        specify radians instead, follow the value with the "r" character.
+
+        Example: `+lat_0=1.570796r`
+
+        See :ref:`Projection Units <projection_units>` for more information.

docs/source/operations/options/lon_0_polyhedral.rst

@@ -0,0 +1,18 @@
+.. option:: +lon_0=<value>
+
+    Geodetic longitude of the geographic point that should land at the
+    projected origin ``(0, 0)``. Used together with ``+lat_0``; the pair
+    translates the projected output without rotating the polyhedron.
+    ``+x_0`` / ``+y_0`` are applied on top of this translation.
+
+    When unset, the projected origin falls on the unfold's root face
+    instead (its centroid in general, or its bounding-box centre for
+    ``+proj=isea``) rather than at a fixed lat / lon.
+
+    .. note::
+        The default convention is to interpret this value as decimal degrees. To
+        specify radians instead, follow the value with the "r" character.
+
+        Example: `+lon_0=1.570796r`
+
+        See :ref:`Projection Units <projection_units>` for more information.

docs/source/operations/options/orient_lat.rst

@@ -0,0 +1,5 @@
+.. option:: +orient_lat=<value>
+
+    Geodetic latitude of the polyhedron's first vertex, in degrees. Together
+    with ``+orient_lon`` and ``+azi`` this fully constrains the 3D pose of
+    the polyhedron on the sphere.

docs/source/operations/options/orient_lon.rst

@@ -0,0 +1,5 @@
+.. option:: +orient_lon=<value>
+
+    Longitude of the polyhedron's first vertex, in degrees. Together with
+    ``+orient_lat`` and ``+azi`` this fully constrains the 3D pose of the
+    polyhedron on the sphere.

docs/source/operations/projections/all_images.rst

@@ -644,12 +644,12 @@ List of all projection images
 ********************************************************************************
 
 
-:ref:`isea`
+:ref:`isea_legacy`
 
 .. figure:: ./images/isea.png
    :width: 500 px
    :align: center
-   :alt:   isea
+   :alt:   isea_legacy
 
 
 ********************************************************************************

docs/source/operations/projections/dsea.rst

@@ -0,0 +1,125 @@
+.. _dsea:
+
+********************************************************************************
+Dodecahedral Snyder Equal Area
+********************************************************************************
+
+Snyder's equal-area mapping :cite:`Snyder1992` applied to the twelve pentagonal
+faces of a regular dodecahedron and unfolded into a planar net.
+
+The dodecahedron is subdivided into 12 × 10 = 120 right sub-triangles,
+and each sub-triangle is mapped independently using the area-preserving
+Snyder construction.
+
+See :ref:`polyhedral` for the shared theory.
+
++---------------------+----------------------------------------------------------+
+| **Classification**  | Polyhedral, equal area                                   |
++---------------------+----------------------------------------------------------+
+| **Available forms** | Forward and inverse, spherical and ellipsoidal           |
++---------------------+----------------------------------------------------------+
+| **Defined area**    | Global                                                   |
++---------------------+----------------------------------------------------------+
+| **Alias**           | dsea                                                     |
++---------------------+----------------------------------------------------------+
+| **Domain**          | 2D                                                       |
++---------------------+----------------------------------------------------------+
+| **Input type**      | Geodetic coordinates                                     |
++---------------------+----------------------------------------------------------+
+| **Output type**     | Projected coordinates                                    |
++---------------------+----------------------------------------------------------+
+
+
+.. figure:: ./images/dsea_net.png
+   :width: 500 px
+   :align: center
+   :alt:   Dodecahedral Snyder Equal Area
+
+   proj-string: ``+proj=dsea``
+
+
+Nets
+################################################################################
+
+dsea (default)
+--------------------------------------------------------------------------------
+
+Snyder's layout (Figure 11).
+
+.. figure:: ./images/dsea_net.png
+   :width: 500 px
+   :align: center
+   :alt:   DSEA default net
+
+   proj-string: ``+proj=dsea``
+
+a5
+--------------------------------------------------------------------------------
+
+Layout used by the `A5 index <https://a5geo.org>`_. First 8 faces contain the
+majority of the populated land mass.
+
+.. figure:: ./images/dsea_a5_net.png
+   :width: 500 px
+   :align: center
+   :alt:   DSEA A5 net
+
+   proj-string: ``+proj=dsea +net=a5``
+
+crescent
+--------------------------------------------------------------------------------
+
+.. figure:: ./images/dsea_crescent_net.png
+   :width: 500 px
+   :align: center
+   :alt:   DSEA crescent net
+
+   proj-string: ``+proj=dsea +net=crescent``
+
+flower
+--------------------------------------------------------------------------------
+
+.. figure:: ./images/dsea_flower_net.png
+   :width: 500 px
+   :align: center
+   :alt:   DSEA flower net
+
+   proj-string: ``+proj=dsea +net=flower``
+
+
+Parameters
+################################################################################
+
+.. note::
+    All parameters are optional.
+
+.. option:: +net=<name>
+
+    Selects the planar unfolding. Accepted values: ``dsea``, ``a5``,
+    ``crescent``, ``flower``.
+
+    *Defaults to* ``dsea``.
+
+.. include:: ../options/orient_lat.rst
+
+*Defaults to* ``atan((1 + 2·cos(36°))/2) ≈ 52.6226°``.
+
+.. include:: ../options/orient_lon.rst
+
+*Defaults to −36.0 (or −129.0 when* ``+net=a5`` *).*
+
+.. include:: ../options/azi.rst
+
+*Defaults to 240.0.*
+
+.. include:: ../options/lat_0_polyhedral.rst
+
+.. include:: ../options/lon_0_polyhedral.rst
+
+.. include:: ../options/x_0.rst
+
+.. include:: ../options/y_0.rst
+
+.. include:: ../options/ellps.rst
+
+.. include:: ../options/R.rst

docs/source/operations/projections/index.rst

@@ -39,6 +39,7 @@ Projections map the spherical 3D space to a flat 2D space.
    comill
    crast
    denoy
+   dsea
    eck1
    eck2
    eck3
@@ -71,6 +72,8 @@ Projections map the spherical 3D space to a flat 2D space.
    imoll_o
    imw_p
    isea
+   isea_legacy
+   polyhedral
    kav5
    kav7
    krovak
@@ -147,6 +150,7 @@ Projections map the spherical 3D space to a flat 2D space.
    tobmerc
    tpeqd
    tpers
+   tsea
    ups
    urm5
    urmfps

docs/source/operations/projections/isea.rst

@@ -4,16 +4,19 @@
 Icosahedral Snyder Equal Area
 ********************************************************************************
 
-Snyder's Icosahedral Equal Area map projection on an icosahedron polyhedral globe
-offers relatively low scale and angular distortion. The equations involved are
-relatively straight-forward. The interruptions remain a disadvantage, as with
-any low-error projection system applied to the entire globe :cite:`Snyder1992`.
-This projection is used as a basis for defining discrete global grid hierarchies.
+Snyder's equal-area mapping :cite:`Snyder1992` applied to the twenty triangular
+faces of a regular icosahedron and unfolded into a planar net.
+
+The icosahedron is subdivided into 20 × 6 = 120 right sub-triangles, and each
+sub-triangle is mapped independently using the area-preserving Snyder
+construction.
+
+See :ref:`polyhedral` for the shared theory.
 
 +---------------------+----------------------------------------------------------+
 | **Classification**  | Polyhedral, equal area                                   |
 +---------------------+----------------------------------------------------------+
-| **Available forms** | Forward and inverse, spherical                           |
+| **Available forms** | Forward and inverse, spherical and ellipsoidal           |
 +---------------------+----------------------------------------------------------+
 | **Defined area**    | Global                                                   |
 +---------------------+----------------------------------------------------------+
@@ -27,66 +30,79 @@ This projection is used as a basis for defining discrete global grid hierarchies
 +---------------------+----------------------------------------------------------+
 
 
-.. figure:: ./images/isea.png
+.. figure:: ./images/isea_net.png
    :width: 500 px
    :align: center
    :alt:   Icosahedral Snyder Equal Area
 
    proj-string: ``+proj=isea``
 
-.. note::
-   As the projection is only defined on a sphere, it should only be used
-   with a spherical ellipsoid e.g., ``+R=6371007.18091875`` for a sphere with the
-   authalic radius of the WGS84 ellipsoid. For mapping coordinates on the WGS84
-   ellipsoid to the authalic sphere, the input latitude should be converted
-   from geodetic latitude to authalic latitude. A future version may
-   automatically perform this conversion when using a non-spherical ellipsoid.
 
-Parameters
+Nets
 ################################################################################
 
-.. note:: All parameters are optional for the projection.
+``isea`` ships a single net (Snyder's Figure 12). Two named orientations of
+that net are available via ``+orient=``.
+
+isea (default)
+--------------------------------------------------------------------------------
 
-.. option:: +orient=<string>
+Snyder's layout (Figure 12).
 
-    Can be set to either ``isea`` or ``pole``.  See Snyder's Figure 12 for pole orientation :cite:`Snyder1992`.
+.. figure:: ./images/isea_net.png
+   :width: 500 px
+   :align: center
+   :alt:   ISEA default orientation
+
+   proj-string: ``+proj=isea``
 
-    *Defaults to isea*
+pole
+--------------------------------------------------------------------------------
 
-.. option:: +azi=<value>
+One icosahedron vertex placed on the geographic north pole.
 
-    Azimuth.
+.. figure:: ./images/isea_pole_net.png
+   :width: 500 px
+   :align: center
+   :alt:   ISEA pole orientation
 
-    Not supported by the inverse.
+   proj-string: ``+proj=isea +orient=pole``
 
-    *Defaults to 0.0*
 
-.. option:: +aperture=<value>
+Parameters
+################################################################################
 
-    Not supported by the inverse.
+.. note::
+    All parameters are optional.
 
-    *Defaults to 3.0*
+.. option:: +orient=<name>
 
-.. option:: +resolution=<value>
+    Shorthand for two named orientations. Accepted values: ``isea``, ``pole``.
+    Equivalent to setting ``+orient_lat`` / ``+orient_lon`` / ``+azi``
+    explicitly; individual ``+orient_*`` parameters still override.
 
-    Not supported by the inverse.
+    *Defaults to* ``isea``.
 
-    *Defaults to 4.0*
+.. include:: ../options/orient_lat.rst
 
-.. option:: +mode=<string>
+*Defaults to ~58.40° geodetic (arctan(φ) ≈ 58.2825° authalic).*
 
-    Can be either ``plane``, ``di``, ``dd`` or ``hex``.
+.. include:: ../options/orient_lon.rst
 
-    Only ``plane`` supported by the inverse.
+*Defaults to 11.25° on a sphere, 11.20° on an ellipsoid.*
 
-    *Defaults to plane*
+.. include:: ../options/azi.rst
 
-.. include:: ../options/lon_0.rst
+*Defaults to 0.0.*
 
-.. include:: ../options/lat_0.rst
+.. include:: ../options/lat_0_polyhedral.rst
 
-.. include:: ../options/R.rst
+.. include:: ../options/lon_0_polyhedral.rst
 
 .. include:: ../options/x_0.rst
 
 .. include:: ../options/y_0.rst
+
+.. include:: ../options/ellps.rst
+
+.. include:: ../options/R.rst