1.. _rfc-33: 2 3================================================================================ 4RFC 33: GTiff - Fixing PixelIsPoint Interpretation 5================================================================================ 6 7Authors: Frank Warmerdam 8 9Contact: warmerdam@pobox.com 10 11Status: Adopted 12 13Summary 14------- 15 16This document proposes changes in the GDAL GTiff (GeoTIFF) driver's 17interpretation of PixelIsPoint when constructing the geotransform and 18interpreting control points. An RFC is used due to the fundamental role 19of GeoTIFF in GDAL and the GDAL user community and the risk for 20significant backward compatibility problems with this adjustment. 21 22Rationale 23--------- 24 25The GeoTIFF specification includes a data item, GTRasterTypeGeoKey, 26which may be set to either RasterPixelIsArea (the default), or 27RasterPixelIsPoint. RasterPixelIsArea defines that a pixel represents an 28area in the real world, while RasterPixelIsPoint defines a pixel to 29represent a point in the real world. Often this is useful to distinguish 30the behavior of optical sensors that average light values over an area 31vs. raster data which is point oriented like an elevation sample at a 32point. 33 34Traditionally GDAL has treated this flag as having no relevance to the 35georeferencing of the image despite disputes from a variety of other 36software developers and data producers. This was based on the authors 37interpretation of something said once by the GeoTIFF author. However, a 38recent review of section [`section 392.5.2.2 <http://www.remotesensing.org/geotiff/spec/geotiff2.5.html#2.5.2.2>`__] 40of the GeoTIFF specificaiton has made it clear that GDAL behavior is 41incorrect and that PixelIsPoint georeferencing needs to be offset by a 42half a pixel when transformed to the GDAL georeferencing model. This 43issue is documented in the following tickets including #3837, #3838, 44.... 45 46This RFC attempts to manage this transition with a minimum of disruption 47for the users of GDAL/OGR. 48 49Planned Changes 50--------------- 51 52Interpretation of the raster space from the GeoTIFF tie points will be 53offset by half a pixel in the PixelIsPoint case in 54gdal/frmts/gtiff/geotiff.cpp. This will impact the formation of the 55geotransform and the formation of GCPs when there are multiple tie 56points. geotransmatrix conversion to geotransform will also be affected. 57 58Conversely if writing files with PixelIsPoint (as driven by the 59"AREA_OR_POINT" metadata item being set to "POINT") the written raster 60space coordinates would be offset by half a pixel. 61 62In trunk the above behavior may be disabled by setting the 63GTIFF_POINT_GEO_IGNORE configuration option to TRUE (it will default to 64FALSE). 65 66In GDAL 1.7 and 1.6 branch the same changes will be applied, except the 67GTIFF_POINT_GEO_IGNORE configuration option will default to TRUE. 68 69Compatibility Issues 70-------------------- 71 72This change will alter the apparent georeferencing of all GeoTIFF files 73with PixelIsPoint set. It is not clear how large a proportion of GeoTIFF 74files this will apply to, but it is significant. This isn't too bad for 75files coming from non-GDAL sources as most other produces have made the 76correct interpretation of PixelIsPoint for years. However, 77unfortunately, files produced in the past by GDAL with PixelIsPoint will 78now be interpreted differently and the values will be off by half a 79pixel. 80 81In practice it was not particularly convenient or well documented how to 82produce PixelIsPoint GeoTIFF files with GDAL, so these files should be 83fairly rare. Thee easiest way to produce them was by copying from 84another PixelIsPoint GeoTIFF file in which the error on write just undid 85the error when reading the source GeoTIFF file. 86 87Reporting Extents 88----------------- 89 90Folks have at various points in the past requested that we report the 91extents differently for files with an AREA_OR_POINT value of POINT, much 92as listgeo does for GeoTIFF files that have a PixelIsPoint 93interpretation. I do *not* plan to do this, and for the purpose of GDAL 94the GCPs, RPCs and GeoTransform will always be based on an area 95interpretation of pixels. The AREA_OR_POINT will *only* be used to 96control setting of the PixelIsPoint value in GeoTIFF files, and as 97metadata about the physical interpretation of pixels. 98 99World Files 100----------- 101 102These changes will have no impact on how world files are treated or 103written. They are always based on the assumption of a area based pixel, 104but with the origin at the center of the top left pixel. This is 105effectively the same as the values for PixelIsPoint, but is not in any 106way tried to this metadata. 107 108Test Suite 109---------- 110 111The 1.6 and 1.7 branch test suites will not be altered. 112 113The trunk branch test suite will be altered to check for the updated 114values and will be extended with a test to confirm that setting the 115config option GTIFF_POINT_GEO_IGNORE to TRUE suppresses the altered 116behavior. 117 118Documentation 119------------- 120 121The situation will be noted in the 1.8.0, 1.7.4 and 1.6.4 release notes 122as well as in the GeoTIFF driver documentation in trunk. 123 124The GeoTIFF web site GeoTIFF FAQ will be updated to clarify the 125interpretation of PixelIsPoint and note that up to GDAL 1.8 it was 126improperly interpreted by GDAL. 127 128Implementation 129-------------- 130 131All code implementation will be by Frank Warmerdam in the next few 132weeks. 133 134Applied in trunk (r21158), 1.7 (r21159), 1.6 (r21160) and 1.6-esri 135(r21161). 136