SDO_GEOR_IP.dodge

Format

SDO_GEOR_IP.dodge(
     inGeoRaster        IN SDO_GEORASTER, 
     gridsize           IN SDO_NUMBER_ARRAY, 
     samplingFactor     IN VARCHAR2 DEFAULT NULL, 
     means              IN SDO_NUMBER_ARRAY DEFAULT NULL,
     standardDeviations IN SDO_NUMBER_ARRAY DEFAULT NULL,
     storageParam       IN VARCHAR2 DEFAULT NULL, 
     outGeoraster       IN OUT SDO_GEORASTER,
     parallelParam      IN VARCHAR2 DEFAULT NULL);

or

SDO_GEOR_IP.dodge(
     inGeoRaster        IN SDO_GEORASTER, 
     gridsize           IN SDO_NUMBER_ARRAY, 
     samplingFactor     IN VARCHAR2 DEFAULT NULL, 
     refGeoraster       IN SDO_GEORASTER,
     standardDeviations IN SDO_NUMBER_ARRAY DEFAULT NULL,
     storageParam       IN VARCHAR2 DEFAULT NULL, 
     outGeoraster       IN OUT SDO_GEORASTER,
     parallelParam      IN VARCHAR2 DEFAULT NULL);

Description

Apply a dodging algorithm on the input GeoRaster object to color balance the image.

Parameters

inGeoRaster

The SDO_GEORASTER object to be processed.

gridSize

The size of each grid in x and y direction, respectively. It is an array of one or two numbers. If only one number is specified, then it is for both x and y direction.

samplingFactor

Sampling factor, used to control the calculation of the statistics, in the format'samplingFactor=n', with the denominator n in 1/(n*n) representing the number of cells skipped in both row and column dimensions in computing the statistics. For example, if samplingFactor is 4, one-sixteenth of the cells are sampled; but if samplingFactor is 1, all cells are sampled. The higher the value, the less accurate the statistics are likely to be, but the more quickly they will be computed. If not specified (null), the default is 1.

samplingFactor cannot be greater than or equal to one-half (0.5) of gridSize.

means

The target mean values for each output bands. If only one value is specified, it is applied to all the output bands; otherwise, it must have the same number of values as the number bands of the output GeoRaster object. If null, it is calculated as the average mean value over all the grids.

standardDeviations

The target standard deviation values for each output bands. If only one value is specified, it is applied to all the output bands; otherwise, it must have the same number of values as the number of bands of the output GeoRaster object. If null, it is calculated as the average standard deviation over all the grids.

refGeoraster

The reference GeoRaster object. The output of the dodging result will adapt to the statistics of the reference GeoRaster object.

storageParam

A string specifying storage parameters, as explained in Storage Parameters.

outGeoRaster

The output SDO_GEORASTER object that reflects the results of the operation. Must be either a valid existing GeoRaster object or an empty GeoRaster object. (Empty GeoRaster objects are explained in Blank and Empty GeoRaster Objects.) Cannot be the same GeoRaster object as inGeoRaster.

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.)

If parallelism is specified, the procedure performs an internal commit while the process is running. Therefore, you cannot roll back the results of this procedure. If an error occurs (even if it is raised by the Oracle parallel server), you must delete the resulting output GeoRaster object explicitly in order to roll back the operation.

Usage Notes

This dodging operation uses an adaptive image enhancement method to make the image tone more balanced, that is, the darker area becomes brighter and the bright area becomes darker. The statistics for the grid defined by the gridsize parameter are collected on the fly and adjusted to the target mean and standard deviation values. The grid size should be smaller than the imbalanced area in order to remove the imbalance. Adjust the gridSize parameter to achieve the best result.

The input GeoRaster image must have a cellDepth value of 8BIT_U. Any celldepth value in the storage parameters is ignored. The cell depth of the outGeoRaster object is always 8BIT_U.

Color map in the input GeoRaster object is not supported.

The output GeoRaster object has no pyramid or mask.

Examples

The following example creates a GeoRaster object that is the result of dodging on the input GeoRaster object. The desired mean and standard deviation are set as 125 and 80, respectively. The grid size is 512 on x and y direction. (It refers to a table named GEORASTER_TABLE, whose definition is presented after Example 1-1 in Storage Parameters.)

DECLARE
  gr1 sdo_georaster;
  gr2 sdo_georaster;
BEGIN
  INSERT INTO georaster_table (georid, georaster)
    VALUES (41, sdo_geor.init('RDT_1'))
    RETURNING georaster INTO gr2;

  SELECT georaster INTO gr1 FROM georaster_table WHERE georid=4;

  sdo_geor_ip.dodge(gr1, sdo_number_array(512, 512), ‘samplingFactor=3’, sdo_number_array(125), sdo_number_array(80), null, gr2);
  UPDATE georaster_table SET georaster=gr2 WHERE georid=41;
  COMMIT;
END;
/

The following example creates a GeoRaster object that is the result of dodging on the input GeoRaster object based on the reference GeoRaster object. Parallel processing is enabled with parallel degree of 4. The grid size is 512 on x and y direction. (It refers to a table named GEORASTER_TABLE, whose definition is presented after Example 1-1 in Storage Parameters.)

DECLARE
gr1 sdo_georaster;
gr2 sdo_georaster;
refgr sdo_georaster;
BEGIN
  INSERT INTO georaster_table (georid, georaster) VALUES (41, sdo_geor.init('RDT_1'))
     RETURNING georaster INTO gr2;
  SELECT georaster INTO gr1 FROM georaster_table WHERE georid=4;
  SELECT georaster INTO refgr FROM georaster_table WHERE georid=1;
  sdo_geor_ip.dodge(gr1, sdo_number_array(512, 512), ‘samplingFactor=3’, refgr, null,
                    gr2, 'parallel=4');
  UPDATE georaster_table SET georaster=gr2 WHERE georid=41;
COMMIT;
END;
/