Add documentation for {Add,Drop}OverviewConstraints (#2824)

git-svn-id: http://svn.osgeo.org/postgis/trunk@12934 b70326c6-7e19-0410-871a-916f4a2858ee

diff --git a/doc/reference_raster.xml b/doc/reference_raster.xml
index 222febc8c7dd6ff61c77be55602774a20a899b46..863a6949d76b2c1f61ef06e08be23a414b1af4fa 100644 (file)
--- a/doc/reference_raster.xml
+++ b/doc/reference_raster.xml
@@ -800,6 +800,171 @@ SELECT srid, scale_x, scale_y, blocksize_x, blocksize_y, num_bands, pixel_types,
                <para><xref linkend="RT_AddRasterConstraints"/></para>
          </refsection>
        </refentry>
+
+  <refentry id="RT_AddOverviewConstraints">
+         <refnamediv>
+               <refname>AddOverviewConstraints</refname>
+
+               <refpurpose>Tag a raster column as being an overview of another.</refpurpose>
+         </refnamediv>
+
+         <refsynopsisdiv>
+               <funcsynopsis>
+
+                 <funcprototype>
+        <funcdef>boolean <function>AddOverviewConstraints</function></funcdef>
+        <paramdef><type>name </type>
+        <parameter>ovschema</parameter></paramdef>
+        <paramdef><type>name </type>
+        <parameter>ovtable</parameter></paramdef>
+        <paramdef><type>name </type>
+        <parameter>ovcolumn</parameter></paramdef>
+        <paramdef><type>name </type>
+        <parameter>refschema</parameter></paramdef>
+        <paramdef><type>name </type>
+        <parameter>reftable</parameter></paramdef>
+        <paramdef><type>name </type>
+        <parameter>refcolumn</parameter></paramdef>
+        <paramdef><type>int </type>
+        <parameter>ovfactor</parameter></paramdef>
+                 </funcprototype>
+
+                 <funcprototype>
+        <funcdef>boolean <function>AddOverviewConstraints</function></funcdef>
+        <paramdef><type>name </type>
+        <parameter>ovtable</parameter></paramdef>
+        <paramdef><type>name </type>
+        <parameter>ovcolumn</parameter></paramdef>
+        <paramdef><type>name </type>
+        <parameter>reftable</parameter></paramdef>
+        <paramdef><type>name </type>
+        <parameter>refcolumn</parameter></paramdef>
+        <paramdef><type>int </type>
+        <parameter>ovfactor</parameter></paramdef>
+                 </funcprototype>
+
+               </funcsynopsis>
+         </refsynopsisdiv>
+
+         <refsection>
+               <title>Description</title>
+
+               <para>
+Adds constraints on a raster column that are used to display information
+in the <varname>raster_overviews</varname> raster catalog.
+               </para>
+               <para>
+The <varname>ovfactor</varname> parameter represents the scale multiplier
+in the overview column: higher overview factors have lower resolution.
+               </para>
+               <para>
+When the <varname>ovschema</varname> and <varname>refschema</varname>
+parameters are omitted, the first table found scanning the
+<varname>search_path</varname> will be used.
+               </para>
+
+               <para>Availability: 2.0.0</para>
+         </refsection>
+
+         <refsection>
+               <title>Examples</title>
+
+               <programlisting>
+CREATE TABLE res1 AS SELECT
+ST_AddBand(
+  ST_MakeEmptyRaster(1000, 1000, 0, 0, 2),
+  1, '8BSI'::text, -129, NULL
+) r1;
+
+CREATE TABLE res2 AS SELECT
+ST_AddBand(
+  ST_MakeEmptyRaster(500, 500, 0, 0, 4),
+  1, '8BSI'::text, -129, NULL
+) r2;
+
+SELECT AddOverviewConstraints('res2', 'r2', 'res1', 'r1', 2);
+
+-- verify if registered correctly in the raster_overviews view --
+SELECT o_table_name ot, o_raster_column oc,
+       r_table_name rt, r_raster_column rc,
+       overview_factor f
+FROM raster_overviews WHERE o_table_name = 'res2';
+  ot  | oc |  rt  | rc | f
+------+----+------+----+---
+ res2 | r2 | res1 | r1 | 2
+(1 row)
+               </programlisting>
+         </refsection>
+
+         <refsection>
+               <title>See Also</title>
+
+      <para>
+ <xref linkend="RT_Raster_Overviews"/>,
+ <xref linkend="RT_DropOverviewConstraints"/>,
+ <xref linkend="RT_AddRasterConstraints"/>
+      </para>
+         </refsection>
+       </refentry>
+
+  <refentry id="RT_DropOverviewConstraints">
+         <refnamediv>
+               <refname>DropOverviewConstraints</refname>
+
+               <refpurpose>Untag a raster column from being an overview of another.</refpurpose>
+         </refnamediv>
+
+         <refsynopsisdiv>
+               <funcsynopsis>
+
+                 <funcprototype>
+        <funcdef>boolean <function>DropOverviewConstraints</function></funcdef>
+        <paramdef><type>name </type>
+        <parameter>ovschema</parameter></paramdef>
+        <paramdef><type>name </type>
+        <parameter>ovtable</parameter></paramdef>
+        <paramdef><type>name </type>
+        <parameter>ovcolumn</parameter></paramdef>
+                 </funcprototype>
+
+                 <funcprototype>
+        <funcdef>boolean <function>AddOverviewConstraints</function></funcdef>
+        <paramdef><type>name </type>
+        <parameter>ovtable</parameter></paramdef>
+        <paramdef><type>name </type>
+        <parameter>ovcolumn</parameter></paramdef>
+                 </funcprototype>
+
+               </funcsynopsis>
+         </refsynopsisdiv>
+
+         <refsection>
+               <title>Description</title>
+
+               <para>
+Remove from a raster column the constraints used to show it as
+being an overview of another in the <varname>raster_overviews</varname>
+raster catalog.
+               </para>
+               <para>
+When the <varname>ovschema</varname> parameter is omitted,
+the first table found scanning the <varname>search_path</varname>
+will be used.
+               </para>
+
+               <para>Availability: 2.0.0</para>
+         </refsection>
+
+         <refsection>
+               <title>See Also</title>
+
+      <para>
+ <xref linkend="RT_Raster_Overviews"/>,
+ <xref linkend="RT_AddOverviewConstraints"/>,
+ <xref linkend="RT_DropRasterConstraints"/>
+      </para>
+         </refsection>
+       </refentry>
        
                <refentry id="RT_PostGIS_GDAL_Version">
                        <refnamediv>

diff --git a/doc/using_raster_dataman.xml b/doc/using_raster_dataman.xml
index fb7671a12a5f5c122aa1b20f38e85022ac5805f9..8d08af97c72e95a102c3f6994a6fd7161eb16df7 100644 (file)
--- a/doc/using_raster_dataman.xml
+++ b/doc/using_raster_dataman.xml
@@ -495,7 +495,7 @@ Available GDAL raster formats:
         </sect2>
         <sect2 id="RT_Raster_Overviews">
                <title>Raster Overviews</title>
-               <para><varname>raster_overviews</varname> catalogs information about raster table columns used for overviews and additional information about them that is useful to know when utilizing overviews. Overview tables are cataloged in both <varname>raster_columns</varname> and <varname>raster_overviews</varname> because they are rasters in their own right but also serve an additional special purpose of being a lower resolution caricature of a higher resolution table. These are generated along-side the main raster table when you use the <varname>-l</varname> switch in raster loading.</para>
+               <para><varname>raster_overviews</varname> catalogs information about raster table columns used for overviews and additional information about them that is useful to know when utilizing overviews. Overview tables are cataloged in both <varname>raster_columns</varname> and <varname>raster_overviews</varname> because they are rasters in their own right but also serve an additional special purpose of being a lower resolution caricature of a higher resolution table. These are generated along-side the main raster table when you use the <varname>-l</varname> switch in raster loading or can be generated manually using <xref linkend="RT_AddOverviewConstraints" />.</para>
                <para>Overview tables contain the same constraints as other raster tables as well as additional informational only constraints specific to overviews.</para>
                <note><para>The information in <varname>raster_overviews</varname> does not duplicate the information in <varname>raster_columns</varname>.  If you need the information about an overview table present in <varname>raster_columns</varname> you can join the <varname>raster_overviews</varname> and <varname>raster_columns</varname> together to get the full set of information you need.</para> </note>
                <para>Two main reasons for overviews are:</para>