= NetCDF export made consistent with CF-1 for orientation, datums, map projections =

(Note: this is an initial draft by pds)

Status: Development

== Summary ==

In August 2011 Etienne Tourinsky initiated a discussion on the GDAL mailing list proposing and calling for interest in improvements to GDAL's NetCDF driver (Subject: discussion on improvements to the NetCDF driver and CF-1 convention), and collected ideas at wiki:NetCDF_Improvements.

This page summarises several of the proposed improvements that would improve the compatibility of GDAL's NetCDF driver with the CF-1 NetCDF conventions :- but change the default behaviour of the driver and thus affect backward compatibility.

The changes affect orientation of data, handling of datum parameters, writing coordinate variables, and are described specifically below.

== Rationale ==

The common rationale underlying these changes is:

(1) The NetCDF view of rasters created by GDAL should conform to CF-1 conventions :- and work for key operations with common NetCDF tools such as creating a WMS or WCS display from a NetCDF raster (eg displaying a WMS using ncWMS, or a WCS using Thredds Data Server).
  - If the user wishes to go against NetCDF conventions when exporting, they should use a -co option.
(2) Given (1), use CF-1 conventions for storing needed metadata where at all possible, but where necessary add extra metadata so the file can be readable back into GDAL with no loss of information or translation error. A specific example of this is named Datum and EPSG codes, which GDAL needs to supplement CF-1.
  - Again, if the user doesn't wish to supplement with GDAL metadata, then
(3) Given (2), when importing from NetCDF files, first read from CF-1 conventions, then read supplementary data from GDAL-added attributes. If the 2 conflict, report this and consider the CF-1 encoded info as authoritative, which assumes a user has modified the data with a non-GDAL program.  

== Planned Changes ==

=== Change to a default south-up orientation for NetCDF data ===

*Related tix*: ??
*Rationale*: CF-1's default orientation is south-up.
*New -co options*: ??



=== Continue saving NetCDF "spatial_ref" attribute by default, but add option not to save ===

*Related tix*:  
*New -co options*: -co WRITEGDALTAGS (yes/no, defaults to yes)
*Rationale*: We assume by default that if users export to a NetCDF file from GDAL, then they may wish to import into GDAL again and retain full information. Currently, the CF-1 convention doesn't allow saving all the projection information that GDAL can manipulate via a WKT (such as named Datums, and EPSG authorities).

However, there is certainly a use-case to export to a NetCDF file with no intention to access again via GDAL and use purely for use by CF-1 applications, in which case we don't need to save the added metadata.

=== When exporting to NetCDF map projections via GDAL, save projection coordinate variables. Optionally, also save lat and lon mapping variables. ===

*Related tix*: ??
*New -co options*: (Lat-lon)
*Rationale*:
X and Y needed as part of CF-1 conventions - and without them, files are not recognised as gridded data by the  NetCDF-Java API, and thus ncWMS, ToolsUI and TDS.
 They do not add a significant file-size overhead.
Similarly, 

Related issues:
 * South-up change on both import and export?
 * adding X and Y coords

== Compatibility Issues ==

== Test Suite ==

== Documentation ==

== Addenda ==

 * We also intend to improve interface for writing to NetCDF 4 - (but will handle this separately, may not need an RFC)