SDO_GEOR_RA.rasterUpdate

Format

SDO_GEOR_RA.rasterUpdate(
     geoRaster     IN OUT SDO_GEORASTER, 
     pyramidLevel  IN NUMBER, 
     conditions    IN SDO_STRING2_ARRAY, 
     vals          IN SDO_STRING2_ARRAYSET, 
     bgValues      IN SDO_NUMBER_ARRAY DEFAULT NULL, 
     nodata        IN VARCHAR2 DEFAULT 'FALSE', 
     parallelParam IN VARCHAR2 DEFAULT NULL);

or

SDO_GEOR_RA.rasterUpdate(
     geoRaster     IN OUT SDO_GEORASTER, 
     pyramidLevel  IN NUMBER, 
     targetArea    IN SDO_NUMBER_ARRAY, 
     conditions    IN SDO_STRING2_ARRAY, 
     vals          IN SDO_STRING2_ARRAYSET, 
     bgValues      IN SDO_NUMBER_ARRAY DEFAULT NULL, 
     nodata        IN VARCHAR2 DEFAULT 'FALSE', 
     parallelParam IN VARCHAR2 DEFAULT NULL);

or

SDO_GEOR_RA.rasterUpdate(
     geoRaster     IN OUT SDO_GEORASTER, 
     pyramidLevel  IN NUMBER, 
     targetArea    IN SDO_GEOMETRY, 
     conditions    IN SDO_STRING2_ARRAY, 
     vals          IN SDO_STRING2_ARRAYSET, 
     bgValues      IN SDO_NUMBER_ARRAY DEFAULT NULL, 
     nodata        IN VARCHAR2 DEFAULT 'FALSE', 
     polygonClip   IN VARCHAR2 DEFAULT 'FALSE',
     parallelParam IN VARCHAR2 DEFAULT NULL);

Description

Updates all cells for which the conditions specification is true, using values calculated from the vals specification.

Parameters

geoRaster

GeoRaster object that is used for input and for output (updating based on specified conditions).

pyramidLevel

Pyramid level to be updated. If this parameter is null, all pyramid levels are updated.

targetArea

Target area definition. If the data type is SDO_GEOMETRY, then if the parameter polygonClip is TRUE, only cells within the target area geometry are updated, and all cells outside the target area geometry keep original values; but if the parameter polygonClip is FALSE, all cells in the MBR of the target area geometry are updated.

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.

conditions

An array of booleanExpr expression strings used to select cells. (See the Usage Notes for more information.) The data type is SDO_STRING2_ARRAY, which is defined as VARRAY(2147483647) OF VARCHAR2(4096).

vals

An array or arrays of arithmeticExpr expressions, with the outer array corresponding to each condition and the inner array corresponding to each layer. The data type is SDO_STRING2_ARRAYSET, which is defined as VARRAY(2147483647) OF SDO_STRING2_ARRAY.

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 not to be updated, and NODATA values are considered in the conditions parameter evaluation. If any cell value involved in the conditions parameter evaluation has a NODATA value, the conditions parameter is evaluated as FALSE (See the Usage Notes regarding the conditions parameter). The string FALSE (the default) causes cells with NODATA values to be considered as regular cells and thus eligible for updating. NODATA values and value ranges are discussed in NODATA Values and Value Ranges.

polygonClip

Ignored if targetArea is null. Otherwise, the string TRUE causes the targetArea geometry value to be used to update raster cell values; the string FALSE or a null value causes the MBR of targetArea geometry to be used to update raster cell values.

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

Because this procedure overwrites data in the input GeoRaster object, you should make a copy of the original GeoRaster object and use this procedure on the copied object. After you are satisfied with the result of this procedure, you can discard the original GeoRaster object if you wish.

This procedure selects cells from the specified GeoRaster object based on booleanExpr strings specified in the conditions parameter, and updates corresponding cell values by calculating arithmeticExpr expression strings specified in the vals parameter. For example, if:

conditions = SDO_STRING2_ARRAY('{0}=48','{0}=108')
vals = SDO_STRING2_ARRAYSET(SDO_STRING2_ARRAY('123','54','89'),SDO_STRING2_ARRAY('98','56','123'))

Then:

For all cells whose first layer value equals 48, their first, second, and third layer values are set to 123,54,89, respectively.
For all cells whose first layer value equals 108, their first, second, and third layer values are set to 98,56,123, respectively.

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 updates all cells for which the conditions specification is true, using values calculated from the vals specification.

DECLARE 
  geor SDO_GEORASTER;
BEGIN
  select georaster into geor from georaster_table where georid = 1;
  sdo_geor_ra.rasterUpdate(geor,0,SDO_STRING2_ARRAY('(abs({0}-{1})=48)&({2}-{1}=-101)','2*{0}-{1}/3=108'),SDO_STRING2_ARRAYSET(SDO_STRING2_ARRAY('123','54','89'),SDO_STRING2_ARRAY('98','56','123')));
END;
/