Doc page for Gall projection

2 files changed, 76 insertions, 0 deletions

diff --git a/docs/source/projections/gall.rst b/docs/source/projections/gall.rst
index 66c948d4..b9120d9f 100644
--- a/docs/source/projections/gall.rst
+++ b/docs/source/projections/gall.rst
@@ -4,7 +4,81 @@
 Gall (Gall Stereographic)
 ********************************************************************************
 
+The Gall stereographic projection, presented by James Gall in 1855, is a cylindrical projection.
+It is neither equal-area nor conformal but instead tries to balance the distortion inherent in any projection.
+
++---------------------+--------------------------------------------------------------------------------+
+| **Classification**  | Transverse and oblique cylindrical                                             |
++---------------------+--------------------------------------------------------------------------------+
+| **Available forms** | Forward and inverse, Spherical                                                 |
++---------------------+--------------------------------------------------------------------------------+
+| **Defined area**    | Global                                                                         |
++---------------------+--------------------------------------------------------------------------------+
+| **Implemented by**  | Gerald I. Evenden                                                              |
++---------------------+--------------------------------------------------------------------------------+
+| **Options**         | No special options for this projection                                         |
++---------------------+--------------------------------------------------------------------------------+
+
+
 .. image:: ./images/gall.png
    :scale: 50%
    :alt:   Gall (Gall Stereographic)  
 
+Usage
+#####
+
+The need for a world map which avoids some of the scale exaggeration of the Mercator projection has led to some commonly used cylindrical modifications, as well as to other modifications which are not cylindrical.
+The earliest common cylindrical example was developed by James Gall of Edinburgh about 1855 (Gall, 1885, p. 119-123).
+His meridians are equally spaced, but the parallels are spaced at increasing intervals away from the Equator.
+The parallels of latitude are actually projected onto a cylinder wrapped about the sphere, but cutting it at lats. 45° N. and S., the point of perspective being a point on the Equator opposite the meridian being projected.
+It is used in several British atlases, but seldom in the United States.
+The Gall projection is neither conformal nor equal-area, but has a blend of various features.
+Unlike the Mercator, the Gall shows the poles as lines running across the top and bottom of the map.
+
+
+Example using Gall Stereographical  ::
+
+    $ echo 9 51 | proj +proj=gall +lon_0=0 +x_0=0 +y_0=0 +ellps=WGS84 +datum=WGS84 +units=m +no_defs 
+    708432.90	5193386.36
+
+Example using Gall Stereographical (Central meridian 90°W) ::
+
+    $ echo 9 51 | proj +proj=gall +lon_0=90w +x_0=0 +y_0=0 +ellps=WGS84 +datum=WGS84 +units=m +no_defs
+    7792761.91	5193386.36
+
+Mathematical definition
+#######################
+
+The formulas describing the Gall Stereographical are all taken from Snyder's [Snyder1993]_.
+
+Spherical form
+**************
+
+Forward projection
+==================
+
+.. math::
+
+   x = \frac{\lambda}{\sqrt{2}}
+
+.. math::
+
+   y = (1+\frac{\sqrt{2}}{2}) \tan(\phi/2)
+
+Inverse projection
+==================
+
+.. math::
+
+  \phi = 2 \arctan( \frac{y}{1+\frac{\sqrt{2}}{2}} ) 
+
+.. math::
+
+  \lambda = \sqrt{2} x
+
+
+Further reading
+###############
+
+#. `Wikipedia <https://en.wikipedia.org/wiki/Gall_stereographic_projection>`_
+#. `Cartographic Projection Procedures for the UNIX Environment-A User's Manual <http://sites.lsa.umich.edu/zhukov/wp-content/uploads/sites/140/2014/08/projection-procedures.pdf>`_
diff --git a/docs/source/references.rst b/docs/source/references.rst
index 80b86c55..e6ddcc31 100644
--- a/docs/source/references.rst
+++ b/docs/source/references.rst
@@ -13,6 +13,8 @@ References
 
 .. [Snyder1987] Snyder. John P. 1987. `Map Projections - A Working Manual <https://github.com/OSGeo/proj.4/blob/master/docs/old/USGS-Snyder-Map-Projections-A-Working-Manual-1987.pdf>`_. US. Geological Survey professional paper; 1395.
 
+.. [Snyder1993] Snyder, 1993, Flattening the Earth, Chicago and London, The university of Chicago press
+
 .. [EberHewitt1979] Eber, L.E., and R.P. Hewitt. 1979. `Conversion algorithms for the CALCOFI station grid <http://www.calcofi.org/publications/calcofireports/v20/Vol_20_Eber___Hewitt.pdf>`__. California Cooperative Oceanic Fisheries Investigations Reports 20:135-137.
 
 .. [WeberMoore2013] Weber, E.D., and T.J. Moore. 2013. `Corrected Conversion Algorithms For The Calcofi Station Grid And Their Implementation In Several Computer Languages <http://calcofi.org/publications/calcofireports/v54/Vol_54_Weber.pdf>`__. California Cooperative Oceanic Fisheries Investigations Reports 54.