[raster] ST_AsTIFF

[mloskot]

This tasks belongs to the Objective 0.1.6f specified in the WKT Raster roadmap

As stated at the end of the comment 5 of the "Specification Comments following the Code Sprint" section of the working specifications, this function should be a PL/pgSQL wrapper around a more general ST_AsImage(format, params) function using GDAL to convert any raster to an image.

The function should return a bytea.

See the working specifications for more details/questions.

[pracine]

A more general ST_AsImage invoking GDAL should be implemented first. ST_AsTIFF should be a wrapper around this more generic function.

[dustymugs]

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.

---

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 last 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 three 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

DEFLATE8

ST_AsTIFF(rast raster, compression text, options 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', 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, '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, '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, compression text, 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, 'DEFLATE9', ARRAY['PROFILE=GeoTIFF'])

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 three functions include band index and compression arguments

ST_AsTIFF(rast raster, nbands int[], compression text, options 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, 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[2], 'DEFLATE9', ARRAY['PROFILE=GeoTIFF'])

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. Like the prior function, the spatial reference of the TIFF will be set to the same as the input raster.

---

Any thoughts before I add this to the wiki?

Also, I wonder if this is an excessive number of possible functions. I ask because I'm wondering if I should add additional possible ways to specify the nbands argument (a single integer or a text string).

[pracine]

1) Shouldn't the most generic variant include a nband[] parameter?

2) It seems to me that the variant with "compression" should not allow users to specify options as this parameter is specifically for lazy users only interested in the compression scheme and who do not want to know about other options. This way you could alleviate the series of at least 4 variants (the two "with compression/no band" with "options text[] and srs text" and the two ones with the band parameter).

(It`s nice to number the variant so we can refer to them by their number.)

[dustymugs]

1. The functions with the nband[] parameter use ST_Band internally before calling the generic ST_TIFF variant. This way, the generic variant expects that the raster passed to it is the final raster to be converted to a TIFF.

2. Great idea. That would alleviate the number of variants.

I'll number the variants for ST_AsJPEG and ST_AsPNG when I post their functions.

[dustymugs]

Adds ST_TIFF capability

[dustymugs]

Attached incremental patch for adding ST_AsTIFF. Patch can be applied with the following in the base postgis source directory.

patch -p1 < st_astiff.patch

Patches for ST_Band, ST_MinMax, ST_Reclass and ST_AsGDALRaster must be applied first in the order listed.

[dustymugs]

No changes made. Update diff due to incremental changes in ST_MinMax.

[dustymugs]

Updated patch to better follow guidelines for error messages

[dustymugs]

Add ST_AsTIFF. Merges cleanly against r7145.

The following patches must be merged first for this patch to merge cleanly:

1. ST_Band

2. ST_SummaryStats

3. ST_Mean

4. ST_StdDev

5. ST_MinMax

6. ST_Histogram

7. ST_Quantile

8. ST_Reclass

9. ST_AsGDALRaster

[dustymugs]

Added in r7156