1. Spatial GeoRaster Developer's Guide
  2. SDO_GEOR_AGGR Package Reference
  3. SDO_GEOR_AGGR.getMosaicSubset

9.5 SDO_GEOR_AGGR.getMosaicSubset

Format

SDO_GEOR_AGGR.getMosaicSubset(
     inGeoRasters     IN SYS_REFCURSOR, 
     pyramidLevel     IN NUMBER DEFAULT NULL, 
     outSRID          IN NUMBER DEFAULT NULL, 
     outModelCoordLoc IN NUMBER DEFAULT NULL, 
     referencePoint   IN SDO_GEOMETRY DEFAULT NULL, 
     cropArea         IN SDO_GEOMETRY DEFAULT NULL, 
     polygonClip      IN VARCHAR2 DEFAULT 'FALSE', 
     boundaryClip     IN VARCHAR2 DEFAULT 'TRUE', 
     layerNumbers     IN VARCHAR2 DEFAULT NULL, 
     outResolutions   IN SDO_NUMBER_ARRAY DEFAULT NULL, 
     resolutionUnit   IN VARCHAR2 DEFAULT NULL, 
     mosaicParam      IN VARCHAR2 DEFAULT NULL, 
     rasterBlob       IN OUT NOCOPY BLOB, 
     outArea          OUT SDO_GEOMETRY, 
     outWindow        OUT SDO_NUMBER_ARRAY, 
     storageParam     IN VARCHAR2 DEFAULT NULL, 
     bgValues         IN SDO_NUMBER_ARRAY DEFAULT NULL);

or

SDO_GEOR_AGGR.getMosaicSubset(
     georasterTableNames  IN VARCHAR2, 
     georasterColumnNames IN VARCHAR2, 
     pyramidLevel         IN NUMBER DEFAULT NULL, 
     outSRID              IN NUMBER DEFAULT NULL, 
     outModelCoordLoc     IN NUMBER DEFAULT NULL, 
     referencePoint       IN SDO_GEOMETRY DEFAULT NULL, 
     cropArea             IN SDO_GEOMETRY DEFAULT NULL, 
     polygonClip          IN VARCHAR2 DEFAULT 'FALSE', 
     boundaryClip         IN VARCHAR2 DEFAULT 'TRUE', 
     layerNumbers         IN VARCHAR2 DEFAULT NULL, 
     outResolutions       IN SDO_NUMBER_ARRAY DEFAULT NULL, 
     resolutionUnit       IN VARCHAR2 DEFAULT NULL, 
     mosaicParam          IN VARCHAR2 DEFAULT NULL, 
     rasterBlob           IN OUT NOCOPY BLOB, 
     outArea              OUT SDO_GEOMETRY, 
     outWindow            OUT SDO_NUMBER_ARRAY, 
     storageParam         IN VARCHAR2 DEFAULT NULL, 
     bgValues             IN SDO_NUMBER_ARRAY DEFAULT NULL);

or

SDO_GEOR_AGGR.getMosaicSubset(
     inGeoRasters     IN SYS_REFCURSOR, 
     pyramidLevel     IN NUMBER DEFAULT NULL, 
     elevationParam   IN VARCHAR2, 
     outSRID          IN NUMBER DEFAULT NULL, 
     outModelCoordLoc IN NUMBER DEFAULT NULL, 
     referencePoint   IN SDO_GEOMETRY DEFAULT NULL, 
     cropArea         IN SDO_GEOMETRY DEFAULT NULL, 
     polygonClip      IN VARCHAR2 DEFAULT 'FALSE', 
     boundaryClip     IN VARCHAR2 DEFAULT 'TRUE', 
     layerNumbers     IN VARCHAR2 DEFAULT NULL, 
     outResolutions   IN SDO_NUMBER_ARRAY DEFAULT NULL, 
     resolutionUnit   IN VARCHAR2 DEFAULT NULL, 
     mosaicParam      IN VARCHAR2 DEFAULT NULL, 
     rasterBlob       IN OUT NOCOPY BLOB, 
     outArea          OUT SDO_GEOMETRY, 
     outWindow        OUT SDO_NUMBER_ARRAY, 
     storageParam     IN VARCHAR2 DEFAULT NULL, 
     bgValues         IN SDO_NUMBER_ARRAY DEFAULT NULL,
     referenceImage   IN SDO_GEORASTER DEFAULT NULL,
     referenceValue1  IN SDO_NUMBER_ARRAY DEFAULT NULL,
     referenceValue2  IN SDO_NUMBER_ARRAY DEFAULT NULL,
     refHistograms    IN SDO_GEOR_HISTOGRAM_ARRAY DEFAULT NULL);

