SDO_GEOR.generateStatisticsMode

Format

SDO_GEOR.generateStatisticsMode(
     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 NUMBER;

or

SDO_GEOR.generateStatisticsMode(
     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 NUMBER;

or

SDO_GEOR.generateStatisticsMode(
     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 NUMBER;

or

SDO_GEOR.generateStatisticsMode(
     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 NUMBER;

Description

Computes statistical data associated with one or more layers on a specified pyramid level, and returns the mode value (the value that occurs most frequently). (It does not modify metadata in the GeoRaster object.)

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 of the returned resolution values. The default is pyramid level 0.

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.

If the data type is SDO_GEOMETRY, see also the Usage Notes for the SDO_GEOR.generateStatistics function for SDO_SRID requirements.

bandNumbers

Band ordinate 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 2, 4, 5, 6, and 8. If bandNumbers is null, all bands are used in computing the statistics.

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 statistical data and returns the MODEVALUE value. (The statistical data is described by the <statisticDatasetType> element in the GeoRaster metadata XML schema, which is described in GeoRaster Metadata XML Schema; however, this function does not update any metadata.)

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

See also the SDO_GEOR.generateStatistics function.

Examples

The following example computes statistical data for all bands on pyramid level 1, and returns the mode value.

DECLARE
  gr sdo_georaster;
  window sdo_geometry:=null;
  mode number; 
BEGIN
  SELECT tmimage INTO gr FROM landsat WHERE id=2021;
  mode:=sdo_geor.generateStatisticsMode(gr,1,'samplingFactor=7',window,null,'false');
END;
/

The following example uses the mask and samplingWindow parameters to select the pixels for the statistics calculation. The mode value is returned.

DECLARE
  gr sdo_georaster;
  maskgr sdo_georaster;
  window sdo_geometry;
  mode_val number;  
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;
  mode_val:=sdo_geor.generateStatisticsMode(gr,maskgr,0,'samplingFactor=2',window,'0','false',’false’,'parallel=4');
  dbms_output.put_line('mode='||mode_val);
END;
/

7.30 SDO_GEOR.generateStatisticsMode