12.6 SDO_GEOR_RA.rasterMathOp
Format
Operation on a Single GeoRaster Object
SDO_GEOR_RA.rasterMathOp( inGeoRaster IN SDO_GEORASTER, operation IN SDO_STRING2_ARRAY, storageParam IN VARCHAR2 DEFAULT NULL, outGeoRaster IN OUT SDO_GEORASTER, nodata IN VARCHAR2 DEFAULT 'FALSE', nodataValue IN NUMBER DEFAULT 0, parallelParam IN VARCHAR2 DEFAULT NULL);
or
SDO_GEOR_RA.rasterMathOp( inGeoRaster IN SDO_GEORASTER, cropArea IN SDO_NUMBER_ARRAY, operation IN SDO_STRING2_ARRAY, storageParam IN VARCHAR2 DEFAULT NULL, outGeoRaster IN OUT SDO_GEORASTER, nodata IN VARCHAR2 DEFAULT 'FALSE', nodataValue IN NUMBER DEFAULT 0, parallelParam IN VARCHAR2 DEFAULT NULL);
SDO_GEOR_RA.rasterMathOp( inGeoRaster IN SDO_GEORASTER, cropArea IN SDO_GEOMETRY, operation IN SDO_STRING2_ARRAY, storageParam IN VARCHAR2 DEFAULT NULL, outGeoRaster IN OUT SDO_GEORASTER, nodata IN VARCHAR2 DEFAULT 'FALSE', nodataValue IN NUMBER DEFAULT 0, polygonClip IN VARCHAR2 DEFAULT 'FALSE', parallelParam IN VARCHAR2 DEFAULT NULL);
or
SDO_GEOR_RA.rasterMathOp( inGeoRaster IN SDO_GEORASTER, cropArea IN SDO_GEOMETRY, operation IN SDO_STRING2_ARRAY, storageParam IN VARCHAR2 DEFAULT NULL, rasterBlob IN OUT BLOB, outArea OUT SDO_GEOMETRY, outWindow OUT SDO_NUMBER_ARRAY, nodata IN VARCHAR2 DEFAULT ‘FALSE’, nodataValue IN NUMBER default 0;
SDO_GEOR_RA.rasterMathOp( inGeoRaster IN SDO_GEORASTER, cropArea IN SDO_GEOMETRY, operation IN SDO_STRING2_ARRAY, storageParam IN VARCHAR2 DEFAULT NULL, rasterBlob IN OUT BLOB, outArea OUT SDO_GEOMETRY, outWindow OUT SDO_NUMBER_ARRAY, nodata IN VARCHAR2 DEFAULT ‘FALSE’, nodataValue IN NUMBER default 0, polygonClip IN VARCHAR2 DEFAULT ‘FALSE’);
Operation on an Array of GeoRaster Objects
SDO_GEOR_RA.rasterMathOp( georArray IN SDO_GEORASTER_ARRAY, operation IN SDO_STRING2_ARRAY, storageParam IN VARCHAR2 DEFAULT NULL, outGeoRaster IN OUT SDO_GEORASTER, nodata IN VARCHAR2 DEFAULT 'FALSE', nodataValue IN NUMBER DEFAULT 0, parallelParam IN VARCHAR2 DEFAULT NULL);
or
SDO_GEOR_RA.rasterMathOp( georArray IN SDO_GEORASTER_ARRAY, cropArea IN SDO_NUMBER_ARRAY, operation IN SDO_STRING2_ARRAY, storageParam IN VARCHAR2 DEFAULT NULL, outGeoRaster IN OUT SDO_GEORASTER, nodata IN VARCHAR2 DEFAULT 'FALSE', nodataValue IN NUMBER DEFAULT 0, parallelParam IN VARCHAR2 DEFAULT NULL);
SDO_GEOR_RA.rasterMathOp( georArray IN SDO_GEORASTER_ARRAY, cropArea IN SDO_GEOMETRY, operation IN SDO_STRING2_ARRAY, storageParam IN VARCHAR2 DEFAULT NULL, outGeoRaster IN OUT SDO_GEORASTER, nodata IN VARCHAR2 DEFAULT 'FALSE', nodataValue IN NUMBER DEFAULT 0, polygonClip IN VARCHAR2 DEFAULT 'FALSE', parallelParam IN VARCHAR2 DEFAULT NULL);
or
SDO_GEOR_RA.rasterMathOp( georArray IN SDO_GEORASTER_ARRAY, cropArea IN SDO_GEOMETRY, operation IN SDO_STRING2_ARRAY, storageParam IN VARCHAR2 DEFAULT NULL, rasterBlob IN OUT BLOB, outArea OUT SDO_GEOMETRY, outWindow OUT SDO_NUMBER_ARRAY, nodata IN VARCHAR2 DEFAULT ‘FALSE’, nodataValue IN NUMBER default 0;
SDO_GEOR_RA.rasterMathOp( georArray IN SDO_GEORASTER_ARRAY, cropArea IN SDO_GEOMETRY, operation IN SDO_STRING2_ARRAY, storageParam IN VARCHAR2 DEFAULT NULL, rasterBlob IN OUT BLOB, outArea OUT SDO_GEOMETRY, outWindow OUT SDO_NUMBER_ARRAY, nodata IN VARCHAR2 DEFAULT ‘FALSE’, nodataValue IN NUMBER default 0, polygonClip IN VARCHAR2 DEFAULT ‘FALSE’);
Operation on GeoRaster Objects Specified by a Cursor
SDO_GEOR_RA.rasterMathOp( inGeoRasters IN SYS_REFCURSOR, operation IN SDO_STRING2_ARRAY, storageParam IN VARCHAR2 DEFAULT NULL, outGeoRaster IN OUT SDO_GEORASTER, nodata IN VARCHAR2 DEFAULT 'FALSE', nodataValue IN NUMBER DEFAULT 0, parallelParam IN VARCHAR2 DEFAULT NULL);
or
SDO_GEOR_RA.rasterMathOp( inGeoRasters IN SYS_REFCURSOR, cropArea IN SDO_NUMBER_ARRAY, operation IN SDO_STRING2_ARRAY, storageParam IN VARCHAR2 DEFAULT NULL, outGeoRaster IN OUT SDO_GEORASTER, nodata IN VARCHAR2 DEFAULT 'FALSE', nodataValue IN NUMBER DEFAULT 0, parallelParam IN VARCHAR2 DEFAULT NULL);
SDO_GEOR_RA.rasterMathOp( inGeoRasters IN SYS_REFCURSOR, cropArea IN SDO_GEOMETRY, operation IN SDO_STRING2_ARRAY, storageParam IN VARCHAR2 DEFAULT NULL, outGeoRaster IN OUT SDO_GEORASTER, nodata IN VARCHAR2 DEFAULT 'FALSE', nodataValue IN NUMBER DEFAULT 0, polygonClip IN VARCHAR2 DEFAULT 'FALSE', parallelParam IN VARCHAR2 DEFAULT NULL);
or
SDO_GEOR_RA.rasterMathOp( inGeoRasters IN SYS_REFCURSOR, cropArea IN SDO_GEOMETRY, operation IN SDO_STRING2_ARRAY, storageParam IN VARCHAR2 DEFAULT NULL, rasterBlob IN OUT BLOB, outArea OUT SDO_GEOMETRY, outWindow OUT SDO_NUMBER_ARRAY, nodata IN VARCHAR2 DEFAULT ‘FALSE’, nodataValue IN NUMBER default 0;
SDO_GEOR_RA.rasterMathOp( inGeoRasters IN SYS_REFCURSOR, cropArea IN SDO_GEOMETRY, operation IN SDO_STRING2_ARRAY, storageParam IN VARCHAR2 DEFAULT NULL, rasterBlob IN OUT BLOB, outArea OUT SDO_GEOMETRY, outWindow OUT SDO_NUMBER_ARRAY, nodata IN VARCHAR2 DEFAULT ‘FALSE’, nodataValue IN NUMBER default 0, polygonClip IN VARCHAR2 DEFAULT ‘FALSE’);
Operation on All Corresponding Cells of Each Layer
SDO_GEOR_RA.rasterMathOp( georaster0 IN SDO_GEORASTER, georaster1 IN SDO_GEORASTER, constant IN NUMBER, operator IN PLS_INTEGER, storageParam IN VARCHAR2 DEFAULT NULL, outGeoRaster IN OUT SDO_GEORASTER, bgValues IN SDO_NUMBER_ARRAY DEFAULT NULL, nodata IN VARCHAR2 DEFAULT 'FALSE', nodataValue IN NUMBER DEFAULT 0, parallelParam IN VARCHAR2 DEFAULT NULL);
or
SDO_GEOR_RA.rasterMathOp( georaster0 IN SDO_GEORASTER, georaster1 IN SDO_GEORASTER, cropArea IN SDO_NUMBER_ARRAY, constant IN NUMBER, operator IN PLS_INTEGER, storageParam IN VARCHAR2 DEFAULT NULL, outGeoRaster IN OUT SDO_GEORASTER, bgValues IN SDO_NUMBER_ARRAY DEFAULT NULL, nodata IN VARCHAR2 DEFAULT 'FALSE', nodataValue IN NUMBER DEFAULT 0, parallelParam IN VARCHAR2 DEFAULT NULL);
SDO_GEOR_RA.rasterMathOp( georaster0 IN SDO_GEORASTER, georaster1 IN SDO_GEORASTER, cropArea IN SDO_GHEOMETRY, constant IN NUMBER, operator IN PLS_INTEGER, storageParam IN VARCHAR2 DEFAULT NULL, outGeoRaster IN OUT SDO_GEORASTER, bgValues IN SDO_NUMBER_ARRAY DEFAULT NULL, nodata IN VARCHAR2 DEFAULT 'FALSE', nodataValue IN NUMBER DEFAULT 0, polygonClip IN VARCHAR2 DEFAULT 'FALSE', parallelParam IN VARCHAR2 DEFAULT NULL);
or
SDO_GEOR_RA.rasterMathOp( georaster0 IN SDO_GEORASTER, georaster1 IN SDO_GEORASTER, cropArea IN SDO_GEOMETRY, constant IN NUMBER, operator IN PLS_INTEGER, 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’, nodataValue IN NUMBER default 0;
SDO_GEOR_RA.rasterMathOp( georaster0 IN SDO_GEORASTER, georaster1 IN SDO_GEORASTER, cropArea IN SDO_GEOMETRY, constant IN NUMBER, operator IN PLS_INTEGER, 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’, nodataValue IN NUMBER default 0, polygonClip IN VARCHAR2 DEFAULT ‘FALSE’);
Description
Performs a raster algebra operation on one or more GeoRaster objects, including general mathematical, statistical, casting, logical, and relational operations or combinations of them.
Parameters
- inGeoRaster
-
Input GeoRaster object.
- georArray
-
An array of GeoRaster objects. The data type is SDO_GEOR_ARRAY, which is defined as
VARRAY(10485760) OF SDO_GEORASTER
. - inGeoRasters
-
Cursor (SYS_REFCURSOR type) for the input GeoRaster objects.
- georaster0
-
The left operand.
- georaster1
-
The right operand.
- 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. If the parameter
polygonClip
isTRUE
, then only cells within the crop area geometry are processed, and all cells outside the crop area geometry are set to zero (0). See also the Usage Notes for SDO_GEOR.reproject for SDO_SRID requirements.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.
- operation
-
An array of
arithmeticExpr
expression strings used to calculate raster cell values in the output GeoRaster object. Each element of the array corresponds to a layer in the output GeoRaster object. The data type is SDO_STRING2_ARRAY, which is defined asVARRAY(2147483647) OF VARCHAR2(4096)
.The syntax for the
arithmeticExpr
expressions is explained in Raster Algebra Language. - constant
-
Constant value for some operators (see the
operator
parameter), such asaddConst
anddivConstant
. - operator
-
One of the following math operators, which are defined in the SDO_GEOR_RA package:
OPERATOR_ABSOLUTE OPERATOR_ADD OPERATOR_ADDCONST OPERATOR_DIVIDE OPERATOR_DIVIDECONST OPERATOR_EXP OPERATOR_INVERT OPERATOR_LOG OPERATOR_MULTIPLY OPERATOR_MULTIPLYCONST OPERATOR_SUBTRACT OPERATOR_SUBTRACTCONST
For the definitions of these operators, see the Usage Notes.
- 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 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.
- nodata
-
The string
TRUE
specifies that if there are any NODATA cells in the operands of the math operation, the operation result is evaluated as a NODATA value; thus, the corresponding cells in the output GeoRaster object are to be set to the value specified for thenodataValue
parameter. The stringFALSE
(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. - nodataValue
-
The value used to set NODATA cells if the
nodata
parameter value is the stringTRUE
. - polygonClip
-
Ignored if
cropArea
is null. Otherwise, the stringTRUE
causes thecropArea
value to be used to crop the mosaicked data; the stringFALSE
or a null value causes the MBR ofcropArea
to be used to crop the output image. - 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 has 20 formats, which can be considered as 4 groups of 5 formats each:
- Operation on a single GeoRaster object
- Operation on an array of GeoRaster objects
- Operation on GeoRaster objects specified by a cursor (SYS_REFCURSOR type)
- Operation on all corresponding cells of each layer or one or two GeoRaster objects
Within each group, the options include specifying a crop areas of type SDO_NUMBER_ARRAY or SDO_GEOMETRY, and for an SDO_GEOMETRY crop area, whether to use the crop area’s geometry object or the MBR of that object. The output raster can be in a GeoRaster object or a single BLOB.
The first three groups of formats are used to generate a new raster from layers of one or more input GeoRaster objects based on the operation
parameter. For example, the following example generates a new GeoRaster object that has three layers, and each layer's value is the cell value of the input GeoRaster object minus 10:
sdo_geor_ra.rasterMathOp(geor,SDO_STRING2_ARRAY('{0,0}-10','{0,1}-10','{0,2}-10'),null,geor1);
The fourth group of formats applies a mathematical operation on all corresponding cells of each layer of input GeoRaster objects, and generates a new GeoRaster object with the same dimension size as the first input GeoRaster object (geoRaster0
). The two input GeoRaster objects must have same row/column/band dimension size.
For the fourth group of formats, when the output raster is a GeoRaster object, all pyramids are removed in the resulting GeoRaster object, but masks of the first input GeoRaster object are kept in the resulting GeoRaster object; when the output raster is in a BLOB, all pyramids and masks are removed from the output.
For the operator
parameter, the operators have the following definitions:
OPERATOR_ABSOLUTE : if (src[x][y][b] < 0) { dst[x][y][b] = -src[x][y][b]; } else { dst[x][y][b] = src[x][y][b]; } OPERATOR_ADD dst[x][y][b]=src1[x][y][b]+src2[x][y][b] OPERATOR_ADDCONST dst[x][y][b]=src[x][y][b] +constant --constant is the third parameter OPERATOR_DIVIDE dst[x][y][b]=src1[x][y][b]/src2[x][y][b] OPERATOR_DIVIDECONST dst[x][y][b]=src[x][y][b]/constant --constant is the third parameter OPERATOR_EXP dst[x][y][b]=exp(src[x][y][b]) OPERATOR_INVERT : Inverts the cell values: dst[x][y][b]=-src[x][y][b] OPERATOR_LOG : dst[x][y][b]=log(src[x][y][b]) OPERATOR_MULTIPLY dst[x][y][b]=src1[x][y][b]*src2[x][y][b] OPERATOR_MULTIPLYCONST dst[x][y][b]=src[x][y][b]*constant --constant is the third parameter OPERATOR_SUBTRACT dst[x][y][b]=src1[x][y][b]-src2[x][y][b] OPERATOR_SUBTRACTCONST dst[x][y][b]=src[x][y][b]-constant --constant is the third parameter
For more information about the raster algebra language, 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 adds the constant 10 to all cell values of the input GeoRaster object. The output is a GeoRaster object.
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.rasterMathOp(geor,null,10,sdo_geor_ra.OPERATOR_ADDCONST,null,geor1); update georaster_table set georaster = geor1 where georid = 5; commit; END; /
The following example adds the constant 10 to all cell values of the input GeoRaster object. The output is 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.rasterMathOp(geor,null,10,sdo_geor_ra.OPERATOR_ADDCONST,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 generates a new three-layer GeoRaster object from three layers of the input GeoRaster object, and each cell value in the new GeoRaster object is the value of the corresponding "old" cell divided by 2.
DECLARE geor SDO_GEORASTER; geor1 SDO_GEORASTER; geo_array SDO_GEORASTER_ARRAY; BEGIN select georaster into geor from georaster_table where georid = 2; insert into georaster_table values (20, sdo_geor.init('rdt_1', 20)) returning georaster into geor1; geo_array:=SDO_GEORASTER_ARRAY(geor); sdo_geor_ra.rasterMathOp(geo_array,SDO_STRING2_ARRAY('{0,0}/2','{0,1}/2','{0,2}/2'),null,geor1); update georaster_table set georaster = geor1 where georid = 20; commit; END; /
The following example performs a raster math operation with a geometry object as the crop area.
DECLARE geor SDO_GEORASTER; geor1 SDO_GEORASTER; geom SDO_GEOMETRY; geo_array SDO_GEORASTER_ARRAY; 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; geo_array:=SDO_GEORASTER_ARRAY(geor); mdsys.sdo_geor_ra.rasterMathOp(geo_array,geom,SDO_STRING2_ARRAY('{0,0}/2','{0,1}/2','{0,2}/2'),null,geor1); update georaster_table set georaster = geor1 where georid = 101; commit; END; /
See Also:
- Logical Operations for examples on applying raster logical operations
- Raster Data Scaling and Offsetting for examples on performing cell data scaling and offsetting operations
- Example 5-23 for mapping cell values from one data type to another using casting operations
- Example 5-24 for performing complex cartographic modeling
Parent topic: SDO_GEOR_RA Package Reference