Virtual Mosaic

6.18 Virtual Mosaic

A virtual mosaic treats a set of GeoRaster images as one large virtually mosaicked image.

For some applications, mosaicking a collection of images into a single physical mosaic is not necessary or desirable. For example, you might not have enough disk space for storing the mosaic separately or you simply want to save disk space. Another example is if you do not want to keep two identical copies of the same data set but prefer to have the original data set stored as is, such as a DEM data set, yet you want to query over this data set seamlessly. Yet another example is if you want to apply different processing and mosaicking rules for the same region when mosaicking the source images -- a physical mosaic has no such flexibility.

In such cases, instead of mosaicking a set of GeoRaster images into one large GeoRaster image and storing it in a GeoRaster table, you can create a virtual mosaic. A virtual mosaic treats a set of GeoRaster images as one large virtually mosaicked image, without storing it in a GeoRaster table.

In GeoRaster, a virtual mosaic is defined as any large collection of georeferenced GeoRaster objects, rectified or unrectified, from one or more GeoRaster tables or views that is treated as if it is a single GeoRaster object. Pyramids of virtual mosaic are supported. A virtual mosaic can contain unlimited number of images, and a whole GeoRaster database can be treated as a virtual mosaic. You issue a single call to query the virtual mosaic based on area-of-interest (that is, subsetting or cropping), and you can request the cropped images to be in different coordinate system with different resolutions. On-the-fly transformations with resampling and mosaicking with common point rules, based on user requests, are done internally and automatically during the query processes.

The following are ways to define a virtual mosaic:

As a GeoRaster table or a list of GeoRaster tables (see Virtual Mosaic as One or a List of GeoRaster Tables)
As a database view with a GeoRaster column (see Virtual Mosaic as a View with a GeoRaster Column)
As a SQL query statement (a cursor) that results in a collection of GeoRaster objects (see Virtual Mosaic as a SQL Query Statement or a Cursor)

Regardless of how the virtual mosaic is defined, the GeoRaster objects in the GeoRaster tables must have the spatialExtent attribute generated or set; otherwise, the SDO_GEOR_AGGR.getMosaicSubset and SDO_GEOR_AGGR.mosaicSubset procedures return an empty lob locator or empty GeoRaster object. For general use cases and best query performance, you should always create a spatial index beforehand on the spatialExtent attribute.

After a virtual mosaic is defined, you can use these procedures to query or process it:

SDO_GEOR_AGGR.getMosaicSubset to perform on-the-fly queries over the virtual mosaic

In spatial query of any portion of that virtually mosaicked image, the SDO_GEOR_AGGR.getMosaicSubset procedure performs the mosaic operation dynamically for the queried area and returns the required result in a BLOB on-the-fly, as if it were subsetting a physically stored mosaicked image.
SDO_GEOR_AGGR.mosaicSubset to store the mosaicked subset in the database as a GeoRaster object

The SDO_GEOR_AGGR.mosaicSubset procedure performs the mosaic operation for the queried area and stores the required result in another GeoRaster object persistently

For a typical workflow of using virtual mosaic, see Using Virtual Mosaic in Applications, and Special Considerations for Large-Scale Virtual Mosaic and its related topic Improving Query Performance Using MIN_X_RES$ and MAX_X_RES$.

Parent topic: Image Processing and Virtual Mosaic

6.18.1 Virtual Mosaic as One or a List of GeoRaster Tables

A virtual mosaic can be defined as one GeoRaster table or a list of GeoRaster tables. Applications specify each table and its GeoRaster column. In this approach, all GeoRaster objects in the specified GeoRaster columns of those GeoRaster tables are part of the virtual mosaic.

Example 6-25 specifies the source images for virtual mosaicking in a list of GeoRaster tables (GRTAB1, GRTAB2, and GRTAB3, which have the same definitions as GRTAB in Large-Scale Image Mosaicking).

