2 GeoRaster Data Types and Related Structures

2.1.1 rasterType Attribute

The rasterType attribute must be a 5-digit number in the format [d][b][t][gt], where:

• [d] identifies the number of spatial dimensions. Must be 2 for the current release.

• [b] indicates band or layer information: 0 means one band or layer; 1 means one or more than one band or layer. Note that you are not specifying the total number of bands or layers in this field. (For information about bands and layers, see Section 1.5.)

• [t] is reserved for future use and should be specified as 0 (zero).

• [gt] identifies the 2-digit GeoRaster type, and must be one of the following values:

  [gt] Value	Meaning
  00	Reserved for Oracle use.
  01	Any GeoRaster type. This is the only value supported for the current release. This value causes GeoRaster not to apply any restrictions associated with specific types that might be implemented in future releases.
  02-50	Reserved for Oracle use.
  51-99	Reserved for customer use in future releases.

  
  

For example, a RasterType value of 20001 means:

• Two-dimensional data

• One band (layer)

• Any GeoRaster type

2.1.2 spatialExtent Attribute

The spatialExtent attribute identifies the spatial extent, or footprint, associated with the raster data. The spatial extent is an Oracle Spatial geometry of type SDO_GEOMETRY. The spatial extent geometry can be in any coordinate system, not necessarily in the GeoRaster model space, and can be directly updated by a SQL UPDATE statement specifying a geometry. However, the spatial extent geometry is in the model (ground) space of the GeoRaster object if the GeoRaster object is georeferenced and if you generate the spatial extent geometry using any of the following methods: calling the SDO_GEOR.generateSpatialExtent function, or specifying spatialExtent=TRUE as a storage parameter to the SDO_GEOR.importFrom procedure or the GeoRaster client-side loader (described in Section 1.14).

You can call SDO_CS.transform to convert it to any other supported coordinate system. The spatial extent is set to null, rather than cell space, if its SRID value is null or 0 (zero). The SDO_GEOMETRY data type is described in Oracle Spatial Developer's Guide.

The GeoRaster spatial extent is generally used to build a Spatial R-tree index on the GeoRaster column. For example, you can use a geodetic SRID for all the spatial extents when all GeoRaster objects are in different local projections, and then build a whole-Earth based spatial index on the GeoRaster table and spatially search GeoRaster objects globally. Because of the potential performance benefits of spatial indexing for GeoRaster applications, the geometry is associated with the spatialExtent attribute, rather than being included in the XML metadata attribute described in Section 2.1.5. For information about indexing GeoRaster data, see Section 3.7.

2.1.3 rasterDataTable Attribute

The rasterDataTable attribute identifies the name of the raster data table. The raster data table must be an object table of type SDO_RASTER. It contains a row of type SDO_RASTER for each raster block that is stored. You must create and (if necessary) drop the raster data table. You should never modify the rows in this table directly, but you can query this table to access the raster data.

This attribute must be a valid nonquoted identifier without any period separators, and all the alphanumeric characters must be uppercase.

For more information about the raster data table and the SDO_RASTER type, see Section 2.2.

2.1.4 rasterID Attribute

The rasterID attribute value is stored in the rows of the raster data table to identify which rows belong to the GeoRaster object. The rasterDataTable attribute and rasterID attribute together uniquely identify the GeoRaster object in the database. That is, each GeoRaster object has a raster data table, although a raster data table can contain data from multiple GeoRaster objects.

You can specify the rasterID and rasterDataTable attributes for new GeoRaster objects, as long as each pair is unique in the database. If you do not specify these values, they are automatically generated by the SDO_GEOR.init and SDO_GEOR.createBlank functions.

2.1.5 metadata Attribute

The metadata attribute contains the GeoRaster metadata that is defined by Oracle. The metadata is described by the GeoRaster metadata XML schema, which is documented in Appendix A. The metadata of any GeoRaster object must be validated against this XML schema, and it must also be validated using the SDO_GEOR.validateGeoRaster function, which imposes additional restrictions not defined by this XML schema.

2.2.1 rasterID Attribute

The rasterID attribute in the SDO_RASTER object must be a number that matches the rasterID value in its associated SDO_GEORASTER object. (The rasterID attribute of the SDO_GEORASTER object is described in Section 2.1.4.) The matching of these numbers identifies the raster block as belonging to a specific GeoRaster object.

2.2.2 pyramidLevel Attribute

The pyramidLevel attribute identifies the pyramid level for this block of cells. The pyramid level is 0 or any positive integer. Pyramid levels are used to create reduced resolution images that require less storage space. A pyramid level of 0 indicates the original raster data; that is, there is no reduction in the image resolution and no change in the storage space required. Values greater than 0 (zero) indicate increasingly reduced levels of image resolution and reduced storage space requirements. For more information about pyramids, see Section 1.7.

