PK_ERROR_code_t   PK_FACE_imprint_curve
(
--- received arguments ---
PK_FACE_t         face,             --- face
PK_CURVE_t        curve,            --- curve
PK_INTERVAL_t     bounds,           --- bounds of curve

--- returned arguments ---
int        *const n_new_edges,      --- number of new edges
PK_EDGE_t **const new_edges,        --- new edges (optional)
int        *const n_new_faces,      --- number of new faces
PK_FACE_t **const new_faces         --- new faces (optional)
)


This function imprints a curve onto a face, thereby creating a new edge or
edges.


Specific Errors:
    PK_ERROR_missing_geom           face does not have geometry
    PK_ERROR_not_on_surface         curve does not lie on faces surface
                                    or bounds not within face
    PK_ERROR_bad_basis_surf         SP curve basis surface differs from
                                    faces surface.
    PK_ERROR_invalid_geometry       curve does not pass checks
    PK_ERROR_not_on_face            no new edges created


If the curve does not lie on the faces surface, then
the error PK_ERROR_not_on_surface is returned.

If none of the interval of the curve lies inside the face i.e. no
new edges are created as a result of the imprint, then the error
PK_ERROR_not_on_face is returned.

Otherwise, each part of the interval of the curve which lies within the
face will be imprinted on the face as a new edge.  The new edges are returned
in new_edges, and the number of them in n_new_edges.  The new edges may
split the face into several faces.  The new faces are returned in new_faces
and the number of them in n_new_faces.  If new faces are created, the old
face will lie on the right of one of the new edges, which will all go in the
direction of the curve.

Both the new_edges and new_faces arguments are optional.  If they are set
to NULL then only the number of new edges and/or faces will be returned.

If curve was an orphan, then it will be attached to the new edge(s).  If
curve may be shared with the new edge(s) then it will be.  Otherwise
a copy of the curve will be made and attached to the new edge(s).  When
several new edges are created by imprinting one curve, then all of the edges
will share the same geometry.