Merge pull request #467 from kbevers/doc-final-migration-from-trac

Migrating the last doc pages from trac to proj4.org

7 files changed, 381 insertions, 11 deletions

diff --git a/docs/source/projections/geos.rst b/docs/source/projections/geos.rst
index 07779386..96884238 100644
--- a/docs/source/projections/geos.rst
+++ b/docs/source/projections/geos.rst
@@ -3,8 +3,70 @@
 ********************************************************************************
 Geostationary Satellite View
 ********************************************************************************
++---------------------+----------------------------------------------------------+
+| **Classification**  | Azimuthal                                                |
++---------------------+----------------------------------------------------------+
+| **Available forms** | Forward and inverse, spherical and elliptical projection |
++---------------------+----------------------------------------------------------+
+| **Defined area**    | Global                                                   |
++---------------------+----------------------------------------------------------+
+| **Implemented by**  | Gerald I. Evenden and Martin Raspaud$                    |
++---------------------+----------------------------------------------------------+
+| **Options**                                                                    |
++---------------------+----------------------------------------------------------+
+| `+h`                | Satellite height above earth. Required.                  |
++---------------------+----------------------------------------------------------+
+| `+sweep`            | Sweep angle axis of the viewing instrument.              |
+|                     | Valid options are ``x`` and ``y``. Defaults to ``y``.    |
++---------------------+----------------------------------------------------------+
+| `+lon_0`            | Subsatellite longitude point.                            |
++---------------------+----------------------------------------------------------+
+
 
 .. image:: ./images/geos.png
    :scale: 50%
-   :alt:   Geostationary Satellite View  
+   :alt:   Geostationary Satellite View
+
+The geos projection pictures how a geostationary satellite scans the earth at regular
+scanning angle intervals.
+
+
+Usage
+###############################################################################
+
+In order to project using the geos projection you can do the following::
+
+    proj +proj=geos +h=35785831.0
+
+The required argument ``h`` is the viewing point (satellite position) height above
+the earth.
+
+The projection coordinate relate to the scanning angle by the following simple
+relation::
+
+    scanning_angle (radians) = projection_coordinate / h
+
+
+Note on sweep angle
+-------------------------------------------------------------------------------
+
+The viewing instrument on-board geostationary satellites described by this
+projection have a two-axis gimbal viewing geometry. This means that the different
+scanning positions are obtained by rotating the gimbal along a N/S axis (or ``y``)
+and a E/W axis (or ``x``).
+
+.. image:: ../../images/geos_sweep.svg
+   :scale: 50%
+   :alt:   Gimbal geometry
+
+In the image above, the outer-gimbal axis, or sweep-angle axis, is the N/S axis (``y``)
+while the inner-gimbal axis, or fixed-angle axis, is the E/W axis (``x``).
+
+This example represents the scanning geometry of the Meteosat series satellite.
+However, the GOES satellite series use the opposite scanning geometry, with the
+E/W axis (``x``) as the sweep-angle axis, and the N/S (``y``) as the fixed-angle axis.
 
+The sweep argument is used to tell proj.4 which on which axis the outer-gimbal
+is rotating. The possible values are x or y, y being the default. Thus, the
+scanning geometry of the Meteosat series satellite should take sweep as x, and
+GOES should take sweep as y.
diff --git a/docs/source/projections/healpix.rst b/docs/source/projections/healpix.rst
index 093ae968..885ea3ea 100644
--- a/docs/source/projections/healpix.rst
+++ b/docs/source/projections/healpix.rst
@@ -3,8 +3,53 @@
 ********************************************************************************
 HEALPix
 ********************************************************************************
