Migrated QSC doc page from trac. The text has been restructured to fit better with the rest of the Proj.4 documentation.

9 files changed, 158 insertions, 2 deletions

diff --git a/docs/images/qsc_backside.jpg b/docs/images/qsc_backside.jpg
new file mode 100644
index 00000000..1540abdd
--- /dev/null
+++ b/docs/images/qsc_backside.jpg
diff --git a/docs/images/qsc_bottomside.jpg b/docs/images/qsc_bottomside.jpg
new file mode 100644
index 00000000..6b7ddc18
--- /dev/null
+++ b/docs/images/qsc_bottomside.jpg
diff --git a/docs/images/qsc_concept.jpg b/docs/images/qsc_concept.jpg
new file mode 100644
index 00000000..b92ee631
--- /dev/null
+++ b/docs/images/qsc_concept.jpg
diff --git a/docs/images/qsc_frontside.jpg b/docs/images/qsc_frontside.jpg
new file mode 100644
index 00000000..7c144310
--- /dev/null
+++ b/docs/images/qsc_frontside.jpg
diff --git a/docs/images/qsc_leftside.jpg b/docs/images/qsc_leftside.jpg
new file mode 100644
index 00000000..89842cff
--- /dev/null
+++ b/docs/images/qsc_leftside.jpg
diff --git a/docs/images/qsc_rightside.jpg b/docs/images/qsc_rightside.jpg
new file mode 100644
index 00000000..7b16ea06
--- /dev/null
+++ b/docs/images/qsc_rightside.jpg
diff --git a/docs/images/qsc_topside.jpg b/docs/images/qsc_topside.jpg
new file mode 100644
index 00000000..0570788d
--- /dev/null
+++ b/docs/images/qsc_topside.jpg
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/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).