diff --git a/appa.adoc b/appa.adoc index 0cdc5326..6495730a 100644 --- a/appa.adoc +++ b/appa.adoc @@ -115,6 +115,12 @@ formula in the definition. | link:$$http://www.unidata.ucar.edu/software/netcdf/docs/attribute_conventions.html$$[NUG Appendix A, "Attribute Conventions"] | Name of the conventions followed by the dataset. +| **`coordinate_interpolation`** +| S +| D, Do +| <> +| Indicates that coordinates have been compressed by sampling and identifies the tie point coordinate variables and their associated interpolation variables. + | **`coordinates`** | S | D, M, Do diff --git a/appj.adoc b/appj.adoc new file mode 100644 index 00000000..4e379e13 --- /dev/null +++ b/appj.adoc @@ -0,0 +1,420 @@ +[[appendix-coordinate-subsampling, Appendix J, Coordinate Interpolation Methods]] +[appendix] +== Coordinate Interpolation Methods + +The general description of the compression by coordinate subsampling is given in section <>. This appendix provides details on the available methods for compression by coordinate subsampling. + +The definitions and guidance given here allow an application to compress an existing data set using coordinate subsampling, while letting the creator of the compressed dataset control the accuracy of the reconstituted coordinates through the degree of subsampling, the choice of interpolation method and by setting the computational precision. + +Furthermore, the definitions given here allow an application to uncompress coordinate and auxiliary coordinate variables that have been compressed using coordinate subsampling. The key element of this process is the reconstitution of the full resolution coordinates in the domain of the data by interpolation between the subsampled coordinates, the tie points, stored in the compressed dataset. + + +The appendix is organised in a sections on <>, <>, <> and finally two sections with step procedures <> and <>. + +[[common-definitions-and-notation, Section J.1, "Common Definitions and Notation"]] +=== Common Definitions and Notation + +The coordinate interpolation methods are named to indicate the number of dimensions they interpolate as well as the type of interpolation provided. For example, the interpolation method named `linear` provides linear interpolation in one dimension and the method named `bi_linear` provides linear interpolation in two dimensions. Equivalently, the interpolation method named `quadratic` provides quadratic interpolation in one dimension and the interpolation method named `bi_quadratic` provides quadratic interpolation in two dimensions. + +When an interpolation method is referred to as linear or quadratic, it means that the method is linear or quadratic in the indices of the interpolated dimensions. + +For convenience, an interpolation argument `s` is introduced, calculated as a function of the index in the target domain of the coordinate value to be reconstituted. In the case of one-dimensional interpolation the variable is computed as + +`s = s(ia, ib, i) = (i - ia)/(ib - ia)` + +where `ia` and `ib` are the indices in the target domain of the tie points `A` and `B` and `i` is the index in the target domain of the coordinate value to be reconstituted. + +Note that the value of `s` varies from `0.0` at the tie point `A` to `1.0` at tie point `B`. For example, if `ia = 100` and `ib = 110` and the index in the target domain of the coordinate value to be reconstituted is `i = 105`, then `s = (105 - 100)/(110 - 100) = 0.5`. + +In the case of two-dimensional interpolation, the interpolation arguments are similarly computed as + +`s1 = s(ia1, ib1, i1) = (i1 - ia1)/(ib1 - ia1)` + +`s2 = s(ia2, ic2, i2) = (i2 - ia2)/(ic2 - ia2)` + +where `ia1` and `ib1` are the first dimension indices in the target domain of the tie points `A` and `B` respectively, `ia2` and `ic2` are the second dimension indices in the target domain of the tie points `A` and `C` respectively and the indices `i1` and `i2` are the first and second dimension indices respectively in the target domain of the coordinate value to be reconstituted. + +The target domain is segmented into smaller interpolation subareas as described in <>. + +For one-dimensional interpolation, an interpolation subarea is defined by two tie points, one at each end of the interpolation subarea. However, the tie points may be inside or outside the interpolation subareas as shown in <>. When interpolation methods are applied for a given interpolation subarea, it must be ensured that reconstituted coordinate points are only generated inside the interpolation subarea being processed, even if some of the tie point coordinates lie outside of that interpolation subarea. See also description in <>. + +[[interpolation_subareas_1d, Figure 1]] +[.text-center] +.One-dimensional interpolation subareas, one including and one excluding tie point A. +image::images/ci_1d_interpolation_subarea.svg[,100%,pdfwidth=50vw,align="center"] + +For two-dimensional interpolation, an interpolation subarea is defined by four tie points, one at each corner of a rectangular area aligned with the domain axes, see <>. + +[[interpolation_subarea_2d, Figure 2]] +[.text-center] +.Two-dimensional interpolation subarea. +image::images/ci_2d_interpolation_subarea.svg[,60%,pdfwidth=50vw,align="center"] + +For the reconstitution of the uncompressed coordinate and auxiliary coordinate variables the interpolation method can be applied independently for each interpolation subarea, making it possible to parallelize the computational process. + +The following notation is used: + +A variable staring with `v` denotes a vector and `v.x` , `v.y` and `v.z` refer to the three coordinates of that vector. + +A variable staring with `ll` denotes a latitude-longitude coordinate pair and `ll.lat` and `ll.lon` refer to the latitude and longitude coordinates. + +For one-dimensional interpolation, `i` is an index in the interpolated dimension, `tpi` is an index in the subsampled dimension and `is` is an index in the interpolation subarea dimensions. +For two-dimensional interpolation, `i1` and `i2` are indices in the interpolated dimensions, `tpi1` and `tpi2` are indices in the subsampled dimensions and `is1` and `is2` are indices in the interpolation subarea dimensions. + + +Note that, for simplicity of notation, the descriptions of the interpolation methods in most places leave out the indices of tie point related variables and refer to these with `a` and `b` in the one-dimensional case and with `a`, `b`, `c` and `d` in the two-dimensional case. In the two-dimensional case, `a = tp(tpi2, tpi1)`, `b = tp(tpi2, tpi1+1)`, `c = tp(tpi2+1, tpi1)` and `d = tp(tpi2+1, tpi1+1)` would reflect the way the tie point data would be stored in the data set, see also <>. + + +[[common-conversions-and-formulas, Section J.2, "Common Conversions and Formulas"]] +==== Common Conversions and Formulas + +[cols="2, 8, 8"] +|=============== +| |Description | Formula + +| `fll2v` | Conversion from geocentric `(latitude, longitude)` to three-dimensional cartesian vector `(x, y, z)` | `(x, y, z) = fll2v(ll) = (cos(ll.lat)*cos(ll.lon), cos(ll.lat)*sin(ll.lon), sin(ll.lat))` + + +| `fv2ll` | Conversion from three-dimensional cartesian vector `(x, y, z)` to geocentric `(latitude, longitude)`| `(lat, lon) = fv2ll(v) = (atan2(v.y, v.x), atan2(z, sqrt(v.x * v.x + v.y * v.y))` + + +| `faz2v` | Conversion from `(azimuth, zenith)` angles to three-dimensional cartesian vector `(x, y, z)` | `(x, y, z) = faz2v(az) = (sin(az.zenith) * sin(az.azimuth), sin(az.zenith) * cos(az.azimuth), cos(az.zenith))` + + +| `fv2az` | Conversion from three-dimensional cartesian vector `(x, y, z)` to `(azimuth, zenith)` angles | `(azimuth, zenith) = fv2az(v) = (atan2(y, x), atan2(sqrt(x * x + y * y), z)` + + +| `fsqrt` | Square Root | `s = fsqrt(t)` + +| `fplus` | Vector Sum | `(x, y, z) = fplus(va , vb) = (va.x + vb.x, va.y + vb.y, va.z + vb.z)` + +`(x, y, z) = fplus(va , vb, vc) = (va.x + vb.x + vc.x, va.y + vb.y + vc.y, va.z + vb.z + vc.z)` + +| `fminus` | Vector Difference | `(x, y, z) = fminus(va, vb) = (va.x - vb.x, va.y - vb.y, va.z - vb.z)` + + +| `fmultiply` | Vector multiplied by Scalar | `(x, y, z) = fmultiply(r, v) = (r * v.x, r * v.y, r * v.z)` + + +| `fcross` | Vector Cross Product | `(x, y, z) = fcross(va, vb) = (va.y*vb.z - va.z*vb.y, va.z*vb.x - va.x*vb.z, va.x*vb.y - va.y*vb.x)` + + +| `norm` | Normalised Vector | `(x, y, z) = norm(v) = (v.x, v.y, v.z) / sqrt (v.x*v.x + v.y*v.y + v.z*v.z)` + + +| `fdot` | Vector Dot Product | `d = fdot(va, vb) = va.x*vb.x + va.y*vb.y + va.z*vb.z` + +|=============== + +[[interpolation-methods, Section J.3, "Interpolation Methods"]] +=== Interpolation Methods + +==== Linear Interpolation + +[cols="6,15"] +|=============== +| Name | **`interpolation_name = "linear"`** +| Description | General purpose one-dimensional linear interpolation method for one or more coordinates +| Interpolation Parameter terms | None +| Coordinate Compression Calculations | None +| Coordinate Uncompression Calculations | + The coordinate value `u(i)` at index `i` between tie points `A` and `B` is calculated from: + + `u(i) = fl(ua, ub, s(i)) = ua + s*(ub-ua)`; + +where `ua` and `ub` are the coordinate values at tie points `A` and `B` respectively. + + +|=============== + +==== Bilinear Interpolation + +[cols="6,15"] +|=============== +| Name | **`interpolation_name = "bi_linear"`** +| Description | General purpose two-dimensional linear interpolation method for one or more coordinates +| Interpolation Parameter terms | None +| Coordinate Compression Calculations | None +| Coordinate Uncompression Calculations | +The interpolation function fl() defined for linear interpolation above is first applied twice in the interpolated dimension 2, once between tie points `A` and `C` and once between tie points `B` and `D`. It is then applied once in the interpolated dimension 1, between the two resulting coordinate points, yielding the interpolated coordinate value `u(i2, i1)`: + +`uac = fl(ua, uc, s(ia2, ic2, i2))`; + +`ubd = fl(ub, ud, s(ia2, ic2, i2))`; + +`u(i2, i1) = fl(uac, ubd, s(ia1, ib1, i1))`; + + + +|=============== + +[[quadratic]] +==== Quadratic Interpolation + +[cols="6,15"] +|=============== +| Name | **`interpolation_name = "quadratic"`** +| Description | General purpose one-dimensional quadratic interpolation method for one coordinate. + +| Interpolation Parameter terms | Optionally coefficient `w`, which must span the interpolation subarea dimension. + +| Coordinate Compression Calculations | +The expression + +`w = fw(ua, ub, u(i), s(i)) = ((u - (1 - s) * ua - s * ub)/( 4 * (1 - s) * s)` + +enables the creator of the dataset to calculate the coefficient `w` from the coordinate values `ua` and `ub` at tie points `A` and `B` respectively, and the coordinate value `u(i)` at index `i` between the tie points `A` and `B`. If the size of the interpolation subarea `(ib - ia)` is an even number, then the data point at index `i = (ib + ia)/2` shall be selected for this calculation, otherwise the data point at index `i = (ib + ia - 1)/2` shall be selected. + +| Coordinate Uncompression Calculations | +The coordinate value `u(i)` at index `i` between tie points `A` and `B` is calculated from: + + `u(i) = fq(ua, ub, w, s(i)) = ua + s * (ub - ua + 4 * w * (1 - s))`; + +where `ua` and `ub` are the coordinate values at tie points `A` and `B` respectively and the coefficient `w` is available as a term in the `interpolation_parameters`, or otherwise defaults to `0.0`. + +|=============== + +[[quadratic_geo]] +==== Quadratic Interpolation of Geographic Coordinates Latitude and Longitude + +[cols="6,15"] +|=============== +| Name | **`interpolation_name = "quadratic_latitude_longitude"`** +| Description | A one-dimensional quadratic method for interpolation of the geographic coordinates latitude and longitude, typically used for remote sensing products with geographic coordinates on the reference ellipsoid. + + +Requires a pair of latitude and longitude tie point variables, as defined unambiguously in <> and <>. For each interpolation subarea, none of the tie points defining the interpolation subarea are permitted to coincide. + +By default, interpolation is performed directly in the latitude and longitude coordinates, but may be performed in three-dimensional cartesian coordinates where required for achieving the desired accuracy. This must be indicated by setting the `location_use_3d_cartesian` flag within the interpolation parameter `interpolation_subarea_flags` for each interpolation subarea where interpolation in three-dimensional cartesian coordinates is required. + +The quadratic interpolation coefficients `cea = (ce, ca)`, stored as interpolation parameters in the product, describe a point `P` between the tie points `A` and `B`, which is equivalent of an additional tie point in the sense that the method will accurately reconstitute the point `P` in the same way as it accurately reconstitutes the tie points `A` and `B`. See <> and <>. + +Although equivalent to a tie point, the coefficients `ce` and `ca` have two advantages over tie points. Firstly, they can often be stored as a lower precision floating point number compared to the tie points, as `ce` and `ca` only describes the position of `P` relative to the midpoint `M` between the tie points `A` and `B`. Secondly, if any of `ce` and `ca` do not contribute significantly to the accuracy of the reconstituted points, it can be left out of the data set and its value will default to zero during uncompression. + +The coefficients may be represented in three different ways: + +For storage in the dataset as the non-dimensional coefficients `cea = (ce, ca)`, referred to as the parametric representation. The component `ce` is the offset projected on the line from tie point `B` to tie point `A` and expressed as a fraction of the distance between `A` and `B`. The component `ca` is the offset projected on the line perpendicular to the line from tie point `B` to tie point `A` and perpendicular to the plane spanned by `va` and `vb`, the vector representations of the two tie points, and expressed as a fraction of the length of `A x B`. + + +For interpolation in three-dimensional cartesian coordinates as the coefficients `cv = (cv.x, cv.y, cv.z)`, expressing the offset components along the three-dimensional cartesian axes X, Y and Z respectively. + +For interpolation in geographic coordinates latitude and longitude as the coefficients `cll = (cll.lat, cll.lon)`, expressing the offset components along the longitude and latitude directions respectively. + +The functions `fq()` and `fw()` referenced in the following are defined in <>. + +| Interpolation Parameter terms | Any subset of interpolation coefficients `ce, ca`, which must each span the interpolation subarea dimension. + +Optionally the flag variable `interpolation_subarea_flags`, which must span the interpolation subarea dimension and must include `location_use_3d_cartesian` in the `flag_meanings` attribute. + +| Coordinate Compression Calculations | +First calculate the tie point vector representations from the tie point latitude-longitude representations + +`va = fll2v(lla); vb = fll2v(llb);` + +Then calculate the three-dimensional cartesian representation of the interpolation coefficients from the tie points `va` and `vb` as well as the point `vp(i)` at index `i` between the tie points `A` and `B`. If the size of the interpolation subarea `(ib - ia)` is an even number, then the data point at index `i = (ib + ia)/2` shall be selected for this calculation, otherwise the data point at index `i = (ib + ia - 1)/2` shall be selected. + +The three-dimensional cartesian interpolation coefficients are found from + +`cv = fcv(va, vb, vp(i), s(i)) = (fw(va.x, vb.x, vp(i).x, s(i)), fw(va.y, vb.y, vp(i).y, s(i)), fw(va.z, vb.z, vp(i).z, s(i))).` + +Finally, for storage in the dataset, convert the coefficients to the parametric representation + +`cea(is) = (ce(is), ca(is)) = fcv2cea(va, vb, cv) = (fdot(cv, fminus(va, vb))/ gsqr), fdot(cv, fcross(va, vb))/(rsqr*gsqr));` + +where `vr = fmultiply(0.5, fplus(va, vb))`, `rsqr = fdot(vr, vr)`, `vg = fminus(va, vb)` and `gsqr = fdot(vg, vg).` + +The interpolation parameter term `interpolation_subarea_flags(is)` shall have the flag `location_use_3d_cartesian` set if the interpolation subarea intersects the `longitude = 180.0` or if the interpolation subarea extends into `latitude > latitude_limit` or `latitude < -latitude_limit`. +The value of `latitude_limit` is set by the data set creator and defines the high latitude areas where interpolation in three-dimensional cartesian coordinates is required for reasons of coordinate reconstitution accuracy. The `latitude_limit` is used solely for setting the flag `location_use_3d_cartesian`, and is not required in a compressed dataset. +| Coordinate Uncompression Calculations | +First calculate the tie point vector representations from the tie point latitude-longitude representations + +`va = fll2v(lla); vb = fll2v(llb);` + +Then calculate the three-dimensional cartesian representation of the interpolation coefficients from the parametric representation stored in the dataset using + +`cv = fcea2cv(va, vb, cea(is)) = fplus(fmultiply(ce, fminus(va, vb)), fmultiply(ca, fcross(va, vb)), fmultiply(cr, vr));` + +where + +`vr = fmultiply(0.5, fplus(va, vb))`; + +`rsqr = fdot(vr, vr);` + +`cr = fsqrt(1 - ce(is)*ce(is) - ca(is)*ca(is)) - fsqrt(rsqr).` + +If the flag `location_use_3d_cartesian` of the interpolation parameter term `interpolation_subarea_flags(is2, is1)` is set, use the following expression to reconstitute any point `llp(i)` between the tie points `A` and `B` using interpolation in three-dimensional cartesian coordinates + +`vp(i) = fqv(va, vb, cv, s(i)) = (fq(va.x, vb.x, cv.x, s(i)), fq(va.y, vb.y, cv.y, s(i)), fq(va.z, vb.z, cv.z, s(i)));` + +`llp(i) = fv2ll(vp(i)).` + +Otherwise, first calculate latitude-longitude representation of the interpolation coefficients + +`cll = fcll(lla, llb, llab) = (fw(lla.lat, llb.lat, llab.lat, 0.5), fw(lla.lon, llb.lon, llab.lon, 0.5));` + +where `llab = fv2ll(fqv(va, vb, cv, 0.5))`. + +Then use the following expression to reconstitute any point `llp(i)` between the tie points `A` and `B` using interpolation in latitude-longitude coordinates + +`llp(i) = (llp(i).lat, llp(i).lon) = fqll(lla, llb, cll, s(i)) = (fq(lla.lat, llb.lat, cll.lat, s(i)), fq(lla.lon, llb.lon, cll.lon, s(i)))`. + +|=============== + +[[quadratic1, figure 2]] +[.text-center] +.With the expansion coefficient ce = 0 and the alignment coefficient ca = 0, the method reconstitutes the points at regular intervals along a great circle between tie points A and B. +image::images/ci_quadratic1.svg[,100%,pdfwidth=50vw,align="center"] + +[[quadratic2, figure 3]] +[.text-center] +.With the expansion coefficient ce > 0 and the alignment coefficient ca > 0, the method reconstitutes the points at intervals of expanding size (ce) along an arc with an alignment offset (ca) from the great circle between tie points A and B. +image::images/ci_quadratic2.svg[,100%,pdfwidth=50vw,align="center"] + + +[[bi_quadratic_geo]] +==== Biquadratic Interpolation of Geographic Coordinates Latitude and Longitude + +[cols="6,15"] +|=============== +| Name | **`interpolation_name = "bi_quadratic_latitude_longitude"`** +| Description | A two-dimensional quadratic method for interpolation of the geographic coordinates latitude and longitude, typically used for remote sensing products with geographic coordinates on the reference ellipsoid. + +Requires a pair of latitude and longitude tie point variables, as defined unambiguously in <> and <>. For each interpolation subarea, none of the tie points defining the interpolation subarea are permitted to coincide. + +The functions `fcv()`, `fcv2cea()`, `fcea2cv()`, `fcll()`, `fqv()` and `fqll()` referenced in the following are defined in <>. As for that method, interpolation is performed directly in the latitude and longitude coordinates or in three-dimensional cartesian coordinates, where required for achieving the desired accuracy. Similarly, it shares the three different representations of the quadratic interpolation coefficients, the parametric representation `cea = (ce, ca)` for storage in the dataset, `cll = (cll.lat, cll.lon)` for interpolation in geographic coordinates latitude and longitude and `cv = (cv.x, cv.y, cv.z)` for interpolation in three-dimensional cartesian coordinates. + +The parametric representation of the interpolation coefficients, stored in the interpolation parameters `ce1, ca1, ce2, ca2, ce3` and `ca3`, is equivalent to five additional tie points for the interpolation subarea as shown in <>, which also shows the orientation and indices of the parameters. + +| Interpolation Parameter terms | +Any subset of interpolation coefficients `ce1, ca1`, which must each span the subsampled dimension 2 and interpolation subarea dimension 1; + +Any subset of interpolation coefficients `ce2, ca2`, which must each span the interpolation subarea dimension 2 and subsampled dimension 1; + +Any subset of interpolation coefficients `ce3, ca3`, which must each span the interpolation subarea dimension 2 and interpolation subarea dimension 1; + + +Optionally the flag variable `interpolation_subarea_flags`, which must span the interpolation subarea dimension 2 and interpolation subarea dimension 1 and must include `location_use_3d_cartesian` in the `flag_meanings` attribute. + +| Coordinate Compression Calculations | +First calculate the tie point vector representations from the tie point latitude-longitude representations + +`va = fll2v(lla); vb = fll2v(llb); vc = fll2v(llc); vd = fll2v(lld).` + +Then calculate the three-dimensional cartesian representation of the interpolation coefficients sets from the tie points as well as a point `vp(i2, i1)` between the tie points. If the size of the interpolation subarea in the first dimension `(ib1 - ia1)` is an even number, then the index +`i1 = (ib1 + ia1)/2` shall be selected for this calculation, otherwise the index +`i1 = (ib1 + ia1 - 1)/2` shall be selected. If the size of the interpolation subarea in the second dimension `(ib2 - ic2)` is an even number, then the index `i2 = (ib2 + ic2)/2` shall be selected for this calculation, otherwise the index `i2 = (ib2 + ic2 - 1)/2` shall be selected. + +Using the selected `(i2, i1)`, the three-dimensional cartesian interpolation coefficients are found from + +`s1 = s(ia1, ib1, i1);` +`s2 = s(ia2, ic2, i2);` + +`vac = fll2v(ll(i2, ia1));` +`vbd = fll2v(ll(i2, ib1));` + +`cv_ac = fcv(va, vc, vac, s2);` + +`cv_bd = fcv(vb, vd, vbd, s2);` + +`cv_ab = fcv(va, vb, fll2v(ll(ia2, i1)), s1);` + +`cv_cd = fcv(vc, vd, fll2v(ll(ic2, i1)), s1);` + +`cv_zz = fcv(vac, vbd, fll2v(ll(i2, i1)), s1);` + +`vz = fqv(vac, vbd, cv_zz, 0.5);` + +`vab = fqv(va, vb, cv_ab, 0.5);` + +`vcd = fqv(vc, vd, cv_cd, 0.5);` + +`cv_z = fcv(vab, vcd, vz, s2);` + +Finally, before storing them in the dataset's interpolation parameters, convert the coefficients to the parametric representation + +`cea1(tpi2, is1) = fcv2cea( va, vb, cv_ab);` + +`cea1(tpi2+1, is1) = fcv2cea( vc, vd, cv_cd);` + +`cea2(is2, tpi1) = fcv2cea( va, vc, cv_ac);` + +`cea2(is2, tpi1+1) = fcv2cea( vb, vd, cv_bd);` + +`cea3(is2, is1) = fcv2cea( vab, vcd, cv_z).` + +The interpolation parameter term `interpolation_subarea_flags(is2, is1)` shall have the flag `location_use_3d_cartesian` set if the interpolation subarea intersects the `longitude = 180.0` or if the interpolation subarea extends into `latitude > latitude_limit` or `latitude < -latitude_limit`. +The value of `latitude_limit` is set by the data set creator and defines the high latitude areas where interpolation in three-dimensional cartesian coordinates is required for reasons of coordinate reconstitution accuracy. The `latitude_limit` is used solely for setting the flag `location_use_3d_cartesian`, and is not required in a compressed dataset. + +| Coordinate Uncompression Calculations | +First calculate the tie point vector representations from the tie point latitude-longitude representations + +`va = fll2v(lla); vb = fll2v(llb); vc = fll2v(llc); vd = fll2v(lld).` + +Then calculate the three-dimensional cartesian representation of the interpolation coefficient sets from the parametric representation stored in the dataset + +`cv_ac = fcea2cv(va, vc, cea2(is2, tpi1));` + +`cv_bd = fcea2cv(vb, vd, cea2(is2, tpi1 + 1));` + +`vab = fqv(va, vb, fcea2cv(va, vb, cea1(tpi2, is1)), 0.5);` + +`vcd = fqv(vc, vd, fcea2cv(vc, vd, cea1(tpi2 + 1, is1)), 0.5);` + +`cv_z = fcea2cv(vab, vcd, cea3(is2, is1));` + +If the flag `location_use_3d_cartesian` of the interpolation parameter term `interpolation_subarea_flags` is set, use the following expression to reconstitute any point `llp(i2, i1)` between the tie points `A` and `B` using interpolation in three-dimensional cartesian coordinates + +`llp(i2, i1) = fv2ll(fqv(vac, vbd, cv_zz, s(ia1, ib1, i1)));` + +where + +`s2 = s(ia2, ic2, i2);` + +`vac = fqv(va, vc, cv_ac, s2);` + +`vbd = fqv(vb, vd, cv_bd, s2);` + +`vz = fqv(vab, vcd, cv_z, s2);` + +`cv_zz = fcv(vac, vbd, vz, 0.5);` + +Otherwise, first calculate latitude-longitude representation of the interpolation coefficients + +`llc_ac = fcll(lla, llc, fv2ll(fqv(va, vc, cv_ac, 0.5)), 0.5);` + +`llc_bd = fcll(llb, lld, fv2ll(fqv(vb, vd, cv_bd, 0.5)), 0.5);` + +`llab = fv2ll(vab);` + +`llcd = fv2ll(vcd);` + +`llc_z = fcll(llab, llcd, fv2ll(fqv(vab, vcd, cv_z, 0.5)), 0.5);` + +Then use the following expression to reconstitute any point `llp(i2, i1)` in the interpolation subarea using interpolation in latitude-longitude coordinates + +`llp(i2, i1) = fqll(llac, llbd, cl_zz, s(ia1, ib1, i1));` + +where + +`s2 = s(ia2, ic2, i2);` + +`llac = fqll(a, c, llc_ac, s2);` + +`llbd = fqll(b, d, llc_bd, s2);` + +`llz = fqll(llab, llcd, llc_z, s2);` + +`cl_zz = fcll(llac, llbd, llz, 0.5);` + +|=============== + +[[quadratic3, figure 4]] +[.text-center] +.The parametric representation of the interpolation coefficients `cea = (ce, ca)`, stored in the interpolation parameters `ce1, ca1, ce2, ca2, ce3` and `ca3`, is equivalent to five additional tie points for the interpolation subarea. Shown with parameter orientation and indices. +image::images/ci_quadratic3.svg[,50%,pdfwidth=50vw,align="center"] + + +[[coordinate-compression-steps, Section J.4, "Coordinate Compression Steps"]] +=== Coordinate Compression Steps + +|=============== +| Step | Description | Link + +| 1 +| Identify the coordinate and auxillary coordinate variables for which tie point and interpolation variables are required. +| + +| 2 +| Identify non-overlapping subsets of the coordinate variables to be interpolated by the same interpolation method. For each coordinate variable subset, create an interpolation variable and specify the selected interpolation method using the **`interpolation_name`** attribute of the interpolation variable. +| <> + +| 3 +| For each coordinate variable subset, add the coordinates variable subset and the corresponding interpolation variable name to the the **`coordinate_interpolation`** attribute of the data variable. +| <> + + +| 4 +| For each coordinate variable subset, identify the set of interpolated dimensions and the set of non-interpolated dimensions. +| <> + +| 5 +| For each set of the interpolated dimensions, identify the continuous areas and select the interpolation subareas and the tie points, taking into account the required coordinate reconstitution accuracy when selecting the density of tie points. +| <> + +| 6 +| For each of the interpolated dimensions, add the interpolated dimension, the corresponding subsampled dimension and, if required by the selected interpolation method, its corresponding interpolation subarea dimension to the **`tie_point_mapping`** attribute of the interpolation variable. +| <> + +<> + +| 7 +| For each of the interpolated dimensions, record the location of each identified tie point in a tie point index variable. For each interpolated dimension, add the tie point index variable name to the **`tie_point_mapping`** attribute of the interpolation variable. +| <> + +<> + +| 8 +| For each of the target coordinate and auxillary coordinate variables, create the corresponding tie point coordinate variable and copy the coordinate values from the target domain coordinate variables to the tie point variables for the target domain indices identified by the tie point index variable. Repeat this step for each combination of indices of the non-interpolated dimensions. +| <> + +<> + +| 9 +| For each of the target coordinate and auxillary coordinate variable having a **`bounds`** attribute, add the **`bounds_tie_points`** attribute to the tie point coordinate variable and create the bounds tie point variable. For each continuous area, copy the selected set of bounds tie points values from the target domain bounds variable to the bounds tie point variable for the target domain indices identified by the tie point index variable. Repeat this step for each combination of indices of the non-interpolated dimensions. +| <> + +| 10 +| If required by the selected interpolation method, follow the steps defined for the method in <> to create any required interpolation parameter variables. As relevant, create the **`interpolation_parameters`** attribute and populate it with the interpolation parameter variables. +| <> + +<> + +| 11 +| Optionally, check the consistency of the original coordinates and the reconstructed coordinates and add a **`comments`** attribute to one or more of the tie point coordinate variables reporting key figures like maximum error, mean error, etc. +| + + +|=============== + +[[coordinate-uncompression-steps, Section J.5, "Coordinate Uncompression Steps"]] +=== Coordinate Uncompression Steps + +|=============== +| Step | Description | Link + +| 1 +| From the **`coordinate_interpolation`** attribute of the data variable, identify the coordinate and auxillary coordinate variable subsets, for which tie point interpolation is required, and the interpolation variable corresponding to each subset. +| <> + +| 2 +| For each coordinate variable subset, identify the interpolation method from the +**`interpolation_name`** attribute of the interpolation variable. +| <> + +| 3 +| For each coordinate variable subset, identify the set of interpolated dimensions and the set of non-interpolated dimensions from the **`tie_point_mapping`** attribute of the interpolation variable. +| <> + +<> + + +| 4 +| From the **`tie_point_mapping`** attribute of the interpolation variable, identify for each of the interpolated dimensions the corresponding subsampled dimension and, if defined, the corresponding interpolation subarea dimension.| <> + +<> + + +| 5 +| From the tie point index variables referenced in the **`tie_point_mapping`** attribute of the interpolation variable, identify the location of the tie points in the corresponding interpolated dimension. +| <> + +<> + +| 6 +| For each of the interpolated dimensions, identify pairs of adjacent indices in the tie point index variable with index values differing by more than one, each index pair defining the extend of an interpolation subarea in that dimension. A full interpolation subarea is defined by one such index pair per interpolated dimension, with combinations of one index from each pair defining the interpolation subarea tie points. +| <> + +| 7 +| As required by the selected interpolation method, identify the interpolation parameter variables from the interpolation variable attribute **`interpolation_parameters`**. +| <> + +| 8 +| For each of the tie point coordinate and auxillary coordinate variables, create the corresponding target coordinate variable. For each interpolation subarea, apply the interpolation method, as described in <>, to reconstitute the target domain coordinate values and store these in the target domain coordinate variables. Repeat this step for each combination of indices of the non-interpolated dimensions. +| <> + +<> + +| 9 +| For each of the tie point coordinate and auxillary coordinate variables having a **`bounds_tie_points`** attribute, add the **`bounds`** attribute to the target coordinate variable and create the target domain bounds variable. For each interpolation subarea, apply the interpolation method to reconstitute the target domain bound values and store these in the target domain bound variables. Repeat this step for each combination of indices of the non-interpolated dimensions. +| <> + +| 10 +| If auxiliary coordinate variables have been reconstituted, then, if not already present, add a **`coordinates`** attribute to the data variable and add to the attribute the list of the names of the reconstituted auxiliary coordinate variables. +| <> + +|=============== diff --git a/bibliography.adoc b/bibliography.adoc index 7f38722e..98eed07b 100644 --- a/bibliography.adoc +++ b/bibliography.adoc @@ -14,6 +14,8 @@ - [[[FGDC]]] link:$$http://www.fgdc.gov/standards/projects/FGDC-standards-projects/metadata/base-metadata/v2_0698.pdf$$[Content Standard for Digital Geospatial Metadata] . Federal Geographic Data Committee, FGDC-STD-001-1998 . + +- [[[IEEE_754]]] link:$$https://ieeexplore.ieee.org/servlet/opac?punumber=8766227$$[IEEE Standard for Floating-Point Arithmetic], in __IEEE Std 754-2019 (Revision of IEEE 754-2008)__, vol., no., pp.1-84, 22 July 2019, doi: 10.1109/IEEESTD.2019.8766229. - [[[NetCDF]]] link:$$http://www.unidata.ucar.edu/netcdf/index.html$$[ NetCDF Software Package] . UNIDATA Program Center of the University Corporation for Atmospheric Research . diff --git a/cf-conventions.adoc b/cf-conventions.adoc index 437a678c..50857378 100644 --- a/cf-conventions.adoc +++ b/cf-conventions.adoc @@ -40,6 +40,10 @@ include::toc-extra.adoc[] * Alan D. Snow, Corteva Agriscience * Tobias Kölling, MPIM * Dave Allured, NOAA +* Aleksandar Jelenak, HDF Group +* Anders Meier Soerensen, EUMETSAT +* Lucile Gaultier, OceanDataLab +* Sylvain Herlédan, OceanDataLab Many others have contributed to the development of CF through their participation in discussions about proposed changes. @@ -107,6 +111,9 @@ include::apph.adoc[] :numbered!: include::appi.adoc[] +:numbered!: +include::appj.adoc[] + :numbered!: include::history.adoc[] diff --git a/ch01.adoc b/ch01.adoc index f818f6a4..1b6da72c 100644 --- a/ch01.adoc +++ b/ch01.adoc @@ -76,6 +76,8 @@ It is a one-dimensional variable with the same name as its dimension [e.g., **`t grid mapping variable:: A variable used as a container for attributes that define a specific grid mapping. The type of the variable is arbitrary since it contains no data. +interpolation variable:: A variable used as a container for attributes that define a specific interpolation method for uncompressing tie point variables. The type of the variable is arbitrary since it contains no data. + latitude dimension:: A dimension of a netCDF variable that has an associated latitude coordinate variable. local apex group:: The nearest (to a referring group) ancestor group in which a dimension of an out-of-group coordinate is defined. The word "apex" refers to position of this group at the vertex of the tree of groups formed by it, the referring group, and the group where a coordinate is located. @@ -103,6 +105,8 @@ sibling group:: Any group with the same parent group as the referring group spatiotemporal dimension:: A dimension of a netCDF variable that is used to identify a location in time and/or space. +tie point variable:: A netCDF variable that contains coordinates that have been compressed by sampling. There is no relationship between the name of a tie point variable and the name(s) of its dimension(s). + time dimension:: A dimension of a netCDF variable that has an associated time coordinate variable. vertical dimension:: A dimension of a netCDF variable that has an associated vertical coordinate variable. diff --git a/ch08.adoc b/ch08.adoc index 4724d47b..ef705716 100644 --- a/ch08.adoc +++ b/ch08.adoc @@ -1,7 +1,9 @@ == Reduction of Dataset Size -There are two methods for reducing dataset size: packing and compression. By packing we mean altering the data in a way that reduces its precision. By compression we mean techniques that store the data more efficiently and result in no precision loss. Compression only works in certain circumstances, e.g., when a variable contains a significant amount of missing or repeated data values. In this case it is possible to make use of standard utilities, e.g., UNIX **`compress`** or GNU **`gzip`** , to compress the entire file after it has been written. In this section we offer an alternative compression method that is applied on a variable by variable basis. This has the advantage that only one variable need be uncompressed at a given time. The disadvantage is that generic utilities that don't recognize the CF conventions will not be able to operate on compressed variables. +There are three methods for reducing dataset size: packing, lossless compression, and lossy compression. By packing we mean altering the data in a way that reduces its precision (but has no other effect on accuracy). By lossless compression we mean techniques that store the data more efficiently and result in no loss of precision or accuracy. By lossy compression we mean techniques that store the data more efficiently and retain its precision but result in some loss in accuracy. + +Lossless compression only works in certain circumstances, e.g., when a variable contains a significant amount of missing or repeated data values. In this case it is possible to make use of standard utilities, e.g., UNIX **`compress`** or GNU **`gzip`** , to compress the entire file after it has been written. In this section we offer an alternative compression method that is applied on a variable by variable basis. This has the advantage that only one variable need be uncompressed at a given time. The disadvantage is that generic utilities that don't recognize the CF conventions will not be able to operate on compressed variables. @@ -18,8 +20,8 @@ When data to be packed contains missing values the attributes that indicate miss -[[compression-by-gathering, Section 8.2, "Compression by Gathering"]] -=== Compression by Gathering +[[compression-by-gathering, Section 8.2, "Lossless Compression by Gathering"]] +=== Lossless Compression by Gathering To save space in the netCDF file, it may be desirable to eliminate points from data arrays that are invariably missing. Such a compression can operate over one or more adjacent axes, and is accomplished with reference to a list of the points to be stored. The list is constructed by considering a mask array that only includes the axes to be compressed, and then mapping this array onto one dimension without reordering. The list is the set of indices in this one-dimensional mask of the required points. In the compressed array, the axes to be compressed are all replaced by a single axis, whose dimension is the number of wanted points. The wanted points appear along this dimension in the same order they appear in the uncompressed array, with the unwanted points skipped over. Compression and uncompression are executed by looping over the list. @@ -68,3 +70,642 @@ variables: ---- This information implies that the salinity field should be uncompressed to an array with dimensions `(depth,lat,lon)` . ==== + + +[[compression-by-coordinate-subsampling, Section 8.3, "Lossy Compression by Coordinate Subsampling"]] +=== Lossy Compression by Coordinate Subsampling + +For some applications the coordinates of a data variable can require +considerably more storage than the data itself. Space may be saved in +the netCDF file by storing a subsample of the coordinates that describe +the data. The uncompressed coordinate and auxiliary coordinate +variables can be reconstituted by interpolation, from the subsampled +coordinate values to the domain of the data (i.e. the target +domain). This process will likely result in a loss in accuracy (as +opposed to precision) in the uncompressed variables, due to rounding +and approximation errors in the interpolation calculations, but it is +assumed that these errors will be small enough to not be of concern to +users of the uncompressed dataset. The creator of the compressed +dataset can control the accuracy of the reconstituted coordinates +through the degree of subsampling and the choice of interpolation +method, see <>. + +The subsampled coordinates are called __tie points__ and are stored in +__tie point coordinate variables__. + +In addition to the tie point coordinate variables themselves, metadata defining the coordinate interpolation method is stored in attributes of the data variable and of the associated __interpolation variable__. The partitioning of metadata between the data variable and the interpolation variable has been designed to minimise redundancy and maximise the reusability of the interpolation variable within a dataset. + +The metadata that define the interpolation formula and its inputs are complete, so that the results of the coordinate reconstitution process are well defined and of a predictable accuracy. + +[[compression-by-coordinate-subsampling-tie-points-and-interpolation-subareas, Section 8.3.1, "Tie Points and Interpolation Subareas"]] +==== Tie Points and Interpolation Subareas + +Reconstitution of the uncompressed coordinate and auxiliary coordinate +variables is based on interpolation. To accomplish this, the target +domain is segmented into smaller __interpolation subareas__, for each of +which the interpolation method is applied independently. For +one-dimensional interpolation, an interpolation subarea is defined by two +tie points, one at each end of the interpolation subarea; for +two-dimensional interpolation, an interpolation subarea is defined by +four tie points, one at each corner of a rectangular area aligned with +the domain axes; etc. For the reconstitution of the uncompressed +coordinate and auxiliary coordinate variables within an interpolation +subarea, the interpolation method is permitted to access its defining tie +points, and no others. + +As an interpolation method relies on the regularity and continuity of +the coordinate values within each interpolation subarea, special +attention must be given to the case when uncompressed coordinates +contain discontinuities. A discontinuity could be an overlap or a gap +in the coordinates' coverage, or a change in cell size or cell +alignment. As an example, such discontinuities are common in remote +sensing data and may be caused by combinations of the instrument scan +motion, the motion of the sensor platform and changes in the +instrument scan mode. When discontinuities are present, the domain is +first divided into multiple __continuous areas__, each of which is +free of discontinuities. When no discontinuities are present, the +whole domain is a single continuous area. Following this step, each +continuous area is segmented into interpolation subareas. The +processes of generating interpolation subareas for a domain without +discontinuities and for a domain with discontinuities is illustrated +in <>, and described in more detail in +<>. + +For each __interpolated dimension__, i.e. a target domain dimension for which coordinate interpolation is required, the locations of the tie point coordinates are defined by a corresponding __tie point index variable__, which also indicates the locations of the continuous areas (<>). + +The interpolation subareas within a continuous area do not overlap, ensuring that each coordinate of an interpolated dimension is computed from a unique interpolation subarea. These interpolation subareas, however, share the tie point coordinates that define their common boundaries. Such a shared tie point coordinate can only be located in one of a pair of adjacent interpolation subareas, which is always the first of the pair in index space. For instance, in <>, the interpolation subarea labelled `(0,0)` contains all four of its tie point coordinates, and the interpolation subarea `(0,1)` only contains two of them. When applied for a given interpolation subarea, interpolation methods (such as those described in <>) must ensure that reconstituted coordinate points are only generated inside the interpolation subarea being processed, even if some of the tie point coordinates lie outside of that interpolation subarea. + +Adjacent interpolation subareas that are in different continuous areas never share tie point coordinates, as consequence of the grid discontinuity between them. This results in a different number of tie point coordinates in the two cases shown in <>. + +For each interpolated dimension, the number of interpolation subareas is equal to the number of tie points minus the number of continuous areas. + +Tie point coordinate variables for both coordinate and auxiliary coordinate variables must be defined as numeric data types and are not allowed to have missing values. + +[[interpolation_subarea_generation, Figure 1]] +[.text-center] +.Process for generating the interpolation subareas for a grid without discontinuities and for a grid with discontinuities. +image::images/ci_interpolation_subarea_generation_process.svg[,100%,pdfwidth=50vw,align="center"] + +[[compression-by-coordinate-subsampling-coordinate-interpolation-attribute, Section 8.3.2, "Coordinate Interpolation Attribute"]] +==== Coordinate Interpolation Attribute + +To indicate that coordinate interpolation is required, a **`coordinate_interpolation`** attribute must be defined for a data variable. This is a string attribute that both identifies the tie point coordinate variables, and maps non-overlapping subsets of them to their corresponding interpolation variables. It is a blank-separated list of words of the form "__tie_point_coordinate_variable: [tie_point_coordinate_variable: ...] interpolation_variable [tie_point_coordinate_variable: [tie_point_coordinate_variable: ...] interpolation_variable ...]__". For example, to specify that the tie point coordinate variables `lat` and `lon` are to be interpolated according to the interpolation variable `bi_linear` could be indicated with `lat: lon: bi_linear`. + +[[compression-by-coordinate-subsampling-interpolation-variable, Section 8.3.3, "Interpolation Variable"]] +==== Interpolation Variable + +The method used to uncompress the tie point coordinate variables is described by +an interpolation variable that acts as a container for the attributes +that define the interpolation technique and the parameters that should +be used. The variable should be a scalar (i.e. it has no dimensions) +of arbitrary type, and the value of its single element is immaterial. + +The interpolation method must be identified in one of two ways. Either +by the **`interpolation_name`** attribute, which takes a string value +that contains the method's name, or else by the +**`interpolation_description`** attribute, which takes a string value +that contains a non-standardized description of the method. These +attributes must not be both set. + +The valid values of **`interpolation_name`** are given in <>. This appendix describes the interpolation technique for each +method, and optional interpolation variable attributes for configuring +the interpolation process. + +If a standardized interpolation name is not given, the interpolation +variable must have an **`interpolation_description`** attribute +defined instead, containing a description of the non-standardised +interpolation (in a similar manner to a long name being used instead +of a standard name). This description is free text that can take any +form (including fully qualified URLs, for example). Whilst it is +recommended that a standardised interpolation is provided, the +alternative is provided to promote interoperability in cases where a +well defined user community needs to use sophisticated interpolation +techniques that may also be under development. + +The definition of the interpolation method, however it is specified, +may include instructions to treat groups of physically related +coordinates simultaneously, if such tie points are present. For +example, there are cases where longitudes cannot be interpolated +without considering the corresponding latitudes. It is up to the +interpolation description to describe how such coordinates are to be +identified (e.g. it may be that such tie point coordinate variables require +particular units or standard names). + +Note that the interpolation method is always applied on a per +interpolation subarea basis, for which the construction of the +uncompressed coordinates may only access those tie points that define +the extent of the of the interpolation subarea. + +In addition to the **`interpolation_name`** and **`interpolation_description`** attributes described in this section, further attributes of the interpolation variable are described in <> and <>, <> and <>. + +[[compression-by-coordinate-subsampling-dimensions,Section 8.3.4, "Subsampled, Interpolated and Non-Interpolated Dimensions"]] +==== Subsampled, Interpolated and Non-Interpolated Dimensions + +For each interpolation variable identified in the +**`coordinate_interpolation`** attribute, all of the associated tie point +coordinate variables must share the same set of one or more dimensions. +This set of dimensions must correspond to the set of dimensions of the +uncompressed coordinate or auxiliary coordinate variables, such that each +of these dimensions must be either the uncompressed dimension itself, or +a dimension that is to be interpolated to the uncompressed dimension. + +Dimensions of the tie point coordinate variable which are to be +interpolated are called __subsampled dimensions__, and +the corresponding data variable dimensions are called __interpolated +dimensions__, while those for which no interpolation is required, +being the same in the data variable and the tie point coordinate +variable, are called __non-interpolated dimensions__. The dimensions +of a tie point coordinate variable must contain at least one +subsampled dimension, for each of which the corresponding +interpolated dimension cannot be included. + +The size of a subsampled dimension will be less than the +size of the corresponding interpolated dimension. For example, if the +interpolated dimensions are `xc = 30` and `yc = 10`, interpolation +could be applied in both of these dimensions, based on tie point +variables of the dimensions `tp_xc = 4` and `tp_yc = 2`. Here, +`tp_xc` is the subsampled dimension related to the +interpolated dimension `xc`, and `tp_yc` is the +subsampled dimension related to the interpolated dimension `yc`. + +The presence of non-interpolated dimensions in the tie point coordinate variable +impacts the interpolation process in that there must be a separate +application of the interpolation method for each combination of +indices of the non-interpolated dimensions. For example, if +`xc = 30` is an interpolated dimension and `yc = 10` +is a non-interpolated dimension, interpolation +could be applied in the `xc` dimension only, based on tie point +variables that have the subsampled dimension `tp_xc = 4` and the +non-interpolated dimension `yc = 10`. The +interpolation in the `xc` dimension would then be repeated for each of +the 10 indices of the `yc` non-interpolated dimension. + +[[compression-by-coordinate-subsampling-tie-point-mapping-attribute, Section 8.3.5, "Tie Point Mapping Attribute"]] +==== Tie Point Mapping Attribute + +The **`tie_point_mapping`** attribute provides mapping at two levels. It associates +interpolated dimensions with the corresponding subsampled dimensions, and for each +of these sets of corresponding dimensions, it associates index values +of the interpolated dimension with index values of the subsampled dimension, thereby +uniquely associating the tie points with their corresponding location in the +target domain. + +The mappings are stored in the interpolation variable's +**`tie_point_mapping`** attribute that contains a blank-separated +list of words of the form __"interpolated_dimension: tie_point_index_variable +subsampled_dimension [interpolation_subarea_dimension] +[interpolated_dimension: ...]"__, the details of which are described in the following two sections. + +[[compression-by-coordinate-subsampling-tie-point-dimension-mapping, Section 8.3.6, "Tie Point Dimension Mapping"]] +==== Tie Point Dimension Mapping + +The **`tie_point_mapping`** attribute defined above associates +each interpolated dimension with its corresponding subsampled + dimension and, if required, its corresponding + __interpolation subarea dimension__ that defines the number of +interpolation subareas which partition the interpolated dimension. +It is only required to associate an interpolated dimension +to an interpolation subarea dimension in the case that the interpolation +subarea dimension is spanned by an interpolation parameter variable, +as described in +<>. +If an interpolation subarea dimension is provided, then it must be +the second of the two named dimensions following the tie point index variable. + +Note that the size of an interpolation subarea dimension is, by definition, the size of the corresponding subsampled dimension minus the number of continuous areas. + +An overview of the different dimensions for coordinate interpolation is shown in <>. + +[[ci_dimensions_overview, figure 2]] +[.text-center] +.Overview of the different dimensions for coordinate interpolation. +image::images/ci_dimensions_overview.svg[,80%,pdfwidth=50vw,align="center"] + +[[compression-by-coordinate-subsampling-tie-point-index-mapping, Section 8.3.7, "Tie Point Index Mapping"]] +==== Tie Point Index Mapping + +The **`tie_point_mapping`** attribute defined in +<> +identifies for each subsampled dimension a tie point index variable. The tie +point index variable defines the relationship between the indices of +the subsampled dimension and the indices of its +corresponding interpolated dimension. + +A tie point index variable is a one-dimensional +integer variable that must span the subsampled dimension. Each tie point +index variable value is a zero-based index of the related +interpolated dimension which maps an element of that interpolated +dimension to the corresponding location in the subsampled +dimension. + +The tie point index values must be strictly monotonically increasing. The location in index space of a continuous area boundary that relates to a grid discontinuity (<>) is indicated by a pair of adjacent tie point index values differing by one. In this case, each tie point index of the pair defines a boundary of a different continuous area. As a consequence, any pair of tie point index values that defines an extent of an interpolation subarea must differ by two or more, i.e. in general, an interpolation subarea spans at least two points in each of its interpolated dimensions. Interpolation subareas that are the first in index space of a continuous area, in one or more of the subsampled dimensions are, however, special. These interpolation subareas contain tie points at both of the subarea boundaries with respect to those subsampled dimensions and so must span at least three points in the corresponding interpolated dimensions (see <>). + +For instance, in example <> +the tie point coordinate variables represent a subset of the target domain and +the tie point index variable `int x_indices(tp_xc)` contains the +indices `x_indices = 0, 9, 19, 29` that identify the location in the +interpolated dimension `xc` of size 30. The corresponding **`tie_point_mapping`** attribute of the interpolation variable is `xc: x_indices tp_xc yc: y_indices tp_yc`. + +[[example-Two-dimensional-tie-point-interpolation]] +[caption="Example 8.3. "] +.Two-dimensional tie point interpolation +==== +---- +dimensions: + xc = 30; + yc = 10; + tp_xc = 4 ; + tp_yc = 2 ; + +variables: + // Data variable + float Temperature(yc, xc) ; + Temperature:standard_name = "air_temperature" ; + Temperature:units = "K" ; + Temperature:coordinate_interpolation = "lat: lon: bl_interpolation" ; + + // Interpolation variable + char bl_interpolation ; + bl_interpolation:interpolation_name = "bi_linear" ; + bl_interpolation:tie_point_mapping = "xc: x_indices tp_xc yc: y_indices tp_yc" ; + bl_interpolation:computational_precision = "64" ; + + // tie point coordinate variables + double lat(tp_yc, tp_xc) ; + lat:units = "degrees_north" ; + lat:standard_name = "latitude" ; + double lon(tp_yc, tp_xc) ; + lon:units = "degrees_east" ; + lon:standard_name = "longitude" ; + + // Tie point index variables + int y_indices(tp_yc) ; + int x_indices(tp_xc) ; + +data: + x_indices = 0, 9, 19, 29 ; + y_indices = 0, 9 ; + ... +---- +==== + +[[example-1d-interpolation-of-2d-domain]] +[caption="Example 8.4. "] +.One-dimensional tie point interpolation of two-dimensional domain. +==== +---- +dimensions: + xc = 30; + yc = 10; + tp_xc = 4 ; + +variables: + // Data variable + float Temperature(yc, xc) ; + Temperature:standard_name = "air_temperature" ; + Temperature:units = "K" ; + Temperature:coordinate_interpolation = "lat: lon: l_interpolation" ; + + // Interpolation variables + char l_interpolation ; + l_interpolation:interpolation_name = "linear" ; + l_interpolation:tie_point_mapping = "xc: x_indices tp_xc" ; + l_interpolation:computational_precision = "64" ; + + // tie point coordinate variables + double lat(yc, tp_xc) ; + lat:units = "degrees_north" ; + lat:standard_name = "latitude" ; + double lon(yc, tp_xc) ; + lon:units = "degrees_east" ; + lon:standard_name = "longitude" ; + + // Tie point index variables + int x_indices(tp_xc) ; + +data: + x_indices = 0, 9, 19, 29 ; + ... +---- +==== + +[[compression-by-coordinate-subsampling-interpolation-parameters, Section 8.3.8, "Interpolation Parameters"]] +==== Interpolation Parameters + +The interpolation variable attribute **`interpolation_parameters`** +may be used to provide extra information to the interpolation +process. This attribute names __interpolation parameter variables__ +that provide values for coefficient terms in the interpolation +equation, or for any other terms that configure the interpolation +process. The **`interpolation_parameters`** attribute takes a string +value, the string comprising blank-separated elements of the form +`"term: variable"`, where `term` is a case-insensitive keyword that +defines one of the terms in the interpolation method's definition +given in <>, and `variable` is the name of the +interpolation parameter variable that contains the values for that +term. The order of elements is not significant. A numerical term that +is omitted from the **`interpolation_parameters`** attribute should be +assumed to be zero. + +The **`interpolation_parameters`** attribute may only be provided if +allowed by the definition of the interpolation method. Interpolation +parameters may always be provided to non-standardized interpolation +methods. + +The interpolation parameters are not permitted to contain absolute coordinate information, such as additional tie points, but may contain relative coordinate information, for example an offset with respect to a tie point or with respect to a combination of tie points. This is to ensure that interpolation methods are equally applicable to both coordinate and bounds interpolation. + +The interpolation parameter variable dimensions must include, for all of the interpolated dimensions, either the associated subsampled dimension or the associated interpolation subarea dimension. Additionally, any subset of zero or more of the non-interpolated dimensions of the tie point coordinate variable are permitted as interpolation parameter variable dimensions. + +The application of an interpolation parameter variable is independent of its non-interpolated dimensions, but depends on its set of subsampled dimensions and interpolation subarea dimensions: + +* If the set only contains subsampled dimensions, then the variable provides values for every tie point and therefore equally applicable to the interpolation subareas that share that tie point, see example a) in figure 3; +* If the set only contains interpolation subarea dimensions, then the variable provides values for every interpolation subarea and therefore only applicable to that interpolation subarea, see example b) in figure 3; +* If the set contains both subsampled dimensions and interpolation subarea dimensions, then the variable’s values are to be shared by the interpolation subareas that are adjacent along each of the specified subsampled dimensions. This case is akin to the values being defined at the interpolation subarea boundaries, and therefore equally applicable to the interpolation subareas that share that boundary, see example c) and d) in figure 3; + +[[ci_interpolation_parameters, figure 3]] +[.text-center] +.Through combination of dimensions, interpolation parameter variables may provide values for a) interpolation subareas sharing a tie point, b) each interpolation subarea, c) and d) interpolation subareas sharing a boundary. +image::images/ci_interpolation_coefficients.svg[,100%,pdfwidth=50vw,align="center"] + +[[example-VIIRS]] +[caption="Example 8.5. "] +.Multiple interpolation variables with interpolation parameter attributes. +==== +---- +dimensions : + // VIIRS I-Band (375 m resolution imaging) + track = 1536 ; + scan = 6400 ; + // Tie points and interpolation subareas + tp_track = 96 ; // 48 VIIRS scans + tp_scan = 205 ; + subarea_track = 48 ; // track interpolation subarea + subarea_scan= 200 ; // scan interpolation subarea + // Time, stored at scan-start and scan-end of each scan + tp_time_scan = 2; + +variables: + // VIIRS I-Band Channel 04 + float I04_radiance(track, scan) ; + I04_radiance:coordinate_interpolation = "lat: lon: tp_interpolation t: time_interpolation" ; + I04_radiance:standard_name = "toa_outgoing_radiance_per_unit_wavelength" ; + I04_radiance:units = "W m-2 sr-1 m-1" ; + float I04_brightness_temperature(track, scan) ; + I04_brightness_temperature:coordinate_interpolation = "lat: lon: tp_interpolation t: time_interpolation" ; + I04_brightness_temperature:standard_name = "brightness_temperature" ; + I04_brightness_temperature:units = "K" ; + + // Interpolation variable + char tp_interpolation ; + tp_interpolation:interpolation_name = "bi_quadratic_latitude_longitude" ; + tp_interpolation:tie_point_mapping = "track: track_indices tp_track subarea_track + scan: scan_indices tp_scan subarea_scan" ; + tp_interpolation:interpolation_parameters = "ce1: ce1 ca2: ca2 ce3: ce3 flags: interpolation_subarea_flags" ; + tp_interpolation:computational_precision = "32" ; + + // Interpolation parameters + short ce1(tp_track , subarea_scan) ; + short ca2(subarea_track , tp_scan) ; + short ce3(subarea_track, subarea_scan) ; + byte interpolation_subarea_flags(subarea_track , subarea_scan) ; + interpolation_subarea_flags : valid_range = "1b, 7b" ; + interpolation_subarea_flags : flag_masks = "1b, 2b, 4b" ; + interpolation_subarea_flags : flag_meanings = + "location_use_3d_cartesian + sensor_direction_use_3d_cartesian + solar_direction_use_3d_cartesian" ; + + // Tie point index variables + int track_indices(tp_track) ; // shared by tp_interpolation and time_interpolation + int scan_indices(tp_scan) ; + int time_scan_indices(tp_time_scan) + + // Tie points + float lat(tp_track, tp_scan) ; + lat:standard_name = "latitude" ; + lat:units = "degrees_north" ; + float lon(tp_track, tp_scan) ; + lon:standard_name = "longitude" ; + lon:units = "degrees_east" ; + + // Time interpolation variable + char time_interpolation ; + time_interpolation:interpolation_name = "bi_linear" ; + time_interpolation:tie_point_mapping = "track: track_indices tp_track scan: time_scan_indices tp_time_scan" ; + time_interpolation:computational_precision = "64" ; + + // Time tie points + double t(tp_track, tp_time_scan) ; + t:standard_name = "time" ; + t:units = "days since 1990-1-1 0:0:0" ; +---- + +This example demonstrates the use of multiple interpolation variables, +the reusability of the interpolation variable between data variables +of different dimensions and the use of the interpolation parameter +attribute. + +==== + +[[example-grid-mapping-and-interpolation-with-time-not-interpolated]] +[caption="Example 8.6. "] +.Combining a grid mapping and coordinate interpolation, with time as a non-interpolated dimension. +==== +---- +dimensions: + y = 228; + x = 306; + time = 41; + + // Tie point dimensions + tp_y = 58; + tp_x = 52; + +variables: + // Data variable + float Temperature(time, y, x) ; + Temperature:standard_name = "air_temperature" ; + Temperature:units = "K" ; + Temperature:grid_mapping = "lambert_conformal" ; + Temperature:coordinate_interpolation = "lat: lon: bi_linear x: linear_x y: linear_y" ; + + int lambert_conformal ; + lambert_conformal:grid_mapping_name = "lambert_conformal_conic" ; + lambert_conformal:standard_parallel = 25.0 ; + lambert_conformal:longitude_of_central_meridian = 265.0 ; + lambert_conformal:latitude_of_projection_origin = 25.0 ; + + // Interpolation variables + char bi_linear ; + bi_linear:interpolation_name = "bi_linear" ; + bi_linear:tie_point_mapping = "y: y_indices tp_y x: x_indices tp_x" ; + bi_linear:computational_precision = "64" ; + + char linear_x ; + linear_x:interpolation_name = "linear" ; + linear_x:tie_point_mapping = "x: x_indices tp_x" ; + linear_x:computational_precision = "64" ; + + char linear_y ; + linear_y:interpolation_name = "linear" ; + linear_y:tie_point_mapping = "y: y_indices tp_y" ; + linear_y:computational_precision = "64" ; + + // tie point coordinate variables + double time(time) ; + time:standard_name = "time" ; + time:units = "days since 2021-03-01" ; + double y(time, tp_y) ; + y:units = "km" ; + y:standard_name = "projection_y_coordinate" ; + double x(time, tp_x) ; + x:units = "km" ; + x:standard_name = "projection_x_coordinate" ; + double lat(time, tp_y, tp_x) ; + lat:units = "degrees_north" ; + lat:standard_name = "latitude" ; + double lon(time, tp_y, tp_x) ; + lon:units = "degrees_east" ; + lon:standard_name = "longitude" ; + + // Tie point index variables + int y_indices(tp_y) ; + y_indices:long_name = "Mapping of y dimension to its ", + "corresponding tie point dimension" ; + int x_indices(tp_x) ; + x_indices:long_name = "Mapping of x dimension to its ", + "corresponding tie point dimension" ; +---- + +In this the projection coordinates are two-dimensional, but are only +linearly interpolated in one of their dimensions - the one which is +given by the **`tie_point_mapping`** attribute. + +==== + + +[[compression-by-coordinate-subsampling-interpolation-of-cell-boundaries, Section 8.3.9, "Interpolation of Cell Boundaries"]] +==== Interpolation of Cell Boundaries + +Coordinates may have cell bounds. For the case that the reconstituted cells are contiguous and have exactly two cell bounds along each interpolated dimension, cell bounds of interpolated dimensions can be stored as __bounds tie points__ and reconstituted through interpolation. In this process, the coordinate tie points are a prerequisite for the bounds tie points and the same interpolation method used for the coordinate interpolation is used for the bounds interpolation. + +For the reconstituted coordinates, cell bounds are stored separately for each coordinate point, as shown in the left part of <> +for the example of 2D bounds. Since the cell bounds are contiguous, bounds points of adjacent cells will coincide and so the full set of bounds points may be represented as a grid, comparable to the coordinate points grid. In the middle part of <> +, both the reconstituted bounds points grid and the reconstituted coordinate points grid are shown for a continuous area, where each bounds point may be shared by up to four cells. + +Bounds interpolation uses the same tie point index variables and therefore the same tie point cells as coordinate interpolation. One of the vertices of each coordinate tie point cell is chosen as the bounds tie point for the cell. It is selected as the vertex of the tie point cell that is the closest to the boundary of the interpolation subarea with respect to each interpolated dimension. For the example of 2D bounds, the resulting set of bounds tie points are marked in <>, where the selected vertices are those closest to the corners of the interpolation subareas. + +Note that within a continuous area, there is one more reconstituted bounds point than there are reconstituted coordinate points in each dimension. For this reason, a virtual __interpolated bounds dimension__ is introduced for each dimension, having a size equal to the size of the interpolated dimension plus one. This dimension is used for solely descriptive purposes, and is not required in a compressed dataset. + + + +[[figure_interpolation_of_cell_boundaries, Figure 4]] +[.text-center] +.Example of 2D bounds interpolation showing the bounds tie points and reconstituted bound points within a continuous area consisting of four interpolation subareas. The dimensions are show for one of the two axes only. The index relationship between coordinate point indices and the related bound points indices is indicated. +image::images/ci_bounds_interpolation.svg[,100%,pdfwidth=50vw,align="center"] + + +Both the process of compressing bounds and the process of uncompressing bounds requires the steps to be carried out for a full continuous area, however, individual continuous areas can be processed independently. In the following description of these processes, indices relative to the origin of each continuous area are used for the interpolated dimension and the interpolated bounds dimension. Consequently, for both coordinate tie points and bounds tie points, the first point in index space of the continuous area has got index 0 in all the interpolated dimensions and interpolated bounds dimensions, respectively. + +Note that the numbering of the bounds `B0`, `B1`, etc, in this section is identical to the numbering in <>. + +A bounds tie point is located in the same interpolation subarea as its corresponding coordinate tie point. The interpolation subareas do not overlap, ensuring that each bound point is computed from a unique interpolation subarea, see also the description of interpolation subareas in <>. That bounds are computed only once ensures that the reconstituted bounds are contiguous. + +For the generation of bounds tie points as part of the process of compressing bounds, the indices of the corresponding coordinate tie points are available in the tie point index variables, see <>. + +[[compressing_one_dimensional, "Compressing one-dimensional coordinate bounds"]] +**Compressing one-dimensional coordinate bounds** + +In the one-dimensional case, a coordinate point at index `i` in the interpolated dimension will be bounded by the two bounds + +`B0 = (n0) = (i); B1 = (n1) = (i+1)` + +where `n` is the bound index in the interpolated bound dimension. + +For one-dimensional bound interpolation, an interpolation subarea is defined by two bounds tie points. The full set of bounds tie points is formed by appending, for each continuous area of the domain, the bound point `B0` of the first coordinate tie points of the continuous area, followed by the bound points `B1` of all subsequent coordinate tie point of the continuous area. + +[[compressing_two_dimensional, "Compressing two-dimensional coordinate bounds"]] +**Compressing two-dimensional coordinate bounds** + +In the two-dimensional case, a coordinate point at indices `(j, i)` in the interpolated dimension will be bounded by the four bounds + +`B0 = (n0, m0) = (j, i); B1 = (n1, m1) = (j, i+1)` + +`B3 = (n3, m3) = (j+1, i); B2 = (n2, m2) = (j+1, i+1)` + +where `(n, m)` are the bounds point indices in the interpolated bound dimensions. + +For two-dimensional bound interpolation, an interpolation subarea is defined by four bounds tie points. The full set of bounds tie points is formed by appending, for each continuous area of the domain, the bound point `B0` of the coordinate tie point at origin the of the continuous area `(0, 0)`, followed by the bound points `B1` of all remaining coordinate tie point of the continuous area with index `j = 0`, followed by the bound points `B3` of all remaining coordinate tie point of the continuous area with index `i = 0`, followed by the bound points `B2` of all remaining coordinate tie point of the continuous area. + +**Bounds Tie Point Attribute and Bounds Tie Point Variable** + +A **`bounds_tie_points`** attribute must be defined for each tie point coordinate variable corresponding to reconstituted coordinates with cell boundaries. It is a single word of the form __“bounds_tie_point_variable”__ that identifies a bounds tie point variable, containing a bounds tie point coordinate value for each tie point stored in its tie point coordinate variable, and therefore the bounds tie point variable has the same set of dimensions as its tie point coordinate variable. An example of the usage of the **`bounds_tie_points`** is shown in <>. Since a bounds tie point variable is considered to be part of a tie point coordinate variable’s metadata, it is not necessary to provide it with attributes such as long_name and units, following the same rules as for the bounds of an uncompressed coordinate variable, see <>. + +**Uncompressing coordinate bounds** + +The reconstitution of the full set of bounds from the bounds tie point is a two-step process. In a first step, which must be carried out for a full continuous area at a time, each bound point is reconstituted by interpolation between the bounds tie points within each interpolation subarea, using the same interpolation method as defined for the ordinary tie points. This step results in a grid of bound points spanning the interpolated bound dimensions. In a second step the reconstituted bounds vertices are replicated to the boundary variables of the reconstituted coordinates. + +**Uncompressing one-dimensional coordinate bounds** + +For one-dimensional coordinate bounds, in the second step of the process, for each index `i` of the interpolated dimension, the two bounds of the boundary variable are set to the value of the interpolated bounds point grid at the indices `B0` and `B1`, respectively, where the indices are defined above under <>. + +**Uncompression of two-dimensional coordinate bounds** + +For two-dimensional coordinate bounds, in the second step of the process, for each index pair `(j, i)` of the interpolated dimension, the four bounds of the boundary variable is set to the value of the interpolated bounds point grid at index pairs `B0` , `B1` , `B2` and `B3`, respectively, where the index pairs are defined above under <>. + + +[[example_interpolation_of_cell_boundaries, Example 8.7]] +[caption="Example 8.7 "] +.Interpolation of 2D Cell Boundaries corresponding to <> +==== +---- +dimensions: + ic = 10; + itp = 3; + + jc = 10; + jtp = 3; + +variables: + // Data variable + float Temperature(jc, ic) ; + Temperature:standard_name = "air_temperature" ; + Temperature:units = "K" ; + Temperature:coordinate_interpolation = "lat: lon: bl_interpolation" ; + + // Interpolation variable + char bl_interpolation ; + bl_interpolation:interpolation_name = "bi_linear" ; + bl_interpolation:tie_point_mapping = "ic: i_indices itp jc: j_indices jtp" ; + bl_interpolation:computational_precision = "64" ; + + // Tie point index variables + int i_indices(itp) ; + int j_indices(jtp) ; + + // Tie point coordinate variables + double lat(jtp, itp) ; + lat:units = "degrees_north" ; + lat:standard_name = "latitude" ; + lat:bounds_tie_points = "lat_bounds" ; + + double lon(jtp, itp) ; + lon:units = "degrees_east" ; + lon:standard_name = "longitude" ; + lon:bounds_tie_points = "lon_bounds" ; + + // Bounds tie point variables + double lat_bounds(jtp, itp) ; + double lon_bounds(jtp, itp) ; + +---- +==== + +[[compression-by-coordinate-subsampling-interpolation-method-implementation, Section 8.3.10, "Interpolation Method Implementation"]] +==== Interpolation Method Implementation + +The accuracy of the reconstituted coordinates depends mainly on the degree of subsampling and the choice of interpolation method, both of which are set by the creator of the dataset. The accuracy and reproducibility will also depend, however, on how the interpolation method is implemented and on the computer platform carrying out the computations. To facilitate a good level of reproducibility of the processes of compressing and uncompressing coordinates, requirements are placed on the specification of interpolation methods and on stating the computational precision. + +**Interpolation Method Specification** + +The interpolation method specifications provided in <> are complete in their description of steps and formulas required for compressing and uncompressing coordinate data. Formulas are structured in a way that encourages an efficient implementation of the interpolation method in a high-level programming language. For instance, expressions that are constant within a computational loop should be externalised from that loop. + +**Computational Precision Attribute** + +The data creator shall specify the floating-point arithmetic precision used during the preparation and validation of the compressed coordinates by setting the interpolation variable’s **`computational_precision**` attribute to one of the following values: + +[cols="3,10"] +|=============== +| ** Value ** | ** Description** +| "32" | 32-bit floating-point arithmetic, comparable to the binary32 standard in [<>] +| "64" | 64-bit floating-point arithmetic, comparable to the binary64 standard in [<>] +|=============== + +Using the given computational precision in the interpolation computations is a necessary, but not sufficient, condition for the data user to be able to reconstitute the coordinates to an accuracy comparable to that intended by the data creator. For instance, a **`computational_precision**` value of **`"64"**` would specify that, using the same implementation and hardware as the creator of the compressed dataset, sufficient accuracy could not be reached when using a floating-point precision lower than 64-bit floating-point arithmetic in the interpolation computations required to reconstitute the coordinates. diff --git a/conformance.adoc b/conformance.adoc index 966cdfe5..7b7b1b10 100644 --- a/conformance.adoc +++ b/conformance.adoc @@ -678,6 +678,134 @@ in the file. starting with 0 and going up to the product of the compressed dimension sizes minus 1 (CDL index conventions). +[[compression-by-gathering]] +=== 8.2 Lossless Compression by Gathering + +*Requirements:* + +* The **`compress`** attribute may only be attached to a coordinate variable +with an integer data type. +* The type of the **`compress`** attribute is a string whose value is a blank +separated list of dimension names. The specified dimensions must exist +in the file. +* The values of the associated coordinate variable must be in the range +starting with 0 and going up to the product of the compressed dimension +sizes minus 1 (CDL index conventions). + +[[compression-by-coordinate-subsampling]] +=== 8.3 Lossy Compression by Coordinate Subsampling + +*Requirements:* + +* When attached to a data variable, the type of the **`tie_points`** + attribute is a string whose value is a list of blank separated word + groups of the following form, in which brackets indicate optional + text: **`tie_point_variable: [tie_point_variable: ...] + interpolation_variable`**. Each **`tie_point_variable`** token + specifies a tie point variable that must exist in the file, and each + **`interpolation_variable`** token specifies a variable that must + exist in the file. + +* An interpolation variable must have one of the string-valued + attributes **`interpolation_name`** or + **`interpolation_description`**, but not both. The legal values for + the **`interpolation_name`** attribute are contained in the + Interpolation Methods section of http://cfconventions.org/cf-conventions/cf-conventions.html#appendix-coordinate-subsampling[Appendix J]. + +* An interpolation variable must have the attribute **`computational_precision`**. + The legal values for the **`computational_precision`** attribute are contained in the Interpolation Method Implementation subsection of the Lossy Compression by Coordinate Subsampling section of chapter 8. + +* An interpolation variable must have a **`tie_point_dimensions`** + attribute that is a string whose value is a list of blank separated + word groups of the following form, in which brackets indicate + optional text: **`interpolation_dimension: + tie_point_interpolation_dimension [interpolation_zone_dimension]`**. + Each **`interpolation_dimension`** token specifies a unique + interpolation dimension of the parent data variable, each + **`tie_point_interpolation_dimension`** token specifies the tie + point interpolation dimension of a unique tie point index variable, + and each **`interpolation_zone_dimension`** token specifies a unique + interpolation zone dimension. The tie point interpolation dimensions + and interpolation zone dimensions must not be dimensions of the + parent data variable. + +* The tie point variables associated with each + **`interpolation_variable`** token must all span the same dimensions, + which comprise a subset of zero or more dimensions of the parent + data variable with the addition of all of the tie point + interpolation dimensions identified by the **`tie_point_dimensions`** + attribute of the interpolation variable. A tie point variable must + not span both a tie point interpolation dimension and its + corresponding interpolation dimension, as defined by the + **`tie_point_dimensions`** mapping. + +* An interpolation variable must have a **`tie_point_indices`** + attribute that is a string whose value is a list of blank separated + word pairs of the following form: **`interpolation_dimension: + tie_point_index_variable`**. The **`interpolation_dimension`** + tokens specify the same interpolation dimensions as the + **`tie_point_dimensions`** attribute, and each + **`tie_point_index_variable`** token specifies a tie point index + variable that must exist in the file. + +* A tie point index variable must be a one-dimensional variable with + an integer data type. + +* The dimension of a tie point index variable must be a tie point + interpolation dimension identified by the **`tie_point_dimensions`** + attribute. + +* The values of a tie point index variable must be non-negative + integers. The first value must be zero, and each subsequent value + must be greater than or equal to the previous value. If a value + differs by zero or one from its previous value, then it must differ + by two or more from its subsequent value. + +* The size of an interpolation zone dimension must be equal to the + size of the corresponding tie point interpolation dimension minus + the number of interpolation areas for that tie point interpolation + dimension. The number of interpolation areas is equal one plus the + number of occurences of adjacent values differing by zero or one in + the corresponding tie point index variable. + +* When attached to an interpolation variable, the type of the + **`interpolation_parameters`** attribute is a string whose value is + list of blank separated word pairs in the form **`term: var`**. For + each valid **`interpolation_name`**, the legal values for **`term`** + are described by the "Interpolation Parameter terms" table entry in + the Interpolation Methods section of http://cfconventions.org/cf-conventions/cf-conventions.html#appendix-coordinate-subsampling[Appendix J]. + The values of + **`var`** must be interpolation parameter variables that exist in + the file. + +* The dimensions of an interpolation parameter variable must be a + subset of zero or more of the dimensions of the corresponding tie + point variables, with the exception that a tie point interpolation + dimension may be replaced with its corresponding interpolation zone + dimension, as defined by the **`tie_point_dimensions`** mapping. + +* If a tie point variable has **`bounds_tie_points`** attribute then + it must be a string whose value is a single variable name. The + specified variable must exist in the file. + +* A bounds tie point variable must have the same dimensions as its + associated tie points coordinate variable. + +* A bounds tie point variable must be a numeric data type. + +* A bounds tie point variable must not have the **`_FillValue`** or + **`missing_value`** attributes. The requirements on all other bounds + tie point variable attributes are the same as for bounds variables + described in <>. + +*Recommendations:* + +* An interpolation variable should have 0 dimensions. + +* The recommendations on bounds tie point variable attributes are the + same as for bounds variables described in <>. + +  === Appendix D Parametric Vertical Coordinates *Requirements:* diff --git a/history.adoc b/history.adoc index 42ff32d3..17aaa9c4 100644 --- a/history.adoc +++ b/history.adoc @@ -285,3 +285,9 @@ node coordinate variables to be one of the dimensions of the data variable. .2 July 2021 . link:$$https://github.com/cf-convention/cf-conventions/issues/298$$[Issue #298]: Interpretation of negative years in the units attribute . link:$$https://github.com/cf-convention/cf-conventions/issues/319$$[Issue #319]: Restrict "gregorian" label to only dates in the Gregorian calendar + +.24 August 2021 +. Added <>. +. Updated definitions in chapter 1 and Appendix A +. Added <>. + diff --git a/images/ci_1d_interpolation_subarea.svg b/images/ci_1d_interpolation_subarea.svg new file mode 100644 index 00000000..0a38d0fc --- /dev/null +++ b/images/ci_1d_interpolation_subarea.svg @@ -0,0 +1 @@ +ABAB0.0……1.0s0.0……1.0sibiaiibiaiInterpolated DimensionuaubuuaubuCoordinate valuetpi1+1tpi1tpi1+1tpi1Subsampled Dimension(0)(1)Interpolation Subarea (0) including Tie Pont A Interpolation Subarea (1) excluding Tie Pont A Interpolation argument \ No newline at end of file diff --git a/images/ci_2d_interpolation_subarea.svg b/images/ci_2d_interpolation_subarea.svg new file mode 100644 index 00000000..27708dc6 --- /dev/null +++ b/images/ci_2d_interpolation_subarea.svg @@ -0,0 +1 @@ +uaADCB...01.0...s20.0……1.0s1uia1id2ia2i2uducucdtpi1tpi2+1tpi2Interpolated DimensionCoordinate valueSubsampled Dimensionubib1tpi1+1i1uabInterpolation argument \ No newline at end of file diff --git a/images/ci_bounds_interpolation.svg b/images/ci_bounds_interpolation.svg new file mode 100644 index 00000000..a9ce9fd2 --- /dev/null +++ b/images/ci_bounds_interpolation.svg @@ -0,0 +1 @@ +Interpolated Bound Dimension, mSize 11Interpolated Dimension, iSize 10490012Subsampled Dimension shared byCoordinate and Bounds Tie PointsSize 310Coordinate Tie PointsReconstituted CoordinateBounds Tie PointsReconstituted BoundsmnijCoordinatePoint(j, i)in Interpolated DimensionsRelated Cell defined by four Bound Points(n, m)in Bound DimensionsB0 = (n0, m0) = (j, i)B1 = (n1, m1)= (j, i+1)B3 = (n3, m3) = (j+1, i)B2 = (n2, m2) = (j+1, i+1)0(0,0)(0,1)(1,0)(1,1)5 \ No newline at end of file diff --git a/images/ci_dimensions_overview.svg b/images/ci_dimensions_overview.svg new file mode 100644 index 00000000..e7701417 --- /dev/null +++ b/images/ci_dimensions_overview.svg @@ -0,0 +1 @@ +901929Interpolated DimensionSize 3010243Subsampled DimensionSize 5102Interpolation Subarea DimensionSize 3Tie PointTie Point Indices:x_indices= 0, 9, 19, 20, 29 y_indices= 0, 7, 8, 15ContinuousAreas 210xyForthe x-dimension: \ No newline at end of file diff --git a/images/ci_interpolation_coefficients.svg b/images/ci_interpolation_coefficients.svg new file mode 100644 index 00000000..8d50e331 --- /dev/null +++ b/images/ci_interpolation_coefficients.svg @@ -0,0 +1 @@ +xyExample c)Dimension (y_ interpolation_subarea, x_subsampled)Example (1, 2) Example d)Dimension (y_subsampled, x_interpolation_subarea)Example (2, 0) Example b)Dimension (y_ interpolation_subarea, x_ interpolation_subarea)Example (0, 1) Example a)Dimension (y_subsampled, x_subsampled)Example (1, 1) \ No newline at end of file diff --git a/images/ci_interpolation_subarea_generation_process.svg b/images/ci_interpolation_subarea_generation_process.svg new file mode 100644 index 00000000..3b5b3d17 --- /dev/null +++ b/images/ci_interpolation_subarea_generation_process.svg @@ -0,0 +1 @@ +Coordinatesand AuxiliaryCoordinatesContinuousAreasseparated byGrid DiscontinuitiesInterpolation Subareas,sharing TiePoints within,but not between,ContinuousAreasGrid(0,0)(0,1)(1,1)(1,0)Grid with DiscontinuitiesCoordinate SpaceIndex Space(0,0)(0,1)(1,1)(1,0)(0,2)(1,2)(0,0)(0,1)(1,1)(1,0)(0,2)(1,2)(0,0)(0,0)(0,0)(0,1)(1,1)(1,0) \ No newline at end of file diff --git a/images/ci_quadratic1.svg b/images/ci_quadratic1.svg new file mode 100644 index 00000000..a6275a43 --- /dev/null +++ b/images/ci_quadratic1.svg @@ -0,0 +1 @@ +-0.2-0.100.10.2-0.200.20.40.60.811.2YXca(iz)= 0ABM, Pce(iz)= 0 \ No newline at end of file diff --git a/images/ci_quadratic2.svg b/images/ci_quadratic2.svg new file mode 100644 index 00000000..e2c3fd6c --- /dev/null +++ b/images/ci_quadratic2.svg @@ -0,0 +1 @@ +-0.2-0.100.10.2-0.200.20.40.60.811.2YXABMca(iz)= 0.1ce(iz)=0.07P \ No newline at end of file diff --git a/images/ci_quadratic3.svg b/images/ci_quadratic3.svg new file mode 100644 index 00000000..94b42322 --- /dev/null +++ b/images/ci_quadratic3.svg @@ -0,0 +1 @@ +ca1(tp2+1, iz1)ca1(tp2, iz1)ce1(tp2, iz1)ca1(tp2+1, iz1)ca3(iz2, iz1)ce3(iz2, iz1)ca2(iz2, tp1)ce2(iz2, tp1)ca2(iz2, tp1+1)ce2(iz2, tp1+1)ABCD \ No newline at end of file diff --git a/toc-extra.adoc b/toc-extra.adoc index daf76be7..a3854c81 100644 --- a/toc-extra.adoc +++ b/toc-extra.adoc @@ -58,6 +58,10 @@ F.1. <> 7.16. <> 8.1. <> 8.2. <> +8.3. <> +8.4. <> +8.5. <> +8.6. <> B.1. <> H.1. <> H.2. <>