Coordinate spaces used in Met.3D
================================

Met.3D works with three coordinate spaces. Understanding them is important when
implementing actors or processing geometry on the CPU or GPU.


LONLATP
-------

The native data space. Coordinates are ``(longitude, latitude, pressure_hPa)``
where longitude and latitude are in degrees and pressure is in hPa. All
meteorological grid data is addressed in this space. This coordinate is typically
used throughout the C++ code. There are some cases where a transformation into 
world space becomes relevant, for example when working with normals.


World space
-----------

The 3-D space in which OpenGL rendering happens. The horizontal axes map
longitude and latitude directly (one world unit equals one degree). The vertical axis
``worldZ`` is derived from pressure through a logarithmic mapping so that the
rendered scene has higher vertical resolution near the surface and it matches
the logarithmic stratification of pressure in the atmosphere.

The scene view holds the parameters for this mapping:

* ``pbot`` / ``ptop``: pressure extent of the scene (default 1050 hPa / 20 hPa)
* ``zbot`` / ``ztop``: corresponding world Z values (default 0 / 36, where
  ``ztop`` is user-adjustable via the vertical scaling property)
* ``slopePtoZ``: precomputed slope ``(ztop - zbot) / (ln(ptop) - ln(pbot))``

The conversion formulas are::

    worldZ = (ln(p_hPa) - ln(pbot)) * slopePtoZ

    p_hPa  = exp(worldZ / slopePtoZ + ln(pbot))

These are implemented in ``MSceneViewGLWidget`` as ``worldZfromPressure()`` and
``pressureFromWorldZ()``. A convenience method ``pressureToWorldZParameters()``
returns the two shader parameters ``(ln(pbot), slopePtoZ)`` as a ``QVector2D``
for upload to GLSL uniforms.

In GLSL shaders the same conversion is available through
``src/glsl/includes/scene.glsl``, which is included by most shaders via
``#include "includes/scene.glsl"``. 
It provides common scene constants via the scene uniform block, and includes some utility functions. 
Call ``pressureToWorldZ(pressure_hPa)`` to convert a
pressure value to world Z inside a shader.

Clip space
----------

Normalized device coordinates produced by the model-view-projection matrix.
This space is primarily used for 2-D overlays (labels, UI elements) that should
not move with the 3-D scene. The ``MLabel`` and sprite component both accept a
``coordinateSystem`` flag so that anchors can be specified in CLIPSPACE,
WORLDSPACE, or LONLATP.

``MSceneViewGLWidget`` provides helper methods for converting between spaces:

* ``lonLatPToClipSpace(lonlatp)``
* ``clipSpaceToLonLatWorldZ(clipPos)``
* ``clipSpaceToLonLatP(clipPos)``
* ``worldToClipSpace(worldSpace)``