SDO_GEOR.generatePyramid

Format

SDO_GEOR.generatePyramid(
     georaster     IN OUT SDO_GEORASTER, 
     pyramidParams IN VARCHAR2, 
     bgValues      IN SDO_NUMBER_ARRAY DEFAULT NULL, 
     parallelParam IN VARCHAR2 DEFAULT NULL);

Description

Generates pyramid data, which is stored together with the original data.

Parameters

georaster

GeoRaster object for which pyramid data is to be generated and stored.

pyramidParams

A string containing the pyramid parameters. See the Usage Notes for information about the available keywords and values.

bgValues

Background values for filling partially empty raster blocks. It is only useful when the source GeoRaster object has empty raster blocks and the current operation leads to partially empty raster blocks (see Empty Raster Blocks). 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.

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

For information about pyramid data, see Pyramids.

pyramidParams must be a quoted string that contains one or more of the following keywords, each with an appropriate value:

rLevel (for example, rLevel=2): Specifies the maximum reduction level: the number of pyramid levels to create at a smaller (reduced) size than the original object. If you do not specify this keyword, pyramid levels are generated until the smaller of the number of rows or columns is between 64 and 128. The dimension sizes at each lower resolution level are equal to the truncated integer values of the dimension sizes at the next higher resolution level, divided by 2.
resampling (for example, resampling=NN): Specifies the resampling method. Must be one of the following: NN, BILINEAR, BIQUADRATIC, CUBIC, AVERAGE4, AVERAGE16. For more information, see Resampling and Interpolation.

Note that for this procedure, BILINEAR and AVERAGE4 have the same effect.
nodata (for example, nodata=TRUE): Specifies whether NODATA values and value ranges should be considered during the procedure. Must be either TRUE (NODATA values and value ranges should be considered) or FALSE (NODATA values and value ranges should not be considered). The default value is FALSE. If the value is TRUE and the resampling method is BILINEAR, BIQUADRATIC, CUBIC, AVERAGE4, or AVERAGE16, whenever a cell value involved in the resampling calculation is a NODATA value, the result of the resampling is also a NODATA value. The resulting NODATA value is the minimum NODATA value associated with the current raster layer, if multiple NODATA values or value ranges exist.

If georaster is null or is a blank GeoRaster object, or if pyramid data exists for georaster but it was created with the same pyramid parameters specified in pyramidParams, this procedure performs no operation.

If pyramid data exists for georaster and it was created using a different resampling value from that specified in pyramidParams, the old pyramid data is deleted and new pyramid data is generated. However, a different nodata specification in pyramidParams does not cause the pyramid data to be regenerated. To cause a new nodata value to take effect, you must delete the old pyramid data and then regenerate it.

If you do not specify an rLevel value, the rLevel value is set to the default, which is calculated as follows:

(int)(log2(a / 64))

In the preceding calculation:

log2 is a logarithmic function with 2 as its base.
a is the smaller of the original row or column dimension size.

In the default case, the smaller of the row and column dimension sizes of the top-level overview (the smallest top-level pyramid) is between 64 and 128. If you specify an rLevel value greater than the maximum reduced-resolution level, the rLevel value is set to the maximum reduced-resolution level, which is calculated as follows:

(int)(log2(a))

In this case, the smaller of the row and column dimension sizes of the top-level overview is 1.

An exception is raised if georaster is invalid.

Examples

The following example creates pyramid data for a GeoRaster object.

DECLARE
  gr sdo_georaster;
BEGIN
 
  SELECT georaster INTO gr 
    FROM georaster_table WHERE georid = 6 FOR UPDATE;
 
  -- Generate pyramids.
  sdo_geor.generatePyramid(gr, 'rLevel=5, resampling=NN');
 
  -- Update the original GeoRaster object.
  UPDATE georaster_table SET georaster = gr WHERE georid = 6;
 
  COMMIT;
END;
/