[postgis-devel] [PostGIS] #990: [raster] ST_ValueProportion

[PostGIS]

#990: [raster] ST_ValueProportion
----------------------------+-----------------------------------------------
 Reporter:  dustymugs       |       Owner:  pracine              
     Type:  task            |      Status:  new                  
 Priority:  medium          |   Milestone:  PostGIS Raster Future
Component:  postgis raster  |     Version:  trunk                
 Keywords:                  |  
----------------------------+-----------------------------------------------
 ST_ValueProportion is the sibling of ST_ValueCount and returns the
 percentage of a raster's band that is of a specified value. To handle
 floating point values, a rounding argument is provided.

 1. ST_ValueProportion(rast raster, nband integer, hasnodata boolean,
 search_value double precision, roundto double precision) -> double
 precision

     returns the percentage of the overall raster's bands pixel values that
 a specific pixel value occurs

     hasnodata: if FALSE, nodata values in band are considered in the
 count. if TRUE, nodata values are not considered

     value: the value to count in the raster

     roundto: the decimal position to round a pixel value to. Originally
 intended for use with 32BF and 64BF pixel types, it can also be used with
 integers when round to the tens, hundreds or higher place.

         examples are...

 {{{
         roundto < 0: no rounding

         0: no rounding

         0.1: round to the tenths place

         0.01: round to the hundredths place

         0.001: round to the thousandths place

         1: round to the ones place

         10: round to the tens place

         100: round to the hundreds place
 }}}

 {{{
 ST_ValueProportion(rast, 1, TRUE, 23, 0)

 ST_ValueProportion(rast, 5, FALSE, 3.14, 0.01)

 ST_ValueProportion(rast, 2, TRUE, 100, 100)

 ST_ValueProportion(rast, 1, FALSE, -9999, 1)
 }}}

 2. ST_ValueProportion(rast raster, nband integer, search_value double
 precision, roundto double precision) -> double precision

     hasnodata is assumed to be TRUE

 {{{
 ST_ValueProportion(rast, 5, 3.14, 0.01)

 ST_ValueProportion(rast, 2, 100, 100)
 }}}

 3. ST_ValueProportion(rast raster, nband integer, search_value double
 precision) -> double precision

     roundto is assumed to be 0, so no rounding takes place. hasnodata is
 assumed to be TRUE

 {{{
 ST_ValueProportion(rast, 1, -9999)
 }}}

 4. ST_ValueProportion(rast raster, search_value double precision, roundto
 double precision) -> double precision

     nband is assumed to be 1. hasnodata is assumed to be TRUE.

 5. ST_ValueProportion(rast raster, search_value double precision) ->
 double precision

     nband is assumed to be 1. roundto is assumed to be 0, so no rounding
 takes place. hasnodata is assumed to be TRUE.

 A set of variations where more than one value parameter can be provided
 should be added.

 To count/get proportion of all unique values in a raster's band, the
 search_value or search_values paramenter can be set to NULL.

-- 
Ticket URL: <http://trac.osgeo.org/postgis/ticket/990>
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.