Example 6-25 Virtual Mosaic as a List of GeoRaster Tables

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, 32610, 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('grtab1, grtab2, grtab3', 
                 'grobj, grobj, grobj', 
                 0, 32610, null, null, cropArea,
                 null, null, null, resolutions, null, 
                 'commonPointRule = end, 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: Virtual Mosaic

6.18.2 Virtual Mosaic as a View with a GeoRaster Column

A virtual mosaic can be defined as one database view with a GeoRaster column. Applications specify the view name and its GeoRaster column. In this approach, all GeoRaster objects in the specified GeoRaster column of the view are part of the virtual mosaic. This approach allows you to select the images for the virtual mosaic in complex ways from any number of GeoRaster tables, taking advantage of the spatial index and any other relevant indexes.

You can also define a virtual mosaic as a list combining GeoRaster views and GeoRaster tables.

When a virtual mosaic is defined as a database view, the view can be specified in the georasterTableNames parameter when you query it. Example 6-26 queries the virtual mosaic defined as a view. Note that in this example, the queries sort the images based on their creation time and pick the latest (newest) image for the resulting mosaic in the overlapping areas.

Example 6-26 Using a View on GeoRaster Tables for Virtual Mosaic

Create or replace view grview as select * from (
       Select grobj, last_update from grtab1 where cloud_cover=0 union all
       Select grobj, last_update from grtab2 where cloud_cover=0 union all
       Select grobj, last_update from grtab3 ) order by last_update;

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, 32610, 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('grview', 'grobj', 
                 0, 32610, null, null, cropArea,
                 null, null, null, resolutions, null, 
                 'commonPointRule = end, 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: Virtual Mosaic

6.18.3 Virtual Mosaic as a SQL Query Statement or a Cursor

Instead of creating a view, you can define a virtual mosaic as a SQL statement or a runtime database cursor, which selects a collection of GeoRaster objects from the database. Applications create the cursor from the SQL statement and use the cursor as the virtual mosaic. In this definition, all GeoRaster objects in the cursor are part of the virtual mosaic. This approach allows you to select the images for the virtual mosaic in complex ways from any number of GeoRaster tables. However, the spatial indexes are not automatically used in queries over this type of virtual mosaic. To take advantage of spatial indexes, dynamically add a spatial query condition directly using the query window to the SQL statement, so that all images in that query window can be more quickly located.

The SDO_GEOR_AGGR.getMosaicSubset and SDO_GEOR_AGGR.mosaicSubsetprocedures accept a cursor of GeoRaster objects as the virtual mosaic, as shown in Example 6-27. Note that in this example, the queries sort the images based on their creation time and pick the latest (newest) image for the resulting mosaic in the overlapping areas. For best performance when there are many GeoRaster objects in the table, the query of the cursor should use the spatial query window to filter out the unrelated GeoRaster objects, as described in the preceding paragraph.

Example 6-27 Using a Cursor for Virtual Mosaic

DECLARE
  lb blob;
  outArea  sdo_geometry := null;
  outWin   sdo_number_array:=null;
  resolutions sdo_number_array;
  mosaic_stmt  varchar2(1000);
  condition        varchar2(1000);
BEGIN
    dbms_lob.createTemporary(lb, TRUE);
 
    resolutions := sdo_number_array(30, 30);
 
   -- Define the query window (cropArea)
   cropArea := sdo_geometry(2003, 32610, null, 
                           sdo_elem_info_array(1, 1003, 3), 
                           sdo_ordinate_array(399180, 4247820, 496140,4353900) );
 
    -- Define the virtual mosaic
    mosaic_stmt := 'select grobj from (select grobj, last_update from grtab1 ' ||
                   'where cloud_cover=0  union all select grobj, last_update from grtab2 ' ||
                   'where cloud_cover=0) t ';
 
   -- Apply filtering using the query window (cropArea) to speed up query performance
    condition := 'where sdo_anyinteract(t.grobj.spatialExtent,:1) = ''true'' ' ||
                 ' order by last_update'; 
 
   -- Open the virtual mosaic for query
    open cur for mosaic_stmt || condition using cropArea;
 
   -- Query the virtual mosaic (make sure the cropArea used here is the same
   -- as the one used at opening the cursor)
    sdo_geor_aggr.getMosaicSubset(cur, 
                 0, 32610, null, null, cropArea,
                 null, null, null, resolutions, null, 
                 'commonPointRule=end, nodata=true', 
                 lb, outArea, outWin);
    dbms_lob.freeTemporary(lb);
    close cur;
    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: Virtual Mosaic

6.18.4 Using Virtual Mosaic in Applications

Virtual mosaic can be used as an image serving engine and in a variety of other application scenarios. The definitions of virtual mosaics can be stored by applications separately as strings or other forms. Besides the major query procedures SDO_GEOR_AGGR.getMosaicSubset and SDO_GEOR_AGGR.mosaicSubset, GeoRaster provides other subprograms in the SDO_GEOR_AGGR package to facilitate application development:

SDO_GEOR_AGGR.validateForMosaicSubset, SDO_GEOR_AGGR.getMosaicExtent, and SDO_GEOR_AGGR.getMosaicResolutions can be called in an application to make sure that the virtual mosaic is valid and that the spatial query falls inside the virtual mosaic. The following steps describe a possible workflow for virtual mosaic in an application:

Define a virtual mosaic. For example:
```
Create or replace view grview as select * from (
Select grobj, last_update from grtab1 where cloud_cover=0 union all
Select grobj, last_update from grtab2 where cloud_cover=0 union all
Select grobj, last_update from grtab3 ) order by last_update;
```
Note that tables GRTAB1, GRTAB2, and GRTAB3 were created using the same definition as GRTAB in Large-Scale Image Mosaicking, and Oracle Spatial spatial indexes have been created on the spatialExtent attribute of the GeoRaster object in these tables.
Validate the virtual mosaic data set. For example:
```
EXECUTE SDO_GEOR_AGGR.validateForMosaicSubset('grview', 'grobj', OUTSRID, OUTResolutions);
```
A validation error table can be created and passed to the call if more detailed validation information is needed. See the SDO_GEOR_AGGR.validateForMosaicSubset reference section for details.

Get the spatial extent of the virtual mosaic. For example:

SELECT SDO_GEOR_AGGR.getMosaicExtent('grview', 'grobj', OUTSRID) from dual;

Get the resolution range of the existing source images. For example:
```
SELECT SDO_GEOR_AGGR.getMosaicResolutions('grview', 'grobj', 'unit=meter') from dual;
```
The resolution range reflects the minimum and maximum resolutions of the source images, including all pyramid levels.
Based on the information acquired in the preceding two steps, pass in the spatial query window cropArea and OUTResolutions according to the application requests to get a subset of the virtual mosaic and optionally to apply different resampling methods, different common point rules, special nodata handling, and color balancing. For example:
```
SDO_GEOR_AGGR.getMosaicSubset('grview', 'grobj', null, OUTSRID, null, null,
  cropArea, null, null, null, OUTResolutions, null, 
  'commonPointRule=end, nodata=true', lb, outArea, outWin);
```
Note that OUTResolutions must be within the source image resolution range. If OUTResolutions is the same as the resolutions of the source image at a specified pyramid level, the pyramid data is used in the output mosaic; otherwise, the source image is scaled to the target resolution.

A typical application repeatedly applies this step to query different areas of interest over the same virtual mosaic for image display, image distribution, or other purposes.

Parent topic: Virtual Mosaic

6.18.5 Special Considerations for Large-Scale Virtual Mosaic

A virtual mosaic can contain just several images, but it can also contain tens of thousands or millions of images. Both SDO_GEOR_AGGR.getMosaicSubset and SDO_GEOR_AGGR.mosaicSubset automatically search (using native spatial indexes) the virtual mosaic for all images touching or inside the cropArea and check the resolutions of those images and their pyramids. Only those images or their appropriate pyramid levels touching or inside the cropArea and with their resolutions close to the requested resolution will be used in the mosaicking process. So, the configuration of the source images and their pyramids is critical for the quality of the results and the overall query performance.

The guideline is to avoid too many small images from either different source images or their pyramids in the requested crop areas at the requested resolution.

For a smaller virtual mosaic with only a limited number of images, simply generate full pyramids for each source image, and the query performance will be good for most applications.

For a large area with a larger number of images (more than a few hundred images), the application can generate only a certain number of pyramid levels for each source image, mosaic their top pyramids into new GeoRaster objects, and then generate pyramids for those mosaics, and so forth. For large-scale web visualization projects, all images at source resolutions and at lower resolution levels might be stored as GeoRaster objects without any pyramids built for them.

In these cases (large number of images and large-scale web visualization), if each source image is small and there are many resolution levels in the virtual mosaic, a query on the lower resolution levels would involve metadata resolution queries on many unnecessary images at the higher resolution levels, which slows the query. To improve performance, applications can define many virtual mosaics, each of which includes only all the images at a specific resolution or a few resolution levels. Then, the application finds the right virtual mosaic or mosaics based on the requested resolution as the first step, and then only spatially queries those selected virtual mosaics. This approach can significantly improve performance.

In addition to the preceding considerations, see Improving Query Performance Using MIN_X_RES$ and MAX_X_RES$ for queries where many different resolution levels are involved for the same area.

Improving Query Performance Using MIN_X_RES$ and MAX_X_RES$

Parent topic: Virtual Mosaic

6.18.5.1 Improving Query Performance Using MIN_X_RES$ and MAX_X_RES$

A more general solution (instead of defining multiple virtual mosaics) for speeding virtual mosaic queries if there are many different resolution levels involved for the same area is to use the resolution range columns (MIN_X_RES$ and MAX_X_RES$) in the GeoRaster tables or views. You must define these columns (NUMBER data type) in the GeoRaster tables of a virtual mosaic, where they specify the minimum and maximum spatial resolution values, respectively, of the source GeoRaster object. After these columns are added and populated with correct resolution data, the SDO_GEOR_AGGR.getMosaicSubset procedure will (if you use the format with the georasterTableNames parameter) use 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 avoids parsing the metadata of each GeoRaster objects in the cropArea, thus significantly improving performance.

To use this approach, follow these steps:

Add the columns MIN_X_RES$ and MAX_X_RES$ to the GeoRaster tables. For example:
```
ALTER TABLE georaster_table ADD (MIN_X_RES$ number, MAX_X_RES$ number);
```

Populate the MIN_X_RES$ column. For example:

UPDATE georaster_table t 
  SET min_x_res$ = (select column_value from the
    (select sdo_geor.generateSpatialResolutions(t.georaster, null,
    t.georaster.spatialextent.sdo_srid) from dual)
  WHERE rownum=1);

Populate the MAX_X_RES$ column. For example:

UPDATE georaster_table t 
  max_x_res$ = min_x_res$ * power(2, sdo_geor.getPyramidMaxLevel(t.georaster));

Optionally, create index on the resolution range columns if the table contains large number of source images:
```
CREATE INDEX georaster_table_res_idx ON georaster_table(MIN_X_RES$, MAX_X_RES$);
```

If the virtual mosaic is defined as a view, the view should also have both columns. For example, the view definition in Example 6-26 must be changed to the following:

Create or replace view grview as select * from ( 
       Select grobj, min_x_res$, max_x_res$, last_update from grtab1 where cloud_cover=0 union all
       Select grobj, min_x_res$, max_x_res$, last_update from grtab2 where cloud_cover=0 union all 
       Select grobj, min_x_res$, max_x_res$, last_update from grtab3 ) 
       order by last_update;

After a virtual mosaic is defined as described in this section, applications can query and use it in the same ways as with all other virtual mosaics, but with better performance for large-scale virtual mosaics that involve many resolution levels. For more information, see the SDO_GEOR_AGGR.getMosaicSubset and SDO_GEOR_AGGR.mosaicSubset reference sections.

Parent topic: Special Considerations for Large-Scale Virtual Mosaic