</sect2> <!-- /map algebra -->
- <sect2 id="Raster_Processing_DEM">
- <title>DEM (Elevation)</title>
+ <sect2 id="Raster_Processing_MapAlgebra_Callbacks">
+ <title>Built-in Map Algebra Callback Functions</title>
+
+ <refentry id="RT_ST_Min4ma">
+ <refnamediv>
+ <refname>ST_Min4ma</refname>
+ <refpurpose>
+ Raster processing function that calculates the minimum pixel value in a neighborhood.
+ </refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>float8 <function>ST_Min4ma</function></funcdef>
+ <paramdef><type>float8[][]</type> <parameter>matrix</parameter></paramdef>
+ <paramdef><type>text </type> <parameter>nodatamode</parameter></paramdef>
+ <paramdef><type>text[]</type> <parameter>VARIADIC args</parameter></paramdef>
+ </funcprototype>
- <refentry id="RT_ST_Aspect">
- <refnamediv>
- <refname>ST_Aspect</refname>
- <refpurpose>Returns the aspect (in degrees by default) of an elevation raster band. Useful for analyzing terrain.</refpurpose>
- </refnamediv>
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>raster <function>ST_Aspect</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
- <paramdef choice="opt"><type>integer </type> <parameter>band=1</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>pixeltype=32BF</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>units=DEGREES</parameter></paramdef>
- <paramdef choice="opt"><type>boolean </type> <parameter>interpolate_nodata=FALSE</parameter></paramdef>
- </funcprototype>
+ <funcprototype>
+ <funcdef>double precision <function>ST_Min4ma</function></funcdef>
+ <paramdef><type>double precision[][][]</type> <parameter>value</parameter></paramdef>
+ <paramdef><type>integer[][] </type> <parameter>pos</parameter></paramdef>
+ <paramdef><type>text[]</type> <parameter>VARIADIC userargs</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
- <funcprototype>
- <funcdef>raster <function>ST_Aspect</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
- <paramdef><type>integer </type> <parameter>band</parameter></paramdef>
- <paramdef><type>raster </type> <parameter>customextent</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>pixeltype=32BF</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>units=DEGREES</parameter></paramdef>
- <paramdef choice="opt"><type>boolean </type> <parameter>interpolate_nodata=FALSE</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
+ <refsection>
+ <title>Description</title>
- <para>Returns the aspect (in degrees by default) of an elevation raster band. Utilizes map algebra and applies the aspect equation to neighboring pixels.</para>
+ <para>
+ Calculate the minimum pixel value in a neighborhood of pixels.
+ </para>
- <varname>units</varname> indicates the units of the aspect. Possible values are: RADIANS, DEGREES (default).
- </para>
+ <para>
+ For Variant 2, a substitution value for NODATA pixels can be specified by passing that value to userargs.
+ </para>
+ <note>
<para>
- When <varname>units</varname> = RADIANS, values are between 0 and 2 * pi radians measured clockwise from North.
+ Variant 1 is a specialized callback function for use as a callback parameter to <xref linkend="RT_ST_MapAlgebraFctNgb" />.
</para>
+ </note>
+ <note>
<para>
- When <varname>units</varname> = DEGREES, values are between 0 and 360 degrees measured clockwise from North.
+ Variant 2 is a specialized callback function for use as a callback parameter to <xref linkend="RT_ST_MapAlgebra" />.
</para>
+ </note>
+ <warning>
<para>
- If slope of pixel is zero, aspect of pixel is -1.
+ Use of Variant 1 is discouraged since <xref linkend="RT_ST_MapAlgebraFctNgb" /> has been deprecated as of 2.1.0.
</para>
+ </warning>
- <note>
- <para>
- For more information about Slope, Aspect and Hillshade, please refer to <ulink url="http://webhelp.esri.com/arcgisdesktop/9.3/index.cfm?TopicName=How%20Hillshade%20works">ESRI - How hillshade works</ulink> and <ulink url="http://geospatial.intergraph.com/fieldguide/wwhelp/wwhimpl/common/html/wwhelp.htm?context=FieldGuide&file=Aspect_Images.html">ERDAS Field Guide - Aspect Images</ulink>.
- </para>
- </note>
+ <para>Availability: 2.0.0</para>
+ <para>Enhanced: 2.1.0 Addition of Variant 2</para>
+ </refsection>
- <para>Availability: 2.0.0 </para>
- <para>Enhanced: 2.1.0 Uses ST_MapAlgebra() and added optional <varname>interpolate_nodata</varname> function parameter</para>
- <para>Changed: 2.1.0 In prior versions, return values were in radians. Now, return values default to degrees</para>
- </refsection>
-
- <refsection>
- <title>Examples: Variant 1</title>
- <programlisting>
-WITH foo AS (
- SELECT ST_SetValues(
- ST_AddBand(ST_MakeEmptyRaster(5, 5, 0, 0, 1, -1, 0, 0, 0), 1, '32BF', 0, -9999),
- 1, 1, 1, ARRAY[
- [1, 1, 1, 1, 1],
- [1, 2, 2, 2, 1],
- [1, 2, 3, 2, 1],
- [1, 2, 2, 2, 1],
- [1, 1, 1, 1, 1]
- ]::double precision[][]
- ) AS rast
-)
-SELECT
- ST_DumpValues(ST_Aspect(rast, 1, '32BF'))
-FROM foo
+ <refsection>
+ <title>Examples</title>
- st_dumpvalues
-
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-----------------------------------
- (1,"{{315,341.565063476562,0,18.4349479675293,45},{288.434936523438,315,0,45,71.5650482177734},{270,270,-1,90,90},{251.565048217773,225,180,135,108.434951782227},{225,198.43495178
-2227,180,161.565048217773,135}}")
+ <programlisting>
+SELECT
+ rid,
+ st_value(
+ st_mapalgebrafctngb(rast, 1, NULL, 1, 1, 'st_min4ma(float[][],text,text[])'::regprocedure, 'ignore', NULL), 2, 2
+ )
+FROM dummy_rast
+WHERE rid = 2;
+ rid | st_value
+-----+----------
+ 2 | 250
(1 row)
- </programlisting>
- </refsection>
+ </programlisting>
+ </refsection>
+
+ <refsection>
+ <title>See Also</title>
+ <para>
+ <xref linkend="RT_ST_MapAlgebraFctNgb" />,
+ <xref linkend="RT_ST_MapAlgebra" />,
+ <xref linkend="RT_ST_Max4ma" />,
+ <xref linkend="RT_ST_Sum4ma" />,
+ <xref linkend="RT_ST_Mean4ma" />,
+ <xref linkend="RT_ST_Range4ma" />,
+ <xref linkend="RT_ST_Distinct4ma" />,
+ <xref linkend="RT_ST_StdDev4ma" />
+ </para>
+ </refsection>
+ </refentry>
- <refsection>
- <title>Examples: Variant 2</title>
+ <refentry id="RT_ST_Max4ma">
+ <refnamediv>
+ <refname>ST_Max4ma</refname>
+ <refpurpose>Raster processing function that calculates the maximum pixel value in a neighborhood.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>float8 <function>ST_Max4ma</function></funcdef>
+ <paramdef><type>float8[][]</type> <parameter>matrix</parameter></paramdef>
+ <paramdef><type>text</type> <parameter>nodatamode</parameter></paramdef>
+ <paramdef><type>text[]</type> <parameter>VARIADIC args</parameter></paramdef>
+ </funcprototype>
- <para>Complete example of tiles of a coverage. This query only works with PostgreSQL 9.1 or higher.</para>
+ <funcprototype>
+ <funcdef>double precision <function>ST_Max4ma</function></funcdef>
+ <paramdef><type>double precision[][][]</type> <parameter>value</parameter></paramdef>
+ <paramdef><type>integer[][] </type> <parameter>pos</parameter></paramdef>
+ <paramdef><type>text[]</type> <parameter>VARIADIC userargs</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
- <programlisting>
-WITH foo AS (
- SELECT ST_Tile(
- ST_SetValues(
- ST_AddBand(
- ST_MakeEmptyRaster(6, 6, 0, 0, 1, -1, 0, 0, 0),
- 1, '32BF', 0, -9999
- ),
- 1, 1, 1, ARRAY[
- [1, 1, 1, 1, 1, 1],
- [1, 1, 1, 1, 2, 1],
- [1, 2, 2, 3, 3, 1],
- [1, 1, 3, 2, 1, 1],
- [1, 2, 2, 1, 2, 1],
- [1, 1, 1, 1, 1, 1]
- ]::double precision[]
- ),
- 2, 2
- ) AS rast
-)
-SELECT
- t1.rast,
- ST_Aspect(ST_Union(t2.rast), 1, t1.rast)
-FROM foo t1
-CROSS JOIN foo t2
-WHERE ST_Intersects(t1.rast, t2.rast)
-GROUP BY t1.rast;
- </programlisting>
- </refsection>
+ <para>Calculate the maximum pixel value in a neighborhood of pixels.</para>
+
+ <para>
+ For Variant 2, a substitution value for NODATA pixels can be specified by passing that value to userargs.
+ </para>
- <refsection>
- <title>See Also</title>
+ <note>
+ <para>Variant 1 is a specialized callback function for use as a callback parameter to <xref linkend="RT_ST_MapAlgebraFctNgb" />.</para>
+ </note>
+
+ <note>
<para>
- <xref linkend="RT_ST_MapAlgebra" />,
- <xref linkend="RT_ST_TRI" />,
- <xref linkend="RT_ST_TPI" />,
- <xref linkend="RT_ST_Roughness" />,
- <xref linkend="RT_ST_HillShade" />,
- <xref linkend="RT_ST_Slope" />
+ Variant 2 is a specialized callback function for use as a callback parameter to <xref linkend="RT_ST_MapAlgebra" />.
</para>
- </refsection>
- </refentry>
+ </note>
- <refentry id="RT_ST_HillShade">
- <refnamediv>
- <refname>ST_HillShade</refname>
- <refpurpose>Returns the hypothetical illumination of an elevation raster band using provided azimuth, altitude, brightness and scale inputs.</refpurpose>
- </refnamediv>
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>raster <function>ST_HillShade</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
- <paramdef choice="opt"><type>integer </type> <parameter>band=1</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>pixeltype=32BF</parameter></paramdef>
- <paramdef choice="opt"><type>double precision </type> <parameter>azimuth=315</parameter></paramdef>
- <paramdef choice="opt"><type>double precision </type> <parameter>altitude=45</parameter></paramdef>
- <paramdef choice="opt"><type>double precision </type> <parameter>max_bright=255</parameter></paramdef>
- <paramdef choice="opt"><type>double precision </type> <parameter>scale=1.0</parameter></paramdef>
- <paramdef choice="opt"><type>boolean </type> <parameter>interpolate_nodata=FALSE</parameter></paramdef>
- </funcprototype>
+ <warning>
+ <para>
+ Use of Variant 1 is discouraged since <xref linkend="RT_ST_MapAlgebraFctNgb" /> has been deprecated as of 2.1.0.
+ </para>
+ </warning>
- <funcprototype>
- <funcdef>raster <function>ST_HillShade</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
- <paramdef><type>integer </type> <parameter>band</parameter></paramdef>
- <paramdef><type>raster </type> <parameter>customextent</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>pixeltype=32BF</parameter></paramdef>
- <paramdef choice="opt"><type>double precision </type> <parameter>azimuth=315</parameter></paramdef>
- <paramdef choice="opt"><type>double precision </type> <parameter>altitude=45</parameter></paramdef>
- <paramdef choice="opt"><type>double precision </type> <parameter>max_bright=255</parameter></paramdef>
- <paramdef choice="opt"><type>double precision </type> <parameter>scale=1.0</parameter></paramdef>
- <paramdef choice="opt"><type>boolean </type> <parameter>interpolate_nodata=FALSE</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
+ <para>Availability: 2.0.0</para>
+ <para>Enhanced: 2.1.0 Addition of Variant 2</para>
+ </refsection>
+
<refsection>
- <title>Description</title>
+ <title>Examples</title>
- <para>Returns the hypothetical illumination of an elevation raster band using the azimuth, altitude, brightness, and scale inputs. Utilizes map algebra and applies the hill shade equation to neighboring pixels. Return pixel values are between 0 and 255.</para>
+ <programlisting>SELECT
+ rid,
+ st_value(
+ st_mapalgebrafctngb(rast, 1, NULL, 1, 1, 'st_max4ma(float[][],text,text[])'::regprocedure, 'ignore', NULL), 2, 2
+ )
+FROM dummy_rast
+WHERE rid = 2;
+ rid | st_value
+-----+----------
+ 2 | 254
+(1 row)
+ </programlisting>
+
+ </refsection>
+
+ <refsection>
+ <title>See Also</title>
+ <para>
+ <xref linkend="RT_ST_MapAlgebraFctNgb" />,
+ <xref linkend="RT_ST_MapAlgebra" />,
+ <xref linkend="RT_ST_Min4ma" />,
+ <xref linkend="RT_ST_Sum4ma" />,
+ <xref linkend="RT_ST_Mean4ma" />,
+ <xref linkend="RT_ST_Range4ma" />,
+ <xref linkend="RT_ST_Distinct4ma" />,
+ <xref linkend="RT_ST_StdDev4ma" />
+ </para>
+ </refsection>
+ </refentry>
- <para>
- <varname>azimuth</varname> is a value between 0 and 360 degrees measured clockwise from North.
- </para>
+ <refentry id="RT_ST_Sum4ma">
+ <refnamediv>
+ <refname>ST_Sum4ma</refname>
+ <refpurpose>Raster processing function that calculates the sum of all pixel values in a neighborhood.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>float8 <function>ST_Sum4ma</function></funcdef>
+ <paramdef><type>float8[][]</type> <parameter>matrix</parameter></paramdef>
+ <paramdef><type>text</type> <parameter>nodatamode</parameter></paramdef>
+ <paramdef><type>text[]</type> <parameter>VARIADIC args</parameter></paramdef>
+ </funcprototype>
- <para>
- <varname>altitude</varname> is a value between 0 and 90 degrees where 0 degrees is at the horizon and 90 degrees is directly overhead.
- </para>
+ <funcprototype>
+ <funcdef>double precision <function>ST_Sum4ma</function></funcdef>
+ <paramdef><type>double precision[][][]</type> <parameter>value</parameter></paramdef>
+ <paramdef><type>integer[][] </type> <parameter>pos</parameter></paramdef>
+ <paramdef><type>text[]</type> <parameter>VARIADIC userargs</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
- <para>
- <varname>max_bright</varname> is a value between 0 and 255 with 0 as no brightness and 255 as max brightness.
- </para>
+ <para>Calculate the sum of all pixel values in a neighborhood of pixels.</para>
+
+ <para>
+ For Variant 2, a substitution value for NODATA pixels can be specified by passing that value to userargs.
+ </para>
+
+ <note>
+ <para>Variant 1 is a specialized callback function for use as a callback parameter to <xref linkend="RT_ST_MapAlgebraFctNgb" />.</para>
+ </note>
+ <note>
<para>
- <varname>scale</varname> is the ratio of vertical units to horizontal. For Feet:LatLon use scale=370400, for Meters:LatLon use scale=111120.
+ Variant 2 is a specialized callback function for use as a callback parameter to <xref linkend="RT_ST_MapAlgebra" />.
</para>
+ </note>
+ <warning>
<para>
- If <varname>interpolate_nodata</varname> is TRUE, values for NODATA pixels from the input raster will be interpolated using <xref linkend="RT_ST_InvDistWeight4ma" /> before computing the hillshade illumination.
+ Use of Variant 1 is discouraged since <xref linkend="RT_ST_MapAlgebraFctNgb" /> has been deprecated as of 2.1.0.
</para>
+ </warning>
- <note>
- <para>
- For more information about Hillshade, please refer to <ulink url="http://webhelp.esri.com/arcgisdesktop/9.3/index.cfm?TopicName=How%20Hillshade%20works">How hillshade works</ulink>.
- </para>
- </note>
-
- <para>Availability: 2.0.0 </para>
- <para>Enhanced: 2.1.0 Uses ST_MapAlgebra() and added optional <varname>interpolate_nodata</varname> function parameter</para>
- <para>Changed: 2.1.0 In prior versions, azimuth and altitude were expressed in radians. Now, azimuth and altitude are expressed in degrees</para>
-
- </refsection>
+ <para>Availability: 2.0.0</para>
+ <para>Enhanced: 2.1.0 Addition of Variant 2</para>
+ </refsection>
<refsection>
- <title>Examples: Variant 1</title>
- <programlisting>
-WITH foo AS (
- SELECT ST_SetValues(
- ST_AddBand(ST_MakeEmptyRaster(5, 5, 0, 0, 1, -1, 0, 0, 0), 1, '32BF', 0, -9999),
- 1, 1, 1, ARRAY[
- [1, 1, 1, 1, 1],
- [1, 2, 2, 2, 1],
- [1, 2, 3, 2, 1],
- [1, 2, 2, 2, 1],
- [1, 1, 1, 1, 1]
- ]::double precision[][]
- ) AS rast
-)
-SELECT
- ST_DumpValues(ST_Hillshade(rast, 1, '32BF'))
-FROM foo
-
- st_dumpvalues
-
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
------------------------------------------------------------------------
- (1,"{{NULL,NULL,NULL,NULL,NULL},{NULL,251.32763671875,220.749786376953,147.224319458008,NULL},{NULL,220.749786376953,180.312225341797,67.7497863769531,NULL},{NULL,147.224319458008
-,67.7497863769531,43.1210060119629,NULL},{NULL,NULL,NULL,NULL,NULL}}")
+ <title>Examples</title>
+
+ <programlisting>SELECT
+ rid,
+ st_value(
+ st_mapalgebrafctngb(rast, 1, '32BF', 1, 1, 'st_sum4ma(float[][],text,text[])'::regprocedure, 'ignore', NULL), 2, 2
+ )
+FROM dummy_rast
+WHERE rid = 2;
+ rid | st_value
+-----+----------
+ 2 | 2279
(1 row)
- </programlisting>
- </refsection>
+ </programlisting>
+
+ </refsection>
+
+ <refsection>
+ <title>See Also</title>
+ <para>
+ <xref linkend="RT_ST_MapAlgebraFctNgb" />,
+ <xref linkend="RT_ST_MapAlgebra" />,
+ <xref linkend="RT_ST_Min4ma" />,
+ <xref linkend="RT_ST_Max4ma" />,
+ <xref linkend="RT_ST_Mean4ma" />,
+ <xref linkend="RT_ST_Range4ma" />,
+ <xref linkend="RT_ST_Distinct4ma" />,
+ <xref linkend="RT_ST_StdDev4ma" />
+ </para>
+ </refsection>
+ </refentry>
- <refsection>
- <title>Examples: Variant 2</title>
+ <refentry id="RT_ST_Mean4ma">
+ <refnamediv>
+ <refname>ST_Mean4ma</refname>
+ <refpurpose>Raster processing function that calculates the mean pixel value in a neighborhood.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>float8 <function>ST_Mean4ma</function></funcdef>
+ <paramdef><type>float8[][]</type> <parameter>matrix</parameter></paramdef>
+ <paramdef><type>text</type> <parameter>nodatamode</parameter></paramdef>
+ <paramdef><type>text[]</type> <parameter>VARIADIC args</parameter></paramdef>
+ </funcprototype>
- <para>Complete example of tiles of a coverage. This query only works with PostgreSQL 9.1 or higher.</para>
+ <funcprototype>
+ <funcdef>double precision <function>ST_Mean4ma</function></funcdef>
+ <paramdef><type>double precision[][][]</type> <parameter>value</parameter></paramdef>
+ <paramdef><type>integer[][] </type> <parameter>pos</parameter></paramdef>
+ <paramdef><type>text[]</type> <parameter>VARIADIC userargs</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
- <programlisting>
-WITH foo AS (
- SELECT ST_Tile(
- ST_SetValues(
- ST_AddBand(
- ST_MakeEmptyRaster(6, 6, 0, 0, 1, -1, 0, 0, 0),
- 1, '32BF', 0, -9999
- ),
- 1, 1, 1, ARRAY[
- [1, 1, 1, 1, 1, 1],
- [1, 1, 1, 1, 2, 1],
- [1, 2, 2, 3, 3, 1],
- [1, 1, 3, 2, 1, 1],
- [1, 2, 2, 1, 2, 1],
- [1, 1, 1, 1, 1, 1]
- ]::double precision[]
- ),
- 2, 2
- ) AS rast
-)
-SELECT
- t1.rast,
- ST_Hillshade(ST_Union(t2.rast), 1, t1.rast)
-FROM foo t1
-CROSS JOIN foo t2
-WHERE ST_Intersects(t1.rast, t2.rast)
-GROUP BY t1.rast;
- </programlisting>
- </refsection>
+ <para>Calculate the mean pixel value in a neighborhood of pixels.</para>
+
+ <para>
+ For Variant 2, a substitution value for NODATA pixels can be specified by passing that value to userargs.
+ </para>
- <refsection>
- <title>See Also</title>
+ <note>
+ <para>Variant 1 is a specialized callback function for use as a callback parameter to <xref linkend="RT_ST_MapAlgebraFctNgb" />.</para>
+ </note>
+
+ <note>
<para>
- <xref linkend="RT_ST_MapAlgebra" />,
- <xref linkend="RT_ST_TRI" />,
- <xref linkend="RT_ST_TPI" />,
- <xref linkend="RT_ST_Roughness" />,
- <xref linkend="RT_ST_Aspect" />,
- <xref linkend="RT_ST_Slope" />
+ Variant 2 is a specialized callback function for use as a callback parameter to <xref linkend="RT_ST_MapAlgebra" />.
</para>
- </refsection>
- </refentry>
+ </note>
- <refentry id="RT_ST_Roughness">
- <refnamediv>
- <refname>ST_Roughness</refname>
- <refpurpose>Returns a raster with the calculated "roughness" of a DEM.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>raster <function>ST_Roughness</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
- <paramdef><type>integer </type> <parameter>nband</parameter></paramdef>
- <paramdef><type>raster </type> <parameter>customextent</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>pixeltype="32BF"</parameter> </paramdef>
- <paramdef choice="opt"><type>boolean </type> <parameter> interpolate_nodata=FALSE </parameter> </paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
- <para>Calculates the "roughness" of a DEM, by subtracting the maximum from the minimum for a given area.</para>
- <para>Availability: 2.1.0</para>
- </refsection>
+ <warning>
+ <para>
+ Use of Variant 1 is discouraged since <xref linkend="RT_ST_MapAlgebraFctNgb" /> has been deprecated as of 2.1.0.
+ </para>
+ </warning>
+ <para>Availability: 2.0.0</para>
+ <para>Enhanced: 2.1.0 Addition of Variant 2</para>
+ </refsection>
+
<refsection>
<title>Examples</title>
- <programlisting>
--- needs examples
- </programlisting>
- </refsection>
-
- <refsection>
- <title>See Also</title>
- <para>
- <xref linkend="RT_ST_MapAlgebra" />,
- <xref linkend="RT_ST_TRI" />,
- <xref linkend="RT_ST_TPI" />,
- <xref linkend="RT_ST_Slope" />,
- <xref linkend="RT_ST_HillShade" />,
- <xref linkend="RT_ST_Aspect" />
- </para>
- </refsection>
- </refentry>
+
+ <programlisting>SELECT
+ rid,
+ st_value(
+ st_mapalgebrafctngb(rast, 1, '32BF', 1, 1, 'st_mean4ma(float[][],text,text[])'::regprocedure, 'ignore', NULL), 2, 2
+ )
+FROM dummy_rast
+WHERE rid = 2;
+ rid | st_value
+-----+------------------
+ 2 | 253.222229003906
+(1 row)
+ </programlisting>
+
+ </refsection>
+
+ <refsection>
+ <title>See Also</title>
+ <para>
+ <xref linkend="RT_ST_MapAlgebraFctNgb" />,
+ <xref linkend="RT_ST_MapAlgebra" />,
+ <xref linkend="RT_ST_Min4ma" />,
+ <xref linkend="RT_ST_Max4ma" />,
+ <xref linkend="RT_ST_Sum4ma" />,
+ <xref linkend="RT_ST_Range4ma" />,
+ <xref linkend="RT_ST_StdDev4ma" />
+ </para>
+ </refsection>
+ </refentry>
- <refentry id="RT_ST_Slope">
- <refnamediv>
- <refname>ST_Slope</refname>
- <refpurpose>Returns the slope (in degrees by default) of an elevation raster band. Useful for analyzing terrain.</refpurpose>
- </refnamediv>
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>raster <function>ST_Slope</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
- <paramdef choice="opt"><type>integer </type> <parameter>nband=1</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>pixeltype=32BF</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>units=DEGREES</parameter></paramdef>
- <paramdef choice="opt"><type>double precision </type> <parameter>scale=1.0</parameter></paramdef>
- <paramdef choice="opt"><type>boolean </type> <parameter>interpolate_nodata=FALSE</parameter></paramdef>
- </funcprototype>
+ <refentry id="RT_ST_Range4ma">
+ <refnamediv>
+ <refname>ST_Range4ma</refname>
+ <refpurpose>Raster processing function that calculates the range of pixel values in a neighborhood.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>float8 <function>ST_Range4ma</function></funcdef>
+ <paramdef><type>float8[][]</type> <parameter>matrix</parameter></paramdef>
+ <paramdef><type>text</type> <parameter>nodatamode</parameter></paramdef>
+ <paramdef><type>text[]</type> <parameter>VARIADIC args</parameter></paramdef>
+ </funcprototype>
- <funcprototype>
- <funcdef>raster <function>ST_Slope</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
- <paramdef><type>integer </type> <parameter>nband</parameter></paramdef>
- <paramdef><type>raster </type> <parameter>customextent</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>pixeltype=32BF</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>units=DEGREES</parameter></paramdef>
- <paramdef choice="opt"><type>double precision </type> <parameter>scale=1.0</parameter></paramdef>
- <paramdef choice="opt"><type>boolean </type> <parameter>interpolate_nodata=FALSE</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
+ <funcprototype>
+ <funcdef>double precision <function>ST_Range4ma</function></funcdef>
+ <paramdef><type>double precision[][][]</type> <parameter>value</parameter></paramdef>
+ <paramdef><type>integer[][] </type> <parameter>pos</parameter></paramdef>
+ <paramdef><type>text[]</type> <parameter>VARIADIC userargs</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
- <refsection>
- <title>Description</title>
-
- <para>Returns the slope (in degrees by default) of an elevation raster band. Utilizes map algebra and applies the slope equation to neighboring pixels.</para>
+ <refsection>
+ <title>Description</title>
- <para>
- <varname>units</varname> indicates the units of the slope. Possible values are: RADIANS, DEGREES (default), PERCENT.
- </para>
+ <para>Calculate the range of pixel values in a neighborhood of pixels.</para>
+
+ <para>
+ For Variant 2, a substitution value for NODATA pixels can be specified by passing that value to userargs.
+ </para>
+
+ <note>
+ <para>Variant 1 is a specialized callback function for use as a callback parameter to <xref linkend="RT_ST_MapAlgebraFctNgb" />.</para>
+ </note>
+ <note>
<para>
- <varname>scale</varname> is the ratio of vertical units to horizontal. For Feet:LatLon use scale=370400, for Meters:LatLon use scale=111120.
+ Variant 2 is a specialized callback function for use as a callback parameter to <xref linkend="RT_ST_MapAlgebra" />.
</para>
+ </note>
+ <warning>
<para>
- If <varname>interpolate_nodata</varname> is TRUE, values for NODATA pixels from the input raster will be interpolated using <xref linkend="RT_ST_InvDistWeight4ma" /> before computing the surface slope.
+ Use of Variant 1 is discouraged since <xref linkend="RT_ST_MapAlgebraFctNgb" /> has been deprecated as of 2.1.0.
</para>
+ </warning>
- <note>
- <para>
- For more information about Slope, Aspect and Hillshade, please refer to <ulink url="http://webhelp.esri.com/arcgisdesktop/9.3/index.cfm?TopicName=How%20Hillshade%20works">ESRI - How hillshade works</ulink> and <ulink url="http://geospatial.intergraph.com/fieldguide/wwhelp/wwhimpl/common/html/wwhelp.htm?context=FieldGuide&file=Slope_Images.html">ERDAS Field Guide - Slope Images</ulink>.
- </para>
- </note>
-
- <para>Availability: 2.0.0 </para>
- <para>Enhanced: 2.1.0 Uses ST_MapAlgebra() and added optional <varname>units</varname>, <varname>scale</varname>, <varname>interpolate_nodata</varname> function parameters</para>
- <para>Changed: 2.1.0 In prior versions, return values were in radians. Now, return values default to degrees</para>
-
- </refsection>
+ <para>Availability: 2.0.0</para>
+ <para>Enhanced: 2.1.0 Addition of Variant 2</para>
+ </refsection>
<refsection>
- <title>Examples: Variant 1</title>
- <programlisting>
-WITH foo AS (
- SELECT ST_SetValues(
- ST_AddBand(ST_MakeEmptyRaster(5, 5, 0, 0, 1, -1, 0, 0, 0), 1, '32BF', 0, -9999),
- 1, 1, 1, ARRAY[
- [1, 1, 1, 1, 1],
- [1, 2, 2, 2, 1],
- [1, 2, 3, 2, 1],
- [1, 2, 2, 2, 1],
- [1, 1, 1, 1, 1]
- ]::double precision[][]
- ) AS rast
-)
-SELECT
- ST_DumpValues(ST_Slope(rast, 1, '32BF'))
-FROM foo
-
- st_dumpvalues
-
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------
- (1,"{{10.0249881744385,21.5681285858154,26.5650520324707,21.5681285858154,10.0249881744385},{21.5681285858154,35.2643890380859,36.8698959350586,35.2643890380859,21.5681285858154},
-{26.5650520324707,36.8698959350586,0,36.8698959350586,26.5650520324707},{21.5681285858154,35.2643890380859,36.8698959350586,35.2643890380859,21.5681285858154},{10.0249881744385,21.
-5681285858154,26.5650520324707,21.5681285858154,10.0249881744385}}")
+ <title>Examples</title>
+
+ <programlisting>SELECT
+ rid,
+ st_value(
+ st_mapalgebrafctngb(rast, 1, NULL, 1, 1, 'st_range4ma(float[][],text,text[])'::regprocedure, 'ignore', NULL), 2, 2
+ )
+FROM dummy_rast
+WHERE rid = 2;
+ rid | st_value
+-----+----------
+ 2 | 4
(1 row)
- </programlisting>
- </refsection>
+ </programlisting>
+
+ </refsection>
+
+ <refsection>
+ <title>See Also</title>
+ <para>
+ <xref linkend="RT_ST_MapAlgebraFctNgb" />,
+ <xref linkend="RT_ST_MapAlgebra" />,
+ <xref linkend="RT_ST_Min4ma" />,
+ <xref linkend="RT_ST_Max4ma" />,
+ <xref linkend="RT_ST_Sum4ma" />,
+ <xref linkend="RT_ST_Mean4ma" />,
+ <xref linkend="RT_ST_Distinct4ma" />,
+ <xref linkend="RT_ST_StdDev4ma" />
+ </para>
+ </refsection>
+ </refentry>
+
+ <refentry id="RT_ST_Distinct4ma">
+ <refnamediv>
+ <refname>ST_Distinct4ma</refname>
+ <refpurpose>Raster processing function that calculates the number of unique pixel values in a neighborhood.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>float8 <function>ST_Distinct4ma</function></funcdef>
+ <paramdef><type>float8[][]</type> <parameter>matrix</parameter></paramdef>
+ <paramdef><type>text</type> <parameter>nodatamode</parameter></paramdef>
+ <paramdef><type>text[]</type> <parameter>VARIADIC args</parameter></paramdef>
+ </funcprototype>
- <refsection>
- <title>Examples: Variant 2</title>
+ <funcprototype>
+ <funcdef>double precision <function>ST_Distinct4ma</function></funcdef>
+ <paramdef><type>double precision[][][]</type> <parameter>value</parameter></paramdef>
+ <paramdef><type>integer[][] </type> <parameter>pos</parameter></paramdef>
+ <paramdef><type>text[]</type> <parameter>VARIADIC userargs</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
- <para>Complete example of tiles of a coverage. This query only works with PostgreSQL 9.1 or higher.</para>
+ <para>Calculate the number of unique pixel values in a neighborhood of pixels.</para>
+
+ <note>
+ <para>Variant 1 is a specialized callback function for use as a callback parameter to <xref linkend="RT_ST_MapAlgebraFctNgb" />.</para>
+ </note>
- <programlisting>
-WITH foo AS (
- SELECT ST_Tile(
- ST_SetValues(
- ST_AddBand(
- ST_MakeEmptyRaster(6, 6, 0, 0, 1, -1, 0, 0, 0),
- 1, '32BF', 0, -9999
- ),
- 1, 1, 1, ARRAY[
- [1, 1, 1, 1, 1, 1],
- [1, 1, 1, 1, 2, 1],
- [1, 2, 2, 3, 3, 1],
- [1, 1, 3, 2, 1, 1],
- [1, 2, 2, 1, 2, 1],
- [1, 1, 1, 1, 1, 1]
- ]::double precision[]
- ),
- 2, 2
- ) AS rast
-)
-SELECT
- t1.rast,
- ST_Slope(ST_Union(t2.rast), 1, t1.rast)
-FROM foo t1
-CROSS JOIN foo t2
-WHERE ST_Intersects(t1.rast, t2.rast)
-GROUP BY t1.rast;
- </programlisting>
- </refsection>
-
- <refsection>
- <title>See Also</title>
+ <note>
<para>
- <xref linkend="RT_ST_MapAlgebra" />,
- <xref linkend="RT_ST_TRI" />,
- <xref linkend="RT_ST_TPI" />,
- <xref linkend="RT_ST_Roughness" />,
- <xref linkend="RT_ST_HillShade" />,
- <xref linkend="RT_ST_Aspect" />
+ Variant 2 is a specialized callback function for use as a callback parameter to <xref linkend="RT_ST_MapAlgebra" />.
</para>
- </refsection>
- </refentry>
-
- <refentry id="RT_ST_TPI">
- <refnamediv>
- <refname>ST_TPI</refname>
- <refpurpose>Returns a raster with the calculated Topographic Position Index.</refpurpose>
- </refnamediv>
+ </note>
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>raster <function>ST_TPI</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
- <paramdef><type>integer </type> <parameter>nband</parameter></paramdef>
- <paramdef><type>raster </type> <parameter>customextent</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>pixeltype="32BF"</parameter> </paramdef>
- <paramdef choice="opt"><type>boolean </type> <parameter> interpolate_nodata=FALSE </parameter> </paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
+ <warning>
+ <para>
+ Use of Variant 1 is discouraged since <xref linkend="RT_ST_MapAlgebraFctNgb" /> has been deprecated as of 2.1.0.
+ </para>
+ </warning>
+ <para>Availability: 2.0.0</para>
+ <para>Enhanced: 2.1.0 Addition of Variant 2</para>
+ </refsection>
+
<refsection>
- <title>Description</title>
+ <title>Examples</title>
+
+ <programlisting>SELECT
+ rid,
+ st_value(
+ st_mapalgebrafctngb(rast, 1, NULL, 1, 1, 'st_distinct4ma(float[][],text,text[])'::regprocedure, 'ignore', NULL), 2, 2
+ )
+FROM dummy_rast
+WHERE rid = 2;
+ rid | st_value
+-----+----------
+ 2 | 3
+(1 row)
+ </programlisting>
+
+ </refsection>
+
+ <refsection>
+ <title>See Also</title>
+ <para>
+ <xref linkend="RT_ST_MapAlgebraFctNgb" />,
+ <xref linkend="RT_ST_MapAlgebra" />,
+ <xref linkend="RT_ST_Min4ma" />,
+ <xref linkend="RT_ST_Max4ma" />,
+ <xref linkend="RT_ST_Sum4ma" />,
+ <xref linkend="RT_ST_Mean4ma" />,
+ <xref linkend="RT_ST_Distinct4ma" />,
+ <xref linkend="RT_ST_StdDev4ma" />
+ </para>
+ </refsection>
+ </refentry>
- <para>Calculates the Topographic Position Index, which is defined as the folcal mean with radius of one minus the center cell.</para>
+ <refentry id="RT_ST_StdDev4ma">
+ <refnamediv>
+ <refname>ST_StdDev4ma</refname>
+ <refpurpose>Raster processing function that calculates the standard deviation of pixel values in a neighborhood.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>float8 <function>ST_StdDev4ma</function></funcdef>
+ <paramdef><type>float8[][]</type> <parameter>matrix</parameter></paramdef>
+ <paramdef><type>text </type> <parameter>nodatamode</parameter></paramdef>
+ <paramdef><type>text[]</type> <parameter>VARIADIC args</parameter></paramdef>
+ </funcprototype>
- <note>
- <para>This function only supports a focalmean radius of one.</para>
- </note>
- <para>Availability: 2.1.0</para>
- </refsection>
+ <funcprototype>
+ <funcdef>double precision <function>ST_StdDev4ma</function></funcdef>
+ <paramdef><type>double precision[][][]</type> <parameter>value</parameter></paramdef>
+ <paramdef><type>integer[][] </type> <parameter>pos</parameter></paramdef>
+ <paramdef><type>text[]</type> <parameter>VARIADIC userargs</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
- <refsection>
- <title>Examples</title>
- <programlisting>
--- needs examples
- </programlisting>
- </refsection>
+ <para>Calculate the standard deviation of pixel values in a neighborhood of pixels.</para>
+
+ <note>
+ <para>Variant 1 is a specialized callback function for use as a callback parameter to <xref linkend="RT_ST_MapAlgebraFctNgb" />.</para>
+ </note>
- <refsection>
- <title>See Also</title>
+ <note>
<para>
- <xref linkend="RT_ST_MapAlgebra" />,
- <xref linkend="RT_ST_TRI" />,
- <xref linkend="RT_ST_Roughness" />,
- <xref linkend="RT_ST_Slope" />,
- <xref linkend="RT_ST_HillShade" />,
- <xref linkend="RT_ST_Aspect" />
+ Variant 2 is a specialized callback function for use as a callback parameter to <xref linkend="RT_ST_MapAlgebra" />.
</para>
- </refsection>
- </refentry>
-
- <refentry id="RT_ST_TRI">
- <refnamediv>
- <refname>ST_TRI</refname>
- <refpurpose>Returns a raster with the calculated Terrain Ruggedness Index.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>raster <function>ST_TRI</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
- <paramdef><type>integer </type> <parameter>nband</parameter></paramdef>
- <paramdef><type>raster </type> <parameter>customextent</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>pixeltype="32BF"</parameter> </paramdef>
- <paramdef choice="opt"><type>boolean </type> <parameter> interpolate_nodata=FALSE </parameter> </paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
+ </note>
+ <warning>
<para>
- Terrain Ruggedness Index is calculated by comparing a central pixel with its neighbors, taking the absolute values of the differences, and averaging the result.
+ Use of Variant 1 is discouraged since <xref linkend="RT_ST_MapAlgebraFctNgb" /> has been deprecated as of 2.1.0.
</para>
+ </warning>
- <note>
- <para>This function only supports a focalmean radius of one.</para>
- </note>
-
- <para>Availability: 2.1.0</para>
- </refsection>
-
+ <para>Availability: 2.0.0</para>
+ <para>Enhanced: 2.1.0 Addition of Variant 2</para>
+ </refsection>
+
<refsection>
<title>Examples</title>
- <programlisting>
--- needs examples
- </programlisting>
- </refsection>
+
+ <programlisting>SELECT
+ rid,
+ st_value(
+ st_mapalgebrafctngb(rast, 1, '32BF', 1, 1, 'st_stddev4ma(float[][],text,text[])'::regprocedure, 'ignore', NULL), 2, 2
+ )
+FROM dummy_rast
+WHERE rid = 2;
+ rid | st_value
+-----+------------------
+ 2 | 1.30170822143555
+(1 row)
+ </programlisting>
+
+ </refsection>
+
+ <refsection>
+ <title>See Also</title>
+ <para>
+ <xref linkend="RT_ST_MapAlgebraFctNgb" />,
+ <xref linkend="RT_ST_MapAlgebra" />,
+ <xref linkend="RT_ST_Min4ma" />,
+ <xref linkend="RT_ST_Max4ma" />,
+ <xref linkend="RT_ST_Sum4ma" />,
+ <xref linkend="RT_ST_Mean4ma" />,
+ <xref linkend="RT_ST_Distinct4ma" />,
+ <xref linkend="RT_ST_StdDev4ma" />
+ </para>
+ </refsection>
+ </refentry>
- <refsection>
- <title>See Also</title>
- <para>
- <xref linkend="RT_ST_MapAlgebra" />,
- <xref linkend="RT_ST_Roughness" />,
- <xref linkend="RT_ST_TPI" />,
- <xref linkend="RT_ST_Slope" />,
- <xref linkend="RT_ST_HillShade" />,
- <xref linkend="RT_ST_Aspect" />
- </para>
- </refsection>
- </refentry>
+ <refentry id="RT_ST_InvDistWeight4ma">
+ <refnamediv>
+ <refname>ST_InvDistWeight4ma</refname>
+ <refpurpose>Raster processing function that interpolates a pixel's value from the pixel's neighborhood.</refpurpose>
+ </refnamediv>
- </sect2> <!-- /DEM -->
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>double precision <function>ST_InvDistWeight4ma</function></funcdef>
+ <paramdef><type>double precision[][][]</type> <parameter>value</parameter></paramdef>
+ <paramdef><type>integer[][]</type> <parameter>pos</parameter></paramdef>
+ <paramdef><type>text[]</type> <parameter>VARIADIC userargs</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
- <sect2 id="Raster_Processing_Geometry">
- <title>Raster to Geometry</title>
+ <refsection>
+ <title>Description</title>
- <refentry id="RT_Box3D">
+ <para>Calculate an interpolated value for a pixel using the Inverse Distance Weighted method.</para>
+
+ <para>
+ There are two optional parameters that can be passed through <varname>userargs</varname>. The first parameter is the power factor (variable k in the equation below) between 0 and 1 used in the Inverse Distance Weighted equation. If not specified, default value is 1. The second parameter is the weight percentage applied only when the value of the pixel of interest is included with the interpolated value from the neighborhood. If not specified and the pixel of interest has a value, that value is returned.
+ </para>
+
+ <para>
+ The basic inverse distance weight equation is:
+
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_invdistweight4ma_equation.png" />
+ </imageobject>
+ <caption>
+ <para>
+ k = power factor, a real number between 0 and 1
+ </para>
+ </caption>
+ </mediaobject>
+ </informalfigure>
+ </para>
+
+ <note>
+ <para>This function is a specialized callback function for use as a callback parameter to <xref linkend="RT_ST_MapAlgebra" />.</para>
+ </note>
+
+ <para>Availability: 2.1.0</para>
+ </refsection>
+
+ <refsection>
+ <title>Examples</title>
+ <programlisting>
+-- NEEDS EXAMPLE
+ </programlisting>
+ </refsection>
+
+ <refsection>
+ <title>See Also</title>
+ <para>
+ <xref linkend="RT_ST_MapAlgebra" />,
+ <xref linkend="RT_ST_MinDist4ma" />
+ </para>
+ </refsection>
+ </refentry>
+
+ <refentry id="RT_ST_MinDist4ma">
+ <refnamediv>
+ <refname>ST_MinDist4ma</refname>
+ <refpurpose>Raster processing function that returns the minimum distance (in number of pixels) between the pixel of interest and a neighboring pixel with value.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>double precision <function>ST_MinDist4ma</function></funcdef>
+ <paramdef><type>double precision[][][]</type> <parameter>value</parameter></paramdef>
+ <paramdef><type>integer[][]</type> <parameter>pos</parameter></paramdef>
+ <paramdef><type>text[]</type> <parameter>VARIADIC userargs</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>Return the shortest distance (in number of pixels) between the pixel of interest and the closest pixel with value in the neighborhood.</para>
+
+ <note>
+ <para>
+ The intent of this function is to provide an informative data point that helps infer the usefulness of the pixel of interest's interpolated value from <xref linkend="RT_ST_InvDistWeight4ma" />. This function is particularly useful when the neighborhood is sparsely populated.
+ </para>
+ </note>
+
+ <note>
+ <para>This function is a specialized callback function for use as a callback parameter to <xref linkend="RT_ST_MapAlgebra" />.</para>
+ </note>
+
+ <para>Availability: 2.1.0</para>
+ </refsection>
+
+ <refsection>
+ <title>Examples</title>
+ <programlisting>
+-- NEEDS EXAMPLE
+ </programlisting>
+ </refsection>
+
+ <refsection>
+ <title>See Also</title>
+ <para>
+ <xref linkend="RT_ST_MapAlgebra" />,
+ <xref linkend="RT_ST_InvDistWeight4ma" />
+ </para>
+ </refsection>
+ </refentry>
+
+ </sect2> <!-- /callback -->
+
+ <sect2 id="Raster_Processing_DEM">
+ <title>DEM (Elevation)</title>
+
+ <refentry id="RT_ST_Aspect">
<refnamediv>
- <refname>Box3D</refname>
- <refpurpose>Returns the box 3d representation of the enclosing box of the raster.</refpurpose>
+ <refname>ST_Aspect</refname>
+ <refpurpose>Returns the aspect (in degrees by default) of an elevation raster band. Useful for analyzing terrain.</refpurpose>
</refnamediv>
-
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
- <funcdef>box3d <function>Box3D</function></funcdef>
+ <funcdef>raster <function>ST_Aspect</function></funcdef>
<paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
- </funcprototype>
+ <paramdef choice="opt"><type>integer </type> <parameter>band=1</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>pixeltype=32BF</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>units=DEGREES</parameter></paramdef>
+ <paramdef choice="opt"><type>boolean </type> <parameter>interpolate_nodata=FALSE</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>raster <function>ST_Aspect</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>band</parameter></paramdef>
+ <paramdef><type>raster </type> <parameter>customextent</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>pixeltype=32BF</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>units=DEGREES</parameter></paramdef>
+ <paramdef choice="opt"><type>boolean </type> <parameter>interpolate_nodata=FALSE</parameter></paramdef>
+ </funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
-
- <para>Returns the box representing the extent of the raster.</para>
+
+ <para>Returns the aspect (in degrees by default) of an elevation raster band. Utilizes map algebra and applies the aspect equation to neighboring pixels.</para>
+
<para>
- The polygon is defined by the corner points of the bounding box ((<varname>MINX</varname>, <varname>MINY</varname>), (<varname>MAXX</varname>, <varname>MAXY</varname>))
+ <varname>units</varname> indicates the units of the aspect. Possible values are: RADIANS, DEGREES (default).
</para>
- <para>Changed: 2.0.0 In pre-2.0 versions, there used to be a box2d instead of box3d. Since box2d is a deprecated type, this was changed to box3d.</para>
+ <para>
+ When <varname>units</varname> = RADIANS, values are between 0 and 2 * pi radians measured clockwise from North.
+ </para>
+
+ <para>
+ When <varname>units</varname> = DEGREES, values are between 0 and 360 degrees measured clockwise from North.
+ </para>
+
+ <para>
+ If slope of pixel is zero, aspect of pixel is -1.
+ </para>
+
+ <note>
+ <para>
+ For more information about Slope, Aspect and Hillshade, please refer to <ulink url="http://webhelp.esri.com/arcgisdesktop/9.3/index.cfm?TopicName=How%20Hillshade%20works">ESRI - How hillshade works</ulink> and <ulink url="http://geospatial.intergraph.com/fieldguide/wwhelp/wwhimpl/common/html/wwhelp.htm?context=FieldGuide&file=Aspect_Images.html">ERDAS Field Guide - Aspect Images</ulink>.
+ </para>
+ </note>
+
+ <para>Availability: 2.0.0 </para>
+ <para>Enhanced: 2.1.0 Uses ST_MapAlgebra() and added optional <varname>interpolate_nodata</varname> function parameter</para>
+ <para>Changed: 2.1.0 In prior versions, return values were in radians. Now, return values default to degrees</para>
</refsection>
<refsection>
- <title>Examples</title>
-
+ <title>Examples: Variant 1</title>
<programlisting>
+WITH foo AS (
+ SELECT ST_SetValues(
+ ST_AddBand(ST_MakeEmptyRaster(5, 5, 0, 0, 1, -1, 0, 0, 0), 1, '32BF', 0, -9999),
+ 1, 1, 1, ARRAY[
+ [1, 1, 1, 1, 1],
+ [1, 2, 2, 2, 1],
+ [1, 2, 3, 2, 1],
+ [1, 2, 2, 2, 1],
+ [1, 1, 1, 1, 1]
+ ]::double precision[][]
+ ) AS rast
+)
SELECT
- rid,
- Box3D(rast) AS rastbox
-FROM dummy_rast;
+ ST_DumpValues(ST_Aspect(rast, 1, '32BF'))
+FROM foo
-rid | rastbox
-----+-------------------------------------------------
-1 | BOX3D(0.5 0.5 0,20.5 60.5 0)
-2 | BOX3D(3427927.75 5793243.5 0,3427928 5793244 0)
+ st_dumpvalues
+
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+----------------------------------
+ (1,"{{315,341.565063476562,0,18.4349479675293,45},{288.434936523438,315,0,45,71.5650482177734},{270,270,-1,90,90},{251.565048217773,225,180,135,108.434951782227},{225,198.43495178
+2227,180,161.565048217773,135}}")
+(1 row)
+ </programlisting>
+ </refsection>
+
+ <refsection>
+ <title>Examples: Variant 2</title>
+
+ <para>Complete example of tiles of a coverage. This query only works with PostgreSQL 9.1 or higher.</para>
+
+ <programlisting>
+WITH foo AS (
+ SELECT ST_Tile(
+ ST_SetValues(
+ ST_AddBand(
+ ST_MakeEmptyRaster(6, 6, 0, 0, 1, -1, 0, 0, 0),
+ 1, '32BF', 0, -9999
+ ),
+ 1, 1, 1, ARRAY[
+ [1, 1, 1, 1, 1, 1],
+ [1, 1, 1, 1, 2, 1],
+ [1, 2, 2, 3, 3, 1],
+ [1, 1, 3, 2, 1, 1],
+ [1, 2, 2, 1, 2, 1],
+ [1, 1, 1, 1, 1, 1]
+ ]::double precision[]
+ ),
+ 2, 2
+ ) AS rast
+)
+SELECT
+ t1.rast,
+ ST_Aspect(ST_Union(t2.rast), 1, t1.rast)
+FROM foo t1
+CROSS JOIN foo t2
+WHERE ST_Intersects(t1.rast, t2.rast)
+GROUP BY t1.rast;
</programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para>
- <xref linkend="RT_ST_Envelope" />
+ <xref linkend="RT_ST_MapAlgebra" />,
+ <xref linkend="RT_ST_TRI" />,
+ <xref linkend="RT_ST_TPI" />,
+ <xref linkend="RT_ST_Roughness" />,
+ <xref linkend="RT_ST_HillShade" />,
+ <xref linkend="RT_ST_Slope" />
</para>
</refsection>
</refentry>
- <refentry id="RT_ST_ConvexHull">
+ <refentry id="RT_ST_HillShade">
<refnamediv>
- <refname>ST_ConvexHull</refname>
- <refpurpose>Return the convex hull geometry of the raster including pixel values equal to BandNoDataValue.
- For regular shaped and non-skewed
- rasters, this gives the same result as ST_Envelope so only useful for irregularly shaped or skewed rasters.</refpurpose>
+ <refname>ST_HillShade</refname>
+ <refpurpose>Returns the hypothetical illumination of an elevation raster band using provided azimuth, altitude, brightness and scale inputs.</refpurpose>
</refnamediv>
-
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
- <funcdef>geometry <function>ST_ConvexHull</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <funcdef>raster <function>ST_HillShade</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef choice="opt"><type>integer </type> <parameter>band=1</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>pixeltype=32BF</parameter></paramdef>
+ <paramdef choice="opt"><type>double precision </type> <parameter>azimuth=315</parameter></paramdef>
+ <paramdef choice="opt"><type>double precision </type> <parameter>altitude=45</parameter></paramdef>
+ <paramdef choice="opt"><type>double precision </type> <parameter>max_bright=255</parameter></paramdef>
+ <paramdef choice="opt"><type>double precision </type> <parameter>scale=1.0</parameter></paramdef>
+ <paramdef choice="opt"><type>boolean </type> <parameter>interpolate_nodata=FALSE</parameter></paramdef>
</funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
- <para>Return the convex hull geometry of the raster including the NoDataBandValue band pixels. For regular shaped and non-skewed
- rasters, this gives more or less the same result as ST_Envelope
- so only useful for irregularly shaped or skewed rasters.</para>
-
- <note><para>ST_Envelope floors the coordinates and hence add a little buffer around the raster so the answer is subtly
- different from ST_ConvexHull which does not floor.</para>
- </note>
- </refsection>
-
- <refsection>
- <title>Examples</title>
- <para>Refer to <ulink url="http://trac.osgeo.org/postgis/wiki/WKTRaster/SpecificationWorking01">PostGIS Raster Specification</ulink> for a diagram of this.</para>
- <programlisting>
--- Note envelope and convexhull are more or less the same
-SELECT ST_AsText(ST_ConvexHull(rast)) As convhull,
- ST_AsText(ST_Envelope(rast)) As env
-FROM dummy_rast WHERE rid=1;
-
- convhull | env
---------------------------------------------------------+------------------------------------
- POLYGON((0.5 0.5,20.5 0.5,20.5 60.5,0.5 60.5,0.5 0.5)) | POLYGON((0 0,20 0,20 60,0 60,0 0))
- </programlisting>
- <programlisting>
--- now we skew the raster
--- note how the convex hull and envelope are now different
-SELECT ST_AsText(ST_ConvexHull(rast)) As convhull,
- ST_AsText(ST_Envelope(rast)) As env
-FROM (SELECT ST_SetRotation(rast, 0.1, 0.1) As rast
- FROM dummy_rast WHERE rid=1) As foo;
-
- convhull | env
---------------------------------------------------------+------------------------------------
- POLYGON((0.5 0.5,20.5 1.5,22.5 61.5,2.5 60.5,0.5 0.5)) | POLYGON((0 0,22 0,22 61,0 61,0 0))
- </programlisting>
- </refsection>
-
- <!-- Optionally add a "See Also" section -->
- <refsection>
- <title>See Also</title>
- <para>
- <xref linkend="RT_ST_Envelope" />,
- <xref linkend="RT_ST_MinConvexHull" />,
- <xref linkend="ST_ConvexHull" />,
- <xref linkend="ST_AsText" />
- </para>
- </refsection>
- </refentry>
-
- <refentry id="RT_ST_DumpAsPolygons">
- <refnamediv>
- <refname>ST_DumpAsPolygons</refname>
- <refpurpose>Returns a set of geomval (geom,val) rows, from a given raster band. If no band number is specified, band num defaults to 1.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
<funcprototype>
- <funcdef>setof geomval <function>ST_DumpAsPolygons</function></funcdef>
+ <funcdef>raster <function>ST_HillShade</function></funcdef>
<paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
- <paramdef choice="opt"><type>integer </type> <parameter>band_num=1</parameter></paramdef>
- <paramdef choice="opt"><type>boolean </type> <parameter>exclude_nodata_value=TRUE</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>band</parameter></paramdef>
+ <paramdef><type>raster </type> <parameter>customextent</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>pixeltype=32BF</parameter></paramdef>
+ <paramdef choice="opt"><type>double precision </type> <parameter>azimuth=315</parameter></paramdef>
+ <paramdef choice="opt"><type>double precision </type> <parameter>altitude=45</parameter></paramdef>
+ <paramdef choice="opt"><type>double precision </type> <parameter>max_bright=255</parameter></paramdef>
+ <paramdef choice="opt"><type>double precision </type> <parameter>scale=1.0</parameter></paramdef>
+ <paramdef choice="opt"><type>boolean </type> <parameter>interpolate_nodata=FALSE</parameter></paramdef>
</funcprototype>
</funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
+ </refsynopsisdiv>
+
+ <refsection>
<title>Description</title>
- <para>This is a set-returning function (SRF). It returns a set of
- geomval rows, formed by a geometry (geom) and a pixel band value (val).
- Each polygon is the union of all pixels for that band that have the same pixel value denoted by val.</para>
-
- <para>ST_DumpAsPolygon is useful for polygonizing rasters. It is the
- reverse of a GROUP BY in that it creates new rows. For example it
- can be used to expand a single raster into multiple POLYGONS/MULTIPOLYGONS.</para>
-
- <para>Availability: Requires GDAL 1.7 or higher.</para>
- <note><para>If there is a no data value set for a band, pixels with that value will not be returned.</para></note>
- <note><para>If you only care about count of pixels with a given value in a raster, it is faster to use <xref linkend="RT_ST_ValueCount" />.</para></note>
+
+ <para>Returns the hypothetical illumination of an elevation raster band using the azimuth, altitude, brightness, and scale inputs. Utilizes map algebra and applies the hill shade equation to neighboring pixels. Return pixel values are between 0 and 255.</para>
+
+ <para>
+ <varname>azimuth</varname> is a value between 0 and 360 degrees measured clockwise from North.
+ </para>
+
+ <para>
+ <varname>altitude</varname> is a value between 0 and 90 degrees where 0 degrees is at the horizon and 90 degrees is directly overhead.
+ </para>
+
+ <para>
+ <varname>max_bright</varname> is a value between 0 and 255 with 0 as no brightness and 255 as max brightness.
+ </para>
+
+ <para>
+ <varname>scale</varname> is the ratio of vertical units to horizontal. For Feet:LatLon use scale=370400, for Meters:LatLon use scale=111120.
+ </para>
+
+ <para>
+ If <varname>interpolate_nodata</varname> is TRUE, values for NODATA pixels from the input raster will be interpolated using <xref linkend="RT_ST_InvDistWeight4ma" /> before computing the hillshade illumination.
+ </para>
+
<note>
<para>
- This is different than ST_PixelAsPolygons where one geometry is returned for each pixel regardless of pixel value.
+ For more information about Hillshade, please refer to <ulink url="http://webhelp.esri.com/arcgisdesktop/9.3/index.cfm?TopicName=How%20Hillshade%20works">How hillshade works</ulink>.
</para>
</note>
- </refsection>
-
- <refsection>
- <title>Examples</title>
+
+ <para>Availability: 2.0.0 </para>
+ <para>Enhanced: 2.1.0 Uses ST_MapAlgebra() and added optional <varname>interpolate_nodata</varname> function parameter</para>
+ <para>Changed: 2.1.0 In prior versions, azimuth and altitude were expressed in radians. Now, azimuth and altitude are expressed in degrees</para>
+
+ </refsection>
+
+ <refsection>
+ <title>Examples: Variant 1</title>
<programlisting>
-SELECT val, ST_AsText(geom) As geomwkt
-FROM (
-SELECT (ST_DumpAsPolygons(rast)).*
-FROM dummy_rast
-WHERE rid = 2
-) As foo
-WHERE val BETWEEN 249 and 251
-ORDER BY val;
+WITH foo AS (
+ SELECT ST_SetValues(
+ ST_AddBand(ST_MakeEmptyRaster(5, 5, 0, 0, 1, -1, 0, 0, 0), 1, '32BF', 0, -9999),
+ 1, 1, 1, ARRAY[
+ [1, 1, 1, 1, 1],
+ [1, 2, 2, 2, 1],
+ [1, 2, 3, 2, 1],
+ [1, 2, 2, 2, 1],
+ [1, 1, 1, 1, 1]
+ ]::double precision[][]
+ ) AS rast
+)
+SELECT
+ ST_DumpValues(ST_Hillshade(rast, 1, '32BF'))
+FROM foo
- val | geomwkt
------+--------------------------------------------------------------------------
- 249 | POLYGON((3427927.95 5793243.95,3427927.95 5793243.85,3427928 5793243.85,
- 3427928 5793243.95,3427927.95 5793243.95))
- 250 | POLYGON((3427927.75 5793243.9,3427927.75 5793243.85,3427927.8 5793243.85,
- 3427927.8 5793243.9,3427927.75 5793243.9))
- 250 | POLYGON((3427927.8 5793243.8,3427927.8 5793243.75,3427927.85 5793243.75,
- 3427927.85 5793243.8, 3427927.8 5793243.8))
- 251 | POLYGON((3427927.75 5793243.85,3427927.75 5793243.8,3427927.8 5793243.8,
- 3427927.8 5793243.85,3427927.75 5793243.85))
+ st_dumpvalues
+
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+-----------------------------------------------------------------------
+ (1,"{{NULL,NULL,NULL,NULL,NULL},{NULL,251.32763671875,220.749786376953,147.224319458008,NULL},{NULL,220.749786376953,180.312225341797,67.7497863769531,NULL},{NULL,147.224319458008
+,67.7497863769531,43.1210060119629,NULL},{NULL,NULL,NULL,NULL,NULL}}")
+(1 row)
</programlisting>
- </refsection>
+ </refsection>
+
+ <refsection>
+ <title>Examples: Variant 2</title>
+
+ <para>Complete example of tiles of a coverage. This query only works with PostgreSQL 9.1 or higher.</para>
+
+ <programlisting>
+WITH foo AS (
+ SELECT ST_Tile(
+ ST_SetValues(
+ ST_AddBand(
+ ST_MakeEmptyRaster(6, 6, 0, 0, 1, -1, 0, 0, 0),
+ 1, '32BF', 0, -9999
+ ),
+ 1, 1, 1, ARRAY[
+ [1, 1, 1, 1, 1, 1],
+ [1, 1, 1, 1, 2, 1],
+ [1, 2, 2, 3, 3, 1],
+ [1, 1, 3, 2, 1, 1],
+ [1, 2, 2, 1, 2, 1],
+ [1, 1, 1, 1, 1, 1]
+ ]::double precision[]
+ ),
+ 2, 2
+ ) AS rast
+)
+SELECT
+ t1.rast,
+ ST_Hillshade(ST_Union(t2.rast), 1, t1.rast)
+FROM foo t1
+CROSS JOIN foo t2
+WHERE ST_Intersects(t1.rast, t2.rast)
+GROUP BY t1.rast;
+ </programlisting>
+ </refsection>
<refsection>
<title>See Also</title>
<para>
- <xref linkend="geomval" />,
- <xref linkend="RT_ST_Value" />,
- <xref linkend="RT_ST_Polygon" />,
- <xref linkend="RT_ST_ValueCount" />
+ <xref linkend="RT_ST_MapAlgebra" />,
+ <xref linkend="RT_ST_TRI" />,
+ <xref linkend="RT_ST_TPI" />,
+ <xref linkend="RT_ST_Roughness" />,
+ <xref linkend="RT_ST_Aspect" />,
+ <xref linkend="RT_ST_Slope" />
</para>
</refsection>
</refentry>
- <refentry id="RT_ST_Envelope">
+ <refentry id="RT_ST_Roughness">
<refnamediv>
- <refname>ST_Envelope</refname>
- <refpurpose>Returns the polygon representation of the extent of the raster.</refpurpose>
+ <refname>ST_Roughness</refname>
+ <refpurpose>Returns a raster with the calculated "roughness" of a DEM.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
- <funcdef>geometry <function>ST_Envelope</function></funcdef>
+ <funcdef>raster <function>ST_Roughness</function></funcdef>
<paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>nband</parameter></paramdef>
+ <paramdef><type>raster </type> <parameter>customextent</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>pixeltype="32BF"</parameter> </paramdef>
+ <paramdef choice="opt"><type>boolean </type> <parameter> interpolate_nodata=FALSE </parameter> </paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
-
- <para>Returns the polygon representation of the extent of the raster in spatial coordinate units defined by srid. It is a float8 minimum bounding box represented as a polygon. </para>
-
- <para>The polygon is defined by the corner points of the bounding box
- ((<varname>MINX</varname>, <varname>MINY</varname>),
- (<varname>MINX</varname>, <varname>MAXY</varname>),
- (<varname>MAXX</varname>, <varname>MAXY</varname>),
- (<varname>MAXX</varname>, <varname>MINY</varname>),
- (<varname>MINX</varname>, <varname>MINY</varname>))
- </para>
+ <para>Calculates the "roughness" of a DEM, by subtracting the maximum from the minimum for a given area.</para>
+ <para>Availability: 2.1.0</para>
</refsection>
-
+
<refsection>
<title>Examples</title>
-
<programlisting>
-SELECT rid, ST_AsText(ST_Envelope(rast)) As envgeomwkt
-FROM dummy_rast;
-
- rid | envgeomwkt
------+--------------------------------------------------------------------
- 1 | POLYGON((0 0,20 0,20 60,0 60,0 0))
- 2 | POLYGON((3427927 5793243,3427928 5793243,
- 3427928 5793244,3427927 5793244, 3427927 5793243))
+-- needs examples
</programlisting>
- </refsection>
+ </refsection>
- <refsection>
- <title>See Also</title>
+ <refsection>
+ <title>See Also</title>
<para>
- <xref linkend="ST_Envelope" />,
- <xref linkend="ST_AsText" />,
- <xref linkend="RT_ST_SRID" />
- </para>
- </refsection>
- </refentry>
-
- <refentry id="RT_ST_MinConvexHull">
+ <xref linkend="RT_ST_MapAlgebra" />,
+ <xref linkend="RT_ST_TRI" />,
+ <xref linkend="RT_ST_TPI" />,
+ <xref linkend="RT_ST_Slope" />,
+ <xref linkend="RT_ST_HillShade" />,
+ <xref linkend="RT_ST_Aspect" />
+ </para>
+ </refsection>
+ </refentry>
+
+ <refentry id="RT_ST_Slope">
<refnamediv>
- <refname>ST_MinConvexHull</refname>
- <refpurpose>
- Return the convex hull geometry of the raster excluding NODATA pixels.
- </refpurpose>
+ <refname>ST_Slope</refname>
+ <refpurpose>Returns the slope (in degrees by default) of an elevation raster band. Useful for analyzing terrain.</refpurpose>
</refnamediv>
-
<refsynopsisdiv>
<funcsynopsis>
- <funcprototype>
- <funcdef>geometry <function>ST_MinConvexHull</function></funcdef>
+ <funcprototype>
+ <funcdef>raster <function>ST_Slope</function></funcdef>
<paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
- <paramdef choice="opt"><type>integer </type> <parameter>nband=NULL</parameter></paramdef>
- </funcprototype>
+ <paramdef choice="opt"><type>integer </type> <parameter>nband=1</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>pixeltype=32BF</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>units=DEGREES</parameter></paramdef>
+ <paramdef choice="opt"><type>double precision </type> <parameter>scale=1.0</parameter></paramdef>
+ <paramdef choice="opt"><type>boolean </type> <parameter>interpolate_nodata=FALSE</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>raster <function>ST_Slope</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>nband</parameter></paramdef>
+ <paramdef><type>raster </type> <parameter>customextent</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>pixeltype=32BF</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>units=DEGREES</parameter></paramdef>
+ <paramdef choice="opt"><type>double precision </type> <parameter>scale=1.0</parameter></paramdef>
+ <paramdef choice="opt"><type>boolean </type> <parameter>interpolate_nodata=FALSE</parameter></paramdef>
+ </funcprototype>
</funcsynopsis>
</refsynopsisdiv>
-
+
<refsection>
<title>Description</title>
+
+ <para>Returns the slope (in degrees by default) of an elevation raster band. Utilizes map algebra and applies the slope equation to neighboring pixels.</para>
<para>
- Return the convex hull geometry of the raster excluding NODATA pixels. If <varname>nband</varname> is NULL, all bands of the raster are considered.
+ <varname>units</varname> indicates the units of the slope. Possible values are: RADIANS, DEGREES (default), PERCENT.
</para>
- <para>Availability: 2.1.0 </para>
+ <para>
+ <varname>scale</varname> is the ratio of vertical units to horizontal. For Feet:LatLon use scale=370400, for Meters:LatLon use scale=111120.
+ </para>
+
+ <para>
+ If <varname>interpolate_nodata</varname> is TRUE, values for NODATA pixels from the input raster will be interpolated using <xref linkend="RT_ST_InvDistWeight4ma" /> before computing the surface slope.
+ </para>
+
+ <note>
+ <para>
+ For more information about Slope, Aspect and Hillshade, please refer to <ulink url="http://webhelp.esri.com/arcgisdesktop/9.3/index.cfm?TopicName=How%20Hillshade%20works">ESRI - How hillshade works</ulink> and <ulink url="http://geospatial.intergraph.com/fieldguide/wwhelp/wwhimpl/common/html/wwhelp.htm?context=FieldGuide&file=Slope_Images.html">ERDAS Field Guide - Slope Images</ulink>.
+ </para>
+ </note>
+
+ <para>Availability: 2.0.0 </para>
+ <para>Enhanced: 2.1.0 Uses ST_MapAlgebra() and added optional <varname>units</varname>, <varname>scale</varname>, <varname>interpolate_nodata</varname> function parameters</para>
+ <para>Changed: 2.1.0 In prior versions, return values were in radians. Now, return values default to degrees</para>
+
+ </refsection>
+
+ <refsection>
+ <title>Examples: Variant 1</title>
+ <programlisting>
+WITH foo AS (
+ SELECT ST_SetValues(
+ ST_AddBand(ST_MakeEmptyRaster(5, 5, 0, 0, 1, -1, 0, 0, 0), 1, '32BF', 0, -9999),
+ 1, 1, 1, ARRAY[
+ [1, 1, 1, 1, 1],
+ [1, 2, 2, 2, 1],
+ [1, 2, 3, 2, 1],
+ [1, 2, 2, 2, 1],
+ [1, 1, 1, 1, 1]
+ ]::double precision[][]
+ ) AS rast
+)
+SELECT
+ ST_DumpValues(ST_Slope(rast, 1, '32BF'))
+FROM foo
+
+ st_dumpvalues
+
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+---------------------------------------------------------------------
+ (1,"{{10.0249881744385,21.5681285858154,26.5650520324707,21.5681285858154,10.0249881744385},{21.5681285858154,35.2643890380859,36.8698959350586,35.2643890380859,21.5681285858154},
+{26.5650520324707,36.8698959350586,0,36.8698959350586,26.5650520324707},{21.5681285858154,35.2643890380859,36.8698959350586,35.2643890380859,21.5681285858154},{10.0249881744385,21.
+5681285858154,26.5650520324707,21.5681285858154,10.0249881744385}}")
+(1 row)
+ </programlisting>
</refsection>
<refsection>
- <title>Examples</title>
+ <title>Examples: Variant 2</title>
+
+ <para>Complete example of tiles of a coverage. This query only works with PostgreSQL 9.1 or higher.</para>
+
<programlisting>
WITH foo AS (
- SELECT
+ SELECT ST_Tile(
ST_SetValues(
- ST_SetValues(
- ST_AddBand(ST_AddBand(ST_MakeEmptyRaster(9, 9, 0, 0, 1, -1, 0, 0, 0), 1, '8BUI', 0, 0), 2, '8BUI', 1, 0),
- 1, 1, 1,
- ARRAY[
- [0, 0, 0, 0, 0, 0, 0, 0, 0],
- [0, 0, 0, 0, 0, 0, 0, 0, 0],
- [0, 0, 0, 0, 0, 0, 0, 0, 0],
- [0, 0, 0, 1, 0, 0, 0, 0, 1],
- [0, 0, 0, 1, 1, 0, 0, 0, 0],
- [0, 0, 0, 1, 0, 0, 0, 0, 0],
- [0, 0, 0, 0, 0, 0, 0, 0, 0],
- [0, 0, 0, 0, 0, 0, 0, 0, 0],
- [0, 0, 0, 0, 0, 0, 0, 0, 0]
- ]::double precision[][]
+ ST_AddBand(
+ ST_MakeEmptyRaster(6, 6, 0, 0, 1, -1, 0, 0, 0),
+ 1, '32BF', 0, -9999
),
- 2, 1, 1,
- ARRAY[
- [0, 0, 0, 0, 0, 0, 0, 0, 0],
- [0, 0, 0, 0, 0, 0, 0, 0, 0],
- [0, 0, 0, 0, 0, 0, 0, 0, 0],
- [1, 0, 0, 0, 0, 1, 0, 0, 0],
- [0, 0, 0, 0, 1, 1, 0, 0, 0],
- [0, 0, 0, 0, 0, 1, 0, 0, 0],
- [0, 0, 0, 0, 0, 0, 0, 0, 0],
- [0, 0, 0, 0, 0, 0, 0, 0, 0],
- [0, 0, 1, 0, 0, 0, 0, 0, 0]
- ]::double precision[][]
- ) AS rast
+ 1, 1, 1, ARRAY[
+ [1, 1, 1, 1, 1, 1],
+ [1, 1, 1, 1, 2, 1],
+ [1, 2, 2, 3, 3, 1],
+ [1, 1, 3, 2, 1, 1],
+ [1, 2, 2, 1, 2, 1],
+ [1, 1, 1, 1, 1, 1]
+ ]::double precision[]
+ ),
+ 2, 2
+ ) AS rast
)
SELECT
- ST_AsText(ST_ConvexHull(rast)) AS hull,
- ST_AsText(ST_MinConvexHull(rast)) AS mhull,
- ST_AsText(ST_MinConvexHull(rast, 1)) AS mhull_1,
- ST_AsText(ST_MinConvexHull(rast, 2)) AS mhull_2
-FROM foo
-
- hull | mhull | mhull_1 | mhull_2
-----------------------------------+-------------------------------------+-------------------------------------+-------------------------------------
- POLYGON((0 0,9 0,9 -9,0 -9,0 0)) | POLYGON((0 -3,9 -3,9 -9,0 -9,0 -3)) | POLYGON((3 -3,9 -3,9 -6,3 -6,3 -3)) | POLYGON((0 -3,6 -3,6 -9,0 -9,0 -3))
+ t1.rast,
+ ST_Slope(ST_Union(t2.rast), 1, t1.rast)
+FROM foo t1
+CROSS JOIN foo t2
+WHERE ST_Intersects(t1.rast, t2.rast)
+GROUP BY t1.rast;
</programlisting>
</refsection>
-
+
<refsection>
<title>See Also</title>
<para>
- <xref linkend="RT_ST_Envelope" />,
- <xref linkend="RT_ST_ConvexHull" />,
- <xref linkend="ST_ConvexHull" />,
- <xref linkend="ST_AsText" />
+ <xref linkend="RT_ST_MapAlgebra" />,
+ <xref linkend="RT_ST_TRI" />,
+ <xref linkend="RT_ST_TPI" />,
+ <xref linkend="RT_ST_Roughness" />,
+ <xref linkend="RT_ST_HillShade" />,
+ <xref linkend="RT_ST_Aspect" />
</para>
</refsection>
</refentry>
-
- <refentry id="RT_ST_Polygon">
- <refnamediv>
- <refname>ST_Polygon</refname>
- <refpurpose>Returns a multipolygon geometry formed by the union of pixels that have a pixel value that is not no data value. If no band number is specified, band num defaults to 1.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
+
+ <refentry id="RT_ST_TPI">
+ <refnamediv>
+ <refname>ST_TPI</refname>
+ <refpurpose>Returns a raster with the calculated Topographic Position Index.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
<funcsynopsis>
- <funcprototype>
- <funcdef>geometry <function>ST_Polygon</function></funcdef>
+ <funcprototype>
+ <funcdef>raster <function>ST_TPI</function></funcdef>
<paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
- <paramdef choice="opt"><type>integer </type> <parameter>band_num=1</parameter></paramdef>
- </funcprototype>
+ <paramdef><type>integer </type> <parameter>nband</parameter></paramdef>
+ <paramdef><type>raster </type> <parameter>customextent</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>pixeltype="32BF"</parameter> </paramdef>
+ <paramdef choice="opt"><type>boolean </type> <parameter> interpolate_nodata=FALSE </parameter> </paramdef>
+ </funcprototype>
</funcsynopsis>
- </refsynopsisdiv>
-
+ </refsynopsisdiv>
+
<refsection>
<title>Description</title>
- <para>Availability: 0.1.6 Requires GDAL 1.7 or higher.</para>
- <para>Enhanced: 2.1.0 Improved Speed (fully C-Based) and the returning multipolygon is ensured to be valid.</para>
- <para>Changed: 2.1.0 In prior versions would sometimes return a polygon, changed to always return multipolygon.</para>
+
+ <para>Calculates the Topographic Position Index, which is defined as the folcal mean with radius of one minus the center cell.</para>
+
+ <note>
+ <para>This function only supports a focalmean radius of one.</para>
+ </note>
+ <para>Availability: 2.1.0</para>
</refsection>
- <refsection>
+ <refsection>
<title>Examples</title>
<programlisting>
--- by default no data band value is 0 or not set, so polygon will return a square polygon
-SELECT ST_AsText(ST_Polygon(rast)) As geomwkt
-FROM dummy_rast
-WHERE rid = 2;
+-- needs examples
+ </programlisting>
+ </refsection>
-geomwkt
---------------------------------------------
-MULTIPOLYGON(((3427927.75 5793244,3427928 5793244,3427928 5793243.75,3427927.75 5793243.75,3427927.75 5793244)))
-
-
--- now we change the no data value of first band
-UPDATE dummy_rast SET rast = ST_SetBandNoDataValue(rast,1,254)
-WHERE rid = 2;
-SELECt rid, ST_BandNoDataValue(rast)
-from dummy_rast where rid = 2;
+ <refsection>
+ <title>See Also</title>
+ <para>
+ <xref linkend="RT_ST_MapAlgebra" />,
+ <xref linkend="RT_ST_TRI" />,
+ <xref linkend="RT_ST_Roughness" />,
+ <xref linkend="RT_ST_Slope" />,
+ <xref linkend="RT_ST_HillShade" />,
+ <xref linkend="RT_ST_Aspect" />
+ </para>
+ </refsection>
+ </refentry>
--- ST_Polygon excludes the pixel value 254 and returns a multipolygon
-SELECT ST_AsText(ST_Polygon(rast)) As geomwkt
-FROM dummy_rast
-WHERE rid = 2;
+ <refentry id="RT_ST_TRI">
+ <refnamediv>
+ <refname>ST_TRI</refname>
+ <refpurpose>Returns a raster with the calculated Terrain Ruggedness Index.</refpurpose>
+ </refnamediv>
-geomwkt
----------------------------------------------------------
-MULTIPOLYGON(((3427927.9 5793243.95,3427927.85 5793243.95,3427927.85 5793244,3427927.9 5793244,3427927.9 5793243.95)),((3427928 5793243.85,3427928 5793243.8,3427927.95 5793243.8,3427927.95 5793243.85,3427927.9 5793243.85,3427927.9 5793243.9,3427927.9 5793243.95,3427927.95 5793243.95,3427928 5793243.95,3427928 5793243.85)),((3427927.8 5793243.75,3427927.75 5793243.75,3427927.75 5793243.8,3427927.75 5793243.85,3427927.75 5793243.9,3427927.75 5793244,3427927.8 5793244,3427927.8 5793243.9,3427927.8 5793243.85,3427927.85 5793243.85,3427927.85 5793243.8,3427927.85 5793243.75,3427927.8 5793243.75)))
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>raster <function>ST_TRI</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>nband</parameter></paramdef>
+ <paramdef><type>raster </type> <parameter>customextent</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>pixeltype="32BF"</parameter> </paramdef>
+ <paramdef choice="opt"><type>boolean </type> <parameter> interpolate_nodata=FALSE </parameter> </paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
--- Or if you want the no data value different for just one time
+ <refsection>
+ <title>Description</title>
-SELECT ST_AsText(
- ST_Polygon(
- ST_SetBandNoDataValue(rast,1,252)
- )
- ) As geomwkt
-FROM dummy_rast
-WHERE rid =2;
+ <para>
+ Terrain Ruggedness Index is calculated by comparing a central pixel with its neighbors, taking the absolute values of the differences, and averaging the result.
+ </para>
-geomwkt
----------------------------------
-MULTIPOLYGON(((3427928 5793243.85,3427928 5793243.8,3427928 5793243.75,3427927.85 5793243.75,3427927.8 5793243.75,3427927.8 5793243.8,3427927.75 5793243.8,3427927.75 5793243.85,3427927.75 5793243.9,3427927.75 5793244,3427927.8 5793244,3427927.85 5793244,3427927.9 5793244,3427928 5793244,3427928 5793243.95,3427928 5793243.85),(3427927.9 5793243.9,3427927.9 5793243.85,3427927.95 5793243.85,3427927.95 5793243.9,3427927.9 5793243.9)))
- </programlisting>
+ <note>
+ <para>This function only supports a focalmean radius of one.</para>
+ </note>
+
+ <para>Availability: 2.1.0</para>
</refsection>
+ <refsection>
+ <title>Examples</title>
+ <programlisting>
+-- needs examples
+ </programlisting>
+ </refsection>
+
<refsection>
<title>See Also</title>
- <para>
- <xref linkend="RT_ST_Value" />,
- <xref linkend="RT_ST_DumpAsPolygons" />
- </para>
+ <para>
+ <xref linkend="RT_ST_MapAlgebra" />,
+ <xref linkend="RT_ST_Roughness" />,
+ <xref linkend="RT_ST_TPI" />,
+ <xref linkend="RT_ST_Slope" />,
+ <xref linkend="RT_ST_HillShade" />,
+ <xref linkend="RT_ST_Aspect" />
+ </para>
</refsection>
</refentry>
- </sect2> <!-- /misc -->
+ </sect2> <!-- /DEM -->
- </sect1>
+ <sect2 id="Raster_Processing_Geometry">
+ <title>Raster to Geometry</title>
- <sect1 id="Raster_MapAlgebra_Builtin_Functions">
- <title>Raster Map Algebra Built-in Functions</title>
- <refentry id="RT_ST_Min4ma">
- <refnamediv>
- <refname>ST_Min4ma</refname>
- <refpurpose>
- Raster processing function that calculates the minimum pixel value in a neighborhood.
- </refpurpose>
- </refnamediv>
+ <refentry id="RT_Box3D">
+ <refnamediv>
+ <refname>Box3D</refname>
+ <refpurpose>Returns the box 3d representation of the enclosing box of the raster.</refpurpose>
+ </refnamediv>
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>float8 <function>ST_Min4ma</function></funcdef>
- <paramdef><type>float8[][]</type> <parameter>matrix</parameter></paramdef>
- <paramdef><type>text </type> <parameter>nodatamode</parameter></paramdef>
- <paramdef><type>text[]</type> <parameter>VARIADIC args</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>double precision <function>ST_Min4ma</function></funcdef>
- <paramdef><type>double precision[][][]</type> <parameter>value</parameter></paramdef>
- <paramdef><type>integer[][] </type> <parameter>pos</parameter></paramdef>
- <paramdef><type>text[]</type> <parameter>VARIADIC userargs</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>
- Calculate the minimum pixel value in a neighborhood of pixels.
- </para>
-
- <para>
- For Variant 2, a substitution value for NODATA pixels can be specified by passing that value to userargs.
- </para>
-
- <note>
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>box3d <function>Box3D</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>Returns the box representing the extent of the raster.</para>
<para>
- Variant 1 is a specialized callback function for use as a callback parameter to <xref linkend="RT_ST_MapAlgebraFctNgb" />.
+ The polygon is defined by the corner points of the bounding box ((<varname>MINX</varname>, <varname>MINY</varname>), (<varname>MAXX</varname>, <varname>MAXY</varname>))
</para>
- </note>
- <note>
- <para>
- Variant 2 is a specialized callback function for use as a callback parameter to <xref linkend="RT_ST_MapAlgebra" />.
- </para>
- </note>
+ <para>Changed: 2.0.0 In pre-2.0 versions, there used to be a box2d instead of box3d. Since box2d is a deprecated type, this was changed to box3d.</para>
+ </refsection>
+
+ <refsection>
+ <title>Examples</title>
+
+ <programlisting>
+SELECT
+ rid,
+ Box3D(rast) AS rastbox
+FROM dummy_rast;
- <warning>
+rid | rastbox
+----+-------------------------------------------------
+1 | BOX3D(0.5 0.5 0,20.5 60.5 0)
+2 | BOX3D(3427927.75 5793243.5 0,3427928 5793244 0)
+ </programlisting>
+ </refsection>
+
+ <refsection>
+ <title>See Also</title>
<para>
- Use of Variant 1 is discouraged since <xref linkend="RT_ST_MapAlgebraFctNgb" /> has been deprecated as of 2.1.0.
+ <xref linkend="RT_ST_Envelope" />
</para>
- </warning>
+ </refsection>
+ </refentry>
- <para>Availability: 2.0.0</para>
- <para>Enhanced: 2.1.0 Addition of Variant 2</para>
- </refsection>
+ <refentry id="RT_ST_ConvexHull">
+ <refnamediv>
+ <refname>ST_ConvexHull</refname>
+ <refpurpose>Return the convex hull geometry of the raster including pixel values equal to BandNoDataValue.
+ For regular shaped and non-skewed
+ rasters, this gives the same result as ST_Envelope so only useful for irregularly shaped or skewed rasters.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>geometry <function>ST_ConvexHull</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
- <refsection>
- <title>Examples</title>
+ <para>Return the convex hull geometry of the raster including the NoDataBandValue band pixels. For regular shaped and non-skewed
+ rasters, this gives more or less the same result as ST_Envelope
+ so only useful for irregularly shaped or skewed rasters.</para>
+
+ <note><para>ST_Envelope floors the coordinates and hence add a little buffer around the raster so the answer is subtly
+ different from ST_ConvexHull which does not floor.</para>
+ </note>
+ </refsection>
+
+ <refsection>
+ <title>Examples</title>
+ <para>Refer to <ulink url="http://trac.osgeo.org/postgis/wiki/WKTRaster/SpecificationWorking01">PostGIS Raster Specification</ulink> for a diagram of this.</para>
+ <programlisting>
+-- Note envelope and convexhull are more or less the same
+SELECT ST_AsText(ST_ConvexHull(rast)) As convhull,
+ ST_AsText(ST_Envelope(rast)) As env
+FROM dummy_rast WHERE rid=1;
- <programlisting>
-SELECT
- rid,
- st_value(
- st_mapalgebrafctngb(rast, 1, NULL, 1, 1, 'st_min4ma(float[][],text,text[])'::regprocedure, 'ignore', NULL), 2, 2
- )
-FROM dummy_rast
-WHERE rid = 2;
- rid | st_value
------+----------
- 2 | 250
-(1 row)
+ convhull | env
+--------------------------------------------------------+------------------------------------
+ POLYGON((0.5 0.5,20.5 0.5,20.5 60.5,0.5 60.5,0.5 0.5)) | POLYGON((0 0,20 0,20 60,0 60,0 0))
</programlisting>
- </refsection>
+ <programlisting>
+-- now we skew the raster
+-- note how the convex hull and envelope are now different
+SELECT ST_AsText(ST_ConvexHull(rast)) As convhull,
+ ST_AsText(ST_Envelope(rast)) As env
+FROM (SELECT ST_SetRotation(rast, 0.1, 0.1) As rast
+ FROM dummy_rast WHERE rid=1) As foo;
+
+ convhull | env
+--------------------------------------------------------+------------------------------------
+ POLYGON((0.5 0.5,20.5 1.5,22.5 61.5,2.5 60.5,0.5 0.5)) | POLYGON((0 0,22 0,22 61,0 61,0 0))
+ </programlisting>
+ </refsection>
- <refsection>
- <title>See Also</title>
- <para>
- <xref linkend="RT_ST_MapAlgebraFctNgb" />,
- <xref linkend="RT_ST_MapAlgebra" />,
- <xref linkend="RT_ST_Max4ma" />,
- <xref linkend="RT_ST_Sum4ma" />,
- <xref linkend="RT_ST_Mean4ma" />,
- <xref linkend="RT_ST_Range4ma" />,
- <xref linkend="RT_ST_Distinct4ma" />,
- <xref linkend="RT_ST_StdDev4ma" />
- </para>
- </refsection>
- </refentry>
+ <!-- Optionally add a "See Also" section -->
+ <refsection>
+ <title>See Also</title>
+ <para>
+ <xref linkend="RT_ST_Envelope" />,
+ <xref linkend="RT_ST_MinConvexHull" />,
+ <xref linkend="ST_ConvexHull" />,
+ <xref linkend="ST_AsText" />
+ </para>
+ </refsection>
+ </refentry>
- <refentry id="RT_ST_Max4ma">
- <refnamediv>
- <refname>ST_Max4ma</refname>
- <refpurpose>Raster processing function that calculates the maximum pixel value in a neighborhood.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>float8 <function>ST_Max4ma</function></funcdef>
- <paramdef><type>float8[][]</type> <parameter>matrix</parameter></paramdef>
- <paramdef><type>text</type> <parameter>nodatamode</parameter></paramdef>
- <paramdef><type>text[]</type> <parameter>VARIADIC args</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>double precision <function>ST_Max4ma</function></funcdef>
- <paramdef><type>double precision[][][]</type> <parameter>value</parameter></paramdef>
- <paramdef><type>integer[][] </type> <parameter>pos</parameter></paramdef>
- <paramdef><type>text[]</type> <parameter>VARIADIC userargs</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>Calculate the maximum pixel value in a neighborhood of pixels.</para>
-
- <para>
- For Variant 2, a substitution value for NODATA pixels can be specified by passing that value to userargs.
- </para>
-
- <note>
- <para>Variant 1 is a specialized callback function for use as a callback parameter to <xref linkend="RT_ST_MapAlgebraFctNgb" />.</para>
- </note>
-
- <note>
- <para>
- Variant 2 is a specialized callback function for use as a callback parameter to <xref linkend="RT_ST_MapAlgebra" />.
- </para>
- </note>
-
- <warning>
- <para>
- Use of Variant 1 is discouraged since <xref linkend="RT_ST_MapAlgebraFctNgb" /> has been deprecated as of 2.1.0.
- </para>
- </warning>
-
- <para>Availability: 2.0.0</para>
- <para>Enhanced: 2.1.0 Addition of Variant 2</para>
- </refsection>
-
- <refsection>
- <title>Examples</title>
-
- <programlisting>SELECT
- rid,
- st_value(
- st_mapalgebrafctngb(rast, 1, NULL, 1, 1, 'st_max4ma(float[][],text,text[])'::regprocedure, 'ignore', NULL), 2, 2
- )
-FROM dummy_rast
-WHERE rid = 2;
- rid | st_value
------+----------
- 2 | 254
-(1 row)
- </programlisting>
-
- </refsection>
-
- <refsection>
- <title>See Also</title>
- <para>
- <xref linkend="RT_ST_MapAlgebraFctNgb" />,
- <xref linkend="RT_ST_MapAlgebra" />,
- <xref linkend="RT_ST_Min4ma" />,
- <xref linkend="RT_ST_Sum4ma" />,
- <xref linkend="RT_ST_Mean4ma" />,
- <xref linkend="RT_ST_Range4ma" />,
- <xref linkend="RT_ST_Distinct4ma" />,
- <xref linkend="RT_ST_StdDev4ma" />
- </para>
- </refsection>
- </refentry>
-
- <refentry id="RT_ST_Sum4ma">
- <refnamediv>
- <refname>ST_Sum4ma</refname>
- <refpurpose>Raster processing function that calculates the sum of all pixel values in a neighborhood.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>float8 <function>ST_Sum4ma</function></funcdef>
- <paramdef><type>float8[][]</type> <parameter>matrix</parameter></paramdef>
- <paramdef><type>text</type> <parameter>nodatamode</parameter></paramdef>
- <paramdef><type>text[]</type> <parameter>VARIADIC args</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>double precision <function>ST_Sum4ma</function></funcdef>
- <paramdef><type>double precision[][][]</type> <parameter>value</parameter></paramdef>
- <paramdef><type>integer[][] </type> <parameter>pos</parameter></paramdef>
- <paramdef><type>text[]</type> <parameter>VARIADIC userargs</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>Calculate the sum of all pixel values in a neighborhood of pixels.</para>
-
- <para>
- For Variant 2, a substitution value for NODATA pixels can be specified by passing that value to userargs.
- </para>
-
- <note>
- <para>Variant 1 is a specialized callback function for use as a callback parameter to <xref linkend="RT_ST_MapAlgebraFctNgb" />.</para>
- </note>
-
- <note>
- <para>
- Variant 2 is a specialized callback function for use as a callback parameter to <xref linkend="RT_ST_MapAlgebra" />.
- </para>
- </note>
-
- <warning>
- <para>
- Use of Variant 1 is discouraged since <xref linkend="RT_ST_MapAlgebraFctNgb" /> has been deprecated as of 2.1.0.
- </para>
- </warning>
-
- <para>Availability: 2.0.0</para>
- <para>Enhanced: 2.1.0 Addition of Variant 2</para>
- </refsection>
-
- <refsection>
- <title>Examples</title>
-
- <programlisting>SELECT
- rid,
- st_value(
- st_mapalgebrafctngb(rast, 1, '32BF', 1, 1, 'st_sum4ma(float[][],text,text[])'::regprocedure, 'ignore', NULL), 2, 2
- )
-FROM dummy_rast
-WHERE rid = 2;
- rid | st_value
------+----------
- 2 | 2279
-(1 row)
- </programlisting>
-
- </refsection>
-
- <refsection>
- <title>See Also</title>
- <para>
- <xref linkend="RT_ST_MapAlgebraFctNgb" />,
- <xref linkend="RT_ST_MapAlgebra" />,
- <xref linkend="RT_ST_Min4ma" />,
- <xref linkend="RT_ST_Max4ma" />,
- <xref linkend="RT_ST_Mean4ma" />,
- <xref linkend="RT_ST_Range4ma" />,
- <xref linkend="RT_ST_Distinct4ma" />,
- <xref linkend="RT_ST_StdDev4ma" />
- </para>
- </refsection>
- </refentry>
-
- <refentry id="RT_ST_Mean4ma">
- <refnamediv>
- <refname>ST_Mean4ma</refname>
- <refpurpose>Raster processing function that calculates the mean pixel value in a neighborhood.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>float8 <function>ST_Mean4ma</function></funcdef>
- <paramdef><type>float8[][]</type> <parameter>matrix</parameter></paramdef>
- <paramdef><type>text</type> <parameter>nodatamode</parameter></paramdef>
- <paramdef><type>text[]</type> <parameter>VARIADIC args</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>double precision <function>ST_Mean4ma</function></funcdef>
- <paramdef><type>double precision[][][]</type> <parameter>value</parameter></paramdef>
- <paramdef><type>integer[][] </type> <parameter>pos</parameter></paramdef>
- <paramdef><type>text[]</type> <parameter>VARIADIC userargs</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>Calculate the mean pixel value in a neighborhood of pixels.</para>
-
- <para>
- For Variant 2, a substitution value for NODATA pixels can be specified by passing that value to userargs.
- </para>
-
- <note>
- <para>Variant 1 is a specialized callback function for use as a callback parameter to <xref linkend="RT_ST_MapAlgebraFctNgb" />.</para>
- </note>
-
- <note>
- <para>
- Variant 2 is a specialized callback function for use as a callback parameter to <xref linkend="RT_ST_MapAlgebra" />.
- </para>
- </note>
-
- <warning>
- <para>
- Use of Variant 1 is discouraged since <xref linkend="RT_ST_MapAlgebraFctNgb" /> has been deprecated as of 2.1.0.
- </para>
- </warning>
-
- <para>Availability: 2.0.0</para>
- <para>Enhanced: 2.1.0 Addition of Variant 2</para>
- </refsection>
-
- <refsection>
- <title>Examples</title>
-
- <programlisting>SELECT
- rid,
- st_value(
- st_mapalgebrafctngb(rast, 1, '32BF', 1, 1, 'st_mean4ma(float[][],text,text[])'::regprocedure, 'ignore', NULL), 2, 2
- )
-FROM dummy_rast
-WHERE rid = 2;
- rid | st_value
------+------------------
- 2 | 253.222229003906
-(1 row)
- </programlisting>
-
- </refsection>
-
- <refsection>
- <title>See Also</title>
- <para>
- <xref linkend="RT_ST_MapAlgebraFctNgb" />,
- <xref linkend="RT_ST_MapAlgebra" />,
- <xref linkend="RT_ST_Min4ma" />,
- <xref linkend="RT_ST_Max4ma" />,
- <xref linkend="RT_ST_Sum4ma" />,
- <xref linkend="RT_ST_Range4ma" />,
- <xref linkend="RT_ST_StdDev4ma" />
- </para>
- </refsection>
- </refentry>
-
- <refentry id="RT_ST_Range4ma">
- <refnamediv>
- <refname>ST_Range4ma</refname>
- <refpurpose>Raster processing function that calculates the range of pixel values in a neighborhood.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>float8 <function>ST_Range4ma</function></funcdef>
- <paramdef><type>float8[][]</type> <parameter>matrix</parameter></paramdef>
- <paramdef><type>text</type> <parameter>nodatamode</parameter></paramdef>
- <paramdef><type>text[]</type> <parameter>VARIADIC args</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>double precision <function>ST_Range4ma</function></funcdef>
- <paramdef><type>double precision[][][]</type> <parameter>value</parameter></paramdef>
- <paramdef><type>integer[][] </type> <parameter>pos</parameter></paramdef>
- <paramdef><type>text[]</type> <parameter>VARIADIC userargs</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>Calculate the range of pixel values in a neighborhood of pixels.</para>
-
- <para>
- For Variant 2, a substitution value for NODATA pixels can be specified by passing that value to userargs.
- </para>
-
- <note>
- <para>Variant 1 is a specialized callback function for use as a callback parameter to <xref linkend="RT_ST_MapAlgebraFctNgb" />.</para>
- </note>
-
- <note>
- <para>
- Variant 2 is a specialized callback function for use as a callback parameter to <xref linkend="RT_ST_MapAlgebra" />.
- </para>
- </note>
-
- <warning>
- <para>
- Use of Variant 1 is discouraged since <xref linkend="RT_ST_MapAlgebraFctNgb" /> has been deprecated as of 2.1.0.
- </para>
- </warning>
-
- <para>Availability: 2.0.0</para>
- <para>Enhanced: 2.1.0 Addition of Variant 2</para>
- </refsection>
-
- <refsection>
+ <refentry id="RT_ST_DumpAsPolygons">
+ <refnamediv>
+ <refname>ST_DumpAsPolygons</refname>
+ <refpurpose>Returns a set of geomval (geom,val) rows, from a given raster band. If no band number is specified, band num defaults to 1.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>setof geomval <function>ST_DumpAsPolygons</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef choice="opt"><type>integer </type> <parameter>band_num=1</parameter></paramdef>
+ <paramdef choice="opt"><type>boolean </type> <parameter>exclude_nodata_value=TRUE</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+ <para>This is a set-returning function (SRF). It returns a set of
+ geomval rows, formed by a geometry (geom) and a pixel band value (val).
+ Each polygon is the union of all pixels for that band that have the same pixel value denoted by val.</para>
+
+ <para>ST_DumpAsPolygon is useful for polygonizing rasters. It is the
+ reverse of a GROUP BY in that it creates new rows. For example it
+ can be used to expand a single raster into multiple POLYGONS/MULTIPOLYGONS.</para>
+
+ <para>Availability: Requires GDAL 1.7 or higher.</para>
+ <note><para>If there is a no data value set for a band, pixels with that value will not be returned.</para></note>
+ <note><para>If you only care about count of pixels with a given value in a raster, it is faster to use <xref linkend="RT_ST_ValueCount" />.</para></note>
+ <note>
+ <para>
+ This is different than ST_PixelAsPolygons where one geometry is returned for each pixel regardless of pixel value.
+ </para>
+ </note>
+ </refsection>
+
+ <refsection>
<title>Examples</title>
-
- <programlisting>SELECT
- rid,
- st_value(
- st_mapalgebrafctngb(rast, 1, NULL, 1, 1, 'st_range4ma(float[][],text,text[])'::regprocedure, 'ignore', NULL), 2, 2
- )
+ <programlisting>
+SELECT val, ST_AsText(geom) As geomwkt
+FROM (
+SELECT (ST_DumpAsPolygons(rast)).*
FROM dummy_rast
-WHERE rid = 2;
- rid | st_value
------+----------
- 2 | 4
-(1 row)
- </programlisting>
-
- </refsection>
-
- <refsection>
- <title>See Also</title>
- <para>
- <xref linkend="RT_ST_MapAlgebraFctNgb" />,
- <xref linkend="RT_ST_MapAlgebra" />,
- <xref linkend="RT_ST_Min4ma" />,
- <xref linkend="RT_ST_Max4ma" />,
- <xref linkend="RT_ST_Sum4ma" />,
- <xref linkend="RT_ST_Mean4ma" />,
- <xref linkend="RT_ST_Distinct4ma" />,
- <xref linkend="RT_ST_StdDev4ma" />
- </para>
- </refsection>
- </refentry>
-
- <refentry id="RT_ST_Distinct4ma">
- <refnamediv>
- <refname>ST_Distinct4ma</refname>
- <refpurpose>Raster processing function that calculates the number of unique pixel values in a neighborhood.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>float8 <function>ST_Distinct4ma</function></funcdef>
- <paramdef><type>float8[][]</type> <parameter>matrix</parameter></paramdef>
- <paramdef><type>text</type> <parameter>nodatamode</parameter></paramdef>
- <paramdef><type>text[]</type> <parameter>VARIADIC args</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>double precision <function>ST_Distinct4ma</function></funcdef>
- <paramdef><type>double precision[][][]</type> <parameter>value</parameter></paramdef>
- <paramdef><type>integer[][] </type> <parameter>pos</parameter></paramdef>
- <paramdef><type>text[]</type> <parameter>VARIADIC userargs</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>Calculate the number of unique pixel values in a neighborhood of pixels.</para>
-
- <note>
- <para>Variant 1 is a specialized callback function for use as a callback parameter to <xref linkend="RT_ST_MapAlgebraFctNgb" />.</para>
- </note>
+WHERE rid = 2
+) As foo
+WHERE val BETWEEN 249 and 251
+ORDER BY val;
- <note>
- <para>
- Variant 2 is a specialized callback function for use as a callback parameter to <xref linkend="RT_ST_MapAlgebra" />.
- </para>
- </note>
+ val | geomwkt
+-----+--------------------------------------------------------------------------
+ 249 | POLYGON((3427927.95 5793243.95,3427927.95 5793243.85,3427928 5793243.85,
+ 3427928 5793243.95,3427927.95 5793243.95))
+ 250 | POLYGON((3427927.75 5793243.9,3427927.75 5793243.85,3427927.8 5793243.85,
+ 3427927.8 5793243.9,3427927.75 5793243.9))
+ 250 | POLYGON((3427927.8 5793243.8,3427927.8 5793243.75,3427927.85 5793243.75,
+ 3427927.85 5793243.8, 3427927.8 5793243.8))
+ 251 | POLYGON((3427927.75 5793243.85,3427927.75 5793243.8,3427927.8 5793243.8,
+ 3427927.8 5793243.85,3427927.75 5793243.85))
+ </programlisting>
+ </refsection>
- <warning>
+ <refsection>
+ <title>See Also</title>
<para>
- Use of Variant 1 is discouraged since <xref linkend="RT_ST_MapAlgebraFctNgb" /> has been deprecated as of 2.1.0.
+ <xref linkend="geomval" />,
+ <xref linkend="RT_ST_Value" />,
+ <xref linkend="RT_ST_Polygon" />,
+ <xref linkend="RT_ST_ValueCount" />
</para>
- </warning>
-
- <para>Availability: 2.0.0</para>
- <para>Enhanced: 2.1.0 Addition of Variant 2</para>
- </refsection>
-
- <refsection>
- <title>Examples</title>
-
- <programlisting>SELECT
- rid,
- st_value(
- st_mapalgebrafctngb(rast, 1, NULL, 1, 1, 'st_distinct4ma(float[][],text,text[])'::regprocedure, 'ignore', NULL), 2, 2
- )
-FROM dummy_rast
-WHERE rid = 2;
- rid | st_value
------+----------
- 2 | 3
-(1 row)
- </programlisting>
-
- </refsection>
-
- <refsection>
- <title>See Also</title>
- <para>
- <xref linkend="RT_ST_MapAlgebraFctNgb" />,
- <xref linkend="RT_ST_MapAlgebra" />,
- <xref linkend="RT_ST_Min4ma" />,
- <xref linkend="RT_ST_Max4ma" />,
- <xref linkend="RT_ST_Sum4ma" />,
- <xref linkend="RT_ST_Mean4ma" />,
- <xref linkend="RT_ST_Distinct4ma" />,
- <xref linkend="RT_ST_StdDev4ma" />
- </para>
- </refsection>
- </refentry>
+ </refsection>
+ </refentry>
- <refentry id="RT_ST_StdDev4ma">
- <refnamediv>
- <refname>ST_StdDev4ma</refname>
- <refpurpose>Raster processing function that calculates the standard deviation of pixel values in a neighborhood.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>float8 <function>ST_StdDev4ma</function></funcdef>
- <paramdef><type>float8[][]</type> <parameter>matrix</parameter></paramdef>
- <paramdef><type>text </type> <parameter>nodatamode</parameter></paramdef>
- <paramdef><type>text[]</type> <parameter>VARIADIC args</parameter></paramdef>
- </funcprototype>
+ <refentry id="RT_ST_Envelope">
+ <refnamediv>
+ <refname>ST_Envelope</refname>
+ <refpurpose>Returns the polygon representation of the extent of the raster.</refpurpose>
+ </refnamediv>
- <funcprototype>
- <funcdef>double precision <function>ST_StdDev4ma</function></funcdef>
- <paramdef><type>double precision[][][]</type> <parameter>value</parameter></paramdef>
- <paramdef><type>integer[][] </type> <parameter>pos</parameter></paramdef>
- <paramdef><type>text[]</type> <parameter>VARIADIC userargs</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>geometry <function>ST_Envelope</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
- <para>Calculate the standard deviation of pixel values in a neighborhood of pixels.</para>
-
- <note>
- <para>Variant 1 is a specialized callback function for use as a callback parameter to <xref linkend="RT_ST_MapAlgebraFctNgb" />.</para>
- </note>
+ <refsection>
+ <title>Description</title>
- <note>
- <para>
- Variant 2 is a specialized callback function for use as a callback parameter to <xref linkend="RT_ST_MapAlgebra" />.
- </para>
- </note>
+ <para>Returns the polygon representation of the extent of the raster in spatial coordinate units defined by srid. It is a float8 minimum bounding box represented as a polygon. </para>
- <warning>
- <para>
- Use of Variant 1 is discouraged since <xref linkend="RT_ST_MapAlgebraFctNgb" /> has been deprecated as of 2.1.0.
+ <para>The polygon is defined by the corner points of the bounding box
+ ((<varname>MINX</varname>, <varname>MINY</varname>),
+ (<varname>MINX</varname>, <varname>MAXY</varname>),
+ (<varname>MAXX</varname>, <varname>MAXY</varname>),
+ (<varname>MAXX</varname>, <varname>MINY</varname>),
+ (<varname>MINX</varname>, <varname>MINY</varname>))
</para>
- </warning>
-
- <para>Availability: 2.0.0</para>
- <para>Enhanced: 2.1.0 Addition of Variant 2</para>
- </refsection>
+ </refsection>
<refsection>
<title>Examples</title>
- <programlisting>SELECT
- rid,
- st_value(
- st_mapalgebrafctngb(rast, 1, '32BF', 1, 1, 'st_stddev4ma(float[][],text,text[])'::regprocedure, 'ignore', NULL), 2, 2
- )
-FROM dummy_rast
-WHERE rid = 2;
- rid | st_value
------+------------------
- 2 | 1.30170822143555
-(1 row)
- </programlisting>
-
- </refsection>
-
- <refsection>
- <title>See Also</title>
- <para>
- <xref linkend="RT_ST_MapAlgebraFctNgb" />,
- <xref linkend="RT_ST_MapAlgebra" />,
- <xref linkend="RT_ST_Min4ma" />,
- <xref linkend="RT_ST_Max4ma" />,
- <xref linkend="RT_ST_Sum4ma" />,
- <xref linkend="RT_ST_Mean4ma" />,
- <xref linkend="RT_ST_Distinct4ma" />,
- <xref linkend="RT_ST_StdDev4ma" />
- </para>
- </refsection>
- </refentry>
+ <programlisting>
+SELECT rid, ST_AsText(ST_Envelope(rast)) As envgeomwkt
+FROM dummy_rast;
+
+ rid | envgeomwkt
+-----+--------------------------------------------------------------------
+ 1 | POLYGON((0 0,20 0,20 60,0 60,0 0))
+ 2 | POLYGON((3427927 5793243,3427928 5793243,
+ 3427928 5793244,3427927 5793244, 3427927 5793243))
+ </programlisting>
+ </refsection>
- <refentry id="RT_ST_InvDistWeight4ma">
- <refnamediv>
- <refname>ST_InvDistWeight4ma</refname>
- <refpurpose>Raster processing function that interpolates a pixel's value from the pixel's neighborhood.</refpurpose>
- </refnamediv>
+ <refsection>
+ <title>See Also</title>
+ <para>
+ <xref linkend="ST_Envelope" />,
+ <xref linkend="ST_AsText" />,
+ <xref linkend="RT_ST_SRID" />
+ </para>
+ </refsection>
+ </refentry>
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>double precision <function>ST_InvDistWeight4ma</function></funcdef>
- <paramdef><type>double precision[][][]</type> <parameter>value</parameter></paramdef>
- <paramdef><type>integer[][]</type> <parameter>pos</parameter></paramdef>
- <paramdef><type>text[]</type> <parameter>VARIADIC userargs</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
+ <refentry id="RT_ST_MinConvexHull">
+ <refnamediv>
+ <refname>ST_MinConvexHull</refname>
+ <refpurpose>
+ Return the convex hull geometry of the raster excluding NODATA pixels.
+ </refpurpose>
+ </refnamediv>
- <refsection>
- <title>Description</title>
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>geometry <function>ST_MinConvexHull</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef choice="opt"><type>integer </type> <parameter>nband=NULL</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
- <para>Calculate an interpolated value for a pixel using the Inverse Distance Weighted method.</para>
+ <refsection>
+ <title>Description</title>
- <para>
- There are two optional parameters that can be passed through <varname>userargs</varname>. The first parameter is the power factor (variable k in the equation below) between 0 and 1 used in the Inverse Distance Weighted equation. If not specified, default value is 1. The second parameter is the weight percentage applied only when the value of the pixel of interest is included with the interpolated value from the neighborhood. If not specified and the pixel of interest has a value, that value is returned.
- </para>
+ Return the convex hull geometry of the raster excluding NODATA pixels. If <varname>nband</varname> is NULL, all bands of the raster are considered.
+ </para>
- <para>
- The basic inverse distance weight equation is:
+ <para>Availability: 2.1.0 </para>
+ </refsection>
- <informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_invdistweight4ma_equation.png" />
- </imageobject>
- <caption>
- <para>
- k = power factor, a real number between 0 and 1
- </para>
- </caption>
- </mediaobject>
- </informalfigure>
- </para>
+ <refsection>
+ <title>Examples</title>
+ <programlisting>
+WITH foo AS (
+ SELECT
+ ST_SetValues(
+ ST_SetValues(
+ ST_AddBand(ST_AddBand(ST_MakeEmptyRaster(9, 9, 0, 0, 1, -1, 0, 0, 0), 1, '8BUI', 0, 0), 2, '8BUI', 1, 0),
+ 1, 1, 1,
+ ARRAY[
+ [0, 0, 0, 0, 0, 0, 0, 0, 0],
+ [0, 0, 0, 0, 0, 0, 0, 0, 0],
+ [0, 0, 0, 0, 0, 0, 0, 0, 0],
+ [0, 0, 0, 1, 0, 0, 0, 0, 1],
+ [0, 0, 0, 1, 1, 0, 0, 0, 0],
+ [0, 0, 0, 1, 0, 0, 0, 0, 0],
+ [0, 0, 0, 0, 0, 0, 0, 0, 0],
+ [0, 0, 0, 0, 0, 0, 0, 0, 0],
+ [0, 0, 0, 0, 0, 0, 0, 0, 0]
+ ]::double precision[][]
+ ),
+ 2, 1, 1,
+ ARRAY[
+ [0, 0, 0, 0, 0, 0, 0, 0, 0],
+ [0, 0, 0, 0, 0, 0, 0, 0, 0],
+ [0, 0, 0, 0, 0, 0, 0, 0, 0],
+ [1, 0, 0, 0, 0, 1, 0, 0, 0],
+ [0, 0, 0, 0, 1, 1, 0, 0, 0],
+ [0, 0, 0, 0, 0, 1, 0, 0, 0],
+ [0, 0, 0, 0, 0, 0, 0, 0, 0],
+ [0, 0, 0, 0, 0, 0, 0, 0, 0],
+ [0, 0, 1, 0, 0, 0, 0, 0, 0]
+ ]::double precision[][]
+ ) AS rast
+)
+SELECT
+ ST_AsText(ST_ConvexHull(rast)) AS hull,
+ ST_AsText(ST_MinConvexHull(rast)) AS mhull,
+ ST_AsText(ST_MinConvexHull(rast, 1)) AS mhull_1,
+ ST_AsText(ST_MinConvexHull(rast, 2)) AS mhull_2
+FROM foo
- <note>
- <para>This function is a specialized callback function for use as a callback parameter to <xref linkend="RT_ST_MapAlgebra" />.</para>
- </note>
+ hull | mhull | mhull_1 | mhull_2
+----------------------------------+-------------------------------------+-------------------------------------+-------------------------------------
+ POLYGON((0 0,9 0,9 -9,0 -9,0 0)) | POLYGON((0 -3,9 -3,9 -9,0 -9,0 -3)) | POLYGON((3 -3,9 -3,9 -6,3 -6,3 -3)) | POLYGON((0 -3,6 -3,6 -9,0 -9,0 -3))
+ </programlisting>
+ </refsection>
+
+ <refsection>
+ <title>See Also</title>
+ <para>
+ <xref linkend="RT_ST_Envelope" />,
+ <xref linkend="RT_ST_ConvexHull" />,
+ <xref linkend="ST_ConvexHull" />,
+ <xref linkend="ST_AsText" />
+ </para>
+ </refsection>
+ </refentry>
+
+ <refentry id="RT_ST_Polygon">
+ <refnamediv>
+ <refname>ST_Polygon</refname>
+ <refpurpose>Returns a multipolygon geometry formed by the union of pixels that have a pixel value that is not no data value. If no band number is specified, band num defaults to 1.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>geometry <function>ST_Polygon</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef choice="opt"><type>integer </type> <parameter>band_num=1</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+ <para>Availability: 0.1.6 Requires GDAL 1.7 or higher.</para>
+ <para>Enhanced: 2.1.0 Improved Speed (fully C-Based) and the returning multipolygon is ensured to be valid.</para>
+ <para>Changed: 2.1.0 In prior versions would sometimes return a polygon, changed to always return multipolygon.</para>
+ </refsection>
- <para>Availability: 2.1.0</para>
- </refsection>
+ <refsection>
+ <title>Examples</title>
+ <programlisting>
+-- by default no data band value is 0 or not set, so polygon will return a square polygon
+SELECT ST_AsText(ST_Polygon(rast)) As geomwkt
+FROM dummy_rast
+WHERE rid = 2;
- <refsection>
- <title>Examples</title>
- <programlisting>
--- NEEDS EXAMPLE
- </programlisting>
- </refsection>
+geomwkt
+--------------------------------------------
+MULTIPOLYGON(((3427927.75 5793244,3427928 5793244,3427928 5793243.75,3427927.75 5793243.75,3427927.75 5793244)))
+
+
+-- now we change the no data value of first band
+UPDATE dummy_rast SET rast = ST_SetBandNoDataValue(rast,1,254)
+WHERE rid = 2;
+SELECt rid, ST_BandNoDataValue(rast)
+from dummy_rast where rid = 2;
- <refsection>
- <title>See Also</title>
- <para>
- <xref linkend="RT_ST_MapAlgebra" />,
- <xref linkend="RT_ST_MinDist4ma" />
- </para>
- </refsection>
- </refentry>
+-- ST_Polygon excludes the pixel value 254 and returns a multipolygon
+SELECT ST_AsText(ST_Polygon(rast)) As geomwkt
+FROM dummy_rast
+WHERE rid = 2;
- <refentry id="RT_ST_MinDist4ma">
- <refnamediv>
- <refname>ST_MinDist4ma</refname>
- <refpurpose>Raster processing function that returns the minimum distance (in number of pixels) between the pixel of interest and a neighboring pixel with value.</refpurpose>
- </refnamediv>
+geomwkt
+---------------------------------------------------------
+MULTIPOLYGON(((3427927.9 5793243.95,3427927.85 5793243.95,3427927.85 5793244,3427927.9 5793244,3427927.9 5793243.95)),((3427928 5793243.85,3427928 5793243.8,3427927.95 5793243.8,3427927.95 5793243.85,3427927.9 5793243.85,3427927.9 5793243.9,3427927.9 5793243.95,3427927.95 5793243.95,3427928 5793243.95,3427928 5793243.85)),((3427927.8 5793243.75,3427927.75 5793243.75,3427927.75 5793243.8,3427927.75 5793243.85,3427927.75 5793243.9,3427927.75 5793244,3427927.8 5793244,3427927.8 5793243.9,3427927.8 5793243.85,3427927.85 5793243.85,3427927.85 5793243.8,3427927.85 5793243.75,3427927.8 5793243.75)))
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>double precision <function>ST_MinDist4ma</function></funcdef>
- <paramdef><type>double precision[][][]</type> <parameter>value</parameter></paramdef>
- <paramdef><type>integer[][]</type> <parameter>pos</parameter></paramdef>
- <paramdef><type>text[]</type> <parameter>VARIADIC userargs</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
+-- Or if you want the no data value different for just one time
- <refsection>
- <title>Description</title>
+SELECT ST_AsText(
+ ST_Polygon(
+ ST_SetBandNoDataValue(rast,1,252)
+ )
+ ) As geomwkt
+FROM dummy_rast
+WHERE rid =2;
- <para>Return the shortest distance (in number of pixels) between the pixel of interest and the closest pixel with value in the neighborhood.</para>
+geomwkt
+---------------------------------
+MULTIPOLYGON(((3427928 5793243.85,3427928 5793243.8,3427928 5793243.75,3427927.85 5793243.75,3427927.8 5793243.75,3427927.8 5793243.8,3427927.75 5793243.8,3427927.75 5793243.85,3427927.75 5793243.9,3427927.75 5793244,3427927.8 5793244,3427927.85 5793244,3427927.9 5793244,3427928 5793244,3427928 5793243.95,3427928 5793243.85),(3427927.9 5793243.9,3427927.9 5793243.85,3427927.95 5793243.85,3427927.95 5793243.9,3427927.9 5793243.9)))
+ </programlisting>
+ </refsection>
- <note>
+ <refsection>
+ <title>See Also</title>
<para>
- The intent of this function is to provide an informative data point that helps infer the usefulness of the pixel of interest's interpolated value from <xref linkend="RT_ST_InvDistWeight4ma" />. This function is particularly useful when the neighborhood is sparsely populated.
+ <xref linkend="RT_ST_Value" />,
+ <xref linkend="RT_ST_DumpAsPolygons" />
</para>
- </note>
-
- <note>
- <para>This function is a specialized callback function for use as a callback parameter to <xref linkend="RT_ST_MapAlgebra" />.</para>
- </note>
-
- <para>Availability: 2.1.0</para>
- </refsection>
-
- <refsection>
- <title>Examples</title>
- <programlisting>
--- NEEDS EXAMPLE
- </programlisting>
- </refsection>
+ </refsection>
+ </refentry>
- <refsection>
- <title>See Also</title>
- <para>
- <xref linkend="RT_ST_MapAlgebra" />,
- <xref linkend="RT_ST_InvDistWeight4ma" />
- </para>
- </refsection>
- </refentry>
+ </sect2> <!-- /misc -->
</sect1>
-
+
<sect1 id="RT_Operators">
<title>Raster Operators</title>
<refentry id="RT_Raster_Intersect">
projects / postgis / commitdiff