3 GeoRaster Operations

3.1 Creating the Standard GeoRaster DML Trigger

To ensure the consistency and integrity of internal GeoRaster tables and data structures, GeoRaster supplies a trigger that performs necessary actions after each of the following data manipulation language (DML) operations affecting a GeoRaster object: insertion of a row, update of a GeoRaster object, and deletion of a row. You must ensure that the trigger is used properly by calling the SDO_GEOR_UTL.createDMLTrigger procedure (described in Chapter 5) to create a trigger on each GeoRaster column in each GeoRaster table. For example, if a table contains two GeoRaster columns, you must call the SDO_GEOR_UTL.createDMLTrigger procedure twice (once for each combination of table name and GeoRaster column) before you perform any DML operations on the table.

You should create the necessary DML trigger or triggers immediately after you create a GeoRaster table, and you must create the trigger or triggers before you perform any operations on the table.

Each time you call the SDO_GEOR_UTL.createDMLTrigger procedure successfully, GeoRaster creates a trigger with a unique name. When you drop a GeoRaster table, all GeoRaster triggers associated with the table are automatically dropped also.

If you have created the GeoRaster DML trigger on a column, GeoRaster automatically performs the following actions when the trigger is fired as a result of a DML operation affecting that column:

• After an insert operation, the trigger inserts a row with the GeoRaster table name, GeoRaster column name, raster data table name, and rasterID value into the USER_SDO_GEOR_SYSDATA view (described in Section 2.4). If an identical entry already exists, an exception is raised.

• After an update operation, if the new GeoRaster object is null or empty, the trigger deletes the old GeoRaster object. If there is no entry in the USER_SDO_GEOR_SYSDATA view for the old GeoRaster object (that is, if the old GeoRaster object is null), the trigger inserts a row into that view for the new GeoRaster object. If there is an entry in the USER_SDO_GEOR_SYSDATA view for the old GeoRaster object, the trigger updates the information to reflect the new GeoRaster object.

• After a delete operation, the trigger deletes raster data blocks for the GeoRaster object in its raster data table, and it deletes the row in the USER_SDO_GEOR_SYSDATA view for the GeoRaster object.

3.2 Creating New GeoRaster Objects

Before you can store a GeoRaster image in a GeoRaster table, you must create the GeoRaster object. To create a new GeoRaster data object, you have the following options:

• Initialize an empty GeoRaster object, using the SDO_GEOR.init function.

• Create a blank GeoRaster object, using the SDO_GEOR.createBlank function.

You cannot perform any GeoRaster operations if the object has not been properly created (that is, if the object is an atomic null). The SDO_GEOR.init and SDO_GEOR.createBlank functions initialize GeoRaster objects with their raster data table and raster ID values if these are not already specified, and ensures that the raster data table name and raster ID value pair is unique for the current user.

If the new GeoRaster object will hold raster cell data (resulting from another GeoRaster procedure, such as SDO_GEOR.importFrom, SDO_GEOR.subset, or SDO_GEOR.copy), and if the raster data table for this new GeoRaster object does not exist, you must first create the raster data table. For information about creating a raster data table, see Section 1.4.1, especially Example 1-2.

To avoid potential GeoRaster data problems (some of which are described in Section 3.14), always register an initialized GeoRaster object in the GeoRaster system views by inserting the GeoRaster object into a GeoRaster table, and do this before you perform any other operations on the GeoRaster object.

3.3 Loading GeoRaster Data

To load GeoRaster data, you have the following options:

• Call the SDO_GEOR.importFrom procedure to load images into GeoRaster objects.

• Use the GeoRaster loader tool, which is described in Section 1.9.

3.4 Validating GeoRaster Objects

Before you use a GeoRaster object, you should ensure that it is valid. Validation for a GeoRaster object includes checking the metadata and the raster cell data, and making sure that they are consistent. For example, validation checks the raster type, dimension information, and the actual sizes of cell blocks, and it performs other checks.

If you used the GeoRaster loader tool described in Section 1.9, the GeoRaster objects were validated during the load operation.

GeoRaster provides the following validation subprograms:

• SDO_GEOR.validateGeoraster validates the GeoRaster object, including cell data and metadata. It returns TRUE if the object is valid; otherwise, it returns one of the following: an Oracle error code indicating why the GeoRaster object is invalid, FALSE if validation fails for an unknown reason, or NULL if the GeoRaster object is null. You should always use this function after you create a GeoRaster object.

• SDO_GEOR.schemaValidate validates the metadata against the GeoRaster XML schema. You can use this function to locate errors if the SDO_GEOR.validateGeoraster function returned the error code 13454. The SDO_GEOR.schemaValidate and SDO_GEOR.validateGeoraster functions do not validate the spatial extent geometry.

