SDO_GEOR.getRasterSubset

Format

SDO_GEOR.getRasterSubset(
     georaster    IN SDO_GEORASTER, 
     pyramidLevel IN NUMBER DEFAULT 0, 
     window       IN SDO_NUMBER_ARRAY, 
     bandNumbers  IN VARCHAR2, 
     rasterBlob   IN OUT NOCOPY BLOB, 
     storageParam IN VARCHAR2 DEFAULT NULL, 
     bgValues     IN SDO_NUMBER_ARRAY DEFAULT NULL);

or

SDO_GEOR.getRasterSubset(
     georaster    IN SDO_GEORASTER, 
     pyramidLevel IN NUMBER DEFAULT 0,
     inWindow     IN SDO_NUMBER_ARRAY, 
     bandNumbers  IN VARCHAR2, 
     rasterBlob   IN OUT NOCOPY BLOB, 
     outWindow    OUT SDO_NUMBER_ARRAY, 
     storageParam IN VARCHAR2 DEFAULT NULL, 
     bgValues     IN SDO_NUMBER_ARRAY DEFAULT NULL);

or

SDO_GEOR.getRasterSubset(
     georaster    IN SDO_GEORASTER, 
     pyramidLevel IN NUMBER DEFAULT 0, 
     window       IN SDO_GEOMETRY, 
     layerNumbers IN VARCHAR2, 
     rasterBlob   IN OUT NOCOPY BLOB, 
     storageParam IN VARCHAR2 DEFAULT NULL, 
     bgValues     IN SDO_NUMBER_ARRAY DEFAULT NULL, 
     polygonClip  IN VARCHAR2 DEFAULT NULL);

or

SDO_GEOR.getRasterSubset(
     georaster    IN SDO_GEORASTER, 
     pyramidLevel IN NUMBER DEFAULT 0, 
     inWindow     IN SDO_GEOMETRY, 
     layerNumbers IN VARCHAR2, 
     rasterBlob   IN OUT NOCOPY BLOB, 
     outWindow    OUT SDO_NUMBER_ARRAY, 
     storageParam IN VARCHAR2 DEFAULT NULL, 
     bgValues     IN SDO_NUMBER_ARRAY DEFAULT NULL, 
     polygonClip  IN VARCHAR2 DEFAULT NULL);

or

SDO_GEOR.getRasterSubset(
     georaster    IN SDO_GEORASTER, 
     pyramidLevel IN NUMBER DEFAULT 0, 
     inWindow     IN SDO_NUMBER_ARRAY, 
     bandNumbers  IN VARCHAR2, 
     rasterData   IN OUT SDO_NUMBER_ARRAY, 
     outWindow    OUT SDO_NUMBER_ARRAY, 
     storageParam IN VARCHAR2 DEFAULT NULL, 
     bgValues     IN SDO_NUMBER_ARRAY DEFAULT NULL);

or

SDO_GEOR.getRasterSubset(
     georaster    IN SDO_GEORASTER, 
     pyramidLevel IN NUMBER DEFAULT 0, 
     inWindow     IN SDO_GEOMETRY, 
     layerNumbers IN VARCHAR2, 
     rasterData   IN OUT SDO_NUMBER_ARRAY, 
     outWindow    OUT SDO_NUMBER_ARRAY, 
     storageParam IN VARCHAR2 DEFAULT NULL, 
     bgValues     IN SDO_NUMBER_ARRAY DEFAULT NULL, 
     polygonClip  IN VARCHAR2 DEFAULT NULL);

or

FUNCTION SDO_GEOR.getRasterSubset(
     georaster    IN SDO_GEORASTER, 
     pyramidLevel IN NUMBER DEFAULT 0, 
     inWindow     IN SDO_GEOMETRY DEFAULT NULL, 
     layerNumber  IN NUMBER DEFAULT 1, 
     pointPolygon IN NUMBER DEFAULT 1, 
     bgValues     IN SDO_NUMBER_ARRAY DEFAULT NULL, 
     polygonClip  IN VARCHAR2 DEFAULT NULL
     ) RETURN SDO_GEOR_CELL_TABLE PIPELINED;

Description

The procedure formats create a single BLOB object or a single SDO_NUMBER_ARRAY object containing all cells of a specified pyramid level that are inside or on the boundary of either a specified rectangular window or polygon geometry object. The function format returns a nested table that holds the cell value, pyramid, row, column, layer, and area or point geometry of all cells inside and touching the specified window.

Parameters

georaster

GeoRaster object.

