AddFace
Prev | 10.8. Topology Processing | Next

## Name

AddFace — Registers a face primitive to a topology and gets its identifier.

## Synopsis

`integer AddFace(`varchar toponame, geometry apolygon, boolean force_new=false`)`;

## Description

Registers a face primitive to a topology and gets its identifier.

For a newly added face, the edges forming its boundaries and the ones contained in the face will be updated to have correct values in the left_face and right_face fields. Isolated nodes contained in the face will also be updated to have a correct containing_face field value.

This function does not use nor set the next_left_edge and next_right_edge fields of the edge table.

The target topology is assumed to be valid (containing no self-intersecting edges). An exception is raised if: The polygon boundary is not fully defined by existing edges or the polygon overlaps an existing face.

If the `apolygon` geometry already exists as a face, then: if `force_new` is false (the default) the face id of the existing face is returned; if `force_new` is true a new id will be assigned to the newly registered face.

When a new registration of an existing face is performed (force_new=true), no action will be taken to resolve dangling references to the existing face in the edge, node an relation tables, nor will the MBR field of the existing face record be updated. It is up to the caller to deal with that.

The `apolygon` geometry must have the same `srid` as defined for the topology otherwise an invalid spatial reference sys error will be thrown.

Availability: 2.0.0

## Examples

    -- first add the edges we use generate_series as an iterator (the below
    -- will only work for polygons with < 10000 points because of our max in gs)
    SELECT topology.AddEdge('ma_topo', ST_MakeLine(ST_PointN(geom,i), ST_PointN(geom, i + 1) )) As edgeid
        FROM (SELECT  ST_NPoints(geom) AS npt, geom
                FROM
                    (SELECT ST_Boundary(ST_GeomFromText('POLYGON((234896.5 899456.7,234914 899436.4,234946.6 899356.9,234872.5 899328.7,
                    234891 899285.4,234992.5 899145, 234890.6 899069,234755.2 899255.4,
                    234612.7 899379.4,234776.9 899563.7,234896.5 899456.7))', 26986) )  As geom
                )  As geoms) As facen CROSS JOIN generate_series(1,10000) As i
             WHERE i < npt;
    -- result --
     edgeid
    --------
          3
          4
          5
          6
          7
          8
          9
         10
         11
         12
    (10 rows)
    -- then add the face -

    SELECT topology.AddFace('ma_topo',
        ST_GeomFromText('POLYGON((234896.5 899456.7,234914 899436.4,234946.6 899356.9,234872.5 899328.7,
        234891 899285.4,234992.5 899145, 234890.6 899069,234755.2 899255.4,
        234612.7 899379.4,234776.9 899563.7,234896.5 899456.7))', 26986) ) As faceid;
    -- result --
    faceid
    --------
     1

## See Also

AddEdge, CreateTopology, Section 4.5, “Spatial Reference Systems”

Prev | Up | Next
AddEdge | Home | ST_Simplify