The SDO_GEOR_AGGR package contains subprograms (functions and procedures) for performing advanced large-scale mosaicking, appending, and virtual mosaic operations on GeoRaster objects. This chapter presents reference information, with one or more examples, for each subprogram.
SDO_GEOR_AGGR.append(
targetGeoRaster IN OUT SDO_GEORASTER,
sourceGeoRaster IN SDO_GEORASTER,
sourcePyramidLevel IN NUMBER,
appendParam IN VARCHAR2,
bgValues IN SDO_NUMBER_ARRAY DEFAULT NULL);
Appends the source GeoRaster object to the target GeoRaster object. Internal rectification, common point rules, gap filling, and color balancing are performed whenever necessary.
GeoRaster object to be updated. Cannot be the same as sourceGeoRaster. (Be sure to make a copy of this object before you update it.)
GeoRaster object to be appended to targetGeoRaster.
Pyramid level of the source GeoRaster object to be appended at the target GeoRaster object pyramid Level 0. If NULL, pyramid level 0 is used.
A comma-separated quoted string of keyword=value pairs for specifying parameters for the operation. It can contain one or more of the keywords in Table 8-1, "mosaicParam Keywords" in the SDO_GEOR_AGGR.mosaicSubset reference section.
If a nondefault value for colorBalance is specified, it is performed on the source GeoRaster object using the target GeoRaster object's statistics as the reference, and the following keywords (if specified) are ignored: maxVal, minVal, std, and min.
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 Section 1.4.4). 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.
Note:
Be sure to make a copy of thetargetGeoRaster object before you call this procedure, because the changes made to this GeoRaster object might not be reversible after the procedure completes.The source and target GeoRaster objects must have the same number of bands or layers. If the cell depths of the source and target GeoRaster objects are not the same, the cell value of the source GeoRaster object is either expanded or truncated to the cell depth of the target GeoRaster object.
The target GeoRaster object's raster data must be blocked.
There is no change on metadata of target GeoRaster object, except that the extent and the number of blocks are updated and the statistics are removed.
The source GeoRaster object is appended to the target GeoRaster object pyramid level 0. The pyramids of the target GeoRaster object are also updated.
The overlapping areas and gaps of the source and target GeoRaster objects are resolved according to the rules defined in the appendParam parameter.
The source GeoRaster object can be located on or touching any side of the target GeoRaster object (that is, it does not have to be on the right or bottom side). The target GeoRaster object will be automatically expanded accordingly.
The following example appends the GeoRaster object with georid = 2 to the GeoRaster object with at georid = 1.
declare
gr1 sdo_georaster;
gr1 sdo_georaster;
begin
select georaster into gr1 from georaster_table where georid = 1 for update;
select georaster into gr2 from georaster_table where georid = 2;
sdo_geor_aggr.append(gr1, gr2, 0, null);
update georaster_table set georaster = gr1 where georid= 1;
commit;
end;
/
SDO_GEOR_AGGR.getMosaicExtent(
inGeoRasters IN SYS_REFCURSOR,
outSRID IN NUMBER DEFAULT NULL
) RETURN SDO_GEOMETRY;
or
SDO_GEOR_AGGR.getMosaicExtent(
georasterTableNames IN VARCHAR2,
georasterColumnNames IN VARCHAR2,
outSRID IN NUMBER DEFAULT NULL
) RETURN SDO_GEOMETRY;
Calculates and returns the minimum bounding rectangle (MBR) of the spatial extent of a virtual mosaic or a collection of GeoRaster objects.
Source GeoRaster objects in a cursor.
Names (comma-separated) of the tables containing the source GeoRaster objects.
Names (comma-separated) of the columns of type SDO_GEORASTER in tables corresponding to the table names in georasterTableNames.
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 this parameter is null (the default), 4326 (EPSG SRID value for the WGS 84 (longitude/latitude) coordinate system) is used.
In calculating the spatial extent of a virtual mosaic or a collection of GeoRaster objects, this function tries to use the spatialExtent attribute of each GeoRaster object. If the spatialExtent attribute is null, the extent of the GeoRaster object is calculated based on the object's metadata.
The following example shows how to get the spatial extent when the virtual mosaic or the collection of GeoRaster objects is a cursor.
declare
cur sys_refcursor,
begin
open cur for select georaster from georaster_table_1 union all select georaster from georaster_table_2;
extent := sdo_geor_aggr.getMosaicExtent(cur, 26986);
close cur;
end;
/
The following example shows how to get the mosaic extent by specifying the table column names.
select sdo_geor_aggr.getMosaicExtent('georaster_table_1, georaster_table_2', 'georaster, georaster', 26986) from dual;
SDO_GEOR_AGGR.getMosaicResolutions(
inGeoRasters IN SYS_REFCURSOR,
resolutionUnit IN VARCHAR2 DEFAULT NULL
) RETURN SDO_RANGE_ARRAY;;
or
SDO_GEOR_AGGR.getMosaicResolutions(
georasterTableNames IN VARCHAR2,
georasterColumnNames IN VARCHAR2,
resolutionUnit IN VARCHAR2 DEFAULT NULL
) RETURN SDO_RANGE_ARRAY;
Returns the resolution range of a virtual mosaic or a collection of GeoRaster objects in a specified unit.
Source GeoRaster objects in a cursor.
Names (comma-separated) of the tables containing the source GeoRaster objects.
Names (comma-separated) of the columns of type SDO_GEORASTER in tables corresponding to the table names in georasterTableNames.
Unit of measure for the returned resolution range. If specified, it must be a quoted string in the format 'unit=value' where value is the unit name. If not specified or null, the returned resolution range is in the unit of meter.
The returned resolution range is in the format of SDO_RANGE_ARRAY(SDO_RANGE(min_x, max_x), SDO_RANGE(min_y, max_y)). where min_x, max_x are the minimum and maximum resolution on the x dimension, and min_y, max_y are the minimum and maximum resolution on the y dimension.
The SDO_RANGE_ARRAY type is defined as VARRAY(1048576) OF SDO_RANGE. The SDO_RANGE type is defined as:
Name Null? Type ----------------------------------------- -------- ------- LB NUMBER UB NUMBER
SDO_GEOR_AGGR.getMosaicSubset(
inGeoRasters IN SYS_REFCURSOR,
pyramidLevel IN NUMBER,
outSRID IN NUMBER,
outModelCoordLoc IN NUMBER,
referencePoint IN SDO_GEOMETRY,
cropArea IN SDO_GEOMETRY,
polygonClip IN VARCHAR2,
boundaryClip IN VARCHAR2,
layerNumbers IN VARCHAR2,
outResolutions IN SDO_NUMBER_ARRAY,
resolutionUnit IN VARCHAR2,
mosaicParam IN VARCHAR2,
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,
outSRID IN NUMBER,
outModelCoordLoc IN NUMBER,
referencePoint IN SDO_GEOMETRY,
cropArea IN SDO_GEOMETRY,
polygonClip IN VARCHAR2,
boundaryClip IN VARCHAR2,
layerNumbers IN VARCHAR2,
outResolutions IN SDO_NUMBER_ARRAY,
resolutionUnit IN VARCHAR2,
mosaicParam IN VARCHAR2,
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);
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.
Source GeoRaster objects in a cursor.
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 Section 5.16.5.1, "Improving Query Performance Using MIN_X_RES$ and MAX_X_RES$".
Names (comma-separated) of the columns of type SDO_GEORASTER in tables corresponding to the table names in georasterTableNames.
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.
Coordinate system for the output GeoRaster object. Must be either null or a value from the SRID column of the MDSYS.CS_SRS table.
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.
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.
Crop area definition. If the SDO_GEOMETRY object has a non-null SRID, the source GeoRaster objects must be georeferenced; otherwise, 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.
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.
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.
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.
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.
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. This parameter is ignored if outResolutions is null.
A comma-separated quoted string of keyword=value pairs for specifying mosaic parameters. It can contain one or more of the keywords in Table 8-1, "mosaicParam Keywords" in the SDO_GEOR_AGGR.mosaicSubset reference section.
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.
Geometry object that describes the extent of the output data.
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.
A string specifying storage parameters, as explained in Section 1.4.1. If this parameter is null, the resulting GeoRaster object has the same storage parameters (blockSize, cellDepth, interleaving, and compression) as the first encountered source GeoRaster object in the model space (if applicable) or cell space. However, it is recommended that you specify the storage parameters, particularly the blocking size, as appropriate for the size of the output mosaic, unless you want the mosaic to have the same storage parameters as those of the first encountered GeoRaster object to be mosaicked.
(If pyramid=true is specified, it is ignored for this procedure, but not for SDO_GEOR_AGGR.mosaicSubset.)
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 Section 1.4.4). 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.
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 Section 1.3.)
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 specified pyramid level (pyramidLevel parameter) is used. The spatial resolution must be set in the metadata of all the source images.
If pyramidLevel is specified but outResolutions is not specified, all the source GeoRaster objects are mosaicked using the raster data at the pyramid level specified by the pyramidLevel parameter. This parameter combination can be used when the source GeoRaster objects have the same spatial resolution at the pyramid level 0.
If outResolutions is specified, the source GeoRaster objects are mosaicked using the raster data at the pyramid level that has the closest resolution to the outResolutions parameter. If the value of the outResolutions parameter is not within a source GeoRaster object's spatial resolution range, this source GeoRaster object will not be involved in the mosaic. 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.
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 have empty raster blocks or do not cover the whole area, the mosaicked result GeoRaster object may have empty or partially empty raster blocks (see Section 1.4.4). A result raster block that is not covered by any of the source GeoRaster objects is kept empty. Any partially empty raster blocks are filled with the values specified in the bgValues parameter, or with 0 if the bgValues parameter is not specified.
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 maximum number of allowable overlapping GeoRaster objects at the specified resolution is 8.
Any bitmap masks associated with the source GeoRaster objects are not considered, and the bitmapmask parameter is ignored if it is specified in the storageParam string.
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. The current color balancing methods work well only with certain types of source images, such as images with contrast or brightness differences only.
If all source GeoRaster objects are blank and have the same blankCellValue value, the resulting GeoRaster object is blank and has that blankCellValue value; otherwise, the resulting GeoRaster object is not blank.
When the source GeoRaster objects have different spatial resolution ranges, you can define the columns MIN_X_RES$ and MAX_X_RES$ (both of type NUMBER) in the tables listed in georasterTableNames parameter, where MIN_X_RES$ and MAX_X_RES$ specify the minimum and maximum spatial resolution values, respectively, of the source GeoRaster object. The procedure uses the resolution range stored in these columns to filter out the source GeoRaster objects that are not at the requested resolutions as specified in the outResolutions parameter. This improves the performance of the procedure when there are many overlapping source GeoRaster objects with different spatial resolution ranges.
To use the MIN_X_RES$ and MAX_X_RES$ column values:
The procedure format with the georasterTableNames parameter must be used.
The outResolutions parameter must not be null.
The resolution values in the MIN_X_RES$ and MAX_X_RES$ columns must be in the same unit as the resolution value specified in the outResolutions parameter.
For more information, see Section 5.16, "Virtual Mosaic".
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;
SDO_GEOR_AGGR.mosaicSubset(
inGeoRasters IN SYS_REFCURSOR,
pyramidLevel IN NUMBER,
outSRID IN NUMBER,
outModelCoordLoc IN NUMBER,
referencePoint IN SDO_GEOMETRY,
cropArea IN SDO_GEOMETRY,
polygonClip IN VARCHAR2,
boundaryClip IN VARCHAR2,
layerNumbers IN VARCHAR2,
outResolutions IN SDO_NUMBER_ARRAY,
resolutionUnit IN VARCHAR2,
mosaicParam IN VARCHAR2,
storageParam IN VARCHAR2,
outGeoRaster IN OUT SDO_GEORASTER,
bgValues IN SDO_NUMBER_ARRAY DEFAULT NULL,
parallelParam IN VARCHAR2 DEFAULT NULL);
or
SDO_GEOR_AGGR.mosaicSubset(
georasterTableNames IN VARCHAR2,
georasterColumnNames IN VARCHAR2,
pyramidLevel IN NUMBER,
outSRID IN NUMBER,
outModelCoordLoc IN NUMBER,
referencePoint IN SDO_GEOMETRY,
cropArea IN SDO_GEOMETRY,
polygonClip IN VARCHAR2,
boundaryClip IN VARCHAR2,
layerNumbers IN VARCHAR2,
outResolutions IN SDO_NUMBER_ARRAY,
resolutionUnit IN VARCHAR2,
mosaicParam IN VARCHAR2,
storageParam IN VARCHAR2,
outGeoRaster IN OUT SDO_GEORASTER,
bgValues IN SDO_NUMBER_ARRAY DEFAULT NULL,
parallelParam IN VARCHAR2 DEFAULT NULL);
Performs advanced large-scale mosaicking or subsetting from a virtual mosaic or a collection of GeoRaster objects. The output data is written into a GeoRaster object for persistent storage or other processing. Internal rectification, common point rules, gap filling, and color balancing are performed whenever necessary.
Source GeoRaster objects in a cursor.
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 Section 5.16.5.1, "Improving Query Performance Using MIN_X_RES$ and MAX_X_RES$".
Names (comma-separated) of the columns of type SDO_GEORASTER in tables corresponding to the table names in georasterTableNames.
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.
Coordinate system for the output GeoRaster object. Must be either null or a value from the SRID column of the MDSYS.CS_SRS table.
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.
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.
Crop area definition. If the SDO_GEOMETRY object has a non-null SRID, the source GeoRaster objects must be georeferenced; otherwise, 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.
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.
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
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.
Resolution of the output GeoRaster data. If null, the default is the resolution of the first encountered GeoRaster object. See the Usage Notes for details.
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. This parameter is ignored if outResolutions is null.
A comma-separated quoted string of keyword=value pairs for specifying mosaic parameters. It can contain one or more of the keywords in Table 8-1.
Note:
For any numbers in string (VARCHAR2) parameters to GeoRaster subprograms, the period (.) must be used for any decimal points regardless of the locale.Table 8-1 mosaicParam Keywords
| Keyword | Explanation |
|---|---|
|
Specifies the method for color balancing. Can have one of the following values:
|
|
|
Specifies the method for getting the cell value at the overlapping area. Can have one of the following values:
|
|
|
Specifies whether or not to fill the narrow gap between source images. |
|
|
Ignored if |
|
|
Ignored if |
|
|
Ignored if |
|
|
Specifies whether or not to consider NODATA (NODATA value or NODATA bitmap mask) when handling the overlap area. The default value is |
|
|
Specifies the resampling method (if resampling is involved or rectification is needed) to be used during the mosaic operation. Can have one of the following values: |
|
|
Specifies the tolerance for not doing resampling when the source GeoRaster objects are not perfectly aligned. The value should be between 0 and 0.5, where the unit is pixel or cell (for example, |
|
|
Specifies whether or not to filter the source GeoRaster objects to select only the GeoRaster object that is in the range of the output resolution ( |
|
|
Ignored if |
A string specifying storage parameters, as explained in Section 1.4.1. If this parameter is null, the resulting GeoRaster object has the same storage parameters (blockSize, cellDepth, interleaving, and compression) as the first encountered source GeoRaster object in the model space (if applicable) or cell space. However, it is recommended that you specify the storage parameters, particularly the blocking size, as appropriate for the size of the output mosaic, unless you want the mosaic to have the same storage parameters as those of the first encountered GeoRaster object to be mosaicked.
If pyramid=true is specified, the pyramids of the source GeoRaster objects are mosaicked when the outResolutions parameter is null and the pyramidLevel parameter is not null. The maximum pyramid level of the result GeoRaster object is the minimal value of the maximum pyramid level of the source GeoRaster objects. By default, the pyramids are not mosaicked.
If bitmapmask=true is specified, the bitmap masks of the source GeoRaster objects are mosaicked also.
GeoRaster object to hold the result of the operation. Cannot be the same as any source GeoRaster object.
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 Section 1.4.4). 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.
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 Section 1.13, "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 mosaicked GeoRaster object explicitly in order to roll back the operation.
The source GeoRaster objects must be prepared images or raster data so that they can be mosaicked. That is, the GeoRaster objects to be mosaicked 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 Section 1.3.)
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 specified pyramid level (pyramidLevel parameter) is used. The spatial resolution must be set in the metadata of all the source images.
If pyramidLevel is specified but outResolutions is not specified, all the source GeoRaster objects are mosaicked using the raster data at the pyramid level specified by the pyramidLevel parameter. This parameter combination can be used when the source GeoRaster objects have the same spatial resolution at the pyramid level 0. The option pyramid=true in the storageParam parameter is valid only in this parameter combination.
If outResolutions is specified, the source GeoRaster objects are mosaicked using the raster data at the pyramid level that has the closest resolution to the outResolutions parameter. If the value of the outResolutions parameter is not within a source GeoRaster object's spatial resolution range, this source GeoRaster object will not be involved in the mosaic. 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.
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 have empty raster blocks or do not cover the whole area, the mosaicked result GeoRaster object may have empty or partially empty raster blocks (see Section 1.4.4). A result raster block that is not covered by any of the source GeoRaster objects is kept empty. Any partially empty raster blocks are filled with the values specified in the bgValues parameter, or with 0 if the bgValues parameter is not specified.
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 maximum number of allowable overlapping GeoRaster objects at the specified resolution is 8.
If the bitmapmask parameter is set to true in the storageParam string, the bitmap masks are also mosaicked. Otherwise, the bitmap masks are not mosaciked. Note that the bitmap mask may also be considered as NODATA; and if they are, see the NODATA keyword in Table 8-1, "mosaicParam Keywords".
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. The current color balancing methods work well only with certain types of source images, such as images with contrast or brightness differences only.
If all source GeoRaster objects are blank and have the same blankCellValue value, the resulting GeoRaster object is blank and has that blankCellValue value; otherwise, the resulting GeoRaster object is not blank.
The GeoRaster object to contain the results of the mosaic operation (georaster parameter) must not be any of the source GeoRaster objects (the objects on which the mosaic operation is performed).
When the source GeoRaster objects have different spatial resolution ranges, you can define the columns MIN_X_RES$ and MAX_X_RES$ (both of type NUMBER) in the tables listed in georasterTableNames parameter, where MIN_X_RES$ and MAX_X_RES$ specify the minimum and maximum spatial resolution values, respectively, of the source GeoRaster object. The procedure uses the resolution range stored in these columns to filter out the source GeoRaster objects that are not at the requested resolutions as specified in the outResolutions parameter. This improves the performance of the procedure when there are many overlapping source GeoRaster objects with different spatial resolution ranges. (To use this feature, the resFilter keyword value in the mosaicParam parameter must be TRUE, which is the default).
To use the MIN_X_RES$ and MAX_X_RES$ column values:
The procedure format with the georasterTableNames parameter must be used.
The outResolutions parameter must not be null.
The resolution values in the MIN_X_RES$ and MAX_X_RES$ columns must be in the same unit as the resolution value specified in the outResolutions parameter.
The mosaic operation performs internal commit operations at regular intervals, and thus it cannot be rolled back. If the operation is interrupted, dangling raster blocks may exist in the raster data table. You can handle dangling raster blocks by maintaining GeoRaster objects and system data in the database, as explained in Section 3.25.
For more information, see Section 5.15, "Large-Scale Image Mosaicking" and Section 5.16, "Virtual Mosaic".
The following example creates a mosaicked GeoRaster object. The referencePoint parameter aligns the output GeoRaster image, and 'commonPointRule=average' indicates how to handle the overlapping area. The parallelParam parameter enables parallel processing during the mosaic operation.
declare
referencePoint sdo_geometry;
resolutions sdo_number_array;
gr sdo_georaster;
begin
insert into georaster_table (georid, georaster)
values (10, sdo_geor.init('RDT_1',10))
returning georaster into gr;
referencePoint := sdo_geometry(2001, 26986, sdo_point_type(399180, 4247820), null, null);
resolutions := sdo_number_array(30, 30);
sdo_geor_aggr.MosaicSubset('georaster_table_1, georaster_table_2',
'georaster, georaster',
0, 32610, null, referencePoint, null,
null, null, null, resolutions, null,
'commonPointRule=average',
'blocksize=(512, 512, 3)', gr, null, 'parallel=4');
update georaster_table set georaster = gr where georid=10;
commit;
end;
/
SDO_GEOR_AGGR.validateForMosaicSubset(
inGeoRasters IN SYS_REFCURSOR,
outSRID IN NUMBER,
outResolutions IN SDO_NUMBER_ARRAY,
resolutionUnit IN VARCHAR2,
resultTableName IN VARCHAR2);
or
SDO_GEOR_AGGR.validateForMosaicSubset(
georasterTableNames IN VARCHAR2,
georasterColumnNames IN VARCHAR2,
outSRID IN NUMBER,
outResolutions IN SDO_NUMBER_ARRAY,
resolutionUnit IN VARCHAR2,
resultTableName IN VARCHAR2);
Checks if it is feasible to do mosaicking or subset query operations over a virtual mosaic or a large collection of GeoRaster objects. Any validation errors and notes are stored in a user-created result table.
Source GeoRaster objects in a cursor.
Names (comma-separated) of the tables containing the source GeoRaster objects.
Names (comma-separated) of the columns of type SDO_GEORASTER in tables corresponding to the table names in georasterTableNames.
Coordinate system for the output GeoRaster object. Must be either null or a value from the SRID column of the MDSYS.CS_SRS table.
Resolution of the output GeoRaster data. If null, the default is the resolution of the first encountered source GeoRaster object.
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. This parameter is ignored if outResolutions is null.
Name of the validation result table. This table must already exist, and it must have the following column definitions:
time timestamp, type varchar2(16), description varchar2(512), table_name varchar2(32), column_name varchar2(1024), rdt_table_name varchar2(32), raster_id number
The following considerations apply to the resultTableName parameter value:
If the specified table does not exist, an error is generated.
If the parameter is not specified or is specified as null, the procedure throws an error at the first validation error found; otherwise, the procedure puts all the validation errors in the table and completes without error.
If the specified table is not empty, the procedure appends rows to the existing data in the table; and if there is a unique constraint on any column and if the newly appended data has the same value as existing data in that constrained column, an error is generated.
The TYPE column of the table contains a string indicating the type of issue, such as ERROR (something that must be fixed) or NOTE (information that may or may not require some action). The DESCRIPTION column provides details about the issue.
This procedure performs the following validation checks:
The source GeoRaster objects must have the same band dimension size.
The source GeoRaster objects must have consistent georeference status, that is, either all are georeferenced or all are not georeferenced.
If reprojection or rectification to be performed when doing the mosaic, the operation must be feasible.
The output spatial reference system must be an affine transformation. The output SRS is determined by either the input parameters (outSRID, outResolutions, resolutionUnit) or the first source GeoRaster object.
The following example checks if a mosaic operation is possible. Any validation errors are stored in the predefined table MOSAIC_ERROR.
EXECUTE sdo_geor_aggr.validateForMosaicSubset('georaster_table_1, georaster_table_2', 'georaster, georaster', 26986, sdo_number_array(30, 30), 'unit=meter', 'mosaic_error');
-- Check the validation results:
SELECT table_name table, column_name column, rdt_table_name rdt, raster_id rid, type, description FROM mosaic_error ORDER BY time;
TABLE COLUMN RDT RID TYPE DESCRIPTION
---------- -------- ----- --- ----- ----------------------------------------
GEORASTER_1 GEORASTER RDT_1 2 ERROR The source georaster object is not georeferenced.