++---------------------+----------------------------------------------------------+
+| **Classification**  | Mixed                                                    |
++---------------------+----------------------------------------------------------+
+| **Available forms** | Forward and inverse, spherical and elliptical projection |
++---------------------+----------------------------------------------------------+
+| **Defined area**    | Global                                                   |
++---------------------+----------------------------------------------------------+
+| **Implemented by**  | Alex Raichev and Michael Speth                           |
++---------------------+----------------------------------------------------------+
+| **Options**                                                                    |
++---------------------+----------------------------------------------------------+
+| `No special options for this projection`                                       |
++---------------------+----------------------------------------------------------+
+
+.. image:: ../../images/healpix.png
+   :scale: 75%
+   :alt:   HEALPix
+
+The HEALPix projection is area preserving and can be used with a spherical and
+ellipsoidal model. It was initially developed for mapping cosmic background
+microwave radiation. The image below is the graphical representation of the
+mapping and consists of eight isomorphic triangular interrupted map graticules.
+The north and south contains four in which straight meridians converge polewards
+to a point and unequally spaced horizontal parallels. HEALPix provides a mapping
+in which points of equal latitude and equally spaced longitude are mapped to points
+of equal latitude and equally spaced longitude with the module of the polar
+interruptions.
+
+
+Usage
+###############################################################################
+
+To run a forward HEALPix projection on a unit sphere model, use the following command::
+
+    proj +proj=healpix +lon_0=0 +a=1 -E <<EOF
+    0 0
+    EOF
+    # output
+    0 0 0.00 0.00
+
+Further reading
+################################################################################
+
+#. `NASA <http://healpix.jpl.nasa.gov/>`_
+#. `Wikipedia <https://en.wikipedia.org/wiki/HEALPix>`_
+
+
+
 
-.. image:: ./images/healpix.png
-   :scale: 50%
-   :alt:   HEALPix  
 
diff --git a/docs/source/projections/natearth.rst b/docs/source/projections/natearth.rst
index de4460cc..57dd96db 100644
--- a/docs/source/projections/natearth.rst
+++ b/docs/source/projections/natearth.rst
@@ -3,8 +3,45 @@
 ********************************************************************************
 Natural Earth
 ********************************************************************************
++---------------------+--------------------------------------------------------+
+| **Classification**  | Pseudo cylindrical                                     |
++---------------------+--------------------------------------------------------+
+| **Available forms** | Forward and inverse, spherical projection              |
++---------------------+--------------------------------------------------------+
+| **Defined area**    | Global                                                 |
++---------------------+--------------------------------------------------------+
+| **Implemented by**  | Bernhard Jenny                                         |
++---------------------+--------------------------------------------------------+
+| **Options**                                                                  |
++---------------------+--------------------------------------------------------+
+| `No special options for this projection`                                     |
++---------------------+--------------------------------------------------------+
 
 .. image:: ./images/natearth.png
    :scale: 50%
-   :alt:   Natural Earth  
+   :alt:   Natural Earth
 
+
+The Natural Earth projection is intended for making world maps. A distinguishing trait
+is its slightly rounded corners fashioned to emulate the spherical shape of Earth.
+The meridians (except for the central meridian) bend acutely inward as they approach
+the pole lines, giving the projection a hint of three-dimensionality. This bending
+also suggests that the meridians converge at the poles instead of truncating at the
+top and bottom edges. The distortion characteristics of the Natural Earth projection
+compare favorably to other world map projections.
+
+
+Usage
+###############################################################################
+
+The Natural Earth projection has no special options so usage is simple. Here is
+an example of an inverse projection on a sphere with a radius of 7500 m::
+
+    $ echo 3500 -8000 | proj -I +proj=natearth +a=7500
+    37d54'6.091"E  61d23'4.582"S
+
+
+Further reading
+################################################################################
+
+#. `Wikipedia  <https://en.wikipedia.org/wiki/Natural_Earth_projection>`_
diff --git a/docs/source/projections/qsc.rst b/docs/source/projections/qsc.rst
index fb94bb25..1e406056 100644
--- a/docs/source/projections/qsc.rst
+++ b/docs/source/projections/qsc.rst
@@ -4,7 +4,155 @@
 Quadrilateralized Spherical Cube
 ********************************************************************************
 
