SDO_GEOR_IP.piecewiseStretch

Format

SDO_GEOR_IP.piecewiseStretch(
     inGeoRaster  IN SDO_GEORASTER, 
     pyramidLevel IN NUMBER DEFAULT 0, 
     cropArea     IN SDO_NUMBER_ARRAY DEFAULT NULL, 
     bandNumbers  IN VARCHAR2, 
     inValues     IN SDO_NUMBER_ARRAYSET,
     outValues    IN SDO_NUMBER_ARRAYSET,
     storageParam IN VARCHAR2 DEFAULT NULL, 
     outGeoraster IN OUT SDO_GEORASTER,
     parallelParam IN VARCHAR2 DEFAULT NULL);

or

SDO_GEOR_IP.piecewiseStretch(
     inGeoRaster  IN SDO_GEORASTER, 
     pyramidLevel IN NUMBER DEFAULT 0, 
     cropArea     IN SDO_GEOMETRY DEFAULT NULL, 
     layerNumbers IN VARCHAR2,
     inValues     IN SDO_NUMBER_ARRAYSET,
     outValues    IN SDO_NUMBER_ARRAYSET,
     storageParam IN VARCHAR2 DEFAULT NULL, 
     outGeoraster IN OUT SDO_GEORASTER,
     parallelParam IN VARCHAR2 DEFAULT NULL);

or

SDO_GEOR_IP.piecewiseStretch(
     inGeoRaster  IN SDO_GEORASTER, 
     pyramidLevel IN NUMBER DEFAULT 0, 
     cropArea     IN SDO_NUMBER_ARRAY DEFAULT NULL, 
     bandNumbers  IN VARCHAR2, 
     inValues     IN SDO_NUMBER_ARRAYSET,
     outValues    IN SDO_NUMBER_ARRAYSET,
     storageParam IN VARCHAR2 DEFAULT NULL, 
     rasterBlob   IN OUT BLOB,
     outArea      OUT SDO_GEOMETRY,
     outWindow    OUT SDO_NUMBER_ARRAY);

or

SDO_GEOR_IP.piecewiseStretch(
     inGeoRaster  IN SDO_GEORASTER, 
     pyramidLevel IN NUMBER DEFAULT 0, 
     cropArea     IN SDO_GEOMETRY DEFAULT NULL, 
     layerNumbers IN VARCHAR2,
     inValues     IN SDO_NUMBER_ARRAYSET,
     outValues    IN SDO_NUMBER_ARRAYSET,
     storageParam IN VARCHAR2 DEFAULT NULL, 
     rasterBlob   IN OUT BLOB,
     outArea      OUT SDO_GEOMETRY,
     outWindow    OUT SDO_NUMBER_ARRAY);

Description

Performs a linear stretch on the input GeoRaster object using the minimum and maximum values. The processed image is stored in the output GeoRaster object or in a BLOB.

Parameters

inGeoRaster

The SDO_GEORASTER object to be stretched.

pyramidLevel

A number specifying the pyramid level to be stretched in the source GeoRaster object. If null, the default is 0.

cropArea

Crop area definition. If cropArea is of type SDO_GEOMETRY, use the layerNumbers parameter to specify one or more layer numbers; if cropArea is of type SDO_NUMBER_ARRAY, use the bandNumbers parameter to specify one or more band numbers.

If the data type is SDO_NUMBER_ARRAY, the parameter identifies the upper-left (row, column) and lower-right (row, column) coordinates of a rectangular window, and raster space is assumed. If the data type is SDO_GEOMETRY, the minimum bounding rectangle (MBR) of the geometry object is used as the crop area; see also the Usage Notes for SDO_SRID requirements.

bandNumbers

A string identifying the physical band numbers on which the operation is to be performed. Use commas to delimit the values, and a hyphen to indicate a range (for example, 1-3 for bands 1, 2, and 3).

layerNumbers

A string identifying the logical layer numbers on which the operation is to be performed. Use commas to delimit the values, and a hyphen to indicate a range (for example, 2-4 for layers 2, 3, and 4).

inValues