This attribute and the bandBlockNumber attribute (described in Section 2.2.3) are also used to indicate bitmap masks and their pyramids. For more information about bitmap masks, bitmap mask pyramids, and how the pyramidLevel and bandBlockNumber attributes are used, see Section 1.8.

2.2.3 bandBlockNumber Attribute

The bandBlockNumber attribute identifies the block number along the band dimension. For information about bands and layers, see Section 1.5. For more information about how the bandBlockNumber attribute is used with bitmap masks and their pyramids, see Section 1.8.

2.2.4 rowBlockNumber Attribute

The rowBlockNumber attribute identifies the block number along the row dimension.

2.2.5 columnBlockNumber Attribute

The columnBlockNumber attribute identifies the block number along the column dimension.

2.2.6 blockMBR Attribute

The blockMBR attribute is the geometry (of type SDO_GEOMETRY) for the minimum bounding rectangle (MBR) for this block. The geometry is in cell space (that is, its SRID value is null), and all ordinates are integers. The ordinates represent the minimum row and column and the maximum row and column stored in this block.

2.2.7 rasterBlock Attribute

The rasterBlock attribute contains all raster cell data for this block. It is also used to store bitmap masks of the GeoRaster object. The rasterBlock attribute is of type BLOB.

2.3.1 SDO_GEOR_HISTOGRAM Object Type

In GeoRaster, the histogram is stored in the GeoRaster metadata using the XML schema defined in Appendix A. The SDO_GEOR_HISTOGRAM object type is used in the PL/SQL API to contain the histogram data of a GeoRaster object or a layer. The layers have the same histogram data structure. Each cell has a value, and for each cell value or a value range there may be any number of cells having that value or falling in that range.

The SDO_GEOR_HISTOGRAM object type is defined as:

CREATE TYPE sdo_geor_histogram AS OBJECT(
  cellValue  SDO_NUMBER_ARRAY,
  count      SDO_NUMBER_ARRAY);

Table 2-1 describes the attributes of the SDO_GEOR_HISTOGRAM object type. The cellValue array and the count array must have the same length.

The histogram contains the cell values (and the implied value ranges) and the total number of cells related to each cell value or each cell value range. For example, if (cellValue1, count1) and (cellValue2, count2) are the two adjacent entries in ascending order in the histogram, the implied value range is [cellValue1, cellValue2) and the total number of cells in this range is count1. The cell value range is always inclusive in its lower boundary and exclusive in the upper boundary. The size of each range does not necessarily have to be the same. Using this example, the range is equal to or greater than cellValue1 and less than cellValue2. For a lower cell depth (for example, 1-bit to 8-bit integers), the cell value ranges are typically the same as the cell values.

2.3.2 SDO_GEOR_COLORMAP Object Type

In GeoRaster, the color information is stored in the GeoRaster metadata using the XML schema defined in Appendix A. The SDO_GEOR_COLORMAP object type is used in the PL/SQL API to contain colormap information, that is, pseudocolor information for identifying the red, green, blue, and (optionally) alpha values of the color to be used to display cells that have a specific value or are in a specific value range. The colormap is also called the pseudocolor table or the palette table. The colormap in GeoRaster is in the default sRGB ColorSpace, which is a proposed standard RGB color space, as explained at

http://www.w3.org/Graphics/Color/sRGB.html

The ranges for red, green, blue, and alpha values are all scaled to be 8-bit unsigned integers from 0 to 255.

Alpha is also called opacity. An alpha value of 255 means that the color is completely opaque, and an alpha value of 0 means that the color is completely transparent. The color component values are never premultiplied by the alpha value.

The SDO_GEOR_COLORMAP object type is defined as:

CREATE TYPE sdo_geor_colormap AS OBJECT(
  cellValue  SDO_NUMBER_ARRAY,
  red        SDO_NUMBER_ARRAY,
  green      SDO_NUMBER_ARRAY,
  blue       SDO_NUMBER_ARRAY,
  alpha      SDO_NUMBER_ARRAY);

Table 2-2 describes the attributes of the SDO_GEOR_COLORMAP object type. Each attribute is an array of numbers. The arrays must have the same length, and the values of the same index in each array must correspond to each other. Each cellValue value must be consistent with the cellDepth value of the GeoRaster object.