-.. image:: ./images/qsc.png
++---------------------+----------------------------------------------------------+
+| **Classification**  | Azimuthal                                                |
++---------------------+----------------------------------------------------------+
+| **Available forms** | Forward and inverse, elliptical projection               |
++---------------------+----------------------------------------------------------+
+| **Defined area**    | Global                                                   |
++---------------------+----------------------------------------------------------+
+| **Implemented by**  | Martin Lambers                                           |
++---------------------+----------------------------------------------------------+
+| **Options**                                                                    |
++---------------------+----------------------------------------------------------+
+| `+lat_0`            | Latitude (in degrees) of the view position.              |
++---------------------+----------------------------------------------------------+
+| `+lon_0`            | Longitude (in degrees) of the view position.             |
++---------------------+----------------------------------------------------------+
+
+The purpose of the Quadrilateralized Spherical Cube (QSC) projection is to project
+a sphere surface onto the six sides of a cube:
+
+.. image:: ../../images/qsc_concept.jpg
    :scale: 50%
-   :alt:   Quadrilateralized Spherical Cube  
+   :align: center
+   :alt:   Quadrilateralized Spherical Cube
+
+For this purpose, other alternatives can be used, notably :ref:`gnom` or
+:ref:`healpix`. However, QSC projection has the following favorable properties:
+
+It is an equal-area projection, and at the same time introduces only limited angular
+distortions. It treats all cube sides equally, i.e. it does not use different
+projections for polar areas and equatorial areas. These properties make QSC
+projection a good choice for planetary-scale terrain rendering. Map data can be
+organized in quadtree structures for each cube side. See [LambersKolb2012]_ for an example.
+
+The QSC projection was introduced by [ONeilLaubscher1976]_,
+building on previous work by [ChanONeil1975]_. For clarity: The
+earlier QSC variant described in [ChanONeil1975]_ became known as the COBE QSC since it
+was used by the NASA Cosmic Background Explorer (COBE) project; it is an approximately
+equal-area projection and is not the same as the QSC projection.
+
+See also [CalabrettaGreisen2002]_ Sec. 5.6.2 and 5.6.3 for a description of both and
+some analysis.
+
+In this implementation, the QSC projection projects onto one side of a circumscribed
+cube. The cube side is selected by choosing one of the following six projection centers:
+
++-------------------------+--------------------+
+| ``+lat_0=0 +lon_0=0``   | front cube side    |
++-------------------------+--------------------+
+| ``+lat_0=0 +lon_0=90``  | right cube side    |
++-------------------------+--------------------+
+| ``+lat_0=0 +lon_0=180`` | back cube side     |
++-------------------------+--------------------+
+| ``+lat_0=0 +lon_0=-90`` | left cube side     |
++-------------------------+--------------------+
+| ``+lat_0=90``           | top cube side      |
++-------------------------+--------------------+
+| ``+lat_0=-90``          | bottom cube side   |
++-------------------------+--------------------+
+
+Furthermore, this implementation allows the projection to be applied to ellipsoids.
+A preceding shift to a sphere is performed automatically; see [LambersKolb2012]_ for details.
+
+
+Usage
+###############################################################################
+
+The following example uses QSC projection via GDAL to create the six cube side
+maps from a world map for the WGS84 ellipsoid::
+
+    gdalwarp -t_srs "+wktext +proj=qsc +units=m +ellps=WGS84  +lat_0=0 +lon_0=0"        \
+        -wo SOURCE_EXTRA=100 -wo SAMPLE_GRID=YES -te -6378137 -6378137 6378137 6378137  \
+        worldmap.tiff frontside.tiff
+
+    gdalwarp -t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=0 +lon_0=90"        \
+        -wo SOURCE_EXTRA=100 -wo SAMPLE_GRID=YES -te -6378137 -6378137 6378137 6378137  \
+        worldmap.tiff rightside.tiff
+
+    gdalwarp -t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=0 +lon_0=180"       \
+        -wo SOURCE_EXTRA=100 -wo SAMPLE_GRID=YES -te -6378137 -6378137 6378137 6378137  \
+        worldmap.tiff backside.tiff
+
+    gdalwarp -t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=0 +lon_0=-90"       \
+        -wo SOURCE_EXTRA=100 -wo SAMPLE_GRID=YES -te -6378137 -6378137 6378137 6378137  \
+        worldmap.tiff leftside.tiff
+
+    gdalwarp -t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=90 +lon_0=0"        \
+        -wo SOURCE_EXTRA=100 -wo SAMPLE_GRID=YES -te -6378137 -6378137 6378137 6378137  \
+        worldmap.tiff topside.tiff
+
+    gdalwarp -t_srs "+wktext +proj=qsc +units=m +ellps=WGS84 +lat_0=-90 +lon_0=0"       \
+        -wo SOURCE_EXTRA=100 -wo SAMPLE_GRID=YES -te -6378137 -6378137 6378137 6378137  \
+        worldmap.tiff bottomside.tiff
+
+
+Explanation:
+
+* QSC projection is selected with ``+wktext +proj=qsc``.
+* The WGS84 ellipsoid is specified with ``+ellps=WGS84``.
+* The cube side is selected with ``+lat_0=... +lon_0=...``.
+* The ``-wo`` options are necessary for GDAL to avoid holes in the output maps.
+* The ``-te`` option limits the extends of the output map to the major axis diameter
+  (from -radius to +radius in both x and y direction). These are the dimensions of one side
+  of the circumscribing cube.
+
+
+The resulting images can be layed out in a grid like below.
+
+
+.. |topside| image:: ../../images/qsc_topside.jpg
+   :scale: 50%
+   :align: middle
+   :alt:   Top side
+
+.. |leftside| image:: ../../images/qsc_leftside.jpg
+   :scale: 50%
+   :align: middle
+   :alt:   Left side
+
+.. |frontside| image:: ../../images/qsc_frontside.jpg
+   :scale: 50%
+   :align: middle
+   :alt:   Front side
+
+.. |rightside| image:: ../../images/qsc_rightside.jpg
+   :scale: 50%
+   :align: middle
+   :alt:   Right side
+
+.. |backside| image:: ../../images/qsc_backside.jpg
+   :scale: 50%
+   :align: middle
+   :alt:   Back side
+
+.. |bottomside| image:: ../../images/qsc_bottomside.jpg
+   :scale: 50%
+   :align: middle
+   :alt:   Bottom side
+
+
++------------+--------------+-------------+------------+
+|            | |topside|    |             |            |
++------------+--------------+-------------+------------+
+| |leftside| | |frontside|  | |rightside| | |backside| |
++------------+--------------+-------------+------------+
+|            | |bottomside| |             |            |
++------------+--------------+-------------+------------+
+
+Further reading
+################################################################################
 
