# `cso_mapping` module

Tools for mapping between footprints and grid cells.

## Methods

cso_mapping.LonLatDistance(lon1, lat1, lon2, lat2)

  Calculates the distance between two points given their (lat, lon) coordinates.

  Arguments (scalar or arrays of same length):

  - `lon1`, `lat1` : first location in degrees east/north;

  - `lon2`, `lat2` : second location in degrees east/north.

cso_mapping.TrianglesArea(xx, yy)

  Return areas of triangles defined by:

  - `xx`, `yy` : corner locations as `(n,3)` arrays

  Uses Heron’s formula to compute area of triangle.

cso_mapping.LonLatTrianglesArea(xx, yy)

  > Return areas in m2 of triangles defined by:

  > - `xx`, `yy` : corner locations in degrees east/north as `(n,3)` arrays

  > Using the radius \(R\) of Earth (m) the area is:

  > \[A ~=~ R^2 \int\limits_{x,y} \cos(y)\ dx\ dy\]

  Approximate this by first computing the area in degrees2 and use the average latitude:

  > \[A ~=~ R^2 \int\limits_{x,y} dx\ dy\ \cos(y_{aver})\]

cso_mapping.LonLatRectanglesArea(xx, yy)

  Return areas in m2 of rectangles defined by:

  - `xx`, `yy` : corner locations in degrees east/north as `(n,4)` or `(m,n,4)` arrays

  Approximate area of rectangle in `(lon,lat)` in degrees using 2 triangles:

      3 o---o 2
        | / |
      0 o---o 1

  This routine is used to ensure that area’s of footprints and grid cells are approximated in the same way.

cso_mapping.LonLatPolygonCentroids(xx, yy, maxlevel=5, _level=0, indent='')

  Let \(N\) polygons be defined with \(n_c\) corners in the arguments: This method returns arrays with \((P,N)\) locations of points distributed within the polygons, as well as the fraction of the area corresponding to each point.

  Arguments:

  - `xx`, `yy` : arrays of shape \((N,n_c)\) with corner locations in degrees east/north

  Return values:

  - `xxp`, `yyp` : arrays of shape \((P,N)\) with the coordinates of the points

  - `wwp` : arrays of shape \((P,N)\) with area in m2 assigned to each point

  The polygon is recursively devided in triangles, the points are their centroids. First the centroid of the polygon is determined, and the first set of triangles is formed from with the sides of the polygon as base and the centroid as top:

      o---o
      |\ /|
      | * |
      |/ \|
      o---o

  Each triangle is devided into 2 new triangles with the middle of the longest side as their top and the two shortest sides as their base:

            2
            o
        0 / | \ 2
        /   |           o-----*-----o
      0    1    1

  Recursion is repeated up to `maxlevels` deep; with “maxlevels==0” a single point is returned. For a 4-sided polygon the number of points is:

  - 1 for `maxlevels=0`;

  - 4 for `maxlevels=1`;

  - 8 for `maxlevels=2`;

  - 16 for `maxlevels=3`;

  - 32 for `maxlevels=4`;

  - 64 for `maxlevels=5` (default).