Changes between Version 61 and Version 62 of WKTRaster/SpecificationWorking03

Timestamp:

04/15/11 08:16:25 (2 years ago)

Author:

dustymugs

Comment:

addition of ST_Reclass

WKTRaster/SpecificationWorking03

@@ -407 +407 @@
 ----
 
+'''ST_Reclass(rast raster, VARIADIC argset reclassarg[]) -> raster'''
+
+Due to limitations in the JPEG (8BUI) and PNG (8BUI and 16BUI) raster formats regarding supported pixel/data types, a method must be provided that can convert a band of a larger data type to 8BUI, amongst other uses.  ST_Reclass allows raster's band pixel values to be remapped from one range of numbers to another as well as between pixel types, e.g. 32BF to 8BUI.
+
+ST_Reclass returns a duplicate of the submitted raster with the bands specified to be reclassed being processed.  This means that if a raster with 5 bands are submitted and band 1 is to be reclassed, the output raster will have 5 bands with band 1 reclassified.  The other four bands will not be touched.
+
+1. ST_Reclass(rast raster, VARIADIC argset reclassarg[]) -> raster
+
+  rast: the raster whose specified bands are to be reclassified
+
+  reclassarg: a new custom type defining the parameters required for reclassifying a band's pixel values.
+
+{{{
+CREATE TYPE reclassarg AS (
+
+  nband int,
+
+  reclassexpr text,
+
+  pixeltype text,
+
+  nodata double
+
+); 
+}}}
+
+    nband: index of the band to reclass (1-based)
+
+    reclassexpr: reclassification expression indicating the ranges to convert from and to.  More than one expression can be provided by separating the expression with a comma (,).  The values provided can be of any valid numeric type.
+
+      ''rangefrom:rangeto[, rangefrom:rangeto]''
+
+{{{
+0-100:0-10
+
+0-100:0-10, 101-1000:11-100
+
+0-100:0-10, 101-1000:11-100, 1001-10000:101-1000
+}}}
+
+      In the last example above, the default evaluation of the ranges is
+
+{{{
+        0 <= x < 100 reclassified to 0 <= y <= 10
+
+        101 <= x < 1000 reclassified to 11 <= y <= 100
+
+        1001 <= x < 10000 reclassified to 101 <= y <= 1000
+}}}
+
+      To change the evaluation of rangefrom, use square brackets and parentheses.
+
+{{{
+1. [a-b] = a <= x <= b
+
+2. (a-b] = a < x <= b
+
+3. [a-b) = a <= x < b
+
+4. (a-b) = a < x < b
+}}}
+
+      !#3 above is the default evaluation of x in the range a-b. The use of square brackets and parentheses are optional, so the examples below would be permitted. Missing notations substitute the appropriate notation from #3 above. 
+
+{{{
+[a-b = a <= x < b
+
+(a-b = a < x < b
+
+a-b] = a <= x <= b
+
+a-b) = a <= x < b
+}}}
+
+    pixeltype: the reclassified band's pixel type, e.g. 8BUI, 16BUI, 32BF
+
+    nodata: the nodata value of the reclassified band.  If the source band has a nodata value, all source pixel value equal to the source nodata value will be converted to the reclassified band's nodata value.  If set to NULL, the reclassified band will NOT have a nodata value specified.
+
+{{{
+ST_Reclass(rast, ROW(1, '0-100:0-10, 101-1000:11-100, 1001-10000:101-1000', '16BUI', NULL));
+
+ST_Reclass(rast, ROW(1, '0-100:0-10, 101-1000:11-100, 1001-10000:101-1000', '16BUI', 1001));
+
+ST_Reclass(rast,
+  ROW(1, '0-100:0-10, 101-1000:11-100, 1001-10000:101-1000', '16BUI', 1001),
+  ROW(2, '0-100:0-10, 101-1000:11-100, 1001-10000:101-1000', '16BUI', 1001),
+  ROW(3, '0-100:0-10, 101-1000:11-100, 1001-10000:101-1000', '16BUI', 1001),
+  ROW(5, '0-100:0-10, 101-1000:11-100, 1001-10000:101-1000', '16BUI', 1001)
+)
+}}}
+
+  An expanded example
+
+{{{
+SELECT ST_Reclass(
+  ST_Band(rast, ARRAY[1,1,1]), 
+  1, LEAST(covmin, 0)::text || '-0:0,0-' || GREATEST(covmax, 0)::text || ':0-255', '8BUI',
+  2, LEAST(covmin, 0)::text || '-0:200,0-' || GREATEST(covmax, 0)::text' || ':0-255','8BUI',
+  3, LEAST(covmin, 0)::text || '-0:255,0-' || (GREATEST(covmax, 0)/2)::text' || ':0,' || (GREATEST(covmax, 0)/2)::text' || ':' || GREATEST(covmax, 0)::text || ':0-255', '8BUI')
+FROM mycoverage
+}}}
+
+2. ST_Reclass(rast raster, nband int, reclassexpr text, pixeltype text, nodata double) -> raster
+
+  provides a method to process just one band of a raster
+
+{{{
+ST_Reclass(rast, 1, '0-100:0-10', '8BUI', 11)
+}}}
+
+3. ST_Reclass(rast raster, nband int, reclassexpr text, pixeltype text) -> raster
+
+  nodata parameter removed so reclassified band will NOT have a nodata value set
+
+{{{
+ST_Reclass(rast, 1, '0-100:0-10', '8BUI')
+}}}
+
+4. ST_Reclass(rast raster, reclassexpr text, pixeltype text) -> raster
+
+  nband parameter removed so reclassified band is assumed to be 1.  nodata parameter removed so reclassified band has NO nodata value.
+
+{{{
+ST_Reclass(rast, '0-100:0-10', '8BUI')
+}}}
+
+5. ST_Reclass(rast raster, reclassexpr text, pixeltype text, nodata double) -> raster
+
+  nband parameter removed so reclassified band is assumed to be 1
+
+{{{
+ST_Reclass(rast, '0-100:0-10', '8BUI', 11)
+}}}
+
+----
+
 == '''Objective FV.02 - Being able to intersect vector and raster to produce raster.''' ==
  
@@ -607 +743 @@
 '''ST_SelectByValue(raster|geometry, ‘expression’) -> same type as first argument'''[[BR]]
 '''ST_Reclass(raster|geometry,string) -> same type as first argument'''[[BR]]
+
+Bborie: Implementation has been moved to FV.01 above.
 
 '''ST_MapAlgebra(raster|geometry, [raster|geometry,…] ‘mathematical expression’, ‘raster’ |’geometry’) -> raster/geometry'''