GeoRaster Tools: Viewer, Loader, Exporter

Oracle Spatial includes tools for viewing, loading, and exporting GeoRaster data.

Oracle works closely with third parties to provide comprehensive ETL (extract, transform, load) tools for loading and exporting various raster data formats and to provide visualization clients to display GeoRaster objects. See the Spatial partner solutions information at https://www.oracle.com/database/technologies/spatial/technology-partners.html and the open source GDAL support at http://www.gdal.org/frmt_georaster.html.

GeoRaster also includes the following client-side tools:

JAI-based GeoRaster viewer, loader and exporter
GDAL-based ETL wizard for concurrent batch loading and exporting of large numbers of image and raster files

To use these client-side tools, you must install the demo files from the Oracle AI Database Examples media (see Oracle AI Database Examples Installation Guide). After the installation, these tools are in the following .jar file (assuming the default Spatial installation directory of $ORACLE_HOME/md):

$ORACLE_HOME/md/demo/georaster/tool/georastertool.jar

In addition, GDAL itself is included with the Oracle Spatial installation.

JAI-Based Viewer, Loader, and Exporter

The GeoRaster JAI-based tools include a viewer, a loader, and an exporter. These tools are intended for DBAs and application developers. The viewer is especially useful for examining all types of GeoRaster objects and their metadata. It can also display a virtual mosaic defined as one or a list of GeoRaster tables or views. The loader and exporter are lightweight tools for conveniently load and export a limited number of image and raster files one at a time. They are very limited in loading and exporting capabilities and have many restrictions. Therefore, it is always recommended to use the GDAL-Based ETL, GDAL, or the SDO_GEOR_GDAL.translate to load and export image and raster files. The $ORACLE_HOME/md/demo/georaster/tool/README.txt file includes helpful usage information and instructions for using the following tools:

GeoRaster viewer displays GeoRaster objects and metadata, as well as virtual mosaics. You can connect to multiple databases simultaneously, and see the GeoRaster objects from each database listed in the left pane. You can quickly switch among views at various resolutions, from the original image (pyramid level 0) to the overview (highest pyramid level). You can perform image enhancement, such as linear stretch (automatic, manual, or piecewise), normalization, equalization, and controls for brightness, contrast, and threshold. (For more information about viewing GeoRaster objects, see Viewing GeoRaster Objects.)

In the viewer, you can call the GeoRaster loader and exporter tools and invoke the GDAL-Based ETL tool, thus enabling you to use a single tool as an interface to the capabilities of all the GeoRaster tools. The loader and exporter tools are described in this section and in the $ORACLE_HOME/md/demo/georaster/tool/JAI_based_tools_user_guide.txt file.
GeoRaster loader, which loads raster data into the GeoRaster objects. It can load the following image formats: TIFF, GeoTIFF, JPEG, BMP, GIF, PNG, and JP2. Georeferencing information can be loaded from ESRI world files, GeoTIFF files and Digital Globe RPC text files.

On non-Windows systems this loader tool does not support the BMP or GIF image formats. This tool does not support raster data that has a cell depth value of 2BIT, or source multiband raster data with BIL or BSQ interleaving types. The imported GeoRaster object has the BIP interleaving type. The loading operation of this tool cannot be rolled back.

When an image in JPEG file format is loaded, the amount of memory required for the operation depends on the size of the uncompressed image, and can be specified as a command line parameter using the -Xmx option (for example, java -Xmx256M oracle.spatial.georaster.tools.GeoRasterLoader ...).
GeoRaster exporter, which exports GeoRaster objects to image files. The GeoRaster exporter tool supports the following destination image file formats: TIFF, GeoTIFF, JPEG, BMP, GIF, PNG, and JP2. Georeferencing information can be exported to ESRI world files, GeoTIFF files and Digital Globe RPC text files.

Note, the GeoRaster exporter tool does not support GIF as a destination file format. The GeoRaster exporter tool does not support GeoRaster objects that have a cellDepth value of 2BIT. GeoRaster objects with a cell depth of 8 bits or greater that have a BSQ or BIL interleaving are exported in BIP interleaved format.

