[postgis-devel] [PostGIS] #934: [raster] ST_Histogram and ST_ApproxHistogram

[PostGIS]

#934: [raster] ST_Histogram and ST_ApproxHistogram
----------------------------+-----------------------------------------------
 Reporter:  dustymugs       |       Owner:  pracine              
     Type:  enhancement     |      Status:  new                  
 Priority:  medium          |   Milestone:  PostGIS Raster Future
Component:  postgis raster  |     Version:  trunk                
 Keywords:                  |  
----------------------------+-----------------------------------------------
 ST_Histogram and ST_ApproxHistogram provide methods to determine a
 raster's data distribution.

 ST_Histogram returns the data by absolute numbers while ST_ApproxHistogram
 returns the data by proportion due to the data used in ST_ApproxHistogram
 is a sample of the raster.

 The return of ST_Histogram and ST_ApproxHistogram is a set of records
 where each record is (min, max, count).

 ST_Histogram should have the following variations.

 1. ST_Histogram(rast raster, nband int, hasnodata boolean, bins int, width
 double precision[], right boolean) -> set of records

     returns set of records of three columns (bin min, bin max, bin count)

     nband: index of band to process on

     hasnodata: if FALSE, any pixel who's value is nodata is ignored.

     bins: the number of categories/bins to have in the histogram.  If NULL
 or value less than one, the number of categories will be auto-computed
 using Sturges' formula if the number of values >= 30 or Square-root choice
 if number of values < 30.

       http://en.wikipedia.org/wiki/Histogram#Mathematical_definition

     width: an array indicating the width of each category/bin.  If the
 number of bins is greater than the number of widths, the widths are
 repeated.  Example: 9 bins, widths are [a, b, c] will have the output be
 [a, b, c, a, b, c, a, b, c].

     right: compute the histogram from the right rather than from the left
 (default).  This changes the criteria for evaluating a value x from [a, b)
 to (a, b].

 {{{
 ST_Histogram(rast, 2, FALSE, NULL, NULL, FALSE)

 ST_Histogram(rast, 1, TRUE, 100, NULL, FALSE)

 ST_Histogram(rast, 2, FALSE, NULL, ARRAY[100, 50], FALSE)

 ST_Histogram(rast, 2, FALSE, 9, ARRAY[1000], TRUE)

 ST_Histogram(rast, 2, FALSE, 20, ARRAY[100, 200, 300], TRUE)
 }}}

 2. ST_Histogram(rast raster, nband int, hasnodata boolean, bins int, right
 boolean) -> set of records

   parameter "width" is not specified thus resulting in all bins having the
 same widths

 {{{
 ST_Histogram(rast, 2, FALSE, 5, FALSE)
 }}}

 3. ST_Histogram(rast raster, nband int, hasnodata boolean, bins int) ->
 set of records

   the parameter "right" is removed and assumed to be FALSE

 {{{
 ST_Histogram(rast, 2, FALSE, 5)
 }}}

 4. ST_Histogram(rast raster, nband int, hasnodata boolean) -> set of
 records

   the parameter "bins" is removed and set to NULL so that function can
 compute the number of bins to use

 5. ST_Histogram(rast raster, nband int) -> set of records

   parameter "hasnodata" is removed and assumed to be FALSE

 6. ST_Histogram(rast raster) -> set of records

   assumes that nband is 1.

 ST_ApproxHistogram should have the following variations.

 1. ST_ApproxHistogram(rast raster, nband int, hasnodata boolean,
 sample_percent double precision, bins int, width double precision[], right
 boolean) -> set of record

     sample_percent: a value between 0 and 1 indicating the percentage of
 the raster band's pixels to consider when generating the histogram.

 {{{
 ST_Histogram(rast, 2, FALSE, 0.1, NULL, NULL, FALSE)

 ST_Histogram(rast, 1, TRUE, 1, 100, NULL, FALSE)

 ST_Histogram(rast, 2, FALSE, 0.2, NULL, ARRAY[100, 50], FALSE)

 ST_Histogram(rast, 2, FALSE, 0.25, 9, ARRAY[1000], TRUE)

 ST_Histogram(rast, 2, FALSE, 0.05, 20, ARRAY[100, 200, 300], TRUE)
 }}}

 2. ST_ApproxHistogram(rast raster, nband int, hasnodata boolean,
 sample_percent double precision, bins int, right boolean) -> set of
 records

   parameter "width" is not specified thus resulting in all bins having the
 same widths

 3. ST_ApproxHistogram(rast raster, nband int, hasnodata boolean,
 sample_percent double precision, bins int) -> set of records

   the parameter "right" is removed and assumed to be FALSE

 {{{
 ST_ApproxHistogram(rast, 2, FALSE, 5)
 }}}

 4. ST_ApproxHistogram(rast raster, nband int, hasnodata boolean,
 sample_percent double precision) -> set of records

   the parameter "bins" is removed and set to NULL so that function can
 compute the number of bins to use

 5. ST_ApproxHistogram(rast raster, nband int, sample_percent double
 precision) -> set of records

   parameter "hasnodata" is removed and assumed to be FALSE

 6. ST_ApproxHistogram(rast raster, nband int) -> set of records

   assumes that sample_percent is 0.1

 7. ST_ApproxHistogram(rast raster, sample_percent double_precision) -> set
 of records

   assumes that nband is 1

 8. ST_ApproxHistogram(rast raster) -> set of records

   assumes that nband is 1 and sample_percent is 0.1

-- 
Ticket URL: <http://trac.osgeo.org/postgis/ticket/934>
PostGIS <http://trac.osgeo.org/postgis/>
The PostGIS Trac is used for bug, enhancement & task tracking, a user and developer wiki, and a view into the subversion code repository of PostGIS project.