SDO_GEOR.affineTransform

Format

SDO_GEOR.affineTransform(
     inGeoRaster   IN SDO_GEORASTER, 
     translation   IN SDO_NUMBER_ARRAY DEFAULT NULL,
     scales        IN SDO_NUMBER_ARRAY DEFAULT NULL,
     rotatePt      IN SDO_NUMBER_ARRAY DEFAULT NULL,
     rotateAngle   IN NUMBER DEFAULT NULL,
     shear         IN SDO_NUMBER_ARRAY DEFAULT NULL,
     reflection    IN NUMBER DEFAULT NULL,
     storageParam  IN VARCHAR2 DEFAULT NULL, 
     outGeoRaster  IN OUT SDO_GEORASTER, 
     bgValues      IN SDO_NUMBER_ARRAY DEFAULT NULL,
     parallelParam IN VARCHAR2 DEFAULT NULL);

or

SDO_GEOR.affineTransform(
     inGeoRaster   IN SDO_GEORASTER, 
     translation   IN SDO_NUMBER_ARRAY DEFAULT NULL,
     scales        IN SDO_NUMBER_ARRAY DEFAULT NULL,
     rotatePt      IN SDO_NUMBER_ARRAY DEFAULT NULL,
     rotateAngle   IN NUMBER DEFAULT NULL,
     shear         IN SDO_NUMBER_ARRAY DEFAULT NULL,
     reflection    IN NUMBER DEFAULT NULL,
     storageParam  IN VARCHAR DEFAULT2 DEFAULT NULL, 
     rasterBlob    IN OUT NOCOPY_BLOB,
     outArea       OUT SDO_GEOMTRY,
     outWindow     OUT SDO_NUMBER_ARRAY, 
     bgValues      IN SDO_NUMBER_ARRAY DEFAULT NULL,
     parallelParam IN VARCHAR2 DEFAULT NULL);

Description

Performs affine transformation on the input GeoRaster image to produce an output GeoRaster image based on the values of the parameters translation, scales, rotatePt. rotateAngle, shear, and reflection.

Parameters

inGeoRaster

GeoRaster object on which to perform the operation. It does not need to be georeferenced. (Georeferencing is explained in Georeferencing GeoRaster Objects and Advanced Georeferencing.)

translation

When specified, should contain two integer numeric values with the number of rows and columns to be applied to the translation transformation. The values for row and columns translation are independent of each other, but positive values will translate the image to the right and to the bottom, and negative values will translate the image to the left and to the top. If this parameter is omitted, no translation is performed.

scales

When specified, should contain two numeric values with the scale factor to be applied to the rows and columns to be applied to the scale transformation. The values for row and columns scaling are independent from each other but values between 0 and 1 will reduce the size of the image in rows and/or columns while values greater than 1 will enlarge the size of image is rows and/or columns. If this parameter is omitted, no scaling is performed.

rotatePt

When specified, should contain two numeric value representing the cell space coordinate (row and columns) to be used as the center of the rotation operation. In practical terms, the image feature associated with rotatePt will be the center of the new output image. If this parameter is omitted, the center of the image is assumed.

rotateAngle

When specified, should contain a numeric value between -180 to 180 identifying the angle to be applied to the rotation transformation. A positive value indicates that the rotation will turn to the right and negative value indicates rotation to the left. See usage notes for more information. If this parameter is omitted, no rotation is performed.

shear

When specified, should contain two numeric value between the shear factor to be applied to the x and y coordinates respectively in a shear transformation. The values for row and columns shear are independent from each other. If this parameter is omitted, no shearing is performed.

reflection

When specified, should contain the numeric values 1 or 2, representing vertical or horizontal reflection, respectively. If this parameter is omitted, no reflection is performed.

storageParam

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

outGeoRaster

GeoRaster object to hold the result of the 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

rasterBlob

BLOB to hold the output reflecting the rectification. It must exist or have been initialized before the operation.

outArea

An SDO_GEOMETRY object containing the MBR (minimum bounding rectangle) in the model coordinate system of the resulting object.

