SDO_GEOR.rectify

Format

SDO_GEOR.rectify(
     inGeoRaster      IN SDO_GEORASTER,
     pyramidLevel     IN NUMBER DEFAULT 0,
     elevationParam   IN VARCHAR2 DEFAULT NULL,
     DEM              IN SDO_GEORASTER DEFAULT NULL,
     outSRID          IN NUMBER,
     outModelCoordLoc IN NUMBER DEFAULT NULL,
     cropArea         IN SDO_GEOMETRY DEFAULT NULL,
     polygonClip      IN VARCHAR2 DEFAULT 'FALSE',
     layerNumbers     IN VARCHAR2 DEFAULT NULL,
     outResolutions   IN SDO_NUMBER_ARRAY DEFAULT NULL,
     resolutionUnit   IN VARCHAR2 DEFAULT NULL,
     referencePoint   IN SDO_GEOMETRY DEFAULT NULL,
     resampleParam    IN VARCHAR2 DEFAULT NULL,
     storageParam     IN VARCHAR2 DEFAULT NULL,
     outGeoRaster     IN OUT SDO_GEORASTER,
     bgValues         IN SDO_NUMBER_ARRAY DEFAULT NULL,
     parallelParam    IN VARCHAR2 DEFAULT NULL);

SDO_GEOR.rectify(
     inGeoRaster      IN SDO_GEORASTER,
     pyramidLevel     IN NUMBER DEFAULT 0,
     elevationParam   IN VARCHAR2 DEFAULT NULL,
     DEM              IN SDO_GEORASTER DEFAULT NULL,
     outSRID          IN NUMBER,
     outModelCoordLoc IN NUMBER DEFAULT NULL,
     cropArea         IN SDO_GEOMETRY DEFAULT NULL,
     polygonClip      IN VARCHAR2 DEFAULT 'FALSE',
     layerNumbers     IN VARCHAR2 DEFAULT NULL,
     outResolutions   IN SDO_NUMBER_ARRAY DEFAULT NULL,
     resolutionUnit   IN VARCHAR2 DEFAULT NULL,
     referencePoint   IN SDO_GEOMETRY DEFAULT NULL,
     resampleParam    IN VARCHAR2 DEFAULT NULL,
     storageParam     IN VARCHAR2 DEFAULT NULL,
     rasterBlob       IN OUT NOCOPY BLOB,
     outArea          OUT SDO_GEOMETRY,
     outWindow        OUT SDO_NUMBER_ARRAY,
     bgValues         IN SDO_NUMBER_ARRAY DEFAULT NULL);

Description

Perform rectification on all or part of a georeferenced GeoRaster object. The resulting object can be a new GeoRaster object (for persistent storage) or a BLOB (for temporary use). If the input model coordinate system (SRID) is three-dimensional, the average elevation or a Digital Elevation Model (DEM) can be used to perform the orthorectification.

Parameters

inGeoRaster

GeoRaster object on which to perform the operation. It must be georeferenced (see the SDO_GEOR.georeference subprogram).

pyramidLevel

Pyramid level of the source GeoRaster object for the operation.

For BLOB output, this parameter is required.
For SDO_GEORASTER output, if this parameter is null and the storageParam pyramid value is FALSE, only the pyramid level 0 is rectified and the output will have only level 0. If this parameter is null and the storageParam pyramid value is TRUE, all the pyramid levels from the input are rectified.
If the number 0 or greater is specified, only that pyramid level is used for the rectification, producing a result in scale based on that pyramid level image.

elevationParam

A string containing one or more of the elevation parameters average (average surface height), scale (scale value applied to all DEM values), and offset (offset applied to all DEM values), where the new value is (value + offset) * scale. This parameter must be a quoted string that contains one or more keyword=value pairs (for example, 'average=800 scale=3.2808399 offset=10'). If this parameter is null, 0 is assumed for average and offset, and 1 is used for scale. Any scale and offset values are ignored if DEM is not specified.

The use of the elevationParam parameter requires that the input GeoRaster object have a 3D model SRID.

When the input GeoRaster object has a 3D model SRID, the average elevation is important for defining the extents of the output image. If that information is available, it should be specified even if DEM is also specified. If the average elevation is not specified, the procedure will calculate an approximate value for the average elevation.

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

DEM

