SDO_GEOR.subset

Format

SDO_GEOR.subset(
     inGeoRaster   IN SDO_GEORASTER, 
     cropArea      IN SDO_GEOMETRY, 
     layerNumbers  IN VARCHAR2, 
     storageParam  IN VARCHAR2 DEFAULT NULL, 
     outGeoRaster  IN OUT SDO_GEORASTER, 
     bgValues      IN SDO_NUMBER_ARRAY DEFAULT NULL, 
     polygonClip   IN VARCHAR2 DEFAULT NULL);

or

SDO_GEOR.subset(
     inGeoRaster   IN SDO_GEORASTER, 
     pyramidLevel  IN NUMBER, 
     cropArea      IN SDO_GEOMETRY, 
     layerNumbers  IN VARCHAR2, 
     storageParam  IN VARCHAR2 DEFAULT NULL, 
     outGeoRaster  IN OUT SDO_GEORASTER, 
     bgValues      IN SDO_NUMBER_ARRAY DEFAULT NULL, 
     polygonClip   IN VARCHAR2 DEFAULT NULL);

or

SDO_GEOR.subset(
     inGeoRaster   IN SDO_GEORASTER, 
     cropArea      IN SDO_NUMBER_ARRAY, 
     bandNumbers   IN VARCHAR2, 
     storageParam  IN VARCHAR2 DEFAULT NULL, 
     outGeoRaster  IN OUT SDO_GEORASTER, 
     bgValues      IN SDO_NUMBER_ARRAY DEFAULT NULL);

or

SDO_GEOR.subset(
     inGeoRaster   IN SDO_GEORASTER, 
     pyramidLevel  IN NUMBER, 
     cropArea      IN SDO_NUMBER_ARRAY, 
     bandNumbers   IN VARCHAR2, 
     storageParam  IN VARCHAR2 DEFAULT NULL, 
     outGeoRaster  IN OUT SDO_GEORASTER, 
     bgValues      IN SDO_NUMBER_ARRAY DEFAULT NULL);

Description

Performs either or both of the following operations: (1) spatial crop, cut, or clip, or (2) layer or band subset or duplicate.

Parameters

inGeoRaster

The SDO_GEORASTER object on which the operation or operations are to be performed.

pyramidLevel

A number specifying the pyramid level of the source GeoRaster object.

cropArea

Crop area definition. 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, the minimum bounding rectangle (MBR) of the geometry object is used as the crop area; see also the Usage Notes for SDO_SRID requirements.

If cropArea is of type SDO_GEOMETRY, use the layerNumbers parameter to specify one or more layer numbers; if cropArea is of type SDO_NUMBER_ARRAY, use the bandNumbers parameter to specify one or more band 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).

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).

storageParam

A string specifying storage parameters, as explained in Storage Parameters.

outGeoRaster

The new SDO_GEORASTER object. Must be either a valid existing GeoRaster object or an empty GeoRaster object. (Empty GeoRaster objects are explained in Blank and Empty GeoRaster Objects.) Cannot be the same GeoRaster object as inGeoRaster.

bgValues

Background values for filling partially empty raster blocks. It is only useful when the source GeoRaster object has empty raster blocks and the current operation leads to partially empty raster blocks (see Empty Raster Blocks). 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).

The filling values must be valid cell values as specified by the target cell depth background values for filling sparse data.

polygonClip

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

Usage Notes

This procedure has a variety of possible uses. For example, you can call it to crop a small area or obtain a subset of a few layers of a GeoRaster object, you can duplicate layers, and you can specify storage parameters such as blocking and interleaving for the resulting object.

If you use the format that includes the pyramidLevel parameter and specify a value greater than zero (0), the cropping is done based on the specified pyramid level of the source GeoRaster object; otherwise, the cropping is done based on the original source GeoRaster object (pyramidLevel = 0).

If the source GeoRaster object is georeferenced and the pyramidLevel parameter value is greater than 0, the georeferencing information is generated for the resulting GeoRaster object only when the georeference is a valid polynomial transformation.

Any upper-level pyramid data in the input GeoRaster object is not considered in this operation, and the output GeoRaster object has no pyramid data.

If the cropArea 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 cropArea 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 cropArea parameter specifies a geodetic MBR, it cannot cross the date line meridian. For information about geodetic MBRs, see Oracle Spatial Developer's Guide.

To be able to use the clipping window geometry object itself to subset the GeoRaster object, the geometry object must be a valid two-dimensional polygon geometry, simple or multipolygon, with an SDO_GTYPE value in the form 2nn3 or 2nn7. For any other SDO_GTYPE value, the MBR of the geometry object is used regardless of the value of the polygonClip parameter. (For an explanation of SDO_GTYPE values, see Oracle Spatial Developer's Guide.)

If the clipping window geometry object itself is applied to the subset process, all cells inside the polygon or touched by the polygon edges are returned; other cells within the MBR of the geometry object are clipped, that is, filled by the specified or default bgValues parameter values.

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.

inGeoRaster and outGeoRaster must be different GeoRaster objects.

Only the overlapping portion of the specified window of interest and the source GeoRaster object's spatial extent is copied.

If you want to reproject the output GeoRaster object to a different coordinate system, use the SDO_GEOR.rectify or SDO_GEOR.reproject procedure.

An exception is raised if one or more of the following are true:

inGeoRaster is invalid.
outGeoRaster has not been initialized.
A raster data table for outGeoRaster does not exist and outGeoRaster is not a blank GeoRaster object.
The specified window of interest falls outside of the GeoRaster object's spatial extent.

Examples

The following example creates a GeoRaster object that contains only specified bands from a specified window from the original object. (It refers to a table named GEORASTER_TABLE, whose definition is presented after Example 1-1 in Storage Parameters.)

DECLARE
  gr1 sdo_georaster;
  gr2 sdo_georaster;
BEGIN
  INSERT INTO georaster_table (georid, georaster)
    VALUES (41, sdo_geor.init('RDT_1'))
    RETURNING georaster INTO gr2;

  SELECT georaster INTO gr1 FROM georaster_table WHERE georid=4;

  sdo_geor.subset(gr1, sdo_geometry(2003, NULL, NULL,
                               sdo_elem_info_array(1, 1003, 3),
                               sdo_ordinate_array(0,256,255,511)),
                  '3,1-2', null, gr2);
  UPDATE georaster_table SET georaster=gr2 WHERE georid=41;
  COMMIT;
END;
/

The following example demonstrates how to do clipping while subsetting a GeoRaster object using a polygon. (It refers to a table named GEORASTER_TABLE, whose definition is presented after Example 1-1 in Storage Parameters.)

DECLARE
  gr sdo_georaster;
  grsub sdo_georaster;
  win1 sdo_geometry;
BEGIN
  Delete from georaster_table where georid = 111;
  INSERT INTO georaster_table VALUES (111, 'ClippedImage', 
     sdo_geor.init('georaster_RDT', 111))
     RETURNING georaster INTO grsub;
  SELECT georaster INTO gr FROM georaster_table WHERE georid=1;
  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.subset(gr, 0, win1, '1-3', 
                  'interleaving = BIL, compression=DEFLATE',
                  grsub, NULL, 'TRUE');
  UPDATE georaster_table SET georaster=grsub WHERE georid=111;
  COMMIT;
END;
/