[postgis-devel] [PostGIS] #901: [raster] ST_AsGDALRaster and the helper functions ST_getGDALDrivers and ST_srtext

[PostGIS]

#901: [raster] ST_AsGDALRaster and the helper functions ST_getGDALDrivers and
ST_srtext
-----------------------+----------------------------------------------------
 Reporter:  dustymugs  |       Owner:  pracine              
     Type:  task       |      Status:  new                  
 Priority:  medium     |   Milestone:  PostGIS Raster Future
Component:  postgis    |     Version:  trunk                
 Keywords:             |  
-----------------------+----------------------------------------------------
 What follows is a proposal on the specifics of ST_AsGDALRaster and two
 supporting functions.

 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')
 }}}

 The two helper functions are:

 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.

 {{{
 SELECT * FROM ST_getGDALDrivers()
 }}}

 The formats outputted from ST_getGDALDrivers have been filtered to only
 those that the GDAL capabilities !CreateCopy and Virtual IO support.

 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.

 {{{
 SELECT ST_srtext(rast);
 }}}

 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.

-- 
Ticket URL: <http://trac.osgeo.org/postgis/ticket/901>
PostGIS <http://trac.osgeo.org/postgis/>
The PostGIS Trac is used for bug, enhancement & task tracking, a user and developer wiki, and a view into the subversion code repository of PostGIS project.