An array of SDO_NUMBER_ARRAY objects corresponding to each input band. If only one element is specified, all the output bands are stretched in the same way. Each SDO_NUMBER_ARRAY specifies the input GeoRaster object cell value ranges used in the stretch. For example, sdo_number_array(0, 50, 255) specifies two value ranges, from 0 to 50 and 50 to 255.

outValues

An array of SDO_NUMBER_ARRAY objects corresponding to each output band. If only one element is specified, all the output bands are stretched in the same way. Each SDO_NUMBER_ARRAY specifies the target values ranges corresponding to the value ranges of the inValues parameter. For example, sdo_number_array(0, 200, 255) specifies two value ranges, from 0 to 200 and 200 to 255.

storageParam

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

outGeoRaster

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

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.

rasterBlob

BLOB to hold the output of the processing result. 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.

Usage Notes

The inValues and outValues parameters must have the same number of values, and the range specified in the inValues parameter must be in ascending order. The values in the inValues parameter must be in the range of the cell depth of the inGeoRaster object. The values in the outValues parameter must be in the range of the cell depth of the outGeoRaster object.

If the cropArea parameter data type is SDO_GEOMETRY, the SDO_SRID value must be one of the following:

Null, to specify raster space
A value from the SRID column of the MDSYS.CS_SRS table

If the SDO_SRID values for the cropArea parameter geometry and the model space are different, the cropArea parameter geometry is automatically transformed to the coordinate system of the model space before the operation is performed. (Raster space and model space are explained in GeoRaster Data Model.)

Color map stored in the input GeoRaster object is not supported.

The output GeoRaster object has no pyramid or mask.

Examples

The following example creates a GeoRaster object that piecewise stretches all bands of the input GeoRaster object into different cell depths: a linear stretch of input values between 0 and 255 to the range 0 to 2000. (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;
  cropArea sdo_number_array := null;
  inValues sdo_number_arrayset;
  outValues sdo_number_arrayset;
BEGIN
  INSERT INTO georaster_table (georid, georaster)
    VALUES (41, sdo_geor.init('RDT_1'))
    RETURNING georaster INTO gr2;

  SELECT georaster INTO gr1 FROM georaster_table WHERE georid=4;

  -- define the input and output value ranges
  inValues := sdo_number_arrayset(sdo_number_array(0, 255));
  outValues := sdo_number_arrayset(sdo_number_array(0, 2000));

  sdo_geor_ip.piecewisestretch(gr1, 0, cropArea, null, 
                inValues, outValues, 'celldepth=16bit_u', gr2);
  UPDATE georaster_table SET georaster=gr2 WHERE georid=41;
  COMMIT;
END;
/

The following example piecewise stretches each band for different ranges; the output is in a temporary BLOB. (It refers to a table named GEORASTER_TABLE, whose definition is presented after Example 1-1 in Storage Parameters.)

DECLARE
  gr1 sdo_georaster;
  cropArea sdo_number_array := null;
  inValues sdo_number_arrayset;
  outValues sdo_number_arrayset;
  out_lob  BLOB;
  outArea  sdo_geometry := null;
  outWindow sdo_geometry := null; 
 BEGIN
  dbms_lob.create_temporary(out_lob, TRUE);

  SELECT georaster INTO gr1 FROM georaster_table WHERE georid=4;

  -- define the input and output values ranges
  inValues := sdo_number_arrayset(sdo_number_array(0, 30, 80, 255), 
                                  sdo_number_array(0, 10, 50, 255),
                                  sdo_number_array(0, 50, 150, 255));
  outValues := sdo_number_arrayset(
                   sdo_number_array(0, 80, 200, 255),
                   sdo_number_array(0, 60, 150, 255),
                   sdo_number_array(0, 100, 250,255) );

  sdo_geor_ip.piecewisestretch(gr1, 0, cropArea, null, inValues, outValues,  
                                     null, out_lob, outArea, outWindow);

  if outWindow is not null then
     dbms_output.put_line('output window: (' || outWindow(1) || ',' ||
                           outWindow(2) || ',' || outWindow(3) || ',' || outWindow(4) || ')');
  end if;
  dbms_lob.freeTemporary(out_lob);

END;
/