3.5 Georeferencing GeoRaster Objects

Georeferencing, as explained in Section 1.6, establishes the relationship between cell coordinates of GeoRaster data and real-world ground coordinates (or some local coordinates). If you need to georeference GeoRaster objects, the following approaches are available:

• If the original image is already georeferenced and if the georeferencing information is stored in an ESRI world file, you can use the SDO_GEOR.importFrom procedure to load an ESRI world file from a file or from a CLOB object, along with the image data itself (in either FILE or BLOB format). You can also use the GeoRaster client-side loader tool (described in Section 1.9) to load an ESRI world file from a file, along with the image file itself.

  Because an ESRI world file does not specify the model coordinate system, after loading a world file you can call the SDO_GEOR.setModelSRID procedure to set the model space of the georeferenced GeoRaster object using an Oracle SRID. You can also call this procedure to change the model space of a georeferenced GeoRaster object.

• You can use the SDO_GEOR.setSRS procedure to add, modify, and delete georeferencing information. For example, you can create an SDO_GEOR_SRS object and assign the coefficients and related georeferencing information, and then call the setSRS procedure to add or update the spatial reference information of any GeoRaster object. If you know that one GeoRaster object has the same SRS information as another GeoRaster object, you can call the SDO_GEOR.getSRS function to retrieve an SDO_GEOR_SRS object from this GeoRaster object, and then call the SDO_GEOR.setSRS procedure to georeference the first GeoRaster object.

• You can call the SDO_GEOR.georeference procedure to georeference a GeoRaster object directly. This function takes the coefficients A, B, C, D, E, F (described in a formula in Section 1.6.1) and other information, converts them into the coefficients a, b, c, d, e, f, and stores them in the spatial reference information of a GeoRaster object. If the original raster data is rectified and if the model coordinate of its origin (upper-left corner) is (x0, y0) and its spatial resolution or scale is s, then the following are true: A = s, B = 0, C = x0, D = 0, E = -s, F = y0.

Based on the SRS information of a georeferenced GeoRaster object, transforming GeoRaster coordinate information means finding the model (ground) coordinate associated with a specific cell (raster) coordinate, and vice versa. That is, you can do the following:

• Given a specific cell coordinate, you can find the associated model space coordinate using the SDO_GEOR.getModelCoordinate function. For example, if you identify a point in an image, you can find the longitude and latitude coordinates associated with that point.

• Given a model space coordinate, you can find the associated cell coordinate using the SDO_GEOR.getCellCoordinate function. For example, if you identify longitude and latitude coordinates, you can find the cell in an image associated with those coordinates.

3.6 Indexing GeoRaster Data

GeoRaster data can be indexed in various ways. The most important index you can create on a GeoRaster object is a spatial index on the spatial extent (footprint) geometry of the GeoRaster object (spatialExtent attribute, described in Section 2.1.2). For information about creating spatial indexes, see Oracle Spatial User's Guide and Reference.

You can also create one or more other indexes, such as:

• Function-based indexes on metadata objects using the Oracle XMLType or Oracle Text document indexing functionality

• Standard indexes on other user-defined columns of the GeoRaster table, such as cloud coverage, water coverage, or vegetation

In addition to any indexes that you may create, a B-tree index for Oracle internal use is built on each raster data table.

3.7 Changing Raster Storage

You can change some aspects of the way raster image data is stored: the raster blocking size, cell depth, interleaving type, and other aspects. To make such changes, use the SDO_GEOR.changeFormat or SDO_GEOR.changeFormatCopy procedure, and specify the desired storage parameter values with the storageParam parameter. You can also specify storage parameters with several other functions and procedures that load and process a GeoRaster object to create another GeoRaster object.

For information about the storage parameters that you can specify, see Section 1.4.1.

3.8 Querying and Updating GeoRaster Metadata

You can query metadata for a GeoRaster object, and you can update many attributes of the metadata.

You can use many functions, most of whose names start with get, to query the metadata and ancillary information (for example, SDO_GEOR.getTotalLayerNumber and SDO_GEOR.hasPseudoColor).

You can use several subprograms, most of whose names start with set, to update metadata and ancillary data (for example, SDO_GEOR.setSRS and SDO_GEOR.setColorMap).

See Section 1.8.4 for categories and lists of subprograms that get and set GeoRaster metadata and cell data.

3.9 Querying and Updating Cell Data

To display part or all of a raster image, you can query the data for a cell (pixel), a range of cells, or the entire image associated with a GeoRaster object:

• SDO_GEOR.getCellValue returns the value of a single cell of the GeoRaster object.