or

SDO_GEOR_AGGR.getMosaicSubset(
     georasterTableNames  IN VARCHAR2, 
     georasterColumnNames IN VARCHAR2, 
     pyramidLevel         IN NUMBER DEFAULT NULL, 
     elevationParam       IN VARCHAR2, 
     outSRID              IN NUMBER DEFAULT NULL, 
     outModelCoordLoc     IN NUMBER DEFAULT NULL, 
     referencePoint       IN SDO_GEOMETRY DEFAULT NULL, 
     cropArea             IN SDO_GEOMETRY DEFAULT NULL, 
     polygonClip          IN VARCHAR2 DEFAULT 'FALSE', 
     boundaryClip         IN VARCHAR2 DEFAULT 'TRUE', 
     layerNumbers         IN VARCHAR2 DEFAULT NULL, 
     outResolutions       IN SDO_NUMBER_ARRAY DEFAULT NULL, 
     resolutionUnit       IN VARCHAR2 DEFAULT NULL, 
     mosaicParam          IN VARCHAR2 DEFAULT NULL, 
     rasterBlob           IN OUT NOCOPY BLOB, 
     outArea              OUT SDO_GEOMETRY, 
     outWindow            OUT SDO_NUMBER_ARRAY, 
     storageParam         IN VARCHAR2 DEFAULT NULL, 
     bgValues             IN SDO_NUMBER_ARRAY DEFAULT NULL,
     referenceImage       IN SDO_GEORASTER DEFAULT NULL,
     referenceValue1      IN SDO_NUMBER_ARRAY DEFAULT NULL,
     referenceValue2      IN SDO_NUMBER_ARRAY DEFAULT NULL,
     refHistograms        IN SDO_GEOR_HISTOGRAM_ARRAY DEFAULT NULL);

Description

Performs subsetting over a virtual mosaic or a collection of GeoRaster objects. It performs mosaic operations dynamically for the queried area and returns the required result in a BLOB on-the-fly. Internal rectification, common point rules, gap filling, and color balancing are performed whenever necessary.

Parameters

inGeoRasters

Source GeoRaster objects in a cursor.

georasterTableNames

Names (comma-separated) of the tables containing the source GeoRaster objects.

For information about defining and using MIN_X_RES$ and MAX_X_RES$ columns in these tables, see the Usage Notes and Improving Query Performance Using MIN_X_RES$ and MAX_X_RES$.

georasterColumnNames

Names (comma-separated) of the columns of type SDO_GEORASTER in tables corresponding to the table names in georasterTableNames.

pyramidLevel

Pyramid level of the source GeoRaster objects for the operation. This parameter is used when the outResolutions parameter is not specified; otherwise, the pyramid level of the source GeoRaster objects is determined by the outResolutions parameter.

elevationParam

A string containing the elevation parameter average (average surface height). This parameter must be a quoted string that contains a keyword=value pair (for example, 'average=800'). This parameter specifies the elevation of the output GeoRaster object. If this parameter is null, 0 is assumed for average.

The use of the elevationParam parameter requires that the input GeoRaster objects have a 3D model SRID and a nonzero average height.

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.

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.

referencePoint

A point of type SDO_GEOMETRY used as the reference point of mosaic. If a point is specified, the mosaicked image's upper left corner aligns with the reference point, that is, the distance between the referencePoint and the upper-left corner of the output will have an integer number of pixels. If this parameter is null, the reference point implicitly uses the upper-left corner of the cropArea, or when the cropArea is null, the upper-left corner of the output extent.

cropArea