The colormap contains the cell values (and the implied value ranges) and the red, green, blue, and/or alpha values related to each cell value or each cell value range. For example, if (cellValue1, red1, green1, blue1, alpha1) and (cellValue2, red2, green2, blue2, alpha2) are the two adjacent entries in ascending order in the colormap, the implied value range is [cellValue1, cellValue2), and the color components associated with all cells in this range are (red1, green1, blue1, alpha1). The cell value range is always inclusive in its lower boundary and exclusive in the upper boundary. The size of each range does not necessarily have to be the same. In this example, the range is equal to or greater than cellValue1 and less than cellValue2. For a lower cell depth (for example, 1-bit to 8-bit integers), the cell value ranges are typically the same as the cell values.

2.3.3 SDO_GEOR_GRAYSCALE Object Type

In GeoRaster, the grayscale information is stored in the GeoRaster metadata using the XML schema defined in Appendix A. The SDO_GEOR_GRAYSCALE object type is used in the PL/SQL API to contain grayscale information for identifying the grayscale value to be used to display cells that have a specific value or fall into a specific value range. The grayscale table cell values can be "stretched" in linear proportion using this grayscale table, so that the original raster data can be properly displayed. The grayscale table value range is 8-bit unsigned integer values from 0 to 255. The grayscale table is also called the contrast table or the lookup table.

The SDO_GEOR_GRAYSCALE object type is defined as:

CREATE TYPE sdo_geor_grayscale AS OBJECT(
  cellValue  SDO_NUMBER_ARRAY,
  gray       SDO_NUMBER_ARRAY);

Table 2-3 describes the attributes of the SDO_GEOR_GRAYSCALE object type. The cellValue array and the gray array must have the same length. Each cellValue value must be consistent with the cellDepth value of the GeoRaster object.

The grayscale contains the cell values (and the implied value ranges) and the gray values related to each cell value or each cell value range. For example, if (cellValue1, gray1) and (cellValue2, gray2) are the two adjacent entries in ascending order in the grayscale table, the implied value range is [cellValue1, cellValue2), and the gray color associated with all cells in this range is gray1. The cell value range is always inclusive in its lower boundary and exclusive in the upper boundary. The size of each range does not necessarily have to be the same. Taking the same example, the range is equal to or greater than cellValue1 and less than cellValue2. For a lower cell depth (for example, 1-bit to 8-bit integers), the cell value ranges are typically the same as the cell values.

2.3.4 SDO_RASTERSET Collection Type

The SDO_RASTERSET collection type is used as the return type of table functions that query the raster data blocks (one or many blocks, the whole set or a subset).

The SDO_RASTERSET collection type is defined as:

CREATE TYPE sdo_rasterset AS TABLE of SDO_RASTER;

The SDO_RASTER type is described in Section 2.2.

2.3.5 SDO_GEOR_SRS Object Type

In GeoRaster, the spatial reference system (SRS) information is stored in the GeoRaster metadata using the XML schema defined in Appendix A. The SDO_GEOR_SRS object type is used in the PL/SQL API to contain information related to the spatial referencing of a GeoRaster object. The metadata and the object type contain the same information. You can use the object type to retrieve the SRS information from GeoRaster objects or to load and update the SRS information in GeoRaster objects.

The SDO_GEOR_SRS object type is defined as:

CREATE TYPE sdo_geor_srs AS OBJECT (
   isReferenced       VARCHAR2(5),
   isRectified        VARCHAR2(5),
   isOrthoRectified   VARCHAR2(5),
   srid               NUMBER,
   spatialResolution  SDO_NUMBER_ARRAY,
   spatialTolerance   NUMBER,
   coordLocation      NUMBER,
   rowOff             NUMBER,
   columnOff          NUMBER,
   xOff               NUMBER,
   yOff               NUMBER,
   zOff               NUMBER,
   rowScale           NUMBER,
   columnScale        NUMBER,
   xScale             NUMBER,
   yScale             NUMBER,
   zScale             NUMBER,
   rowRMS             NUMBER,
   columnRMS          NUMBER,
   totalRMS           NUMBER,
   rowNumerator       SDO_NUMBER_ARRAY,
   rowDenominator     SDO_NUMBER_ARRAY,
   columnNumerator    SDO_NUMBER_ARRAY,
   columnDenominator  SDO_NUMBER_ARRAY,
   xRMS               NUMBER,
   yRMS               NUMBER,
   zRMS               NUMBER,
   modelTotalRMS      NUMBER,
   GCPgeoreferenceModel SDO_GEOR_GCPGEOREFTYPE);

Table 2-4 describes the attributes of the SDO_GEOR_SRS object type.

However, when the direct and inverse solutions are derived from the functional fitting model, the accuracy values listed in Table 2-4 are not considered in GeoRaster internal cell coordinate and model coordinate transformation computations for the current release.

