PK_BODY_make_facet_body

PK_ERROR_code_t                    PK_BODY_make_facet_body
(
--- received arguments ---
PK_BODY_t                          body,            --- Body to facet
PK_TRANSF_t                        transf,          --- Transform
const PK_BODY_make_facet_body_o_t *options,

--- returned arguments ---
PK_BODY_t                   *const body_copy,       --- Faceted copy of body
PK_TOPOL_track_r_t          *const tracking,        --- Tracking information
PK_TOPOL_track_r_t          *const redundant_topol  --- Topological entities
                                                    --- that were not copied
                                                    --- to the new body
)


This function produces a new body which is a copy of the given body with its
geometry replaced with facet geometry generated using the supplied options.


Specific Errors:
    PK_ERROR_unsupported_transf    'transf' is not a rigid body transformation.
                                   (MILD)
    PK_ERROR_bad_box               The box of 'body' does not all lie inside
                                   the size box. (MILD)
    PK_ERROR_failed_to_facet       'partial_conversion' is set to
                                   PK_ERROR_on_fail_any_c and some faces or
                                   edges in 'body' failed to facet. (SERIOUS)
                                   'partial_conversion' is set to
                                   PK_ERROR_on_fail_all_c and all faces and
                                   edges in 'body' failed to facet. (SERIOUS)


PK_BODY_make_facet_body will return a copy of 'body' in 'body_copy'. Points,
polylines and meshes will be created for the 'body_copy' in place of the
geometry attached to 'body'. Options are available to specify whether groups
and/or attributes should be copied and whether a partial conversion is
acceptable.  If a partial conversion occurs 'body_copy' will have some topology
with missing geometry.

If 'transf' is not PK_ENTITY_null and it only contains translation and rotation
components then 'transf' will be applied to the meshes, polylines and points
of 'body_copy'.  Reflections, scales, shears and perspective components are not
allowed.

The options structure contains controls for generating a tessellation for the
original body.  If the 'body' has facet geometry and the tessellation options
are left at their default values, the meshes, polylines and points attached to
'body_copy' will be exact copies of those in 'body'.  Otherwise, the body will
be tessellated based on the options given, and the meshes, polylines and points
in the copy will be derived from this tessellation.


The function receives:
    'body'               A body to facet.

    'transf'             A rigid body transformation (translation and rotation
                         only).

    'options'            Tessellation options, tracking controls, whether to
                         retain attributes and groups, and whether partial
                         conversion is allowed.


The function will return:
    'body_copy'          A copy of the body with facet geometry.

    'tracking'           Tracking information identifying the mapping of
                         topology in 'body' to topology in 'body_copy'.

    'redundant_topol'    Information identifying topologies from 'body' that
                         were not copied to 'body_copy'.