SDO_GEOR_GDAL.translate

Format

SDO_GEOR_GDAL.translate(
     inDirectory     IN SDO_VARCHAR2, 
     InFileName      IN OUT SDO_VARCHAR2, 
     outGeoRaster    IN OUT SDO_GEORASTER, 
     options         IN VARCHAR2 DEFAULT NULL,
     createOptions   IN VARCHAR2 DEFAULT NULL,
     metadataOptions IN VARCHAR2 DEFAULT NULL,
     openOptions     IN VARCHAR2 DEFAULT NULL);

or

SDO_GEOR_GDAL.translate(
     inGeoRaster     IN SDO_GEORASTER, 
     outDirectory    IN VARCHAR2, 
     outFileName     IN VARCHAR2, 
     options         IN VARCHAR2 DEFAULT NULL,
     createOptions   IN VARCHAR2 DEFAULT NULL,
     metadataOptions IN VARCHAR2 DEFAULT NULL,
     openOptions     IN VARCHAR2 DEFAULT NULL);

or

SDO_GEOR_GDAL.translate(
     inGeoRaster     IN SDO_GEORASTER, 
     outGeoRaster    IN OUT SDO_GEORASTER, 
     options         IN VARCHAR2 DEFAULT NULL,
     createOptions   IN VARCHAR2 DEFAULT NULL,
     metadataOptions IN VARCHAR2 DEFAULT NULL,
     openOptions     IN VARCHAR2 DEFAULT NULL);

or

SDO_GEOR_GDAL.translate(
     inGeoRaster     IN MDSYS.SDO_GEORASTER,
     outTableName    IN VARCHAR2,
     outRasterid     IN NUMBER, 
     options         IN VARCHAR2 DEFAULT '',
     createOptions   IN VARCHAR2 DEFAULT '',
     metadataOptions IN VARCHAR2 DEFAULT '',
     openOptions     IN VARCHAR2 DEFAULT '');

or

SDO_GEOR_GDAL.translate(
     inTableName     IN     VARCHAR2,
     inRasterid      IN     NUMBER,
     outGeoRaster    IN OUT MDSYS.SDO_GEORASTER,
     options         IN     VARCHAR2 DEFAULT '',
     createOptions   IN     VARCHAR2 DEFAULT '',
     metadataOptions IN     VARCHAR2 DEFAULT '',
     openOptions     IN     VARCHAR2 DEFAULT '');

Description

Converts raster data between different formats, potentially performing some operations like subsettings, resampling, and rescaling pixels in the process.

Parameters

inDirectory

The name of a directory object pointing at the system directory containing the input file.

inFileName

A base file name (file name without path) of any GDAL compatible raster data source specification.

inGeoRaster

Input GeoRaster object.

outGeoRaster

GeoRaster object to hold the result of the operation. Must be a valid initialized GeoRaster object. Cannot be the same GeoRaster object as inGeoRaster.

outDirectory

The name of a directory object pointing at the system directory to contain the output file.

outFileName

Name of the output file.

inTableName

The table or view name in which the input raster is stored in a BLOB column. See the Usage Notes for more information.

inRasterid

The ID to identify the row in the table where the input raster is stored in a BLOB column. See the Usage Notes for more information.

outTableName

The table or view name in which the output raster is to be stored in a BLOB column. See the Usage Notes for more information.

outRasterid

The ID to identify the row in the table where the output raster is to be stored in a BLOB column. See the Usage Notes for more information.

options

When specified, identifies options for the GDAL translate operation. See the Usage Notes for a table of names and explanations of possible options parameter values.

Example: options => 'srcwin=100,100,2500,2500'

createOptions

When specified, identifies options specific to the output driver. Format 'name=value', with options separated by space. Example: "COMPRESS=JPEG-F GENPYRAMID=NN".

metadataOptions

When specified, assigns metadata values specific to the output driver. Format 'name=value', with options separated by space. Example: "TIFFTAG_POINTAREA=AREA".

openOptions

When specified, identifies options specific to the input driver format. See the GDAL supported format list for details.

Usage Notes

This function performs the same action as the GDAL translate command.

The source and the target raster data can be stored in a file system, in a BLOB in a table, or in a GeoRaster object. Also, note the following:

The raster data that is stored in a file system is identified by the combination of a database directory object name and a file name, such as (inDirectory, inFileName) or (outDirectory, outFileName).
The raster data that is stored in a BLOB is identified by a table or view name and an ID, such as (inTableName, inRasterid) or (outTableName, outRasterid). Note that the table or view that stores the raster in BLOB must have at least the following two columns: (rasterblock BLOB, rasterid NUMBER), where rasterblock column stores the raster and rasterid is used to identify the raster.

The options parameter possible keywords are listed in the following table.

Table 10-2 options Parameter Possible Values for translate Operations

Keyword	Explanation
`bandList`	Array of band numbers. Integer list; 1 is the first band. Example: `'bandlist=4,3,2'` If not specified, the band list from the input file will be used.
`eco`	Show error when `projWin` is completely outside. Boolean type; default is `false`. Example: `'eco=true'`
`epo`	Show error when `projWin` is partially outside. Boolean type; default is `false`. Example: `'epo=true'`
`exponentList`	Apply non linear scaling with a power function. Must be positive. Used with the scale option. Example: `'exponent=10,100'`
`format`	The name of GDAL driver that support dataset creating. String type. Example: `'format=gtiff'`. This option is not needed for sdo_georaster output. For file output, if this option is not specified, 'GTIFF' is assumed.
`GCP`	Ground Control Points. May be provided multiple times to provide a set of GCPs. In the format `“pixel,line,easting,northing,elevation”` where elevation is optional. Example: `“gcp=10,40,234.2,734 gcp=13,54,28.4,837 gcp=20,90,285.2,934”`
`maskBandList`	Array of band numbers. Integer list, where 1 is the first band. Example: `'maskbandlist=1'` If not specified, the band list from the input file will be used.
`nodata`	List of Nodata value (or `none` to unset it) for each output band. Example: `”nodata=9990”`
`outputBounds`	Assigned the output bounds of the output image in the format `“upper-left-x, upper-left-y, lower-right-x, lower-right-y”`. Example: `'outputbounds=293.992,643.447,361.104, 118.648'`
`outputBoundSRS`	The spatial reference system (SRS) for `outputBounds`. Example: `outputBoundsSRS=EPSG:4326`. If not specified, assumes the input image SRS.
`outputType`	Output pixel data type. Supported values are: `Byte`, `Int16`, `UInt16`, `UInt32`, `Int32`, `Float32`, `Float64`, `CInt16`, `CInt32`, `CFloat32`, and `CFloat64`. Example: `'outputtype=float64'` If this option is not specified, the input data type will be used. Check if the output format support the data type in use.
`outsize`	Set the size of the output image defined by rows and columns or by the relative percentage of the original image size. Example: `'outsize=50%,50%', 'outsize=1024,512', 'outsize=200%,200%'` If not specified, the original size of the input image will be used.
`projWin`	Source window sub region from input image defined in coordinates as in `“upper-left-x, upper-left-y, lower-right-x, lower-right-y”`. Example: `'srcwin=180,90,0,0'`. If not specified, the entire input image will be used.
`projWinSRS`	The spatial reference system (SRS) for `projWin`. Example: `projWinSRS=EPSG:4326`. If not specified, assumes the input image SRS.
`rat`	Indicate whether to copy the source image raster attribute table to the output image . Default is `true`. Example: “rat=false” The operation depend on the capacity of the output format to support raster attribute table.
`resampleAlg`	Resampling mode {`nearest`(default), `bilinear`, `cubic`, `cubicspline`, `lanczos`, `average`, `mode`}. Example:: `resample=cubic`
`rgbExpand`	Indicate whether to translate a dataset with 1 band with a color table as a dataset with 3 (RGB) or 4 (RGBA) bands. Expands a dataset with a color table that only contains gray levels to a gray indexed dataset. {`gray\|rgb\|rgba`}. Example: `“rgbExpand=rgb”`
`scale`	List of values to rescale the pixel values from the input image to the output image. The values cam be defined as `“src_min,src_max”` or `“src_min,src_max,dst_min,dst_max”`. Example: `'scale=-10,2400,0,255'`
`srcWin`	Source window subregion from input image defined in pixels coordinates as in `“left_x, top_y, width, height”`. Example: `'srcwin=10,31,400,800'` If not specified, the entire input image will be used.
`stats`	Calculate and store statistics on output image. Boolean type; default is `false`. Example: `'stats=true'`
`strict`	Raise an error if are data type mismatches and lost data when translating to the output format. Boolean type; default is `false`. Example: `'strict=true'`
`xyRes`	Output horizontal and vertical output image resolution. Example: : `'xyres=30.0,30.0'`. If not specified, the resolution of the input image will be used.