Some restrictions on load and export operations may apply regarding image size and type; see the $ORACLE_HOME/md/demo/georaster/tool/JAI_based_tools_user_guide.txt file for the GeoRaster tools.

These tools are developed in Java, so you can run them anywhere through an intranet or the Internet, as long as you establish a network connection with the Oracle AI Database.

To load or export GeoTIFF images with the GeoRaster client-side tools, add the following libraries to your CLASSPATH definition:

xtiff-jai.jar (available from the SourceForge Extensible-TIFF-JAI group)
geotiff-jai.jar (available from the SourceForge GeoTIFF-JAI group)

To load or export JP2 images, add the following library to your CLASSPATH definition: jai-imageio.jar (available from the Oracle Java Advanced Imaging Image I/O Tools download page).

After raster or image files are loaded into GeoRaster objects, the data is completely stored in the native GeoRaster object data type and is independent from any specific file formats.

If you want to create your own GeoRaster loader and exporter tools, you can develop them using OCI, Oracle C++ Call Interface (OCCI), or Java, and you can implement them as client-side commands or server-side SQL procedures or functions.

GDAL-Based ETL Wizard for Concurrent Batch Loading and Exporting

GeoRaster includes an ETL wizard tool to automate and enable concurrent batch loading and exporting of various image and raster files using GDAL. This powerful tool can load and export large numbers of raster and image files in batches and concurrently.

It defines an XML schema and provides a graphical user interface to create loading and exporting description files in XML. Each description file describes how to load or export a series of raster files into or from GeoRaster in a batch. After the XML description files are created, you can use the same wizard tool to invoke multiple description files to concurrently load and export raster files in batches. Any run-time failures are caught and logged, but they do not stop the batch loading or exporting processes. This tool supports the raster formats supported by the GDAL installed with it.

To use this wizard, you must install the demo files from the Oracle AI Database Examples media (see Oracle AI Database Examples Installation Guide). After the installation, this wizard is in the following .jar file (assuming the default Spatial installation directory of $ORACLE_HOME/md):

$ORACLE_HOME/md/demo/georaster/tool/georastertool.jar

The $ORACLE_HOME/md/demo/georaster/tool/README.txt file describes how to set up GDAL and launch the wizard.

The $ORACLE_HOME/md/demo/georaster/tool/GDAL_based_etl_user_guide.pdf file describes the usage in detail.

Using GDAL from the Spatial Installation or on a Client Machine

The GeoSpatial Data Abstraction Library (GDAL) is an Open Source software library that supports many data formats and services. Oracle Spatial geometries and GeoRaster objects are supported by the GDAL library, command line tools, and programing interface.

GDAL is distributed with Oracle Spatial, where it is installed under $ORACLE_HOME/md/gdal on Linux systems and %ORACLE_HOME% \md\gdal on Windows systems. GDAL can also be downloaded from My Oracle Support using the Patch ID listed in Oracle MOS Note 2997919.1. (GDAL is distributed with Linux x86-64 and Microsoft Windows x64 (64-bit) platforms only. It is not distributed with Oracle Spatial on other platforms.)

To prepare GDAL for command line use from the Oracle installation, you must add the GDAL bin, data, lib, and plugins folders to the system environment variables.

The following examples set up GDAL on Linux x86-64:

setenv GDAL_HOME ${ORACLE_HOME}/md/gdal
setenv GDAL_DATA ${GDAL_HOME}/data
setenv GDAL_DRIVER_PATH ${GDAL_HOME}/lib/gdalplugins
setenv PATH ${GDAL_HOME}/bin:${PATH}
setenv LD_LIBRARY_PATH ${GDAL_HOME}/lib:${LD_LIBRARY_PATH}

The following examples set up GDAL on Windows x64 (64-bit):

set GDAL_HOME=%ORACLE_HOME%\md\gdal
set GDAL_DATA=%GDAL_HOME%\data
set GDAL_DRIVER_PATH=%GDAL_HOME%\bin\gdalplugins
set PATH=%GDAL_HOME%\bin;%PATH%

