Move 'Coordinate operations' to top level of docs [skip ci]

1 files changed, 158 insertions, 0 deletions

diff --git a/docs/source/operations/projections/qsc.rst b/docs/source/operations/projections/qsc.rst
new file mode 100644
index 00000000..740901e8
--- /dev/null
+++ b/docs/source/operations/projections/qsc.rst
@@ -0,0 +1,158 @@
+.. _qsc:
+
+********************************************************************************
+Quadrilateralized Spherical Cube
+********************************************************************************
+
++---------------------+----------------------------------------------------------+
+| **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%
+   :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 laid 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>`_