7.113 SDO_GEOR.scaleCopy

Format

SDO_GEOR.scaleCopy(
     inGeoRaster    IN SDO_GEORASTER, 
     scaleParam     IN VARCHAR2, 
     resampleParam  IN VARCHAR2, 
     storageParam   IN VARCHAR2, 
     outGeoRaster   IN OUT SDO_GEORASTER, 
     bgValues       IN SDO_NUMBER_ARRAY DEFAULT NULL);

or

SDO_GEOR.scaleCopy(
     inGeoRaster    IN SDO_GEORASTER, 
     pyramidLevel   IN NUMBER, 
     scaleParam     IN VARCHAR2, 
     resampleParam  IN VARCHAR2, 
     storageParam   IN VARCHAR2, 
     outGeoRaster   IN OUT SDO_GEORASTER, 
     bgValues       IN SDO_NUMBER_ARRAY DEFAULT NULL);

Description

Scales a GeoRaster object by enlarging or reducing the image along row and column dimensions, and puts the result into a new object that reflects the scaling.

Parameters

inGeoRaster

The SDO_GEORASTER object on which the scaling operation is to be performed to create the new object (outGeoRaster).

pyramidLevel

A number specifying the pyramid level of the source GeoRaster object.

scaleParam

A string specifying a scaling parameter keyword and its associated value. The keyword must be one of the following:

Note:

For any numbers in string (VARCHAR2) parameters to GeoRaster subprograms, the period (.) must be used for any decimal points regardless of the locale.

  • scaleFactor, to reduce or enlarge as a multiple of the original size. This keyword must have a numeric value greater than 0 (zero) (for example, 'scaleFactor=0.75'). A value of 1.0 will not change the current size; a value less than 1 will reduce the image; a value greater than 1 will enlarge the image. The number of cells along each dimension is the original number multiplied by scaleFactor. For example, if the scaleFactor value is 2 and the GeoRaster object has X and Y dimensions, the number of cells along each dimension is doubled.

  • maxDimSize, to specify a size in terms of the maximum number of cells for each dimension. This keyword must have a numeric value for each dimension (for example, 'maxDimSize=(512,512)'). The aspect ratio is not changed.

  • rowMaxDimSize and columnMaxDimSize, to specify sizes in terms of the maximum number of cells for row and column dimensions. This pair of keywords must have numeric values for each dimension (for example, 'rowMaxDimSize=512,columnMaxDimSize=256'). The aspect ratio can be changed, and the two keywords must be specified together.

  • rowScaleFactor and columnScaleFactor, to reduce or enlarge as a multiple of the original size. This pair of keywords must have numeric values greater than 0 (zero). A value of 1.0 will not change the current size; a value less than 1 will reduce the image; a value greater than 1 will enlarge the image. The number of cells along row dimension is the original number multiplied by rowScaleFactor. The number of cells along column dimension is the original number multiplied by columnScaleFactor. rowScaleFactor and columnScaleFactor can be different numbers, but must be specified together.

resampleParam

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

storageParam

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

outGeoRaster

The new SDO_GEORASTER object that reflects the results of the scaling 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.

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.

Usage Notes

Use this procedure to create a new GeoRaster object reflecting the specified scaling, based on the original GeoRaster object or a specified pyramid level of the GeoRaster object. After you use this procedure, you can check to ensure that the desired changes were made in the copy of the original GeoRaster object, and then discard the original GeoRaster object if you wish.

If you use the format that does not include the pyramidLevel parameter, the scaling is based on the original GeoRaster object (pyramidLevel=0).

If you need to get the scaled cell values, use the procedure described in the Usage Notes for the SDO_GEOR.getCellValue function.

inGeoRaster and outGeoRaster must be different GeoRaster objects.

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

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

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

Any upper-level pyramid data in the input GeoRaster object is not considered during this operation, and the output GeoRaster object has no pyramid data.

After the operation, the row and column ULT coordinates are always set to 0 (zero), even if no scaling is performed (that is, even if scaleFactor=1).

This procedure does not scale along the band dimension.

If the source GeoRaster object is georeferenced with a valid polynomial transformation, the georeferencing information for the resulting GeoRaster object is generated accordingly; otherwise, the result GeoRaster object contains no spatial reference information.

An exception is raised if one or more of the following are true:

  • inGeoRaster is invalid.

  • outGeoRaster has not been initialized.

  • A raster data table for outGeoRaster does not exist and outGeoRaster is not a blank GeoRaster object.

Examples

The following example reduces an image to three-fourths (0.75) size, specifies AVERAGE4 resampling, and specifies an optimized block size around 512 for each dimension in the storage parameters. (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 (21, sdo_geor.init('RDT_1'))
    RETURNING georaster INTO gr2;

  SELECT georaster INTO gr1 FROM georaster_table WHERE georid=2;

  sdo_geor.scaleCopy(gr1, 'scaleFactor=0.75', 'resampling=AVERAGE4',
                     'blocking=optimalpadding blocksize=(512,512)', gr2);
  UPDATE georaster_table SET georaster=gr2 WHERE georid=21;
  COMMIT;
END;
/

Parent topic: SDO_GEOR Package Reference