SDO_GEOR.getCellCoordinate

Format

SDO_GEOR.getCellCoordinate(
     georaster       IN SDO_GEORASTER, 
     pyramidLevel    IN NUMBER, 
     modelCoordinate IN SDO_GEOMETRY, 
     subCell         IN VARCHAR2 DEFAULT NULL, 
     height          IN NUMBER DEFAULT NULL, 
     vert_id         IN NUMBER DEFAULT NULL, 
     ellipsoidal     IN VARCHAR2 DEFAULT NULL 
     ) RETURN SDO_NUMBER_ARRAY;

or

SDO_GEOR.getCellCoordinate(
     georaster       IN SDO_GEORASTER, 
     pyramidLevel    IN NUMBER, 
     modelCoordinate IN SDO_GEOMETRY, 
     cellCoordinate  OUT SDO_GEOMETRY, 
     subCell         IN VARCHAR2 DEFAULT NULL, 
     height          IN NUMBER DEFAULT NULL, 
     vert_id         IN NUMBER DEFAULT NULL, 
     ellipsoidal     IN VARCHAR2 DEFAULT NULL);

or

SDO_GEOR.getCellCoordinate(
     georaster            IN SDO_GEORASTER, 
     sourcePyramidLevel   IN NUMBER, 
     sourceCellCoordinate IN SDO_NUMBER_ARRAY, 
     targetPyramidLevel   IN NUMBER, 
     subCell              IN VARCHAR2 DEFAULT NULL, 
     ) RETURN SDO_NUMBER_ARRAY;

or

SDO_GEOR.getCellCoordinate(
     georaster            IN SDO_GEORASTER, 
     sourcePyramidLevel   IN NUMBER, 
     sourceCellCoordinate IN SDO_GEOMETRY, 
     targetPyramidLevel   IN NUMBER, 
     subCell              IN VARCHAR2 DEFAULT NULL, 
     ) RETURN SDO_GEOMETRY;

Description

Returns the coordinates in the cell (raster) coordinate system associated with the geometry at the specified model (ground) coordinates (first two formats), or converts cell coordinates between pyramid levels (last two formats).

Note that the second format is a procedure; the other formats are functions.

Parameters

georaster: GeoRaster object.
pyramidLevel: Pyramid level containing the cell specified in modelCoordinate.
modelCoordinate: The geometry that is to be converted.
cellCoordinate: The output geometry in the cell space of the GeoRaster object.
sourcePyramidLevel (last two formats): Pyramid level with which the input cell coordinate is associated.
sourceCellCoordinate (last two formats): Input cell coordinates to be converted. Must be a two-dimensional geometry, and its SDO_SRID value must be null.
targetPyramidLevel (last two formats): Pyramid level of the returned (target) GeoRaster object.
subCell: String (TRUE or FALSE) specifying whether to return the cell coordinates in sub-pixel (floating) values.
height: Number specifying the Z value for three-dimensional (X, Y, Z) georeferencing.
vert_id: Number specifying the vertical reference ID.
ellipsoidal: String specifying whether the vertical reference system is ellipsoidal (TRUE) or not ellipsoidal (FALSE).

Usage Notes

The first two formats of this function return the coordinates in the cell (raster) coordinate system associated with the geometry at the specified model (ground) coordinates:

Use the first format (a function without the cellCoordinate parameter) to transform a point in the ground coordinate system (a longitude, latitude pair) to the location of a point on the GeoRaster image.
Use the second format (a procedure with the cellCoordinate parameter) to transform a geometry in the ground coordinate system to the location of a geometry in the raster space of the GeoRaster object. The conversion is done by converting the coordinates of each vertex of the input geometry from the ground coordinate system to the raster space of the GeoRaster object.

The last two formats of this function convert cell coordinates between pyramid levels. If the type of the sourceCellCoordinate parameter is SDO_NUMBER_ARRAY, it specifies the <row,column> pair for a point in the cell space at the source pyramid level. If the type of the sourceCellCoordinate parameter is SDO_GEOMETRY, it specifies a geometry in the cell space at the source pyramid level. The coordinates of each vertex of the input geometry are converted according to the specified pyramid levels.

Use the first format (without the cellCoordinate parameter) to transform a point in the ground coordinate system (a longitude, latitude pair) to the location of a point on the GeoRaster image.
Use the second format (with the cellCoordinate parameter) to transform a geometry in the ground coordinate system to the location of a geometry in the raster space of the GeoRaster object. The conversion is done by converting the coordinates of each vertex of the input geometry from the ground coordinate system to the raster space of the GeoRaster object.

If the SDO_SRID value of the modelCoordinate geometry is null, the parameter specifies a geometry in the raster space; otherwise, it specifies a point in a ground coordinate system. If the ground coordinate system is different from the model coordinate system, the modelCoordinate parameter geometry is automatically transformed to the coordinate system of the model space before the operation is performed.

Contrast this function with SDO_GEOR.getModelCoordinate, which returns a point geometry containing the coordinates in the model (ground) coordinate system associated with the point at the specified cell coordinates.

Examples

The following example returns the cell coordinates in the raster image associated with model coordinate values (32343.64,7489527.23) in a specified GeoRaster object. (It refers to a table named GEORASTER_TABLE, whose definition is presented after Example 1-1 in Storage Parameters.)

SELECT sdo_geor.getCellCoordinate(georaster, 0, sdo_geometry(2001,82394,
  sdo_point_type(32343.64,7489527.23,null), null,null)) coord
FROM georaster_table WHERE georid=4;
 
COORD
--------------------------------------------------------------------------------
SDO_NUMBER_ARRAY(100, 100)

The following example returns the geometry at pyramid level 0 that is associated with the specified geometry at pyramid level 2, assuming the geometry is not georeferenced (the model coordination location is CENTER) and the ultCoordinate is (100,-100,0).

SELECT sdo_geor.getCellCoordinate(georaster, 2, 
                sdo_geometry(2003,NULL,NULL,sdo_elem_info_array(1,1003,3),
                             sdo_ordinate_array(100.8,-100.2,220.15,0.3)), 
                0, 'true') coord
FROM georaster_table WHERE georid=1;
 
COORD
--------------------------------------------------------------------------------
SDO_GEOMETRY(2003, NULL, NULL, SDO_ELEM_INFO_ARRAY(1, 1003, 3), SDO_ORDINATE_ARR
AY(104.7, -99.3, 582.1, 302.7))