4.7 SDO_TOPO_MAP.ADD_POLYGON_GEOMETRY

Format

SDO_TOPO_MAP.ADD_POLYGON_GEOMETRY(     
  topology  IN VARCHAR2,      
  polygon   IN SDO_GEOMETRY      
) RETURN SDO_NUMBER_ARRAY;

or

SDO_TOPO_MAP.ADD_POLYGON_GEOMETRY(     
  topology  IN VARCHAR2,      
  coords    IN SDO_NUMBER_ARRAY      
) RETURN SDO_NUMBER_ARRAY;

Description

Adds one or more faces representing a specified polygon geometry, and returns the face ID of each added face.

Parameters

topology

Name of the topology to which to add the face or faces, or null if you are using an updatable TopoMap object (see Specifying the Editing Approach with the Topology Parameter). Must not exceed 20 characters.

polygon

SDO_GEOMETRY object (polygon or multipolygon geometry) representing the face or faces to be added. Each polygon in the object must have a single exterior ring that can contain any number of interior rings.

coords

SDO_NUMBER_ARRAY object specifying the coordinates of a single polygon geometry representing the face or faces to be added. The vertices of the polygon must be in counterclockwise order, with the last vertex the same as the first vertex.

Usage Notes

This function creates at least one new face, and more faces if necessary. For example, if the polygon geometry intersects an existing face, faces are created for the added polygon, and the existing face (the one being intersected) definition is adjusted. If topology is not null, Spatial automatically updates the <topology-name>_FACE$ table as needed. (If topology is null, you can update this table at any time by calling the SDO_TOPO_MAP.UPDATE_TOPO_MAP procedure.)

If the polygon coincides with an existing face, no changes are made to the topology.

For a multipolygon geometry, no exterior ring may overlap any other exterior ring. For example, you cannot add a face representing the following single multipolygon geometry: a park (exterior ring) containing a lake (interior ring) with an island in the lake (exterior ring inside the preceding interior ring).

This function is equivalent to using the addPolygonGeometry method of the TopoMap class of the client-side Java API (described in Topology Data Model Java Interface).

Examples

The following example adds a face representing a specified polygon geometry, and it returns and prints the face ID of the added edge. It uses the current updatable TopoMap object.

DECLARE
  res_number_array SDO_NUMBER_ARRAY;
  face_count NUMBER;
  face_ctr NUMBER;
  this_face NUMBER;
BEGIN
res_number_array := SDO_TOPO_MAP.ADD_POLYGON_GEOMETRY(null,
  SDO_GEOMETRY(2003, NULL, NULL, SDO_ELEM_INFO_ARRAY(1,1003,1),
    SDO_ORDINATE_ARRAY(61,10, 70,10, 70,15, 65,15, 61,10)));
-- DBMS_OUTPUT.PUT_LINE('Result = ' || res_number_array);
-- Print each face associated with the geometry.
face_count := res_number_array.count;
for face_ctr in 1..face_count loop
  this_face := res_number_array(face_ctr);
  dbms_output.put_line ('this face = '|| this_face);
  end loop;  -- printed each face
END;
/
this face = 12