Specification of Coordinate Reference System properties in Well-Known Text format
|Reported by:||pbentley||Owned by:||cf-conventions@…|
Specification of Coordinate Reference System properties in Well-Known Text format
3.1. Data producers and software application developers desire a mechanism for specifying coordinate reference system (CRS) properties that are not covered by the existing set of CF grid mapping attributes.
3.2. Because the conceptual model for coordinate reference systems is both large and complex it is considered impractical to devise CF attributes for all of the potential CRS properties which might need to be encoded as metadata attributes in netCDF files. Consequently there is a requirement for such CRS properties to be specified in a compact notational format, preferably a format that is already in widespread use, either as a de facto or de jure standard.
3.3. The proposed method for specifying additional CRS properties should be optional and should act as an adjunct, or supplement, to the existing grid mapping attributes defined in the latest CF conventions.
3.4. The proposed method, if applied to existing CF-compliant netCDF files, should not render such files non-compliant.
3.5. If a given CRS property is defined both by the proposed method and also by one of the existing CF grid mapping attributes, and the property values differ, then the latter value shall take precedence.
4. Initial Statement of Technical Proposal
4.1 Background (Informative)
The current proposal entails the addition of an optional new grid mapping attribute to the CF conventions. The proposed name of the attribute is crs_wkt, signifying coordinate reference system well-known text (commonly abbreviated to CRS WKT). The CRS WKT format is widely recognised and used within the geoscience software community. As such it represents the obvious candidate for encoding information about a variety of coordinate reference system parameters.
The value of the crs_wkt attribute must be a text string, i.e. netCDF data type NC_CHAR or, as of netCDF-4, NC_STRING. The text content of the new attribute must adhere to the CRS WKT syntax, as specified in  (and prior to that !). The crs_wkt attribute should only be attached to grid mapping variables.
The purpose of the new crs_wkt attribute is to enable multiple CRS properties to be specified in compact form in a single netCDF attribute. Importantly, the crs_wkt attribute is intended to act as a supplement to existing CF grid mapping attributes - it is not intended to replace them. This is in order to maintain backwards-compatibility with existing netCDF software clients, which naturally will have no knowledge of the proposed new attribute and will expect to find the familiar grid mapping attributes.
The idea of using WKT syntax to encode CRS properties within netCDF files has previously been discussed under CF proposals #9 and #18. Although use of the WKT method wasn't endorsed at the time of those proposals, recently there have been increased expressions of interest on the CF mailing list to re-evaluate this method as an efficient - and non-disruptive - mechanism for specifying CRS's in more detail.
The origin of the WKT specification within the oil and gas exploration domain means that it primarily, though by no means exclusively, focussed on the specification of earth-centric horizontal coordinate systems. Consequently the WKT format may not provide the expressive power required, for example, to define some of the more specialised vertical coordinate systems utilised within the metocean domain. Nonetheless, for its principal domain of application - horizontal coordinate systems - it is believed to represent the best available encoding mechanism.
It is acknowledged that there will be occasions when CRS property values will be duplicated in both the new compound crs_wkt attribute and in single-property CF grid mapping attributes. In such cases the onus is on data producers, or software tools, to ensure that the property values are internally consistent. However, in situations where two values of a given property are different, then the value specified by the single-property CF attribute will take precedence.
For example, if the semi-major axis length of the ellipsoid is defined by the CF grid mapping attribute semi_major_axis and also by the crs_wkt attribute (via the WKT SPHEROID[...] element), then the former, being the more specific attribute, takes precedence. Naturally if the two values are equal then no ambiguity arises.
While this potential for information duplication is undesirable, the alternative - defining a multitude of CF grid mapping attributes for all potential CRS properties - is considered to represent an even less attractive solution.
Example of CRS WKT Usage
The simplistic CDL example below illustrates how the crs_wkt attribute could be used to define the CRS for a dataset based upon the British National Grid (which is a flavour of transverse mercator projection). In this example line breaks have been inserted into the WKT value to aid legibility: in real-world netCDF files the value of the crs_wkt attribute may well be a single unbroken line of text.
Additional, possibly more realistic WKT examples are included in the document resources cited in the References section.
dimensions: x = 800 ; y = 600 ; time = 30 ; variables: double x(x) ; x:standard_name = "projection_x_coordinate" ; x:long_name = "British National Grid eastings" ; x:units = "m" ; double y(y) ; y:standard_name = "projection_y_coordinate" ; y:long_name = "British National Grid northings" ; y:units = "m" ; double time(time) ; ... double lat(y, x) ; ... double lon(y, x) ; ... // a data variable whose CRS definition is provided by the 'bng_crs' grid mapping variable float precip(time, y, x) ; precip:standard_name = "rainfall_amount" ; precip:coordinates = "lat lon" ; precip:grid_mapping = "bng_crs" ; ... // grid mapping variable containing a WKT definition of the British National Grid int bng_crs ; bng_crs:grid_mapping_name = "transverse_mercator" ; bng_crs:crs_wkt = "PROJCS ["OSGB 1936 / British National Grid", GEOGCS ["OSGB 1936", DATUM ["OSGB 1936", SPHEROID ["Airy 1830", 6377563.396, 299.3249646]], PRIMEM ["Greenwich", 0], UNIT ["degree", 0.0174532925199433]], PROJECTION ["Transverse Mercator"], PARAMETER ["False easting", 400000], PARAMETER ["False northing", -100000], PARAMETER ["Longitude of natural origin", -2.0], PARAMETER ["Latitude of natural origin", 49.0], PARAMETER ["Scale factor at natural origin", 0.9996012717], UNIT ["metre", 1.0]]" ; ...
Note: names of projection PARAMETERs in the example above follow the spelling of Coordinate Operation Parameters defined in the EPSG geodetic parameter registry. Different client applications might well use different parameter names: the current proposal does not seek to prescribe the content of the crs_wkt attribute for any particular application context.
4.2 Proposed Changes to the CF Conventions Document (Normative)
This proposal would require the following changes to the CF conventions document.
Addition of a new subsection 5.6.1 after Example 5.10
5.6.1. Use of the CRS Well-known Text Format
An optional grid mapping attribute called crs_wkt may be used to specify multiple coordinate system properties in so-called well-known text format (usually abbreviated to CRS WKT or OGC WKT). The CRS WKT format is widely recognised and used within the geoscience software community. As such it represents a versatile mechanism for encoding information about a variety of coordinate reference system parameters in a highly compact notational form.
The crs_wkt attribute should comprise a text string that conforms to the WKT syntax as specified in reference [OGC_CTS]. If desired the text string may contain embedded newline characters to aid human readability. However, any such characters are purely cosmetic and do not alter the meaning of the attribute value. It is envisaged that the value of the crs_wkt attribute typically will be a single line of text, one intended primarily for machine processing. Other than the requirement to be a valid WKT string, the CF convention does not prescribe the content of the crs_wkt attribute since it will necessarily be context-dependent.
The crs_wkt attribute is intended to act as a supplement to other single-property CF grid mapping attributes (as described in Appendix F); it is not intended to replace those attributes. Data producers (and software tools) could, in theory, omit the single-property grid mapping attributes solely in favour of the compound crs_wkt attribute. However, such practice could result in client software conforming to earlier versions of the CF conventions being unable to read a netCDF file configured in this way. Therefore, until client software evolves to support both methods, it is strongly recommended that the crs_wkt attribute be used as an adjunct to the existing set of grid mapping attributes.
There will be occasions when a given CRS property value is duplicated in both a single-property grid mapping attribute and the crs_wkt attribute. In such cases the onus is on data producers to ensure that the property values are consistent. However, in those situations where two values of a given property are different, then the value specified by the single-property attribute shall take precedence. For example, if the semi-major axis length of the ellipsoid is defined by the grid mapping attribute semi_major_axis and also by the crs_wkt attribute (via the WKT SPHEROID[...] element) then the former, being the more specific attribute, takes precedence. Naturally if the two values are equal then no ambiguity arises.
Likewise, in those cases where the value of a CRS WKT element should be used consistently across the CF-netCDF community (names of projections and projection parameters, for example) then, in the absence of an overriding CF-maintained list, the OGP/EPSG registry of geodetic parameters [OGP/EPSG] is considered to represent the definitive authority as regards CRS property names and values (it is noted that some examples in the published literature do not always adhere to the OGP/EPSG values).
Example 5.11 illustrates how the coordinate system properties specified via the crs grid mapping variable in Example 5.10 might be expressed using a crs_wkt attribute (it also represents a slightly modified version of the WKT example shown in section 7.4 of [OGC_CTS]). For brevity only the grid mapping variable is included in this example; all other elements are as per the earlier example. Names of projection PARAMETERs follow the spellings used in the EPSG geodetic parameter registry. Example 5.11 illustrates how certain WKT elements - all of which are optional - can be used to specify CRS properties not covered by existing CF grid mapping attributes, including:
- use of the TOWGS84 element to specify horizontal datum transformation parameters (to WGS 1984 datum)
- use of the VERT_DATUM element to specify vertical datum information
- use of additional PARAMETER elements (albeit not essential ones in this example) to define the location of the false origin of the projection
- use of AUTHORITY elements to specify object identifier codes assigned by an external authority, OGP/EPSG in this instance
Example 5.11. British National Grid + Newlyn Datum in CRS WKT format
... int crs ; crs:grid_mapping_name = "transverse_mercator" ; crs:crs_wkt = "COMPD_CS ["OSGB 1936 / British National Grid + ODN", PROJCS ["OSGB 1936 / British National Grid", GEOGCS ["OSGB 1936", DATUM ["OSGB 1936", SPHEROID ["Airy 1830", 6377563.396, 299.3249646], TOWGS84[375, -111, 431, 0, 0, 0, 0] ], PRIMEM ["Greenwich", 0], UNIT ["degree", 0.0174532925199433] ], PROJECTION ["Transverse Mercator"], PARAMETER ["False easting", 400000], PARAMETER ["False northing", -100000], PARAMETER ["Longitude of natural origin", -2.0], PARAMETER ["Latitude of natural origin", 49.0], PARAMETER ["Longitude of false origin", -7.556], PARAMETER ["Latitude of false origin", 49.766], PARAMETER ["Scale factor at natural origin", 0.9996012717], UNIT ["metre", 1.0], AUTHORITY ["EPSG", "27700"] ], VERT_CS ["Newlyn", VERT_DATUM ["Ordnance Datum Newlyn", 2005], UNIT ["metre", 1.0]", AXIS ["Gravity-related height", UP], AUTHORITY ["EPSG", "5701"] ]]" ; ...
Note: To enhance readability the WKT value has been split across multiple lines and embedded quotation marks (") left unescaped - in real netCDF files such characters would need to be escaped. The WKT specification in [OGC_CTS] appears to silent be as regards which character(s) may be used to delimit text-valued properties; however, since all the examples in that specification use quotation marks, the use of that particular delimiting character is mandated by the CF convention.
Insertion of an additional row into Table F.1
In Appendix F the following additional line entry should be inserted into Table F.1 at row 1.
crs_wkt S This optional attribute may be used to specify multiple coordinate system properties in well-known text (WKT) format. The syntax must conform to the WKT format as specified in reference [OGC_CTS]. Use of the crs_wkt attribute is described in section 5.6.1.
Additions to Bibliography
[OGC_CTS] OpenGIS Coordinate Transformation Service Implementation Specification. OGC document 01-009. 12 January 2001 (URL: http://www.opengeospatial.org/standards/ct)
- In Example 5.10, the final attribute should more accurately be scale_factor_at_central_meridian rather than scale_factor_at_projection_origin, since the scale factor applies to the entirety of the central meridian employed in the projection, not just the point of origin.
- The entry for grid_mapping_name in Table F.1 needs to be amended. The data type column should read 'S' not 'N'.
Changes to Conformance Document
The following conformance statement needs to be appended to the Requirements heading of section 5.6:
"If present, the crs_wkt attribute must be a text string conforming to the CRS WKT specification described in reference [OGC_CTS]."
5.1. The proposed new crs_wkt attribute will enable data producers and software developers to encode a richer set of CRS properties within netCDF files.
5.2. The crs_wkt attribute is entirely optional; its presence (or absence) will not render existing CF-compliant netCDF files non-compliant. Similarly, the presence of the crs_wkt attribute should not cause existing netCDF clients to fail - it should simply be ignored as with any other unrecognised attribute.
5.3. The CRS WKT format represents a compact notational format, one that has been in widespread use for many years within the geoscience software community. It is currently used by a number of commercial and open source software packages (e.g. GDAL, GeoAPI).
5.4. The CRS WKT format is both human-readable and amenable to machine-processing (its primary intent, of course). As such it complies with the customary requirement for CF metadata properties to be self-describing.
5.5. Use of the crs_wkt attribute obviates the need to devise numerous discrete CF attributes such as would be required to realise the complex conceptual model underpinning the CRS domain.
5.6. The CRS WKT format ! is maintained by the Open Geospatial Consortium (OGC), the world's leading independent body for commissioning and publishing geospatial standards (as such the notation is sometimes referred to as the OGC WKT format). The CRS WKT specification appears to be stable.
6. Status Quo
Data producers could - and anecdotal evidence suggests that they do - encode additional CRS properties in locally-devised netCDF attributes. Clearly this is undesirable as, over time, it will lead to a proliferation of parochial and incompatible implementations.
The author is aware of a number of data producers and software developers (both commercial and open source) that are currently using a similar approach to the one described in this proposal. Consequently, a chief aim of this proposal is to formalise this practice as part of the CF conventions.
! OpenGIS Coordinate Transformation Service Implementation Specification. OGC document 01-009 (link)
! OpenGIS Implementation Standard for Geographic Information - Simple feature access - Part 1: Common architecture. OGC document 06-103r4 (link)
! Well-known Text Wikipedia entry (link)
! GeoAPI description of WKT format (link)