SDO_GEOR_RA.findCells

Format

SDO_GEOR_AGGR.findCells(
     inGeoRaster   IN SDO_GEORASTER, 
     condition     IN VARCHAR2, 
     storageParam  IN VARCHAR2 DEFAULT NULL,
     outGeoRaster  OUT SDO_GEORASTER, 
     bgValues      IN SDO_NUMBER_ARRAY DEFAULT NULL, 
     nodata        IN VARCHAR2 DEFAULT 'FALSE', 
     parallelParam IN VARCHAR2 DEFAULT NULL);

or

SDO_GEOR_AGGR.findCells(
     inGeoRaster   IN SDO_GEORASTER, 
     cropArea      IN SDO_NUMBER_ARRAY, 
     condition     IN VARCHAR2, 
     storageParam  IN VARCHAR2 DEFAULT NULL,
     outGeoRaster  OUT SDO_GEORASTER, 
     bgValues      IN SDO_NUMBER_ARRAY DEFAULT NULL, 
     nodata        IN VARCHAR2 DEFAULT 'FALSE', 
     parallelParam IN VARCHAR2 DEFAULT NULL);

SDO_GEOR_AGGR.findCells(
     inGeoRaster   IN SDO_GEORASTER, 
     cropArea      IN SDO_GEOMETRY, 
     condition     IN VARCHAR2, 
     storageParam  IN VARCHAR2 DEFAULT NULL,
     outGeoRaster  OUT SDO_GEORASTER, 
     bgValues      IN SDO_NUMBER_ARRAY DEFAULT NULL, 
     nodata        IN VARCHAR2 DEFAULT 'FALSE', 
     polygonClip   IN VARCHAR2 DEFAULT 'FALSE', 
     parallelParam IN VARCHAR2 DEFAULT NULL);

or

