= '''PostGIS Raster Working Specifications for Future Versions''' = {{{ #!div style='background-color: #F4F4F4; padding: 5px; border: 1px solid gray; float: right; margin-left: 5px; width: 260px; font-size: small;' > '''Quick Links''' * [wiki:WKTRaster PostGIS Raster Home Page] * [wiki:WKTRaster/PlanningAndFunding Planning & Funding] * [wiki:WKTRaster/SpecificationWorking02 Working Specifications for PostGIS 2.0] * [wiki:WKTRaster/SpecificationFinal01 Old Final Specifications for Beta 0.1.6] }}} ---- == '''Objective FV.01 - Being able to return a JPEG, a TIFF, a PNG or any image format supported by GDAL.''' == '''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)) Bborie: 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) -> 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]] 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 JPEG 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) ---- '''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"''' ---- '''ST_AsGDALRaster(raster, band int, type text, options text) -> bytea''' Use GDAL to convert the raster into one of the format suported by GDAL. Bborie: 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. 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_AsGDALRaster and other format specific functions (ST_AsJPEG, ST_AsTIFF and ST_AsPNG) are all wrappers around the function _ST_AsGDALRaster(rast raster, format text, options text[], srs text) ---- '''ST_getGDALDrivers() -> 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 not embedding any spatial reference information into the output GDAL raster. ---- == '''Objective FV.02 - Being able to intersect vector and raster to produce raster.''' == '''ST_Intersects(raster, raster)'''[[BR]] '''ST_AsRaster(geometry, pixelsize) -> raster'''[[BR]] '''ST_Intersection(geometry, val, raster, band) -> raster''' The first series of variant return a raster having the same extent as the provided raster. Variant 1: ST_Intersection(geometry, val, raster, band, pixeltype, nodatavalue) -> raster Variant 2: ST_Intersection(raster, band, geometry, val, pixeltype, nodatavalue) -> raster Variant 3: ST_Intersection(geometry, val, raster, pixeltype, nodatavalue) -> raster Variant 4: ST_Intersection(raster, geometry, val, pixeltype, nodatavalue) -> raster The second series of variant return a raster having the minimal extent. Variant 5: ST_Intersection(geometry, val, raster, band, pixeltype, nodatavalue, 'TRIM') -> raster Variant 6: ST_Intersection(raster, band, geometry, val, pixeltype, nodatavalue, 'TRIM') -> raster Variant 7: ST_Intersection(geometry, val, raster, pixeltype, nodatavalue, 'TRIM') -> raster Variant 8: ST_Intersection(raster, geometry, val, pixeltype, nodatavalue, 'TRIM') -> raster Returns a two bands raster the first band containing only the pixels from the provided raster intersecting with the geometry and the second band containing the same area filled with the provided value. The second band gets its pixeltype and nodatavalue from the parameters. Non intersecting pixels are filled with nodata values. Variant 1 return a raster having the same extent as the provided raster. Variant 3, 4, 7 and 8 defaults the band number to 1. Variant 5 to 8 "trim" or "crop" the raster to the withvalue extent (removing extra nodata value pixels surrounding the extent of the resulting withvalue extent). '''Open question''' PR: Shoud we return one raster per raster/geometry couple or split the raster into as many small rasters as there are areas sharing a same value? The second behavior seems more coherent with the present behavior of ST_Intersection(raster, geometry) -> geometry even if this would produce tons of small two bands rasters. '''Implementation details''' Rasterize the geometry as a new raster (ST_AsRaster(geometry, pixeltype, val, nodataval, raster)) and then copy only pixels for which both raster bands have a value. Should be implemented as a wrapper around ST_MapAlgebra after rasterizing the geometry to a raster having the same alignment as the raster. ---- == '''Objective FV.03 - Implement all the necessary versions of ST_MapAlgebra''' == Different versions of ST_MapAlgebra are planned... One raster versions: 1) '''ST_MapAlgebraExpr() -''' A one raster version taking an '''expression''' of one pixel at a time. Already implemented... 2) '''ST_MapAlgebraFct() -''' A one raster version taking a '''user defined function''' (with optional parameters) of one pixel at a time. The function is a user defined PL/pgSQL function taking a float8 value and returning a value. Code was developped by David Zwarg, needs to be integrated in the source tree. This version is much faster than 1) but requires the user to write a PL/pgSQL function. 3) '''ST_MapAlgebraFctNgb() -''' A one raster version taking a '''user defined function''' (with optional parameters) of the set of first, second, etc... '''neighbours''' of a pixel. The function is a user defined PL/pgSQL function taking a matrix containing the neighbour values and returning one value. Code do not exist yet but will be very much similar to 2). Out of bound pixels values are set to NULL. This version requires the user to write a PL/pgSQL function. Many predefined function should be delivered. 4) '''ST_MapAlgebraFctNgb() -''' A one raster version taking a '''table name and a raster column name''' (in order to work on a '''tiled coverage''') and a '''user defined function''' (with optional parameters) of the set of first, second, etc... '''neighbours''' of a pixel. The passed matrix should include values for out of bound pixels taken from neighbour tiles. Two rasters versions. These versions must take into account different alignment, different extents, nodata and non-existent values. 5) '''ST_MapAlgebraExpr() -''' A two rasters version taking an expression of two pixels at a time, one from each rasters. 6) '''ST_MapAlgebraExpr() -''' A two rasters version taking a '''table name and a raster column name''' (in order to work on a '''tiled coverage''') and an expression of two pixels at a time, one from each rasters. 7) '''ST_MapAlgebraFct() -''' A two rasters version taking a '''user defined function''' (with optional parameters) of two pixels at a time, one from each rasters. The function is a user defined PL/pgSQL function taking two float8 values and returning one value. 8) '''ST_MapAlgebraFct() -''' A two rasters version taking a '''table name and a raster column name''' (in order to work on a '''tiled coverage''') and a '''user defined function''' (with optional parameters) of two pixels at a time, one from each rasters. The function is a user defined PL/pgSQL function taking two float8 values and returning one value. Non-existent values are found in the neighbour tiles when possible. '''Details for 3) ST_MapAlgebraFctNgb()''' For now ST_MapAlgebra expressions refer only to the pixel being computed. e.g. "rast * 100". The original plan was to allow refering to neighbour pixels using two coordinated relative to the pixel being computed. e.g. "rast[-1,0] * 100" where rast[-1,0] refer to the value of the pixel one pixel to the left of the pixel being computed. However this syntax might prove to be hard to use when many neighbours are to be used. An alternative syntax would involve another function name (e.g. ST_MapAlgebraNgb or ST_MovingWindow) and a way to define a neighbour rectangular region around the computed pixel (e.g.: "2,2" meaning a rectangle encompassing the two neighbour pixels in each direction) and a function to call with this matrix of pixel values. A complete example might look like: SELECT ST_MapAlgebraNgb(rast, band, pixeltype, "ST_Mean", 2, 2, "ignore") So this would mean "for each pixel, compute the average of all the 1 + 8 + 16 = 25 pixels surrounding the current pixel and "ignore" pixels with nodata values." The "ST_Mean" summarizing function should accept three parameters: an array of float8 values, a X and a Y dimension, and optionnally a "what to do with nodata values". The possible value for this last parameter could be: * "NULL": If any value is a nodata value, return NULL. * "ignore": Ignore any nodata value so that if 4 pixels on 25 are nodata values, do the computation with the 21 remaining. This is the default. * "value": Replace any nodata value with the value of the pixel being computed. * a value: Replace any nodata value with this value and compute. Any remaining parameters to ST_MapAlgebraNgb could be passed to the summarizing functions for its own need (e.g. "round" to specify that only the pixel forming a circle should be used in the computing). A number of predefined summarizing function could be delivered: ST_Max, ST_Min, ST_Sum, ST_Distinct, ST_Mean, ST_STD, ST_Range, ST_Quantile, ST_Median, ST_Majority, ST_Minority, ST_Slope, ST_Aspect, and more... Users could write their own map algebra summarizing functions. A more sophisticated version would pass a georeferenced raster instead of just a value matrix so that summarizing function could use this geoereference (e.g. to determine a value from the whole coverage (with ST_Value) when the neighbours are out of the bound of the raster). Passing a raster would allow existing raster functions (like the summarizing function which are to come). Only the optional "what to do with nodata values" could be needed and some additional parameters. In this case the example become: SELECT ST_MapAlgebraNgb(rast, band, pixeltype, 2, 2, "ST_Mean", "ignore") and the dimensions do not have to be passed to the summarizing functions since it could deduce them from ST_Width & ST_Height. An even more sophisticated version should get a raster table and a raster column as parameters and try to search for neighbour in the whole raster coverage when out of bound pixels are part of the neighbourhood. e.g.: SELECT ST_MapAlgebraNgb("mycoveragetable", "myrastercolumn", band, pixeltype, 2, 2, "ST_Mean", "ignore") Three difficulties must be solved to implement this function: * The construction of the matrix must to be passed to the summarizing functions must be optimized when passing from one pixel to the other. * We must see how it is possible to call a PL/pgSQL function from a C function * We must see how to pass a variable number of parameter to a PL/pgSQL function See also: [wiki:WKTRaster/MapAlgebra Notes taken by David Zwarg during the Montreal Code Sprint 2011] and http://trac.osgeo.org/postgis/ticket/860 '''Details for 5) to 8) Two rasters versions''' These function must first determine if a resampling of one raster is necessary: '''ST_SameAlignment(raster, raster)''' This function returns true if both rasters' grids are aligned. Two rasters grid are aligned if: -They share the same pixel scales and skews -At least one of any of the four corner of any pixel of one raster fall on any corner of the grid of the other raster. Alignment is not the same concept as georeference. Two rasters can be aligned but not have the same georeference. Rotation is important here since two rasters grid might look perfectly aligned but are not if their rotated are different. Knowing if two rasters share the same alignment is useful when it is time to decide if one of them must be resampled before doing other operations (like ST_MapAlgebra on two rasters). '''Variants''' 1) ST_SameAlignment(ulx1, uly1, scalex1, scaley1, skewx1, skewy1, ulx2, uly2, scalex2, scaley2, skewx2, skewy2) 2) ST_SameAlignment(rast1 raster, rast2 raster) The first variant is useful to PL/pgSQL function which have already get the values of the parameters. '''Implementation Details''' Only the first variant should be implemented in C. The second one is a PL/pgSQL variants. The C implementation should follow the PL/pgSQL version implemented in http://trac.osgeo.org/postgis/browser/trunk/raster/scripts/plpgsql/st_mapalgebra.sql It is not clear if this PL/pgSQL implementation works when raster are rotated. To verify. See discussion in http://trac.osgeo.org/postgis/ticket/589 '''ST_MapAlgebra on two rasters''' Specifications of ST_MapAlgebra on two rasters are still in progress as a new optimised version, filling large areas of same value more quickly, is planned. See http://trac.osgeo.org/postgis/browser/trunk/raster/scripts/plpgsql/st_mapalgebra_optimized.sql See discussion in http://trac.osgeo.org/postgis/ticket/590 ---- == '''Objective FV.04 - Being able to use "group by" to accumulate tiles to form a new raster.''' == '''ST_Union(raster|geometry, raster|geometry, ‘raster’|’geometry’) -> raster/geometry'''[[BR]] '''ST_Accum(raster set|geometry set, ‘raster’|’geometry’) -> raster/geometry''' ---- == '''Objective FV.05 - Being able to reproject a raster.''' == '''ST_Transform(raster|geometry, SRID) -> same type as input''' ---- == '''Objective FV.06 - Being able to do some base raster operations.''' == '''ST_Area(raster|geometry) -> double'''[[BR]] '''ST_Count(raster, value) -> integer'''[[BR]] '''ST_Resample(raster, method, originx, originy, pixelsizex, pixelsizey) -> raster''' '''Variant''' 1) ST_Resample(raster, method, raster) -> raster Recompute a raster in order to change its pixel size and/or the position of its upper left corner. The second parameter is the resampling method performed when computing new pixel values: 1) 'NEAREST NEIGHBOR'[[BR]] 2) 'LINEAR'[[BR]] 3) 'BICUBIC' The 3rd or 3rd-6th parameters define the pixel size of the resampling operation. For the 3rd parameter variant, the pixel size is taken from the pixel size of the raster parameter. For the 3rd-6th parameter variant, the pixel origin and dimensions are explicitly defined. '''ST_SelectByValue(raster|geometry, ‘expression’) -> same type as first argument'''[[BR]] '''ST_Reclass(raster|geometry,string) -> same type as first argument'''[[BR]] '''ST_MapAlgebra(raster|geometry, [raster|geometry,…] ‘mathematical expression’, ‘raster’ |’geometry’) -> raster/geometry''' Variant 1: ST_MapAlgebra(raster|geometry, [raster|geometry,…] ‘mathematical expression’, ‘raster’ |’geometry’, originx, originy, pixelsizex, pixelsizey) -> raster/geometry Variant 2: ST_MapAlgebra(raster|geometry, [raster|geometry,…] 'mathematical expression', 'raster' |'geometry', integer) ->raster/geometry Variant 3: ST_MapAlgebra(raster|geometry, [raster|geometry,…] 'mathematical expression', 'raster' |'geometry', raster) ->raster/geometry ST_MapAlgebra performs the specified mathematical expression on the input rasters, returning a raster or geometry. Both rasters must have the same SRID. If both rasters do not have the same SRID, ST_MapAlgebra will return an error: ERROR: Operation on two geometries with different SRIDs The first raster passed to ST_MapAlgebra is the 'master' raster, unless either: 1 additional parameter specifies the index (in the parameter list) of the 'master' raster.[[BR]] 1 additional parameter specifies a raster whose origin and cell size should be used to compute the output raster.[[BR]] 4 additional parameters are passed specifying the origin, cell size, and raster rotation. This function implicitly calls ST_Intersects(raster|geometry, [raster|geometry,…]) to detect if the rasters are overlapping before performing any computation. Additionally, the resulting raster will have the same extent as the result of ST_Intersection(raster, integer, geometry). One of the implications of the ST_Intersects inclusion is that: SELECT ST_MapAlgebra(rast1, rast2, mathExpr) FROM mytable WHERE ST_Intersects(rast1, rast2) will be faster than: SELECT ST_MapAlgebra(rast1, rast2, mathExpr) FROM mytable '''Open Question:''' DZ: Should ST_MapAlgebra resample rasters internally, or produce a raster that can be processed by ST_Resample? If so, variant 1 and variant 3 can be removed, and all ST_MapAlgebra results can be processed through ST_Resample, like: ST_Resample(ST_MapAlgebra(raster, [raster,…] 'mathematical expression', integer), originx, originy, pixelsizex, pixelsizey)[[BR]] ST_Resample(ST_MapAlgebra(raster, [raster,…] 'mathematical expression', integer), rastergrid) PR: I think this would greatly contribute to simplify the API. '''ST_Clip(raster|geometry,geometry) -> same type as first argument'''[[BR]] '''ST_Flip(raster|geometry, ’vertical’|’horizontal’) -> same type as first argument''' ---- == '''Objective FV.07 - Being able to convert a raster to standards formats.''' == '''ST_AsKML(raster|geometry) -> string'''[[BR]] '''ST_AsSVG(raster|geometry) -> string''' ---- == '''Objective FV.08 - Being able to control the validity of a raster.''' == '''ST_IsEmpty(raster|geometry) -> boolean'''[[BR]] '''ST_mem_size(raster|geometry) -> integer'''[[BR]] '''ST_isvalid(raster|geometry) -> boolean''' ---- == '''Objective FV.09 - Being able to use other major topological operators''' == '''ST_Within(raster|geometry A, raster|geometry B)'''[[BR]] '''ST_Contains(raster|geometry A, raster|geometry B)'''[[BR]] '''ST_Overlaps(raster|geometry, raster|geometry)''' ---- == '''Objective FV.10 - Being able to derive a raster layer from vector layer.''' == '''ST_Interpolate(points, pixelsize, method) -> raster''' ---- == '''Objective FV.11 - Being able to do on rasters most operations available on geometries''' == '''ST_Centroid(raster|geometry) -> point geometry'''[[BR]] '''ST_PointOnSurface(raster|geometry) -> point geometry'''[[BR]] '''ST_Buffer(raster|geometry, double) -> same type as first arg.'''[[BR]] '''ST_Difference(raster|geometry A, raster|geometry B) -> same type as first argument'''[[BR]] '''ST_SymDifference(raster|geometry,raster|geometry,‘raster’|’geometry’) -> raster/geometry''' ---- == '''Objective FV.12 - Being able to use all the other topological operators''' == '''ST_Equals(raster|geometry, raster|geometry)'''[[BR]] '''ST_Disjoint(raster|geometry, raster|geometry)'''[[BR]] '''ST_Touches(raster|geometry, raster|geometry)'''[[BR]] '''ST_Crosses(raster|geometry, raster|geometry)'''[[BR]] '''ST_Covers(raster|geometry A, raster|geometry B)'''[[BR]] '''ST_IsCoveredBy(raster|geometry A, raster|geometry B)'''[[BR]] '''ST_Relate(raster|geometry, raster|geometry, intersectionPatternMatrix )''' ---- == '''Objective FV.13 - Being able to edit a raster''' == '''ST_Affine(raster|geometry,…) -> same type as input'''[[BR]] '''ST_Translate(raster|geometry,…) -> same type as input'''[[BR]] '''ST_Scale(raster|geometry,…) -> same type as input'''[[BR]] '''ST_TransScale(raster|geometry,…) -> same type as input'''[[BR]] '''ST_RotateZ,Y,Z(raster|geometry, float8) -> same type as input''' ---- == '''Objective FV.14 - Being able to intersect two rasters to get a raster.''' == '''ST_Intersection(raster, integer, raster, integer) -> raster''' - Returns a two bands raster with values only in the intersecting areas of both rasters. Integer parameters are the band number of the raster. '''Variants''' 1) ST_Intersection(raster, integer, raster, integer) -> raster -- the integer parameters are the band number of the rasters[[BR]] 2) ST_Intersection(raster, raster, integer) -> raster -- default first raster to band # 1[[BR]] 3) ST_Intersection(raster, integer, raster) -> raster -- default second raster to band # 1[[BR]] 4) ST_Intersection(raster, raster) -> raster -- default both rasters to band # 1 ---- == '''Objective FV.15 - Being able to intersect two rasters to get a geometry.''' == '''ST_Intersection(raster, integer, raster, integer, 'geometry') -> geometry''' - Returns a two bands raster with values only in the intersecting areas of both rasters. Integer parameters are the band number of the raster. '''Variants''' 1) ST_Intersection(raster, integer, raster, integer, 'geometry') -> geometry[[BR]] 2) ST_Intersection(raster, raster, integer, 'geometry') -> geometry -- default first raster to band # 1[[BR]] 3) ST_Intersection(raster, integer, raster, 'geometry') -> geometry -- default second raster to band # 1[[BR]] 4) ST_Intersection(raster, raster, 'geometry') -> geometry -- default both raster to band # 1 ---- == '''Objective FV.16 - Being able to quickly get raster statistics.''' == '''Add cached basic raster statistic to the base raster WKB format. ---- == '''Objective FV.17 - Being able to refer to band by textual name.''' == '''Add 8 digit string to each band in the base raster WKB format. '''Adjust gdal2wktraster.py to be able to give names to each band when importing. '''Adjust/overlaod every function to be able to refer to raster band by name. ---- == '''Objective FV.18 - Being able to load rasters from SQL''' == The idea is to change the rt_band_get_data core function so it load filesystem registered raster data using GDAL into the data base. This allow us to create a list of raster with a new ST_MakeRegisteredRaster("c:/temp/mytiff/*.tif") and to convert them witinot a CREATE TABLE with a ST_MakeBandInDB(rast, band) '''Changes to the rt_band_get_data core function'''[[BR]] '''ST_MakeRegisteredRaster(wildcardPath)'''[[BR]] '''ST_SetPath(raster, band, string)'''[[BR]] '''ST_MakeBandInDB(rast, band)''' ---- == '''Other functions''' == '''ST_AsBinary(raster, compression)'''[[BR]] '''ST_RasterFromWKB(raster, [])'''[[BR]] '''ST_RasterFromText(string, [])'''[[BR]] '''ST_AsText(raster)'''