SDO_GEOR.getBitmapMaskSubset

Format

SDO_GEOR.getBitmapMaskSubset(
     georaster    IN SDO_GEORASTER, 
     layerNumber  IN NUMBER, 
     pyramidLevel IN VARCHAR2, 
     window       IN SDO_NUMBER_ARRAY, 
     rasterBlob   IN OUT NOCOPY BLOB, 
     storageParam IN VARCHAR2 DEFAULT NULL);

or

SDO_GEOR.getBitmapMaskSubset(
     georaster    IN SDO_GEORASTER, 
     layerNumber  IN NUMBER, 
     pyramidLevel IN VARCHAR2, 
     inWindow     IN SDO_NUMBER_ARRAY, 
     rasterBlob   IN OUT NOCOPY BLOB, 
     outWindow    OUT SDO_NUMBER_ARRAY, 
     storageParam IN VARCHAR2 DEFAULT NULL);

or

SDO_GEOR.getBitmapMaskSubset(
     georaster    IN SDO_GEORASTER, 
     layerNumber  IN NUMBER, 
     pyramidLevel IN VARCHAR2, 
     window       IN SDO_GEOMETRY, 
     rasterBlob   IN OUT NOCOPY BLOB, 
     storageParam IN VARCHAR2 DEFAULT NULL);

or

SDO_GEOR.getBitmapMaskSubset(
     georaster    IN SDO_GEORASTER, 
     layerNumber  IN NUMBER, 
     pyramidLevel IN VARCHAR2, 
     inWindow     IN SDO_GEOMETRY, 
     rasterBlob   IN OUT NOCOPY BLOB, 
     outWindow    OUT SDO_NUMBER_ARRAY, 
     storageParam IN VARCHAR2 DEFAULT NULL);

Description

Gets a subset of a bitmap mask.

Parameters

georaster

GeoRaster object.

layerNumber

Number of the layer on which to perform the operation. A value of 0 (zero) indicates the object layer.

pyramidLevel

Pyramid level containing the specified cell.

window, inWindow

A rectangular window for the subset, specified either as a numeric array with the lower-left and upper-right coordinates or as an SDO_GEOMETRY object. The SDO_NUMBER_ARRAY type is defined as VARRAY(1048576) OF NUMBER.

rasterBlob

BLOB to hold the output (the resulting subset).

outWindow

An SDO_NUMBER_ARRAY object identifying the coordinates of the upper-left and lower-right corners of the output window in the cell space.

storageParam

A string specifying storage parameters to be applied in creating rasterBlob. The only storageParam keywords supported for this procedure are celldepth, compression, interleaving, and quality; all other keywords are ignored. Storage parameters are explained in Storage Parameters.

If the storageParam parameter is null, the resulting GeoRaster object has a celldepth value of 1BIT celldepth, has DEFLATE compression if the input GeoRaster object is compressed, and has the same interleaving type as the input GeoRaster object.

Usage Notes

If there is no bitmap associated with the specified GeoRaster object at the specified raster layer, or the specified input window does not intersect with the spatial extent of the GeoRaster object, the procedure returns with rasterBlob truncated to length zero and the outWindow set to a null value.

This procedure operates on a single GeoRaster object. The procedure has four formats, depending on whether the input window is specified as a geometry object or as the upper-left and lower-right corners of a box, and on whether the outWindow parameter is used to return the coordinates of the output window.

If the window or inWindow parameter data type is SDO_GEOMETRY, the SDO_SRID value must be one of the following: null (to specify raster space) or a value from the SRID column of the MDSYS.CS_SRS table.

If the SDO_SRID values for the window or inWindow parameter geometry and the model space are different, the geometry parameter is automatically transformed to the coordinate system of the model space before the operation is performed. (Raster space and model space are explained in GeoRaster Data Model.)

If the window parameter specifies a geodetic MBR, it cannot cross the date line meridian. For information about geodetic MBRs, see Oracle Spatial Developer's Guide.

After the procedure completes, the rasterBLOB parameter contains the cell (pixel) data in the cropped window without tiling. The cropped window is the overlapping portion of the specified window of interest and the source GeoRaster object's spatial extent. If the outWindow parameter is specified, after the procedure completes it contains the coordinates of the cropped window in the cell space.

A bitmap mask may have empty raster blocks (see Empty Raster Blocks). Any cells in the output window that are derived from an empty raster block are filled with the value 0 in the output BLOB.

The BLOB has no padding, except when the cell depth is less than 8 bits and the total number of bits needed for the output cannot be divided by 8; in these cases, unlike normal padding, only the last byte of the result is padded with 0 (zeros) for the trailing bits.

You can specify compression regardless of whether the input GeoRaster object is compressed or not. To have decompressed output for a compressed input GeoRaster object, specify compression=NONE in the storageParam parameter. For information about GeoRaster compression and decompression, see Compression and Decompression.

For an explanation of bitmap masks, see Bitmap Masks.

Examples

The following example retrieves a subset of a bitmap mask associated with the object layer of a specified GeoRaster object.

DECLARE
  gr sdo_georaster;
  lb blob;
BEGIN
  SELECT georaster INTO gr FROM georaster_table WHERE georid=4;
  dbms_lob.createTemporary(lb, TRUE);
  sdo_geor.getBitmapMaskSubset(gr, 0, 0, sdo_number_array(0,0,99,99), lb, 'compression=none');
  dbms_lob.freeTemporary(lb);
END;
/