diff --git a/ch07.adoc b/ch07.adoc index f83c8fa8..90a4ce21 100644 --- a/ch07.adoc +++ b/ch07.adoc @@ -18,9 +18,15 @@ We refer to this type of variable as a "boundary variable." __A boundary variable must have one more dimension than its associated coordinate or auxiliary coordinate variable.__ We refer to the additional dimension as the "vertex dimension". The vertex dimension must be the most rapidly varying dimension (the last dimension in CDL order), and its size is the maximum number of cell vertices. + The vertex dimension must be of size two if the associated variable is one-dimensional, and of size greater than two if the associated variable has more than one dimension. For grids constructed from cells that do not all have the same number of sides (e.g., a grid with some rectangular cells and some triangular cells), the vertex dimension must be at least as large as the maximum number of cell vertices. For cells with fewer vertices than the size of vertex dimension, the unneeded elements must appear as the last elements in the vertex dimension and must be assigned the **`_FillValue`**. +CF can currently describe boundaries for cells which have one or two spatial dimensions, and does not provide conventions to describe the boundaries of cells with three spatial dimensions. +Please refer to <> for development of such conventions. + +[[boundaries-and-formula-terms, Section 7.1.1, "Boundaries and Formula Terms"]] +==== Boundaries and Formula Terms A boundary variable inherits the values of some attributes from its parent coordinate variable. If a coordinate variable has any of the attributes marked "BI" (for "inherit") in the "Use" column of <>, they are assumed to apply to its bounds variable as well. @@ -77,49 +83,13 @@ float eta(eta) ; Note that the boundary variable for a set of N contiguous intervals is an array of shape (N,2). Although in this case there will be a duplication of the boundary coordinates between adjacent intervals, this representation has the advantage that it is general enough to handle, without modification, non-contiguous intervals, as well as intervals on an axis using the unlimited dimension. -Applications that process cell boundary data often times need to determine whether or not adjacent cells share an edge. -In order to facilitate this type of processing the following restrictions are placed on the data in boundary variables. +[[bounds-one-d, Section 7.1.2, "Bounds for one-dimensional coordinate variables"]] +==== Bounds for one-dimensional coordinate variables -Bounds for 1-D coordinate variables:: For a coordinate variable such as **`lat(lat)`** with associated boundary variable **`latbnd(x,2)`**, the interval endpoints must be ordered consistently with the associated coordinate, e.g., for an increasing coordinate, **`lat(1)`** > **`lat(0)`** implies **`latbnd(i,1)`** >= **`latbnd(i,0)`** for all **`i`** (<>). -+ -If adjacent intervals are contiguous, the shared endpoint must be represented indentically in each instance where it occurs in the boundary variable. -For example, if the intervals that contain grid points **`lat(i)`** and **`lat(i+1)`** are contiguous, then **`latbnd(i+1,0)`** = **`latbnd(i,1)`**. -+ -[[img-bnd_1d_coords, figure 1]] -[caption="Figure {doc-part}.{counter:figure}. ", reftext=Figure {doc-part}.{figure}] -[.text-center] -.Order of **`lonbnd(i,0)`** and **`lonbnd(i,1)`** as well as of **`latbnd(i,0)`** and **`latbnd(i,1)`** in the case of one-dimensional horizontal coordinate axes. Tuples **`(lon(i),lat(j))`** represent grid cell centers. The four grid cell vertices are given by **`(lonbnd(i,0),latbnd(j,0))`**, **`(lonbnd(i,1),latbnd(j,0))`**, **`(lonbnd(i,1),latbnd(j,1))`** and **`(lonbnd(i,0),latbnd(j,1))`**. -image::images/order_horizontal_bounds__1D_coord_variables.png[,50%,pdfwidth=50vw,align="center"] +For a coordinate variable such as **`lat(lat)`** with associated boundary variable **`latbnd(x,2)`**, the interval endpoints must be ordered consistently with the associated coordinate, e.g., for an increasing coordinate, **`lat(1)`** > **`lat(0)`** implies **`latbnd(i,1)`** >= **`latbnd(i,0)`** for all **`i`** (<>). -Bounds for 2-D coordinate variables with 4-sided cells:: In the case where the horizontal grid is described by two-dimensional auxiliary coordinate variables in latitude **`lat(n,m)`** and longitude **`lon(n,m)`**, and the associated cells are four-sided, then the boundary variables are given in the form **`latbnd(n,m,4)`** and **`lonbnd(n,m,4)`**, where the trailing index runs over the four vertices of the cells. -Let us call the side of cell **`(j,i)`** facing cell **`(j,i-1)`** the "**`i-1`**" side, the side facing cell **`(j,i+1)`** the "**`i+1`**" side, and similarly for "**`j-1`**" and "**`j+1`**". -Then we can refer to the vertex formed by sides **`i-1`** and **`j-1`** as **`(j-1,i-1)`**. -With this notation, the four vertices are indexed as follows: **`0=(j-1,i-1)`**, **`1=(j-1,i+1)`**, **`2=(j+1,i+1)`**, **`3=(j+1,i-1)`**. -+ -[[img-bnd_2d_coords, figure 2]] -[caption="Figure {doc-part}.{counter:figure}. ", reftext=Figure {doc-part}.{figure}] -[.text-center] -.Order of **`lonbnd(j,i,0)`** to **`lonbnd(j,i,3)`** and of **`latbnd(j,i,0)`** and **`latbnd(j,i,3)`** in the case of two-dimensional horizontal coordinate axes. Tuples **`(lon(j,i),lat(j,i))`** represent grid cell centers and tuples **`(lonbnd(j,i,n),latbnd(j,i,n))`** represent the grid cell vertices. -image::images/order_horizontal_bounds__2D_coord_variables.png[,50%,pdfwidth=50vw,align="center"] -+ -If i-j-upward is a right-handed coordinate system (like lon-lat-upward), this ordering means the vertices will be traversed anticlockwise on the lon-lat surface seen from above (<>). -If i-j-upward is left-handed, they will be traversed clockwise on the lon-lat surface. -+ -The bounds can be used to decide whether cells are contiguous via the following relationships. -In these equations the variable **`bnd`** is used generically to represent either the latitude or longitude boundary variable. - ----- -For 0 < j < n and 0 < i < m, - If cells (j,i) and (j,i+1) are contiguous, then - bnd(j,i,1)=bnd(j,i+1,0) - bnd(j,i,2)=bnd(j,i+1,3) - If cells (j,i) and (j+1,i) are contiguous, then - bnd(j,i,3)=bnd(j+1,i,0) and bnd(j,i,2)=bnd(j+1,i,1) ----- - -Bounds for multi-dimensional coordinate variables with p-sided cells:: In all other cases, the bounds should be dimensioned **`(...,n,p)`**, where **`(...,n)`** are the dimensions of the auxiliary coordinate variables, and **`p`** the number of vertices of the cells. -The vertices must be traversed anticlockwise in the lon-lat plane as viewed from above. -The starting vertex is not specified. +If adjacent intervals are contiguous, the shared endpoint must be represented identically in each instance where it occurs in the boundary variable. +For example, if the intervals that contain grid points **`lat(i)`** and **`lat(i+1)`** are contiguous, then **`latbnd(i+1,0)`** = **`latbnd(i,1)`**. [[cells-on-a-latitude-axis-ex]] [caption="Example 7.2. "] @@ -140,12 +110,24 @@ The boundary variable `lat_bnds` associates a latitude gridpoint `i` with the in The gridpoint location, `lat(i)`, should be contained within this interval. ==== -For rectangular grids, two-dimensional cells can be expressed as Cartesian products of one-dimensional cells of the type in the preceding example. -However for non-rectangular grids a "rectangular" cell will in general require specifying all four vertices for each cell. +[[img-bnd_1d_coords, figure 1]] +[caption="Figure {doc-part}.{counter:figure}. ", reftext=Figure {doc-part}.{figure}] +[.text-center] +.Order of **`lonbnd(i,0)`** and **`lonbnd(i,1)`** as well as of **`latbnd(i,0)`** and **`latbnd(i,1)`** in the case of one-dimensional horizontal coordinate axes. Tuples **`(lon(i),lat(j))`** represent grid cell centers. The four grid cell vertices are given by **`(lonbnd(i,0),latbnd(j,0))`**, **`(lonbnd(i,1),latbnd(j,0))`**, **`(lonbnd(i,1),latbnd(j,1))`** and **`(lonbnd(i,0),latbnd(j,1))`**. +image::images/order_horizontal_bounds__1D_coord_variables.png[,50%,pdfwidth=50vw,align="center"] + + +[[bounds-lat-lon, Section 7.1.3, "Bounds for horizontal coordinate variables with four-sided cells"]] +==== Bounds for horizontal coordinate variables with four-sided cells + +There is a common case of a rectangular horizontal grid, with four-sided cells, whose two axes are not latitude and longitude (e.g. it uses a map projection from <> or a curvilinear grid, such as the tripolar ocean grid). +In that case, two-dimensional auxiliary coordinate variables in latitude **`lat(n,m)`** and longitude **`lon(n,m)`** may be provided as well. +Since the sides of the cells do not generally have constant latitude or longitude, all four vertices must be specified individually. +Therefore the boundary variables for the two-dimensional auxiliary coordinate variables are given in the form **`latbnd(n,m,4)`** and **`lonbnd(n,m,4)`**, where the trailing index runs over the four vertices of the cells. [[cells-in-a-non-rectangular-grid-ex]] [caption="Example 7.3. "] -.Cells in a non-rectangular grid +.Cells in a non-latitude-longitude horizontal grid ==== ---- dimensions: @@ -168,6 +150,43 @@ The boundary variables `lat_bnds` and `lon_bnds` associate a gridpoint `(j,i)` w The gridpoint location, `(lat(j,i),lon(j,i))`, should be contained within this region. ==== +Let us call the side of cell **`(j,i)`** facing cell **`(j,i-1)`** the "**`i-1`**" side, the side facing cell **`(j,i+1)`** the "**`i+1`**" side, and similarly for "**`j-1`**" and "**`j+1`**". +Then we can refer to the vertex formed by sides **`i-1`** and **`j-1`** as **`(j-1,i-1)`**. +With this notation, the four vertices are indexed as follows: **`0=(j-1,i-1)`**, **`1=(j-1,i+1)`**, **`2=(j+1,i+1)`**, **`3=(j+1,i-1)`**. +If i-j-upward is a right-handed coordinate system (like lon-lat-upward), this ordering means the vertices will be traversed anticlockwise on the lon-lat surface seen from above (<>). +If i-j-upward is left-handed, they will be traversed clockwise on the lon-lat surface. + +[[img-bnd_2d_coords, figure 2]] +[caption="Figure {doc-part}.{counter:figure}. ", reftext=Figure {doc-part}.{figure}] +[.text-center] +.Order of **`lonbnd(j,i,0)`** to **`lonbnd(j,i,3)`** and of **`latbnd(j,i,0)`** and **`latbnd(j,i,3)`** in the case of two-dimensional horizontal coordinate axes. Tuples **`(lon(j,i),lat(j,i))`** represent grid cell centers and tuples **`(lonbnd(j,i,n),latbnd(j,i,n))`** represent the grid cell vertices. +image::images/order_horizontal_bounds__2D_coord_variables.png[,50%,pdfwidth=50vw,align="center"] + +The bounds can be used to decide whether cells are contiguous via the following relationships. +In these equations the variable **`bnd`** is used generically to represent either the latitude or longitude boundary variable. + +---- +For 0 < j < n and 0 < i < m, + If cells (j,i) and (j,i+1) are contiguous, then + bnd(j,i,1)=bnd(j,i+1,0) + bnd(j,i,2)=bnd(j,i+1,3) + If cells (j,i) and (j+1,i) are contiguous, then + bnd(j,i,3)=bnd(j+1,i,0) and bnd(j,i,2)=bnd(j+1,i,1) +---- + + +[[bounds-two-d, Section 7.1.4, "Bounds for coordinate variables with p-sided cells in two spatial dimensions"]] +==== Bounds for coordinate variables with p-sided cells in two spatial dimensions + +The general case of a grid composed of polygonal cells in two spatial dimensions with **`p`** sides and vertices, or a mixture of polygons where **`p`** is the maximum number of sides and vertices, the grid could have one, two or more dimensions, depending on how it is organised logically (e.g. as a 1-D list or a 2-D rectangular arrangement). +The boundary variables for the auxiliary coordinate variables are dimensioned **`(...,m,p)`**, giving coordinates for the **`p`** vertices of each cell, where **`(...,m)`** are the dimensions of the auxiliary coordinate variables. + If the cells are in a horizontal plane, the vertices must be traversed anticlockwise in the lon-lat plane as viewed from above. +The starting vertex is not specified. + +The case of a 2-D horizontal coordinate variables with 4-sided cells (<>) is a particular case, with **`p=4`** for boundary variables dimensioned **`(n,m,p)**`, where **`n`** and **`m`** are horizontal dimensions. +See also <> for conventions describing horizontal cells with more complicated geometry and topology. + + [[cell-measures, Section 7.2, "Cell Measures"]] === Cell Measures diff --git a/history.adoc b/history.adoc index 8ef18ae7..dece5f15 100644 --- a/history.adoc +++ b/history.adoc @@ -7,6 +7,7 @@ === Working version (most recent first) +* {issues}527[Issue #527]: Clarify the conventions for boundary variables, especially for auxiliary coordinate variables of more than one dimension. * {issues}403[Issue #403]: Metadata to encode quantization properties * {issues}530{Issue #530]: Define "the most rapidly varying dimension", and use this phrase consistently with the clarification "(the last dimension in CDL order)". * {issues}163[Issue #163]: Provide a convention for boundary variables for grids whose cells do not all have the same number of sides.