<sect1 id="Raster_Processing">
<title>Raster Processing</title>
- <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>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>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>
-
- <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;
-
-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><xref linkend="RT_ST_Envelope" /></para>
- </refsection>
- </refentry>
- <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>
+ <sect2 id="Raster_Processing_MapAlgebra">
+ <title>Map Algebra</title>
+
+ <refentry id="RT_ST_Clip">
+ <refnamediv>
+ <refname>ST_Clip</refname>
+ <refpurpose>Returns the raster clipped by the input geometry. If band number not is specified, all bands are processed. If <varname>crop</varname> is not specified or TRUE, the output raster is cropped.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+
+ <funcprototype>
+ <funcdef>raster <function>ST_Clip</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>integer[] </type> <parameter>nband</parameter></paramdef>
+ <paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
+ <paramdef choice="opt"><type>double precision[] </type> <parameter>nodataval=NULL</parameter></paramdef>
+ <paramdef choice="opt"><type>boolean </type> <parameter>crop=TRUE</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>raster <function>ST_Clip</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>nband</parameter></paramdef>
+ <paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
+ <paramdef><type>double precision </type> <parameter>nodataval</parameter></paramdef>
+ <paramdef choice="opt"><type>boolean </type> <parameter>crop=TRUE</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>raster <function>ST_Clip</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>nband</parameter></paramdef>
+ <paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
+ <paramdef><type>boolean </type> <parameter>crop</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>raster <function>ST_Clip</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
+ <paramdef choice="opt"><type>double precision[] </type> <parameter>nodataval=NULL</parameter></paramdef>
+ <paramdef choice="opt"><type>boolean </type> <parameter>crop=TRUE</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>raster <function>ST_Clip</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
+ <paramdef><type>double precision </type> <parameter>nodataval</parameter></paramdef>
+ <paramdef choice="opt"><type>boolean </type> <parameter>crop=TRUE</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>raster <function>ST_Clip</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
+ <paramdef><type>boolean </type> <parameter>crop</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>
- <varname>units</varname> indicates the units of the aspect. Possible values are: RADIANS, DEGREES (default).
- </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>.
+ Returns a raster that is clipped by the input geometry <varname>geom</varname>. If band index is not specified, all bands are processed.
</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: 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
-
- 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_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_Clip">
- <refnamediv>
- <refname>ST_Clip</refname>
- <refpurpose>Returns the raster clipped by the input geometry. If band number not is specified, all bands are processed. If <varname>crop</varname> is not specified or TRUE, the output raster is cropped.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
-
- <funcprototype>
- <funcdef>raster <function>ST_Clip</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
- <paramdef><type>integer[] </type> <parameter>nband</parameter></paramdef>
- <paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
- <paramdef choice="opt"><type>double precision[] </type> <parameter>nodataval=NULL</parameter></paramdef>
- <paramdef choice="opt"><type>boolean </type> <parameter>crop=TRUE</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>raster <function>ST_Clip</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
- <paramdef><type>integer </type> <parameter>nband</parameter></paramdef>
- <paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
- <paramdef><type>double precision </type> <parameter>nodataval</parameter></paramdef>
- <paramdef choice="opt"><type>boolean </type> <parameter>crop=TRUE</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>raster <function>ST_Clip</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
- <paramdef><type>integer </type> <parameter>nband</parameter></paramdef>
- <paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
- <paramdef><type>boolean </type> <parameter>crop</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>raster <function>ST_Clip</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
- <paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
- <paramdef choice="opt"><type>double precision[] </type> <parameter>nodataval=NULL</parameter></paramdef>
- <paramdef choice="opt"><type>boolean </type> <parameter>crop=TRUE</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>raster <function>ST_Clip</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
- <paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
- <paramdef><type>double precision </type> <parameter>nodataval</parameter></paramdef>
- <paramdef choice="opt"><type>boolean </type> <parameter>crop=TRUE</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>raster <function>ST_Clip</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
- <paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
- <paramdef><type>boolean </type> <parameter>crop</parameter></paramdef>
- </funcprototype>
-
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>
- Returns a raster that is clipped by the input geometry <varname>geom</varname>. If band index is not specified, all bands are processed.
- </para>
- <para>
- Rasters resulting from ST_Clip must have a nodata value assigned for areas clipped, one for each band. If none are provided and the input raster do not have a nodata value defined, nodata values of the resulting raster are set to ST_MinPossibleValue(ST_BandPixelType(rast, band)). When the number of nodata value in the array is smaller than the number of band, the last one in the array is used for the remaining bands. If the number of nodata value is greater than the number of band, the extra nodata values are ignored. All variants accepting an array of nodata values also accept a single value which will be assigned to each band.
- </para>
+ Rasters resulting from ST_Clip must have a nodata value assigned for areas clipped, one for each band. If none are provided and the input raster do not have a nodata value defined, nodata values of the resulting raster are set to ST_MinPossibleValue(ST_BandPixelType(rast, band)). When the number of nodata value in the array is smaller than the number of band, the last one in the array is used for the remaining bands. If the number of nodata value is greater than the number of band, the extra nodata values are ignored. All variants accepting an array of nodata values also accept a single value which will be assigned to each band.
+ </para>
- <para>
- If <varname>crop</varname> is not specified, true is assumed meaning the output raster is cropped to the intersection of the <varname>geom</varname>and <varname>rast</varname> extents. If <varname>crop</varname> is set to false, the new raster gets the same extent as <varname>rast</varname>.
- </para>
+ If <varname>crop</varname> is not specified, true is assumed meaning the output raster is cropped to the intersection of the <varname>geom</varname>and <varname>rast</varname> extents. If <varname>crop</varname> is set to false, the new raster gets the same extent as <varname>rast</varname>.
+ </para>
- <para>Availability: 2.0.0 </para>
+
<para>Availability: 2.0.0 </para>
- <para>Enhanced: 2.1.0 Rewritten in C</para>
+
<para>Enhanced: 2.1.0 Rewritten in C</para>
- <para>
- Examples here use Massachusetts aerial data available on MassGIS site <ulink url="http://www.mass.gov/mgis/colororthos2008.htm">MassGIS Aerial Orthos</ulink>. Coordinates are in Massachusetts State Plane Meters.
- </para>
- </refsection>
+
Examples here use Massachusetts aerial data available on MassGIS site <ulink url="http://www.mass.gov/mgis/colororthos2008.htm">MassGIS Aerial Orthos</ulink>. Coordinates are in Massachusetts State Plane Meters.
+ </para>
+ </refsection>
- <refsection>
- <title>Examples: 1 band clipping</title>
+ <refsection>
+ <title>Examples: 1 band clipping</title>
- <programlisting>
-- Clip the first band of an aerial tile by a 20 meter buffer.
SELECT ST_Clip(rast, 1,
ST_Buffer(ST_Centroid(ST_Envelope(rast)),20)
) from aerials.boston
WHERE rid = 4;
- </programlisting>
+ </programlisting>
- <programlisting>
-- Demonstrate effect of crop on final dimensions of raster
-- Note how final extent is clipped to that of the geometry
-- if crop = true
xmax_w_trim | xmax_clipper | xmax_wo_trim | xmax_rast_orig
------------------+------------------+------------------+------------------
230657.436173996 | 230657.436173996 | 230666.436173996 | 230666.436173996
- </programlisting>
+ </programlisting>
- <informaltable>
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>
- <para>
- <informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_clip01.png" />
- </imageobject>
- <caption>
- <para>Full raster tile before clipping</para>
- </caption>
- </mediaobject>
- </informalfigure>
- </para>
- </entry>
- <entry>
- <para>
- <informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_clip02.png" />
- </imageobject>
- <caption>
- <para>After Clipping</para>
- </caption>
- </mediaobject>
- </informalfigure>
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </refsection>
-
- <refsection>
- <title>Examples: 1 band clipping with no crop and add back other bands unchanged</title>
+ <informaltable>
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_clip01.png" />
+ </imageobject>
+ <caption>
+ <para>Full raster tile before clipping</para>
+ </caption>
+ </mediaobject>
+ </informalfigure>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_clip02.png" />
+ </imageobject>
+ <caption>
+ <para>After Clipping</para>
+ </caption>
+ </mediaobject>
+ </informalfigure>
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </refsection>
- <programlisting>
+ <refsection>
+ <title>Examples: 1 band clipping with no crop and add back other bands unchanged</title>
+
+ <programlisting>
-- Same example as before, but we need to set crop to false to be able to use ST_AddBand
-- because ST_AddBand requires all bands be the same Width and height
SELECT ST_AddBand(ST_Clip(rast, 1,
ST_Buffer(ST_Centroid(ST_Envelope(rast)),20),false
), ARRAY[ST_Band(rast,2),ST_Band(rast,3)] ) from aerials.boston
WHERE rid = 6;
- </programlisting>
+ </programlisting>
- <informaltable>
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>
- <para>
- <informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_clip04.png" />
- </imageobject>
- <caption>
- <para>Full raster tile before clipping</para>
- </caption>
- </mediaobject>
- </informalfigure>
- </para>
- </entry>
- <entry>
- <para>
- <informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_clip05.png" />
- </imageobject>
- <caption>
- <para>After Clipping - surreal</para>
- </caption>
- </mediaobject>
- </informalfigure>
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </refsection>
-
- <refsection>
- <title>Examples: Clip all bands</title>
+ <informaltable>
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_clip04.png" />
+ </imageobject>
+ <caption>
+ <para>Full raster tile before clipping</para>
+ </caption>
+ </mediaobject>
+ </informalfigure>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_clip05.png" />
+ </imageobject>
+ <caption>
+ <para>After Clipping - surreal</para>
+ </caption>
+ </mediaobject>
+ </informalfigure>
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </refsection>
- <programlisting>
+ <refsection>
+ <title>Examples: Clip all bands</title>
+
+ <programlisting>
-- Clip all bands of an aerial tile by a 20 meter buffer.
-- Only difference is we don't specify a specific band to clip
-- so all bands are clipped
false
) from aerials.boston
WHERE rid = 4;
- </programlisting>
+ </programlisting>
- <informaltable>
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>
- <para>
- <informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_clip01.png" />
- </imageobject>
- <caption>
- <para>Full raster tile before clipping</para>
- </caption>
- </mediaobject>
- </informalfigure>
- </para>
- </entry>
- <entry>
- <para>
- <informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_clip03.png" />
- </imageobject>
- <caption>
- <para>After Clipping</para>
- </caption>
- </mediaobject>
- </informalfigure>
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </refsection>
+ <informaltable>
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_clip01.png" />
+ </imageobject>
+ <caption>
+
<para>Full raster tile before clipping</para>
+ </caption>
+ </mediaobject>
+ </informalfigure>
+ </para>
+ </entry>
+ <entry>
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_clip03.png" />
+ </imageobject>
+ <caption>
+
<para>After Clipping</para>
+ </caption>
+ </mediaobject>
+ </informalfigure>
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </refsection>
- <!-- Optionally add a "See Also" section -->
- <refsection>
- <title>See Also</title>
- <para>
- <xref linkend="RT_ST_AddBand" />,
- <xref linkend="RT_ST_MapAlgebra" />,
- <xref linkend="RT_ST_Intersection" />
- </para>
- </refsection>
- </refentry>
-
- <refentry id="RT_ST_ColorMap">
- <refnamediv>
- <refname>ST_ColorMap</refname>
- <refpurpose>Creates a new raster of up to four 8BUI bands (grayscale, RGB, RGBA) from the source raster and a specified band. Band 1 is assumed if not specified.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>raster <function>ST_ColorMap</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>colormap=grayscale</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>method=INTERPOLATE</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
+ <!-- Optionally add a "See Also" section -->
+ <refsection>
+ <title>See Also</title>
+ <para>
+ <xref linkend="RT_ST_AddBand" />,
+ <xref linkend="RT_ST_MapAlgebra" />,
+ <xref linkend="RT_ST_Intersection" />
+ </para>
+ </refsection>
+ </refentry>
+
+ <refentry id="RT_ST_ColorMap">
+ <refnamediv>
+ <refname>ST_ColorMap</refname>
+ <refpurpose>Creates a new raster of up to four 8BUI bands (grayscale, RGB, RGBA) from the source raster and a specified band. Band 1 is assumed if not specified.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>raster <function>ST_ColorMap</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>colormap=grayscale</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>method=INTERPOLATE</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>raster <function>ST_ColorMap</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>text </type> <parameter>colormap</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>method=INTERPOLATE</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>raster <function>ST_ColorMap</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
- <paramdef><type>text </type> <parameter>colormap</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>method=INTERPOLATE</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
+ <refsection>
+ <title>Description</title>
- <refsection>
- <title>Description</title>
+ <para>
+ Apply a <varname>colormap</varname> to the band at <varname>nband</varname> of <varname>rast</varname> resulting a new raster comprised of up to four 8BUI bands. The number of 8BUI bands in the new raster is determined by the number of color components defined in <varname>colormap</varname>.
+ </para>
- <para>
- Apply a <varname>colormap</varname> to the band at <varname>nband</varname> of <varname>rast</varname> resulting a new raster comprised of up to four 8BUI bands. The number of 8BUI bands in the new raster is determined by the number of color components defined in <varname>colormap</varname>.
- </para>
- <para>If <varname>nband</varname> is not specified, then band 1 is assumed.</para>
+ <para>If <varname>nband</varname> is not specified, then band 1 is assumed.</para>
- <para>
- <varname>colormap</varname> can be a keyword of a pre-defined colormap or a set of lines defining the value and the color components.
- </para>
+ <varname>colormap</varname> can be a keyword of a pre-defined colormap or a set of lines defining the value and the color components.
+ </para>
- <para>
- Valid pre-defined <varname>colormap</varname> keyword:
- </para>
+ Valid pre-defined <varname>colormap</varname> keyword:
+ </para>
- <itemizedlist>
- <listitem>
- <para>
- <varname>grayscale</varname> or <varname>greyscale</varname> for a one 8BUI band raster of shades of gray.
- </para>
- </listitem>
- <listitem>
- <para>
- <varname>pseudocolor</varname> for a four 8BUI (RGBA) band raster with colors going from blue to green to red.
- </para>
- </listitem>
- <listitem>
- <para>
- <varname>fire</varname> for a four 8BUI (RGBA) band raster with colors going from black to red to pale yellow.
- </para>
- </listitem>
- <listitem>
- <para>
- <varname>bluered</varname> for a four 8BUI (RGBA) band raster with colors going from blue to pale white to red.
- </para>
- </listitem>
- </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <varname>grayscale</varname> or <varname>greyscale</varname> for a one 8BUI band raster of shades of gray.
+ </para>
+ </listitem>
+ <listitem>
+ <varname>pseudocolor</varname> for a four 8BUI (RGBA) band raster with colors going from blue to green to red.
+ </para>
+ </listitem>
+ <listitem>
+ <varname>fire</varname> for a four 8BUI (RGBA) band raster with colors going from black to red to pale yellow.
+ </para>
+ </listitem>
+ <listitem>
+ <varname>bluered</varname> for a four 8BUI (RGBA) band raster with colors going from blue to pale white to red.
+ </para>
+ </listitem>
+ </itemizedlist>
- <para>
- Users can pass a set of entries (one per line) to <varname>colormap</varname> to specify custom colormaps. Each entry generally consists of five values: the pixel value and corresponding Red, Green, Blue, Alpha components (color components between 0 and 255). Percent values can be used instead of pixel values where 0% and 100% are the minimum and maximum values found in the raster band. Values can be separated with commas (','), tabs, colons (':') and/or spaces. The pixel value can be set to <emphasis>nv</emphasis>, <emphasis>null</emphasis> or <emphasis>nodata</emphasis> for the NODATA value. An example is provided below.
- </para>
+ Users can pass a set of entries (one per line) to <varname>colormap</varname> to specify custom colormaps. Each entry generally consists of five values: the pixel value and corresponding Red, Green, Blue, Alpha components (color components between 0 and 255). Percent values can be used instead of pixel values where 0% and 100% are the minimum and maximum values found in the raster band. Values can be separated with commas (','), tabs, colons (':') and/or spaces. The pixel value can be set to <emphasis>nv</emphasis>, <emphasis>null</emphasis> or <emphasis>nodata</emphasis> for the NODATA value. An example is provided below.
+ </para>
- <programlisting>
5 0 0 0 255
4 100:50 55 255
1 150,100 150 255
0% 255 255 255 255
nv 0 0 0 0
- </programlisting>
+ </programlisting>
- <para>
- The syntax of <varname>colormap</varname> is similar to that of the color-relief mode of GDAL <ulink url="http://www.gdal.org/gdaldem.html#gdaldem_color_relief">gdaldem</ulink>.
- </para>
+
The syntax of <varname>colormap</varname> is similar to that of the color-relief mode of GDAL <ulink url="http://www.gdal.org/gdaldem.html#gdaldem_color_relief">gdaldem</ulink>.
+ </para>
- <para>
- Valid keywords for <varname>method</varname>:
- </para>
+ Valid keywords for <varname>method</varname>:
+ </para>
- <itemizedlist>
- <listitem>
- <para>
- <varname>INTERPOLATE</varname> to use linear interpolation to smoothly blend the colors between the given pixel values
- </para>
- </listitem>
- <listitem>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <varname>INTERPOLATE</varname> to use linear interpolation to smoothly blend the colors between the given pixel values
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>EXACT</varname> to strictly match only those pixels values found in the colormap. Pixels whose value does not match a colormap entry will be set to 0 0 0 0 (RGBA)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>NEAREST</varname> to use the colormap entry whose value is closest to the pixel value
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <note>
<para>
- <varname>EXACT</varname> to strictly match only those pixels values found in the colormap. Pixels whose value does not match a colormap entry will be set to 0 0 0 0 (RGBA)
+ A great reference for colormaps is <ulink url="http://www.colorbrewer2.org">ColorBrewer</ulink>.
</para>
- </listitem>
- <listitem>
+ </note>
+ <warning>
<para>
- <varname>NEAREST</varname> to use the colormap entry whose value is closest to the pixel value
+ The resulting bands of new raster will have no NODATA value set. Use <xref linkend="RT_ST_SetBandNoDataValue" /> to set a NODATA value if one is needed.
</para>
- </listitem>
- </itemizedlist>
+ </warning>
- <note>
- <para>
- A great reference for colormaps is <ulink url="http://www.colorbrewer2.org">ColorBrewer</ulink>.
- </para>
- </note>
- <warning>
- <para>
- The resulting bands of new raster will have no NODATA value set. Use <xref linkend="RT_ST_SetBandNoDataValue" /> to set a NODATA value if one is needed.
- </para>
- </warning>
+ <para>Availability: 2.1.0 </para>
+ </refsection>
- <para>Availability: 2.1.0 </para>
- </refsection>
+ <refsection>
+ <title>Examples</title>
+ <para>This is a junk table to play with</para>
- <refsection>
- <title>Examples</title>
- <para>This is a junk table to play with</para>
- <programlisting>
+ <programlisting>
-- setup test raster table --
DROP TABLE IF EXISTS funky_shapes;
CREATE TABLE funky_shapes(rast raster);
+
INSERT INTO funky_shapes(rast)
-WITH ref As (
- SELECT ST_MakeEmptyRaster( 200, 200, 0, 200, 1, -1, 0, 0) As rast
- )
-SELECT ST_Union(rast)
-FROM (SELECT
- ST_AsRaster(
- ST_Rotate(ST_Buffer(
- ST_GeomFromText('LINESTRING(0 2,50 50,150 150,125 50)'), i*2
- ), pi()*i*0.125, ST_Point(50,50))
- , ref.rast, '8BUI'::text, i*5) As rast
- FROM ref cross JOIN generate_series(1,10,3) As i ) As shapes ;</programlisting>
-<programlisting>SELECT ST_NumBands(rast) As n_orig
- , ST_NumBands(ST_ColorMap(rast,1, 'greyscale')) As ngrey
- , ST_NumBands(ST_ColorMap(rast,1, 'pseudocolor')) As npseudo
- , ST_NumBands(ST_ColorMap(rast,1, 'fire')) As nfire
- , ST_NumBands(ST_ColorMap(rast,1, 'bluered')) As nbluered
- , ST_NumBands(ST_ColorMap(rast,1, '100% 255 0 0
-80% 160 0 0
-50% 130 0 0
-30% 30 0 0
-20% 60 0 0
-0% 0 0 0
-nv 255 255 255')) As nred
-FROM funky_shapes;</programlisting>
-<screen>
+WITH ref AS (
+ SELECT ST_MakeEmptyRaster( 200, 200, 0, 200, 1, -1, 0, 0) AS rast
+)
+SELECT
+ ST_Union(rast)
+FROM (
+ SELECT
+ ST_AsRaster(
+ ST_Rotate(
+ ST_Buffer(
+ ST_GeomFromText('LINESTRING(0 2,50 50,150 150,125 50)'),
+ i*2
+ ),
+ pi() * i * 0.125, ST_Point(50,50)
+ ),
+ ref.rast, '8BUI'::text, i * 5
+ ) AS rast
+ FROM ref
+ CROSS JOIN generate_series(1, 10, 3) AS i
+) AS shapes;
+ </programlisting>
+
+ <programlisting>
+SELECT
+ ST_NumBands(rast) As n_orig,
+ ST_NumBands(ST_ColorMap(rast,1, 'greyscale')) As ngrey,
+ ST_NumBands(ST_ColorMap(rast,1, 'pseudocolor')) As npseudo,
+ ST_NumBands(ST_ColorMap(rast,1, 'fire')) As nfire,
+ ST_NumBands(ST_ColorMap(rast,1, 'bluered')) As nbluered,
+ ST_NumBands(ST_ColorMap(rast,1, '
+100% 255 0 0
+ 80% 160 0 0
+ 50% 130 0 0
+ 30% 30 0 0
+ 20% 60 0 0
+ 0% 0 0 0
+ nv 255 255 255
+ ')) As nred
+FROM funky_shapes;
+ </programlisting>
+
+ <screen>
n_orig | ngrey | npseudo | nfire | nbluered | nred
--------+-------+---------+-------+----------+------
1 | 1 | 4 | 4 | 4 | 3
-</screen>
- </refsection>
- <refsection><title>Examples: Compare different color map looks using ST_AsPNG</title>
- <programlisting>SELECT ST_AsPNG(rast) As orig_png
- , ST_AsPNG(ST_ColorMap(rast,1,'greyscale')) As grey_png
- , ST_AsPNG(ST_ColorMap(rast,1, 'pseudocolor')) As pseudo_png
- , ST_AsPNG(ST_ColorMap(rast,1, 'nfire')) As fire_png
- , ST_AsPNG(ST_ColorMap(rast,1, 'bluered')) As bluered_png
- , ST_AsPNG(ST_ColorMap(rast,1, '100% 255 0 0
-80% 160 0 0
-50% 130 0 0
-30% 30 0 0
-20% 60 0 0
-0% 0 0 0
-nv 255 255 255')) As red_png
-FROM funky_shapes;</programlisting>
+ </screen>
+ </refsection>
-<informaltable>
- <tgroup cols="3">
- <tbody>
- <row>
- <entry><para><informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_colormap_orig.png" />
- </imageobject>
- <caption><para>orig_png</para></caption>
- </mediaobject>
- </informalfigure></para>
- </entry>
- <entry><para><informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_colormap_grey.png" />
- </imageobject>
- <caption><para>grey_png</para></caption>
- </mediaobject>
- </informalfigure></para>
- </entry>
- <entry><para><informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_colormap_pseudo.png" />
- </imageobject>
- <caption><para>pseudo_png</para></caption>
- </mediaobject>
- </informalfigure></para>
- </entry>
- </row>
- <row>
- <entry><para><informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_colormap_fire.png" />
- </imageobject>
- <caption><para>fire_png</para></caption>
- </mediaobject>
- </informalfigure></para>
- </entry>
- <entry><para><informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_colormap_bluered.png" />
- </imageobject>
- <caption><para>bluered_png</para></caption>
- </mediaobject>
- </informalfigure></para>
- </entry>
- <entry><para><informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_colormap_red.png" />
- </imageobject>
- <caption><para>red_png</para></caption>
- </mediaobject>
- </informalfigure></para>
- </entry>
- </row>
- </tbody>
-</tgroup>
-</informaltable>
- </refsection>
+ <refsection>
+ <title>Examples: Compare different color map looks using ST_AsPNG</title>
+ <programlisting>
+SELECT
+ ST_AsPNG(rast) As orig_png,
+ ST_AsPNG(ST_ColorMap(rast,1,'greyscale')) As grey_png,
+ ST_AsPNG(ST_ColorMap(rast,1, 'pseudocolor')) As pseudo_png,
+ ST_AsPNG(ST_ColorMap(rast,1, 'nfire')) As fire_png,
+ ST_AsPNG(ST_ColorMap(rast,1, 'bluered')) As bluered_png,
+ ST_AsPNG(ST_ColorMap(rast,1, '
+100% 255 0 0
+ 80% 160 0 0
+ 50% 130 0 0
+ 30% 30 0 0
+ 20% 60 0 0
+ 0% 0 0 0
+ nv 255 255 255
+ ')) As red_png
+FROM funky_shapes;
+ </programlisting>
- <refsection>
- <title>See Also</title>
- <para>
- <xref linkend="RT_ST_AsPNG" />,
- <xref linkend="RT_ST_AsRaster" />
- <xref linkend="RT_ST_MapAlgebra" />,
- <xref linkend="RT_ST_NumBands" />,
- <xref linkend="RT_ST_Reclass" />,
- <xref linkend="RT_ST_SetBandNoDataValue" />,
- <xref linkend="RT_ST_Union" />
- </para>
- </refsection>
- </refentry>
+ <informaltable>
+ <tgroup cols="3">
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_colormap_orig.png" />
+ </imageobject>
+ <caption>
+ <para>orig_png</para>
+ </caption>
+ </mediaobject>
+ </informalfigure>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_colormap_grey.png" />
+ </imageobject>
+ <caption>
+ <para>grey_png</para>
+ </caption>
+ </mediaobject>
+ </informalfigure>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_colormap_pseudo.png" />
+ </imageobject>
+ <caption>
+ <para>pseudo_png</para>
+ </caption>
+ </mediaobject>
+ </informalfigure>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_colormap_fire.png" />
+ </imageobject>
+ <caption>
+ <para>fire_png</para>
+ </caption>
+ </mediaobject>
+ </informalfigure>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_colormap_bluered.png" />
+ </imageobject>
+ <caption>
+ <para>bluered_png</para>
+ </caption>
+ </mediaobject>
+ </informalfigure>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_colormap_red.png" />
+ </imageobject>
+ <caption>
+ <para>red_png</para>
+ </caption>
+ </mediaobject>
+ </informalfigure>
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </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>See Also</title>
+ <para>
+ <xref linkend="RT_ST_AsPNG" />,
+ <xref linkend="RT_ST_AsRaster" />
+ <xref linkend="RT_ST_MapAlgebra" />,
+ <xref linkend="RT_ST_NumBands" />,
+ <xref linkend="RT_ST_Reclass" />,
+ <xref linkend="RT_ST_SetBandNoDataValue" />,
+ <xref linkend="RT_ST_Union" />
+ </para>
+ </refsection>
+ </refentry>
+
+ <refentry id="RT_ST_Intersection">
+ <refnamediv>
+ <refname>ST_Intersection</refname>
+ <refpurpose>Returns a raster or a set of geometry-pixelvalue pairs representing the shared portion of two rasters or the geometrical intersection of a vectorization of the raster and a geometry.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>setof geomval <function>ST_Intersection</function></funcdef>
+ <paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef choice="opt"><type>integer </type> <parameter>band_num=1</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>setof geomval <function>ST_Intersection</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>setof geomval <function>ST_Intersection</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>band_num</parameter></paramdef>
+ <paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>raster <function>ST_Intersection</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast1</parameter></paramdef>
+ <paramdef><type>raster </type> <parameter>rast2</parameter></paramdef>
+ <paramdef><type>double precision[] </type> <parameter>nodataval</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>raster <function>ST_Intersection</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast1</parameter></paramdef>
+ <paramdef><type>raster </type> <parameter>rast2</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>returnband='BOTH'</parameter></paramdef>
+ <paramdef choice="opt"><type>double precision[] </type> <parameter>nodataval=NULL</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>raster <function>ST_Intersection</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast1</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>band_num1</parameter></paramdef>
+ <paramdef><type>raster </type> <parameter>rast2</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>band_num2</parameter></paramdef>
+ <paramdef><type>double precision[] </type> <parameter>nodataval</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>raster <function>ST_Intersection</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast1</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>band_num1</parameter></paramdef>
+ <paramdef><type>raster </type> <parameter>rast2</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>band_num2</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>returnband='BOTH'</parameter></paramdef>
+ <paramdef choice="opt"><type>double precision[] </type> <parameter>nodataval=NULL</parameter></paramdef>
+ </funcprototype>
+
+ </funcsynopsis>
+ </refsynopsisdiv>
- <refsection>
- <title>Description</title>
+ <refsection>
+ <title>Description</title>
+ <para>
+ Returns a raster or a set of geometry-pixelvalue pairs representing the shared portion of two rasters or the geometrical intersection of a vectorization of the raster and a geometry.
+ </para>
+
+ <para>
+ The first three variants, returning a setof geomval, works in vector space. The raster is first vectorized (using ST_DumpAsPolygon) into a set of geomval rows and those rows are then intersected with the geometry using the ST_Intersection(geometry, geometry) PostGIS function. Geometries intersecting only with a nodata value area of a raster returns an empty geometry. They are normally excluded from the results by the proper usage of ST_Intersect in the WHERE clause.
+ </para>
- <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>
+ <para>
+ You can access the geometry and the value parts of the resulting set of geomval by surrounding them with parenthesis and adding '.geom' or '.val' at the end of the expression. e.g. (ST_Intersection(rast, geom)).geom
+ </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>
+ <para>
+ The other variants, returning a raster, works in raster space. They are using the two rasters version of ST_MapAlgebraExpr to perform the intersection.
+ </para>
- <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>
+ <para>
+ The extent of the resulting raster corresponds to the geometrical intersection of the two raster extents. The resulting raster includes 'BAND1', 'BAND2' or 'BOTH' bands, following what is passed as the <varname>returnband</varname> parameter. Nodata value areas present in any band results in nodata value areas in every bands of the result. In other words, any pixel intersecting with a nodata value pixel becomes a nodata value pixel in the result.
+ </para>
+
+ <para>
+ Rasters resulting from ST_Intersection must have a nodata value assigned for areas not intersecting. You can define or replace the nodata value for any resulting band by providing a <varname>nodataval[]</varname> array of one or two nodata values depending if you request 'BAND1', 'BAND2' or 'BOTH' bands. The first value in the array replace the nodata value in the first band and the second value replace the nodata value in the second band. If one input band do not have a nodata value defined and none are provided as an array, one is chosen using the ST_MinPossibleValue function. All variant accepting an array of nodata value can also accept a single value which will be assigned to each requested band.
+ </para>
- <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.
+ In all variants, if no band number is specified band 1 is assumed.
</para>
- </note>
- </refsection>
-
- <refsection>
- <title>Examples</title>
- <programlisting>SELECT val, ST_AsText(geom) As geomwkt
+
+ <note>
+ <para>
+ To get more control on the resulting extent or on what to return when encountering a nodata value, use the two rasters version of <xref linkend="RT_ST_MapAlgebraExpr2" />.
+ </para>
+ </note>
+
+ <note>
+ <para>
+ To compute the intersection of a raster band with a geometry in raster space, use <xref linkend="RT_ST_Clip" />. ST_Clip works on multiple bands rasters and does not return a band corresponding to the rasterized geometry.
+ </para>
+ </note>
+
+ <note>
+ <para>
+ ST_Intersection should be used in conjunction with ST_Intersects and an index on the raster column and/or the geometry column.
+ </para>
+ </note>
+
+ <para>
+ Enhanced: 2.0.0 - Intersection in the raster space was introduced. In earlier pre-2.0.0 versions, only intersection performed in vector space were supported.
+ </para>
+ </refsection>
+
+ <refsection>
+ <title>Examples: Geometry, Raster -- resulting in geometry vals</title>
+
+ <programlisting>
+SELECT
+ foo.rid,
+ foo.gid,
+ ST_AsText((foo.geomval).geom) As geomwkt,
+ (foo.geomval).val
FROM (
-SELECT (ST_DumpAsPolygons(rast)).*
-FROM dummy_rast
-WHERE rid = 2
-) As foo
-WHERE val BETWEEN 249 and 251
-ORDER BY val;
+ SELECT
+ A.rid,
+ g.gid,
+ ST_Intersection(A.rast, g.geom) As geomval
+ FROM dummy_rast AS A
+ CROSS JOIN (
+ VALUES
+ (1, ST_Point(3427928, 5793243.85) ),
+ (2, ST_GeomFromText('LINESTRING(3427927.85 5793243.75,3427927.8 5793243.75,3427927.8 5793243.8)')),
+ (3, ST_GeomFromText('LINESTRING(1 2, 3 4)'))
+ ) As g(gid,geom)
+ WHERE A.rid = 2
+) As 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))
- </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" /></para>
- </refsection>
- </refentry>
-
- <refentry id="RT_ST_Envelope">
- <refnamediv>
- <refname>ST_Envelope</refname>
- <refpurpose>Returns the polygon representation of the extent of the raster.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>geometry <function>ST_Envelope</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast</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>
+ rid | gid | geomwkt | val
+-----+-----+---------------------------------------------------------------------------------------------
+ 2 | 1 | POINT(3427928 5793243.85) | 249
+ 2 | 1 | POINT(3427928 5793243.85) | 253
+ 2 | 2 | POINT(3427927.85 5793243.75) | 254
+ 2 | 2 | POINT(3427927.8 5793243.8) | 251
+ 2 | 2 | POINT(3427927.8 5793243.8) | 253
+ 2 | 2 | LINESTRING(3427927.8 5793243.75,3427927.8 5793243.8) | 252
+ 2 | 2 | MULTILINESTRING((3427927.8 5793243.8,3427927.8 5793243.75),...) | 250
+ 2 | 3 | GEOMETRYCOLLECTION EMPTY
+ </programlisting>
</refsection>
-
+
<refsection>
- <title>Examples</title>
-
- <programlisting>SELECT rid, ST_AsText(ST_Envelope(rast)) As envgeomwkt
-FROM dummy_rast;
+ <title>Example: Raster, Geometry -- resulting is a raster</title>
+ <para>Examples coming soon</para>
+ <!-- TODO: EXAMPLES coming soon -->
+ </refsection>
- 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>
+ <refsection>
+ <title>See Also</title>
+ <para>
+ <xref linkend="geomval" />,
+ <xref linkend="RT_ST_Intersects" />,
+ <xref linkend="RT_ST_MapAlgebraExpr2" />,
+ <xref linkend="RT_ST_Clip" />,
+ <xref linkend="ST_AsText" />
+ </para>
+ </refsection>
+ </refentry>
+
+ <refentry id="RT_ST_MapAlgebra">
+ <refnamediv>
+ <refname>ST_MapAlgebra</refname>
+ <refpurpose>
+ Callback function version - Returns a one-band raster given one or more input rasters, band indexes and one user-specified callback function.
+ </refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+
+ <funcprototype>
+ <funcdef>raster <function>ST_MapAlgebra</function></funcdef>
+ <paramdef><type>rastbandarg[] </type> <parameter>rastbandargset</parameter></paramdef>
+ <paramdef><type>regprocedure </type> <parameter>callbackfunc</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>pixeltype=NULL</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>extenttype=INTERSECTION</parameter></paramdef>
+ <paramdef choice="opt"><type>raster </type> <parameter>customextent=NULL</parameter></paramdef>
+ <paramdef choice="opt"><type>integer </type> <parameter>distancex=0</parameter></paramdef>
+ <paramdef choice="opt"><type>integer </type> <parameter>distancey=0</parameter></paramdef>
+ <paramdef choice="opt"><type>text[] </type> <parameter>VARIADIC userargs=NULL</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>raster <function>ST_MapAlgebra</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>integer[] </type> <parameter>nband</parameter></paramdef>
+ <paramdef><type>regprocedure </type> <parameter>callbackfunc</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>pixeltype=NULL</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>extenttype=FIRST</parameter></paramdef>
+ <paramdef choice="opt"><type>raster </type> <parameter>customextent=NULL</parameter></paramdef>
+ <paramdef choice="opt"><type>integer </type> <parameter>distancex=0</parameter></paramdef>
+ <paramdef choice="opt"><type>integer </type> <parameter>distancey=0</parameter></paramdef>
+ <paramdef choice="opt"><type>text[] </type> <parameter>VARIADIC userargs=NULL</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>raster <function>ST_MapAlgebra</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>nband</parameter></paramdef>
+ <paramdef><type>regprocedure </type> <parameter>callbackfunc</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>pixeltype=NULL</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>extenttype=FIRST</parameter></paramdef>
+ <paramdef choice="opt"><type>raster </type> <parameter>customextent=NULL</parameter></paramdef>
+ <paramdef choice="opt"><type>integer </type> <parameter>distancex=0</parameter></paramdef>
+ <paramdef choice="opt"><type>integer </type> <parameter>distancey=0</parameter></paramdef>
+ <paramdef choice="opt"><type>text[] </type> <parameter>VARIADIC userargs=NULL</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>raster <function>ST_MapAlgebra</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast1</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>nband1</parameter></paramdef>
+ <paramdef><type>raster </type> <parameter>rast2</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>nband2</parameter></paramdef>
+ <paramdef><type>regprocedure </type> <parameter>callbackfunc</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>pixeltype=NULL</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>extenttype=INTERSECTION</parameter></paramdef>
+ <paramdef choice="opt"><type>raster </type> <parameter>customextent=NULL</parameter></paramdef>
+ <paramdef choice="opt"><type>integer </type> <parameter>distancex=0</parameter></paramdef>
+ <paramdef choice="opt"><type>integer </type> <parameter>distancey=0</parameter></paramdef>
+ <paramdef choice="opt"><type>text[] </type> <parameter>VARIADIC userargs=NULL</parameter></paramdef>
+ </funcprototype>
+
+ </funcsynopsis>
+ </refsynopsisdiv>
- <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_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>
+ <refsection>
+ <title>Description</title>
- <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>
-
- <refsection>
- <title>Description</title>
+ <para>
+ Returns a one-band raster given one or more input rasters, band indexes and one user-specified callback function.
+ </para>
- <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>
+ <variablelist>
+ <varlistentry>
+ <term>rast,rast1,rast2, rastbandargset</term>
+ <listitem>
+ <para>
+ Rasters on which the map algebra process is evaluated.</para><para><varname>rastbandargset</varname> allows the use of a map algebra operation on many rasters and/or many bands. See example Variant 1.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>nband, nband1, nband2</term>
+ <listitem>
+ <para>
+ Band numbers of the raster to be evaluated. nband can be an integer or integer[] denoting the bands. nband1 is band on rast1 and nband2 is band on rast2 for hte 2 raster/2band case.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>callbackfunc</term>
+ <listitem>
+ <para>
+ The <varname>callbackfunc</varname> parameter must be the name and signature of an SQL or PL/pgSQL function, cast to a regprocedure. An example PL/pgSQL function example is:
+ <programlisting>
+CREATE OR REPLACE FUNCTION sample_callbackfunc(value double precision[][][], position integer[][], VARIADIC userargs text[])
+ RETURNS double precision
+ AS $$
+ BEGIN
+ RETURN 0;
+ END;
+ $$ LANGUAGE 'plpgsql' IMMUTABLE;
+ </programlisting>
- <para>
- <varname>azimuth</varname> is a value between 0 and 360 degrees measured clockwise from North.
- </para>
+ The <varname>callbackfunc</varname> must have three arguments: a 3-dimension double precision array, a 2-dimension integer array and a variadic 1-dimension text array. The first argument <varname>value</varname> is the set of values (as double precision) from all input rasters. The three dimensions (where indexes are 1-based) are: raster #, row y, column x. The second argument <varname>position</varname> is the set of pixel positions from the output raster and input rasters. The outer dimension (where indexes are 0-based) is the raster #. The position at outer dimension index 0 is the output raster's pixel position. For each outer dimension, there are two elements in the inner dimension for X and Y. The third argument <varname>userargs</varname> is for passing through any user-specified arguments.
+ </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>
+ Passing a <type>regprocedure</type> argument to a SQL function requires the full function signature to be passed, then cast to a <type>regprocedure</type> type. To pass the above example PL/pgSQL function as an argument, the SQL for the argument is:
- <para>
- <varname>max_bright</varname> is a value between 0 and 255 with 0 as no brightness and 255 as max brightness.
- </para>
+ <programlisting>
+'sample_callbackfunc(double precision[], integer[], text[])'::regprocedure
+ </programlisting>
- <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>
+ Note that the argument contains the name of the function, the types of the function arguments, quotes around the name and argument types, and a cast to a <type>regprocedure</type>.
+ </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>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>pixeltype</term>
+ <listitem>
+ <para>
+ If <varname>pixeltype</varname> is passed in, the one band of the new raster will be of that pixeltype. If pixeltype is passed NULL or left out, the new raster band will have the same pixeltype as the specified band of the first raster (for extent types: INTERSECTION, UNION, FIRST, CUSTOM) or the specified band of the appropriate raster (for extent types: SECOND, LAST). If in doubt, always specify <varname>pixeltype</varname>.
+ </para>
+ <para>
+ The resulting pixel type of the output raster must be one listed in <xref linkend="RT_ST_BandPixelType" /> or left out or set to NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>extenttype</term>
+ <listitem>
+ <para>
+ Possible values are INTERSECTION (default), UNION, FIRST (default for one raster variants), SECOND, LAST, CUSTOM.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>customextent</term>
+ <listitem>
+ <para>
+ If <varname>extentype</varname> is CUSTOM, a raster must be provided for <varname>customextent</varname>. See example 4 of Variant 1.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>distancex</term>
+ <listitem>
+ <para>
+ The distance in pixels from the reference cell. So width of resulting matrix would be <code>2*distancex + 1</code>.If not specified only the reference cell is considered (neighborhood of 0).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>distancey</term>
+ <listitem>
+ <para>
+ The distance in pixels from reference cell in y direction. Height of resulting matrix would be <code>2*distancey + 1</code> .If not specified only the reference cell is considered (neighborhood of 0).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>userargs</term>
+ <listitem>
+ <para>
+ The third argument to the <varname>callbackfunc</varname> is a <type>variadic text</type> array. All trailing text arguments are passed through to the specified <varname>callbackfunc</varname>, and are contained in the <varname>userargs</varname> argument.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <note>
+ <para>
+ For more information about the VARIADIC keyword, please refer to the PostgreSQL documentation and the "SQL Functions with Variable Numbers of Arguments" section of <ulink url="http://www.postgresql.org/docs/current/static/xfunc-sql.html">Query Language (SQL) Functions</ulink>.
+ </para>
+ </note>
+
+ <note>
+ <para>
+ The <type>text[]</type> argument to the <varname>callbackfunc</varname> is required, regardless of whether you choose to pass any arguments to the callback function for processing or not.
+ </para>
+ </note>
- <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>.
+ Variant 1 accepts an array of <varname>rastbandarg</varname> allowing the use of a map algebra operation on many rasters and/or many bands. See example Variant 1.
</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>
+ <para>
+ Variants 2 and 3 operate upon one or more bands of one raster. See example Variant 2 and 3.
+ </para>
- </refsection>
-
- <refsection>
- <title>Examples: Variant 1</title>
- <programlisting>
+ <para>
+ Variant 4 operate upon two rasters with one band per raster. See example Variant 4.
+ </para>
+
+ <para>Availability: 2.1.0</para>
+
+ </refsection>
+
+ <refsection>
+ <title>Examples: Variant 1</title>
+
+ <para>One raster, one band</para>
+ <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[][]
+ SELECT 1 AS rid, ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, 0, 1, -1, 0, 0, 0), 1, '16BUI', 1, 0) AS rast
+)
+SELECT
+ ST_MapAlgebra(
+ ARRAY[ROW(rast, 1)]::rastbandarg[],
+ 'sample_callbackfunc(double precision[], int[], text[])'::regprocedure
) AS rast
+FROM foo
+ </programlisting>
+
+ <para>One raster, several bands</para>
+ <programlisting>
+WITH foo AS (
+ SELECT 1 AS rid, ST_AddBand(ST_AddBand(ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, 0, 1, -1, 0, 0, 0), 1, '16BUI', 1, 0), 2, '8BUI', 10, 0), 3, '32BUI', 100, 0) AS rast
)
SELECT
- ST_DumpValues(ST_Hillshade(rast, 1, '32BF'))
+ ST_MapAlgebra(
+ ARRAY[ROW(rast, 3), ROW(rast, 1), ROW(rast, 3), ROW(rast, 2)]::rastbandarg[],
+ 'sample_callbackfunc(double precision[], int[], text[])'::regprocedure
+ ) AS rast
FROM foo
+ </programlisting>
- 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>
- <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="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_Intersection">
- <refnamediv>
- <refname>ST_Intersection</refname>
- <refpurpose>Returns a raster or a set of geometry-pixelvalue pairs representing the shared portion of two rasters or the geometrical intersection of a vectorization of the raster and a geometry.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>setof geomval <function>ST_Intersection</function></funcdef>
- <paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
- <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
- <paramdef choice="opt"><type>integer </type> <parameter>band_num=1</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>setof geomval <function>ST_Intersection</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
- <paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>setof geomval <function>ST_Intersection</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
- <paramdef><type>integer </type> <parameter>band_num</parameter></paramdef>
- <paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>raster <function>ST_Intersection</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast1</parameter></paramdef>
- <paramdef><type>raster </type> <parameter>rast2</parameter></paramdef>
- <paramdef><type>double precision[] </type> <parameter>nodataval</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>raster <function>ST_Intersection</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast1</parameter></paramdef>
- <paramdef><type>raster </type> <parameter>rast2</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>returnband='BOTH'</parameter></paramdef>
- <paramdef choice="opt"><type>double precision[] </type> <parameter>nodataval=NULL</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>raster <function>ST_Intersection</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast1</parameter></paramdef>
- <paramdef><type>integer </type> <parameter>band_num1</parameter></paramdef>
- <paramdef><type>raster </type> <parameter>rast2</parameter></paramdef>
- <paramdef><type>integer </type> <parameter>band_num2</parameter></paramdef>
- <paramdef><type>double precision[] </type> <parameter>nodataval</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>raster <function>ST_Intersection</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast1</parameter></paramdef>
- <paramdef><type>integer </type> <parameter>band_num1</parameter></paramdef>
- <paramdef><type>raster </type> <parameter>rast2</parameter></paramdef>
- <paramdef><type>integer </type> <parameter>band_num2</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>returnband='BOTH'</parameter></paramdef>
- <paramdef choice="opt"><type>double precision[] </type> <parameter>nodataval=NULL</parameter></paramdef>
- </funcprototype>
-
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
- <para>Returns a raster or a set of geometry-pixelvalue pairs representing the shared portion of two rasters or the geometrical intersection of a vectorization of the raster and a geometry.</para>
-
- <para>The first three variants, returning a setof geomval, works in vector space. The raster is first vectorized (using ST_DumpAsPolygon) into a set of geomval rows and those rows are then intersected with the geometry using the ST_Intersection(geometry, geometry) PostGIS function. Geometries intersecting only with a nodata value area of a raster returns an empty geometry. They are normally excluded from the results by the proper usage of ST_Intersect in the WHERE clause.</para>
-
- <para>You can access the geometry and the value parts of the resulting set of geomval by surrounding them with parenthesis and adding '.geom' or '.val' at the end of the expression. e.g. (ST_Intersection(rast, geom)).geom</para>
-
- <para>The other variants, returning a raster, works in raster space. They are using the two rasters version of ST_MapAlgebraExpr to perform the intersection.</para>
-
- <para>The extent of the resulting raster corresponds to the geometrical intersection of the two raster extents. The resulting raster includes 'BAND1', 'BAND2' or 'BOTH' bands, following what is passed as the <varname>returnband</varname> parameter. Nodata value areas present in any band results in nodata value areas in every bands of the result. In other words, any pixel intersecting with a nodata value pixel becomes a nodata value pixel in the result.</para>
-
- <para>Rasters resulting from ST_Intersection must have a nodata value assigned for areas not intersecting. You can define or replace the nodata value for any resulting band by providing a <varname>nodataval[]</varname> array of one or two nodata values depending if you request 'BAND1', 'BAND2' or 'BOTH' bands. The first value in the array replace the nodata value in the first band and the second value replace the nodata value in the second band. If one input band do not have a nodata value defined and none are provided as an array, one is chosen using the ST_MinPossibleValue function. All variant accepting an array of nodata value can also accept a single value which will be assigned to each requested band.</para>
-
- <para>In all variants, if no band number is specified band 1 is assumed.</para>
-
- <note><para>To get more control on the resulting extent or on what to return when encountering a nodata value, use the two rasters version of <xref linkend="RT_ST_MapAlgebraExpr2" />.</para></note>
-
- <note><para>To compute the intersection of a raster band with a geometry in raster space, use <xref linkend="RT_ST_Clip" />. ST_Clip works on multiple bands rasters and does not return a band corresponding to the rasterized geometry.</para></note>
-
- <note><para>ST_Intersection should be used in conjunction with ST_Intersects and an index on the raster column and/or the geometry column.</para></note>
-
- <para>Enhanced: 2.0.0 - Intersection in the raster space was introduced. In earlier pre-2.0.0 versions, only intersection performed in vector space were supported.</para>
- </refsection>
-
- <refsection>
- <title>Examples: Geometry, Raster -- resulting in geometry vals</title>
-
- <programlisting>SELECT foo.rid, foo.gid,
- ST_AsText((foo.geomval).geom) As geomwkt, (foo.geomval).val
-FROM
- (
-SELECT A.rid, g.gid , ST_Intersection(A.rast, g.geom) As geomval
- FROM dummy_rast AS A CROSS JOIN
- (VALUES (1, ST_Point(3427928, 5793243.85) ) ,
- (2, ST_GeomFromText('LINESTRING(3427927.85 5793243.75,3427927.8 5793243.75,3427927.8 5793243.8)') ),
- (3, ST_GeomFromText('LINESTRING(1 2, 3 4)') )
- ) As g(gid,geom)
-WHERE A.rid =2 ) As foo;
-
- rid | gid | geomwkt | val
------+-----+---------------------------------------------------------------------------------------------
- 2 | 1 | POINT(3427928 5793243.85) | 249
- 2 | 1 | POINT(3427928 5793243.85) | 253
- 2 | 2 | POINT(3427927.85 5793243.75) | 254
- 2 | 2 | POINT(3427927.8 5793243.8) | 251
- 2 | 2 | POINT(3427927.8 5793243.8) | 253
- 2 | 2 | LINESTRING(3427927.8 5793243.75,3427927.8 5793243.8) | 252
- 2 | 2 | MULTILINESTRING((3427927.8 5793243.8,3427927.8 5793243.75),...) | 250
- 2 | 3 | GEOMETRYCOLLECTION EMPTY
-</programlisting>
-
- </refsection>
-
- <refsection>
- <title>Example: Raster, Geometry -- resulting is a raster</title>
- <para>Examples coming soon</para>
- <!-- TODO: EXAMPLES coming soon -->
- </refsection>
-
-
- <refsection>
- <title>See Also</title>
- <para><xref linkend="geomval" />, <xref linkend="RT_ST_Intersects" />, <xref linkend="RT_ST_MapAlgebraExpr2" />, <xref linkend="RT_ST_Clip" />, <xref linkend="ST_AsText" /></para>
- </refsection>
- </refentry>
-
- <refentry id="RT_ST_MapAlgebra">
- <refnamediv>
- <refname>ST_MapAlgebra</refname>
- <refpurpose>
- Callback function version - Returns a one-band raster given one or more input rasters, band indexes and one user-specified callback function.
- </refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
-
- <funcprototype>
- <funcdef>raster <function>ST_MapAlgebra</function></funcdef>
- <paramdef><type>rastbandarg[] </type> <parameter>rastbandargset</parameter></paramdef>
- <paramdef><type>regprocedure </type> <parameter>callbackfunc</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>pixeltype=NULL</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>extenttype=INTERSECTION</parameter></paramdef>
- <paramdef choice="opt"><type>raster </type> <parameter>customextent=NULL</parameter></paramdef>
- <paramdef choice="opt"><type>integer </type> <parameter>distancex=0</parameter></paramdef>
- <paramdef choice="opt"><type>integer </type> <parameter>distancey=0</parameter></paramdef>
- <paramdef choice="opt"><type>text[] </type> <parameter>VARIADIC userargs=NULL</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>raster <function>ST_MapAlgebra</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
- <paramdef><type>integer[] </type> <parameter>nband</parameter></paramdef>
- <paramdef><type>regprocedure </type> <parameter>callbackfunc</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>pixeltype=NULL</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>extenttype=FIRST</parameter></paramdef>
- <paramdef choice="opt"><type>raster </type> <parameter>customextent=NULL</parameter></paramdef>
- <paramdef choice="opt"><type>integer </type> <parameter>distancex=0</parameter></paramdef>
- <paramdef choice="opt"><type>integer </type> <parameter>distancey=0</parameter></paramdef>
- <paramdef choice="opt"><type>text[] </type> <parameter>VARIADIC userargs=NULL</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>raster <function>ST_MapAlgebra</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
- <paramdef><type>integer </type> <parameter>nband</parameter></paramdef>
- <paramdef><type>regprocedure </type> <parameter>callbackfunc</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>pixeltype=NULL</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>extenttype=FIRST</parameter></paramdef>
- <paramdef choice="opt"><type>raster </type> <parameter>customextent=NULL</parameter></paramdef>
- <paramdef choice="opt"><type>integer </type> <parameter>distancex=0</parameter></paramdef>
- <paramdef choice="opt"><type>integer </type> <parameter>distancey=0</parameter></paramdef>
- <paramdef choice="opt"><type>text[] </type> <parameter>VARIADIC userargs=NULL</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>raster <function>ST_MapAlgebra</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast1</parameter></paramdef>
- <paramdef><type>integer </type> <parameter>nband1</parameter></paramdef>
- <paramdef><type>raster </type> <parameter>rast2</parameter></paramdef>
- <paramdef><type>integer </type> <parameter>nband2</parameter></paramdef>
- <paramdef><type>regprocedure </type> <parameter>callbackfunc</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>pixeltype=NULL</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>extenttype=INTERSECTION</parameter></paramdef>
- <paramdef choice="opt"><type>raster </type> <parameter>customextent=NULL</parameter></paramdef>
- <paramdef choice="opt"><type>integer </type> <parameter>distancex=0</parameter></paramdef>
- <paramdef choice="opt"><type>integer </type> <parameter>distancey=0</parameter></paramdef>
- <paramdef choice="opt"><type>text[] </type> <parameter>VARIADIC userargs=NULL</parameter></paramdef>
- </funcprototype>
-
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>
- Returns a one-band raster given one or more input rasters, band indexes and one user-specified callback function.
- </para>
-
- <variablelist>
- <varlistentry>
- <term>rast,rast1,rast2, rastbandargset</term>
- <listitem><para>Rasters on which the map algebra process is evaluated.</para><para><varname>rastbandargset</varname> allows the use of a map algebra operation on many rasters and/or many bands. See example Variant 1.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>nband, nband1, nband2</term>
- <listitem><para>Band numbers of the raster to be evaluated. nband can be an integer or integer[] denoting the bands. nband1 is band on rast1 and nband2 is band on rast2 for hte 2 raster/2band case.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>callbackfunc</term>
- <listitem><para>
- The <varname>callbackfunc</varname> parameter must be the name and signature of an SQL or PL/pgSQL function, cast to a regprocedure. An example PL/pgSQL function example is:
- <programlisting>
-CREATE OR REPLACE FUNCTION sample_callbackfunc(value double precision[][][], position integer[][], VARIADIC userargs text[])
- RETURNS double precision
- AS $$
- BEGIN
- RETURN 0;
- END;
- $$ LANGUAGE 'plpgsql' IMMUTABLE;
- </programlisting>
-
- The <varname>callbackfunc</varname> must have three arguments: a 3-dimension double precision array, a 2-dimension integer array and a variadic 1-dimension text array. The first argument <varname>value</varname> is the set of values (as double precision) from all input rasters. The three dimensions (where indexes are 1-based) are: raster #, row y, column x. The second argument <varname>position</varname> is the set of pixel positions from the output raster and input rasters. The outer dimension (where indexes are 0-based) is the raster #. The position at outer dimension index 0 is the output raster's pixel position. For each outer dimension, there are two elements in the inner dimension for X and Y. The third argument <varname>userargs</varname> is for passing through any user-specified arguments.
- </para>
-
- <para>
- Passing a <type>regprocedure</type> argument to a SQL function requires the full function signature to be passed, then cast to a <type>regprocedure</type> type. To pass the above example PL/pgSQL function as an argument, the SQL for the argument is:
-
+ <para>Several rasters, several bands</para>
<programlisting>
-'sample_callbackfunc(double precision[], integer[], text[])'::regprocedure
- </programlisting>
-
- Note that the argument contains the name of the function, the types of the function arguments, quotes around the name and argument types, and a cast to a <type>regprocedure</type>.
- </para>
-
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>pixeltype</term>
- <listitem><para>If <varname>pixeltype</varname> is passed in, the one band of the new raster will be of that pixeltype. If pixeltype is passed NULL or left out, the new raster band will have the same pixeltype as the specified band of the first raster (for extent types: INTERSECTION, UNION, FIRST, CUSTOM) or the specified band of the appropriate raster (for extent types: SECOND, LAST). If in doubt, always specify <varname>pixeltype</varname>.</para>
- <para>The resulting pixel type of the output raster must be one listed in <xref linkend="RT_ST_BandPixelType" /> or left out or set to NULL. </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>extenttype</term>
- <listitem>
- <para>Possible values are INTERSECTION (default), UNION, FIRST (default for one raster variants), SECOND, LAST, CUSTOM. </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>customextent</term>
- <listitem>
- <para>If <varname>extentype</varname> is CUSTOM, a raster must be provided for <varname>customextent</varname>. See example 4 of Variant 1.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>distancex</term>
- <listitem><para>The distance in pixels from the reference cell. So width of resulting matrix would be <code>2*distancex + 1</code>.If not specified only the reference cell is considered (neighborhood of 0).</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>distancey</term>
- <listitem><para>The distance in pixels from reference cell in y direction. Height of resulting matrix would be <code>2*distancey + 1</code> .If not specified only the reference cell is considered (neighborhood of 0).</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term>userargs</term>
- <listitem><para>
- The third argument to the <varname>callbackfunc</varname> is a <type>variadic text</type> array. All trailing text arguments are passed through to the specified <varname>callbackfunc</varname>, and are contained in the <varname>userargs</varname> argument.</para>
- </listitem>
- </varlistentry>
-
- </variablelist>
-
-
-
- <note>
- <para>
- For more information about the VARIADIC keyword, please refer to the PostgreSQL documentation and the "SQL Functions with Variable Numbers of Arguments" section of <ulink url="http://www.postgresql.org/docs/current/static/xfunc-sql.html">Query Language (SQL) Functions</ulink>.
- </para>
- </note>
-
- <note>
- <para>
- The <type>text[]</type> argument to the <varname>callbackfunc</varname> is required, regardless of whether you choose to pass any arguments to the callback function for processing or not.
- </para>
- </note>
-
-
- <para>
- Variant 1 accepts an array of <varname>rastbandarg</varname> allowing the use of a map algebra operation on many rasters and/or many bands. See example Variant 1.
- </para>
-
- <para>
- Variants 2 and 3 operate upon one or more bands of one raster. See example Variant 2 and 3.
- </para>
-
- <para>
- Variant 4 operate upon two rasters with one band per raster. See example Variant 4.
- </para>
-
- <para>Availability: 2.1.0</para>
-
- </refsection>
-
- <refsection>
- <title>Examples: Variant 1</title>
-
- <para>One raster, one band</para>
- <programlisting>
-WITH foo AS (
- SELECT 1 AS rid, ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, 0, 1, -1, 0, 0, 0), 1, '16BUI', 1, 0) AS rast
-)
-SELECT
- ST_MapAlgebra(
- ARRAY[ROW(rast, 1)]::rastbandarg[],
- 'sample_callbackfunc(double precision[], int[], text[])'::regprocedure
- ) AS rast
-FROM foo
- </programlisting>
-
- <para>One raster, several bands</para>
- <programlisting>
-WITH foo AS (
- SELECT 1 AS rid, ST_AddBand(ST_AddBand(ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, 0, 1, -1, 0, 0, 0), 1, '16BUI', 1, 0), 2, '8BUI', 10, 0), 3, '32BUI', 100, 0) AS rast
-)
-SELECT
- ST_MapAlgebra(
- ARRAY[ROW(rast, 3), ROW(rast, 1), ROW(rast, 3), ROW(rast, 2)]::rastbandarg[],
- 'sample_callbackfunc(double precision[], int[], text[])'::regprocedure
- ) AS rast
-FROM foo
- </programlisting>
-
- <para>Several rasters, several bands</para>
- <programlisting>
WITH foo AS (
SELECT 1 AS rid, ST_AddBand(ST_AddBand(ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, 0, 1, -1, 0, 0, 0), 1, '16BUI', 1, 0), 2, '8BUI', 10, 0), 3, '32BUI', 100, 0) AS rast UNION ALL
SELECT 2 AS rid, ST_AddBand(ST_AddBand(ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, 1, 1, -1, 0, 0, 0), 1, '16BUI', 2, 0), 2, '8BUI', 20, 0), 3, '32BUI', 300, 0) AS rast
CROSS JOIN foo t2
WHERE t1.rid = 1
AND t2.rid = 2
- </programlisting>
+ </programlisting>
- <para>Complete example of tiles of a coverage with neighborhood. This query only works with PostgreSQL 9.1 or higher.</para>
- <programlisting>
+
<para>Complete example of tiles of a coverage with neighborhood. This query only works with PostgreSQL 9.1 or higher.</para>
WITH foo AS (
SELECT 0 AS rid, ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, 0, 1, -1, 0, 0, 0), 1, '16BUI', 1, 0) AS rast UNION ALL
SELECT 1, ST_AddBand(ST_MakeEmptyRaster(2, 2, 2, 0, 1, -1, 0, 0, 0), 1, '16BUI', 2, 0) AS rast UNION ALL
AND t2.rid BETWEEN 0 AND 8
AND ST_Intersects(t1.rast, t2.rast)
GROUP BY t1.rid, t1.rast
- </programlisting>
+ </programlisting>
- <para>Example like the prior one for tiles of a coverage with neighborhood but works with PostgreSQL 9.0.</para>
- <programlisting>
+
<para>Example like the prior one for tiles of a coverage with neighborhood but works with PostgreSQL 9.0.</para>
WITH src AS (
SELECT 0 AS rid, ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, 0, 1, -1, 0, 0, 0), 1, '16BUI', 1, 0) AS rast UNION ALL
SELECT 1, ST_AddBand(ST_MakeEmptyRaster(2, 2, 2, 0, 1, -1, 0, 0, 0), 1, '16BUI', 2, 0) AS rast UNION ALL
(ST_BandMetadata(rast, 1)),
ST_Value(rast, 1, 1, 1)
FROM bar;
- </programlisting>
-
- </refsection>
+ </programlisting>
+ </refsection>
- <refsection>
- <title>Examples: Variants 2 and 3</title>
+ <refsection>
+ <title>Examples: Variants 2 and 3</title>
- <para>One raster, several bands</para>
- <programlisting>
+
<para>One raster, several bands</para>
WITH foo AS (
SELECT 1 AS rid, ST_AddBand(ST_AddBand(ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, 0, 1, -1, 0, 0, 0), 1, '16BUI', 1, 0), 2, '8BUI', 10, 0), 3, '32BUI', 100, 0) AS rast
)
'sample_callbackfunc(double precision[], int[], text[])'::regprocedure
) AS rast
FROM foo
- </programlisting>
+ </programlisting>
- <para>One raster, one band</para>
- <programlisting>
+
<para>One raster, one band</para>
WITH foo AS (
SELECT 1 AS rid, ST_AddBand(ST_AddBand(ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, 0, 1, -1, 0, 0, 0), 1, '16BUI', 1, 0), 2, '8BUI', 10, 0), 3, '32BUI', 100, 0) AS rast
)
'sample_callbackfunc(double precision[], int[], text[])'::regprocedure
) AS rast
FROM foo
- </programlisting>
-
- </refsection>
+ </programlisting>
+ </refsection>
- <refsection>
- <title>Examples: Variant 4</title>
+ <refsection>
+ <title>Examples: Variant 4</title>
- <para>Two rasters, two bands</para>
- <programlisting>
+
<para>Two rasters, two bands</para>
WITH foo AS (
SELECT 1 AS rid, ST_AddBand(ST_AddBand(ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, 0, 1, -1, 0, 0, 0), 1, '16BUI', 1, 0), 2, '8BUI', 10, 0), 3, '32BUI', 100, 0) AS rast UNION ALL
SELECT 2 AS rid, ST_AddBand(ST_AddBand(ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, 1, 1, -1, 0, 0, 0), 1, '16BUI', 2, 0), 2, '8BUI', 20, 0), 3, '32BUI', 300, 0) AS rast
CROSS JOIN foo t2
WHERE t1.rid = 1
AND t2.rid = 2
- </programlisting>
-
- </refsection>
-
- <refsection>
- <title>See Also</title>
-
- <para>
- <xref linkend="rastbandarg" />,
- <xref linkend="RT_ST_Union" />,
- <xref linkend="RT_ST_MapAlgebra_expr" />
- </para>
- </refsection>
-
- </refentry>
-
- <refentry id="RT_ST_MapAlgebra_expr">
- <refnamediv>
- <refname>ST_MapAlgebra</refname>
- <refpurpose>
- Expression version - Returns a one-band raster given one or two input rasters, band indexes and one or more user-specified SQL expressions.
- </refpurpose>
- </refnamediv>
+ </programlisting>
- <refsynopsisdiv>
- <funcsynopsis>
+ </refsection>
- <funcprototype>
- <funcdef>raster <function>ST_MapAlgebra</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
- <paramdef><type>integer </type> <parameter>nband</parameter></paramdef>
- <paramdef><type>text </type> <parameter>pixeltype</parameter></paramdef>
- <paramdef><type>text </type> <parameter>expression</parameter></paramdef>
- <paramdef choice="opt"><type>double precision </type> <parameter>nodataval=NULL</parameter></paramdef>
- </funcprototype>
+ <refsection>
+ <title>See Also</title>
- <funcprototype>
- <funcdef>raster <function>ST_MapAlgebra</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
- <paramdef><type>text </type> <parameter>pixeltype</parameter></paramdef>
- <paramdef><type>text </type> <parameter>expression</parameter></paramdef>
- <paramdef choice="opt"><type>double precision </type> <parameter>nodataval=NULL</parameter></paramdef>
- </funcprototype>
+ <para>
+ <xref linkend="rastbandarg" />,
+ <xref linkend="RT_ST_Union" />,
+ <xref linkend="RT_ST_MapAlgebra_expr" />
+ </para>
+ </refsection>
- <funcprototype>
- <funcdef>raster <function>ST_MapAlgebra</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast1</parameter></paramdef>
- <paramdef><type>integer </type> <parameter>nband1</parameter></paramdef>
- <paramdef><type>raster </type> <parameter>rast2</parameter></paramdef>
- <paramdef><type>integer </type> <parameter>nband2</parameter></paramdef>
- <paramdef><type>text </type> <parameter>expression</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>pixeltype=NULL</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>extenttype=INTERSECTION</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>nodata1expr=NULL</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>nodata2expr=NULL</parameter></paramdef>
- <paramdef choice="opt"><type>double precision </type> <parameter>nodatanodataval=NULL</parameter></paramdef>
- </funcprototype>
+ </refentry>
- <funcprototype>
- <funcdef>raster <function>ST_MapAlgebra</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast1</parameter></paramdef>
- <paramdef><type>raster </type> <parameter>rast2</parameter></paramdef>
- <paramdef><type>text </type> <parameter>expression</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>pixeltype=NULL</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>extenttype=INTERSECTION</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>nodata1expr=NULL</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>nodata2expr=NULL</parameter></paramdef>
- <paramdef choice="opt"><type>double precision </type> <parameter>nodatanodataval=NULL</parameter></paramdef>
- </funcprototype>
+ <refentry id="RT_ST_MapAlgebra_expr">
+ <refnamediv>
+ <refname>ST_MapAlgebra</refname>
+ <refpurpose>
+ Expression version - Returns a one-band raster given one or two input rasters, band indexes and one or more user-specified SQL expressions.
+ </refpurpose>
+ </refnamediv>
- </funcsynopsis>
- </refsynopsisdiv>
+ <refsynopsisdiv>
+ <funcsynopsis>
+
+ <funcprototype>
+ <funcdef>raster <function>ST_MapAlgebra</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>nband</parameter></paramdef>
+ <paramdef><type>text </type> <parameter>pixeltype</parameter></paramdef>
+ <paramdef><type>text </type> <parameter>expression</parameter></paramdef>
+ <paramdef choice="opt"><type>double precision </type> <parameter>nodataval=NULL</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>raster <function>ST_MapAlgebra</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>text </type> <parameter>pixeltype</parameter></paramdef>
+ <paramdef><type>text </type> <parameter>expression</parameter></paramdef>
+ <paramdef choice="opt"><type>double precision </type> <parameter>nodataval=NULL</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>raster <function>ST_MapAlgebra</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast1</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>nband1</parameter></paramdef>
+ <paramdef><type>raster </type> <parameter>rast2</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>nband2</parameter></paramdef>
+ <paramdef><type>text </type> <parameter>expression</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>pixeltype=NULL</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>extenttype=INTERSECTION</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>nodata1expr=NULL</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>nodata2expr=NULL</parameter></paramdef>
+ <paramdef choice="opt"><type>double precision </type> <parameter>nodatanodataval=NULL</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>raster <function>ST_MapAlgebra</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast1</parameter></paramdef>
+ <paramdef><type>raster </type> <parameter>rast2</parameter></paramdef>
+ <paramdef><type>text </type> <parameter>expression</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>pixeltype=NULL</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>extenttype=INTERSECTION</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>nodata1expr=NULL</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>nodata2expr=NULL</parameter></paramdef>
+ <paramdef choice="opt"><type>double precision </type> <parameter>nodatanodataval=NULL</parameter></paramdef>
+ </funcprototype>
+
+ </funcsynopsis>
+ </refsynopsisdiv>
- <refsection>
- <title>Description</title>
+ <refsection>
+ <title>Description</title>
- <para>
- Expression version - Returns a one-band raster given one or two input rasters, band indexes and one or more user-specified SQL expressions.
- </para>
+ Expression version - Returns a one-band raster given one or two input rasters, band indexes and one or more user-specified SQL expressions.
+ </para>
- <para>Availability: 2.1.0</para>
- </refsection>
+
<para>Availability: 2.1.0</para>
+ </refsection>
- <refsection>
- <title>Description: Variants 1 and 2 (one raster)</title>
+ <refsection>
+ <title>Description: Variants 1 and 2 (one raster)</title>
- <para>
- Creates a new one band raster formed by applying a valid PostgreSQL algebraic operation defined by the <varname>expression</varname> on the input raster (<varname>rast</varname>). If <varname>nband</varname> is not provided, band 1 is assumed. The new raster will have the same georeference, width, and height as the original raster but will only have one band.
- </para>
+ Creates a new one band raster formed by applying a valid PostgreSQL algebraic operation defined by the <varname>expression</varname> on the input raster (<varname>rast</varname>). If <varname>nband</varname> is not provided, band 1 is assumed. The new raster will have the same georeference, width, and height as the original raster but will only have one band.
+ </para>
- <para>
- If <varname>pixeltype</varname> is passed in, then the new raster will have a band of that pixeltype. If pixeltype is passed NULL, then the new raster band will have the same pixeltype as the input <varname>rast</varname> band.
- </para>
+ If <varname>pixeltype</varname> is passed in, then the new raster will have a band of that pixeltype. If pixeltype is passed NULL, then the new raster band will have the same pixeltype as the input <varname>rast</varname> band.
+ </para>
- <itemizedlist>
- <listitem><para>Keywords permitted for <varname>expression</varname></para>
- <orderedlist>
- <listitem>
- <para><varname>[rast]</varname> - Pixel value of the pixel of interest</para>
- </listitem>
- <listitem>
- <para><varname>[rast.val]</varname> - Pixel value of the pixel of interest</para>
- </listitem>
- <listitem>
- <para><varname>[rast.x]</varname> - 1-based pixel column of the pixel of interest</para>
- </listitem>
- <listitem>
- <para><varname>[rast.y]</varname> - 1-based pixel row of the pixel of interest</para>
+ <itemizedlist>
+ <listitem><para>Keywords permitted for <varname>expression</varname></para>
+ <orderedlist>
+ <listitem>
+ <para><varname>[rast]</varname> - Pixel value of the pixel of interest</para>
+ </listitem>
+ <listitem>
+ <para><varname>[rast.val]</varname> - Pixel value of the pixel of interest</para>
+ </listitem>
+ <listitem>
+ <para><varname>[rast.x]</varname> - 1-based pixel column of the pixel of interest</para>
+ </listitem>
+ <listitem>
+ <para><varname>[rast.y]</varname> - 1-based pixel row of the pixel of interest</para>
+ </listitem>
+ </orderedlist>
</listitem>
- </orderedlist>
- </listitem>
- </itemizedlist>
+ </itemizedlist>
- </refsection>
+ </refsection>
- <refsection>
- <title>Description: Variants 3 and 4 (two raster)</title>
+ <refsection>
+ <title>Description: Variants 3 and 4 (two raster)</title>
- <para>
- Creates a new one band raster formed by applying a valid PostgreSQL algebraic operation to the two bands defined by the <varname>expression</varname> on the two input raster bands <varname>rast1</varname>, (<varname>rast2</varname>). If no <varname>band1</varname>, <varname>band2</varname> is specified band 1 is assumed. The resulting raster will be aligned (scale, skew and pixel corners) on the grid defined by the first raster. The resulting raster will have the extent defined by the <varname>extenttype</varname> parameter.
- </para>
+ Creates a new one band raster formed by applying a valid PostgreSQL algebraic operation to the two bands defined by the <varname>expression</varname> on the two input raster bands <varname>rast1</varname>, (<varname>rast2</varname>). If no <varname>band1</varname>, <varname>band2</varname> is specified band 1 is assumed. The resulting raster will be aligned (scale, skew and pixel corners) on the grid defined by the first raster. The resulting raster will have the extent defined by the <varname>extenttype</varname> parameter.
+ </para>
- <variablelist>
- <varlistentry>
- <term>expression</term>
- <listitem>
- <para>
- A PostgreSQL algebraic expression involving the two rasters and PostgreSQL defined functions/operators that will define the pixel value when pixels intersect. e.g. (([rast1] + [rast2])/2.0)::integer
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>pixeltype</term>
- <listitem>
- <para>
- The resulting pixel type of the output raster. Must be one listed in <xref linkend="RT_ST_BandPixelType" />, left out or set to NULL. If not passed in or set to NULL, will default to the pixeltype of the first raster.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>extenttype</term>
- <listitem>
- <para>
- Controls the extent of resulting raster
- </para>
+ <variablelist>
+ <varlistentry>
+ <term>expression</term>
+ <listitem>
+ A PostgreSQL algebraic expression involving the two rasters and PostgreSQL defined functions/operators that will define the pixel value when pixels intersect. e.g. (([rast1] + [rast2])/2.0)::integer
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>pixeltype</term>
+ <listitem>
+ The resulting pixel type of the output raster. Must be one listed in <xref linkend="RT_ST_BandPixelType" />, left out or set to NULL. If not passed in or set to NULL, will default to the pixeltype of the first raster.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>extenttype</term>
+ <listitem>
+ Controls the extent of resulting raster
+ </para>
- <orderedlist>
- <listitem>
- <para>
- <varname>INTERSECTION</varname> - The extent of the new raster is the intersection of the two rasters. This is the default.
- </para>
- </listitem>
- <listitem>
- <para>
- <varname>UNION</varname> - The extent of the new raster is the union of the two rasters.
- </para>
- </listitem>
- <listitem>
- <para>
- <varname>FIRST</varname> - The extent of the new raster is the same as the one of the first raster.
- </para>
- </listitem>
- <listitem>
- <para>
- <varname>SECOND</varname> - The extent of the new raster is the same as the one of the second raster.
- </para>
- </listitem>
- </orderedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>nodata1expr</term>
- <listitem>
- <para>
- An algebraic expression involving only <varname>rast2</varname> or a constant that defines what to return when pixels of <varname>rast1</varname> are nodata values and spatially corresponding rast2 pixels have values.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>nodata2expr</term>
- <listitem>
- <para>
- An algebraic expression involving only <varname>rast1</varname> or a constant that defines what to return when pixels of <varname>rast2</varname> are nodata values and spatially corresponding rast1 pixels have values.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>nodatanodataval</term>
- <listitem>
- <para>
- A numeric constant to return when spatially corresponding rast1 and rast2 pixels are both nodata values.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <itemizedlist>
- <listitem><para>Keywords permitted in <varname>expression</varname>, <varname>nodata1expr</varname> and <varname>nodata2expr</varname></para>
- <orderedlist>
- <listitem>
- <para><varname>[rast1]</varname> - Pixel value of the pixel of interest from <varname>rast1</varname></para>
- </listitem>
- <listitem>
- <para><varname>[rast1.val]</varname> - Pixel value of the pixel of interest from <varname>rast1</varname></para>
- </listitem>
- <listitem>
- <para><varname>[rast1.x]</varname> - 1-based pixel column of the pixel of interest from <varname>rast1</varname></para>
- </listitem>
- <listitem>
- <para><varname>[rast1.y]</varname> - 1-based pixel row of the pixel of interest from <varname>rast1</varname></para>
- </listitem>
- <listitem>
- <para><varname>[rast2]</varname> - Pixel value of the pixel of interest from <varname>rast2</varname></para>
- </listitem>
- <listitem>
- <para><varname>[rast2.val]</varname> - Pixel value of the pixel of interest from <varname>rast2</varname></para>
- </listitem>
- <listitem>
- <para><varname>[rast2.x]</varname> - 1-based pixel column of the pixel of interest from <varname>rast2</varname></para>
- </listitem>
- <listitem>
- <para><varname>[rast2.y]</varname> - 1-based pixel row of the pixel of interest from <varname>rast2</varname></para>
- </listitem>
- </orderedlist>
- </listitem>
- </itemizedlist>
+ <orderedlist>
+ <listitem>
+ <para>
+ <varname>INTERSECTION</varname> - The extent of the new raster is the intersection of the two rasters. This is the default.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>UNION</varname> - The extent of the new raster is the union of the two rasters.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>FIRST</varname> - The extent of the new raster is the same as the one of the first raster.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>SECOND</varname> - The extent of the new raster is the same as the one of the second raster.
+ </para>
+ </listitem>
+ </orderedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>nodata1expr</term>
+ <listitem>
+ <para>
+ An algebraic expression involving only <varname>rast2</varname> or a constant that defines what to return when pixels of <varname>rast1</varname> are nodata values and spatially corresponding rast2 pixels have values.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>nodata2expr</term>
+ <listitem>
+ <para>
+ An algebraic expression involving only <varname>rast1</varname> or a constant that defines what to return when pixels of <varname>rast2</varname> are nodata values and spatially corresponding rast1 pixels have values.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>nodatanodataval</term>
+ <listitem>
+ <para>
+ A numeric constant to return when spatially corresponding rast1 and rast2 pixels are both nodata values.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
- </refsection>
+ <itemizedlist>
+ <listitem><para>Keywords permitted in <varname>expression</varname>, <varname>nodata1expr</varname> and <varname>nodata2expr</varname></para>
+ <orderedlist>
+ <listitem>
+ <para><varname>[rast1]</varname> - Pixel value of the pixel of interest from <varname>rast1</varname></para>
+ </listitem>
+ <listitem>
+ <para><varname>[rast1.val]</varname> - Pixel value of the pixel of interest from <varname>rast1</varname></para>
+ </listitem>
+ <listitem>
+ <para><varname>[rast1.x]</varname> - 1-based pixel column of the pixel of interest from <varname>rast1</varname></para>
+ </listitem>
+ <listitem>
+ <para><varname>[rast1.y]</varname> - 1-based pixel row of the pixel of interest from <varname>rast1</varname></para>
+ </listitem>
+ <listitem>
+ <para><varname>[rast2]</varname> - Pixel value of the pixel of interest from <varname>rast2</varname></para>
+ </listitem>
+ <listitem>
+ <para><varname>[rast2.val]</varname> - Pixel value of the pixel of interest from <varname>rast2</varname></para>
+ </listitem>
+ <listitem>
+ <para><varname>[rast2.x]</varname> - 1-based pixel column of the pixel of interest from <varname>rast2</varname></para>
+ </listitem>
+ <listitem>
+ <para><varname>[rast2.y]</varname> - 1-based pixel row of the pixel of interest from <varname>rast2</varname></para>
+ </listitem>
+ </orderedlist>
+ </listitem>
+ </itemizedlist>
+ </refsection>
- <refsection>
- <title>Examples: Variants 1 and 2</title>
+ <refsection>
+ <title>Examples: Variants 1 and 2</title>
- <programlisting>
WITH foo AS (
SELECT ST_AddBand(ST_MakeEmptyRaster(10, 10, 0, 0, 1, 1, 0, 0, 0), '32BF', 1, -1) AS rast
)
SELECT
ST_MapAlgebra(rast, 1, NULL, 'ceil([rast]*[rast.x]/[rast.y]+[rast.val])')
FROM foo
- </programlisting>
-
- </refsection>
+ </programlisting>
+ </refsection>
- <refsection>
- <title>Examples: Variant 3 and 4</title>
+ <refsection>
+ <title>Examples: Variant 3 and 4</title>
- <programlisting>
WITH foo AS (
SELECT 1 AS rid, ST_AddBand(ST_AddBand(ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, 0, 1, -1, 0, 0, 0), 1, '16BUI', 1, 0), 2, '8BUI', 10, 0), 3, '32BUI', 100, 0) AS rast UNION ALL
SELECT 2 AS rid, ST_AddBand(ST_AddBand(ST_AddBand(ST_MakeEmptyRaster(2, 2, 0, 1, 1, -1, 0, 0, 0), 1, '16BUI', 2, 0), 2, '8BUI', 20, 0), 3, '32BUI', 300, 0) AS rast
CROSS JOIN foo t2
WHERE t1.rid = 1
AND t2.rid = 2
- </programlisting>
-
- </refsection>
-
- <refsection>
- <title>See Also</title>
-
- <para>
- <xref linkend="rastbandarg" />,
- <xref linkend="RT_ST_Union" />,
- <xref linkend="RT_ST_MapAlgebra" />
- </para>
- </refsection>
+ </programlisting>
+ </refsection>
- </refentry>
+ <refsection>
+ <title>See Also</title>
- <refentry id="RT_ST_MapAlgebraExpr">
- <refnamediv>
- <refname>ST_MapAlgebraExpr</refname>
- <refpurpose>1 raster band version: Creates a new one band raster formed by applying a valid PostgreSQL algebraic operation on the input raster band and of pixeltype provided. Band 1 is assumed if no band is specified.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>raster <function>ST_MapAlgebraExpr</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
- <paramdef><type>integer </type> <parameter>band</parameter></paramdef>
- <paramdef><type>text </type> <parameter>pixeltype</parameter></paramdef>
- <paramdef><type>text </type> <parameter>expression</parameter></paramdef>
- <paramdef choice="opt"><type>double precision </type> <parameter>nodataval=NULL</parameter></paramdef>
- </funcprototype>
+ <para>
+ <xref linkend="rastbandarg" />,
+ <xref linkend="RT_ST_Union" />,
+ <xref linkend="RT_ST_MapAlgebra" />
+ </para>
+ </refsection>
+ </refentry>
+
+ <refentry id="RT_ST_MapAlgebraExpr">
+ <refnamediv>
+ <refname>ST_MapAlgebraExpr</refname>
+ <refpurpose>1 raster band version: Creates a new one band raster formed by applying a valid PostgreSQL algebraic operation on the input raster band and of pixeltype provided. Band 1 is assumed if no band is specified.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+
+ <funcprototype>
+ <funcdef>raster <function>ST_MapAlgebraExpr</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>band</parameter></paramdef>
+ <paramdef><type>text </type> <parameter>pixeltype</parameter></paramdef>
+ <paramdef><type>text </type> <parameter>expression</parameter></paramdef>
+ <paramdef choice="opt"><type>double precision </type> <parameter>nodataval=NULL</parameter></paramdef>
+ </funcprototype>
- <funcprototype>
- <funcdef>raster <function>ST_MapAlgebraExpr</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
- <paramdef><type>text </type> <parameter>pixeltype</parameter></paramdef>
- <paramdef><type>text </type> <parameter>expression</parameter></paramdef>
- <paramdef choice="opt"><type>double precision </type> <parameter>nodataval=NULL</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
+ <funcprototype>
+ <funcdef>raster <function>ST_MapAlgebraExpr</function></funcdef>
+
<paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+
<paramdef><type>text </type> <parameter>pixeltype</parameter></paramdef>
+
<paramdef><type>text </type> <parameter>expression</parameter></paramdef>
+
<paramdef choice="opt"><type>double precision </type> <parameter>nodataval=NULL</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
- <refsection>
- <title>Description</title>
+ <refsection>
+ <title>Description</title>
- <warning>
- <para>
- <xref linkend="RT_ST_MapAlgebraExpr" /> is deprecated as of 2.1.0. Use <xref linkend="RT_ST_MapAlgebra_expr" /> instead.
- </para>
- </warning>
+ <warning>
+ <xref linkend="RT_ST_MapAlgebraExpr" /> is deprecated as of 2.1.0. Use <xref linkend="RT_ST_MapAlgebra_expr" /> instead.
+ </para>
+ </warning>
- <para>Creates a new one band raster formed by applying a valid PostgreSQL algebraic operation defined by the <varname>expression</varname> on the input raster (<varname>rast</varname>). If no <varname>band</varname> is specified band 1 is assumed. The new raster will have the same georeference, width, and height as the original raster but will only have one band.</para>
-
- <para>If <varname>pixeltype</varname> is passed in, then the new raster will have a band of that pixeltype. If pixeltype is passed NULL, then the new raster band will have the same pixeltype as the input <varname>rast</varname> band.</para>
+ <para>
+ Creates a new one band raster formed by applying a valid PostgreSQL algebraic operation defined by the <varname>expression</varname> on the input raster (<varname>rast</varname>). If no <varname>band</varname> is specified band 1 is assumed. The new raster will have the same georeference, width, and height as the original raster but will only have one band.
+ </para>
- <para>In the expression you can use the term
- <varname>[rast]</varname> to refer to the pixel value of
- the original band, <varname>[rast.x]</varname> to refer to
- the 1-based pixel column index, <varname>[rast.y]</varname>
- to refer to the 1-based pixel row index.</para>
-
- <para>Availability: 2.0.0 </para>
- </refsection>
-
- <refsection>
- <title>Examples</title>
-
- <para>Create a new 1 band raster from our original that is a function of modulo 2 of the original raster band.</para>
- <programlisting>ALTER TABLE dummy_rast ADD COLUMN map_rast raster;
+ <para>
+ If <varname>pixeltype</varname> is passed in, then the new raster will have a band of that pixeltype. If pixeltype is passed NULL, then the new raster band will have the same pixeltype as the input <varname>rast</varname> band.
+ </para>
+
+ <para>
+ In the expression you can use the term <varname>[rast]</varname> to refer to the pixel value of the original band, <varname>[rast.x]</varname> to refer to the 1-based pixel column index, <varname>[rast.y]</varname> to refer to the 1-based pixel row index.
+ </para>
+
+ <para>Availability: 2.0.0 </para>
+ </refsection>
+
+ <refsection>
+ <title>Examples</title>
+
+ <para>Create a new 1 band raster from our original that is a function of modulo 2 of the original raster band.</para>
+ <programlisting>
+ALTER TABLE dummy_rast ADD COLUMN map_rast raster;
UPDATE dummy_rast SET map_rast = ST_MapAlgebraExpr(rast,NULL,'mod([rast],2)') WHERE rid = 2;
-SELECT ST_Value(rast,1,i,j) As origval, ST_Value(map_rast, 1, i, j) As mapval
-FROM dummy_rast CROSS JOIN generate_series(1, 3) AS i CROSS JOIN generate_series(1,3) AS j
+SELECT
+ ST_Value(rast,1,i,j) As origval,
+ ST_Value(map_rast, 1, i, j) As mapval
+FROM dummy_rast
+CROSS JOIN generate_series(1, 3) AS i
+CROSS JOIN generate_series(1,3) AS j
WHERE rid = 2;
origval | mapval
250 | 0
254 | 0
254 | 0
- </programlisting>
- <para>Create a new 1 band raster of pixel-type 2BUI from our original that is reclassified and set the nodata value to be 0.</para>
- <programlisting>ALTER TABLE dummy_rast ADD COLUMN map_rast2 raster;
-UPDATE dummy_rast SET map_rast2 = ST_MapAlgebraExpr(rast,'2BUI','CASE WHEN [rast] BETWEEN 100 and 250 THEN 1
-WHEN [rast] = 252 THEN 2
-WHEN [rast] BETWEEN 253 and 254 THEN 3 ELSE 0 END', '0') WHERE rid = 2;
+ </programlisting>
-SELECT DISTINCT ST_Value(rast,1,i,j) As origval, ST_Value(map_rast2, 1, i, j) As mapval
-FROM dummy_rast CROSS JOIN generate_series(1, 5) AS i CROSS JOIN generate_series(1,5) AS j
+ <para>Create a new 1 band raster of pixel-type 2BUI from our original that is reclassified and set the nodata value to be 0.</para>
+ <programlisting>ALTER TABLE dummy_rast ADD COLUMN map_rast2 raster;
+UPDATE dummy_rast SET
+ map_rast2 = ST_MapAlgebraExpr(rast,'2BUI','CASE WHEN [rast] BETWEEN 100 and 250 THEN 1 WHEN [rast] = 252 THEN 2 WHEN [rast] BETWEEN 253 and 254 THEN 3 ELSE 0 END', '0')
+WHERE rid = 2;
+
+SELECT DISTINCT
+ ST_Value(rast,1,i,j) As origval,
+ ST_Value(map_rast2, 1, i, j) As mapval
+FROM dummy_rast
+CROSS JOIN generate_series(1, 5) AS i
+CROSS JOIN generate_series(1,5) AS j
WHERE rid = 2;
origval | mapval
253 | 3
254 | 3
-SELECT ST_BandPixelType(map_rast2) As b1pixtyp
-FROM dummy_rast WHERE rid = 2;
+SELECT
+ ST_BandPixelType(map_rast2) As b1pixtyp
+FROM dummy_rast
+WHERE rid = 2;
b1pixtyp
----------
- 2BUI</programlisting>
- <informaltable>
- <tgroup cols="2">
- <tbody>
- <row>
- <entry><para><informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_mapalgebraexpr01.png" />
- </imageobject>
- <caption><para>original (column rast-view)</para></caption>
- </mediaobject>
- </informalfigure></para>
- </entry>
- <entry><para><informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_mapalgebraexpr02.png" />
- </imageobject>
- <caption><para>rast_view_ma</para></caption>
- </mediaobject>
- </informalfigure></para>
- </entry>
- </row>
- </tbody>
-</tgroup>
-</informaltable>
- <para>Create a new 3 band raster same pixel type from our original 3 band raster with first band
- altered by map algebra and remaining 2 bands unaltered.</para>
- <programlisting>SELECT ST_AddBand(
-ST_AddBand(
+ 2BUI
+ </programlisting>
+
+ <informaltable>
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_mapalgebraexpr01.png" />
+ </imageobject>
+ <caption>
+ <para>original (column rast-view)</para>
+ </caption>
+ </mediaobject>
+ </informalfigure>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_mapalgebraexpr02.png" />
+ </imageobject>
+ <caption>
+ <para>rast_view_ma</para>
+ </caption>
+ </mediaobject>
+ </informalfigure>
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>Create a new 3 band raster same pixel type from our original 3 band raster with first band altered by map algebra and remaining 2 bands unaltered.</para>
+ <programlisting>
+SELECT
ST_AddBand(
- ST_MakeEmptyRaster(rast_view),
- ST_MapAlgebraExpr(rast_view,1,NULL,'tan([rast])*[rast]')
+ ST_AddBand(
+ ST_AddBand(
+ ST_MakeEmptyRaster(rast_view),
+ ST_MapAlgebraExpr(rast_view,1,NULL,'tan([rast])*[rast]')
),
- ST_Band(rast_view,2)
- ),
- ST_Band(rast_view, 3) As rast_view_ma
-)
+ ST_Band(rast_view,2)
+ ),
+ ST_Band(rast_view, 3) As rast_view_ma
+ )
FROM wind
-WHERE rid=167;
- </programlisting>
- </refsection>
+WHERE rid=167;
+ </programlisting>
+ </refsection>
- <refsection>
- <title>See Also</title>
- <para><xref linkend="RT_ST_MapAlgebraExpr2" />, <xref linkend="RT_ST_MapAlgebraFct" />, <xref linkend="RT_ST_BandPixelType" />, <xref linkend="RT_ST_GeoReference" />, <xref linkend="RT_ST_Value" /></para>
- </refsection>
- </refentry>
-
- <refentry id="RT_ST_MapAlgebraExpr2">
- <refnamediv>
- <refname>ST_MapAlgebraExpr</refname>
- <refpurpose>2 raster band version: Creates a new one band raster formed by applying a valid PostgreSQL algebraic operation on the two input raster bands and of pixeltype provided. band 1 of each raster is assumed if no band numbers are specified. The resulting raster will be aligned (scale, skew and pixel corners) on the grid defined by the first raster and have its extent defined by the "extenttype" parameter. Values for "extenttype" can be: INTERSECTION, UNION, FIRST, SECOND.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>raster <function>ST_MapAlgebraExpr</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast1</parameter></paramdef>
- <paramdef><type>raster </type> <parameter>rast2</parameter></paramdef>
- <paramdef><type>text </type> <parameter>expression</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>pixeltype=same_as_rast1_band</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>extenttype=INTERSECTION</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>nodata1expr=NULL</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>nodata2expr=NULL</parameter></paramdef>
- <paramdef choice="opt"><type>double precision </type> <parameter>nodatanodataval=NULL</parameter></paramdef>
- </funcprototype>
+ <refsection>
+ <title>See Also</title>
+ <para>
+ <xref linkend="RT_ST_MapAlgebraExpr2" />,
+ <xref linkend="RT_ST_MapAlgebraFct" />,
+ <xref linkend="RT_ST_BandPixelType" />,
+ <xref linkend="RT_ST_GeoReference" />,
+ <xref linkend="RT_ST_Value" />
+ </para>
+ </refsection>
+ </refentry>
+
+ <refentry id="RT_ST_MapAlgebraExpr2">
+ <refnamediv>
+ <refname>ST_MapAlgebraExpr</refname>
+ <refpurpose>
+ 2 raster band version: Creates a new one band raster formed by applying a valid PostgreSQL algebraic operation on the two input raster bands and of pixeltype provided. band 1 of each raster is assumed if no band numbers are specified. The resulting raster will be aligned (scale, skew and pixel corners) on the grid defined by the first raster and have its extent defined by the "extenttype" parameter. Values for "extenttype" can be: INTERSECTION, UNION, FIRST, SECOND.
+ </refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>raster <function>ST_MapAlgebraExpr</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast1</parameter></paramdef>
+ <paramdef><type>raster </type> <parameter>rast2</parameter></paramdef>
+ <paramdef><type>text </type> <parameter>expression</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>pixeltype=same_as_rast1_band</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>extenttype=INTERSECTION</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>nodata1expr=NULL</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>nodata2expr=NULL</parameter></paramdef>
+ <paramdef choice="opt"><type>double precision </type> <parameter>nodatanodataval=NULL</parameter></paramdef>
+ </funcprototype>
- <funcprototype>
- <funcdef>raster <function>ST_MapAlgebraExpr</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast1</parameter></paramdef>
- <paramdef><type>integer </type> <parameter>band1</parameter></paramdef>
- <paramdef><type>raster </type> <parameter>rast2</parameter></paramdef>
- <paramdef><type>integer </type> <parameter>band2</parameter></paramdef>
- <paramdef><type>text </type> <parameter>expression</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>pixeltype=same_as_rast1_band</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>extenttype=INTERSECTION</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>nodata1expr=NULL</parameter></paramdef>
- <paramdef choice="opt"><type>text </type> <parameter>nodata2expr=NULL</parameter></paramdef>
- <paramdef choice="opt"><type>double precision </type> <parameter>nodatanodataval=NULL</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
+ <funcprototype>
+ <funcdef>raster <function>ST_MapAlgebraExpr</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast1</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>band1</parameter></paramdef>
+ <paramdef><type>raster </type> <parameter>rast2</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>band2</parameter></paramdef>
+ <paramdef><type>text </type> <parameter>expression</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>pixeltype=same_as_rast1_band</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>extenttype=INTERSECTION</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>nodata1expr=NULL</parameter></paramdef>
+ <paramdef choice="opt"><type>text </type> <parameter>nodata2expr=NULL</parameter></paramdef>
+ <paramdef choice="opt"><type>double precision </type> <parameter>nodatanodataval=NULL</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
- <warning>
+ <refsection>
+ <title>Description</title>
+
+ <warning>
+ <para>
+ <xref linkend="RT_ST_MapAlgebraExpr2" /> is deprecated as of 2.1.0. Use <xref linkend="RT_ST_MapAlgebra_expr" /> instead.
+ </para>
+ </warning>
+
<para>
- <xref linkend="RT_ST_MapAlgebraExpr2" /> is deprecated as of 2.1.0. Use <xref linkend="RT_ST_MapAlgebra_expr" /> instead.
+ Creates a new one band raster formed by applying a valid PostgreSQL algebraic operation to the two bands defined by the <varname>expression</varname> on the two input raster bands <varname>rast1</varname>, (<varname>rast2</varname>). If no <varname>band1</varname>, <varname>band2</varname> is specified band 1 is assumed. The resulting raster will be aligned (scale, skew and pixel corners) on the grid defined by the first raster. The resulting raster will have the extent defined by the <varname>extenttype</varname> parameter.
</para>
- </warning>
-
- <para>Creates a new one band raster formed by applying a valid PostgreSQL algebraic operation to the two bands defined by the <varname>expression</varname> on the two input raster bands <varname>rast1</varname>, (<varname>rast2</varname>). If no <varname>band1</varname>, <varname>band2</varname> is specified band 1 is assumed.
- The resulting raster will be aligned (scale, skew and pixel corners) on the grid defined by the first raster. The resulting raster will have the extent defined by the <varname>extenttype</varname> parameter.</para>
-
- <variablelist>
- <varlistentry>
- <term>expression</term>
- <listitem><para>A PostgreSQL algebraic expression involving the two rasters and PostgreSQL defined functions/operators that will define the pixel value when pixels intersect. e.g. (([rast1] + [rast2])/2.0)::integer</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>pixeltype</term>
- <listitem><para>The resulting pixel type of the output raster. Must be one listed in <xref linkend="RT_ST_BandPixelType" />, left out or set to NULL. If not passed in or set to NULL, will default to the pixeltype of the first raster.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>extenttype</term>
- <listitem><para>Controls the extent of resulting raster</para>
- <orderedlist>
+
+ <variablelist>
+ <varlistentry>
+ <term>expression</term>
<listitem>
- <para><varname>INTERSECTION</varname> - The extent of the new raster is the intersection of the two rasters. This is the default.</para>
+ <para>
+ A PostgreSQL algebraic expression involving the two rasters and PostgreSQL defined functions/operators that will define the pixel value when pixels intersect. e.g. (([rast1] + [rast2])/2.0)::integer
+ </para>
</listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>pixeltype</term>
<listitem>
- <para><varname>UNION</varname> - The extent of the new raster is the union of the two rasters.</para>
+ <para>
+ The resulting pixel type of the output raster. Must be one listed in <xref linkend="RT_ST_BandPixelType" />, left out or set to NULL. If not passed in or set to NULL, will default to the pixeltype of the first raster.
+ </para>
</listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>extenttype</term>
<listitem>
- <para><varname>FIRST</varname> - The extent of the new raster is the same as the one of the first raster.</para>
+ <para>Controls the extent of resulting raster</para>
+ <orderedlist>
+ <listitem>
+ <para>
+ <varname>INTERSECTION</varname> - The extent of the new raster is the intersection of the two rasters. This is the default.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>UNION</varname> - The extent of the new raster is the union of the two rasters.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>FIRST</varname> - The extent of the new raster is the same as the one of the first raster.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>SECOND</varname> - The extent of the new raster is the same as the one of the second raster.
+ </para>
+ </listitem>
+ </orderedlist>
</listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>nodata1expr</term>
<listitem>
- <para><varname>SECOND</varname> - The extent of the new raster is the same as the one of the second raster.</para>
+ <para>
+ An algebraic expression involving only <varname>rast2</varname> or a constant that defines what to return when pixels of <varname>rast1</varname> are nodata values and spatially corresponding rast2 pixels have values.
+ </para>
</listitem>
- </orderedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>nodata1expr</term>
- <listitem><para>An algebraic expression involving only <varname>rast2</varname> or a constant that defines what to return when pixels of <varname>rast1</varname> are nodata values and spatially corresponding rast2 pixels have values.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>nodata2expr</term>
- <listitem><para>An algebraic expression involving only <varname>rast1</varname> or a constant that defines what to return when pixels of <varname>rast2</varname> are nodata values and spatially corresponding rast1 pixels have values.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>nodatanodataval</term>
- <listitem><para>A numeric constant to return when spatially corresponding rast1 and rast2 pixels are both nodata values.</para></listitem>
- </varlistentry>
-
- </variablelist>
-
- <para>If <varname>pixeltype</varname> is passed in, then the new raster will have a band of that pixeltype. If pixeltype is passed NULL or no pixel type specified, then the new raster band will have the same pixeltype as the input <varname>rast1</varname> band.</para>
- <para>Use the term <varname>[rast1.val]</varname> <varname>[rast2.val]</varname> to refer to the pixel value of the original raster bands and
- <varname>[rast1.x]</varname>, <varname>[rast1.y]</varname> etc. to refer to the column / row positions of the pixels.</para>
-
-
- <para>Availability: 2.0.0 </para>
- </refsection>
-
- <refsection>
- <title>Example: 2 Band Intersection and Union</title>
-
- <para>Create a new 1 band raster from our original that is a function of modulo 2 of the original raster band.</para>
- <programlisting>
+ </varlistentry>
+
+ <varlistentry>
+ <term>nodata2expr</term>
+ <listitem>
+ <para>
+ An algebraic expression involving only <varname>rast1</varname> or a constant that defines what to return when pixels of <varname>rast2</varname> are nodata values and spatially corresponding rast1 pixels have values.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>nodatanodataval</term>
+ <listitem>
+ <para>
+ A numeric constant to return when spatially corresponding rast1 and rast2 pixels are both nodata values.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ If <varname>pixeltype</varname> is passed in, then the new raster will have a band of that pixeltype. If pixeltype is passed NULL or no pixel type specified, then the new raster band will have the same pixeltype as the input <varname>rast1</varname> band.
+ </para>
+ <para>
+ Use the term <varname>[rast1.val]</varname> <varname>[rast2.val]</varname> to refer to the pixel value of the original raster bands and <varname>[rast1.x]</varname>, <varname>[rast1.y]</varname> etc. to refer to the column / row positions of the pixels.
+ </para>
+
+ <para>Availability: 2.0.0 </para>
+ </refsection>
+
+ <refsection>
+ <title>Example: 2 Band Intersection and Union</title>
+
+ <para>Create a new 1 band raster from our original that is a function of modulo 2 of the original raster band.</para>
+ <programlisting>
--Create a cool set of rasters --
DROP TABLE IF EXISTS fun_shapes;
CREATE TABLE fun_shapes(rid serial PRIMARY KEY, fun_name text, rast raster);
CROSS JOIN (SELECT rast
FROM fun_shapes WHERE
fun_name = 'rand bubbles') As bub
- </programlisting>
- <informaltable>
- <tgroup cols="2">
- <tbody>
- <row>
- <entry><para><informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_mapalgebraexpr2_01.png" />
- </imageobject>
- <caption><para>mapalgebra intersection</para></caption>
- </mediaobject>
- </informalfigure></para>
- </entry>
- <entry><para><informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_mapalgebraexpr2_02.png" />
- </imageobject>
- <caption><para>map algebra union</para></caption>
- </mediaobject>
- </informalfigure></para>
- </entry>
- </row>
- </tbody>
-</tgroup>
-</informaltable>
- </refsection>
- <refsection>
- <title>Example: Overlaying rasters on a canvas as separate bands</title>
- <programlisting>
+ </programlisting>
+
+ <informaltable>
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_mapalgebraexpr2_01.png" />
+ </imageobject>
+ <caption>
+ <para>mapalgebra intersection</para>
+ </caption>
+ </mediaobject>
+ </informalfigure>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_mapalgebraexpr2_02.png" />
+ </imageobject>
+ <caption>
+ <para>map algebra union</para>
+ </caption>
+ </mediaobject>
+ </informalfigure>
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </refsection>
+
+ <refsection>
+ <title>Example: Overlaying rasters on a canvas as separate bands</title>
+ <programlisting>
-- we use ST_AsPNG to render the image so all single band ones look grey --
WITH mygeoms
AS ( SELECT 2 As bnum, ST_Buffer(ST_Point(1,5),10) As geom
)
SELECT rasts[1] As rast1 , rasts[2] As rast2, rasts[3] As rast3, ST_AddBand(
ST_AddBand(rasts[1],rasts[2]), rasts[3]) As final_rast
- FROM rbands;</programlisting>
+ FROM rbands;
+ </programlisting>
-<informaltable>
- <tgroup cols="2">
- <tbody>
- <row>
- <entry><para><informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_mapalgebraexpr2_04.png" />
- </imageobject>
- <caption><para>rast1</para></caption>
- </mediaobject>
- </informalfigure></para>
- </entry>
- <entry><para><informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_mapalgebraexpr2_05.png" />
- </imageobject>
- <caption><para>rast2</para></caption>
- </mediaobject>
- </informalfigure></para>
- </entry>
- </row>
- <row>
- <entry><para><informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_mapalgebraexpr2_06.png" />
- </imageobject>
- <caption><para>rast3</para></caption>
- </mediaobject>
- </informalfigure></para>
- </entry>
-
- <entry><para><informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_mapalgebraexpr2_07.png" />
- </imageobject>
- <caption><para>final_rast</para></caption>
- </mediaobject>
- </informalfigure></para>
- </entry>
- </row>
- </tbody>
-</tgroup>
-</informaltable>
- </refsection>
- <refsection>
- <title>Example: Overlay 2 meter boundary of select parcels over an aerial imagery</title>
- <programlisting>-- Create new 3 band raster composed of first 2 clipped bands, and overlay of 3rd band with our geometry
+ <informaltable>
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_mapalgebraexpr2_04.png" />
+ </imageobject>
+ <caption><para>rast1</para></caption>
+ </mediaobject>
+ </informalfigure>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_mapalgebraexpr2_05.png" />
+ </imageobject>
+ <caption>
+ <para>rast2</para>
+ </caption>
+ </mediaobject>
+ </informalfigure>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_mapalgebraexpr2_06.png" />
+ </imageobject>
+ <caption>
+ <para>rast3</para>
+ </caption>
+ </mediaobject>
+ </informalfigure>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_mapalgebraexpr2_07.png" />
+ </imageobject>
+ <caption>
+ <para>final_rast</para>
+ </caption>
+ </mediaobject>
+ </informalfigure>
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </refsection>
+
+ <refsection>
+ <title>Example: Overlay 2 meter boundary of select parcels over an aerial imagery</title>
+
+ <programlisting>-- Create new 3 band raster composed of first 2 clipped bands, and overlay of 3rd band with our geometry
-- This query took 3.6 seconds on PostGIS windows 64-bit install
WITH pr AS
-- Note the order of operation: we clip all the rasters to dimensions of our region
SELECT ST_AddBand(ST_Band(clipped,ARRAY[1,2])
, ST_MapAlgebraExpr(ST_Band(clipped,3), ST_AsRaster(ST_Buffer(ST_Boundary(geom),2),clipped, '8BUI',250),
'[rast2.val]', '8BUI', 'FIRST', '[rast2.val]', '[rast1.val]') ) As rast
-FROM prunion;</programlisting>
-
-<informaltable>
- <tgroup cols="1">
- <tbody>
- <row>
- <entry><para><informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_mapalgebraexpr2_08.png" />
- </imageobject>
- <caption><para>The blue lines are the boundaries of select parcels</para></caption>
- </mediaobject>
- </informalfigure></para>
- </entry>
- </row>
- </tbody>
- </tgroup>
-</informaltable>
-</refsection>
- <refsection>
- <title>See Also</title>
- <para><xref linkend="RT_ST_MapAlgebraExpr" />, <xref linkend="RT_ST_AddBand" />, <xref linkend="RT_ST_AsPNG" />, <xref linkend="RT_ST_AsRaster" />, <xref linkend="RT_ST_MapAlgebraFct" />, <xref linkend="RT_ST_BandPixelType" />, <xref linkend="RT_ST_GeoReference" />, <xref linkend="RT_ST_Value" />
- , <xref linkend="RT_ST_Union" />, <xref linkend="ST_Union" /></para>
- </refsection>
- </refentry>
+FROM prunion;
+ </programlisting>
- <refentry id="RT_ST_MapAlgebraFct">
- <refnamediv>
- <refname>ST_MapAlgebraFct</refname>
- <refpurpose>1 band version - Creates a new one band raster formed by applying a valid PostgreSQL function on the input raster band and of pixeltype prodived. Band 1 is assumed if no band is specified.</refpurpose>
- </refnamediv>
+ <informaltable>
+ <tgroup cols="1">
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_mapalgebraexpr2_08.png" />
+ </imageobject>
+ <caption>
+ <para>The blue lines are the boundaries of select parcels</para>
+ </caption>
+ </mediaobject>
+ </informalfigure>
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </refsection>
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>raster <function>ST_MapAlgebraFct</function></funcdef>
- <paramdef><type>raster</type> <parameter>rast</parameter></paramdef>
- <paramdef><type>regprocedure</type> <parameter>onerasteruserfunc</parameter></paramdef>
- </funcprototype>
- <funcprototype>
- <funcdef>raster <function>ST_MapAlgebraFct</function></funcdef>
- <paramdef><type>raster</type> <parameter>rast</parameter></paramdef>
- <paramdef><type>regprocedure</type> <parameter>onerasteruserfunc</parameter></paramdef>
- <paramdef><type>text[]</type> <parameter>VARIADIC args</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>raster <function>ST_MapAlgebraFct</function></funcdef>
- <paramdef><type>raster</type> <parameter>rast</parameter></paramdef>
- <paramdef><type>text</type> <parameter>pixeltype</parameter></paramdef>
- <paramdef><type>regprocedure</type> <parameter>onerasteruserfunc</parameter></paramdef>
- </funcprototype>
- <funcprototype>
- <funcdef>raster <function>ST_MapAlgebraFct</function></funcdef>
- <paramdef><type>raster</type> <parameter>rast</parameter></paramdef>
- <paramdef><type>text</type> <parameter>pixeltype</parameter></paramdef>
- <paramdef><type>regprocedure</type> <parameter>onerasteruserfunc</parameter></paramdef>
- <paramdef><type>text[]</type> <parameter>VARIADIC args</parameter></paramdef>
- </funcprototype>
+ <refsection>
+ <title>See Also</title>
+ <para>
+ <xref linkend="RT_ST_MapAlgebraExpr" />,
+ <xref linkend="RT_ST_AddBand" />,
+ <xref linkend="RT_ST_AsPNG" />,
+ <xref linkend="RT_ST_AsRaster" />,
+ <xref linkend="RT_ST_MapAlgebraFct" />,
+ <xref linkend="RT_ST_BandPixelType" />,
+ <xref linkend="RT_ST_GeoReference" />,
+ <xref linkend="RT_ST_Value" />,
+ <xref linkend="RT_ST_Union" />,
+ <xref linkend="ST_Union" />
+ </para>
+ </refsection>
+ </refentry>
+
+ <refentry id="RT_ST_MapAlgebraFct">
+ <refnamediv>
+ <refname>ST_MapAlgebraFct</refname>
+ <refpurpose>1 band version - Creates a new one band raster formed by applying a valid PostgreSQL function on the input raster band and of pixeltype prodived. Band 1 is assumed if no band is specified.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>raster <function>ST_MapAlgebraFct</function></funcdef>
+ <paramdef><type>raster</type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>regprocedure</type> <parameter>onerasteruserfunc</parameter></paramdef>
+ </funcprototype>
+ <funcprototype>
+ <funcdef>raster <function>ST_MapAlgebraFct</function></funcdef>
+ <paramdef><type>raster</type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>regprocedure</type> <parameter>onerasteruserfunc</parameter></paramdef>
+ <paramdef><type>text[]</type> <parameter>VARIADIC args</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>raster <function>ST_MapAlgebraFct</function></funcdef>
+ <paramdef><type>raster</type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>text</type> <parameter>pixeltype</parameter></paramdef>
+ <paramdef><type>regprocedure</type> <parameter>onerasteruserfunc</parameter></paramdef>
+ </funcprototype>
+ <funcprototype>
+ <funcdef>raster <function>ST_MapAlgebraFct</function></funcdef>
+ <paramdef><type>raster</type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>text</type> <parameter>pixeltype</parameter></paramdef>
+ <paramdef><type>regprocedure</type> <parameter>onerasteruserfunc</parameter></paramdef>
+ <paramdef><type>text[]</type> <parameter>VARIADIC args</parameter></paramdef>
+ </funcprototype>
- <funcprototype>
- <funcdef>raster <function>ST_MapAlgebraFct</function></funcdef>
- <paramdef><type>raster</type> <parameter>rast</parameter></paramdef>
- <paramdef><type>integer</type> <parameter>band</parameter></paramdef>
- <paramdef><type>regprocedure</type> <parameter>onerasteruserfunc</parameter></paramdef>
- </funcprototype>
- <funcprototype>
- <funcdef>raster <function>ST_MapAlgebraFct</function></funcdef>
- <paramdef><type>raster</type> <parameter>rast</parameter></paramdef>
- <paramdef><type>integer</type> <parameter>band</parameter></paramdef>
- <paramdef><type>regprocedure</type> <parameter>onerasteruserfunc</parameter></paramdef>
- <paramdef><type>text[]</type> <parameter>VARIADIC args</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>raster <function>ST_MapAlgebraFct</function></funcdef>
- <paramdef><type>raster</type> <parameter>rast</parameter></paramdef>
- <paramdef><type>integer</type> <parameter>band</parameter></paramdef>
- <paramdef><type>text</type> <parameter>pixeltype</parameter></paramdef>
- <paramdef><type>regprocedure</type> <parameter>onerasteruserfunc</parameter></paramdef>
- </funcprototype>
- <funcprototype>
- <funcdef>raster <function>ST_MapAlgebraFct</function></funcdef>
- <paramdef><type>raster</type> <parameter>rast</parameter></paramdef>
- <paramdef><type>integer</type> <parameter>band</parameter></paramdef>
- <paramdef><type>text</type> <parameter>pixeltype</parameter></paramdef>
- <paramdef><type>regprocedure</type> <parameter>onerasteruserfunc</parameter></paramdef>
- <paramdef><type>text[]</type> <parameter>VARIADIC args</parameter></paramdef>
- </funcprototype>
-
- </funcsynopsis>
- </refsynopsisdiv>
+ <funcprototype>
+ <funcdef>raster <function>ST_MapAlgebraFct</function></funcdef>
+
<paramdef><type>raster</type> <parameter>rast</parameter></paramdef>
+
<paramdef><type>integer</type> <parameter>band</parameter></paramdef>
+
<paramdef><type>regprocedure</type> <parameter>onerasteruserfunc</parameter></paramdef>
+ </funcprototype>
+ <funcprototype>
+ <funcdef>raster <function>ST_MapAlgebraFct</function></funcdef>
+
<paramdef><type>raster</type> <parameter>rast</parameter></paramdef>
+
<paramdef><type>integer</type> <parameter>band</parameter></paramdef>
+
<paramdef><type>regprocedure</type> <parameter>onerasteruserfunc</parameter></paramdef>
+
<paramdef><type>text[]</type> <parameter>VARIADIC args</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>raster <function>ST_MapAlgebraFct</function></funcdef>
+
<paramdef><type>raster</type> <parameter>rast</parameter></paramdef>
+
<paramdef><type>integer</type> <parameter>band</parameter></paramdef>
+
<paramdef><type>text</type> <parameter>pixeltype</parameter></paramdef>
+
<paramdef><type>regprocedure</type> <parameter>onerasteruserfunc</parameter></paramdef>
+ </funcprototype>
+ <funcprototype>
+ <funcdef>raster <function>ST_MapAlgebraFct</function></funcdef>
+
<paramdef><type>raster</type> <parameter>rast</parameter></paramdef>
+
<paramdef><type>integer</type> <parameter>band</parameter></paramdef>
+
<paramdef><type>text</type> <parameter>pixeltype</parameter></paramdef>
+
<paramdef><type>regprocedure</type> <parameter>onerasteruserfunc</parameter></paramdef>
+
<paramdef><type>text[]</type> <parameter>VARIADIC args</parameter></paramdef>
+ </funcprototype>
+
+ </funcsynopsis>
+ </refsynopsisdiv>
- <refsection>
- <title>Description</title>
+ <refsection>
+ <title>Description</title>
- <warning>
- <para>
- <xref linkend="RT_ST_MapAlgebraFct" /> is deprecated as of 2.1.0. Use <xref linkend="RT_ST_MapAlgebra" /> instead.
- </para>
- </warning>
+ <warning>
+ <xref linkend="RT_ST_MapAlgebraFct" /> is deprecated as of 2.1.0. Use <xref linkend="RT_ST_MapAlgebra" /> instead.
+ </para>
+ </warning>
- <para>Creates a new one band raster formed by applying a valid PostgreSQL function specified by the <varname>onerasteruserfunc</varname> on the input raster (<varname>rast</varname>). If no <varname>band</varname> is specified, band 1 is assumed. The new raster will have the same georeference, width, and height as the original raster but will only have one band.</para>
+
<para>Creates a new one band raster formed by applying a valid PostgreSQL function specified by the <varname>onerasteruserfunc</varname> on the input raster (<varname>rast</varname>). If no <varname>band</varname> is specified, band 1 is assumed. The new raster will have the same georeference, width, and height as the original raster but will only have one band.</para>
- <para>If <varname>pixeltype</varname> is passed in, then the new raster will have a band of that pixeltype. If pixeltype is passed NULL, then the new raster band will have the same pixeltype as the input <varname>rast</varname> band.</para>
+
<para>If <varname>pixeltype</varname> is passed in, then the new raster will have a band of that pixeltype. If pixeltype is passed NULL, then the new raster band will have the same pixeltype as the input <varname>rast</varname> band.</para>
- <para>The <varname>onerasteruserfunc</varname> parameter must be the name and signature of a SQL or PL/pgSQL function, cast to a regprocedure. A very simple and quite useless PL/pgSQL function example is:
+
<para>The <varname>onerasteruserfunc</varname> parameter must be the name and signature of a SQL or PL/pgSQL function, cast to a regprocedure. A very simple and quite useless PL/pgSQL function example is:
<programlisting>CREATE OR REPLACE FUNCTION simple_function(pixel FLOAT, pos INTEGER[], VARIADIC args TEXT[])
RETURNS FLOAT
AS $$ BEGIN
RETURN 0.0;
END; $$
LANGUAGE 'plpgsql' IMMUTABLE;</programlisting>
- The <varname>userfunction</varname> may accept two or three arguments: a float value, an optional integer array, and a variadic text array. The first argument is the value of an individual raster cell (regardless of the raster datatype). The second argument is the position of the current processing cell in the form '{x,y}'. The third argument indicates that all remaining parameters to <xref linkend="RT_ST_MapAlgebraFct" /> shall be passed through to the <varname>userfunction</varname>.</para>
+ The <varname>userfunction</varname> may accept two or three arguments: a float value, an optional integer array, and a variadic text array. The first argument is the value of an individual raster cell (regardless of the raster datatype). The second argument is the position of the current processing cell in the form '{x,y}'. The third argument indicates that all remaining parameters to <xref linkend="RT_ST_MapAlgebraFct" /> shall be passed through to the <varname>userfunction</varname>.
+ </para>
- <para>Passing a <type>regprodedure</type> argument to a SQL function requires the full function signature to be passed, then cast to a <type>regprocedure</type> type. To pass the above example PL/pgSQL function as an argument, the SQL for the argument is:<programlisting>'simple_function(float,integer[],text[])'::regprocedure</programlisting>Note that the argument contains the name of the function, the types of the function arguments, quotes around the name and argument types, and a cast to a <type>regprocedure</type>.</para>
+ <para>
+ Passing a <type>regprodedure</type> argument to a SQL function requires the full function signature to be passed, then cast to a <type>regprocedure</type> type. To pass the above example PL/pgSQL function as an argument, the SQL for the argument is:<programlisting>'simple_function(float,integer[],text[])'::regprocedure</programlisting>Note that the argument contains the name of the function, the types of the function arguments, quotes around the name and argument types, and a cast to a <type>regprocedure</type>.
+ </para>
- <para>The third argument to the <varname>userfunction</varname> is a <type>variadic text</type> array. All trailing text arguments to any <xref linkend="RT_ST_MapAlgebraFct" /> call are passed through to the specified <varname>userfunction</varname>, and are contained in the <varname>args</varname> argument.</para>
+ <para>
+ The third argument to the <varname>userfunction</varname> is a <type>variadic text</type> array. All trailing text arguments to any <xref linkend="RT_ST_MapAlgebraFct" /> call are passed through to the specified <varname>userfunction</varname>, and are contained in the <varname>args</varname> argument.
+ </para>
- <note><para>For more information about the VARIADIC keyword, please refer to the PostgreSQL documentation and the "SQL Functions with Variable Numbers of Arguments" section of <ulink url="http://www.postgresql.org/docs/current/static/xfunc-sql.html">Query Language (SQL) Functions</ulink>.</para></note>
+ <note>
+ <para>For more information about the VARIADIC keyword, please refer to the PostgreSQL documentation and the "SQL Functions with Variable Numbers of Arguments" section of <ulink url="http://www.postgresql.org/docs/current/static/xfunc-sql.html">Query Language (SQL) Functions</ulink>.</para>
+ </note>
- <note><para>The <type>text[]</type> argument to the <varname>userfunction</varname> is required, regardless of whether you choose to pass any arguments to your user function for processing or not.</para></note>
+ <note>
+ <para>The <type>text[]</type> argument to the <varname>userfunction</varname> is required, regardless of whether you choose to pass any arguments to your user function for processing or not.</para>
+ </note>
- <para>Availability: 2.0.0</para>
- </refsection>
+
<para>Availability: 2.0.0</para>
+ </refsection>
- <refsection>
- <title>Examples</title>
+ <refsection>
+ <title>Examples</title>
- <para>Create a new 1 band raster from our original that is a function of modulo 2 of the original raster band.</para>
- <programlisting>ALTER TABLE dummy_rast ADD COLUMN map_rast raster;
+
<para>Create a new 1 band raster from our original that is a function of modulo 2 of the original raster band.</para>
+
<programlisting>ALTER TABLE dummy_rast ADD COLUMN map_rast raster;
CREATE FUNCTION mod_fct(pixel float, pos integer[], variadic args text[])
RETURNS float
AS $$
250 | 0
254 | 0
254 | 0
- </programlisting>
- <para>Create a new 1 band raster of pixel-type 2BUI from our original that is reclassified and set the nodata value to a passed parameter to the user function (0).</para>
- <programlisting>ALTER TABLE dummy_rast ADD COLUMN map_rast2 raster;
+ </programlisting>
+
+ <para>Create a new 1 band raster of pixel-type 2BUI from our original that is reclassified and set the nodata value to a passed parameter to the user function (0).</para>
+ <programlisting>ALTER TABLE dummy_rast ADD COLUMN map_rast2 raster;
CREATE FUNCTION classify_fct(pixel float, pos integer[], variadic args text[])
RETURNS float
AS
b1pixtyp
----------
- 2BUI</programlisting>
- <informaltable>
- <tgroup cols="2">
- <tbody>
- <row>
- <entry><para><informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_mapalgebraexpr01.png" />
- </imageobject>
- <caption><para>original (column rast-view)</para></caption>
- </mediaobject>
- </informalfigure></para></entry>
- <entry><para><informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_mapalgebraexpr02.png" />
- </imageobject>
- <caption><para>rast_view_ma</para></caption>
- </mediaobject>
- </informalfigure></para></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <para>Create a new 3 band raster same pixel type from our original 3 band raster with first band altered by map algebra and remaining 2 bands unaltered.</para>
- <programlisting>CREATE FUNCTION rast_plus_tan(pixel float, pos integer[], variadic args text[])
+ 2BUI
+ </programlisting>
+
+ <informaltable>
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry><para><informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_mapalgebraexpr01.png" />
+ </imageobject>
+ <caption><para>original (column rast-view)</para></caption>
+ </mediaobject>
+ </informalfigure></para></entry>
+ <entry><para><informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_mapalgebraexpr02.png" />
+ </imageobject>
+ <caption><para>rast_view_ma</para></caption>
+ </mediaobject>
+ </informalfigure></para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>Create a new 3 band raster same pixel type from our original 3 band raster with first band altered by map algebra and remaining 2 bands unaltered.</para>
+ <programlisting>CREATE FUNCTION rast_plus_tan(pixel float, pos integer[], variadic args text[])
RETURNS float
AS
$$
ST_Band(rast_view, 3) As rast_view_ma
)
FROM wind
-WHERE rid=167;
- </programlisting>
- </refsection>
+WHERE rid=167;
+ </programlisting>
+ </refsection>
- <refsection>
- <title>See Also</title>
- <para><xref linkend="RT_ST_MapAlgebraExpr" />, <xref linkend="RT_ST_BandPixelType" />, <xref linkend="RT_ST_GeoReference" />, <xref linkend="RT_ST_SetValue" /></para>
- </refsection>
- </refentry>
-
- <refentry id="RT_ST_MapAlgebraFct2">
- <refnamediv>
- <refname>ST_MapAlgebraFct</refname>
- <refpurpose>2 band version - Creates a new one band raster formed by applying a valid PostgreSQL function on the 2 input raster bands and of pixeltype prodived. Band 1 is assumed if no band is specified. Extent type defaults to INTERSECTION if not specified.</refpurpose>
- </refnamediv>
+ <refsection>
+ <title>See Also</title>
+ <para>
+ <xref linkend="RT_ST_MapAlgebraExpr" />,
+ <xref linkend="RT_ST_BandPixelType" />,
+ <xref linkend="RT_ST_GeoReference" />,
+ <xref linkend="RT_ST_SetValue" />
+ </para>
+ </refsection>
+ </refentry>
+
+ <refentry id="RT_ST_MapAlgebraFct2">
+ <refnamediv>
+ <refname>ST_MapAlgebraFct</refname>
+ <refpurpose>2 band version - Creates a new one band raster formed by applying a valid PostgreSQL function on the 2 input raster bands and of pixeltype prodived. Band 1 is assumed if no band is specified. Extent type defaults to INTERSECTION if not specified.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>raster <function>ST_MapAlgebraFct</function></funcdef>
+ <paramdef><type>raster</type> <parameter>rast1</parameter></paramdef>
+ <paramdef><type>raster</type> <parameter>rast2</parameter></paramdef>
+ <paramdef><type>regprocedure</type> <parameter>tworastuserfunc</parameter></paramdef>
+ <paramdef choice="opt"><type>text</type> <parameter>pixeltype=same_as_rast1</parameter></paramdef>
+ <paramdef choice="opt"><type>text</type> <parameter>extenttype=INTERSECTION</parameter></paramdef>
+ <paramdef><type>text[]</type> <parameter>VARIADIC userargs</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>raster <function>ST_MapAlgebraFct</function></funcdef>
+ <paramdef><type>raster</type> <parameter>rast1</parameter></paramdef>
+ <paramdef><type>integer</type> <parameter>band1</parameter></paramdef>
+ <paramdef><type>raster</type> <parameter>rast2</parameter></paramdef>
+ <paramdef><type>integer</type> <parameter>band2</parameter></paramdef>
+ <paramdef><type>regprocedure</type> <parameter>tworastuserfunc</parameter></paramdef>
+ <paramdef choice="opt"><type>text</type> <parameter>pixeltype=same_as_rast1</parameter></paramdef>
+ <paramdef choice="opt"><type>text</type> <parameter>extenttype=INTERSECTION</parameter></paramdef>
+ <paramdef><type>text[]</type> <parameter>VARIADIC userargs</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>raster <function>ST_MapAlgebraFct</function></funcdef>
- <paramdef><type>raster</type> <parameter>rast1</parameter></paramdef>
- <paramdef><type>raster</type> <parameter>rast2</parameter></paramdef>
- <paramdef><type>regprocedure</type> <parameter>tworastuserfunc</parameter></paramdef>
- <paramdef choice="opt"><type>text</type> <parameter>pixeltype=same_as_rast1</parameter></paramdef>
- <paramdef choice="opt"><type>text</type> <parameter>extenttype=INTERSECTION</parameter></paramdef>
- <paramdef><type>text[]</type> <parameter>VARIADIC userargs</parameter></paramdef>
- </funcprototype>
+ <refsection>
+ <title>Description</title>
- <funcprototype>
- <funcdef>raster <function>ST_MapAlgebraFct</function></funcdef>
- <paramdef><type>raster</type> <parameter>rast1</parameter></paramdef>
- <paramdef><type>integer</type> <parameter>band1</parameter></paramdef>
- <paramdef><type>raster</type> <parameter>rast2</parameter></paramdef>
- <paramdef><type>integer</type> <parameter>band2</parameter></paramdef>
- <paramdef><type>regprocedure</type> <parameter>tworastuserfunc</parameter></paramdef>
- <paramdef choice="opt"><type>text</type> <parameter>pixeltype=same_as_rast1</parameter></paramdef>
- <paramdef choice="opt"><type>text</type> <parameter>extenttype=INTERSECTION</parameter></paramdef>
- <paramdef><type>text[]</type> <parameter>VARIADIC userargs</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
+ <warning>
+ <para>
+ <xref linkend="RT_ST_MapAlgebraFct2" /> is deprecated as of 2.1.0. Use <xref linkend="RT_ST_MapAlgebra" /> instead.
+ </para>
+ </warning>
- <refsection>
- <title>Description</title>
-
- <warning>
- <para>
- <xref linkend="RT_ST_MapAlgebraFct2" /> is deprecated as of 2.1.0. Use <xref linkend="RT_ST_MapAlgebra" /> instead.
+ <para>Creates a new one band raster formed by applying a valid PostgreSQL function specified by the <varname>tworastuserfunc</varname> on the input raster <varname>rast1</varname>, <varname>rast2</varname>. If no <varname>band1</varname> or <varname>band2</varname> is specified, band 1 is assumed. The new raster will have the same georeference, width, and height as the original rasters but will only have one band.
</para>
- </warning>
-
- <para>Creates a new one band raster formed by applying a valid PostgreSQL function specified by the <varname>tworastuserfunc</varname> on the input raster <varname>rast1</varname>, <varname>rast2</varname>. If no <varname>band1</varname> or <varname>band2</varname> is specified, band 1 is assumed. The new raster will have the same georeference, width, and height as the original rasters but will only have one band.</para>
- <para>If <varname>pixeltype</varname> is passed in, then the new raster will have a band of that pixeltype. If pixeltype is passed NULL or left out, then the new raster band will have the same pixeltype as the input <varname>rast1</varname> band.</para>
+ <para>If <varname>pixeltype</varname> is passed in, then the new raster will have a band of that pixeltype. If pixeltype is passed NULL or left out, then the new raster band will have the same pixeltype as the input <varname>rast1</varname> band.
+ </para>
- <para>The <varname>tworastuserfunc</varname> parameter must be the name and signature of an SQL or PL/pgSQL function, cast to a regprocedure. An example PL/pgSQL function example is:
+
<para>The <varname>tworastuserfunc</varname> parameter must be the name and signature of an SQL or PL/pgSQL function, cast to a regprocedure. An example PL/pgSQL function example is:
<programlisting>CREATE OR REPLACE FUNCTION simple_function_for_two_rasters(pixel1 FLOAT, pixel2 FLOAT, pos INTEGER[], VARIADIC args TEXT[])
RETURNS FLOAT
AS $$ BEGIN
END; $$
LANGUAGE 'plpgsql' IMMUTABLE;</programlisting>
- The <varname>tworastuserfunc</varname> may accept three or four arguments: a double precision value, a double precision value, an optional integer array, and a variadic text array. The first argument is the value of an individual raster cell in <varname>rast1</varname> (regardless of the raster datatype). The second argument is an individual raster cell value in <varname>rast2</varname>. The third argument is the position of the current processing cell in the form '{x,y}'. The fourth argument indicates that all remaining parameters to <xref linkend="RT_ST_MapAlgebraFct2" /> shall be passed through to the <varname>tworastuserfunc</varname>.</para>
+ The <varname>tworastuserfunc</varname> may accept three or four arguments: a double precision value, a double precision value, an optional integer array, and a variadic text array. The first argument is the value of an individual raster cell in <varname>rast1</varname> (regardless of the raster datatype). The second argument is an individual raster cell value in <varname>rast2</varname>. The third argument is the position of the current processing cell in the form '{x,y}'. The fourth argument indicates that all remaining parameters to <xref linkend="RT_ST_MapAlgebraFct2" /> shall be passed through to the <varname>tworastuserfunc</varname>.
+ </para>
- <para>Passing a <type>regprodedure</type> argument to a SQL function requires the full function signature to be passed, then cast to a <type>regprocedure</type> type. To pass the above example PL/pgSQL function as an argument, the SQL for the argument is:<programlisting>'simple_function(double precision, double precision, integer[], text[])'::regprocedure</programlisting>Note that the argument contains the name of the function, the types of the function arguments, quotes around the name and argument types, and a cast to a <type>regprocedure</type>.</para>
+ <para>Passing a <type>regprodedure</type> argument to a SQL function requires the full function signature to be passed, then cast to a <type>regprocedure</type> type. To pass the above example PL/pgSQL function as an argument, the SQL for the argument is:<programlisting>'simple_function(double precision, double precision, integer[], text[])'::regprocedure</programlisting>Note that the argument contains the name of the function, the types of the function arguments, quotes around the name and argument types, and a cast to a <type>regprocedure</type>.
+ </para>
- <para>The third argument to the <varname>tworastuserfunc</varname> is a <type>variadic text</type> array. All trailing text arguments to any <xref linkend="RT_ST_MapAlgebraFct2" /> call are passed through to the specified <varname>tworastuserfunc</varname>, and are contained in the <varname>userargs</varname> argument.</para>
+ <para>The third argument to the <varname>tworastuserfunc</varname> is a <type>variadic text</type> array. All trailing text arguments to any <xref linkend="RT_ST_MapAlgebraFct2" /> call are passed through to the specified <varname>tworastuserfunc</varname>, and are contained in the <varname>userargs</varname> argument.
+ </para>
- <note><para>For more information about the VARIADIC keyword, please refer to the PostgreSQL documentation and the "SQL Functions with Variable Numbers of Arguments" section of <ulink url="http://www.postgresql.org/docs/current/static/xfunc-sql.html">Query Language (SQL) Functions</ulink>.</para></note>
+ <note>
+ <para>For more information about the VARIADIC keyword, please refer to the PostgreSQL documentation and the "SQL Functions with Variable Numbers of Arguments" section of <ulink url="http://www.postgresql.org/docs/current/static/xfunc-sql.html">Query Language (SQL) Functions</ulink>.</para>
+ </note>
- <note><para>The <type>text[]</type> argument to the <varname>tworastuserfunc</varname> is required, regardless of whether you choose to pass any arguments to your user function for processing or not.</para></note>
+ <note>
+ <para>The <type>text[]</type> argument to the <varname>tworastuserfunc</varname> is required, regardless of whether you choose to pass any arguments to your user function for processing or not.</para>
+ </note>
- <para>Availability: 2.0.0</para>
- </refsection>
+
<para>Availability: 2.0.0</para>
+ </refsection>
- <refsection>
- <title>Example: Overlaying rasters on a canvas as separate bands</title>
- <programlisting>
+ <refsection>
+ <title>Example: Overlaying rasters on a canvas as separate bands</title>
-- define our user defined function --
CREATE OR REPLACE FUNCTION raster_mapalgebra_union(
rast1 double precision,
'raster_mapalgebra_union(double precision, double precision, integer[], text[])'::regprocedure, '8BUI', 'FIRST')
FROM map_shapes As m1 CROSS JOIN map_shapes As m2
WHERE m1.descrip = 'canvas' AND m2.descrip <> 'canvas' ORDER BY m2.bnum) As rasts) As foo;
+ </programlisting>
- </programlisting>
-
-<informaltable>
- <tgroup cols="1">
- <tbody>
- <row>
- <entry><para><informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_mapalgebrafct2_01.png" />
- </imageobject>
- <caption><para>map bands overlay (canvas) (R: small road, G: circle, B: big road)</para></caption>
- </mediaobject>
- </informalfigure></para>
- </entry>
- </row>
- </tbody>
-</tgroup>
-</informaltable>
-</refsection>
-<refsection>
- <title>User Defined function that takes extra args</title>
- <programlisting>
+ <informaltable>
+ <tgroup cols="1">
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_mapalgebrafct2_01.png" />
+ </imageobject>
+ <caption><para>map bands overlay (canvas) (R: small road, G: circle, B: big road)</para></caption>
+ </mediaobject>
+ </informalfigure>
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </refsection>
+
+ <refsection>
+ <title>User Defined function that takes extra args</title>
+ <programlisting>
CREATE OR REPLACE FUNCTION raster_mapalgebra_userargs(
rast1 double precision,
rast2 double precision,
'8BUI', 'INTERSECT', '100','200','200','0')
FROM map_shapes As m1
WHERE m1.descrip = 'map bands overlay fct union (canvas)';
-</programlisting>
- <para>
- <informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_mapalgebrafct2_02.png" />
- </imageobject>
- <caption><para>user defined with extra args and different bands from same raster</para></caption>
- </mediaobject>
- </informalfigure>
- </para>
-
- </refsection>
-
+ </programlisting>
- <refsection>
- <title>See Also</title>
- <para><xref linkend="RT_ST_MapAlgebraExpr2" />, <xref linkend="RT_ST_BandPixelType" />, <xref linkend="RT_ST_GeoReference" />, <xref linkend="RT_ST_SetValue" /></para>
- </refsection>
- </refentry>
-
- <refentry id="RT_ST_MapAlgebraFctNgb">
- <refnamediv>
- <refname>ST_MapAlgebraFctNgb</refname>
-
- <refpurpose>1-band version: Map Algebra Nearest Neighbor using user-defined PostgreSQL function. Return a raster which values are the result of a PLPGSQL user function involving a neighborhood of values from the input raster band.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>raster <function>ST_MapAlgebraFctNgb</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
- <paramdef><type>integer </type> <parameter>band</parameter></paramdef>
- <paramdef><type>text </type> <parameter>pixeltype</parameter></paramdef>
- <paramdef><type>integer </type> <parameter>ngbwidth</parameter></paramdef>
- <paramdef><type>integer </type> <parameter>ngbheight</parameter></paramdef>
- <paramdef><type>regprocedure </type> <parameter>onerastngbuserfunc</parameter></paramdef>
- <paramdef><type>text </type> <parameter>nodatamode</parameter></paramdef>
- <paramdef><type>text[] </type> <parameter>VARIADIC args</parameter></paramdef>
- </funcprototype>
-
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <warning>
<para>
- <xref linkend="RT_ST_MapAlgebraFctNgb" /> is deprecated as of 2.1.0. Use <xref linkend="RT_ST_MapAlgebra" /> instead.
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_mapalgebrafct2_02.png" />
+ </imageobject>
+ <caption><para>user defined with extra args and different bands from same raster</para></caption>
+ </mediaobject>
+ </informalfigure>
</para>
- </warning>
+ </refsection>
- <para>(one raster version) Return a raster which values
- are the result of a PLPGSQL user function involving a
- neighborhood of values from the input raster band. The user function takes the neighborhood of pixel values
- as an array of numbers, for each pixel, returns the result from the user function,
- replacing pixel value of currently inspected pixel with the function result. </para>
+ <refsection>
+ <title>See Also</title>
+ <para>
+ <xref linkend="RT_ST_MapAlgebraExpr2" />,
+ <xref linkend="RT_ST_BandPixelType" />,
+ <xref linkend="RT_ST_GeoReference" />,
+ <xref linkend="RT_ST_SetValue" />
+ </para>
+ </refsection>
+ </refentry>
+
+ <refentry id="RT_ST_MapAlgebraFctNgb">
+ <refnamediv>
+ <refname>ST_MapAlgebraFctNgb</refname>
+ <refpurpose>1-band version: Map Algebra Nearest Neighbor using user-defined PostgreSQL function. Return a raster which values are the result of a PLPGSQL user function involving a neighborhood of values from the input raster band.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>raster <function>ST_MapAlgebraFctNgb</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>band</parameter></paramdef>
+ <paramdef><type>text </type> <parameter>pixeltype</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>ngbwidth</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>ngbheight</parameter></paramdef>
+ <paramdef><type>regprocedure </type> <parameter>onerastngbuserfunc</parameter></paramdef>
+ <paramdef><type>text </type> <parameter>nodatamode</parameter></paramdef>
+ <paramdef><type>text[] </type> <parameter>VARIADIC args</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
- <variablelist>
- <varlistentry>
- <term>rast</term>
- <listitem><para>Raster on which the user function is evaluated.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>band</term>
- <listitem><para>Band number of the raster to be evaluated. Default to 1.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>pixeltype</term>
- <listitem><para>The resulting pixel type of the output raster. Must be one listed in <xref linkend="RT_ST_BandPixelType" /> or left out or set to NULL. If not passed in or set to NULL, will default to the pixeltype of the <varname>rast</varname>. Results are truncated if they are larger than what is allowed for the pixeltype.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>ngbwidth</term>
- <listitem><para>The width of the neighborhood, in cells.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>ngbheight</term>
- <listitem><para>The height of the neighborhood, in cells.</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>onerastngbuserfunc</term>
- <listitem><para>PLPGSQL/psql user function to apply to neighborhood pixels of a single band of a raster. The first element is a 2-dimensional
- array of numbers representing the rectangular pixel neighborhood</para></listitem>
- </varlistentry>
- <varlistentry>
- <term>nodatamode</term>
- <listitem><para>Defines what value to pass to the function for a neighborhood pixel that is nodata or NULL</para>
- <para>'ignore': any NODATA values encountered in the neighborhood are ignored by the computation -- this flag must be sent to the user callback function, and the user function decides how to ignore it.</para>
- <para>'NULL': any NODATA values encountered in the neighborhood will cause the resulting pixel to be NULL -- the user callback function is skipped in this case.</para>
- <para>'value': any NODATA values encountered in the neighborhood are replaced by the reference pixel (the one in the center of the neighborhood). Note that if this value is NODATA, the behavior is the same as 'NULL' (for the affected neighborhood)</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>args</term>
- <listitem><para>Arguments to pass into the user function.</para></listitem>
- </varlistentry>
- </variablelist>
+ <refsection>
+ <title>Description</title>
- <para>Availability: 2.0.0 </para>
-
-
- </refsection>
-
-
- <refsection>
- <title>Examples</title>
- <para>Examples utilize the katrina raster loaded as a single tile described in
- <ulink url="http://trac.osgeo.org/gdal/wiki/frmts_wtkraster.html">http://trac.osgeo.org/gdal/wiki/frmts_wtkraster.html</ulink>
- and then prepared in the <xref linkend="RT_ST_Rescale" /> examples </para>
-<programlisting>
+ <warning>
+ <para>
+ <xref linkend="RT_ST_MapAlgebraFctNgb" /> is deprecated as of 2.1.0. Use <xref linkend="RT_ST_MapAlgebra" /> instead.
+ </para>
+ </warning>
+
+ <para>(one raster version) Return a raster which values are the result of a PLPGSQL user function involving a neighborhood of values from the input raster band. The user function takes the neighborhood of pixel values as an array of numbers, for each pixel, returns the result from the user function, replacing pixel value of currently inspected pixel with the function result. </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>rast</term>
+ <listitem><para>Raster on which the user function is evaluated.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>band</term>
+ <listitem><para>Band number of the raster to be evaluated. Default to 1.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>pixeltype</term>
+ <listitem><para>The resulting pixel type of the output raster. Must be one listed in <xref linkend="RT_ST_BandPixelType" /> or left out or set to NULL. If not passed in or set to NULL, will default to the pixeltype of the <varname>rast</varname>. Results are truncated if they are larger than what is allowed for the pixeltype.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ngbwidth</term>
+ <listitem><para>The width of the neighborhood, in cells.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ngbheight</term>
+ <listitem><para>The height of the neighborhood, in cells.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>onerastngbuserfunc</term>
+ <listitem><para>PLPGSQL/psql user function to apply to neighborhood pixels of a single band of a raster. The first element is a 2-dimensional array of numbers representing the rectangular pixel neighborhood</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>nodatamode</term>
+ <listitem>
+ <para>Defines what value to pass to the function for a neighborhood pixel that is nodata or NULL</para>
+ <para>'ignore': any NODATA values encountered in the neighborhood are ignored by the computation -- this flag must be sent to the user callback function, and the user function decides how to ignore it.</para>
+ <para>'NULL': any NODATA values encountered in the neighborhood will cause the resulting pixel to be NULL -- the user callback function is skipped in this case.</para>
+ <para>'value': any NODATA values encountered in the neighborhood are replaced by the reference pixel (the one in the center of the neighborhood). Note that if this value is NODATA, the behavior is the same as 'NULL' (for the affected neighborhood)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>args</term>
+ <listitem><para>Arguments to pass into the user function.</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Availability: 2.0.0 </para>
+ </refsection>
+
+ <refsection>
+ <title>Examples</title>
+
+ <para>Examples utilize the katrina raster loaded as a single tile described in <ulink url="http://trac.osgeo.org/gdal/wiki/frmts_wtkraster.html">http://trac.osgeo.org/gdal/wiki/frmts_wtkraster.html</ulink> and then prepared in the <xref linkend="RT_ST_Rescale" /> examples </para>
+
+ <programlisting>
--
-- A simple 'callback' user function that averages up all the values in a neighborhood.
--
'rast_avg(float[][], text, text[])'::regprocedure, 'NULL', NULL) As nn_with_border
FROM katrinas_rescaled
limit 1;
-</programlisting>
+ </programlisting>
- <informaltable>
- <tgroup cols="2">
- <tbody>
- <row>
- <entry><para><informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_mapalgebrafctngb01.png" />
- </imageobject>
- <caption><para>First band of our raster</para></caption>
- </mediaobject>
- </informalfigure></para></entry>
- <entry><para><informalfigure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/st_mapalgebrafctngb02.png" />
- </imageobject>
- <caption><para>new raster after averaging pixels withing 4x4 pixels of each other</para></caption>
- </mediaobject>
- </informalfigure></para></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </refsection>
-
- <!-- Optionally add a "See Also" section -->
- <refsection>
- <title>See Also</title>
-
- <para><xref linkend="RT_ST_MapAlgebraFct" />, <xref linkend="RT_ST_MapAlgebraExpr" />, <xref linkend="RT_ST_Rescale" /></para>
- </refsection>
- </refentry>
+ <informaltable>
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_mapalgebrafctngb01.png" />
+ </imageobject>
+ <caption>
+ <para>First band of our raster</para>
+ </caption>
+ </mediaobject>
+ </informalfigure>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <informalfigure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/st_mapalgebrafctngb02.png" />
+ </imageobject>
+ <caption>
+ <para>new raster after averaging pixels withing 4x4 pixels of each other</para>
+ </caption>
+ </mediaobject>
+ </informalfigure>
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </refsection>
- <refentry id="RT_ST_MinConvexHull">
- <refnamediv>
- <refname>ST_MinConvexHull</refname>
- <refpurpose>
- Return the convex hull geometry of the raster excluding NODATA pixels.</refpurpose>
- </refnamediv>
+ <!-- Optionally add a "See Also" section -->
+ <refsection>
+ <title>See Also</title>
+ <para>
+ <xref linkend="RT_ST_MapAlgebraFct" />,
+ <xref linkend="RT_ST_MapAlgebraExpr" />,
+ <xref linkend="RT_ST_Rescale" />
+ </para>
+ </refsection>
+ </refentry>
+
+ <refentry id="RT_ST_Reclass">
+ <refnamediv>
+ <refname>ST_Reclass</refname>
+ <refpurpose>Creates a new raster composed of band types reclassified from original. The nband is the band to be changed. If nband is not specified assumed to be 1. All other bands are returned unchanged. Use case: convert a 16BUI band to a 8BUI and so forth for simpler rendering as viewable formats.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>raster <function>ST_Reclass</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>integer </type> <parameter>nband</parameter></paramdef>
+ <paramdef><type>text </type> <parameter>reclassexpr</parameter></paramdef>
+ <paramdef><type>text </type> <parameter>pixeltype</parameter></paramdef>
+ <paramdef choice="opt"><type>double precision </type> <parameter>nodataval=NULL</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>raster <function>ST_Reclass</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>reclassarg[] </type> <parameter>VARIADIC reclassargset</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>raster <function>ST_Reclass</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>text </type> <parameter>reclassexpr</parameter></paramdef>
+ <paramdef><type>text </type> <parameter>pixeltype</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
- <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>
+ <refsection>
+ <title>Description</title>
+
+ <para>Creates a new raster formed by applying a valid PostgreSQL algebraic operation defined by the <varname>reclassexpr</varname> on the input raster (<varname>rast</varname>). If no <varname>band</varname> is specified band 1 is assumed. The new raster will have the same georeference, width, and height as the original raster. Bands not designated will come back unchanged. Refer to <xref linkend="reclassarg" /> for description of valid reclassification expressions.</para>
- <refsection>
- <title>Description</title>
+ <para>The bands of the new raster will have pixel type of <varname>pixeltype</varname>. If <varname>reclassargset</varname> is passed in then each reclassarg defines behavior of each band generated.</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.
- </para>
-
- <para>Availability: 2.1.0 </para>
- </refsection>
+ <para>Availability: 2.0.0 </para>
+ </refsection>
- <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
-
- 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>
-
- <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;
-
-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;
-
--- 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;
-
-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)))
-
--- Or if you want the no data value different for just one time
-
-SELECT ST_AsText(
- ST_Polygon(
- ST_SetBandNoDataValue(rast,1,252)
- )
- ) As geomwkt
-FROM dummy_rast
-WHERE rid =2;
-
-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>
- <refsection>
- <title>See Also</title>
- <para><xref linkend="RT_ST_Value" />, <xref linkend="RT_ST_DumpAsPolygons" /></para>
- </refsection>
- </refentry>
-
- <refentry id="RT_ST_Reclass">
- <refnamediv>
- <refname>ST_Reclass</refname>
- <refpurpose>Creates a new raster composed of band types reclassified from original. The nband is the band to be changed. If nband is not specified assumed to be 1. All other bands are returned unchanged.
- Use case: convert a 16BUI band to a 8BUI and so forth for simpler rendering as viewable formats.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>raster <function>ST_Reclass</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
- <paramdef><type>integer </type> <parameter>nband</parameter></paramdef>
- <paramdef><type>text </type> <parameter>reclassexpr</parameter></paramdef>
- <paramdef><type>text </type> <parameter>pixeltype</parameter></paramdef>
- <paramdef choice="opt"><type>double precision </type> <parameter>nodataval=NULL</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>raster <function>ST_Reclass</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
- <paramdef><type>reclassarg[] </type> <parameter>VARIADIC reclassargset</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>raster <function>ST_Reclass</function></funcdef>
- <paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
- <paramdef><type>text </type> <parameter>reclassexpr</parameter></paramdef>
- <paramdef><type>text </type> <parameter>pixeltype</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>Creates a new raster formed by applying a valid PostgreSQL algebraic operation defined by the <varname>reclassexpr</varname> on the input raster (<varname>rast</varname>). If no <varname>band</varname> is specified
- band 1 is assumed. The new raster will have the same georeference, width, and height as the original raster. Bands not designated will come back unchanged.
- Refer to <xref linkend="reclassarg" /> for description of valid reclassification expressions.</para>
-
- <para>The bands of the new raster will have pixel type of <varname>pixeltype</varname>. If <varname>reclassargset</varname> is passed in then each reclassarg defines behavior of each band generated.</para>
-
-
- <para>Availability: 2.0.0 </para>
- </refsection>
-
- <refsection>
- <title>Examples Basic</title>
-
- <para>Create a new raster from the original where band 2 is converted from 8BUI to 4BUI and all values from 101-254 are set to nodata value.</para>
- <programlisting>ALTER TABLE dummy_rast ADD COLUMN reclass_rast raster;
+ <refsection>
+ <title>Examples Basic</title>
+ <para>Create a new raster from the original where band 2 is converted from 8BUI to 4BUI and all values from 101-254 are set to nodata value.</para>
+ <programlisting>
+ALTER TABLE dummy_rast ADD COLUMN reclass_rast raster;
UPDATE dummy_rast SET reclass_rast = ST_Reclass(rast,2,'0-87:1-10, 88-100:11-15, 101-254:0-0', '4BUI',0) WHERE rid = 2;
SELECT i as col, j as row, ST_Value(rast,2,i,j) As origval,
3 | 2 | 180 | | 0
1 | 3 | 99 | 15 | 15
2 | 3 | 112 | | 0
- 3 | 3 | 169 | | 0</programlisting>
- </refsection>
-
- <refsection>
- <title>Example: Advanced using multiple reclassargs</title>
-
- <para>Create a new raster from the original where band 1,2,3 is converted to 1BB,4BUI, 4BUI respectively and reclassified.
- Note this uses the variadic <varname>reclassarg</varname> argument which can take as input an indefinite number of reclassargs (theoretically as many bands as you have) </para>
- <programlisting>UPDATE dummy_rast SET reclass_rast =
+ 3 | 3 | 169 | | 0
+ </programlisting>
+ </refsection>
+
+ <refsection>
+ <title>Example: Advanced using multiple reclassargs</title>
+
+ <para>Create a new raster from the original where band 1,2,3 is converted to 1BB,4BUI, 4BUI respectively and reclassified. Note this uses the variadic <varname>reclassarg</varname> argument which can take as input an indefinite number of reclassargs (theoretically as many bands as you have) </para>
+ <programlisting>
+UPDATE dummy_rast SET reclass_rast =
ST_Reclass(rast,
ROW(2,'0-87]:1-10, (87-100]:11-15, (101-254]:0-0', '4BUI',NULL)::reclassarg,
ROW(1,'0-253]:1, 254:0', '1BB', NULL)::reclassarg,
3 | 2 | 254 | 0 | 180 | 0 | 162 | 4
1 | 3 | 250 | 1 | 99 | 15 | 90 | 3
2 | 3 | 254 | 0 | 112 | 0 | 108 | 3
- 3 | 3 | 254 | 0 | 169 | 0 | 175 | 4</programlisting>
- </refsection>
- <refsection>
- <title>Example: Advanced Map a single band 32BF raster to multiple viewable bands</title>
-
- <para>Create a new 3 band (8BUI,8BUI,8BUI viewable raster) from a raster that has only one 32bf band </para>
- <programlisting>
+ 3 | 3 | 254 | 0 | 169 | 0 | 175 | 4
+ </programlisting>
+ </refsection>
+
+ <refsection>
+ <title>Example: Advanced Map a single band 32BF raster to multiple viewable bands</title>
+ <para>Create a new 3 band (8BUI,8BUI,8BUI viewable raster) from a raster that has only one 32bf band </para>
+ <programlisting>
ALTER TABLE wind ADD COLUMN rast_view raster;
UPDATE wind
set rast_view = ST_AddBand( NULL,
ST_Reclass(rast,1, '11-33):0-255,[0-32:0,(34-1000:0'::text, '8BUI'::text,0),
ST_Reclass(rast,1,'0-32]:0,(32-100:100-255'::text, '8BUI'::text,0)
]
- ) ;</programlisting>
- </refsection>
-
-
- <refsection>
- <title>See Also</title>
- <para>
- <xref linkend="RT_ST_AddBand" />,
- <xref linkend="RT_ST_Band" />,
- <xref linkend="RT_ST_BandPixelType" />,
- <xref linkend="RT_ST_MakeEmptyRaster" />,
- <xref linkend="reclassarg" />,
- <xref linkend="RT_ST_Value" />
- </para>
- </refsection>
- </refentry>
-
- <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>
+ );
+ </programlisting>
+ </refsection>
- <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>
+ <refsection>
+ <title>See Also</title>
+ <para>
+ <xref linkend="RT_ST_AddBand" />,
+ <xref linkend="RT_ST_Band" />,
+ <xref linkend="RT_ST_BandPixelType" />,
+ <xref linkend="RT_ST_MakeEmptyRaster" />,
+ <xref linkend="reclassarg" />,
+ <xref linkend="RT_ST_Value" />
+ </para>
+ </refsection>
+ </refentry>
+
+ <refentry id="RT_ST_Union">
+ <refnamediv>
+ <refname>ST_Union</refname>
+ <refpurpose>Returns the union of a set of raster tiles into a single raster composed of 1 or more bands.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>raster <function>ST_Union</function></funcdef>
+ <paramdef><type>setof raster </type> <parameter>rast</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>raster <function>ST_Union</function></funcdef>
+ <paramdef><type>setof raster </type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>unionarg[] </type> <parameter>unionargset</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>raster <function>ST_Union</function></funcdef>
+ <paramdef><type>setof raster</type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>integer</type> <parameter>nband</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>raster <function>ST_Union</function></funcdef>
+ <paramdef><type>setof raster</type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>text</type> <parameter>uniontype</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>raster <function>ST_Union</function></funcdef>
+ <paramdef><type>setof raster</type> <parameter>rast</parameter></paramdef>
+ <paramdef><type>integer</type> <parameter>nband</parameter></paramdef>
+ <paramdef><type>text</type> <parameter>uniontype</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>Returns the union of a set of raster tiles into a single raster composed of at least one band. The resulting raster's extent is the extent of the whole set. In the case of intersection, the resulting value is defined by <varname>uniontype</varname> which is one of the following: LAST (default), FIRST, MIN, MAX, COUNT, SUM, MEAN, RANGE.</para>
- <refsection>
- <title>Examples</title>
- <programlisting>
--- needs examples
- </programlisting>
- </refsection>
+ <para>Availability: 2.0.0 </para>
+ <para>Enhanced: 2.1.0 Improved Speed (fully C-Based).</para>
+ <para>Availability: 2.1.0 ST_Union(rast, unionarg) variant was introduced.</para>
+ <para>Enhanced: 2.1.0 ST_Union(rast) (variant 1) unions all bands of all input rasters. Prior versions of PostGIS assumed the first band.</para>
+ <para>Enhanced: 2.1.0 ST_Union(rast, uniontype) (variant 4) unions all bands of all input rasters.</para>
+ </refsection>
+ <refsection>
+ <title>Examples: Reconstitute a single band chunked raster tile</title>
+ <programlisting>
+-- this creates a single band from first band of raster tiles
+-- that form the original file system tile
+SELECT filename, ST_Union(rast,1) As file_rast
+FROM sometable WHERE filename IN('dem01', 'dem02') GROUP BY filename;
+ </programlisting>
+ </refsection>
+
+ <refsection>
+ <title>Examples: Return a multi-band raster that is the union of tiles intersecting geometry</title>
+ <programlisting>
+-- this creates a multi band raster collecting all the tiles that intersect a line
+-- Note: In 2.0, this would have just returned a single band raster
+-- , new union works on all bands by default
+-- this is equivalent to unionarg: ARRAY[ROW(1, 'LAST'), ROW(2, 'LAST'), ROW(3, 'LAST')]::unionarg[]
+SELECT ST_Union(rast)
+FROM aerials.boston
+WHERE ST_Intersects(rast, ST_GeomFromText('LINESTRING(230486 887771, 230500 88772)',26986) );
+ </programlisting>
+ </refsection>
+ <refsection>
+ <title>Examples: Return a multi-band raster that is the union of tiles intersecting geometry</title>
+ <para>Here we use the longer syntax if we only wanted a subset of bands or we want to change order of bands</para>
+ <programlisting>
+-- this creates a multi band raster collecting all the tiles that intersect a line
+SELECT ST_Union(rast,ARRAY[ROW(2, 'LAST'), ROW(1, 'LAST'), ROW(3, 'LAST')]::unionarg[])
+FROM aerials.boston
+WHERE ST_Intersects(rast, ST_GeomFromText('LINESTRING(230486 887771, 230500 88772)',26986) );
+ </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>
+ <!-- Optionally add a "See Also" section -->
+ <refsection>
+ <title>See Also</title>
+ <para>
+ <xref linkend="unionarg" />,
+ <xref linkend="RT_ST_Envelope" />,
+ <xref linkend="RT_ST_ConvexHull" />,
+ <xref linkend="RT_ST_Clip" />,
+ <xref linkend="ST_Union" />
+ </para>
+ </refsection>
+ </refentry>
+
+ </sect2> <!-- /map algebra -->
+
+ <sect2 id="Raster_Processing_DEM">
+ <title>DEM (Elevation)</title>
+
+ <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>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>
- <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>
+ <refsection>
+ <title>Description</title>
- <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>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>
- <varname>units</varname> indicates the units of the slope. Possible values are: RADIANS, DEGREES (default), PERCENT.
- </para>
+ <varname>units</varname> indicates the units of the aspect. Possible values are: RADIANS, DEGREES (default).
+ </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>
+ When <varname>units</varname> = RADIANS, values are between 0 and 2 * pi radians measured clockwise from North.
+ </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>
+ When <varname>units</varname> = DEGREES, values are between 0 and 360 degrees measured clockwise from North.
+ </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>.
+ If slope of pixel is zero, aspect of pixel is -1.
</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>
+ <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: 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),
) AS rast
)
SELECT
- ST_DumpValues(ST_Slope(rast, 1, '32BF'))
+ ST_DumpValues(ST_Aspect(rast, 1, '32BF'))
FROM foo
- st_dumpvalues
-
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ 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,"{{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>
- </programlisting>
- </refsection>
- <refsection>
- <title>Examples: Variant 2</title>
+ <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>
+
<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(
)
SELECT
t1.rast,
- ST_Slope(ST_Union(t2.rast), 1, 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>
+ </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_Roughness" />,
- <xref linkend="RT_ST_HillShade" />,
- <xref linkend="RT_ST_Aspect" />
- </para>
- </refsection>
- </refentry>
+ <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_Roughness" />,
+ <xref linkend="RT_ST_HillShade" />,
+ <xref linkend="RT_ST_Slope" />
+ </para>
+ </refsection>
+ </refentry>
+
+ <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>
+
+ <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>
- <refentry id="RT_ST_TPI">
- <refnamediv>
- <refname>ST_TPI</refname>
- <refpurpose>Returns a raster with the calculated Topographic Position Index.</refpurpose>
- </refnamediv>
+ <refsection>
+ <title>Description</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>
- <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>
+ <para>
+ <varname>azimuth</varname> is a value between 0 and 360 degrees measured clockwise from North.
+ </para>
- <refsection>
- <title>Description</title>
+ <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>Calculates the Topographic Position Index, which is defined as the folcal mean with radius of one minus the center cell.</para>
+ <para>
+ <varname>max_bright</varname> is a value between 0 and 255 with 0 as no brightness and 255 as max brightness.
+ </para>
- <note>
- <para>This function only supports a focalmean radius of one.</para>
- </note>
- <para>Availability: 2.1.0</para>
- </refsection>
+ <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>
- <refsection>
- <title>Examples</title>
- <programlisting>
--- needs examples
- </programlisting>
- </refsection>
+ <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>
- <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>
+ <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>
- <refentry id="RT_ST_TRI">
- <refnamediv>
- <refname>ST_TRI</refname>
- <refpurpose>Returns a raster with the calculated Terrain Ruggedness Index.</refpurpose>
- </refnamediv>
+ </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
- <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>
+ 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>
- <title>Description</title>
+ <refsection>
+ <title>Examples: Variant 2</title>
- <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>
+ <para>Complete example of tiles of a coverage. This query only works with PostgreSQL 9.1 or higher.</para>
- <note>
- <para>This function only supports a focalmean radius of one.</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_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>Availability: 2.1.0</para>
- </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_Roughness" />,
+ <xref linkend="RT_ST_Aspect" />,
+ <xref linkend="RT_ST_Slope" />
+ </para>
+ </refsection>
+ </refentry>
+
+ <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>Examples</title>
- <programlisting>
+ <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>
+
+ <refsection>
+ <title>Examples</title>
+ <programlisting>
-- needs examples
- </programlisting>
- </refsection>
+ </programlisting>
+ </refsection>
- <refsection>
- <title>See Also</title>
+ <refsection>
+ <title>See Also</title>
<para>
<xref linkend="RT_ST_MapAlgebra" />,
- <xref linkend="RT_ST_Roughness" />,
+ <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_Union">
- <refnamediv>
- <refname>ST_Union</refname>
- <refpurpose>Returns the union of a set of raster tiles into a single raster composed of 1 or more bands.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>raster <function>ST_Union</function></funcdef>
- <paramdef><type>setof raster </type> <parameter>rast</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <funcsynopsis>
- <funcprototype>
- <funcdef>raster <function>ST_Union</function></funcdef>
- <paramdef><type>setof raster </type> <parameter>rast</parameter></paramdef>
- <paramdef><type>unionarg[] </type> <parameter>unionargset</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <funcsynopsis>
- <funcprototype>
- <funcdef>raster <function>ST_Union</function></funcdef>
- <paramdef><type>setof raster</type> <parameter>rast</parameter></paramdef>
- <paramdef><type>integer</type> <parameter>nband</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <funcsynopsis>
- <funcprototype>
- <funcdef>raster <function>ST_Union</function></funcdef>
- <paramdef><type>setof raster</type> <parameter>rast</parameter></paramdef>
- <paramdef><type>text</type> <parameter>uniontype</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- <funcsynopsis>
- <funcprototype>
- <funcdef>raster <function>ST_Union</function></funcdef>
- <paramdef><type>setof raster</type> <parameter>rast</parameter></paramdef>
- <paramdef><type>integer</type> <parameter>nband</parameter></paramdef>
- <paramdef><type>text</type> <parameter>uniontype</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
+ </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>
+
+ <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>
+ <refsection>
+ <title>Description</title>
- <para>Returns the union of a set of raster tiles into a single raster composed of at least one band. The resulting raster's extent is the extent of the whole set. In the case of intersection, the resulting value is defined by <varname>uniontype</varname> which is one of the following: LAST (default), FIRST, MIN, MAX, COUNT, SUM, MEAN, RANGE.</para>
+ <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>Availability: 2.0.0 </para>
- <note><para>For variant ST_Union(rast,uniontype), band 1 is assumed.</para></note>
- <para>Enhanced: 2.1.0 Improved Speed (fully C-Based).</para>
- <para>Availability: 2.1.0 ST_Union(rast, unionarg) variant was introduced.</para>
- <para>Enhanced: 2.1.0 ST_Union(rast) (variant 1) unions all bands of all input rasters. Prior versions of PostGIS assumed the first band.</para>
- <para>Enhanced: 2.1.0 ST_Union(rast, uniontype) (variant 4) unions all bands of all input rasters.</para>
-
-
- </refsection>
-
- <refsection>
- <title>Examples: Reconstitute a single band chunked raster tile</title>
- <programlisting>
--- this creates a single band from first band of raster tiles
--- that form the original file system tile
-SELECT filename, ST_Union(rast,1) As file_rast
-FROM sometable WHERE filename IN('dem01', 'dem02') GROUP BY filename;</programlisting>
- </refsection>
-
- <refsection>
- <title>Examples: Return a multi-band raster that is the union of tiles intersecting geometry</title>
- <para>-- this creates a multi band raster collecting all the tiles that intersect a line
--- Note: In 2.0, this would have just returned a single band raster
--- , new union works on all bands by default
--- this is equivalent to unionarg: ARRAY[ROW(1, 'LAST'), ROW(2, 'LAST'), ROW(3, 'LAST')]::unionarg[] </para>
- <programlisting>SELECT ST_Union(rast)
-FROM aerials.boston
-WHERE ST_Intersects(rast, ST_GeomFromText('LINESTRING(230486 887771, 230500 88772)',26986) );</programlisting>
- </refsection>
- <refsection>
- <title>Examples: Return a multi-band raster that is the union of tiles intersecting geometry</title>
- <para>Here we use the longer syntax if we only wanted a subset of bands or we want to change order of bands</para>
- <programlisting>-- this creates a multi band raster collecting all the tiles that intersect a line
-SELECT ST_Union(rast,ARRAY[ROW(2, 'LAST'), ROW(1, 'LAST'), ROW(3, 'LAST')]::unionarg[])
-FROM aerials.boston
-WHERE ST_Intersects(rast, ST_GeomFromText('LINESTRING(230486 887771, 230500 88772)',26986) );</programlisting>
- </refsection>
+ <para>
+ <varname>units</varname> indicates the units of the slope. Possible values are: RADIANS, DEGREES (default), PERCENT.
+ </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: 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_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_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_TPI">
+ <refnamediv>
+ <refname>ST_TPI</refname>
+ <refpurpose>Returns a raster with the calculated Topographic Position Index.</refpurpose>
+ </refnamediv>
+
+ <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>
+
+ <refsection>
+ <title>Description</title>
+
+ <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>
+ <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_Roughness" />,
+ <xref linkend="RT_ST_Slope" />,
+ <xref linkend="RT_ST_HillShade" />,
+ <xref linkend="RT_ST_Aspect" />
+ </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>
+
+ <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>
+
+ <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_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> <!-- /DEM -->
+
+ <sect2 id="Raster_Processing_Geometry">
+ <title>Raster to Geometry</title>
+
+ <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>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>
+ 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>
+
+ <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;
+
+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>
+ <xref linkend="RT_ST_Envelope" />
+ </para>
+ </refsection>
+ </refentry>
+
+ <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>
+
+ <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>
+ <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 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;
+
+ 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>
+
+ <refsection>
+ <title>See Also</title>
+ <para>
+ <xref linkend="geomval" />,
+ <xref linkend="RT_ST_Value" />,
+ <xref linkend="RT_ST_Polygon" />,
+ <xref linkend="RT_ST_ValueCount" />
+ </para>
+ </refsection>
+ </refentry>
+
+ <refentry id="RT_ST_Envelope">
+ <refnamediv>
+ <refname>ST_Envelope</refname>
+ <refpurpose>Returns the polygon representation of the extent of the raster.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>geometry <function>ST_Envelope</function></funcdef>
+ <paramdef><type>raster </type> <parameter>rast</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>
+ </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))
+ </programlisting>
+ </refsection>
+
+ <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">
+ <refnamediv>
+ <refname>ST_MinConvexHull</refname>
+ <refpurpose>
+ Return the convex hull geometry of the raster excluding NODATA pixels.
+ </refpurpose>
+ </refnamediv>
+
+ <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>
+
+ <refsection>
+ <title>Description</title>
+
+ <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>Availability: 2.1.0 </para>
+ </refsection>
+
+ <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
+
+ 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>
+
+ <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;
+
+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;
+
+-- 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;
+
+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)))
+
+-- Or if you want the no data value different for just one time
+
+SELECT ST_AsText(
+ ST_Polygon(
+ ST_SetBandNoDataValue(rast,1,252)
+ )
+ ) As geomwkt
+FROM dummy_rast
+WHERE rid =2;
+
+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>
+
+ <refsection>
+ <title>See Also</title>
+ <para>
+ <xref linkend="RT_ST_Value" />,
+ <xref linkend="RT_ST_DumpAsPolygons" />
+ </para>
+ </refsection>
+ </refentry>
+
+ </sect2> <!-- /misc -->
- <!-- Optionally add a "See Also" section -->
- <refsection>
- <title>See Also</title>
- <para>
- <xref linkend="unionarg" />,
- <xref linkend="RT_ST_Envelope" />,
- <xref linkend="RT_ST_ConvexHull" />,
- <xref linkend="RT_ST_Clip" />,
- <xref linkend="ST_Union" />
- </para>
- </refsection>
- </refentry>
</sect1>
- <sect1 id="Raster_Processing_Builtin_Functions">
- <title>Raster Processing Builtin Functions</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>
projects / postgis / commitdiff