PK_EDGE_imprint_point

PK_ERROR_code_t    PK_EDGE_imprint_point
(
--- received arguments ---
PK_EDGE_t          edge,        --- edge to be imprinted onto
PK_POINT_t         point,       --- point to imprint

--- returned arguments ---
PK_VERTEX_t *const new_vertex,  --- new vertex
PK_EDGE_t   *const new_edge     --- new edge   (may be PK_ENTITY_null)
)


This function imprints a point onto an edge, thereby creating a
new vertex.


Specific Errors:
    PK_ERROR_coincident            point coincident with existing vertex
    PK_ERROR_not_on_curve          point does not lie on edge's curve or
                                   it is outside the edge
    PK_ERROR_missing_geom          edge does not have geometry


If 'edge' is accurate, 'point' is required to lie on the edge curve. If 'edge'
is tolerant, 'point' is required to lie within the tolerance tube of the edge.
If this requirement is not met, or if 'point' is outside that part of the curve
on which the edge lies, the error code PK_ERROR_not_on_curve is returned.

If 'point' lies within the 'edge', then a 'new_vertex' is created at this
position.  If 'edge' was a ring edge, then no 'new_edge' is created and
'new_edge' is returned as PK_ENTITY_null.  If 'edge' was not a ring edge,
then adding the new vertex splits the edge into two.  The new edge is returned
in 'new_edge'.  If 'point' was an orphan then it will be attached to the new
vertex.  If 'point' was not an orphan, then a copy of it will be attached to
the new vertex.