7.25 SDO_GEOR.generateStatistics

Format (Storage in Metadata)

SDO_GEOR.generateStatistics(
     georaster      IN OUT SDO_GEORASTER, 
     samplingFactor IN VARCHAR2, 
     samplingWindow IN SDO_NUMBER_ARRAY, 
     histogram      IN VARCHAR2, 
     layerNumbers   IN VARCHAR2 DEFAULT NULL, 
     useBin         IN VARCHAR2 DEFAULT 'TRUE', 
     binFunction    IN SDO_NUMBER_ARRAY DEFAULT NULL, 
     nodata         IN VARCHAR2 DEFAULT 'FALSE' 
     ) RETURN VARCHAR2;

or

SDO_GEOR.generateStatistics(
     georaster      IN OUT SDO_GEORASTER, 
     samplingFactor IN VARCHAR2, 
     samplingWindow IN SDO_GEOMETRY, 
     histogram      IN VARCHAR2, 
     layerNumbers   IN VARCHAR2 DEFAULT NULL, 
     useBin         IN VARCHAR2 DEFAULT 'TRUE', 
     binFunction    IN SDO_NUMBER_ARRAY DEFAULT NULL, 
     nodata         IN VARCHAR2 DEFAULT 'FALSE' 
     ) RETURN VARCHAR2;

Format (No Storage in Metadata)

SDO_GEOR.generateStatistics(
     georaster      IN SDO_GEORASTER, 
     pyramidLevel   IN NUMBER, 
     samplingFactor IN VARCHAR2, 
     samplingWindow IN SDO_NUMBER_ARRAY, 
     bandNumbers    IN VARCHAR2 DEFAULT NULL, 
     nodata         IN VARCHAR2 DEFAULT 'FALSE',
     parallelParam  IN VARCHAR2 DEFAULT NULL
     ) RETURN SDO_NUMBER_ARRAY;

or

SDO_GEOR.generateStatistics(
     georaster      IN SDO_GEORASTER, 
     pyramidLevel   IN NUMBER, 
     samplingFactor IN VARCHAR2, 
     samplingWindow IN SDO_GEOMETRY, 
     bandNumbers    IN VARCHAR2 DEFAULT NULL, 
     nodata         IN VARCHAR2 DEFAULT 'FALSE',
     polygonClip    IN VARCHAR2 DEFAULT NULL, 
     parallelParam  IN VARCHAR2 DEFAULT NULL
     ) RETURN SDO_NUMBER_ARRAY;

or

SDO_GEOR.generateStatistics(
     georaster      IN SDO_GEORASTER, 
     mask           IN SDO_GEORASTER,
     pyramidLevel   IN NUMBER, 
     samplingFactor IN VARCHAR2, 
     samplingWindow IN SDO_NUMBER_ARRAY, 
     bandNumbers    IN VARCHAR2 DEFAULT NULL, 
     nodata         IN VARCHAR2 DEFAULT 'FALSE',
     parallelParam  IN VARCHAR2 DEFAULT NULL
     ) RETURN SDO_NUMBER_ARRAY;

or

SDO_GEOR.generateStatistics(
     georaster      IN SDO_GEORASTER, 
     mask           IN SDO_GEORASTER,
     pyramidLevel   IN NUMBER, 
     samplingFactor IN VARCHAR2, 
     samplingWindow IN SDO_GEOMETRY, 
     bandNumbers    IN VARCHAR2 DEFAULT NULL, 
     nodata         IN VARCHAR2 DEFAULT 'FALSE',
     polygonClip    IN VARCHAR2 DEFAULT NULL, 
     parallelParam  IN VARCHAR2 DEFAULT NULL
     ) RETURN SDO_NUMBER_ARRAY;

Description

Computes statistical data associated with one or more layers, or with one or more layers and pyramid levels. The two sets of function formats have significant usage differences:

  • Storage in Metadata formats also set statistical data in the GeoRaster object metadata for each specified layer, and optionally for the whole raster. These formats return the string TRUE or FALSE, indicating success or failure of the operation.

  • No Storage in Metadata formats do not set any GeoRaster object metadata, and they calculate statistics for a single layer or for the aggregation of specified layers. These formats return an SDO_NUMBER_ARRAY object where the numbers reflect the aggregated minimum, maximum, mean, median, mode, standard deviation, and sum values.

Parameters

georaster

GeoRaster object.

mask

