1.. _rfc-57: 2 3======================================================================================= 4RFC 57: 64-bit bucket counts for histograms 5======================================================================================= 6 7Author: Even Rouault 8 9Contact: even dot rouault at spatialys dot com 10 11Status: Adopted, implemented 12 13Version: 2.0 14 15Summary 16------- 17 18This RFC modifies the GDALRasterBand GetHistogram(), 19GetDefaultHistogram() and SetDefaultHistogram() methods to accept arrays 20of 64-bit integer instead of the current arrays of 32-bit integer for 21bucket counts. It also changes GetRasterSampleOverview() to take a 2264-bit integer. This will fix issues when operating on large rasters 23that have more than 2 billion pixels. 24 25Core changes 26------------ 27 28The following methods of GDALRasterBand class are modified to take a 29GUIntBig\* argument for GetHistogram() and SetDefaultHistograph(), 30GUIntBig*\* for GetDefaultHistogram() and GUIntBig for 31GetRasterSampleOverview() 32 33:: 34 35 virtual CPLErr GetHistogram( double dfMin, double dfMax, 36 int nBuckets, GUIntBig * panHistogram, 37 int bIncludeOutOfRange, int bApproxOK, 38 GDALProgressFunc, void *pProgressData ); 39 40 virtual CPLErr GetDefaultHistogram( double *pdfMin, double *pdfMax, 41 int *pnBuckets, GUIntBig ** ppanHistogram, 42 int bForce, 43 GDALProgressFunc, void *pProgressData); 44 45 virtual CPLErr SetDefaultHistogram( double dfMin, double dfMax, 46 int nBuckets, GUIntBig *panHistogram ); 47 48 virtual GDALRasterBand *GetRasterSampleOverview( GUIntBig ); 49 50PAM serialization/deserialization is also updated. 51 52C API changes 53~~~~~~~~~~~~~ 54 55Only additions : 56 57:: 58 59 CPLErr CPL_DLL CPL_STDCALL GDALGetRasterHistogramEx( GDALRasterBandH hBand, 60 double dfMin, double dfMax, 61 int nBuckets, GUIntBig *panHistogram, 62 int bIncludeOutOfRange, int bApproxOK, 63 GDALProgressFunc pfnProgress, 64 void * pProgressData ); 65 66 CPLErr CPL_DLL CPL_STDCALL GDALGetDefaultHistogramEx( GDALRasterBandH hBand, 67 double *pdfMin, double *pdfMax, 68 int *pnBuckets, GUIntBig **ppanHistogram, 69 int bForce, 70 GDALProgressFunc pfnProgress, 71 void * pProgressData ); 72 73 CPLErr CPL_DLL CPL_STDCALL GDALSetDefaultHistogramEx( GDALRasterBandH hBand, 74 double dfMin, double dfMax, 75 int nBuckets, GUIntBig *panHistogram ); 76 77 GDALRasterBandH CPL_DLL CPL_STDCALL 78 GDALGetRasterSampleOverviewEx( GDALRasterBandH, GUIntBig ); 79 80The existing methods GDALGetRasterHistogram(), GDALGetDefaultHistogram() 81and GDALSetDefaultHistogram() are marked deprecated. They internally 82call the 64-bit methods, and, for GDALGetRasterHistogram() and 83GDALGetDefaultHistogram(), warn if a 32-bit overflow would occur, in 84which case the bucket count is set to INT_MAX. 85 86Changes in drivers 87------------------ 88 89All in-tree drivers that use/implement the C++ histogram methods are 90modified: ECW, VRT, MEM and HFA. 91 92Changes in utilities 93-------------------- 94 95gdalinfo and gdalenhance are modified to use the modified methods. 96 97Changes in SWIG bindings 98------------------------ 99 100For Python bindings only, RasterBand.GetHistogram(), 101GetDefaultHistogram() and SetDefaultHistogram() use the new 64-bit C 102functions. 103 104Other bindings could be updated, but likely need new typemaps for (int, 105GUIntBig*). In the meantime, they still use the 32-bit C functions. 106 107Compatibility 108------------- 109 110This modifies the C++ API and ABI. 111 112Out-of-tree drivers must make sure to take into account the updated C++ 113API if they implement some of the 4 modified virtual methods. 114 115Related ticket 116-------------- 117 118#5159 119 120Documentation 121------------- 122 123All new/modified methods/functions are documented. MIGRATION_GUIDE.TXT 124is updated with a new section for this RFC. 125 126Testing 127------- 128 129Setting/getting 64 bit values is tested in gcore/pam.y and 130gdrivers/mem.py 131 132Implementation 133-------------- 134 135Implementation will be done by Even Rouault 136(`Spatialys <http://spatialys.com>`__). 137 138The proposed implementation lies in the "histogram_64bit_count" branch 139of the 140`https://github.com/rouault/gdal2/tree/histogram_64bit_count <https://github.com/rouault/gdal2/tree/histogram_64bit_count>`__. 141 142The list of changes : 143`https://github.com/rouault/gdal2/compare/histogram_64bit_count <https://github.com/rouault/gdal2/compare/histogram_64bit_count>`__ 144 145Voting history 146-------------- 147 148+1 from DanielM, JukkaR and EvenR 149