• SDO_GEOR.getRasterSubset returns a single BLOB object containing all cells of a precise subset of the GeoRaster object (as specified by a window, layer or band numbers, and pyramid level). This BLOB object contains only raster cells and no related metadata.

• SDO_GEOR.getRasterData creates a single BLOB object containing all cells of the GeoRaster object at a specified pyramid level. This BLOB object contains only raster cells and no related metadata.

• SDO_GEOR.getRasterBlocks returns an object that includes all image data inside or touching a specified window. Specifically, it returns an object of the SDO_RASTERSET collection type that identifies all blocks of a specified pyramid level that are inside or touch a specified window.

You can also use the SDO_GEOR.exportTo procedure to export all or part of a raster image to a BLOB object (binary image format) or to a file of a specified file format type.

To change the value of raster cells in a specified window to a single value, you can use the SDO_GEOR.changeCellValue procedure.

See Section 1.8.4 for categories and lists of subprograms that get and set GeoRaster metadata and cell data.

3.10 Processing GeoRaster Objects

You can perform a variety of processing operations on GeoRaster data, including changing the format, subsetting (cropping), scaling, and generating pyramids. See the GeoRaster PL/SQL demo files, described in Section 1.10, for examples and explanatory comments.

3.11 Viewing GeoRaster Objects

To view GeoRaster objects, you have the following options:

• Call the SDO_GEOR.exportTo procedure to export GeoRaster objects to image files, and then display the images using image tools or a Web browser.

• Use the standalone GeoRaster viewer provided with GeoRaster.

With the supplied standalone GeoRaster viewer, you can select any GeoRaster object of a database schema (user), query and display the whole or a subset of a GeoRaster object, zoom in and zoom out, pan, and perform other basic operations. The pyramid level, cell coordinates, and model coordinates (if the object is georeferenced) are displayed for the point at the mouse pointer location. You can display individual cell values and choose different layers of a multiband or hyperspectral image for RGB full color display. The blocking boundaries can be overlapped on the top of the display. Depending on the data and your requests, the viewer can display the raster data in grayscale, pseudocolor, and 24-bit true color over an intranet or the Internet. (For the current release, bitmap, two-dimensional grayscale, pseudocolor, and three-band full color are supported.) Some of the basic GeoRaster metadata is also displayed.

In the supplied standalone GeoRaster viewer, the data displayed by every operation is retrieved from the GeoRaster server; it is not generated in memory.

3.12 Exporting GeoRaster Objects

To export GeoRaster objects to image files, you have the following options:

• Call the SDO_GEOR.exportTo procedure (which allows you to export either to a file or a BLOB object).

• Use the GeoRaster exporter tool, described in Section 1.9.

3.13 Transferring GeoRaster Data Between Databases

You can use either the Data Pump Export and Import utilities (new for Oracle Database 10g Release 1) or the original Export and Import utilities to transfer GeoRaster data between databases. You must export and import rows from both the GeoRaster table and its related raster data table or tables at the same time. After the transfer, you may also need to insert the GeoRaster system data for the imported GeoRaster objects into the USER_SDO_GEOR_SYSDATA view (described in Section 2.4) in the target schema, and you should use the SDO_GEOR.validateGeoraster function to check the validity of imported GeoRaster objects.

For small data sets or where performance is not a concern, you can follow these steps:

1. Export and import the GeoRaster table and raster data table definitions (if they do not exist in the target schema). If you use the Data Pump Export and Import utilities, set CONTENT=METADATA_ONLY. If you use the original Export and Import utilities, set ROWS=N.

2. Export and import the GeoRaster object and raster data. If you use the Data Pump Export and Import utilities, set CONTENT=DATA_ONLY. If you use the original Export and Import utilities, set IGNORE=Y.

The preceding approach ensures that during the data import in Step 2, any GeoRaster-related DML triggers defined on a GeoRaster table are fired, thus automatically maintaining the GeoRaster system data in the target schema. However, Step 2 uses conventional loading, so performance is not optimal.

For large data sets where performance is a concern, you can use an approach that exports and imports table definitions and table data together. This approach requires you to maintain the GeoRaster system data in the target schema after the import operation. For the following steps, assume that Table mode is used for the export and import operations.

1. Create a table to hold all related GeoRaster system data. For example:

   CREATE TABLE tmp_sysdata_table
     AS SELECT * FROM user_sdo_geor_sysdata
       WHERE table_name='<table_to_be_exported>';
   
   

   In the preceding example, replace <table_to_be_exported> with the name of the GeoRaster table to be exported.

   If you use the QUERY parameter to filter the GeoRaster objects to be exported, add corresponding conditions in the WHERE clause in the preceding example to filter the GeoRaster system data as well.

   Perform the operation or operations in this step once for each source schema and target schema pair, because the USER_SDO_GEOR_SYSDATA view is schema-specific.