pyramidLevel

Pyramid level on which to perform the operation.

window, inWindow

A rectangular window or a polygon geometry object from which to crop the cells. If the data type is SDO_NUMBER_ARRAY, the parameter identifies the upper-left (row, column) and lower-right (row, column) coordinates of a rectangular window, and raster space is assumed. If the data type is SDO_GEOMETRY and the polygonClip value is FALSE, the MBR of the geometry object is used as the window; if the data type is SDO_GEOMETRY and the polygonClip value is TRUE, the polygon geometry object (if valid) is used as the window. If the data type is SDO_GEOMETRY, see also the Usage Notes for SDO_SRID requirements.

If window or inWindow is of type SDO_NUMBER_ARRAY, use the bandNumbers parameter to specify one or more band numbers; if window or inWindow is of type SDO_GEOMETRY, use the layerNumbers parameter to specify one or more layer numbers.

layerNumbers

A string identifying the logical layer numbers on which the operation or operations are to be performed. Use commas to delimit the values, and a hyphen to indicate a range (for example, 2-4 for layers 2, 3, and 4). If you specify a null value for this parameter, the operation or operations are performed on all layers.

layerNumber

For the function format, the layer number on which to perform the operation. The default value is 1.

bandNumbers

A string identifying the physical band numbers on which the operation or operations are to be performed. Use commas to delimit the values, and a hyphen to indicate a range (for example, 1-3 for bands 1, 2, and 3). If you specify a null value for this parameter, the operation or operations are performed on all bands.

rasterBlob

BLOB object to hold the result (the mosaicked raster subset) of the operation. It must exist or have been initialized before the operation.

rasterData

SDO_NUMBER_ARRAY object to hold the result (the mosaicked raster subset) of the operation.

(Note: The upper limit of element numbers in an SDO_NUMBER_ARRAY object is 1048576.)

outWindow

An SDO_NUMBER_ARRAY object identifying the coordinates of the upper-left and lower-right corners of the output window in the cell space.

storageParam

A string specifying storage parameters to be applied in creating rasterBlob. The only supported storageParam keywords supported for this procedure are celldepth, compression, interleaving, and quality; all other keywords are ignored. Storage parameters are explained in Storage Parameters.

If storageParam is null or not specified, the cell depth, interleaving, and compression type (and compression quality, if applicable) are the same as for the input GeoRaster object.

pointPolygon

If 0, the function returns a boundary polygon geometry for each cell; if 1 (the default), the function returns the central point geometry for each cell.

bgValues

Background values for filling sparse data. The number of elements in the SDO_NUMBER_ARRAY object must be either one (same filling value used for all bands) or the band dimension size (a different filling value for each band, respectively). For example, SDO_NUMBER_ARRAY(1,5,10) fills the first band with 1, the second band with 5, and the third band with 10. The default bgValues are zero (0).

This parameter is useful when the source has empty raster blocks and the output window intersects any empty raster blocks (see Empty Raster Blocks). If this parameter is not specified, any cells in the output window that are derived from an empty raster block are filled with the value 0 in the output BLOB.

polygonClip

The string TRUE causes the window or inWindow geometry object to be used for the subset operation; the string FALSE or a null value causes the MBR (minimum bounding rectangle) of the window or inWindow geometry object to be used for the subset operation.

Usage Notes

This subprogram has several procedure formats and a function format. The procedure format to use depends whether the input window is specified as a geometry object or as the upper-left and lower-right corners of a box, whether the result of the operation is a BLOB or SDO_NUMEBR_ARRAY object, and on whether the outWindow parameter is used to return the coordinates of the output window.

If the window or inWindow parameter data type is SDO_GEOMETRY, the SDO_SRID value must be one of the following:

Null, to specify raster space
A value from the SRID column of the MDSYS.CS_SRS table

If the SDO_SRID values for the window parameter geometry and the model space are different, the window parameter geometry is automatically transformed to the coordinate system of the model space before the operation is performed. (Raster space and model space are explained in GeoRaster Data Model.)

If the window or inWindow parameter specifies a geodetic MBR, it cannot cross the date line meridian. For information about geodetic MBRs, see Oracle Spatial Developer's Guide.

After the procedure completes, the rasterBLOB parameter contains the cell (pixel) data in the cropped window without tiling. The cropped window is the overlapping portion of the specified window of interest and the source GeoRaster object's spatial extent. If the outWindow parameter is specified, after the procedure completes it contains the coordinates of the cropped window in the cell space.

