The SDO_GEOR_RA package contains subprograms (functions and procedures) for raster algebra and analytic operations related to GeoRaster. This chapter presents reference information, with one or more examples, for each subprogram.
SDO_GEOR_RA.classify(
inGeoRaster IN SDO_GEORASTER,
expresssion IN VARCHAR2,
rangeArray IN SDO_NUMBER_ARRAY,
valueArray IN SDO_NUMBER_ARRAY,
storageParam IN VARCHAR2,
outGeoRaster IN OUT SDO_GEORASTER,
nodata IN VARCHAR2 DEFAULT 'FALSE',
nodataValue IN NUMBER DEFAULT 0,
parallelParam IN VARCHAR2 DEFAULT NULL);
or
SDO_GEOR_RA.classify(
georArray IN SDO_GEORASTER_ARRAY,
expresssion IN VARCHAR2,
rangeArray IN SDO_NUMBER_ARRAY,
valueArray IN SDO_NUMBER_ARRAY,
storageParam IN VARCHAR2,
outGeoRaster IN OUT SDO_GEORASTER,
nodata IN VARCHAR2 DEFAULT 'FALSE',
nodataValue IN NUMBER DEFAULT 0,
parallelParam IN VARCHAR2 DEFAULT NULL);
or
SDO_GEOR_RA.classify(
inGeoRasters IN SYS_REFCURSOR,
expresssion IN VARCHAR2,
rangeArray IN SDO_NUMBER_ARRAY,
valueArray IN SDO_NUMBER_ARRAY,
storageParam IN VARCHAR2,
outGeoRaster IN OUT SDO_GEORASTER,
nodata IN VARCHAR2 DEFAULT 'FALSE',
nodataValue IN NUMBER DEFAULT 0,
parallelParam IN VARCHAR2 DEFAULT NULL);
Generates a new GeoRaster object after applying the specified classification operation on the input GeoRaster object or objects.
Input GeoRaster object.
An array of GeoRaster objects. The data type is SDO_GEOR_ARRAY, which is defined as VARRAY(10485760) OF SDO_GEORASTER. The maximum number of GeoRaster objects in the array is 8, but there is no limit on the total number of layers for all the GeoRaster objects.
Cursor (SYS_REFCURSOR type) for the input GeoRaster objects. The maximum number of GeoRaster objects in the cursor is 8, but there is no limit on the total number of layers for all the GeoRaster objects.
An arithmetic expression used to classify cell values. See the Usage Notes for more information about specifying this parameter.
A number array that defines ranges for classifying cell values. The array must contain at least one element.
A number array that defines the target cell value for each range. The number of elements must be 1 greater than the elements in rangeArray (that is, its length must be rangeArray+1).
A string specifying storage parameters, as explained in Section 1.4.1.
Output GeoRaster object.
The string TRUE specifies that for any NODATA cells in an input GeoRaster object, the corresponding cells in the output GeoRaster object are to be set to the value specified for the nodataValue 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 Section 1.10.
The value used to set NODATA cells if the nodata parameter value is the string TRUE.
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 Section 1.13, "Parallel Processing in GeoRaster".)
Specifying parallelParam means that you cannot roll back the results of this procedure, as explained in the Usage Notes.
This procedure generates a one-layer GeoRaster object based on the input GeoRaster object or objects and the expression parameter, which is an arithmetic expression string. For each cell in the output GeoRaster object, expression is evaluated against corresponding cell values in the input GeoRaster object, and the following algorithm is used to calculate cell values of the output GeoRaster object:
if (value of expression < rangeArray[0]) cellValue=valueArray[0] else if (value of expression >= rangeArray[n-1]) cellValue=valueArray[n] else if rangeArray[m-1] <= value of expression < rangeArray[m] cellValue=valueArray[m]
In the expression calculation:
Length of rangeArray is n
Length of valueArray is n+1
0 < m < n-1
For more information, see Section 4.1, "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.
The following example classifies cell values based on the cell values of the first layer.
DECLARE
geor SDO_GEORASTER;
geor1 SDO_GEORASTER;
rangeArray SDO_NUMBER_ARRAY;
valueArray SDO_NUMBER_ARRAY;
BEGIN
rangeArray:=sdo_number_array(70,80,90,100,110,120,130,140,150,160,170,180);
valueArray:=sdo_number_array(70,80,90,100,110,120,130,140,150,160,170,180,190);
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.classify(geor,'{0}',rangeArray,valueArray,null,geor1);
update georaster_table set georaster = geor1 where georid = 5;
commit;
END;
/
SDO_GEOR_AGGR.findCells(
inGeoRaster IN SDO_GEORASTER,
condition IN VARCHAR2,
storageParam IN VARCHAR2
outGeoRaster OUT SDO_GEORASTER,
bgValues IN SDO_NUMBER_ARRAY DEFAULT NULL,
nodata IN VARCHAR2 DEFAULT 'FALSE',
parallelParam IN VARCHAR2 DEFAULT NULL);
Generates a new GeoRaster object based on the input GeoRaster object, but masking all cells that do not satisfy the condition parameter specification.
Input GeoRaster object.
An expression string used to filter out cells. (See the Usage Notes for more information.).
A string specifying storage parameters, as explained in Section 1.4.1.
Output GeoRaster object.
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.
The string TRUE specifies to keep the original values for any NODATA cells in the GeoRaster object. The string FALSE (the default) causes cells with NODATA values to be considered as regular data. NODATA values and value ranges are discussed in Section 1.10.
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 Section 1.13, "Parallel Processing in GeoRaster".)
Specifying parallelParam means that you cannot roll back the results of this procedure, as explained in the Usage Notes.
This procedure generates a new GeoRaster object 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 Section 4.1, "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.
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;
/
SDO_GEOR.isOverlap(
georaster1 IN SDO_GEORASTER,
georaster2 IN SDO_GEORASTER,
tolerance IN NUMBER DEFAULT 0.5
) RETURN VARCHAR2;
or
SDO_GEOR_RA.isOverlap(
georArray IN SDO_GEORASTER_ARRAY,
tolerance IN NUMBER DEFAULT 0.5
) RETURN VARCHAR2;
or
SDO_GEOR_RA.isOverlap(
geor_cur IN SYS_REFCURSOR,
tolerance IN NUMBER DEFAULT 0.5
) RETURN VARCHAR2;
Returns the string TRUE if two or more GeoRaster objects overlap, or FALSE if two or more GeoRaster objects do not overlap. (See the Usage Notes for the logic used to determine of two GeoRaster objects, whether georeferenced or not, overlap.)
GeoRaster object.
GeoRaster object.
An array of GeoRaster objects. The data type is SDO_GEOR_ARRAY, which is defined as VARRAY(10485760) OF SDO_GEORASTER.
Cursor (SYS_REFCURSOR type) for the input GeoRaster objects.
Tolerance value used to determine if two cells in the cell space overlap in the model space. The value should be between 0 and 1, and the unit is cell. For example, 0.5 (the default) means one-half cell, namely, that two cells overlap if the distance between them in 0.5 cell or less.
The GeoRaster objects being compared for overlap must be either all georeferenced or all non-georeferenced.
The following logic is applied to determine if two GeoRaster objects overlap:
If the row or column dimension size of two GeoRaster objects is different, then return 'FALSE'. Otherwise, continue to the next step.
Check if both GeoRaster objects are georeferenced.
If one is georeferenced and the other one is not, then return 'FALSE'.
If both are non-georeferenced, and if the ultCoordinate of both GeoRaster objects is the same, then return 'TRUE'; else, return 'FALSE'.
If both are georeferenced, go to the next step.
Check the pType, nVars, order, and nCoefficients values (explained in Section 1.6.1, "Functional Fitting Georeferencing Model") of the p, q, r, and s polynomials. If any are different, then return 'FALSE'; else, go to the next step.
Calculate the upper-left, upper-right, lower-left, and lower-right four points from cell space to model space. If the distance of corresponding points of the two GeoRaster objects is within the tolerance value (converted from cell space to model space), then return 'TRUE'; else, return 'FALSE'.
The raster algebra functions of GeoRaster require the raster layers from different GeoRaster objects have the same size and completely overlap each other. Before you apply raster algebra operations over two or more GeoRaster objects or perform other operations, you can use the SDO_GEOR_RA.isOverlap function to determine if the GeoRaster objects are of the same size and cover the same ground area.
The following examples check if two GeoRaster objects overlap. (They use two different formats of the function.)
DECLARE
geor MDSYS.SDO_GEORASTER;
geor1 MDSYS.SDO_GEORASTER;
BEGIN
SELECT georaster INTO geor FROM georaster_table WHERE georid = 1;
SELECT georaster INTO geor1 FROM georaster_table WHERE georid = 30;
dbms_output.put_line(sdo_geor_ra.isOverlap(geor,geor1,0.5));
END;
/
DECLARE
mycursor sys_refcursor;
BEGIN
OPEN mycursor FOR
SELECT georaster FROM georaster_table WHERE georid = 1 or georid=30;
dbms_output.put_line(sdo_geor_ra.isOverlap(mycursor,0.5));
END;
/
SDO_GEOR_RA.rasterMathOp(
inGeoRaster IN SDO_GEORASTER,
operation IN SDO_STRING2_ARRAY,
storageParam IN VARCHAR2,
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,
operation IN SDO_STRING2_ARRAY,
storageParam IN VARCHAR2,
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,
operation IN SDO_STRING2_ARRAY,
storageParam IN VARCHAR2,
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(
georaster0 IN SDO_GEORASTER,
georaster1 IN SDO_GEORASTER,
constant IN NUMBER,
operator IN PLS_INTEGER,
storageParam IN VARCHAR2,
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);
The first three formats generate a new GeoRaster object from layers of one or more input GeoRaster objects based on the operation parameter specification. The last format applies a mathematical operation on all corresponding cells of each layer of one or two input GeoRaster objects.
Input GeoRaster object.
An array of GeoRaster objects. The data type is SDO_GEOR_ARRAY, which is defined as VARRAY(10485760) OF SDO_GEORASTER. The maximum number of GeoRaster objects in the array is 8, but there is no limit on the total number of layers for all the GeoRaster objects.
Cursor (SYS_REFCURSOR type) for the input GeoRaster objects. The maximum number of GeoRaster objects in the cursor is 8, but there is no limit on the total number of layers for all the GeoRaster objects.
The left operand.
The right operand.
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 as VARRAY(2147483647) OF VARCHAR2(4096).
The syntax for the arithmeticExpr expressions is explained in Section 4.1, "Raster Algebra Language".
Constant value for some operators (see the operator parameter), such as addConst and divConstant.
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.
A string specifying storage parameters, as explained in Section 1.4.1.
Output GeoRaster object.
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.
The string TRUE specifies that for any NODATA cells in an input GeoRaster object, the corresponding cells in the output GeoRaster object are to be set to the value specified for the nodataValue 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 Section 1.10.
The value used to set NODATA cells if the nodata parameter value is the string TRUE.
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 Section 1.13, "Parallel Processing in GeoRaster".)
Specifying parallelParam means that you cannot roll back the results of this procedure, as explained in the Usage Notes.
The first three formats are used to generate a new GeoRaster object 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 format 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 format, all pyramids are removed in the resulting GeoRaster object, but masks of the first input GeoRaster object are kept in the resulting GeoRaster object.
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 Section 4.1.
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.
The following example adds the constant 10 to all cell values of the input 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 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;
/
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);
Updates all cells for which the conditions specification is true, using values calculated from the vals specification.
GeoRaster object that is used for input and for output (updating based on specified conditions).
Pyramid level to be updated. If this parameter is null, all pyramid levels are updated.
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).
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.
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.
The string TRUE specifies that any NODATA cells in the GeoRaster object are not to be updated. 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 Section 1.10.
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 Section 1.13, "Parallel Processing in GeoRaster".)
Specifying parallelParam means that you cannot roll back the results of this procedure, as explained in the 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 Section 4.1, "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.
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;
/