A bitmap mask stored as a GeoRaster object. It can be georeferenced or not:

  • If the mask is not georeferenced, its extent will be used as cell space coordinates.
  • If the mask is georeferenced, it must has the same SRID as the input GeoRaster object.

The spatial area of the input GeoRaster object that is covered by the mask will be calculated for statistics. A cell value of 1 in the mask means the pixel at the same location of the source geoRaster will be used for the statistics calculation. The mask can be smaller or larger than the source GeoRaster object.

pyramidLevel

Pyramid level on which to perform the operation.

samplingFactor

Sampling factor 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.

samplingWindow

A sampling window for which to generate statistics, specified either as a numeric array or as an SDO_GEOMETRY object. If the data type is SDO_NUMBER_ARRAY (defined as VARRAY(1048576) OF NUMBER), 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, it is transformed into raster space if it is in model space, and then the minimum bounding rectangle (MBR) of the geometry object in raster space is used as the window. The default value is the entire image.

In both cases, the intersection of the MBR of the sampling window in raster space and the MBR of the GeoRaster object in raster space is used for computing statistics. However, if polygonClip is TRUE, then the samplingWindow geometry object will be used for the operation instead of the MBR of the sampling window, in which case only cells within the samplingWindow geometry are counted.

histogram

Specify TRUE to cause a histogram to be computed and stored, or FALSE to cause a histogram not to be computed and stored. Histograms are discussed in SDO_GEOR_HISTOGRAM Object Type. The XML definitions of the <histogram> element and the histogramType complex type are included in GeoRaster Metadata XML Schema.

layerNumbers

Numbers of the layers for which to compute the statistics. This is a string that can include numbers, number ranges indicated by hyphens (-), and commas to separate numbers and number ranges. For example, '1,3-5,7' specifies layers 1, 3, 4, 5, and 7. Layer 0 (zero) indicates the object layer.

bandNumbers

Band ordinate numbers of the layers for which values are used in computing the statistics. This is a string that can include numbers, number ranges indicated by hyphens (-), and commas to separate numbers and number ranges. For example, '0,1,3-5,7' specifies layers 1, 2, 4, 5, 6, and 8. If bandNumbers is null, all bands are used in computing the statistics.

useBin

Specifies whether or not to use a provided bin function (specified in the binFunction parameter) when generating statistics. TRUE (the default) causes a bin function to be used as follows: (1) the bin function specified by the binFunction parameter, if it is not null; otherwise, (2) the bin function specified by the <binFunction> element in the GeoRaster XML metadata, if one is specified; otherwise, (3) a dynamically generated bin function, as explained in the Usage Notes. FALSE causes a dynamically generated bin function to be used, and causes the binFunction parameter and <binFunction> element to be ignored.

For information about bin functions, see the Usage Notes for the SDO_GEOR.setBinFunction procedure.

binFunction

Bin function as an array whose elements specify the bin type, total number of bins, first bin number, minimum cell value, and maximum cell value. The SDO_NUMBER_ARRAY type is defined as VARRAY(1048576) OF NUMBER. For more information about the bin function for SQO_GEOR.generateStatistics, see the Usage Notes. For information about bin functions and an example, see the Usage Notes for the SDO_GEOR.setBinFunction procedure.

nodata

Specifies whether or not to compare each cell values with NODATA values defined in the metadata when computing statistics. TRUE causes all pixels with a NODATA value not to be considered; FALSE (the default) causes pixels with NODATA values to be considered as regular pixels. NODATA values and value ranges are discussed in NODATA Values and Value Ranges.

polygonClip

The string TRUE causes the samplingWindow geometry object to be used for the operation; the string FALSE or a null value causes the MBR (minimum bounding rectangle) of the samplingWindow geometry object to be used for the operation.

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, you cannot roll back the results of this function.

Usage Notes

This function computes and can set the statistical data described by the <statisticDatasetType> element in the GeoRaster metadata XML schema, which is described in GeoRaster Metadata XML Schema.

If samplingWindow is outside the GeoRaster object or if it contains only NODATA values, the following error is raised: 

ORA-13393: null or invalid samplingWindow parameter

If histogram is TRUE, this function determines the range of each bin based on the bin function being used, and within each range it computes the count of each pixel value. The histogram and the bin function are related as follows: each bin is mapped to a (value, count) pair of the histogram, and the lower boundary of each bin is mapped to corresponding value of histogram (value, count) pair, with the following exceptions:

  • If Min_r < Min, then one more pair (Min_r, count) is added as the first pair of the histogram. (Min_r is the real minimum value of the data set computed by this function, and Min is the min value specified in the bin function.)

  • If Max_r > Max, then one more pair (Max_r, count) is added as the last pair of the histogram. (Max_r is the real maximum value of the data set computed by this function, and Max is the max value specified in the bin function.)

  • Leading and trailing count=0 pairs in the histogram are suppressed. For example:

    (1,0) (2,0) (3,11) (4,12) becomes (3,11) (4,12)