outWindow

An SDO_NUMBER_ARRAY object identifying the coordinates of the upper-left and lower-right corners of the output window in the cell space.

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

This procedure has two formats:

The first format generates a GeoRaster object for persistent storage in the database.
The second format generates a BLOB for temporary storage or immediate use, such as to display data on the screen.

This procedure performs the specified simple affine transformation operations individually or in combination.

For all the possible operations and combinations of operations, this procedure will transform the physical representation of the stored image and build new georeferencing information that preserves the original location of features in the image. Thus, the image might look the same when projected by a visualization tool.

Examples

In the following example, the output GeoRaster object will be generated from rotating the source image by -90 degrees (90 degrees to the left).

DECLARE
  gr1 sdo_georaster;
  gr2 sdo_georaster;  
BEGIN
  select georaster into gr1 from georaster_table where georid = 1;

  insert into georaster_table values(2, 'Rotated 90 left',
         sdo_geor.init('rdt0',2)) returning georaster into gr2;

  sdo_geor.affineTransform(inGeoRaster   => gr1,
                           translation   => null,
                           scales        => null,
                           rotatePt      => null,
                           rotateAngle   => -90,
                           shear         => null,
                           reflection    => null,
                           storageParam  => 'pyramid=true',
                           outGeoraster  => gr2);

  update georaster_table set georaster = gr2 where georid = 2;
  commit;
END;

In the following example, the output GeoRaster object will be generated from enlarging the source image two times bigger while rotating it by 15 degrees to the right.

DECLARE
  gr1 sdo_georaster;
  gr3 sdo_georaster;  
BEGIN
  select georaster into gr2 from georaster_table where georid = 1;

  insert into georaster_table values(3, 'Scaled x 2 Rotated 15',
         sdo_geor.init('rdt0',3)) returning georaster into gr3;

  sdo_geor.affineTransform(inGeoRaster   => gr1,
                           translation   => null,
                           scales        => sdo_number_array(2,2),
                           rotatePt      => null,
                           rotateAngle   => 15,
                           shear         => null,
                           reflection    => null,
                           storageParam  => 'blocksize=(512,512,3)',
                           outGeoraster  => gr3,
                           parallelParam => 'parallel=4');

  update georaster_table set georaster = gr3 where georid = 3;
  commit;
END;

In the following example, the output GeoRaster object will be generated from shearing the source image by a factor of 5 in both rows and columns:

DECLARE
  gr1 sdo_georaster;
  gr4 sdo_georaster;  
BEGIN
  select georaster into gr2 from georaster_table where georid = 1;

  insert into georaster_table values(4, 'Shear 5,5',
         sdo_geor.init('rdt0',4)) returning georaster into gr4;

  sdo_geor.affineTransform(inGeoRaster   => gr1,
                           translation   => null,
                           scales        => null,
                           rotatePt      => null,
                           rotateAngle   => null,
                           shear         => sdo_number_array(5,5),
                           reflection    => null,
                           storageParam  => 'pyramid=true',
                           outGeoraster  => gr4,
                           parallelParam => 'parallel=4');

  update georaster_table set georaster = gr4 where georid = 4;
  commit;
END;

In the following example, the output GeoRaster object will be generated from the vertical reflection of the source image.

DECLARE
  gr1 sdo_georaster;
  gr5 sdo_georaster;  
BEGIN
  select georaster into gr2 from georaster_table where georid = 1;

  insert into georaster_table values(5, 'Vertical reflection',
         sdo_geor.init('rdt0',5)) returning georaster into gr5;

  sdo_geor.affineTransform(inGeoRaster   => gr1,
                           translation   => null,
                           scales        => null,
                           rotatePt      => null,
                           rotateAngle   => null,
                           shear         => null,
                           reflection    => 1,
                           storageParam  => 'pyramid=true',
                           outGeoraster  => gr5,
                           parallelParam => 'parallel=4');

  update georaster_table set georaster = gr5 where georid = 5;
  commit;
END;