Crop area definition. If the SDO_GEOMETRY object has a non-null SRID, the coordinates specified in the SDO_GEOMETRY object are in model space and the source GeoRaster objects must be georeferenced; otherwise, the coordinates specified in the SDO_GEOMETRY object are in cell space and the source GeoRaster objects can be georeferenced or non-georeferenced. If polygonClip is FALSE, the MBR of the cropArea is used to crop the mosaicked data. If polygonClip is TRUE, the geometry of the cropArea is used to crop the mosaicked data.

polygonClip

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 the cropArea to be used to crop the mosaicked data.

boundaryClip

The string TRUE or a null value causes the boundary of the virtual mosaic to be used to clip the cropArea; the string FALSE causes the area that is outside the virtual mosaic but within the cropArea to be filled with the background value.

layerNumbers

A string identifying the logical layer numbers on which the operation or operations are 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). If not specified, the mosaic result contains the same number of bands as the source GeoRaster objects.

outResolutions

Resolution requested for the output GeoRaster data. If null, the default is the resolution of the first encountered GeoRaster object. See the Usage Notes for details.

resolutionUnit

The unit of the outResolutions parameter. If 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 value (a valid UNIT_OF_MEAS_NAME value from the SDO_UNITS_OF_MEASURE table). This parameter is ignored if outResolutions is null.

mosaicParam

A comma-separated quoted string of keyword=value pairs for specifying mosaic parameters. It can contain one or more of the keywords in Table 9-1 in the SDO_GEOR_AGGR.mosaicSubset reference section.

rasterBlob

BLOB (binary large object) to hold the result of the operation. It must exist or have been initialized before the operation is performed. It is usually a temporary BLOB.

outArea

Geometry object that describes the extent of the output data.

outWindow

An SDO_NUMBER_ARRAY object that identifies the coordinates of the upper-left and lower-right corners of the output window in the cell space. For this function, the upper-left corner of the output window is always (0,0).

storageParam

A string specifying storage parameters, as explained in Storage Parameters. If this parameter is null, the resulting GeoRaster object has the same storage parameters (cellDepth, interleaving, and compression) as the first encountered source GeoRaster object in the model space (if applicable) or cell space.

If pyramid=true is specified, it is ignored for this procedure, but not for SDO_GEOR_AGGR.mosaicSubset.

If bitmapmask=true is specified, it is ignored for this procedure.

bgValues