+#. `Wikipedia <https://en.wikipedia.org/wiki/Quadrilateralized_spherical_cube>`_
+#. `NASA <https://lambda.gsfc.nasa.gov/product/cobe/skymap_info_new.cfm>`_
diff --git a/docs/source/projections/rhealpix.rst b/docs/source/projections/rhealpix.rst
index c00c5166..1701558e 100644
--- a/docs/source/projections/rhealpix.rst
+++ b/docs/source/projections/rhealpix.rst
@@ -3,8 +3,49 @@
 ********************************************************************************
 rHEALPix
 ********************************************************************************
++---------------------+----------------------------------------------------------+
+| **Classification**  | Mixed                                                    |
++---------------------+----------------------------------------------------------+
+| **Available forms** | Forward and inverse, spherical and elliptical projection |
++---------------------+----------------------------------------------------------+
+| **Defined area**    | Global                                                   |
++---------------------+----------------------------------------------------------+
+| **Implemented by**  | Alex Raichev and Michael Speth                           |
++---------------------+----------------------------------------------------------+
+| **Options**                                                                    |
++---------------------+----------------------------------------------------------+
+| `+north_square`     | Position of the north polar square.                      |
+|                     | Valid inputs are 0--3. Defaults to 0.                    |
++---------------------+----------------------------------------------------------+
+| `+south_square`     | Position of the south polar square.                      |
+|                     | Valid inputs are 0--3. Defaults to 0.                    |
++---------------------+----------------------------------------------------------+
 
-.. image:: ./images/rhealpix.png
-   :scale: 50%
-   :alt:   rHEALPix  
+.. image:: ../../images/rhealpix.png
+   :scale: 75%
+   :alt:   rHEALPix
 
