Format

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

or

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

Description

Makes a copy of an existing GeoRaster object using a different storage format (for example, changing the blocking, cell depth, or interleaving).

Parameters

inGeoRaster

The SDO_GEORASTER object whose format is to be copied.

pyramidLevel

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

storageParam

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

outGeoRaster

The SDO_GEORASTER object to hold the copy. 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

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

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

If the copy is to be made from a pyramid of the original GeoRaster object (pyramidLevel > 0), and if the original GeoRaster object is georeferenced, georeferencing information is generated for the resulting GeoRaster object only when the georeference is a valid polynomial transformation. The resulting object's row and column ultCoordinates are set to (0,0).

To compress or decompress a GeoRaster object, use the compression keyword in the storageParam parameter. (There is no separate GeoRaster function or procedure for compressing or decompressing a GeoRaster object.)

If inGeoRaster is null, this procedure performs no operation.

If storageParam is null, inGeoRaster is copied to outGeoRaster.

If outGeoRaster has any raster data, it is deleted before the copy operation.

inGeoRaster and outGeoRaster must be different GeoRaster objects.

If pyramid data exists for inGeoRaster, any upper level pyramid data is copied to outGeoRaster unless the storageParam string contains pyramid=FALSE.

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 creates a GeoRaster object that is the same as the input object except that the block size is set to 2048 for both dimensions. (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
    SELECT georaster INTO gr2 from georaster_table WHERE georid=11 FOR UPDATE;
    SELECT georaster INTO gr1 from georaster_table WHERE georid=1;
  
    sdo_geor.changeFormatCopy(gr1, 'blocksize=(2048,2048)', gr2);
    UPDATE georaster_table SET georaster=gr2 WHERE georid=11;
    COMMIT;
END;
/

The following example creates a GeoRaster object that is the same as the input object except that raster data is compressed to deflate format and the compression process is running in parallel. (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
    SELECT georaster INTO gr2 from georaster_table WHERE georid=11 FOR UPDATE;
    SELECT georaster INTO gr1 from georaster_table WHERE georid=1;
  
    sdo_geor.changeFormatCopy(gr1, 'compression=deflate parallel=4', gr2);
    UPDATE georaster_table SET georaster=gr2 WHERE georid=11;
    COMMIT;
END;
/