self-hosted/postgis
self-hosted/postgis
1
0
Fork 0
mirror of https://git.osgeo.org/gitea/postgis/postgis synced 2024-10-23 16:42:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

Updated docs for new type addbandarg and new ST_AddBand() variant

Browse source 
git-svn-id: http://svn.osgeo.org/postgis/trunk@10131 b70326c6-7e19-0410-871a-916f4a2858ee
This commit is contained in:
Bborie Park 2012-07-27 19:46:10 +00:00
parent e33c9bac72
commit 135fe6ec68
2 changed files with 196 additions and 69 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
NEWS
View file

@ -24,11 +24,12 @@ PostGIS 2.1.0
* Enhancements *
- #823, tiger geocoder: Make loader_generate_script download portion less greedy
- #1661, Add aggregate variant of ST_SameAlignment
- #1719, Add support for Point and GeometryCollection ST_MakeValid inputs
- #1796, Big performance boost for distance calculations in geography
- #1802, improved function interruptibility.
- #1856, tiger geocoder: reverse geocoder rating setting for prefer numbered highway name
- #1661, Add aggregate variant of ST_SameAlignment
- #1938, Refactor basic ST_AddBand to add multiple new bands in one call
* Fixes *

262
doc/reference_raster.xml
View file

@ -69,7 +69,79 @@ VALUES (1,
<para><xref linkend="PostGIS_Geometry_DumpFunctions" /> </para>
</refsection>
</refentry>
<refentry id="addbandarg">
<refnamediv>
<refname>addbandarg</refname>
<refpurpose>A composite type used as input into the ST_AddBand function defining the attributes and initial value of the new band.</refpurpose>
</refnamediv>
<refsection>
<title>Description</title>
<para>
A composite type used as input into the ST_AddBand function defining the attributes and initial value of the new band.
<variablelist>
<varlistentry>
<term>
<parameter>index </parameter>
<type>integer</type>
</term>
<listitem>
<para>
1-based value indicating the position where the new band will be added amongst the raster's bands. If NULL, the new band will be added at the end of the raster's bands.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>pixeltype </parameter>
<type>text</type>
</term>
<listitem>
<para>
Pixel type of the new band. One of defined pixel types as described in <xref linkend="RT_ST_BandPixelType" />.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>initialvalue </parameter>
<type>double precision</type>
</term>
<listitem>
<para>
Initial value that all pixels of new band will be set to.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>nodataval </parameter>
<type>double precision</type>
</term>
<listitem>
<para>
NODATA value of the new band. If NULL, the new band will not have a NODATA value assigned.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsection>
<refsection>
<title>See Also</title>
<para>
<xref linkend="RT_ST_AddBand" />
</para>
</refsection>
</refentry>
<refentry id="histogram">
<refnamediv>
<refname>histogram</refname>
@ -880,75 +952,94 @@ WHERE short_name = 'GTiff') As g;
</sect1>
<sect1 id="Raster_Constructors">
<title>Raster Constructors</title>
<refentry id="RT_ST_AddBand">
<sect1 id="Raster_Constructors">
<title>Raster Constructors</title>
<refentry id="RT_ST_AddBand">
<refnamediv>
<refname>ST_AddBand</refname>
<refpurpose>Returns a raster with the new band(s) of given type added with given initial value in the given index location. If no index is specified, the band is added to the end.</refpurpose>
<refpurpose>
Returns a raster with the new band(s) of given type added with given initial value in the given index location. If no index is specified, the band is added to the end.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>raster <function>ST_AddBand</function></funcdef>
<paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
<paramdef><type>text </type> <parameter>pixeltype</parameter></paramdef>
<paramdef choice='opt'><type>double precision </type> <parameter>initialvalue=0</parameter></paramdef>
<paramdef choice='opt'><type>double precision </type> <parameter>nodataval=NULL</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>raster <function>ST_AddBand</function></funcdef>
<paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
<paramdef><type>integer </type> <parameter>index</parameter></paramdef>
<paramdef><type>text </type> <parameter>pixeltype</parameter></paramdef>
<paramdef choice='opt'><type>double precision </type> <parameter>initialvalue=0</parameter></paramdef>
<paramdef choice='opt'><type>double precision </type> <parameter>nodataval=NULL</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>raster <function>ST_AddBand</function></funcdef>
<paramdef><type>raster </type> <parameter>torast</parameter></paramdef>
<paramdef><type>raster </type> <parameter>fromrast</parameter></paramdef>
<paramdef choice='opt'><type>integer </type> <parameter>fromband=1</parameter></paramdef>
<paramdef choice='opt'><type>integer </type> <parameter>torastindex=at_end</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>raster <function>ST_AddBand</function></funcdef>
<paramdef><type>raster </type> <parameter>torast</parameter></paramdef>
<paramdef><type>raster[] </type> <parameter>fromrasts</parameter></paramdef>
<paramdef choice='opt'><type>integer </type> <parameter>fromband=1</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>raster <function>ST_AddBand</function></funcdef>
<paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
<paramdef><type>addbandarg[] </type> <parameter>addbandargset</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>raster <function>ST_AddBand</function></funcdef>
<paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
<paramdef><type>text </type> <parameter>pixeltype</parameter></paramdef>
<paramdef choice='opt'><type>double precision </type> <parameter>initialvalue=0</parameter></paramdef>
<paramdef choice='opt'><type>double precision </type> <parameter>nodataval=NULL</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>raster <function>ST_AddBand</function></funcdef>
<paramdef><type>raster </type> <parameter>rast</parameter></paramdef>
<paramdef><type>integer </type> <parameter>index</parameter></paramdef>
<paramdef><type>text </type> <parameter>pixeltype</parameter></paramdef>
<paramdef choice='opt'><type>double precision </type> <parameter>initialvalue=0</parameter></paramdef>
<paramdef choice='opt'><type>double precision </type> <parameter>nodataval=NULL</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>raster <function>ST_AddBand</function></funcdef>
<paramdef><type>raster </type> <parameter>torast</parameter></paramdef>
<paramdef><type>raster </type> <parameter>fromrast</parameter></paramdef>
<paramdef choice='opt'><type>integer </type> <parameter>fromband=1</parameter></paramdef>
<paramdef choice='opt'><type>integer </type> <parameter>torastindex=at_end</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>raster <function>ST_AddBand</function></funcdef>
<paramdef><type>raster </type> <parameter>torast</parameter></paramdef>
<paramdef><type>raster[] </type> <parameter>fromrasts</parameter></paramdef>
<paramdef choice='opt'><type>integer </type> <parameter>fromband=1</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Returns a raster with a new band added in given position (index), of given type, of given initial value, and of given nodata value. If no index is specified, the band is added to the end.
If no <varname>fromband</varname> is specified, band 1 is assumed. Pixel type is a string representation
of one of the pixel types specified in <xref linkend="RT_ST_BandPixelType" />. If an existing index is specified all subsequent bands >= that index are incremented by 1.
If an initial value greater than the max of the pixel type
is specified, then the initial value is set to the highest
value allowed by the pixel type. The last version add the
<varname>fromband</varname> from <varname>fromrast</varname> raster to <varname>torast</varname> in position <varname>torastindex</varname>.</para>
<para>For the version that takes an array of bands if <varname>torast</varname> is NULL, then the <varname>fromband</varname> band of each raster in the array
is accumulated into a new raster </para>
</refsection>
<refsection>
<title>Examples: Single Add Band versions</title>
<programlisting>-- Add another band of type 8 bit unsigned integer with pixels initialized to 200
<title>Description</title>
<para>
Returns a raster with a new band added in given position (index), of given type, of given initial value, and of given nodata value. If no index is specified, the band is added to the end. If no <varname>fromband</varname> is specified, band 1 is assumed. Pixel type is a string representation of one of the pixel types specified in <xref linkend="RT_ST_BandPixelType" />. If an existing index is specified all subsequent bands >= that index are incremented by 1. If an initial value greater than the max of the pixel type is specified, then the initial value is set to the highest value allowed by the pixel type. The last version add the <varname>fromband</varname> from <varname>fromrast</varname> raster to <varname>torast</varname> in position <varname>torastindex</varname>.
</para>
<para>
For the version that takes an array of <xref linkend="addbandarg" />, a specific addbandarg's index value is relative to the raster at the time when the band described by that addbandarg is being added to the raster. See the Multiple New Bands example below.
</para>
<para>
For the version that takes an array of bands if <varname>torast</varname> is NULL, then the <varname>fromband</varname> band of each raster in the array is accumulated into a new raster.
</para>
</refsection>
<refsection>
<title>Examples: Single New Band versions</title>
<programlisting>
-- Add another band of type 8 bit unsigned integer with pixels initialized to 200
UPDATE dummy_rast
SET rast = ST_AddBand(rast,'8BUI'::text,200)
WHERE rid = 1;
</programlisting>
<programlisting>-- Create an empty raster 100x100 units, with upper left right at 0, add 2 bands (band 1 is 0/1 boolean bit switch, band2 allows values 0-15)
</programlisting>
<programlisting>
-- Create an empty raster 100x100 units, with upper left right at 0, add 2 bands (band 1 is 0/1 boolean bit switch, band2 allows values 0-15)
INSERT INTO dummy_rast(rid,rast)
VALUES(10, ST_AddBand(ST_AddBand(ST_MakeEmptyRaster(100, 100, 0, 0, 1, -1, 0, 0, 0), '1BB'::text), '4BUI'::text) );
@ -971,14 +1062,42 @@ FROM (SELECT ST_MetaData(rast) As rmd
upperleftx | upperlefty | width | height | scalex | scaley | skewx | skewy | srid | numbands
------------+------------+-------+--------+------------+------------+-------+-------+------+----------
0 | 0 | 100 | 100 | 1 | -1 | 0 | 0 | 0 | 2
</programlisting>
</programlisting>
</refsection>
<refsection>
<title>Examples: Multi-Band versions</title>
<programlisting>-- Aggregate the 1st band of a table of like rasters into a single raster
<title>Examples: Multiple New Bands</title>
<programlisting>
SELECT
*
FROM ST_BandMetadata(
ST_AddBand(
ST_MakeEmptyRaster(10, 10, 0, 0, 1, -1, 0, 0, 0),
ARRAY[
ROW(NULL, '8BUI', 255, 0),
ROW(NULL, '16BUI', 1, 2),
ROW(2, '32BUI', 100, 12),
ROW(2, '32BF', 3.14, -1)
]::addbandarg[]
),
ARRAY[]::integer[]
);
bandnum | pixeltype | nodatavalue | isoutdb | path
---------+-----------+-------------+---------+------
1 | 8BUI | 0 | f |
2 | 32BF | -1 | f |
3 | 32BUI | 12 | f |
4 | 16BUI | 2 | f |
</programlisting>
</refsection>
<refsection>
<title>Examples: Multi-Band versions</title>
<programlisting>
-- Aggregate the 1st band of a table of like rasters into a single raster
-- with as many bands as there are test_types and as many rows (new rasters) as there are mice
-- NOTE: The ORDER BY test_type is only supported in PostgreSQL 9.0+
-- for 8.4 and below it usually works to order your data in a subselect (but not guaranteed)
@ -986,16 +1105,23 @@ FROM (SELECT ST_MetaData(rast) As rmd
-- For mouse lovers: No mice were harmed in this exercise
SELECT mouse, ST_AddBand(NULL, array_agg(rast ORDER BY test_type), 1 ) As rast
FROM mice_studies
GROUP BY mouse;
</programlisting>
GROUP BY mouse;
</programlisting>
</refsection>
<refsection>
<title>See Also</title>
<para><xref linkend="RT_ST_BandMetaData" />, <xref linkend="RT_ST_BandPixelType" />, <xref linkend="RT_ST_MakeEmptyRaster" />, <xref linkend="RT_ST_MetaData" />, <xref linkend="RT_ST_NumBands" />, <xref linkend="RT_ST_Reclass" /></para>
<para>
<xref linkend="RT_ST_BandMetaData" />,
<xref linkend="RT_ST_BandPixelType" />,
<xref linkend="RT_ST_MakeEmptyRaster" />,
<xref linkend="RT_ST_MetaData" />,
<xref linkend="RT_ST_NumBands" />,
<xref linkend="RT_ST_Reclass" />
</para>
</refsection>
</refentry>
<refentry id="RT_ST_AsRaster">
<refnamediv>
<refname>ST_AsRaster</refname>