+rHEALPix is a projection based on the HEALPix projection. The implementation of
+rHEALPix uses the HEALPix projection. The rHEALPix combines the peaks of the
+HEALPix into a square. The square's position can be translated and rotated across
+the x-axis which is a noval approach for the rHEALPix projection. The initial
+intention of using rHEALPix in the Spatial Computation Engine Science Collaboration
+Environment (SCENZGrid).
+
+Usage
+###############################################################################
+
+To run a rHEALPix projection on a WGS84 ellipsoidal model, use the following
+command::
+
+    proj +proj=rhealpix -f '%.2f' +ellps=WGS84 +south_square=0 +north_square=2  -E << EOF
+    > 55 12
+    > EOF
+    55 12   6115727.86  1553840.13
+
+
+Further reading
+################################################################################
+
+#. `NASA <http://healpix.jpl.nasa.gov/>`_
+#. `Wikipedia <https://en.wikipedia.org/wiki/HEALPix>`_
diff --git a/docs/source/projections/tpers.rst b/docs/source/projections/tpers.rst
index 7be5bd6c..345a5faa 100644
--- a/docs/source/projections/tpers.rst
+++ b/docs/source/projections/tpers.rst
@@ -3,8 +3,37 @@
 ********************************************************************************
 Tilted perspective
 ********************************************************************************
++---------------------+----------------------------------------------------------+
+| **Classification**  | Azimuthal                                                |
++---------------------+----------------------------------------------------------+
+| **Available forms** | Forward and inverse, spherical projection                |
++---------------------+----------------------------------------------------------+
+| **Defined area**    | Global                                                   |
++---------------------+----------------------------------------------------------+
+| **Implemented by**  | Gerald I. Evenden                                        |
++---------------------+----------------------------------------------------------+
+| **Options**                                                                    |
++---------------------+----------------------------------------------------------+
+| `+h`                | Height (in meters) above the surface. Required.          |
++---------------------+----------------------------------------------------------+
+| `+azi`              | Bearing (in degrees) from due north.                     |
++---------------------+----------------------------------------------------------+
+| `+tilt`             | Angle (in degrees) away from nadir.                      |
++---------------------+----------------------------------------------------------+
+| `+lat_0`            | Latitude (in degrees) of the view position.              |
++---------------------+----------------------------------------------------------+
+| `+lon_0`            | Longitude (in degrees) of the view position.             |
++---------------------+----------------------------------------------------------+
+
 
 .. image:: ./images/tpers.png
    :scale: 50%
-   :alt:   Tilted perspective  
+   :alt:   Tilted perspective
+
 
+Tilted Perspective is similar to :ref:`nsper` (``nsper``) in that it simulates a
+perspective view from a hight. Where ``nsper`` projects onto a plane tangent to
+the surface, Tilted Perspective orients the plane towards the direction of the
+view. Thus, extra parameters azi and tilt are required beyond `nsper``'s ``h``.
+As with ``nsper``, ``lat_0`` & ``lon_0`` are also required
+for satellite position.
diff --git a/docs/source/references.rst b/docs/source/references.rst
index e6ddcc31..26c4da08 100644
--- a/docs/source/references.rst
+++ b/docs/source/references.rst
@@ -18,3 +18,11 @@ References
 .. [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.
+
+.. [CalabrettaGreisen2002]  M. Calabretta and E. Greisen, 2002, "Representations of celestial coordinates in FITS". Astronomy & Astrophysics 395, 3, 1077–1122.
+
+.. [ChanONeil1975]  F. Chan and E.M.O'Neill, 1975, "Feasibility Study of a Quadrilateralized Spherical Cube Earth Data Base". Tech. Rep. EPRF 2-75 (CSC), Environmental Prediction Research Facility.
+
+.. [ONeilLaubscher1976] E.M. O'Neill and R.E. Laubscher, 1976, "Extended Studies of a Quadrilateralized Spherical Cube Earth Data Base". Tech. Rep. NEPRF 3-76 (CSC), Naval Environmental Prediction Research Facility.
+
+.. [LambersKolb2012] M. Lambers and A. Kolb, 2012, "Ellipsoidal Cube Maps for Accurate Rendering of Planetary-Scale Terrain Data", Proc. Pacfic Graphics (Short Papers).