PK_BODY_make_persp_outline

PK_ERROR_code_t                        PK_BODY_make_persp_outline
(
--- received arguments ---
const int                              n_bodies,      --- number of bodies
const PK_BODY_t                        bodies[],      --- bodies
const PK_TRANSF_t                      transfs[],     --- body transformation
const PK_VECTOR_t                      eye_position,  --- eye position
const PK_BODY_make_persp_outline_o_t  *options,       --- option structure

--- returned arguments ---
PK_BODY_make_persp_outline_r_t  *const result,        --- outline result
PK_ENTITY_track_r_t             *const tracking       --- tracking information
)


This function produces outlines for viewing bodies of type PK_BODY_type_solid_c
or PK_BODY_type_sheet_c from the 'eye_position', to give a perspective view.


Specific Errors:
    PK_ERROR_bad_component        (MILD)  a supplied transform contains terms
                                          other than translation, rotation and
                                          reflection.

    PK_ERROR_unsuitable_entity    (MILD)  a supplied body is edge-on or is
                                          neither solid body nor sheet body.

    PK_ERROR_bad_position         (MILD)  the 'eye_position' is placed outside
                                          the size box or close to the
                                          projection surface within the
                                          operation tolerance.



This function produces outlines for viewing bodies of type PK_BODY_type_solid_c
or PK_BODY_type_sheet_c from the 'eye_position', to give a perspective view.

If the 'transfs' argument is NULL, no transforms are applied to the bodies and
the bodies array must not contain duplicates.

If the 'transfs' argument is not NULL, it refers to an array of 'n_bodies'
PK_TRANSF_t entities. Each body is transformed by its corresponding entry in
'transfs'. The bodies array may contain duplicates. The 'transfs' may only
include rigid and reflection transforms. If an instance does not need to be
transformed, its 'transfs' entry can be set to PK_ENTITY_null.

'result' returns the status information and an array of outlines, each
consisting of a set of outline curves that connect to each other when viewing
from the 'eye_position'.

If PK_persp_outline_ok_c or PK_persp_outline_non_manifold_c or
PK_persp_outline_cant_project_c is returned as the 'status' of the 'result',
'tracking' returns the tracking information of the edges and faces that
generate the outline curves, one track record per outline curve.
If the value of 'clipping' is not PK_persp_clipping_no_c, the result may
include bound curves that are created from the boundary of the viewing range,
which together with the outline curves define the areas inside the outline
loops. A bound curve has a tracking record with empty 'original_entities' and
'original_classes' arrays.

An edge is returned as the original entity if it coincides with an outline
curve when viewing from the 'eye_position'.

A face is returned if its silhouette coincides with an outline curve when
viewing from the 'eye_position'.

If PK_persp_outline_non_manifold_c is returned, the 'product_error_entities'
in the 'result' contains the entities associated with the non-manifold
outlines.

If PK_persp_outline_cant_project_c is returned, the outline curves that fail
to project will be returned as 0, and the outline curves that fail to check
will be returned in the 'product_error_entities' in the 'result'. The
entities that generate these outline curves will be returned in the
'original_error_entities' in the 'result'.

If PK_persp_outline_no_outline_c is returned as the 'status' of the 'result',
only empty arrays will be returned in the 'result'.

For a returned 'status' that indicates an operation failure before producing
any outline, e.g. PK_persp_outline_cant_facet_c, the entities associated with
the failure will be returned in 'original_error_entities' in the 'result'.
The 'product_error_entities' will be empty.

For a returned 'status' that indicates an operation failure after producing
outline curves, the error curves responsible for the failure will be returned
in 'product_error_entities'. In cases where the value of 'clipping' is not
PK_persp_clipping_no_c, the error curves may include some bound curves from
the boundary of the viewing range. The original entities and transforms of
error bound curves are returned as 0 in 'original_error_entities' and
'original_error_transfs' respectively.

If applicable, the transformations associated with the entities in
'original_error_entities' will be returned in 'original_error_transfs' in the
'result'. If an entity in 'original_error_entities' does not associate with
a transformation or the operation failure does not link to a transformation,
its transformation tag in 'original_error_transfs' will be returned as 0.

Note: Where the function returns several outlines the order of those outlines
is undefined.