Format

SDO_GEOR.mask(
     inGeoRaster   IN SDO_GEORASTER, 
     bandNumbers   IN VARCHAR2, 
     mask          IN SDO_GEORASTER, 
     storageParam  IN VARCHAR2, 
     outGeoraster  IN OUT SDO_GEORASTER, 
     zeroMapping   IN NUMBER DEFAULT 0, 
     oneMapping    IN NUMBER DEFAULT 1, 
     bgValues      IN SDO_NUMBER_ARRAY DEFAULT NULL);

Description

Applies a mask to specified layers of an existing (input) GeoRaster object. The mask GeoRaster object and the input GeoRaster object can have the same storage format or different storage formats, and you can specify storage format options for the output GeoRaster object (for example, to change the blocking, cell depth, or interleaving).

For information about how to determine the mask value to use, see the Usage Notes.

Parameters

inGeoRaster

The SDO_GEORASTER object on which the mask operation is to be performed to create the new object.

bandNumbers

A string identifying the physical band numbers on which the operation is to be performed. Use commas to delimit the values, and a hyphen to indicate a range (for example, 1-3 for the second, third, and forth layers).

mask

The SDO_GEORASTER object to be used as a mask on the input GeoRaster object for generating the output GeoRaster object. If this parameter is specified as null, then available attached masks of the input GeoRaster object are applied to the specified layers.

storageParam

A string specifying storage parameters, as explained in Storage Parameters.

outGeoRaster

The new SDO_GEORASTER object that reflects the results of the mask operation. Must be either a valid existing GeoRaster object or an empty GeoRaster object. (Empty GeoRaster objects are explained in Blank and Empty GeoRaster Objects.) Cannot be the same GeoRaster object as inGeoRaster.

If the output GeoRaster object has any existing raster data, it is deleted before the mask operation is performed. The output GeoRaster object is overwritten as a result of this function.

zeroMapping

Value used for mask cell value 0 (zero). The default value is 0.

oneMapping

Value used for mask cell value 1 (one). The default value is 1.

bgValues

Background values for filling partially empty raster blocks. It is only useful when the source GeoRaster object has empty raster blocks and the current operation leads to partially empty raster blocks (see Empty Raster Blocks). The number of elements in the SDO_NUMBER_ARRAY object must be either one (same filling value used for all layers) or the band dimension size (a different filling value for each layer, respectively). For example, SDO_NUMBER_ARRAY(1,5,10) fills the first layer with 1, the second layer with 5, and the third layer with 10. The default bgValues are zero (0).

The filling values must be valid cell values as specified by the target cell depth background values for filling sparse data.

Usage Notes

To determine the mask value to use with the mask parameter, apply the following logic:

If(cellValue_mask==0)
   cellValue_target=cellValue_source * zeroMapping;      
else
   cellValue_target=cellValue_source * oneMapping;

where:

• cellValue_source is the cell value of inGeoraster at coordinate (x,y).

• cellValue_target is the cell value of outGeoraster at coordinate (x,y).

• cellValue_mask is the cell value of mask at coordinate (x,y).

If inGeoRaster is null, no operation is performed.

If pyramid data exists for inGeoRaster, then the mask GeoRaster object must have at least the same number of pyramid levels as inGeoRaster.

If mask is not null, its dimension (row and column) size must be equal to that of inGeoRaster, and mask must overlap on inGeoRaster. (You can check for overlap using the SDO_GEOR_RA.isOverlap function.)

If mask is null and if no attached mask is available for the specified layers, then inGeoRaster is copied to outGeoRaster, which is also modified as specified by any storageParam specifications.

Contrast this function with the SDO_GEOR.setBitmapMask function: SDO_GEOR.mask calculates cell values in layers and stores them in the target GeoRaster object, whereas SDO_GEOR.setBitmapMask associates mask data with specified layers of the source GeoRaster object.

An exception is raised if one or more of the following are true:

• inGeoRaster is invalid.

• outGeoRaster has not been initialized.

• A raster data table for outGeoRaster does not exist and outGeoRaster is not a blank GeoRaster object.

Examples

The following example applies mask GeoRaster object gr2 to the source GeoRaster object gr1. (It refers to a table named GEORASTER_TABLE, whose definition is presented after Example 1-1 in Storage Parameters.)

DECLARE
  gr1 sdo_georaster;
  gr2 sdo_georaster;
  gr3 sdo_georaster;
BEGIN
  select tmimage into gr1 from landsat where id=103;
  select tmimage into gr3 from landsat where id=1015;
  select grobj into gr2 from grtab where id=1;
  SDO_GEOR.mask(gr1,null,gr2,'blocksize=(100,100,3)',gr3,0.1,0.9,null);
  update landsat set tmimage=gr3 where id=1007;  
END;
/

The following example applies the attached mask of the source GeoRaster object gr1 to its second layer.

DECLARE
  gr1 sdo_georaster;
  gr2 sdo_georaster;
  gr3 sdo_georaster;
BEGIN
  select tmimage into gr1 from landsat where id=103;
  select tmimage into gr3 from landsat where id=1015;
  gr2:=null;
  SDO_GEOR.mask(gr1,'1',gr2,'blocksize=(100,100,3)',gr3,0.1,0.9,null);
  update landsat set tmimage=gr3 where id=1007;  
END;
/