PK_ERROR_code_t     PK_BODY_imprint_curve
(
--- received arguments ---
PK_BODY_t           body,                  --- body
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 body, thereby creating a new edge or
edges.


Specific Errors:
    PK_ERROR_unsuitable_entity      not a minimum or wire body
    PK_ERROR_non_manifold           body would become general
    PK_ERROR_crossing_edge          curve crosses existing edge


The body must be a minimum body or a wire body, otherwise
PK_ERROR_unsuitable_entity will be returned.

Each section of that part of curve bounded by parametric bounds that lies
in the interior of the unique region of the body gives rise to a new edge or
edges. Under certain circumstances a new face will also be made; see below.
The given curve and bounds may indicate either an open part of a curve or a
whole period of a closed periodic curve.  The result depends upon the type of
the body and whether generalised topology has been enabled
(see PK_SESSION_set_general_topology).


Minimum body:

  Without generalised topology:

    If the bounded curve is open, an open wire body will result.
    If the bounded curve is closed, the result will be a sheet body with a
    single face without a surface attached; the face will lie on the left of
    the new edge, which will go in the direction of the curve.


  With generalised topology:

    If the bounded curve is open, an open wire body will result.
    If the bounded curve is closed, the result will be a closed wire body.

  The position of the point of the single vertex of the body is irrelevant.


Wire body:

  Without generalised topology:

    The bound curve may not be closed, and one bound must coincide with an end
    vertex of the (open) wire body; otherwise PK_ERROR_non_manifold will be
    returned.  If both bounds coincide with the end vertices of a wire body,
    then the result is a sheet body with a single face without a surface
    attached; the face will lie on the left of the new edge, which
    will go in the direction of the curve.  The new edges may not
    touch or cross the interior of an edge of the wire body or the error
    PK_ERROR_crossing_edge will be returned. The new edges may not touch or
    cross an interior vertex of the wire or the error PK_ERROR_non_manifold
    will be returned.

  With generalised topology:

    The bounded curve may or may not cross the existing vertices of
    the body.  It may not be coincident with the existing edges of the
    body, or cross them except at the vertices or the error
    PK_ERROR_crossing_edge will be returned.

    This operation will in some cases result in a non-manifold or
    disconnected body; if it does, the body type will change to general.


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.