GeoRaster object with a digital elevation model (DEM); used to perform orthorectification, as explained in the Usage Notes. Must have the same SRID as outGeoRaster. The DEM area should cover the entire outGeoRaster area, or the cropArea if used. The elevation data is assumed to be on the first layer of the DEM GeoRaster object. If this parameter is null, the elevationParam value is used. For best results, the resolution of the DEM GeoRaster object should be close to the resolution of the input GeoRaster object.

The use of the DEM parameter requires that the input GeoRaster object have a 3D model SRID.

When the input GeoRaster object has a 3D model SRID, the average elevation is important for defining the extents of the output image. If that information is available, it should be specified in the elevationParam parameter even if DEM is also specified. If the average elevation is not specified, the procedure will calculate an approximate value for the average elevation.

outSRID

Coordinate system for the output GeoRaster object. Must be either null or a value from the SRID column of the MDSYS.CS_SRS table. If it is null, the output GeoRaster object will have the same SRID as the input GeoRaster object.

outModelCoordLoc

A value specifying the model location of the base of the area represented by a cell: 0 for CENTER or 1 for UPPERLEFT. If null, CENTER is used.

cropArea

Crop area definition. If null, no cropping is performed, and polygonClip is ignored.

If polygonClip is FALSE, the MBR of the cropArea is used to crop the output image. If polygonClip is TRUE, the geometry of the cropArea is used to crop the output image. Areas outside the crop area are filled with the background value

polygonClip

Ignored if cropArea is null. Otherwise, the string TRUE causes the cropArea value to be used to crop the mosaicked data; the string FALSE or a null value causes the MBR of cropArea to be used to crop the output image.

layerNumbers

A string identifying the logical layer numbers for the rectification and the output to outGeoRaster. Use commas to delimit the values, and a hyphen to indicate a range (for example, 2-4 for layers 2, 3, and 4).

outResolutions

An array of numeric values, one for each spatial dimension. Each value indicates the number of units of measure associated with the data area represented by that spatial dimension of a pixel. For example, if the spatial resolution values are (10,10) and the unit of measure for the ground data is meters, each pixel represents an area of 10 meters by 10 meters. If null, the default is the resolution of the source data at the specified pyramid level.

resolutionUnit

The unit of the outResolutions parameter. If resolutionUnit is different from the outGeoRaster SRID unit, an appropriate conversion is computed (the value of the output resolution is calculated by converting the outResolutions value in resolutionUnit to the unit of the output SRID) . If resolutionUnit is null, the default is the unit of the output SRID. If specified, it must be a quoted string in the format “unit=value” where value is the unit name. This parameter is ignored if outResolutions is null.

referencePoint

A point of type SDO_GEOMETRY indicating a reference to where the outGeoRaster object should be aligned so that the distance between the referencePoint and the upper-left corner of the output will have an integer number of pixels.

resampleParam

A comma-separated quoted string of keyword=value pairs for specifying resampling parameters. See the Usage Notes for more information.

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:

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

This procedure uses a non-parametric rectification method that takes the georeferencing polynomials from the input GeoRaster object to transform the original image space into the target image space. Therefore, the input GeoRaster object must be georeferenced (see the SDO_GEOR.georeference subprogram).

Orthorectification can be performed if the input GeoRaster object has a 3D model SRID. A digital elevation model (DEM) GeoRaster object can be used to improve the accuracy of the orthorectification. If the DEM parameter is not specified, the elevationParam average value is used as the height for the whole target area. If the elevationParam average value is not specified, it is estimated based on the SRS and DEM information (see Image Orthorectification).

resampleParam, if specified, 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, or 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.

Examples

In the following example, the input GeoRaster object is rectified to the same SRID. The input GeoRaster object was georeferenced using GCPs with SRID 32619.

The layerNumbers parameter indicates the order of selection of three bands of the seven bands from the input GeoRaster object, producing a three-band output GeoRaster object.

DECLARE
  gr1   sdo_georaster;
  gr2   sdo_georaster;
BEGIN
  select raster into gr1 from georaster_table where georid = 1;
  insert into georaster_table values(2, 'Rectified image',
         sdo_geor.init('georaster_rdt')) returning raster into gr2;
  sdo_geor.rectify(inGeoRaster       => gr1,
                   pyramidLevel      => null,
                   elevationParam    => null,
                   dem               => null,
                   outSRID           => null,
                   outModelCoordLoc  => null,
                   cropArea          => null,
                   polygonClip       => null,
                   layerNumbers      => '2,4,5',
                   outResolutions    => null,
                   resolutionUnit    => null,
                   referencePoint    => null,
                   resampleParam     => null,
                   storageParam      => null,
                   outGeoraster      => gr2);
  update georaster_table set georaster = gr2 where georid = 2;
  commit;
