ST_Raster.subset

Definition

ST_Raster.subset returns a subset of an ST_Raster object.

Syntax

Oracle

subset (parameter_list IN VARCHAR2) RETURN ST_RASTER

subset (parameter_list IN VARCHAR2, 
        options IN VARCHAR2) RETURN ST_RASTER

PostgreSQL

subset (raster IN ST_RASTER, 
        parameter_list IN TEXT) RETURN ST_RASTER

subset (raster IN ST_RASTER, 
        parameter_list IN TEXT, 
        options IN TEXT) RETURN ST_RASTER

SQL Server

subset (parameter_list IN NVARCHAR, 
        options IN NVARCHAR) RETURN ST_RASTER

Returns

ST_Raster

Parameters

Parameter

Description

raster

The ST_Raster from which the subset will be generated

parameter_list

A comma-delimited list of parameters enclosed in single quotes that may include the following parameters:

  • band <1st band number>[,<2nd band number>],…,[nth band number]>—A comma-delimited list of band sequence numbers of the bands returned

    The pixel data is returned in the order of the band sequence numbers. If the parameter is not specified, all the bands of the ST_Raster are exported in regular band sequential order.

  • window (minx,miny,maxx,maxy)—The area of the ST_Raster expressed in pixel coordinates

    The window parameter is exclusive of the extent parameter; one or the other may be used to define a subset area, but not both. If both are present, an error is returned. If neither is present, the entire area of the source ST_Raster is returned.

  • extent (minx,miny,maxx,maxy)—The area of the ST_Raster expressed in geographic coordinates

    The extent parameter is exclusive of the window parameter; one or the other may be used to define a subset area, but not both. If both are present, an error is returned. If neither is present, the entire area of the source ST_Raster is returned.

options

A comma-delimited list of options enclosed in single quotes that may include the following:

  • compression <lz77 | jpeg | jp2>—The compression algorithm to be applied to the ST_Raster; the default is to not compress the data.
  • interleave <separate | contiguous>—This option applies to ST_Rasters that store three-band, eight-bit pixel data. Specifying a separate interleave indicates that the pixel data will be extracted in separate RGB bands, while specifying a contiguous interleave indicates that the pixel data will be extracted in a contiguous series of red, green, and blue pixels.
  • conversion <rgb | grayscale>—When set to rgb, the conversion parameter directs the subset function to return a single-band color-mapped ST_Raster as a three-band RGB ST_Raster. A conversion parameter set to grayscale indicates that a 1-bit black-and-white ST_Raster object should be returned as an 8-bit grayscale ST_Raster.
  • quality <value>—The quality for either JPEG compression or JPEG 2000 variable compression
  • bitrate <value>—The bitrate for JPEG 2000 fixed compression
  • nodata (r,g,b) | <value>—The pixel values of the ST_Raster that will be returned as nodata
  • nocolormap—Indicates that the color map will not be returned
  • edge <value>:<tolerance>—Removes the unwanted boundary pixels around an ST_Raster that are marked as NoData; edge indicates that only the pixels in the specified value range will be removed and only from the outside edge of the raster. This prevents pixels of the same value within the raster from being removed.
  • level <pyramid level>—The pyramid level of the ST_Raster that will be returned; the default is the base pyramid level.
  • skipLevel1—Indicates that the ST_Raster is returned without its first pyramid level; the pyramid begins at the second level.
  • tile (width,height)—The pixel width and height of the tiles of the returned ST_Raster
  • nearest | bilinear | bicubic—The pyramid interpolation of the returned ST_Raster
  • log <logfile name>—The log file captures the results of the subset function

Examples

In the first example, the ST_Raster.subset function is used to create a copy of an existing ST_Raster object with a reversed band sequence.

In the second example, the output of the ST_Raster.subset function is used as a source of raster data for the ST_Raster.mosaic function. The second pyramid level is extracted from the image column of the world table using the ST_Raster.subset function, which is then mosaicked to the image column of the valley table.

Oracle

  1. INSERT INTO VALLEY (image)
    SELECT image.subset('band=(3,2,1)')
    FROM VALLEY
    WHERE image.raster_id = 2;
  2. UPDATE VALLEY t
    SET image = t.image.mosaic ('select t.image.subset('level=2') 
    FROM WORLD t', 'log=E:\log.txt');

PostgreSQL

  1. INSERT INTO valley (image)
    SELECT subset(image,'band=(3,2,1)')
    FROM valley
    WHERE raster_id(image) = 2;
  2. UPDATE valley
    SET image = mosaic (image,'select subset(image,'level=2') 
    FROM world', 'log=E:\log.txt');

SQL Server

  1. INSERT INTO valley (image)
    SELECT image.subset('band=(3,2,1)',NULL)
    FROM valley
    WHERE image.raster_id = 2;
  2. UPDATE valley
    SET image = image.mosaic (NULL, 'select image.subset('level=2',NULL) 
    FROM world', 'log=E:\log.txt');

11/18/2013