|Oracle® Spatial GeoRaster
10g Release 1 (10.1)
Part Number B10827-01
This chapter describes how to perform the main kinds of GeoRaster operations. A typical GeoRaster workflow consists of most or all of the following steps:
Create the GeoRaster table, raster data table, and standard GeoRaster DML trigger (see Section 3.1 about the DML trigger).
Initialize or create GeoRaster objects (see Section 3.2).
Load raster imagery or grids (see Section 3.3).
Validate GeoRaster objects, if they have not already been validated (see Section 3.4).
Georeference the GeoRaster objects, if necessary (see Section 3.5).
Create spatial indexes or other indexes, or both (see Section 3.6).
Change the GeoRaster storage format, if necessary (see Section 3.7).
Query and update the GeoRaster metadata (see Section 3.8).
Query and update cell data (see Section 3.9).
Process GeoRaster objects (see Section 3.10).
View GeoRaster objects (see Section 3.11).
Export GeoRaster objects (see Section 3.12).
Transfer GeoRaster data between databases (see Section 3.13).
If necessary, deal with possible GeoRaster data problems (see Section 3.14).
After you create the GeoRaster objects, load the data, and validate the GeoRaster objects, you can perform the remaining operations in any order, depending on your application needs. You may also be able to skip certain operations.
Some operations can be performed using SQL, and some operations must be performed using PL/SQL blocks. For examples of these operations, see the demo files described in Section 1.10 and the examples in Chapter 4.
This chapter contains the sections that explain the main kinds of GeoRaster operations.
Chapter 4 contains detailed reference information about the SDO_GEOR package, which contains subprograms (functions and procedures) to work with GeoRaster data and metadata.
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.
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.
To load GeoRaster data, you have the following options:
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.
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
F (described in a formula in Section 1.6.1) and other information, converts them into the coefficients
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.
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.
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.
You can query metadata for a GeoRaster object, and you can update many attributes of the metadata.
See Section 1.8.4 for categories and lists of subprograms that get and set GeoRaster metadata and 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.
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.
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.
To export GeoRaster objects to image files, you have the following options:
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:
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
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
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.
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.
Export and import the table that you created in Step 1, together with GeoRaster tables and their related raster data tables.
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;
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:
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.
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
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:
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'));
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.