SDO_GEOR_AGGR.findCells(
     inGeoRaster  IN SDO_GEORASTER,
     cropArea     IN SDO_GEOMETRY,
     condition    IN VARCHAR2,
     storageParam IN VARCHAR2 DEFAULT NULL,
     rasterBlob   IN OUT BLOB,
     outArea      OUT SDO_GEOMETRY,
     outWindow    OUT SDO_NUMBER_ARRAY,
     bgValues     IN SDO_NUMBER_ARRAY DEFAULT NULL,
     nodata       IN VARCHAR2 DEFAULT ‘FALSE’;

SDO_GEOR_AGGR.findCells(
     inGeoRaster  IN SDO_GEORASTER,
     cropArea     IN SDO_GEOMETRY,
     condition    IN VARCHAR2,
     storageParam IN VARCHAR2 DEFAULT NULL,
     rasterBlob   IN OUT BLOB,
     outArea      OUT SDO_GEOMETRY,
     outWindow    OUT SDO_NUMBER_ARRAY,
     bgValues     IN SDO_NUMBER_ARRAY DEFAULT NULL,
     nodata       IN VARCHAR2 DEFAULT ‘FALSE’,
     polygonClip  IN VARCHAR2 DEFAULT ‘FALSE’);

Description

Generates a new raster either in a GeoRaster object or a single BLOB based on the input GeoRaster object, but masking all cells that do not satisfy the condition parameter specification.

Parameters

inGeoRaster

Input GeoRaster object.

cropArea

Crop area definition. If the data type is SDO_GEOMETRY, the minimum bounding rectangle (MBR) of the geometry object is used as a rectangular crop area to generate the output GeoRaster object; see also the Usage Notes for SDO_GEOR.reproject for SDO_SRID requirements.. If the parameter polygonClip is TRUE, then only cells within the crop area geometry are processed, and all cells outside the crop area geometry are set to zero (0). If the parameter polygonClip is FALSE, then all cells within the minimum bounding rectangle are processed.

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.

condition

An expression string used to filter out cells. (See the Usage Notes for more information.).

storageParam

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

outGeoRaster

Output GeoRaster object.

rasterBlob

BLOB to hold the output of the processing result. It must exist or have been initialized before the operation.

outArea

An SDO_GEOMETRY object containing the MBR (minimum bounding rectangle) in the model coordinate system of the resulting object.

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.

bgValues

Background values to represent values of cells in the empty raster blocks of the input GeoRaster object. 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.

nodata

The string TRUE means that the original values for any NODATA cells in the GeoRaster object are kept, and NODATA values are considered in the condition parameter evaluation. If any cell value involved in the condition parameter evaluation has a NODATA value, the condition parameter is evaluated as FALSE (see the Usage Notes regarding the condition parameter). The string FALSE (the default) causes cells with NODATA values to be considered as regular data. NODATA values and value ranges are discussed in NODATA Values and Value Ranges.

polygonClip

Ignored if cropArea is null. Otherwise, the string TRUE causes the cropArea geometry to be used to process the data; the string FALSE or a null value causes the minimum bounding rectangle (MBR) of thecropArea geometry to be used to process the data.

parallelParam

Specifies the degree of parallelism for the operation. If specified, must be in the form parallel=n, where n is greater than 1. The database optimizer uses the degree of parallelism specified by this parameter. If not specified, then by default there is no parallel processing. (For more information, see Parallel Processing in GeoRaster.)

Specifying parallelParam means that you cannot roll back the results of this procedure, as explained in the Usage Notes.

Usage Notes

This procedure generates a new raster either in a GeoRaster object or a single BLOB based on the input GeoRaster object and the condition parameter, which is booleanExpr, a Boolean expression string. For each cell in the output GeoRaster object, condition is evaluated against corresponding cell values in the input GeoRaster object. If condition is true for a cell, the original cell value is kept in the output GeoRaster object; otherwise, bgValues are filled for the cell in the output GeoRaster object

For more information, see Raster Algebra Language.

If you specify parallelParam, some execution units of the procedure run as autonomous transactions, which means that some changes are committed while the procedure is running and therefore you cannot roll back those changes. If you do not specify this parameter, you can roll back all changes.

Examples

The following example changes cell values to default background values 0, if cell value of the second layer is less than or equal to 200.

DECLARE
  geor  SDO_GEORASTER;
  geor1 SDO_GEORASTER;
BEGIN
  select georaster into geor from georaster_table where georid = 1;
  insert into georaster_table values (5, sdo_geor.init('rdt_1', 5)) returning georaster into geor1;
  sdo_geor_ra.findcells(geor, '{1}>200',null,geor1);
  update georaster_table set georaster = geor1 where georid = 5;
  commit;
END;
/

The following example changes cell values to default background values 0, if cell value of the second layer is less than or equal to 200. The output is in a BLOB..

DECLARE
  geor  SDO_GEORASTER;
  out_lob    BLOB;
  outArea    sdo_geometry;
  outWindow  sdo_number_array; 
BEGIN
  select georaster into geor from georaster_table where georid = 1;
  dbms_lob.create_temporary(out_lob, TRUE);  
  sdo_geor_ra.findcells(geor, '{1}>200',null,out_lob, outArea, outWindow);
  if outWindow is not null then
     dbms_output.put_line('output window: (' || outWindow(1) || ',' ||
                           outWindow(2) || ',' || outWindow(3) || ',' || outWindow(4) || ')');
  end if;
  dbms_lob.freeTemporary(out_lob);
END;
/

The following example uses a geometry object (geom) as the input cropArea.

DECLARE
  geor       SDO_GEORASTER;
  geor0      SDO_GEORASTER;
  geor1      SDO_GEORASTER;
  geom       SDO_GEOMETRY;
BEGIN
  geom:= sdo_geometry(2003,82394, NULL,
                         sdo_elem_info_array(1, 1003, 1),
                         sdo_ordinate_array(21783.775, 1008687.9,
                                           18783.775, 966687.905,
                                           63783.775, 966687.905,
                                           81783.775, 990687.905,
                                           21783.775, 1008687.9));
  select georaster into geor from georaster_table where georid = 100;
  select georaster into geor1 from georaster_table where georid = 101 for update;
  sdo_geor_ra.findcells(geor,geom,'({1}=42)','blocking=true, blocksize=(256,256,3)',geor1,null,'false');
  update georaster_table set georaster = geor1 where georid = 101;
END;
/