PK_ERROR_code_t            PK_BODY_extrude
(
--- received arguments ---
PK_BODY_t                  profile,     --- minimum, wire or sheet profile
                                        --- to extrude
PK_VECTOR1_t               path,        --- direction of linear extrusion
const PK_BODY_extrude_o_t *options,     --- options structure

--- returned arguments ---
PK_BODY_t           *const body,        --- resulting extruded body
PK_TOPOL_track_r_t  *const tracking,    --- tracking information
PK_TOPOL_local_r_t  *const results      --- status information
)


This function creates a new body by performing a linear extrusion of a given
profile.


Specific Errors:
    PK_ERROR_distance_le_0         distance over which profile is to be
                                   extruded is zero or negative
    PK_ERROR_unsuitable_entity     profile is unsuitable for extrusion
    PK_ERROR_non_manifold          Can't extrude body with non-manifold
                                   boundary
    PK_ERROR_impossible_sweep      Can't determine swept geometry
    PK_ERROR_su_self_intersect     Extrusion would produce a self intersecting
                                   surface
    PK_ERROR_no_division           bound does not divide extruded body
    PK_ERROR_no_nth_division       nth division does not exist
    PK_ERROR_not_implemented       option not implemented


The new body is created by extruding the given profile body along the
given path vector between two bounds.

The profile may be a minimum, wire or sheet body, the resulting body then
being a wire, sheet or solid body respectively.

Bounds are defined in terms of extrusion divisions.  An extrusion division is
where a potentially infinite body extruded in the direction of and in the
opposite direction to the path vector would be divided into two.

An extrusion division may be a copy of the given profile at a given distance
along the path, or it may be defined by the intersection between the
potentially infinite body and a given entity.  Intersections with a given
entity which do not divide the infinite body in two in the direction of the
path are not extrusion divisions and are ignored.

The resulting body is bounded in the path direction by extrusion
divisions selected by the start_bound and end_bound fields of the options
structure.  The forward fields of the start_bound and end_bound
structures indicate whether each respective bound is on the side of the
profile in the positive direction of the path or on the other side.

The given profile will be contained in the result body if the start_bound
of the options has its forward field set to PK_LOGICAL_false and the
end_bound of the options has its forward field set to PK_LOGICAL_true.
If both forward fields are given the same value then the resulting body is
entirely on one side of the given profile.

The intersection between the potentially infinite body and a given entity
may produce more than one division.  If the given profile is contained in
the result body then divisions are ordered by increasing distance from the
profile.  When both bounds are on the same side of the profile then
divisions for the bound nearest the profile are ordered by increasing
distance from the profile, and divisions for the bound furthest from the
profile are ordered by increasing distance from the bound nearest to
the profile.  The ordering of divisions may be reversed ( nearest field
of the start_bound and end_bound structures ) so that furthest rather than
nearest divisions may be selected.

If a division intersects the profile, or if the profile is not contained
in the result, and a division of the bound furthest from the profile
intersects the bound nearest to the profile then the result body is
undefined.

The end_bound must be on the side of the start_bound in the positive
direction of the path vector.

The given profile is unaffected by this function.

Tracking:

    The PK_TOPOL_track_r_t structure contains track records of the type
    PK_TOPOL_track_create_c.

    For a sheet body profile there is a track record for every face in
    the result body.  For each face the original class may be:
     -  PK_CLASS_edge: the face is produced be sweeping an edge of the
        profile,
     -  PK_CLASS_face: the face is derived from a face of the profile or
        from a face of a bounding body,
     -  any subclass of PK_CLASS_surf: the face is produced from a surface
        in a PK_bound_surf_c bound.

    For a wire body profile, there is a track record for every face showing
    the edge it has been swept from, and a track record for the bound edges
    relating them to profile edges'.

    For a minimum body 'profile', there is a track record for the edge
    relating it to the vertex it was swept from, and a track record for each
    resulting vertex showing how that was obtained.  For these vertices, the
    original class may be:
     -  PK_CLASS_vertex: the vertex is produced by a PK_bound_distance_c
        bound,
     -  PK_CLASS_face: the vertex is produced at an intersection with a face
        at a PK_bound_face_c, PK_bound_body_c or PK_bound_sheet_c bound
     -  any subclass of PK_CLASS_surf: the vertex is produced at the
        intersection with a surface given with a PK_bound_surf_c bound.


The results argument is not currently used.  The status field of the
PK_TOPOL_local_r_t structure is always set to PK_local_status_ok_c.

Restrictions:

   If profile is a wire body then only PK_bound_distance_c bounds are
   allowed.

   If profile is a sheet body then unbounded surfaces may not be used
   with PK_bound_surf_c.