The SDO_GEOR_SRS object type has two constructors:

• One constructor takes no parameters and creates an instance of the type with the isReferenced attribute set to FALSE and the other attributes set to null values. This constructor allows you to set up either the functional fitting model or the stored function (GCP) model, or to set up both of them together.

• The other constructor takes all the attributes of this object type as parameters, except those related to the stored function (GCP) model.

For examples of how to use the SDO_GEOR_SRS constructor, see the reference section for the SDO_GEOR.setSRS procedure in Chapter 4.

2.3.6 SDO_GEOR_GCP Object Type

In GeoRaster, the ground control point (GCP) information is stored in the GeoRaster metadata using the XML schema defined in Appendix A. The SDO_GEOR_GCP object type is used in the PL/SQL API to contain GCP information related to the georeferencing of a GeoRaster object. The metadata and the object type contain the same information. You can use the object type to retrieve the GCP information from GeoRaster objects or to load and update the GCP information in GeoRaster objects.

The SDO_GEOR_GCP object type is defined as:

CREATE TYPE sdo_geor_gcp AS OBJECT (
     pointID          VARCHAR2(32),
     description      VARCHAR2(256),
     pointType        NUMBER,
     cellDimension    NUMBER,
     cellCoordinates  SDO_NUMBER_ARRAY,
     modelDimension   NUMBER,
     modelCoordinates SDO_NUMBER_ARRAY,
     accuracy         SDO_NUMBER_ARRAY,
     status           NUMBER
);

Table 2-5 describes the attributes of the SDO_GEOR_GCP object type.

The SDO_GEOR_GCP constructor can be used to create an empty instance of this object type. You should then fill in the necessary data before you use this instance.

2.3.7 SDO_GEOR_GCP_ COLLECTION Collection Type

The SDO_GEOR_GCP_ COLLECTION collection type is used to store an array (a collection) of ground control points (GCPs).

The SDO_GEOR_GCP_ COLLECTION collection type is defined as:

CREATE TYPE sdo_geor_gcp_collection VARRAY(1048576) OF SDO_GEOR_GCP;

The SDO_GEOR_GCP type is described in Section 2.3.6.

2.3.8 SDO_GEOR_GCPGEOREFTYPE Object Type

In GeoRaster, the GCP-based georeferencing model information is stored in the GeoRaster metadata using the XML schema defined in Appendix A. The SDO_GEOR_GCPGEOREFTYPE object includes the georeferencing functional fitting method (that is, the geometric model), control points for solving the model parameters, and solution accuracy. The SDO_GEOR_ GCPGEOREFTYPE object type is used in the PL/SQL API to contain georeferencing model information related to the GCP-based georeferencing of a GeoRaster object. The metadata and the object type contain the same information. You can use the object type to retrieve the georeferencing model information from GeoRaster objects or to load and update the georeferencing model information in GeoRaster objects.

The SDO_GEOR_GCPGEOREFTYPE object type is defined as:

CREATE TYPE sdo_geor_gcpgeoreftype AS OBJECT (
     FFMethodType     VARCHAR2(32),
     numberGCP        NUMBER,
     GCPs             SDO_GEOR_GCP_COLLECTION,
     solutionAccuracy SDO_NUMBER_ARRAY
);

Table 2-6 describes the attributes of the SDO_GEOR_GCPGEOREFTYPE object type.

The SDO_GEOR_GCPGEOREFTYPE object type has one constructor. The constructor takes no parameters, and it creates an instance of the type with the FFMethodType attribute set to Affine and the other attributes set to null values.

2.4.1 TABLE_NAME Column

The TABLE_NAME column contains the name of a GeoRaster table that has at least one column of type SDO_GEORASTER.

2.4.2 COLUMN_NAME Column

The COLUMN_NAME column contains the name of a column of type SDO_GEORASTER in the GeoRaster table specified in the TABLE_NAME column.

2.4.3 METADATA_COLUMN_NAME Column

The METADATA_COLUMN_NAME column is ignored for the current release.

2.4.4 RDT_TABLE_NAME Column

The RDT_TABLE_NAME column contains the name of the raster data table associated with the table and column specified in the TABLE_NAME and COLUMN_NAME columns. (The raster data table is explained in Section 2.2.)

2.4.5 RASTER_ID Column

The RASTER_ID column contains a number that, together with the RDT_TABLE_NAME column value, uniquely identifies each GeoRaster object.

2.4.6 OTHER_TABLE_NAMES Column

The OTHER_TABLE_NAMES column is ignored for the current release.