For convenience, the arguments of the options parameter can also be entered in the same format as the GDAL gdal_translate command line tool. Example: “-srcwin 10 10 512 512 –outsize 1024 1024“

Examples

The following example loads a geotiff file from the file system to an initialized GeoRaster object.

CREATE OR REPLACE DIRECTORY mydata_dir AS '/folder_name/data/';

BEGIN
  DELETE FROM imagery WHERE id = 1;
  INSERT INTO imagery VALUES(1, sdo_geor.init('imagery_rdt',1))
         RETURNING raster INTO gr;
  sdo_geor_gdal.translate(inDirectory   => 'mydata_dir',
                          inFileName    => 'sample.tif',
                          outGeoRaster  => gr);
  UPDATE imagery SET raster = gr WHERE id = 1;
  COMMIT;
END;

The following example exports a GeoRaster object to a geotiff file.

CREATE OR REPLACE DIRECTORY dump_dir AS '/folder_name/dump/';

DECLARE
  gr sdo_georaster;
BEGIN
  SELECT raster INTO gr FROM imagery WHERE id = 1;
  sdo_geor_gdal.translate(inGeoRaster   => gr,
                          outDirectory  => 'dump_dir',
                          outFileName   => 'copy_imagery_id_1.tif');
END;

The following example copies a GeoRaster object into another cropping part of the image while changing the resolution and the scale of values.

DECLARE
  gr1 sdo_georaster;
  gr2 sdo_georaster;
BEGIN
  DELETE FROM imagery WHERE id = 2;
  SELECT raster INTO gr1 WHERE id = 2;
  INSERT INTO imagery VALUES(2, sdo_geor.init('imagery',2))
         RETURNING raster INTO gr2;
  sdo_geor_gdal.translate(
                inGeoraster   => gr1,
                options       => 'srcwin=100,100,2500,2500' ||
                                 'scale=0,255' ||
                                 'resxy=400,400',
                outGeoRaster  => gr);
  UPDATE imagery SET raster = gr2 WHERE id = 2;
  COMMIT;
END;

The following example exports a GeoRaster object into a file in Erdas .img format.

CREATE OR REPLACE DIRECTORY myoutput_dir AS '/folder_name/data/';

DECLARE
  gr sdo_georaster;
BEGIN
  SELECT raster INTO gr where id = 3;
  sdo_geor_gdal.translate(
                inGeoraster   => gr,
                outDirectory  => myoutput_dir,,
                outFilename   => 'exported.img',
                options       => 'format=hfa');
END;

The following example exports a GeoRaster object into a BLOB in the table raster_table, where the raster_table is defined as (rasterid number, rasterblock BLOB):

DECLARE
   gr sdo_georaster;
BEGIN
   INSERT INTO raster_table VALUES (100, empty_blob());
   SELECT raster INTO gr FROM imagery WHERE id = 1;
   sdo_geor_gdal.translate(inGeoRaster   => gr,
                           outTableName  => 'raster_table',
                           outRasterid   => 100);
   COMMIT;
END;

The following example imports the raster data stored in a BLOB in the table raster_table into a GeoRaster object. The raster_table is defined as (rasterid number, rasterblock BLOB):

DECLARE
   gr sdo_georaster;
BEGIN
   INSERT INTO imagery VALUES (2, sdo_geor.init(‘imagery_rdt’, 2))
       RETURNING raster INTO gr; 
   
   sdo_geor_gdal.translate(
                           inTableName  => 'raster_table',
                           inRasterid   => 100, 
                           outGeoRaster => gr);
  UPDATE imagery SET raster = gr WHERE id= 2;
  COMMIT;
END;