(1,11) (2,12) (3,0) (4,0) becomes (1,11) (2,12)

If histogram is TRUE, any existing histogram in the XML metadata is replaced by the new generated histogram.

SQO_GEOR.generateStatistics supports only LINEAR bin functions (binType = 0), not LOGARITHM or EXPLICIT bin functions. (The XML definitions of all bin function types are in GeoRaster Metadata XML Schema.) If the useBin parameter value is FALSE, this function ignores any binFunction parameter value and any <binFunction> element in the GeoRaster XML metadata, and it uses a LINEAR bin function in which the min and max values are the actual minimum and maximum values of the data set, and the numbins value depends on the cell depth, as follows:

  • If cellDepth = 1, numbins = 2.

  • If cellDepth = 2, numbins = 4.

  • If cellDepth = 4, numbins = 8.

  • If cellDepth >= 8, numbins = 256.

If the useBin parameter value is TRUE, this function uses a bin function as follows:

  1. If the binFunction parameter specifies a valid bin function, it is used.

  2. Otherwise, if a valid bin function is defined in the GeoRaster metadata, it is used.

  3. Otherwise, the same bin function is used as when the useBin parameter value is FALSE.

Contrast this function, which causes GeoRaster to compute and optionally set the statistics, with the SDO_GEOR.setStatistics procedure, in which you specify the statistics to be set.

To retrieve the statistical data associated with a layer, use the SDO_GEOR.getStatistics function.

Examples

The following example generates the statistical data and a histogram.

DECLARE
  gr SDO_GEORASTER;
  ret VARCHAR2(256);
  window SDO_NUMBER_ARRAY := SDO_NUMBER_ARRAY(20,10,50,50);
BEGIN
  SELECT georaster INTO gr FROM georaster_table WHERE georid=1 FOR UPDATE;
  SDO_GEOR.setBinFunction(gr,1,sdo_number_array(0,10,1,50,200));
  ret := SDO_GEOR.generateStatistics(gr, 'samplingFactor=5', window, 'TRUE',
    '1-1', 'TRUE');
  UPDATE georaster_table SET georaster=gr WHERE georid=1;
  COMMIT;
END;
/

The following example generates the statistical data for all bands on pyramid level 1; however, it does not create a histogram or modify the GeoRaster object metadata.

DECLARE
  gr sdo_georaster;
  window  sdo_geometry:=null;
  stat   sdo_number_array;  
BEGIN  
  SELECT tmimage INTO gr FROM landsat WHERE id=2021;
  stat:=sdo_geor.generateStatistics(gr,1,'samplingFactor=7',window,null,'false');
  dbms_output.put_line('min='||stat(1));  
  dbms_output.put_line('max='||stat(2));
  dbms_output.put_line('mean='||stat(3));
  dbms_output.put_line('median='||stat(4));
  dbms_output.put_line('mode='||stat(5));
  dbms_output.put_line('std='||stat(6));
  dbms_output.put_line('sum='||stat(7));
END;
/

The following example uses the mask, samplingWindow, and polygonClip parameters to select the pixels for the statistics calculation. The statistics are returned in an array. 

DECLARE
  gr sdo_georaster;
  maskgr sdo_georaster;
  window  sdo_geometry;
  stat   sdo_number_array;  
BEGIN  
  SELECT tmimage INTO gr FROM landsat WHERE id=2021;
  SELECT mask INTO maskgr FROM masks WHERE id=1;
  SELECT geom INTO window FROM boundary WHERE id=1;

  stat:=sdo_geor.generateStatistics(gr,maskgr,0,'samplingFactor=2',window,'0-2','false',’true’,'parallel=4');
  dbms_output.put_line('min='||stat(1));  
  dbms_output.put_line('max='||stat(2));
  dbms_output.put_line('mean='||stat(3));
  dbms_output.put_line('median='||stat(4));
  dbms_output.put_line('mode='||stat(5));
  dbms_output.put_line('std='||stat(6));
  dbms_output.put_line('sum='||stat(7));
END;
/

Parent topic: SDO_GEOR Package Reference