The preceding examples assume that Oracle OCI shared libraries are already configured in the system. Oracle OCI shared libraries can be found in the Oracle AI Database or Instant Client installation.

The following example adds Oracle Instant Client to the Windows PATH variable:

set PATH=C:\instantclient_12_1;%PATH%

The scripts to automatically set up GDAL are setup_gdal.conf and setup_gdal.bat, which can be found in the following folder: $ORACLE_HOME/md/demo/georaster/tool Loading Raster Data and its subtopics provide explanations and examples of how to use GDAL to load raster files into GeoRaster.

To prepare GDAL for command line use on a client machine, download it from My Oracle Support using the Patch ID listed in Oracle MOS note 2997919.1, and follow the instructions in the README.txt file inside the GDAL package.

Using the SDO_GEOR_GDAL Package

The SDO_GEOR_GDAL PL/SQL package integrates the open source software GDAL with Oracle AI Database Server through external procedures and provides PL/SQL APIs to execute a set of GDAL functions.

Note: SDO_GEOR_GDAL is not supported in Autonomous AI Database in both shared and dedicated deployments.

The functions and procedures from the SDO_GEOR_GDAL package will execute on the Oracle AI Database server system and can work together with any other GeoRaster PL/SQL APIs.

Currently the SDO_GEOR_GDAL package is only available on the Linux x86-64 and Microsoft Windows x64 (64-bit) operating systems. SDO_GEOR_GDAL Package Reference describes the SDO_GEOR_GDAL package and includes reference information for the subprograms in that package.

Configuration Requirements for Using SDO_GEOR_GDAL

To use the SDO_GEOR_GDAL package, follow the instructions for your operating system.

Linux x86-64 Systems:

Add the following lines to the server configuration file: ${ORACLE_HOME}/hs/admin/extproc.ora

However, in each of these lines, replace ${ORACLE_HOME} with the actual path to the Oracle home directory.

set EXTPROC_DLLS=${ORACLE_HOME}/md/lib/libsdogdal.so
set GDAL_DATA=${ORACLE_HOME}/md/gdal/data
set GDAL_DRIVER_PATH=${ORACLE_HOME}/md/gdal/lib/gdalplugins
set LD_LIBRARY_PATH=${ORACLE_HOME}/lib:${ORACLE_HOME}/md/gdal/lib

You need to shut down and restart the database for the preceding configuration to take effect.

Note:

If you get an error "ORA-06520: PL/SQL: Error loading external library" while invoking SDO_GEOR_GDAL package methods for the configuration, then you can create symbolic links for all the libraries (*.so*) at ${ORALE_HOME}/md/gdal/lib in directory ${ORACLE_HOME}/lib and try again. For example:

ln -s ${ORACLE_HOME}/md/gdal/lib/libgdal.so ${ORACLE_HOME}/lib/libgdal.so

Windows x64 (64-bit) Systems:

Add the following lines to the server configuration file: %ORACLE_HOME%\hs\admin\extproc.ora

However, in each of these lines, replace %ORACLE_HOME% with the actual path to the Oracle home directory.

set EXTPROC_DLLS=%ORACLE_HOME%\\md\\bin\\orasdogdal.dll
set GDAL_DATA=%ORACLE_HOME%\\md\\gdal\\data
set GDAL_DRIVER_PATH=%ORACLE_HOME%\\md\\gdal\\bin\\gdalplugins
set PATH=%ORACLE_HOME%\\bin;%ORACLE_HOME%\\lib;%ORACLE_HOME%\\md\\gdal\\bin

You need to shut down and restart the database for the preceding configuration to take effect.

Note: If you get an error "ORA-06520: PL/SQL: Error loading external library" while invoking SDO_GEOR_GDAL package methods for the configuration, then you can copy all the libraries (*.dll) at %ORACLE_HOME%\md\gdal\bin to directory %ORALCE_HOME%\bin and try again.