END;

In the following example, the input GeoRaster object was georeferenced using 3D GCPs with SRID 32619, and the function produces an orthorectified GeoRaster with SRID 4326.

The dem parameter specifies the GeoRaster object gr3 as the digital elevation model for providing height values for each pixel for the orthorectification.
resampleParam specifies the resampling method as BILINEAR.
The storageParam parameter specifies the interleaving as BSQ and the compression as DEFLATE.
The specified outResolutions value has the same unit of measurement as the output GeoRaster SRID because resolutionUnit is null.
The point geometry specified by referencePoint causes the output image upper-left corner to be aligned with that coordinate, with a integer number of pixel (rows and columns resolution) in between them.

DECLARE
  gr1   sdo_georaster;
  gr2   sdo_georaster;
  gr3   sdo_georaster;
  pto   sdo_geometry;
BEGIN
  pto := sdo_geometry(2001, 4326, sdo_point_type(-71.50,42.0, null));
  select raster into gr1 from georaster_table where georid = 1;
  select raster into gr1 from georaster_table where georid = 3;
  insert into georaster_table values(2, 'Rectified image',
         sdo_geor.init('georaster_rdt')) returning raster into gr2;
  sdo_geor.rectify(inGeoRaster       => gr1,
                   pyramidLevel      => 1,
                   elevationParam    => null,
                   dem               => gr3,
                   outSRID           => 4326,
                   outModelCoordLoc  => null,
                   cropArea          => null,
                   polygonClip       => null,
                   layerNumbers      => null,
                   outResolutions    => sdo_number_array(0.0025,0.0025),
                   resolutionUnit    => null,
                   referencePoint    => pto,
                   resampleParam     => 'resampling=BILINEAR',
                   storageParam      => 'interleaving=BSQ compress=DEFLATE',
                   outGeoraster      => gr2);
  update georaster_table set georaster = gr2 where georid = 2;
  commit;
END;

In the following example, the input GeoRaster object was georeferenced using GCPs with SRID 32619, and the output GeoRaster object is projected to SRID 4326.

resampleParam specifies the resampling method as CUBIC.
The storageParam parameter specifies blockSize as (512,512,3). Because interleaving is not specified, the interleaving method for inGeoRaster is used.
outResolutions and resolutionUnit are specified in meters, which is a different unit from outSRID 4316. In this case, the SDO_NUMBER_ARRAY values (30,30) are converted to degrees.
The SDO_GEOMETRY polygon specified for cropArea is used to crop the output area to the extents of that polygon; and because polygonClip is TRUE, the area of the image outside of the polygon is set to background values.
The model coordinate location of the output object is UpperLeft because outModelCoordLoc is specified as 1.

DECLARE
  gr1   sdo_georaster;
  gr2   sdo_georaster;
  pol   sdo_geometry;
BEGIN
  pol := sdo_geometry(2003,4326,NULL,sdo_elem_info_array(1,1003,1),
           sdo_ordinate_array(-70.869495075803073, 42.349420282160885,
                              -70.468523716196913, 42.813138293441916,
                              -70.957334345349082, 43.218053058782452,
                              -71.350984405166344, 42.736563729419181,
                              -70.869495075803073, 42.349420282160885));
  select raster into gr1 from georaster_table where georid = 1;
  insert into georaster_table values(2, 'Rectified image',
         sdo_geor.init('georaster_rdt')) returning raster into gr2;
  sdo_geor.rectify(inGeoRaster       => gr1,
                   pyramidLevel      => 0,
                   elevationParam    => null,
                   dem               => null,
                   outSRID           => 4326,
                   outModelCoordLoc  => 1,
                   cropArea          => pol,
                   polygonClip       => 'true',
                   layerNumbers      => null,
                   outResolutions    => sdo_number_array(30,30),
                   resolutionUnit    => 'unit=meter',
                   referencePoint    => null,
                   resampleParam     => 'resampling=CUBIC',
                   storageParam      => 'blocking=optimalpadding blockSize=(512,512,3)',
                   outGeoraster      => gr2);
  update georaster_table set georaster = gr2 where georid = 2;
  commit;
END;