1.. _rfc-58:
2
3=======================================================================================
4RFC 58: Removing Dataset Nodata Value
5=======================================================================================
6
7Authors: Sean Gillies
8
9Contact: sean at mapbox.com
10
11Status: Adopted, implemented
12
13Implementation version: 2.1
14
15Summary
16-------
17
18This RFC concerns addition of a ``DeleteNoDataValue()`` function to the
19C++ GDALRasterBand API. This function removes the nodata value of a
20raster band. When it succeeds, the raster band will have no nodata
21value. When it fails, the nodata value will be unchanged.
22
23Rationale
24---------
25
26The nodata value has accessors ``GetNoDataValue()`` and
27``SetNoDataValue()``. For GeoTIFFs, the value is stored in a
28TIFFTAG_GDAL_NODATA TIFF tag. Newly created GeoTIFF files can have no
29nodata value (no tag), but once a nodata value is set and stored it can
30only be given new values, it can not be removed. Nor can it be set to a
31value outside the range of the data type; for 8-bit data passing
32``nan``, ``-inf``, or ``256`` to ``GDALSetNoDataValue()`` has the same
33effect as passing 0.
34
35The problem with un-removable nodata values is this:
36
37-  Nodata masks (see GDAL RFC 15) can cover up a nodata value but if the
38   .msk file gets lost (and this is ever the problem with sidecar
39   files), the nodata value you were hiding is exposed again.
40-  Nodata masks are not available everywhere in GDAL, nodata values are
41   the only definition of valid data in some parts of GDAL.
42
43The current recommended practice for removing a nodata value is to copy
44the GeoTIFF using gdal_translate, specifying that the nodata tag not be
45copied over along with the data. By making the nodata value fully
46editable and removable we could avoid copying unnecessarily.
47
48Changes
49-------
50
51The ``virtual CPLErr DeleteNoDataValue()`` method will be added to the
52GDALRasterBand method in gdal_priv.h (C++ API), and
53``CPLErr GDALDeleteRasterNoDataValue()`` to gdal.h (C API)
54
55Updated drivers
56~~~~~~~~~~~~~~~
57
58The following drivers will be updated: GTiff, MEM, VRT and KEA.
59
60For GTiff, the TIFFTAG_GDAL_NODATA TIFF tag is unset if GDAL is built
61against libtiff 4.X, which is the appropriate behavior. For libtiff 3.X
62where TIFFUnsetField() does not exist, the tag is set to the empty
63string : GDAL 2.0 will detect that as the absence of a nodata value,
64older versions will parse it as 0.
65
66The ``GDALPamRasterBand`` class will also be updated (for drivers that
67have no built-in mechanism nodata mechanism and rely on .aux.xml
68sidecars). Note that this only removes the tag from the .aux.xml, so in
69the situation where a driver would have a internal way of storing
70nodata, but would be opened in read-only mode (so defaulting to PAM),
71DeleteNoData() would have no effect.
72
73SWIG bindings (Python / Java / C# / Perl) changes
74-------------------------------------------------
75
76The DeleteNoDataValue() method is added to the RasterBand object.
77
78Utilities
79---------
80
81The gdal_edit.py script is enhanced with a -unsetnodata option.
82
83Documentation
84-------------
85
86The new method and function are documented.
87
88Test Suite
89----------
90
91The tests of the updated drivers test the effect of the new method.
92
93Compatibility Issues
94--------------------
95
96None for the C API. ABI change for the C++ API because of introduction
97of a new virtual method.
98
99Related ticket
100--------------
101
102#2020 mentions the issue.
103
104Implementation
105--------------
106
107Implementation will be done by Even Rouault and be sponsored by Mapbox.
108
109A proposed implementation is available in
110`https://github.com/OSGeo/gdal/compare/trunk...rouault:rfc58_removing_nodata_value <https://github.com/OSGeo/gdal/compare/trunk...rouault:rfc58_removing_nodata_value>`__
111
112Voting history
113--------------
114
115+1 from EvenR, HowardB, DanielM and JukkaR
116