The BLOB has no padding, except when the cell depth is less than 8 bits and the total number of bits needed for the output cannot be divided by 8; in these cases, unlike normal padding, only the last byte of the result is padded with 0 (zeros) for the trailing bits.

If polygonClip is TRUE, and if this procedure creates a rectangular image subset but the geometry is not a rectangle, check the validity of the inWindow geometry object with the function SDO_GEOM.VALIDATE_GEOMETRY_WITH_CONTEXT. For an invalid geometry, this procedure operates as if the polygonClip value is FALSE or a null value.

You can specify compression even if the input GeoRaster object is not compressed or is compressed in a different format from what you specify in the storageParam parameter. To have decompressed output for a compressed input GeoRaster object, specify compression=NONE in the storageParam parameter. For information about GeoRaster compression and decompression, see Compression and Decompression.

If you want to get a subset and reproject it to another coordinate system, do not use this procedure, but instead use the SDO_GEOR.rectify procedure using a format that includes the rasterBlob parameter, so that this BLOB holds the desired subset.

The SDO_GEOR_CELL_TABLE type for the result of the function format has the following definition:

SDO_GEOR_CELL_TABLE TABLE OF MDSYS.SDO_GEOR_CELL
Name                           Null?     Type
------------------------------ --------  ----------------------------
VALUE                                    NUMBER
PYRAMIDLEVEL                             NUMBER
ROWNUMBER                                NUMBER
COLNUMBER                                NUMBER
LAYERNUMBER                              NUMBER
GEOM                                     MDSYS.SDO_GEOMETRY

Examples

The following two examples retrieve raster data of a specified pyramid level inside a specified window into a BLOB object and an SDO_NUMBER_ARRAY object. (They refer to the GEORASTER_TABLE table, whose definition is presented after Example 1-1 in Storage Parameters.)

DECLARE
  gr sdo_georaster;
  lb blob;
  win sdo_number_array;
BEGIN
  SELECT georaster INTO gr FROM georaster_table WHERE georid=4;
  dbms_lob.createTemporary(lb, TRUE);
  win := sdo_number_array(-21,100,100,200);
  sdo_geor.getRasterSubset(gr, 0, win, null, lb);
  dbms_lob.freeTemporary(lb);
END;
/

DECLARE
  gr sdo_georaster;
  data sdo_number_array;
  win sdo_number_array;
BEGIN
  SELECT georaster INTO gr FROM georaster_table WHERE georid=4;
  win := sdo_number_array(-21,100,100,200);
  sdo_geor.getRasterSubset(gr, 0, win, null, data);
END;
/

The following example demonstrates how to get the window for the cropping.

DECLARE
  gr sdo_georaster;
  lb blob;
  win1 sdo_geometry;
  win2 sdo_number_array;
BEGIN
  SELECT georaster INTO gr FROM georaster_table WHERE georid=4;
  dbms_lob.createTemporary(lb, TRUE);
  win1 := sdo_geometry(2003,82263,null,sdo_elem_info_array(1,1003,3),
                       sdo_ordinate_array(1828466,646447,1823400,642512));
  sdo_geor.getRasterSubset(gr, 0, win1, '1-3', lb, win2, 'compression=NONE');
  dbms_lob.freeTemporary(lb);
  IF win2 IS NOT NULL THEN
    dbms_output.put_line('output window: (' || win2(1) || ',' ||
                          win2(2) || ',' || win2(3) || ',' || win2(4) || ')');
  END IF;
END;
/

The following example demonstrates how to do clipping while querying a subset using a polygon.

DECLARE
  gr sdo_georaster;
  lb blob;
  win1 sdo_geometry;
  win2 sdo_number_array;
BEGIN
  dbms_lob.createTemporary(lb, TRUE);
  SELECT georaster INTO gr FROM rstpoly_table WHERE georid=1;
  -- querying/clipping polygon
  win1 := sdo_geometry(2003, 26986, null, sdo_elem_info_array(1,1003,1),
                sdo_ordinate_array(237040,   897924, 
                                   237013.3, 897831.6,
                                   237129,   897840,
                                   237182.5, 897785.5, 
                                   237239.9, 897902.7,
                                   237223,   897954,
                                   237133,   897899,
                                   237040,   897924));
  sdo_geor.getRasterSubset(gr, 0, win1, '1-3', 
                           lb, win2, NULL, NULL, 'TRUE');
  -- Then work on the resulting subset stored in lb.
END;
/

7.84 SDO_GEOR.getRasterSubset