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