==================================
:mod:`eqarea` -- The eqarea module
==================================

.. toctree::
   :maxdepth: 1



.. module:: eqarea

Routines for computing an equal area grid.

Specifically, Sergej's equal area 8000 element grid of the Earth (or any sphere
like object).  See GISTEMP code, subroutine GRIDEA

Global Variables
----------------

  .. attribute:: band_altitude()
  
     Array of altitudes from the equatorial plane.
     
     Altitude refers to the distance from the equatorial plane.  The "North" pole
     being at altitude 1, the "South" pole being at altitude -1.
     
     band_altitude[n] gives the northern altitude of band n, n from 0 to 3.
     band_altitude[n+1] gives the southern altitude of band n.
     
     .. Note::
     
        These are the sines of the latitude.
     
  
  .. attribute:: band_boxes()
  
     Number of horizontal boxes in each band.
     
     To ensure equal area these should be proportional to the thickness of each
     band (Archimedes' Hat Box Theorem).
     
  
Functions
---------

  .. function:: centre (box)
  
     Return the (latitude,longitude) pair for the centre of box/subbox.
     
     This the the "equal area" centre in the sense that the area to the
     north will equal the area to the south, and the same for east/west.
     box is specified as a 4-tuple (as returned as an element of grid()
     for example).
     
     
     **Return Value**
     
       A tuple of ``(latitude,longitude)``.
       

  .. function:: grid ()
  
     Generator: Yields 80 boxes comprising equal area divisions of a sphere.
     
     Each box is yielded as a 4-tuple of its boundaries: ``(southern, northern,
     western, eastern)``.
     
     Co-ordinates are given as (fractional) degrees of latitude (for northern
     and southern borders) and longitude (for western and eastern borders).
     

  .. function:: grid8k ()
  
     As :func:`~eqarea.gridsub`, but returns a single generator for all 8000 subboxes.
     
     Not used by real code, but it useful for debugging.
     

  .. function:: gridJSON ()
  
     As gridR3 but in JSON (http://www.json.org/) format.
     
     
     **Return Value**
     
       A string matching a JSON array production.
       

  .. function:: gridR3 ()
  
     As grid but each box is described in a right-hand 3-dimensional euclidean
     co-ordinate system.
     
     The sphere is centred at the origin ``(0,0,0)``. The equator lies on the
     plane containing the x- and y-axes (z=0).  The north pole has co-ordinate
     ``(0,0,1)``; the intersection of the eqautor and the prime meridian (0
     longitude at equator) is ``(1,0,0)``.  That should be enough for you to
     deduce that longitude 90 on the equator is at ``(0,1,0)``.
     
     Each box is a quadrilateral described by its corners; from the viewpoint of a
     distant observer viewing the side of the sphere with the box on, the corners
     are in a counter-clockwise order (so this consistent ordering can be used for
     face culling if desired).
     
     Each box is yielde as a 4-tuple of 3-tuples.  Note polar boxes have
     co-incident corners.
     

  .. function:: gridsub ()
  
     Generator: Yields 80 boxes, each divided into subboxes.
     
     Each box containts, in a general sense, 100 subboxes.  The 80 boxes are
     those obtained from the generator :func:`~eqarea.grid`.  A box is yielded as a tuple pair
     ``(bound, subgen)``, where ``bound`` is the 4-tuple as returned by :func:`~eqarea.grid`
     (boundaries in degrees for S N W E edges), and ``subgen`` is a generator for
     the 100 subboxes.
     
     The order of the boxes is the same as grid().
     
     The subboxes are returned as 4-tuples using the same
     latitude/longitude box representation as for :func:`~eqarea.grid`.
     
     Note that Sheffield, +53.40-001.50, is in subbox 759:
     
      >>> subbox=list(list(gridsub())[7][1])[59]
      >>> subbox[0] < 53.4 < subbox[1]
      True
      >>> subbox[2] < -1.5 < subbox[3]
      True
     
     and Vostok, -78.40+106.90, is in subbox 7921:
     
      >>> subbox=list(list(gridsub())[79][1])[21]
      >>> subbox[0] < -78.4 < subbox[1]
      True
      >>> subbox[2] < 106.9 < subbox[3]
      True
     

  .. function:: lerp (x, y, p)
  
     Return a value interpolated between x and y by the fraction p.
     
     
     **Return Value**
     
       When *p* == 0 *x* will be returned, when *p* == 1 *y* will be returned.  Note
       that *p* is not restricted to being between 0 and 1.
       

  .. function:: northern40 ()
  
     Generator: Yields each of the 40 northern hemisphere boxes.
     
     Each box is yielded as a tuple of ``(southern, northern, western,
     eastern)``.
     
     See :func:`~eqarea.grid` for more details about what a box is.
     

  .. function:: southern40 ()
  
     As :func:`~eqarea.northern40` but for southern hemisphere.