-
Notifications
You must be signed in to change notification settings - Fork 4
Home
Version 0.1.0
This NetCDF-CF extension provides a mechanism to specify a geometry as the spatial representation of the indices of a dimension. The intended use case for this functionality is specifying a geometry for each instance in a timeSeries featureType discrete sampling geometry, which only supports a point representation for the instances on its own. This extension builds on the concept of cell_bounds but does not follow the cell_bounds pattern strictly.
A geometry attribute contains a variable name of what we will refer to as a geometry container variable. This geometry container is similar to the coordinate reference system container variable in that it contains no data, but holds metadata and points to other variables that make up the geometry. The geometry container must hold geometry_type and node_coordinates attributes. Depending on the geometry_type, the geometry container may also need to contain a node_count, part_node_count, and outside_ring attribute. These attributes are described in detail below.
While this proposal is applicable to any variable with a dimension for which a geometry exists for each position, the use case that prompted it requires that geometry be joined to the instance dimension of a Discrete Sampling Geometry timeSeries featureType. In this case, any data variable can be given a geometry attribute that is to be interpreted as the representative geometry for the quantity held in the variable. An example of this is areal average precipitation over a watershed.
Note that several geometry types could be encoded in a single file. For example, a watershed model may have estimates of discharge at catchment outlet points, average stream conditions associated with the channels in catchments, and average precipitation over catchment areas. In this case, the number of modeling units and IDs of the modeling units remain the same, but the geospatial element that should be used to interpret the model data is different for each type of variable.
- Contiguous Ragged Array
As defined in NetCDF-CF 1.7 Chapter 9, the contiguous ragged array uses one long array and an accompanying count variable that indicates the count of indices in each contiguous block of data associated with each instance. The number of instances is the length of the count variable and the sum of the values in the count variable is the length of the long array.
- Geometry
A geometry is usually thought to be a spatial representation of a real-world feature. It can be disjoint and have multiple parts described by multiple points, polylines, or polygons.
- Geometry Container
A variable, identified by a
geometryattribute of a data variable that contains only attributes of the geometry in question.
- Geometry Type
In this CF extension geometry type is limited to point, multipoint, line, multiline, polygon and multipolygon types. Other types exist and may be introduced in a later version of the specification.
- Inside
A polygon node ring that forms a hole in an encompassing polygon ring.
- Multi-Part Geometry
A geometry that corresponds to a single instance or feature but is made up of multiple independent points, polylines or polygons.
- Outside
A polygon node ring that forms the outside edge of a polygon.
- Single-Part Geometry
A geometry that has only one point, polyline, or polygon.
geometry_type
Options: point, multipoint, line, multiline, polygon, multipolygon
Carried by a geometry container variable and indicates the type of geometry present.
node_coordinates
Carried by a geometry container and contains the space delimited names of the x and y (and z) variables that contain geometry node coordinates.
node_count. Carried by a geometry container and contains the name of the variable containing count of nodes per geometry. Note that it may span multiple parts.
part_node_count
Carried by a geometry container and contains the name of the variable containing count of nodes per part. Note that it is not required for point, multipoint, and line geometry types, nor for polygons without holes.
outside_ring
Carried by a geometry container and contains the name of the variable that indicates if polygon parts are holes or not -- not required unless polygons with holes are present.
crs
Carried by a geometry container and contains the name of a coordinate reference system container variable. Similar to grid_mapping but to be used with geometry. Not required if applicable grid_mapping attribute exists on associated data variable.
geometry
Carried by any 1-d variable defined on the same dimension as the variable indicated by the node_count attribute of the geometry container variable. Comparable to the cell_bounds attribute but links to representative geometry for each position in the variable indicated by the node_count attribute of the geometry container variable.
cf_role values geometry_x_node, geometry_y_node, and geometry_z_node
Carried by a variable indicated by a node_coordinates attribute of a geometry container. Indicates that the variable contains the x, y, or z coordinates of the linked geometry container respectively.
Any variable can be given a geometry attribute containing the name of a geometry container variable. The geometry described in the geometry container must have an instance dimension that corresponds to one of the dimensions of the data variable. For point geometries this is the node_coordinates; for multipoint, line, multiline, polygon, and multipolygon types it is the node_count variable. As can be seen in the examples, the geometry attribute that refers to a geometry container variable is associated with a instance_name variable.
The geometry container specifies the geometry_type and node_coordinates for point as well as the node_count for line and polygon types. Since there are no holes in the polygon, the outside_ring attribute is omitted. The variables in the node_coordinates attribute contain the cf_role attributes geometry_x_node and geometry_y_node (and geometry_z_node if z-values are present).
As seen in the multipart examples, all aspects of the single part encoding are present. Each multipart type gets a part_node_count attribute and variable. If a polygons with holes, i.e., interior rings, are present, the exterior polygon rings are treated as separate parts from the interior rings. Note that because multipoints always have a single node per part, the part_node_count is not required for this geometry type.
Polygons with inside rings require the addition of an outside_ring attribute and variable. This variable should contain the value 1 to indicate an outside polygon or 0 to indicate an inside polygon.
The ecosystem of polygon specifications and software implementations of those specifications varies in how polygons are encoded. For example, some specifications require the last node of a polygon to be equivalent to the first as in the triangle described by the four nodes (0 0, 2 0, 1 2, 0 0), whereas others can represent a triangle with only three nodes as in (0 0, 2 0, 1 2). In general, the NetCDF-CF polygon encoding rules follow conventions described in [OGC_SFA]
Nodes within a polygon exterior or interior boundary (also known as a ring) are encoded clockwise or anticlockwise around the polygon. Geospatial software may use the [Shoelace-alrogithm] to compute polygon area. This method requires that the order of nodes within the outer ring is opposite that of any holes. The [OGC_SFA] convention, using anticlockwise order for outer rings and clockwise order for holes is required for compliance with NetCDF-CF.
The [OGC_SFA] convention of closing polygons by making the first and last polygon node coordinates within a ring equivalent is required.
A CRS is strictly required for specification of geometries. The normal NetCDF-CF practice, of attaching a grid_mapping attribute containing the name of a CRS container variable to a data variable, can be used and the grid_mapping CRS should be assumed to apply to the geometry. However, the normal grid_mapping, which typically applies to auxiliary coordinate variables and remains optional for use with geometries, can be overridden by attaching a crs attribute that contains the name of a CRS container variable to the geometry container variable. If a grid_mapping is not present on a data variable linked to geometry, a crs attribute is required.
- [OGC_SFA] OpenGIS Implementation Standard for Geographic information - Simple feature access - Part 1: Common architecture. OGC document 06-103r4 version 1.2.1. 28 May 2011.
- [Shoelace-alrogithm] Shoelace formula. Wikipedia.