PK_ERROR_code_t     PK_REGION_imprint_curve
(
--- received arguments ---
PK_REGION_t         region,         --- region
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 region, thereby creating a new edge or
edges.


Specific Errors:
    PK_ERROR_non_manifold           body would become general
    PK_ERROR_crossing_edge          curve crosses existing edge
    PK_ERROR_general_body           given region is from general body
    PK_ERROR_not_in_region          bounded curve not inside region
    PK_ERROR_crossing_face          curve crosses existing face


Each section of that part of curve bounded by parametric bounds that lies
in the interior of the region 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 owning
the region and whether generalised topology has been enabled
(see PK_SESSION_set_general_topology).


Region of 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.


Region of 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.


Region of a sheet, solid, or general body:

  Without generalised topology:

    This is not allowed.  One of the errors PK_ERROR_non_manifold or
    PK_ERROR_general_body will be returned.


  With generalised topology:

    If the bounded curve does not lie in the region, the error
    PK_ERROR_not_in_region will be returned.

    The bounded curve may or may not cross the existing vertices of the
    body. It may not coincide with existing edges or faces of the body,
    or cross them except at the vertices or one of the errors
    PK_ERROR_crossing_edge or PK_ERROR_crossing_face will be returned.

    One or more wireframe edges will be created in the given region. If
    the region is in a sheet or solid body, this operation will always
    result in a non-manifold or disconnected body, and so the body type
    of a sheet or solid body will change to general. If the region is in
    a general body the operation may result in a wire body, in which
    case the body type will change to wire. The operation may involve
    the creation of a new shell in the given region, or even the merging
    of two of its existing shells.


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.