Context Navigation

Changes between Version 99 and Version 100 of WKTRaster/SpecificationWorking03

Timestamp:: Jun 13, 2011, 1:52:09 PM (13 years ago)
Author:: pracine
Comment:: —

Legend:

: Unmodified
: Added
: Removed
: Modified

WKTRaster/SpecificationWorking03

-              v99
+              v100
 ----
+== '''Objective FV.01 - Being able to return a JPEG, a TIFF, a PNG or any image format supported by GDAL - ''DONE''''' ==
+'''ST_bytea(raster, integer) -> raster''' -- the integer parameters is the band number of the raster.[[BR]]
+What is does?
+----
+~~'''Open Question:''' When exporting a multiband raster to JPEG, TIFF, PNG, SVG or KML, how should we specify the band number in the exporting function.~~
+~~There is two options to select the band to convert from a multiband raster in all the ST_AsFormat functions. [[BR]]~~
+[[BR]]
+~~ 1. Precede each call with ST_Band() to return a selected band.[[BR]]~~
+~~  Pros: This is a general function that can be called before any function that would otherwise require a band parameter.[[BR]]~~
+~~  Cons: This implies creating a temporary raster. This might be more elegant and general but is this too much overhead comparing with having a band parameter?~~
+~~ 2. Add a band parameter to each ST_AsFormat function.[[BR]]~~
+~~  Pros: Hypothetically less overhead.[[BR]]~~
+~~  Cons: Every functions implying access to a band should then have this parameter when in most case it would be equal to 1. In many cases it makes no sence to have to specify a band parameter since it is the whole raster that we want to export, including all the bands.~~
+~~Pierre: More I think about it more I think that the first option is the best one...~~
+~~mloskot: Perhaps there is a compromise in form of two sets of functions: 1) ST_As* which always burn the whole raster (all bands) 2) ST_BandAs* which takes number of band as a parameter and return only this requested band.~~
+----
+'''ST_Band(raster, integer) -> raster''' -- the integer parameters are the band number of the rasters.[[BR]]
+Return a single band from a multiband raster. If "band" is greater than the value returned by ST_GetNumBands(), the function returns the last band. This function should be used to select a band before converting it to JPEG, TIFF, PNG, SVG or KML with the corresponding function. e.g. '''ST_AsTIFF(ST_Band(raster, band))
+A complete implementation of ST_Band should include the following:
+. ST_Band(rast raster, nbands int[]) -> raster
+    nbands is an array of 1-based band indices of the bands to copy into the output raster
+    For a raster rast with 3 bands:
+{{{
+ST_Band(rast, ARRAY[1,3,2])
+ST_Band(rast, ARRAY[3,2,1])
+}}}
+    You can rearrange the bands as above. You can also duplicate the bands:
+{{{
+ST_Band(rast, ARRAY[1,2,3,2,1])
+}}}
+. ST_Band(rast raster, nband int) -> raster
+    nband is a single integer of the 1-based band index of the band to copy into the output raster
+{{{
+ST_Band(rast, 1)
+ST_Band(rast, 3)
+}}}
+. ST_Band(rast raster, nbands text) -> raster
+    nbands is a comma separated string of 1-based band indices indicating the bands to copy into the output raster
+{{{
+ST_Band(rast, '1,2')
+ST_Band(rast, '1,2,3, 1, 1 , 2')
+}}}
+. ST_Band(rast raster, nbands text, delimiter char) -> raster
+    nbands is a user-specified delimiter separated string of 1-based band indices indicating the bands to copy into the output raster
+{{{
+ST_Band(rast, '1,2', ',')
+ST_Band(rast, '1,2,3, 1, 1 , 2', ',')
+}}}
+. ST_Band(rast raster) -> raster
+    the band to extract is automatically assumed to be one.
+{{{
+ST_Band(rast)
+}}}
+If an index is outside the valid range of band indices for a raster (less than 1 or greater than the value returned by ST_NumBands), the function will fail and return.
+~~''' Open Question: ''' Should the function fail if an index is invalid?  How should this work when providing more than one indices to the function?~~
+----
+'''ST_AsJPEG(raster, quality) -> JPEG as "bytea"'''[[BR]]
+The JPEG format has several limitations:
+. JPEG only allows 1 (greyscale) or 3 (RGB) bands of data
+. JPEG only supports 8BUI pixeltype
+. JPEG cannot embed spatial reference information within the file but can have an associated world file
+To address the limitations:
+. Use ST_Band to specify which band(s) should be passed to the ST_AsJPEG function. Variations of ST_AsJPEG are made available that allows specifying a band index. If a raster whose number of specified bands does not equal 1 or 3 is provided, a warning is raised and the first or the first three bands are used.
+. Throw an exception if any of the specified bands is not 8BUI. The user should use ST_Reclass to convert any non-8BUI bands to 8BUI.
+. Nothing can be done.
+A proposed set of variations of the ST_AsJPEG function:
+. ST_AsJPEG(rast raster, options text[])
+    rast: the raster with one or three bands in 8BUI pixel type to generate a JPEG image from
+    options: array of creation options to pass to the GDAL JPEG driver
+{{{
+ST_AsJPEG(rast, ARRAY['QUALITY=90', 'PROGRESSIVE=ON'])
+}}}
+. ST_AsJPEG(rast raster)
+    Like !#1 above but use the driver's default creation options
+. ST_AsJPEG(rast raster, nbands int[], options text[])
+    nbands: an integer array specifying the band indices of the raster to include in the JPEG file
+{{{
+ST_AsJPEG(rast, ARRAY[1,3,6], ARRAY['QUALITY=50'])
+}}}
+. ST_AsJPEG(rast raster, nbands int[])
+    Like !#3, but use the default creation options
+{{{
+ST_AsJPEG(rast, ARRAY[1,3,6])
+}}}
+. ST_AsJPEG(rast raster, nbands int[], quality int)
+    quality: number between 10 and 100 indicating image quality
+{{{
+ST_AsJPEG(rast, ARRAY[1,2,3], 90)
+}}}
+. ST_AsJPEG(rast raster, nband int, options text[])
+    nband: index of the band to include
+{{{
+ST_AsJPEG(rast, 2, ARRAY['QUALITY=25'])
+}}}
+. ST_AsJPEG(rast raster, nband int, quality int)
+{{{
+ST_AsJPEG(rast, 5, 75)
+}}}
+. ST_AsJPEG(rast raster, nband int)
+{{{
+ST_AsJPEG(rast, 4)
+}}}
+''OLD NOTES''
+~~Return the raster as a JPEG encoded as a PostgreSQL bytea. By default quality is set to 75, but this option can be used to select other values. Values must be in the range 10-100. Low values result in higher compression ratios, but poorer image quality. Values above 95 are not meaningfully better quality but can but substantially larger. (copied from http://www.gdal.org/frmt_jpeg.html)~~
+~~'''Open Question:''' Is JPEG export limited to raster having 8 bit unsigned integer pixeltype (8BUI)?~~
+~~[http://www.gdal.org/frmt_jpeg.html See how GDAL do it]. It converts only 8 bits rasters. Should we do the same?~~
+~~Otherwise, how do we convert other types to 8BUI? e.g. 16BUI or 8BSI?~~
+~~Pierre: It might be more simple to ignore pixeltypes other than 8BUI but it would be very convenient to have a way to quickly export elevation data for example as a JPEG. It would be nice to have an elegant solution to this. Maybe something inspired from !MapServer.~~
+~~Proposition one (Pierre): ST_AsJPEG could simply (optionally when the pixeltype is not 8BUI) map the ST_Maximum() and ST_Minimum() value to 0-255. ST_Maximum() and ST_Minimum() are not in the spec yet but this could be on nice usage of it. They will imply caching the min and max when importing and editing. Both function should ignore the !NoDataValues. They could also be two parameters passed to ST_AsJPEG(raster, quality, min, max).~~
+~~Proposition two: There could also be just one parameter (string) defining a mapping method:~~
+~~ * Method "None": No mapping. This is possible only for 8BUI.~~
+~~ * Method "!MaxMinValue": Use the Max and the Min cached in the raster. e.g. for 16BSI (min, max) -> (-2033, 2456) -> (round((-2033 - -2033)/(2456 - -2033)*255), round((2456 - -2033)/(2456 - -2033)*255)) -> (0, 255).[[BR]]~~
+~~[[BR]]This is equivalent to ST_AsJPEG(raster, quality, ST_Minimum(rast), ST_Maximum(rast))~~
+~~ * Method "!MaxMinType": Use the Max and the Min allowed by the type. e.g. for 16BSI (min, max) -> (-2033, 2456) -> (round((-2033 - -32768)/(32767 - -32768)*255), round((2456 - -32768)/(32767 - -32768)*255)) -> (120, 137)[[BR]]~~
+~~[[BR]]This would be equivalent to ST_AsJPEG(raster, quality, ST_BandPixelTypeMin(rast), ST_BandPixelTypeMax(rast)). Both functions (ST_BandPixelTypeMin & ST_BandPixelTypeMax) are not yet planned and I could not find an SQL query that returns the equivalent range for a type. [http://groups.google.nl/group/microsoft.public.sqlserver.programming/browse_thread/thread/46512c2691da4607/6743f4aea485c6d1 One possible solution.]~~
+~~mloskot: ATM, I have no thoughts on this issue.~~
+~~'''Open Question:''' Is JPEG export limited to raster having 1 or 3 bands?~~
+~~[http://www.gdal.org/frmt_jpeg.html See how GDAL do it]. It converts only 1 or 3 band rasters. Should we do the same? In this case 1 band rasters would be exported as a greyscale JPEG having R G and B identical and 3 band rasters would be interpreted as R, G and B.~~
+~~Pierre: I think the answer should be yes. I don't see how we could have a 2 band raster fit into RGB.~~
+~~mloskot: I agree, the answer should be yes.~~
+~~'''Here is an attempt to define the different versions of the function:'''~~
+~~The most minimalistic versions of the function should assume band 1, 2 and 3 as being r, g, b and the quality equal to 75:~~
+~~ ST_AsJPEG(raster) -quality = 75~~
+~~A variant allow specifying the quality:~~
+~~ ST_AsJPEG(raster, integer)~~
+~~Another variant should enable us to specify which band correspond to the r, the g and the b:~~
+~~ ST_AsJPEG(raster, integer, integer, integer) - raster, rband, gband, bband, quality=75~~
+~~ ST_AsJPEG(raster, integer, integer, integer, integer) - raster, rband, gband, bband, quality~~
+~~Another version should be designed to be used with a future ST_Band(raster) function. In this case there is no attempt to extract r, g or b band from any passed raster:~~
+~~ ST_AsJPEG(raster, raster, raster)~~
+~~ ST_AsJPEG(raster, raster, raster, integer) -with the quality param~~
+~~Another series should allow converting 1 band raster with pixel of type 8BUI to a grayscale JPEG (Carefull study of the GDAL behavior when converting a single band to JPEG should be done before confirming these functions):~~
+~~ ST_AsJPEG(raster, "GRAYSCALE") - convert only band 1 with quality = 75~~
+~~ ST_AsJPEG(raster, "GRAYSCALE", integer) - convert only band 1 with specified quality~~
+~~ ST_AsJPEG(raster, integer, "GRAYSCALE") - allow specifying the band number to convert~~
+~~ ST_AsJPEG(raster, integer, "GRAYSCALE", integer) - allow specifying the band number to convert and the quality~~
+~~Another series should allow converting 1 band raster of ANY pixel type to a grayscale JPEG. Pixel types different than 8BUI should be mapped according to specified min, max values and a mapping mode: "!MaxMinValue" (default) or "!MaxMinType".~~
+~~ ST_AsJPEG(raster, "GRAYSCALE", min, max, text) - convert only band 1 with quality = 75~~
+~~ ST_AsJPEG(raster, "GRAYSCALE", integer, min, max, text) - convert only band 1 with specified quality~~
+~~ ST_AsJPEG(raster, integer, "GRAYSCALE", min, max, text) - allow specifying the band number to convert~~
+~~ ST_AsJPEG(raster, integer, "GRAYSCALE", integer, min, max, text) - allow specifying the band number to convert and the quality~~
+----
+'''ST_AsTIFF(raster, compression) -> TIFF as "bytea"'''[[BR]]
+Return the raster as a TIFF encoded as a PostgreSQL bytea. If raster is a multiband raster and no band were selected with ST_Band() every band are written to the resulting TIFF.
+compression=[JPEG/LZW/PACKBITS/DEFLATE/CCITTRLE/CCITTFAX3/CCITTFAX4/NONE]: Set the type of compression to use. None is the default. The CCITT compression should only be used with 1bit (NBITS=1) data. JPEG should only be used with Byte data. When using JPEG add a number specifying the quality. 75 is the default. e.g. ST_AsTIFF(raster, "JPEG60") (copied from http://www.gdal.org/frmt_gtiff.html)
+A proposed implementation of the ST_AsTIFF functions.
+The TIFF format is probably the most robust available for converting rasters to GDAL rasters. Not only does it support all PostGIS Raster pixel types, it also provides plenty of creation options and possibly no issues with the number of bands. The only limitation found is that there can only be one NODATA value for all bands.
+''If the compression parameter/option is specified to JPEG, all bands must be of pixel type 8BUI.  If the compression parameter/option is specified to one of the CCITT options, all bands must be of pixel type 1BB.  If any band violates the restriction, an exception is raised.''
+The next three functions are the most basic of the ST_AsTIFF functions.
+. ST_AsTIFF(rast raster, options text[], srs text) -> bytea
+    The most generic version of this function. All other ST_AsTIFF functions call this function.
+    This function will check that all bands of the raster to be converted has the same NODATA value. If there are more than one possible NODATA values, a WARNING will be raised and the output TIFF will use the NODATA value of the first band with a NODATA value.
+        options: the GDAL creation options found in the Creation Options section of the GDAL TIFF driver
+        srs: the user-specified OGC WKT or the proj4 text for a spatial reference to embed in the GDAL raster. TIFF is one of the formats that supports embedding the spatial reference within the image file.
+{{{
+ST_AsTIFF(rast, ARRAY['COMPRESS=DEFLATE', 'ZLEVEL=9'], '+proj=aea +lat_1=34 +lat_2=40.5 +lat_0=0 +lon_0=-120 +x_0=0 +y_0=-4000000 +ellps=GRS80 +datum=NAD83 +units=m +no_defs')
+ST_AsTIFF(rast, ARRAY['COMPRESS=DEFLATE', 'ZLEVEL=9'], 'PROJCS["NAD83 / California Albers",GEOGCS["NAD83",DATUM["North_American_Datum_1983",SPHEROID["GRS 1980",6378137,298.257222101,AUTHORITY["EPSG","7019"]],AUTHORITY["EPSG","6269"]],PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],UNIT["degree",0.01745329251994328,AUTHORITY["EPSG","9122"]],AUTHORITY["EPSG","4269"]],UNIT["metre",1,AUTHORITY["EPSG","9001"]],PROJECTION["Albers_Conic_Equal_Area"],PARAMETER["standard_parallel_1",34],PARAMETER["standard_parallel_2",40.5],PARAMETER["latitude_of_center",0],PARAMETER["longitude_of_center",-120],PARAMETER["false_easting",0],PARAMETER["false_northing",-4000000],AUTHORITY["EPSG","3310"],AXIS["X",EAST],AXIS["Y",NORTH]]')
+}}}
+. ST_AsTIFF(rast raster, options text[]) -> bytea
+This one removes the user-specified srs argument. The output TIFF's spatial reference will be set to the same as the input raster, if possible.
+{{{
+ST_AsTIFF(rast, ARRAY['COMPRESS=DEFLATE', 'ZLEVEL=9'])
+}}}
+. ST_AsTIFF(rast raster) -> bytea
+The simplest implementation of this function. Since the options argument has been removed, the output TIFF will be created with default options. Like the prior function, the spatial reference of the TIFF will be set to the same as the input raster.
+{{{
+ST_AsTIFF(rast)
+}}}
+The next three functions add a band index argument to filter the raster's bands before generating the output TIFF.
+. ST_AsTIFF(rast raster, nbands int[], options text[], srs text) -> bytea
+{{{
+ST_AsTIFF(rast, ARRAY[3,1,2], ARRAY['COMPRESS=DEFLATE', 'ZLEVEL=9'], '+proj=aea +lat_1=34 +lat_2=40.5 +lat_0=0 +lon_0=-120 +x_0=0 +y_0=-4000000 +ellps=GRS80 +datum=NAD83 +units=m +no_defs')
+}}}
+. ST_AsTIFF(rast raster, nbands int[], options text[]) -> bytea
+This one removes the user-specified srs argument. The output TIFF's spatial reference will be set to the same as the input raster, if possible.
+{{{
+ST_AsTIFF(rast, ARRAY[3,1,2], ARRAY['COMPRESS=DEFLATE', 'ZLEVEL=9'])
+}}}
+. ST_AsTIFF(rast raster, nbands int[]) -> bytea
+Since the options argument has been removed, the output TIFF will be created with default options. Like the prior function, the spatial reference of the TIFF will be set to the same as the input raster.
+{{{
+ST_AsTIFF(rast, ARRAY[3,1,2])
+}}}
+The next two functions add a compression argument. If the compression desired is JPEG or DEFLATE, the user can specify a quality as part of the compression string.
+Examples are:
+{{{
+JPEG90
+JPEG
+DEFLATE8
+DEFLATE
+}}}
+. ST_AsTIFF(rast raster, compression text, srs text) -> bytea
+This function will parse the compression string for the compression type and the compression quality. It will also inspect to make sure that the pixel types of the raster's bands are appropriate for the compression type. This is primarily for JPEG and CCITT compression types, which only support 8BUI and 1BB respectively.
+{{{
+ST_AsTIFF(rast, 'JPEG90', '+proj=aea +lat_1=34 +lat_2=40.5 +lat_0=0 +lon_0=-120 +x_0=0 +y_0=-4000000 +ellps=GRS80 +datum=NAD83 +units=m +no_defs')
+ST_AsTIFF(rast, 'JPEG', '+proj=aea +lat_1=34 +lat_2=40.5 +lat_0=0 +lon_0=-120 +x_0=0 +y_0=-4000000 +ellps=GRS80 +datum=NAD83 +units=m +no_defs')
+ST_AsTIFF(rast, 'LZMA', '+proj=aea +lat_1=34 +lat_2=40.5 +lat_0=0 +lon_0=-120 +x_0=0 +y_0=-4000000 +ellps=GRS80 +datum=NAD83 +units=m +no_defs')
+}}}
+. ST_AsTIFF(rast raster, compression text) -> bytea
+The output TIFF will be created with default options. Like the prior function, the spatial reference of the TIFF will be set to the same as the input raster.
+{{{
+ST_AsTIFF(rast, 'LZMA')
+}}}
+The next two functions include band index and compression arguments
+. ST_AsTIFF(rast raster, nbands int[], compression text, srs text) -> bytea
+{{{
+ST_AsTIFF(rast, ARRAY[2], 'JPEG90', ARRAY['BIGTIFF=IF_NEEDED'], '+proj=aea +lat_1=34 +lat_2=40.5 +lat_0=0 +lon_0=-120 +x_0=0 +y_0=-4000000 +ellps=GRS80 +datum=NAD83 +units=m +no_defs')
+ST_AsTIFF(rast, ARRAY[1,3], 'JPEG', ARRAY['BIGTIFF=IF_NEEDED'], '+proj=aea +lat_1=34 +lat_2=40.5 +lat_0=0 +lon_0=-120 +x_0=0 +y_0=-4000000 +ellps=GRS80 +datum=NAD83 +units=m +no_defs')
+ST_AsTIFF(rast, ARRAY[3,1,2], 'LZMA', ARRAY['BIGTIFF=IF_NEEDED'], '+proj=aea +lat_1=34 +lat_2=40.5 +lat_0=0 +lon_0=-120 +x_0=0 +y_0=-4000000 +ellps=GRS80 +datum=NAD83 +units=m +no_defs')
+}}}
+. ST_AsTIFF(rast raster, nbands int[], compression text) -> bytea
+{{{
+ST_AsTIFF(rast, ARRAY[3,2], 'DEFLATE9')
+}}}
+The output TIFF will be created with default options. The spatial reference of the TIFF will be set to the same as the input raster.
+----
+~~'''Open Question:''' What if we want to export only the first two band of a three band layer?~~
+~~Maybe we need a ST_RasterFromBands(band1, band2, etc...) to reconstitute a multiband raster from multiple sources (having the same width, height, pixelsize, etc...)~~
+~~mloskot: or ST_RasterFromBands(bands) where bands is ARRAY[int]. For instance, ST_RasterFromBands(ARRAY[1,3]) will burn new raster from 1 and 3 bands of input raster.~~
+----
+'''ST_AsPNG(raster, band) -> PNG as "bytea"'''
+Like the JPEG raster format, the PNG format has limitations:
+. PNG only allows 1 (greyscale) or 3 (RGB) bands of data
+. PNG only supports 8BUI and 16BUI pixeltypes. Any other pixeltype will be written as 8BUI, though the results are probably useless
+. PNG cannot embed spatial reference information within the file but can have an associated world file
+Like JPEG, the limitations can be resolved:
+. Use ST_Band to specify which band(s) should be passed to the ST_AsPNG function. If a raster whose number of specified bands does not equal 1 or 3 is provided, a warning is raised and the first or the first three bands are used.
+. Throw an exception if any of the specified bands is not 8BUI or 16BUI. The user should use ST_Reclass to convert any non-8BUI or 16BUI bands to 8BUI or 16BUI.
+. Nothing can be done within this function. ST_Georeference() can be used to the contents of the associated world file
+A proposed set of variations of the ST_AsPNG function:
+. ST_AsPNG(rast raster, options text[])
+    rast: the raster with one or three bands in 8BUI or 16BUI pixel type to generate a PNG image from
+    options: array of creation options to pass to the GDAL PNG driver
+{{{
+ST_AsPNG(rast, ARRAY['ZLEVEL=9'])
+}}}
+. ST_AsPNG(rast raster)
+    Like !#1 above but use the driver's default creation options
+. ST_AsPNG(rast raster, nbands int[], options text[])
+    nbands: an integer array specifying the band indices of the raster to include in the PNG file
+{{{
+ST_AsPNG(rast, ARRAY[3,1,2], ARRAY['ZLEVEL=9'])
+}}}
+. ST_AsPNG(rast raster, nbands int[])
+    Like !#3, but use the default creation options
+{{{
+ST_AsPNG(rast, ARRAY[3])
+}}}
+. ST_AsPNG(rast raster, nbands int[], compression int)
+    compression: number between 1 and 9 indicating the amount of time to spend on compression. 1 is fastest with least compression. 9 is slowest with best compression
+{{{
+ST_AsPNG(rast, ARRAY[2,1,3], 3)
+}}}
+. ST_AsPNG(rast raster, nband int, options text[])
+    nband: index of the band to include
+{{{
+ST_AsPNG(rast, 2, ARRAY['ZLEVEL=5'])
+}}}
+. ST_AsPNG(rast raster, nband int, compression int)
+{{{
+ST_AsPNG(rast, 1, 8)
+}}}
+. ST_AsPNG(rast raster, nband int)
+{{{
+ST_AsPNG(rast, 1)
+}}}
+----
+'''ST_AsGDALRaster(raster, band int, type text, options text) -> bytea'''
+Use GDAL to convert the raster into one of the format suported by GDAL.
+This is a generic interface to outputting a supported and installed GDAL raster:
+. ST_AsGDALRaster(rast raster, format text, options text[], srs text) -> bytea
+  This is the most generic and GDAL-specific method to convert a raster to a GDAL raster.  All other version of ST_AsGDALRaster and other format specific functions (ST_AsJPEG, ST_AsTIFF and ST_AsPNG) are all wrappers around this function.  Reference information for the format and options arguments of a particular format are specified at: http://gdal.org/formats_list.html.  The arguments specified are:
+  format: the GDAL format code.  e.g. GTiff, JPEG, PNG
+  options: the GDAL creation options found in the '''Creation Options''' section of a specified format.  e.g. COMPRESS=JPEG, JPEG_QUALITY=90
+  srs: the user-specified OGC WKT or the proj4 text for a spatial reference to embed in the GDAL raster.  Not all formats support embedding this information.  e.g. the non-empty value for the srtext or proj4text column from the spatial_ref_sys table.
+{{{
+ST_AsGDALRaster(rast, 'GTiff', ARRAY['COMPRESS=JPEG', 'JPEG_QUALITY=90'], '+proj=aea +lat_1=34 +lat_2=40.5 +lat_0=0 +lon_0=-120 +x_0=0 +y_0=-4000000 +ellps=GRS80 +datum=NAD83 +units=m +no_defs')
+ST_AsGDALRaster(rast, 'GTiff', ARRAY['COMPRESS=JPEG', 'JPEG_QUALITY=90'], 'PROJCS["NAD83 / California Albers",GEOGCS["NAD83",DATUM["North_American_Datum_1983",SPHEROID["GRS 1980",6378137,298.257222101,AUTHORITY["EPSG","7019"]],AUTHORITY["EPSG","6269"]],PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],UNIT["degree",0.01745329251994328,AUTHORITY["EPSG","9122"]],AUTHORITY["EPSG","4269"]],UNIT["metre",1,AUTHORITY["EPSG","9001"]],PROJECTION["Albers_Conic_Equal_Area"],PARAMETER["standard_parallel_1",34],PARAMETER["standard_parallel_2",40.5],PARAMETER["latitude_of_center",0],PARAMETER["longitude_of_center",-120],PARAMETER["false_easting",0],PARAMETER["false_northing",-4000000],AUTHORITY["EPSG","3310"],AXIS["X",EAST],AXIS["Y",NORTH]]')
+}}}
+. ST_AsGDALRaster(rast raster, format text, options text[]) -> bytea
+  This one removes the user-specified srs argument.  The output GDAL raster's spatial reference will be set to the same as the input raster, if possible.
+{{{
+ST_AsGDALRaster(rast, 'JPEG', ARRAY['QUALITY=50'])
+ST_AsGDALRaster(rast, 'PNG', ARRAY['ZLEVEL=7'])
+}}}
+. ST_AsGDALRaster(rast raster, format text) -> bytea
+  The simplest implementation of this function.  Since the options argument has been removed, the output GDAL raster will be created with default options.  Like the prior function, the spatial reference of the GDAL raster will be set to the same as the input raster.
+{{{
+ST_AsGDALRaster(rast, 'JPEG')
+}}}
+----
+'''ST_GDALDrivers() -> set of record'''
+As each GDAL installation may be different and ST_AsGDALRaster can be used to support formats other than GTiff, JPEG and PNG, a method is needed to expose to the end user the possible GDAL formats capable of being exported.  This function will output the following columns.
+  idx: the internal GDAL index number
+  short_name: the GDAL format code.  This is the value to pass to the format paramenter of ST_AsGDALRaster
+  long_name: the full name of the GDAL format
+  create_options: the creation options available for the format as an XML string.
+The formats outputted from ST_getGDALDrivers have been filtered to only those that the GDAL capabilities !CreateCopy and Virtual IO support.
+'''Open Question:''' Should the GDAL raster process be capable of supporting the GDAL capability Create?  As the GDAL raster process writes nothing to a file in the filesystem (via Virtual IO), should there be support for writing the output GDAL raster temporarily to the filesystem?  If so, how is it done in other PostgreSQL extensions in a secure manner?
+----
+'''ST_srtext(rast raster) -> text'''
+A helper function to get the value of column srtext or proj4text for a raster with an SRID.  By default, the srtext is returned.  If srtext is not available but proj4text is, the proj4text is returned.
+This function may be removed based upon the capabilities of SPI.  It may not be possible to remove this function as the srs function argument of ST_AsGDALRaster can be NULL, thereby instructing the function to not embed any spatial reference information into the output GDAL raster.
+----
+'''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.
+. 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]''
+{{{
+-100:0-10
+-100:0-10, 101-1000:11-100
+-100:0-10, 101-1000:11-100, 1001-10000:101-1000
+}}}
+      In the last example above, the default evaluation of the ranges is
+{{{
+<= x < 100 reclassified to 0 <= y <= 10
+<= x < 1000 reclassified to 11 <= y <= 100
+<= x < 10000 reclassified to 101 <= y <= 1000
+}}}
+      To change the evaluation of rangefrom, use square brackets and parentheses.
+{{{
+. [a-b] = a <= x <= b
+. (a-b] = a < x <= b
+. [a-b) = a <= x < b
+. (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
+}}}
+      Two special cases are also available for use when x may be outside the range of a-b.  This situation is possible if your range is based upon an approximation, such as from ST_ApproxMinMax.
+{{{
+]a-b or )a-b = x < a, rule matches
+a-b[ or a-b( = x >= b, rule matches
+}}}
+    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]),
+  ROW(1, LEAST(covmin, 0)::text || '-0:0,0-' || GREATEST(covmax, 0)::text || ':0-255', '8BUI'),
+  ROW(2, LEAST(covmin, 0)::text || '-0:200,0-' || GREATEST(covmax, 0)::text' || ':0-255','8BUI'),
+  ROW(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
+}}}
+. 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)
+}}}
+. 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')
+}}}
+. 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')
+}}}
+. 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)
+}}}
 ----
 …
 '''ST_RasterFromText(string, [<srid>])'''[[BR]]
 '''ST_AsText(raster)'''
