7.5 SDO_GEOR.changeCellValue
Format
SDO_GEOR.changeCellValue( georaster IN OUT SDO_GEORASTER, window IN SDO_NUMBER_ARRAY, bandNumbers IN VARCHAR2, newCellValue IN NUMBER, bgValues IN SDO_NUMBER_ARRAY DEFAULT NULL);
or
SDO_GEOR.changeCellValue( georaster IN OUT SDO_GEORASTER, window IN SDO_GEOMETRY, layerNumbers IN VARCHAR2, newCellValue IN NUMBER, bgValues IN SDO_NUMBER_ARRAY DEFAULT NULL);
Description
Changes the value of raster cells in a specified window of a GeoRaster object to a single new value.
Parameters
- georaster
-
GeoRaster object.
- window
-
Window in which to change the values of all cells to
newCellValue
. The data type can be SDO_NUMBER_ARRAY or SDO_GEOMETRY. 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, see the Usage Notes for SDO_SRID requirements and other information. - bandNumbers
-
A string identifying the physical band numbers on which the operation is 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). - layerNumbers
-
A string identifying the logical layer numbers on which the operation is 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). - newCellValue
-
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 defaultbgValues
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.
If the window
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, thewindow
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
parameter specifies a nonrectangular SDO_GEOMETRY object, this function calculates the MBR of the geometry and update the cells inside that MBR, including the cells on the boundary of the MBR.
If the window
parameter specifies a geodetic MBR, it cannot cross the date line meridian. For information about geodetic MBRs, see Oracle Spatial Developer's
Guide.
If georaster
is a blank GeoRaster object and the whole area is updated, the result is a blank GeoRaster object with the blankCellValue
value set to newCellValue
.
If georaster
is a blank GeoRaster object and it is only partially updated, the result is a nonblank GeoRaster object with the original blankCellValue
and newCellValue
values set according to the window
parameter and the bandNumbers
or layerNumbers
parameter.
If georaster
is a nonblank GeoRaster object, the result is a nonblank GeoRaster object, even if all cells are set to the newCellValue
value.
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 value of a single cell located anywhere in the GeoRaster object, use the SDO_GEOR.getCellValue function.
Examples
The following example changes the value of all cells to 151 in a specified window 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.changeCellValue(gr, sdo_number_array(100,67,134,113), '1', 151); UPDATE georaster_table SET georaster=gr WHERE georid=110; COMMIT; END; /
Parent topic: SDO_GEOR Package Reference