From: Regina Obe Date: Mon, 30 May 2011 01:51:37 +0000 (+0000) Subject: Move Bborie's new cool stat functions into their own section. Add documentation... X-Git-Tag: 2.0.0alpha1~1529 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=ba770da84195d700e6c0dc8bcf7aef733e460467;p=postgis Move Bborie's new cool stat functions into their own section. Add documentation for st_valuecount -- more coming for other raster functions. macro replace hasnodata with exclude_nodata_value which hopefully will be clearer to everyone. The raster codebase needs to be changed to agree with new names (mostly for those utilizing named arguments in PostgreSQL 9.0+). In enhnced section --put a note that hasnodata was renamed to exclude_nodata_value. git-svn-id: http://svn.osgeo.org/postgis/trunk@7285 b70326c6-7e19-0410-871a-916f4a2858ee --- diff --git a/doc/reference_raster.xml b/doc/reference_raster.xml index 57ccf4bae..dddfb2162 100644 --- a/doc/reference_raster.xml +++ b/doc/reference_raster.xml @@ -865,70 +865,7 @@ FROM (SELECT rid, ST_MetaData(rast) As md Raster Accessors - - - ST_Count - Returns the number of pixels in a given band of a raster or raster coverage. If no band is specified defaults to band 1. If hasnodata is set to true, will also count pixels with no data. - - - - - - text ST_Count - raster rast - integer nband=1 - boolean hasnodata=true - - - text ST_Count - raster rast - boolean hasnodata - - - text ST_Count - text rastertable - text rastercolumn - integer nband=1 - boolean hasnodata=true - - - text ST_Count - text rastertable - text rastercolumn - boolean hasnodata - - - - - - Description - - Returns the number of pixels in a given band of a raster or raster coverage. If no band is specified nband defaults to 1. - If hasnodata is set to true, will also count pixels with no data. Set hasnodata to false to get only pixels with data - Availability: 2.0.0 - This currently does the opposite of what I just said. Will be fixed to agree with the documentation or the documentation will be fixed to agree with the behavior. - - - - Examples - - ---example will count all pixels not 249 and one will count all pixels. Note this behavior may be reversed -- -SELECT rid, ST_Count(ST_SetBandNoDataValue(rast,249)) As exclude_nodata, - ST_Count(ST_SetBandNoDataValue(rast,249),false) As include_nodata - FROM dummy_rast WHERE rid=2; - -rid | exclude_nodata | include_nodata ------+----------------+---------------- - 2 | 23 | 25 - - - - - See Also - - - + ST_GeoReference @@ -1635,8 +1572,7 @@ FROM dummy_rast; , , - - + ST_Width @@ -1943,7 +1879,7 @@ SELECT (bmd).* FROM (SELECT ST_BandMetaData(rast,generate_series(1,2)) As bmd FROM dummy_rast WHERE rid = 10) AS foo; --result -- - pixeltype | hasnodatavalue | nodatavalue | isoutdb | path + pixeltype | exclude_nodata_valuevalue | nodatavalue | isoutdb | path -----------+----------------+-------------+---------+------ 1BB | f | 0 | f | 4BUI | f | 0 | f | @@ -1991,7 +1927,7 @@ FROM (SELECT ST_MetaData(rast) As rmd Description Returns basic meta data about a raster band. Columns returned - pixeltype | hasnodatavalue | nodatavalue | isoutdb | path. + pixeltype | hasnodata | nodatavalue | isoutdb | path. @@ -2007,7 +1943,7 @@ FROM (SELECT ST_MetaData(rast) As rmd FROM (SELECT rid, ST_BandMetaData(rast,1) As md FROM dummy_rast WHERE rid=2) As foo; - rid | pixeltype | hasnodatavalue | nodatavalue | isoutdb | path + rid | pixeltype | hasnodata | nodatavalue | isoutdb | path -----+-----------+----------------+-------------+---------+------ 2 | 8BUI | t | 0 | f | @@ -2430,7 +2366,7 @@ WHERE rid=2; ST_Value - Returns the value of a given band in a given columnx, rowy pixel or at a particular geometric point. Band numbers start at 1 and assumed to be 1 if not specified. If hasnodata is set to true, then only non nodata pixels are considered. If hasnodata is not passed in then reads it from metadata of raster. + Returns the value of a given band in a given columnx, rowy pixel or at a particular geometric point. Band numbers start at 1 and assumed to be 1 if not specified. If exclude_nodata_value is set to false, then all pixels include nodata pixels are considered to intersect and return value. If exclude_nodata_value is not passed in then reads it from metadata of raster. @@ -2444,7 +2380,7 @@ WHERE rid=2; double precision ST_Value raster rast geometry pt - boolean hasnodata + boolean exclude_nodata_value double precision ST_Value @@ -2457,7 +2393,7 @@ WHERE rid=2; raster rast integer bandnum geometry pt - boolean hasnodata + boolean exclude_nodata_value double precision ST_Value @@ -2470,7 +2406,7 @@ WHERE rid=2; raster rast integer columnx integer rowy - boolean hasnodata + boolean exclude_nodata_value double precision ST_Value @@ -2485,7 +2421,7 @@ WHERE rid=2; integer bandnum integer columnx integer rowy - boolean hasnodata + boolean exclude_nodata_value @@ -2494,9 +2430,9 @@ WHERE rid=2; Description Returns the value of a given band in a given columnx, rowy pixel or at a given geometry point. Band numbers start at 1 and band is assumed to be 1 if not specified. - If hasnodata is set to true, then only non nodata pixels are considered. If hasnodata is set to false, then all pixels are considered. + If exclude_nodata_value is set to true, then only non nodata pixels are considered. If exclude_nodata_value is set to false, then all pixels are considered. - Enhanced: 2.0.0 hasnodata optional argument was added. + Enhanced: 2.0.0 exclude_nodata_value optional argument was added. @@ -3191,6 +3127,177 @@ select st_bandisnodata(rast, 1) from dummy_rast where rid = 1; -- Expected true + + Raster Band Statistics and Analytics + + + ST_Count + Returns the number of pixels in a given band of a raster or raster coverage. If no band is specified defaults to band 1. If exclude_nodata_value is set to true, will only count pixels that are not equal to the nodata value. + + + + + + bigint ST_Count + raster rast + integer nband=1 + boolean exclude_nodata_value=true + + + bigint ST_Count + raster rast + boolean exclude_nodata_value + + + bigint ST_Count + text rastertable + text rastercolumn + integer nband=1 + boolean exclude_nodata_value=true + + + bigint ST_Count + text rastertable + text rastercolumn + boolean exclude_nodata_value + + + + + + Description + + Returns the number of pixels in a given band of a raster or raster coverage. If no band is specified nband defaults to 1. + If exclude_nodata_value is set to true, will only count pixels with value not equal to the nodata value of the raster. Set exclude_nodata_value to false to get count all pixels + Availability: 2.0.0 + + + + Examples + + +--example will count all pixels not 249 and one will count all pixels. -- +SELECT rid, ST_Count(ST_SetBandNoDataValue(rast,249)) As exclude_nodata, + ST_Count(ST_SetBandNoDataValue(rast,249),false) As include_nodata + FROM dummy_rast WHERE rid=2; + +rid | exclude_nodata | include_nodata +-----+----------------+---------------- + 2 | 23 | 25 + + + + + See Also + + + + + + + ST_ValueCount + Returns a set of records containing a pixel band valuue and count of the number of pixels in a given band of a raster (or a raster coverage) that have a given set of values. If no band is specified defaults to band 1. BY default nodata value pixels are not counted. + and all other values in the pixel are output and pixel band values are rounded to the nearest integer. + + + + + + record ST_ValueCount + raster rast + integer nband=1 + boolean exclude_nodata_value=true + double precision[] searchvalues=NULL + double precision roundto=0 + double precision OUT value + double precision OUT count + + + record ST_ValueCount + text rastertable + text rastercolumn + integer nband=1 + boolean exclude_nodata_value=true + double precision[] searchvalues=NULL + double precision roundto=0 + double precision OUT value + double precision OUT count + + + + + + Description + + Returns the number of pixels in a given band of a raster or raster coverage. If no band is specified nband defaults to 1. + If exclude_nodata_value is set to true, will also count pixels with no data. Set exclude_nodata_value to false to get only pixels with data + Availability: 2.0.0 + This currently does the opposite of what I just said. Will be fixed to agree with the documentation or the documentation will be fixed to agree with the behavior. + + + + Examples + + +UPDATE dummy_rast SET rast = ST_SetBandNoDataValue(rast,249) WHERE rid=2; +--Example will count only pixels of band 1 that are not 249. -- + +SELECT (pvc).* +FROM (SELECT ST_ValueCount(rast) As pvc + FROM dummy_rast WHERE rid=2) As foo + ORDER BY (pvc).value; + + value | count +-------+------- + 250 | 2 + 251 | 1 + 252 | 2 + 253 | 6 + 254 | 12 + +-- Example will coount all pixels of band 1 including 249 -- +SELECT (pvc).* +FROM (SELECT ST_ValueCount(rast,1,false) As pvc + FROM dummy_rast WHERE rid=2) As foo + ORDER BY (pvc).value; + + value | count +-------+------- + 249 | 2 + 250 | 2 + 251 | 1 + 252 | 2 + 253 | 6 + 254 | 12 + +-- Example will count only non-nodata value pixels of band 2 +SELECT (pvc).* +FROM (SELECT ST_ValueCount(rast,2) As pvc + FROM dummy_rast WHERE rid=2) As foo + ORDER BY (pvc).value; + value | count +-------+------- + 78 | 1 + 79 | 1 + 88 | 1 + 89 | 1 + 96 | 1 + 97 | 1 + 98 | 1 + 99 | 2 + 112 | 2 +: + + + + + + See Also + , + + + + Raster Outputs @@ -4177,8 +4284,8 @@ a_rid | b_rid | overleft ST_Intersects - Returns TRUE if rast pixel in a band with non-nodata band value intersects - with a geometry/raster. If band is not specified it defaults to 1. If hasnodata is omitted, reads from band meta data. + If exclude_nodata_value is omitted returns TRUE only if rast pixel in a band with non-nodata band value intersects + with a geometry/raster. If band is not specified it defaults to 1. If exclude_nodata_value is set to false then nodata band values that intersect also return true. @@ -4246,7 +4353,7 @@ a_rid | b_rid | overleft boolean - hasnodata + exclude_nodata_value geometry @@ -4266,7 +4373,7 @@ a_rid | b_rid | overleft boolean - hasnodata + exclude_nodata_value @@ -4286,7 +4393,7 @@ a_rid | b_rid | overleft boolean - hasnodata + exclude_nodata_value @@ -4302,7 +4409,7 @@ a_rid | b_rid | overleft boolean - hasnodata + exclude_nodata_value geometry @@ -4316,7 +4423,7 @@ a_rid | b_rid | overleft Description Returns true if the geometry intersects with the raster. Nodata values are taken into account so that if the geometry intersects only with nodata values, the function returns false. - hasnodata may modify this behavior: if set to false, nodata value are not taken into account and the function returns true as soon as the geometry intersects with the convex hull of the raster. + exclude_nodata_value may modify this behavior: if set to false, nodata value are not taken into account and the function returns true as soon as the geometry intersects with the convex hull of the raster. This operand will make use of any indexes that may be available on the geometries / rasters. diff --git a/doc/xsl/postgis_aggs_mm.xml.xsl b/doc/xsl/postgis_aggs_mm.xml.xsl index ccad3016a..06a2baaa6 100644 --- a/doc/xsl/postgis_aggs_mm.xml.xsl +++ b/doc/xsl/postgis_aggs_mm.xml.xsl @@ -504,6 +504,7 @@ or some internal functions that were never documented. If you are using a function that you don't see documented, it's probably deprecated, about to be deprecated, or internal and should be avoided. If you have applications or tools that rely on deprecated functions, please refer to for more details. + The arguments hasnodata was replaced with exclude_nodata_value which has the same meaning as the older hasnodata but clearer in purpose.