+== '''Objective FV.01 - Being able to return a JPEG, a TIFF, a PNG or any image format supported by GDAL - ''DONE''''' ==
+'''ST_bytea(raster, integer) -> raster''' -- the integer parameters is the band number of the raster.[[BR]]
+What is does?
+----
+~~'''Open Question:''' When exporting a multiband raster to JPEG, TIFF, PNG, SVG or KML, how should we specify the band number in the exporting function.~~
+~~There is two options to select the band to convert from a multiband raster in all the ST_AsFormat functions. [[BR]]~~
+[[BR]]
+~~ 1. Precede each call with ST_Band() to return a selected band.[[BR]]~~
+~~  Pros: This is a general function that can be called before any function that would otherwise require a band parameter.[[BR]]~~
+~~  Cons: This implies creating a temporary raster. This might be more elegant and general but is this too much overhead comparing with having a band parameter?~~
+~~ 2. Add a band parameter to each ST_AsFormat function.[[BR]]~~
+~~  Pros: Hypothetically less overhead.[[BR]]~~
+~~  Cons: Every functions implying access to a band should then have this parameter when in most case it would be equal to 1. In many cases it makes no sence to have to specify a band parameter since it is the whole raster that we want to export, including all the bands.~~
+~~Pierre: More I think about it more I think that the first option is the best one...~~
+~~mloskot: Perhaps there is a compromise in form of two sets of functions: 1) ST_As* which always burn the whole raster (all bands) 2) ST_BandAs* which takes number of band as a parameter and return only this requested band.~~
+----
+'''ST_Band(raster, integer) -> raster''' -- the integer parameters are the band number of the rasters.[[BR]]
+Return a single band from a multiband raster. If "band" is greater than the value returned by ST_GetNumBands(), the function returns the last band. This function should be used to select a band before converting it to JPEG, TIFF, PNG, SVG or KML with the corresponding function. e.g. '''ST_AsTIFF(ST_Band(raster, band))
+A complete implementation of ST_Band should include the following:
+. ST_Band(rast raster, nbands int[]) -> raster
+    nbands is an array of 1-based band indices of the bands to copy into the output raster
+    For a raster rast with 3 bands:
+{{{
+ST_Band(rast, ARRAY[1,3,2])
+ST_Band(rast, ARRAY[3,2,1])
+}}}
+    You can rearrange the bands as above. You can also duplicate the bands:
+{{{
+ST_Band(rast, ARRAY[1,2,3,2,1])
+}}}
+. ST_Band(rast raster, nband int) -> raster
+    nband is a single integer of the 1-based band index of the band to copy into the output raster
+{{{
+ST_Band(rast, 1)
+ST_Band(rast, 3)
+}}}
+. ST_Band(rast raster, nbands text) -> raster
+    nbands is a comma separated string of 1-based band indices indicating the bands to copy into the output raster
+{{{
+ST_Band(rast, '1,2')
+ST_Band(rast, '1,2,3, 1, 1 , 2')
+}}}
+. ST_Band(rast raster, nbands text, delimiter char) -> raster
+    nbands is a user-specified delimiter separated string of 1-based band indices indicating the bands to copy into the output raster
+{{{
+ST_Band(rast, '1,2', ',')
+ST_Band(rast, '1,2,3, 1, 1 , 2', ',')
+}}}
+. ST_Band(rast raster) -> raster
+    the band to extract is automatically assumed to be one.
+{{{
+ST_Band(rast)
+}}}
+If an index is outside the valid range of band indices for a raster (less than 1 or greater than the value returned by ST_NumBands), the function will fail and return.
+~~''' Open Question: ''' Should the function fail if an index is invalid?  How should this work when providing more than one indices to the function?~~
+----
+'''ST_AsJPEG(raster, quality) -> JPEG as "bytea"'''[[BR]]
+The JPEG format has several limitations:
+. JPEG only allows 1 (greyscale) or 3 (RGB) bands of data
+. JPEG only supports 8BUI pixeltype
+. JPEG cannot embed spatial reference information within the file but can have an associated world file
+To address the limitations:
+. Use ST_Band to specify which band(s) should be passed to the ST_AsJPEG function. Variations of ST_AsJPEG are made available that allows specifying a band index. If a raster whose number of specified bands does not equal 1 or 3 is provided, a warning is raised and the first or the first three bands are used.
+. Throw an exception if any of the specified bands is not 8BUI. The user should use ST_Reclass to convert any non-8BUI bands to 8BUI.
+. Nothing can be done.
+A proposed set of variations of the ST_AsJPEG function:
+. ST_AsJPEG(rast raster, options text[])
+    rast: the raster with one or three bands in 8BUI pixel type to generate a JPEG image from
+    options: array of creation options to pass to the GDAL JPEG driver
+{{{
+ST_AsJPEG(rast, ARRAY['QUALITY=90', 'PROGRESSIVE=ON'])
+}}}
+. ST_AsJPEG(rast raster)
+    Like !#1 above but use the driver's default creation options
+. ST_AsJPEG(rast raster, nbands int[], options text[])
+    nbands: an integer array specifying the band indices of the raster to include in the JPEG file
+{{{
+ST_AsJPEG(rast, ARRAY[1,3,6], ARRAY['QUALITY=50'])
+}}}
+. ST_AsJPEG(rast raster, nbands int[])
+    Like !#3, but use the default creation options
+{{{
+ST_AsJPEG(rast, ARRAY[1,3,6])
+}}}
+. ST_AsJPEG(rast raster, nbands int[], quality int)
+    quality: number between 10 and 100 indicating image quality
+{{{
+ST_AsJPEG(rast, ARRAY[1,2,3], 90)
+}}}
+. ST_AsJPEG(rast raster, nband int, options text[])
+    nband: index of the band to include
+{{{
+ST_AsJPEG(rast, 2, ARRAY['QUALITY=25'])
+}}}
+. ST_AsJPEG(rast raster, nband int, quality int)
+{{{
+ST_AsJPEG(rast, 5, 75)
+}}}
+. ST_AsJPEG(rast raster, nband int)
+{{{
+ST_AsJPEG(rast, 4)
+}}}
+''OLD NOTES''
+~~Return the raster as a JPEG encoded as a PostgreSQL bytea. By default quality is set to 75, but this option can be used to select other values. Values must be in the range 10-100. Low values result in higher compression ratios, but poorer image quality. Values above 95 are not meaningfully better quality but can but substantially larger. (copied from http://www.gdal.org/frmt_jpeg.html)~~
+~~'''Open Question:''' Is JPEG export limited to raster having 8 bit unsigned integer pixeltype (8BUI)?~~
+~~[http://www.gdal.org/frmt_jpeg.html See how GDAL do it]. It converts only 8 bits rasters. Should we do the same?~~
+~~Otherwise, how do we convert other types to 8BUI? e.g. 16BUI or 8BSI?~~
+~~Pierre: It might be more simple to ignore pixeltypes other than 8BUI but it would be very convenient to have a way to quickly export elevation data for example as a JPEG. It would be nice to have an elegant solution to this. Maybe something inspired from !MapServer.~~
+~~Proposition one (Pierre): ST_AsJPEG could simply (optionally when the pixeltype is not 8BUI) map the ST_Maximum() and ST_Minimum() value to 0-255. ST_Maximum() and ST_Minimum() are not in the spec yet but this could be on nice usage of it. They will imply caching the min and max when importing and editing. Both function should ignore the !NoDataValues. They could also be two parameters passed to ST_AsJPEG(raster, quality, min, max).~~
+~~Proposition two: There could also be just one parameter (string) defining a mapping method:~~
+~~ * Method "None": No mapping. This is possible only for 8BUI.~~
+~~ * Method "!MaxMinValue": Use the Max and the Min cached in the raster. e.g. for 16BSI (min, max) -> (-2033, 2456) -> (round((-2033 - -2033)/(2456 - -2033)*255), round((2456 - -2033)/(2456 - -2033)*255)) -> (0, 255).[[BR]]~~
+~~[[BR]]This is equivalent to ST_AsJPEG(raster, quality, ST_Minimum(rast), ST_Maximum(rast))~~
+~~ * Method "!MaxMinType": Use the Max and the Min allowed by the type. e.g. for 16BSI (min, max) -> (-2033, 2456) -> (round((-2033 - -32768)/(32767 - -32768)*255), round((2456 - -32768)/(32767 - -32768)*255)) -> (120, 137)[[BR]]~~
+~~[[BR]]This would be equivalent to ST_AsJPEG(raster, quality, ST_BandPixelTypeMin(rast), ST_BandPixelTypeMax(rast)). Both functions (ST_BandPixelTypeMin & ST_BandPixelTypeMax) are not yet planned and I could not find an SQL query that returns the equivalent range for a type. [http://groups.google.nl/group/microsoft.public.sqlserver.programming/browse_thread/thread/46512c2691da4607/6743f4aea485c6d1 One possible solution.]~~
+~~mloskot: ATM, I have no thoughts on this issue.~~
+~~'''Open Question:''' Is JPEG export limited to raster having 1 or 3 bands?~~
+~~[http://www.gdal.org/frmt_jpeg.html See how GDAL do it]. It converts only 1 or 3 band rasters. Should we do the same? In this case 1 band rasters would be exported as a greyscale JPEG having R G and B identical and 3 band rasters would be interpreted as R, G and B.~~
+~~Pierre: I think the answer should be yes. I don't see how we could have a 2 band raster fit into RGB.~~
+~~mloskot: I agree, the answer should be yes.~~
+~~'''Here is an attempt to define the different versions of the function:'''~~
+~~The most minimalistic versions of the function should assume band 1, 2 and 3 as being r, g, b and the quality equal to 75:~~
+~~ ST_AsJPEG(raster) -quality = 75~~
+~~A variant allow specifying the quality:~~
+~~ ST_AsJPEG(raster, integer)~~
+~~Another variant should enable us to specify which band correspond to the r, the g and the b:~~
+~~ ST_AsJPEG(raster, integer, integer, integer) - raster, rband, gband, bband, quality=75~~
+~~ ST_AsJPEG(raster, integer, integer, integer, integer) - raster, rband, gband, bband, quality~~
+~~Another version should be designed to be used with a future ST_Band(raster) function. In this case there is no attempt to extract r, g or b band from any passed raster:~~
+~~ ST_AsJPEG(raster, raster, raster)~~
+~~ ST_AsJPEG(raster, raster, raster, integer) -with the quality param~~
+~~Another series should allow converting 1 band raster with pixel of type 8BUI to a grayscale JPEG (Carefull study of the GDAL behavior when converting a single band to JPEG should be done before confirming these functions):~~
+~~ ST_AsJPEG(raster, "GRAYSCALE") - convert only band 1 with quality = 75~~
+~~ ST_AsJPEG(raster, "GRAYSCALE", integer) - convert only band 1 with specified quality~~
+~~ ST_AsJPEG(raster, integer, "GRAYSCALE") - allow specifying the band number to convert~~
+~~ ST_AsJPEG(raster, integer, "GRAYSCALE", integer) - allow specifying the band number to convert and the quality~~
+~~Another series should allow converting 1 band raster of ANY pixel type to a grayscale JPEG. Pixel types different than 8BUI should be mapped according to specified min, max values and a mapping mode: "!MaxMinValue" (default) or "!MaxMinType".~~
+~~ ST_AsJPEG(raster, "GRAYSCALE", min, max, text) - convert only band 1 with quality = 75~~
+~~ ST_AsJPEG(raster, "GRAYSCALE", integer, min, max, text) - convert only band 1 with specified quality~~
+~~ ST_AsJPEG(raster, integer, "GRAYSCALE", min, max, text) - allow specifying the band number to convert~~
+~~ ST_AsJPEG(raster, integer, "GRAYSCALE", integer, min, max, text) - allow specifying the band number to convert and the quality~~
+----
+'''ST_AsTIFF(raster, compression) -> TIFF as "bytea"'''[[BR]]
+Return the raster as a TIFF encoded as a PostgreSQL bytea. If raster is a multiband raster and no band were selected with ST_Band() every band are written to the resulting TIFF.
+compression=[JPEG/LZW/PACKBITS/DEFLATE/CCITTRLE/CCITTFAX3/CCITTFAX4/NONE]: Set the type of compression to use. None is the default. The CCITT compression should only be used with 1bit (NBITS=1) data. JPEG should only be used with Byte data. When using JPEG add a number specifying the quality. 75 is the default. e.g. ST_AsTIFF(raster, "JPEG60") (copied from http://www.gdal.org/frmt_gtiff.html)
+A proposed implementation of the ST_AsTIFF functions.
+The TIFF format is probably the most robust available for converting rasters to GDAL rasters. Not only does it support all PostGIS Raster pixel types, it also provides plenty of creation options and possibly no issues with the number of bands. The only limitation found is that there can only be one NODATA value for all bands.
+''If the compression parameter/option is specified to JPEG, all bands must be of pixel type 8BUI.  If the compression parameter/option is specified to one of the CCITT options, all bands must be of pixel type 1BB.  If any band violates the restriction, an exception is raised.''
+The next three functions are the most basic of the ST_AsTIFF functions.
+. ST_AsTIFF(rast raster, options text[], srs text) -> bytea
+    The most generic version of this function. All other ST_AsTIFF functions call this function.
+    This function will check that all bands of the raster to be converted has the same NODATA value. If there are more than one possible NODATA values, a WARNING will be raised and the output TIFF will use the NODATA value of the first band with a NODATA value.
+        options: the GDAL creation options found in the Creation Options section of the GDAL TIFF driver
+        srs: the user-specified OGC WKT or the proj4 text for a spatial reference to embed in the GDAL raster. TIFF is one of the formats that supports embedding the spatial reference within the image file.
+{{{
+ST_AsTIFF(rast, ARRAY['COMPRESS=DEFLATE', 'ZLEVEL=9'], '+proj=aea +lat_1=34 +lat_2=40.5 +lat_0=0 +lon_0=-120 +x_0=0 +y_0=-4000000 +ellps=GRS80 +datum=NAD83 +units=m +no_defs')
+ST_AsTIFF(rast, ARRAY['COMPRESS=DEFLATE', 'ZLEVEL=9'], 'PROJCS["NAD83 / California Albers",GEOGCS["NAD83",DATUM["North_American_Datum_1983",SPHEROID["GRS 1980",6378137,298.257222101,AUTHORITY["EPSG","7019"]],AUTHORITY["EPSG","6269"]],PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],UNIT["degree",0.01745329251994328,AUTHORITY["EPSG","9122"]],AUTHORITY["EPSG","4269"]],UNIT["metre",1,AUTHORITY["EPSG","9001"]],PROJECTION["Albers_Conic_Equal_Area"],PARAMETER["standard_parallel_1",34],PARAMETER["standard_parallel_2",40.5],PARAMETER["latitude_of_center",0],PARAMETER["longitude_of_center",-120],PARAMETER["false_easting",0],PARAMETER["false_northing",-4000000],AUTHORITY["EPSG","3310"],AXIS["X",EAST],AXIS["Y",NORTH]]')
+}}}
+. ST_AsTIFF(rast raster, options text[]) -> bytea
+This one removes the user-specified srs argument. The output TIFF's spatial reference will be set to the same as the input raster, if possible.
+{{{
+ST_AsTIFF(rast, ARRAY['COMPRESS=DEFLATE', 'ZLEVEL=9'])
+}}}
+. ST_AsTIFF(rast raster) -> bytea
+The simplest implementation of this function. Since the options argument has been removed, the output TIFF will be created with default options. Like the prior function, the spatial reference of the TIFF will be set to the same as the input raster.
+{{{
+ST_AsTIFF(rast)
+}}}
+The next three functions add a band index argument to filter the raster's bands before generating the output TIFF.
+. ST_AsTIFF(rast raster, nbands int[], options text[], srs text) -> bytea
+{{{
+ST_AsTIFF(rast, ARRAY[3,1,2], ARRAY['COMPRESS=DEFLATE', 'ZLEVEL=9'], '+proj=aea +lat_1=34 +lat_2=40.5 +lat_0=0 +lon_0=-120 +x_0=0 +y_0=-4000000 +ellps=GRS80 +datum=NAD83 +units=m +no_defs')
+}}}
+. ST_AsTIFF(rast raster, nbands int[], options text[]) -> bytea
+This one removes the user-specified srs argument. The output TIFF's spatial reference will be set to the same as the input raster, if possible.
+{{{
+ST_AsTIFF(rast, ARRAY[3,1,2], ARRAY['COMPRESS=DEFLATE', 'ZLEVEL=9'])
+}}}
+. ST_AsTIFF(rast raster, nbands int[]) -> bytea
+Since the options argument has been removed, the output TIFF will be created with default options. Like the prior function, the spatial reference of the TIFF will be set to the same as the input raster.
+{{{
+ST_AsTIFF(rast, ARRAY[3,1,2])
+}}}
+The next two functions add a compression argument. If the compression desired is JPEG or DEFLATE, the user can specify a quality as part of the compression string.
+Examples are:
+{{{
+JPEG90
+JPEG
+DEFLATE8
+DEFLATE
+}}}
+. ST_AsTIFF(rast raster, compression text, srs text) -> bytea
+This function will parse the compression string for the compression type and the compression quality. It will also inspect to make sure that the pixel types of the raster's bands are appropriate for the compression type. This is primarily for JPEG and CCITT compression types, which only support 8BUI and 1BB respectively.
+{{{
+ST_AsTIFF(rast, 'JPEG90', '+proj=aea +lat_1=34 +lat_2=40.5 +lat_0=0 +lon_0=-120 +x_0=0 +y_0=-4000000 +ellps=GRS80 +datum=NAD83 +units=m +no_defs')
+ST_AsTIFF(rast, 'JPEG', '+proj=aea +lat_1=34 +lat_2=40.5 +lat_0=0 +lon_0=-120 +x_0=0 +y_0=-4000000 +ellps=GRS80 +datum=NAD83 +units=m +no_defs')
+ST_AsTIFF(rast, 'LZMA', '+proj=aea +lat_1=34 +lat_2=40.5 +lat_0=0 +lon_0=-120 +x_0=0 +y_0=-4000000 +ellps=GRS80 +datum=NAD83 +units=m +no_defs')
+}}}
+. ST_AsTIFF(rast raster, compression text) -> bytea
+The output TIFF will be created with default options. Like the prior function, the spatial reference of the TIFF will be set to the same as the input raster.
+{{{
+ST_AsTIFF(rast, 'LZMA')
+}}}
+The next two functions include band index and compression arguments
+. ST_AsTIFF(rast raster, nbands int[], compression text, srs text) -> bytea
+{{{
+ST_AsTIFF(rast, ARRAY[2], 'JPEG90', ARRAY['BIGTIFF=IF_NEEDED'], '+proj=aea +lat_1=34 +lat_2=40.5 +lat_0=0 +lon_0=-120 +x_0=0 +y_0=-4000000 +ellps=GRS80 +datum=NAD83 +units=m +no_defs')
+ST_AsTIFF(rast, ARRAY[1,3], 'JPEG', ARRAY['BIGTIFF=IF_NEEDED'], '+proj=aea +lat_1=34 +lat_2=40.5 +lat_0=0 +lon_0=-120 +x_0=0 +y_0=-4000000 +ellps=GRS80 +datum=NAD83 +units=m +no_defs')
+ST_AsTIFF(rast, ARRAY[3,1,2], 'LZMA', ARRAY['BIGTIFF=IF_NEEDED'], '+proj=aea +lat_1=34 +lat_2=40.5 +lat_0=0 +lon_0=-120 +x_0=0 +y_0=-4000000 +ellps=GRS80 +datum=NAD83 +units=m +no_defs')
+}}}
+. ST_AsTIFF(rast raster, nbands int[], compression text) -> bytea
+{{{
+ST_AsTIFF(rast, ARRAY[3,2], 'DEFLATE9')
+}}}
+The output TIFF will be created with default options. The spatial reference of the TIFF will be set to the same as the input raster.
+----
+~~'''Open Question:''' What if we want to export only the first two band of a three band layer?~~
+~~Maybe we need a ST_RasterFromBands(band1, band2, etc...) to reconstitute a multiband raster from multiple sources (having the same width, height, pixelsize, etc...)~~
+~~mloskot: or ST_RasterFromBands(bands) where bands is ARRAY[int]. For instance, ST_RasterFromBands(ARRAY[1,3]) will burn new raster from 1 and 3 bands of input raster.~~
+----
+'''ST_AsPNG(raster, band) -> PNG as "bytea"'''
+Like the JPEG raster format, the PNG format has limitations:
+. PNG only allows 1 (greyscale) or 3 (RGB) bands of data
+. PNG only supports 8BUI and 16BUI pixeltypes. Any other pixeltype will be written as 8BUI, though the results are probably useless
+. PNG cannot embed spatial reference information within the file but can have an associated world file
+Like JPEG, the limitations can be resolved:
+. Use ST_Band to specify which band(s) should be passed to the ST_AsPNG function. If a raster whose number of specified bands does not equal 1 or 3 is provided, a warning is raised and the first or the first three bands are used.
+. Throw an exception if any of the specified bands is not 8BUI or 16BUI. The user should use ST_Reclass to convert any non-8BUI or 16BUI bands to 8BUI or 16BUI.
+. Nothing can be done within this function. ST_Georeference() can be used to the contents of the associated world file
+A proposed set of variations of the ST_AsPNG function:
+. ST_AsPNG(rast raster, options text[])
+    rast: the raster with one or three bands in 8BUI or 16BUI pixel type to generate a PNG image from
+    options: array of creation options to pass to the GDAL PNG driver
+{{{
+ST_AsPNG(rast, ARRAY['ZLEVEL=9'])
+}}}
+. ST_AsPNG(rast raster)
+    Like !#1 above but use the driver's default creation options
+. ST_AsPNG(rast raster, nbands int[], options text[])
+    nbands: an integer array specifying the band indices of the raster to include in the PNG file
+{{{
+ST_AsPNG(rast, ARRAY[3,1,2], ARRAY['ZLEVEL=9'])
+}}}
+. ST_AsPNG(rast raster, nbands int[])
+    Like !#3, but use the default creation options
+{{{
+ST_AsPNG(rast, ARRAY[3])
+}}}
+. ST_AsPNG(rast raster, nbands int[], compression int)
+    compression: number between 1 and 9 indicating the amount of time to spend on compression. 1 is fastest with least compression. 9 is slowest with best compression
+{{{
+ST_AsPNG(rast, ARRAY[2,1,3], 3)
+}}}
+. ST_AsPNG(rast raster, nband int, options text[])
+    nband: index of the band to include
+{{{
+ST_AsPNG(rast, 2, ARRAY['ZLEVEL=5'])
+}}}
+. ST_AsPNG(rast raster, nband int, compression int)
+{{{
+ST_AsPNG(rast, 1, 8)
+}}}
+. ST_AsPNG(rast raster, nband int)
+{{{
+ST_AsPNG(rast, 1)
+}}}
+----
+'''ST_AsGDALRaster(raster, band int, type text, options text) -> bytea'''
+Use GDAL to convert the raster into one of the format suported by GDAL.
+This is a generic interface to outputting a supported and installed GDAL raster:
+. ST_AsGDALRaster(rast raster, format text, options text[], srs text) -> bytea
+  This is the most generic and GDAL-specific method to convert a raster to a GDAL raster.  All other version of ST_AsGDALRaster and other format specific functions (ST_AsJPEG, ST_AsTIFF and ST_AsPNG) are all wrappers around this function.  Reference information for the format and options arguments of a particular format are specified at: http://gdal.org/formats_list.html.  The arguments specified are:
+  format: the GDAL format code.  e.g. GTiff, JPEG, PNG
+  options: the GDAL creation options found in the '''Creation Options''' section of a specified format.  e.g. COMPRESS=JPEG, JPEG_QUALITY=90
+  srs: the user-specified OGC WKT or the proj4 text for a spatial reference to embed in the GDAL raster.  Not all formats support embedding this information.  e.g. the non-empty value for the srtext or proj4text column from the spatial_ref_sys table.
+{{{
+ST_AsGDALRaster(rast, 'GTiff', ARRAY['COMPRESS=JPEG', 'JPEG_QUALITY=90'], '+proj=aea +lat_1=34 +lat_2=40.5 +lat_0=0 +lon_0=-120 +x_0=0 +y_0=-4000000 +ellps=GRS80 +datum=NAD83 +units=m +no_defs')
+ST_AsGDALRaster(rast, 'GTiff', ARRAY['COMPRESS=JPEG', 'JPEG_QUALITY=90'], 'PROJCS["NAD83 / California Albers",GEOGCS["NAD83",DATUM["North_American_Datum_1983",SPHEROID["GRS 1980",6378137,298.257222101,AUTHORITY["EPSG","7019"]],AUTHORITY["EPSG","6269"]],PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],UNIT["degree",0.01745329251994328,AUTHORITY["EPSG","9122"]],AUTHORITY["EPSG","4269"]],UNIT["metre",1,AUTHORITY["EPSG","9001"]],PROJECTION["Albers_Conic_Equal_Area"],PARAMETER["standard_parallel_1",34],PARAMETER["standard_parallel_2",40.5],PARAMETER["latitude_of_center",0],PARAMETER["longitude_of_center",-120],PARAMETER["false_easting",0],PARAMETER["false_northing",-4000000],AUTHORITY["EPSG","3310"],AXIS["X",EAST],AXIS["Y",NORTH]]')
+}}}
+. ST_AsGDALRaster(rast raster, format text, options text[]) -> bytea
+  This one removes the user-specified srs argument.  The output GDAL raster's spatial reference will be set to the same as the input raster, if possible.
+{{{
+ST_AsGDALRaster(rast, 'JPEG', ARRAY['QUALITY=50'])
+ST_AsGDALRaster(rast, 'PNG', ARRAY['ZLEVEL=7'])
+}}}
+. ST_AsGDALRaster(rast raster, format text) -> bytea
+  The simplest implementation of this function.  Since the options argument has been removed, the output GDAL raster will be created with default options.  Like the prior function, the spatial reference of the GDAL raster will be set to the same as the input raster.
+{{{
+ST_AsGDALRaster(rast, 'JPEG')
+}}}
+----
+'''ST_GDALDrivers() -> set of record'''
+As each GDAL installation may be different and ST_AsGDALRaster can be used to support formats other than GTiff, JPEG and PNG, a method is needed to expose to the end user the possible GDAL formats capable of being exported.  This function will output the following columns.
+  idx: the internal GDAL index number
+  short_name: the GDAL format code.  This is the value to pass to the format paramenter of ST_AsGDALRaster
+  long_name: the full name of the GDAL format
+  create_options: the creation options available for the format as an XML string.
+The formats outputted from ST_getGDALDrivers have been filtered to only those that the GDAL capabilities !CreateCopy and Virtual IO support.
+'''Open Question:''' Should the GDAL raster process be capable of supporting the GDAL capability Create?  As the GDAL raster process writes nothing to a file in the filesystem (via Virtual IO), should there be support for writing the output GDAL raster temporarily to the filesystem?  If so, how is it done in other PostgreSQL extensions in a secure manner?
+----
+'''ST_srtext(rast raster) -> text'''
+A helper function to get the value of column srtext or proj4text for a raster with an SRID.  By default, the srtext is returned.  If srtext is not available but proj4text is, the proj4text is returned.
+This function may be removed based upon the capabilities of SPI.  It may not be possible to remove this function as the srs function argument of ST_AsGDALRaster can be NULL, thereby instructing the function to not embed any spatial reference information into the output GDAL raster.
+----
+'''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.
+. 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]''
+{{{
+-100:0-10
+-100:0-10, 101-1000:11-100
+-100:0-10, 101-1000:11-100, 1001-10000:101-1000
+}}}
+      In the last example above, the default evaluation of the ranges is
+{{{
+<= x < 100 reclassified to 0 <= y <= 10
+<= x < 1000 reclassified to 11 <= y <= 100
+<= x < 10000 reclassified to 101 <= y <= 1000
+}}}
+      To change the evaluation of rangefrom, use square brackets and parentheses.
+{{{
+. [a-b] = a <= x <= b
+. (a-b] = a < x <= b
+. [a-b) = a <= x < b
+. (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
+}}}
+      Two special cases are also available for use when x may be outside the range of a-b.  This situation is possible if your range is based upon an approximation, such as from ST_ApproxMinMax.
+{{{
+]a-b or )a-b = x < a, rule matches
+a-b[ or a-b( = x >= b, rule matches
+}}}
+    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]),
+  ROW(1, LEAST(covmin, 0)::text || '-0:0,0-' || GREATEST(covmax, 0)::text || ':0-255', '8BUI'),
+  ROW(2, LEAST(covmin, 0)::text || '-0:200,0-' || GREATEST(covmax, 0)::text' || ':0-255','8BUI'),
+  ROW(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
+}}}
+. 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)
+}}}
+. 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')
+}}}
+. 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')
+}}}
+. 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)
+}}}