Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Migrating the last doc pages from trac to proj4.org #467

Merged
merged 6 commits into from
Dec 18, 2016
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/images/geos_sweep.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/qsc_backside.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/qsc_bottomside.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/qsc_concept.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/qsc_frontside.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/qsc_leftside.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/qsc_rightside.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/qsc_topside.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
64 changes: 63 additions & 1 deletion docs/source/projections/geos.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.
51 changes: 48 additions & 3 deletions docs/source/projections/healpix.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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

39 changes: 38 additions & 1 deletion docs/source/projections/natearth.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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>`_
152 changes: 150 additions & 2 deletions docs/source/projections/qsc.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

laid, not layed.

Copy link
Member Author

@kbevers kbevers Dec 18, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks. Fixed c64b7b5



.. |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>`_
47 changes: 44 additions & 3 deletions docs/source/projections/rhealpix.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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>`_
Loading