2. Export and import the table that you created in Step 1, together with GeoRaster tables and their related raster data tables.

3. Insert the rows in the table that you created in Step 1 back into the USER_SDO_GEOR_SYSDATA view in the target schema. For example:

   INSERT INTO user_sdo_geor_sysdata SELECT * FROM tmp_sysdata_table;
   
   

4. Drop the table that you created in Step 1.

In similar manner, if you export and import GeoRaster data using a mode other than Table mode (such as Full, Schema, Tablespace, or Transportable Tablespace), you must also maintain the GeoRaster system data in the target schema after the import operation.

The success of importing GeoRaster data into a target schema depends on there being no conflicts in the target schema's GeoRaster system data. That is, the pairs of raster data table name and raster ID to be inserted into the target schema's USER_SDO_GEOR_SYSDATA view must be unique. If a conflict occurs, you must modify one of the GeoRaster objects involved in the conflict in either the source or the target schema. To avoid moving data around, fixing a conflict usually means changing the raster ID of one GeoRaster object to another number. For example:

1. Find a raster ID that is not being used (in either the source or the target schema) in the raster data table involved in the conflict.

2. Modify one of the GeoRaster objects. For example:

   UPDATE georaster_table t SET t.georaster_col.rasterid=new_raster_id 
     WHERE t.georaster_col.rasterid=old_raster_id ;
   
   

After the UPDATE statement, if the required standard GeoRaster data manipulation language (DML) trigger has been created and enabled, the raster ID value shown in the USER_SDO_GEOR_SYSDATA view for the fixed GeoRaster object is updated correspondingly. You should validate the fixed GeoRaster object before performing a commit or any other operation.

If you import GeoRaster-related DML triggers with GeoRaster tables (as is usually the case), you should drop these triggers and re-create them using the SDO_GEOR_UTL.createDMLTrigger procedure after the import operation finishes. The GeoRaster-related DML triggers have names that start with GRDMLTR_.

3.14 Dealing with Possible GeoRaster Data Problems

If you do not perform GeoRaster operations in the required sequence, or if you perform an incorrect or inappropriate operation, some data problems can occur. For example:

• A nonblank GeoRaster object might have been created, but no rows or an incorrect number of rows exist in the raster data table for that object, or the raster data blocks associated with the object have an incorrect length.

• Raster data table rows might exist for a nonexistent GeoRaster object. The raster blocks associated with such rows are referred to as "dangling" blocks.

If a GeoRaster object is invalid because of a raster data error, delete the GeoRaster object and create it again.

If dangling raster blocks exist, they cause wasted disk space in the raster data table, although otherwise they do not present a problem as long as the necessary primary key is defined on the raster data table. If you want to remove the raster data table rows associated with dangling raster blocks, you can try to find rows associated with problems and to fix the problems. To find rows associated with problems, follow these steps:

1. To find out whether there is any dangling raster block data in a raster data table, issue a query of the following general form:

   SELECT unique rasterid FROM rdt_tab 
    WHERE rasterid NOT IN
          (SELECT RASTER_ID FROM USER_SDO_GEOR_SYSDATA
            WHERE RDT_TABLE_NAME=UPPER('rdt_tab'));
   
   

2. To find out whether the dangling raster block data actually belongs to some GeoRaster object in a GeoRaster table, issue a query of the following general form:

   SELECT t.georaster_col FROM georaster_tab t
    WHERE UPPER(t.georaster_col.rasterDataTable) = UPPER(‘rdt_name') AND
          t.georaster_col.rasterId = dangling_raster_id;
   
   

If multiple rows are returned from the preceding query, the GeoRaster-related DML trigger associated with this specific GeoRaster column is either missing or disabled and the returned GeoRaster objects are corrupted. In this case, the data is beyond repair. Delete the corrupted GeoRaster objects and clean up the dangling raster block data.

To remove the dangling raster block data from a raster data table, delete the rows associated with problems.

If no data is missing, you can manually repair a GeoRaster object by establishing the relationship between a GeoRaster object and some dangling raster block data. To do so, execute a statement of the following general form:

INSERT INTO USER_SDO_GEOR_SYSDATA 
   VALUES (‘georaster_table', ‘georaster_column', NULL, 
           ‘rdt_name', dangling_raster_id, NULL);

Always use the SDO_GEOR.validateGeoraster function to check the validity of a GeoRaster object after attempting any repair operation.