Background cell values for filling partially empty raster blocks (full empty raster blocks are left as empty without filling). They are used to fill the empty areas resulted from the mosaicking operation, such as the areas that are outside of the clipping polygon or the gap areas not covered by any source images. (See alsoEmpty 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.

referenceImage

Specifies the reference image used during the color balance operation. If null, it defaults to the source image that is closest to the center of the output mosaic.

referenceValue1

Specifies the reference value or values used during the color balance operation. The meaning of the values is determined by the color balance method.

referenceValue2

Specifies the reference value or values used during the color balance operation. The meaning of the values is determined by the color balance method.

referenceHistograms

Specifies the reference histograms used during the color balance operation.

Usage Notes

The first two formats of the procedure provide the basic color balancing method and assume that the elevation of the output GeoRaster object is 0. The last two formats of the procedure provide more advanced color balancing method using the reference values or reference images, and they let you specify the elevation value for the output GeoRaster object.

The source GeoRaster objects must be prepared images or raster data so that they can be mosaicked. That is, the GeoRaster objects in the virtual mosaic must:

  • Not be a mixture of georeferenced and nongeoreferenced objects. Either all of the objects are georeferenced, or none of the objects is georeferenced.

  • Have the same number of layers or bands. There is no restriction on the row and column dimension sizes of the source objects.

If the GeoRaster objects to be mosaicked are georeferenced, they are co-located according to their georeferencing information. If the GeoRaster objects are not georeferenced, they are co-located according to their ULTCoordinate values. (The ULTCoordinate is explained in GeoRaster Data Model.)

The resulting GeoRaster object's spatial reference metadata information is determined by the outSRID and outResolutions parameters. If outSRID is not specified, the SRID of the first encountered source GeoRaster object is used. If outResolutions is not specified, the spatial resolution of the first encountered source GeoRaster object at thespecified pyramid level (pyramidLevel parameter) is used. The spatial resolution must be set in the metadata of all the source images.

If any source GeoRaster object has a different SRID from outSRID or is not rectified, it is dynamically reprojected or rectified so that the mosaicked GeoRaster object has uniform SRID and spatial resolution values.

If the source GeoRaster objects overlap, data of the overlapping area follows the rules specified in the mosaicParam parameter. By default, the cell value of the last encountered source GeoRaster object is used.

The source GeoRaster objects that contributes to the output mosaic are selected by the cropArea parameter spatially and  outResolutions parameter in resolution wise (resolution selection).

  • The cropArea parameter is used to query the source GeoRaster objects' spatial extents to determine the GeoRaster objects that are covered by the cropArea geometry; thus, a patial index should be built on the spatialExtent attribute of the GeoRaster objects.

  • The outResolutions parameter is used to find the source GeoRaster objects so that the outResolutions value is within the resolution range of the source GeoRaster objects. A GeoRaster object's spatial resolution range is determined by the resolution at pyramid level 0 and the resolution at the top pyramid level of the GeoRaster object. It is a half pyramid lower than the pyramid level 0 and a half pyramid level higher than the top pyramid level. For example, if a GeoRaster object has a resolution of 30 meters at pyramid level 0 and a resolution of 960 meters at the top pyramid level 5, this GeoRaster object’s spatial resolution range is between 22.5 meters ((30 + 30/2)/2) and 1440 meters ((960 + 960*2)/2).

The resolution selection using the outResolutions parameter can be speeded up by defining the columns MIN_X_RES$ and MAX_X_RES$ (both of type NUMBER) in the tables listed in the georasterTableNames parameter, where MIN_X_RES$ and MAX_X_RES$ specify the minimum and maximum spatial resolution values, respectively, of the source GeoRaster object. (A B-tree index should be created on the MIN_X_RES$ and MAX_X_RES$ columns if there are a large number of source GeoRaster objects.) To take advantage of this feature, the procedure format with the georasterTableNames parameter must be used. It also requires that the resolution values stored in the MIN_X_RES$ and MAX_X_RES$ columns have the same unit as the unit of the SRID that is stored in the source GeoRaster object’s spatialExtent attribute.

The resolution selection can be turned off by setting resFilter=false in the mosaicParam parameter. When the resolution selection is turned off, the source GeoRaster objects will only be filtered spatially.

If the source GeoRaster objects have empty raster blocks or do not cover the whole area, the empty areas are filled with the values specified in the bgValues parameter, or with 0 if the bgValues parameter is not specified.

In order to use the colorBalance option in mosaicParam, you should call SDO_GEOR.generateStatistics on the source images to generate the image's statistics and store them in the metadata for the source image.

If all source GeoRaster objects are blank and have the same blankCellValue value, the resulting rasterBlob is filled with the blankCellValue value.

For more information, see Virtual Mosaic.

Examples

The following example gets the subset of a virtual mosaic (defined as two GeoRaster tables) at SRID 32610 with resolution of 30 meters by specifying a cropArea window. NODATA is considered at the resampling process (if there is one) and at the overlapping area of the source images. 

declare
  lb blob;
  cropArea sdo_geometry;
  outArea  sdo_geometry := null;
  outWin   sdo_number_array:=null;
  resolutions sdo_number_array;
begin
    dbms_lob.createTemporary(lb, TRUE);
 
     cropArea :=  sdo_geometry(2003, 26986, null,                 
                    sdo_elem_info_array(1, 1003, 3), 
                    sdo_ordinate_array(399180, 4247820, 
                                       496140,4353900) );
      resolutions := sdo_number_array(30, 30);
     sdo_geor_aggr.getMosaicSubset('georaster_table_1, georaster_table_2', 
                 'georaster, georaster', 
                 0, 32610, null, null, cropArea,
                 null, null, null, resolutions, null, 
                 'nodata=true', 
                 lb, outArea, outWin);
    dbms_lob.freeTemporary(lb);
    if outWin is not null then
        dbms_output.put_line('output window: (' || outWin(1) || ',' || outWin(2) ||', ' || outWin(3) || ', ' || outWin(4) || ')');
    end if;
end;

Parent topic: SDO_GEOR_AGGR Package Reference