SDO_GEOR.changeCellValues

Format

SDO_GEOR.changeCellValues(
     georaster     IN OUT SDO_GEORASTER, 
     rowNumbers    IN SDO_NUMBER_ARRAY, 
     colNumbers    IN SDO_NUMBER_ARRAY, 
     bandNumber    IN NUMBER, 
     newCellValues IN SDO_NUMBER_ARRAY, 
     bgValues      IN SDO_NUMBER_ARRAY DEFAULT NULL);

or

SDO_GEOR.changeCellValues(
     georaster     IN OUT SDO_GEORASTER, 
     ptGeom        IN SDO_GEOMETRY, 
     layerNumber   IN NUMBER, 
     newCellValues IN SDO_NUMBER_ARRAY, 
     bgValues      IN SDO_NUMBER_ARRAY DEFAULT NULL);

Description

Changes the value of raster cells specified by row/column arrays or by a multipoint geometry to new values.

Parameters

georaster

GeoRaster object.

rowNumbers

Numbers of the rows that contains the cells whose values are to be changed.

colNumbers

Numbers of the columns that contains the cells whose values are to be changed.

bandNumber

Number of the physical band that contains the cells whose value is to be changed.

ptGeom

Multipoint geometry that identifies the cells whose values are to be changed.

layerNumber

Number of the logical layer that contains the cells whose value is to be changed. (As mentioned in Bands_ Layers_ and Metadata, the logical layer number is the physical band number plus 1.)

newCellValues

The new cell value for each cell inside the window in the specified bands or layers. The value must be in the range designated by the cellDepth value for the GeoRaster object.

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.

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 can be used to mask, or conceal, parts of an image. For example, you can change irrelevant parts of an image to a dull color before displaying the image, to help people to focus on the relevant parts.

In the ptGeom SDO_GEOMETRY object, 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 ptGeom parameter geometry and the model space are different, the ptGeom 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 georaster is null, this procedure performs no operation. If georaster is invalid, an exception is raised.

If any pyramids are defined on the GeoRaster object, the corresponding cell values for the pyramids are updated.

To return the values of cells located anywhere in the GeoRaster object, use the SDO_GEOR.getCellValues function.

Examples

The following example changes the value of two cells to 151 and 152 in band number 1. (It refers to a table named GEORASTER_TABLE, whose definition is presented after Example 1-1 in Storage Parameters.)

DECLARE
  gr sdo_georaster;
BEGIN
  SELECT georaster INTO gr FROM georaster_table WHERE georid=110 FOR UPDATE;
  sdo_geor.changeCellValues(gr, sdo_number_array(100,67),sdo_number_array(134,113), 1, 
     sdo_number_array(151,152));
  UPDATE georaster_table SET georaster=gr WHERE georid=110;
  COMMIT;
END;
/