Geometries Contribution (and github experimentation)

appe.adoc

@@ -54,5 +54,4 @@ respect to the specified dimension.
 | `variance` | __u^2^__ | Variance
 |===============
 
-
 

ch07.adoc

@@ -544,3 +544,168 @@ data:  // time coordinates translated to date/time format
                      "2000-8-1 6:00:00", "2000-9-1 6:00:00" ;
 ----
 ====
+
+[[geometries, Section 7.5, "Geometries"]]
+=== Geometries
+
+For many geospatial applications, data values are associated with a geometry, which is a spatial representation of a real-world feature, for instance a time-series of areal average precipitation over a watershed. 
+Polygonal cells with an arbitrary number of vertices can be described using <<cell-boundaries>>, but in that case every cell must have the same number of vertices and must be single polygon rings. 
+In contrast, each geometry may have a different number of nodes, the geometries may be lines (as alternatives to points and polygons), and they may be __multipart__ i.e include several disjoint parts. 
+While line and point geometries don't describe an interval along a dimension as the traditional cell bounds described above do, they do describe the extent of a geometry or real-world feature so are included in this section. 
+The approach described here specifies how to encode such geometries following the pattern in **9.3.3 Contiguous ragged array representation** and attach them to variables in a way that is consistent with the cell bounds approach.
+
+All geometries are made up of one or more nodes. 
+The geometry type specifies the set of topological assumptions to be applied to relate the nodes. 
+For example, __multipoint__ and __line__ geometries are nearly the same except nodes are interpreted as being connected for lines. 
+Lines and polygons are also nearly the same except that it should be assumed that the first and last node are connected. 
+Note that CF does not require the first and last node to be identical but allows them to be coincident if desired. 
+Polygons that have holes, such as waterbodies in a land unit, are encoded as a collection of polygon ring parts, each identified as __exterior__ or __interior__ polygons. 
+Multipart geometries, such as multiple lines representing the same river or multiple islands representing the same jurisdiction, are encoded as collections of un-connected points, lines, or polygons that are logically grouped into a single geometry.
+
+Any data variable can be given a `geometry` attribute that indicates the geometry for the quantity held in the variable. 
+One of the dimensions of the data variable must be the number of geometries to which the data applies. 
+As shown in Example 7.14, if the data variable has a discrete sampling geometry, the number of geometries is the length of the instance dimension (Section 9.2).
+
+[["timeseries-with-geometry"]]
+[caption="Example 7.14. "]
+.Timeseries with geometry.
+====
+----
+dimensions:
+  instance = 2 ;
+  node = 5 ;
+  time = 4 ;
+variables:
+  int time(time) ;
+    time:units = "days since 2000-01-01" ;
+  double lat(instance) ;
+    lat:units = "degrees_north" ;
+    lat:standard_name = "latitude" ;
+    lat:geometry = "geometry_container" ;
+  double lon(instance) ;
+    lon:units = "degrees_east" ;
+    lon:standard_name = "longitude" ;
+    lon:geometry = "geometry_container" ;
+  int datum ;
+    datum:grid_mapping_name = "latitude_longitude" ;
+    datum:longitude_of_prime_meridian = 0.0 ;
+    datum:semi_major_axis = 6378137.0 ;
+    datum:inverse_flattening = 298.257223563 ;
+  int geometry_container ;
+    geometry_container:geometry_type = "line" ;
+    geometry_container:node_count = "node_count" ;
+    geometry_container:node_coordinates = "x y" ;
+  int node_count(instance) ;
+  double x(node) ;
+    x:units = "degrees_east" ;
+    x:standard_name = "longitude" ;
+    x:cf_role = "geometry_x_node" ;
+  double y(node) ;
+    y:units = "degrees_north" ;
+    y:standard_name = "latitude" ;
+    y:cf_role = "geometry_y_node" ;
+  double someData(instance, time) ;
+    someData:coordinates = "time lat lon" ;
+    someData:grid_mapping = "datum" ;
+    someData:geometry = "geometry_container" ;
+// global attributes:
+  :Conventions = "CF-1.8" ;
+  :featureType = "timeSeries" ;
+data:
+  time = 1, 2, 3, 4 ;
+  lat = 30, 50 ;
+  lon = 10, 60 ;
+  someData =
+    1, 2, 3, 4,
+    1, 2, 3, 4 ;
+  node_count = 3, 2 ;
+  x = 30, 10, 40, 50, 50 ;
+  y = 10, 30, 40, 60, 50 ;
+----
+The time series variable, someData, is associated with line geometries via the geometry attribute. The first line geometry is comprised of three nodes, while the second has two nodes. Client applications unaware of CF geometries can fall back to the lat and lon variables to locate feature instances in space. In this example, lat and lon coordinates are identical to the first node in each line geometry, though any representative point could be used.
+====
+
+
+A __geometry container__ variable acts as a container for attributes that describe a set of geometries. 
+The **`geometry`** attribute of the data variable contains the name of a geometry container variable. 
+The geometry container variable must hold **`geometry_type`** and **`node_coordinates`** attributes. 
+A **`grid_mapping`** attribute, which would usually by carried by a data variable, can be carried by the geometry container variable.
+
+The **`geometry_type`** attribute indicates the type of geometry present. 
+Its allowable values are: __point__, __multipoint__, __line__, __multiline__, __polygon__, __multipolygon__. 
+The **`node_coordinates`** attribute contains the blank delimited names of the variables that contain geometry node coordinates (one variable for each spatial dimension). 
+
+
+The geometry node coordinate variables must each have a **`cf_role`** attribute whose allowable values are __geometry_x_node__, __geometry_y_node__, and __geometry_z_node__. 
+The geometry node coordinate variables must all have the same single dimension, which is the total number of nodes in all the geometries. 
+The nodes must be stored consecutively for each geometry and in the order of the geometries, and within each multipart geometry the nodes must be stored consecutively for each part and in the order of the parts. 
+Polygon exterior rings must be put in anticlockwise order (viewed from above) and polygon interior rings in clockwise order. 
+They are put in opposite orders to facilitate calculation of area and consistency with the typical implementation pattern. 
+
+
+For all geometry types except __point__, in which each geometry contains a single node, when more than one geometry is present, the geometry container variable must have a **`node_count`** attribute that contains the name of a variable indicating the count of nodes per geometry. 
+The node count is the total nodes in all the parts. 
+
+
+For __multiline__, __multipolygon__, and __polygons__ with holes, the geometry container variable must have a **`part_node_count`** attribute indicates a variable of the count of nodes per geometry part. 
+Note that because multipoint geometries always have a single node per part, the **`part_node_count`** is not required. 
+The single dimension of the part node count variable should equal the total number of parts in all the geometries.
+
+For __polygon__ and __multipolygon__ geometries with holes, the geometry container variable must have an **`interior_ring`** attribute that contains the name of a variable that indicates if the polygon parts are interior rings (i.e., holes) or not. 
+This interior ring variable should contain the value 0 to indicate an exterior ring polygon and 1 to indicate an interior ring polygon. 
+The single dimension of the interior ring variable should be the same dimension as that of the part node count variable.
+
+[[complete-multipolygon-example]]
+[caption="Example 7.15. "]
+.A multipolygon with holes
+====
+This example demonstrates the use of all potential attributes and variables for encoding geometries.
+----
+dimensions:
+  node = 12 ;
+  feature = 2 ;
+  part = 4 ;
+variables:
+  double x(node) ;
+    x:units = "degrees_east" ;
+    x:standard_name = "longitude" ;
+    x:cf_role = "geometry_x_node" ;
+  double y(node) ;
+    y:units = "degrees_north" ;
+    y:standard_name = "latitude" ;
+    y:cf_role = "geometry_y_node" ;
+  double lat(feature) ;
+    lat:units = "degrees_north" ;
+    lat:standard_name = "latitude" ;
+    lat:geometry = "geometry_container" ;
+  double lon(feature) ;
+    lon:units = "degrees_east" ;
+    lon:standard_name = "longitude" ;
+    lon:geometry = "geometry_container" ;
+  float geometry_container ;
+    geometry_container:geometry_type = "multipolygon" ;
+    geometry_container:node_count = "node_count" ;
+    geometry_container:node_coordinates = "x y" ;
+    geometry_container:grid_mapping = "crs" ;
+    geometry_container:coordinates = "lat lon"
+    geometry_container:part_node_count = "part_node_count" ;
+    geometry_container:interior_ring = "interior_ring" ;
+  int node_count(feature) ;
+  int part_node_count(part) ;
+  int interior_ring(part) ;
+  float crs ;
+    crs:grid_mapping_name = "latitude_longitude" ;
+    crs:semi_major_axis = 6378137. ;
+    crs:inverse_flattening = 298.257223563 ;
+    crs:longitude_of_prime_meridian = 0. ;
+// global attributes:
+  :Conventions = "CF-1.8" ;
+data:
+ x = 20, 10, 0, 5, 10, 15, 20, 10, 0, 50, 40, 30 ;
+ y = 0, 15, 0, 5, 10, 5, 20, 35, 20, 0, 15, 0 ;
+ node_count = 9, 3 ;
+ part_node_count = 3, 3, 3, 3 ;
+ interior_ring = 0, 1, 0, 0 ;
+ crs = 0. ;
+----
+====

history.adoc

@@ -157,5 +157,9 @@ Replaced first para in Section 9.6. "Missing Data". Added verbiage to Section 2.
 .06 April 2017
 . Ticket #70, Connecting coordinates to Grid Mapping variables: revisions in Section 5.6 and Examples 5.10 and 5.12
 
+.07 April 2017
+. New Simple Geometry section 7.5 and content in appendix E.
+
 .25 April 2017
 . Ticket #100, Clarifications to the preamble of sections 4 and 5.
+