Encode function in rasql
Note: this text has been included in the documentation of QL Guide 8.4.
The encode() function allows to export MDDs to various formats as supported by the GDAL library. This function has the following signature:
encode( mddExpr, format, formatParams? )
This is an expression that must evaluate to an 2D MDD object. Supported is encoding of single-band MDDs of any type, and multi-band MDDs where all bands have to be of the same type.
This is a string parameter (has to be in quotes in the query) that indicates to which format should the MDD be encoded. It has to be the format ID that GDAL understands, i.e. one of the IDs that gdal_translate outputs. For example:
$ gdal_translate GDAL 1.9.0, released 2011/12/29 The following format drivers are configured and support output: VRT: Virtual Raster GTiff: GeoTIFF NITF: National Imagery Transmission Format HFA: Erdas Imagine Images (.img) ELAS: ELAS ...
The identifiers in the first column above (VRT, GTiff, etc.) are the accepted values. For a full list of the formats supported by GDAL and respective codes see http://www.gdal.org/formats_list.html
This optional string parameter allows to pass format-specific options, as well as generic parameters like a geo-referencing bounding box and CRS. The parameters have to be fit into one string (quoted in the query) in the following format:
Note that both the key and the value are case-sensitive.
Parameters that apply to each format
- xmin, ymin, xmax, ymax for specifying the bounding box;
- metadata for any extra metadata that should be added to the output file;
- nodata allows to give a list of nodata values for each band separated by a comma, e.g. "nodata=119,208,248;" will set the blue color of the sample rasdaman image rgb to transparent; if only one value is given it will be set to all bands. By default nodata is set to 0 for all bands;
- crs, which can accept any of these CRS representations (reference):
- Well Known Text definition
- "AUTO:proj_id,unit_id,lon0,lat0" indicating OGC WMS auto projections
- "urn:ogc:def:crs:EPSG::n" indicating OGC URNs (deprecated by OGC)
- PROJ.4 definitions
- well known name, such as NAD27, NAD83, WGS84 or WGS72.
- WKT in ESRI format, prefixed with "ESRI::"
- "IGNF:xxx" - "+init=IGNF:xxx"
- Since GDAL v1.10.0 OGC CRS URLs are supported as well (gdal ticket).
Further format-specific parameters are listed on the respective format pages, e.g. GeoTIFF for example would support an INTERLEAVE=[BAND,PIXEL] parameter.
Configuration options can be added via the config parameter (rasdaman v9.0.2 on), as a comma-separated list of KV white-space spaced pairs.
The result from the encode() function is a 1D MDD of type char, which is the MDD encoded to the target format. In other words, encode() behaves same as png(), netcdf(), and the other convertor function in rasdaman.
The below query will encode a 2D slice (out of the 3D collection COLL) to GeoTIFF, setting the bounding box and crs appropriately, and with the band interleaving (default is pixel):
rasql -q 'select encode( c[0, *:*, *:*], "GTiff", "xmin=25;ymin=-40;xmax=75;ymax=75;crs=EPSG:4326;INTERLEAVE=BAND;metadata=\"some metadata\"" ) from COLL as c' --out file
If we want to retrieve a JPEG2000 image with embedded GML information (requires JP2OpenJPEG driver, and GDAL 1.10 or greater), we can write:
rasql -q 'select encode(c, "JP2OpenJPEG", \ "xmin=0;xmax=666;ymin=0;ymax=999;\ crs=EPSG:2000;\ CODEC=jp2;\ config=GMLJP2OVERRIDE /path/to/coverage_gml_fragment.xml") \ from mr AS c'
Note that JP2 codec is required in this case (J2K does not enable GML box). If the configuration option GMLJP2OVERRIDE is not specified, then GDAL will embed a default minimal (OGC) GMLJP2 fragment. Mind as well that JP2OpenJPEG only supports creating Byte, GDT_Int16, GDT_UInt16, GDT_Int32 and GDT_UInt32. In case of small images, the encoding JP2OpenJPEG can also fail because the default number of pyramids (6) is too high for such image, hence the 6 pyramids cannot be created; in this case, tune the RESOLUTIONS parameter to a lower value.