PK_LATTICE_clip

PK_ERROR_code_t            PK_LATTICE_clip
(
--- received arguments ---
PK_LATTICE_t               lattice,   --- lattice to be clipped
const PK_LATTICE_clip_o_t *options,   --- options structure

--- returned arguments ---
PK_LATTICE_clip_r_t *const results    --- results structure
)


This function creates new lattices by clipping the supplied 'lattice'.


Specific Errors:
    PK_ERROR_unsuitable_entity          One or more unsupported clipping
                                        entities have been supplied. (MILD)
    PK_ERROR_bad_option_data            No clipping entities, more than one
                                        surface, faces from the same body with
                                        different fences, an invalid
                                        'duplicate_tolerance', or an
                                        inconsistent combination of 'lrod_clip'
                                        and 'lrod_min_length' have been
                                        supplied. (MILD)
    PK_ERROR_clip_failure               The clipping operation encountered an
                                        internal error. (SERIOUS)




Introduction

This function creates new lattices corresponding to those portions of the
supplied lattice that lie on the relevant side of the supplied clipping
entities. The original lattice is unmodified by this operation. The clipping
entities act on the centre lines of the lattice's lrods, rather than on the
lattice volume.

The clipping entities must be a single surface or one or more faces. Any faces
must be from manifold non-disjoint bodies. A lattice topology lies in front of
a surface or face if it is in the direction pointed to by that entity's normal.
Correspondingly, a lattice topology lies behind a surface or face if it is in
the opposite direction to that pointed to by the entity's normal. Whether the
surviving set of lattice topologies lies in front of or behind each entity is
specified using the 'fence' option.

To define a clip, at least one non-coincident lrod must cross from one side of
a clipping entity to the other or have an lball that lies in a clipping entity.

For any lrod that is divided by one or more clipping entities, the clipped
lrods are those portions of it that lie on the sides of the entities specified
in 'fence'. These clipped lrods will survive if 'lrod_clip' is
PK_LROD_clip_keep_all_c, or if 'lrod_clip' is PK_LROD_clip_keep_connected_c and
the clipped lrod has a surviving lball. If 'lrod_clip' is
PK_LROD_clip_delete_c, no clipped lrods survive.

If an 'lrod_min_length' is supplied, clipped lrods are further required to be
greater than or equal to this value in length in order to survive.

If an lrod is coincident with one or more clipping entities, it will survive if
'lrod_coi' is PK_LROD_coi_keep_all_c, or if 'lrod_coi' is
PK_LROD_coi_keep_connected_c and the lrod is connected to surviving
non-coincident ltopology. It will be deleted if 'lrod_coi' is
PK_LROD_coi_delete_c.

Each surviving clipped lrod has a new lball introduced where it has been
clipped. The radii of these new lballs is controlled by the 'lball_radius'
option.

If 'merge_duplicates' is PK_LTOPOL_dup_merge_yes_c, any set of lballs
containing at least one new lball that are considered duplicates to within
'duplicate_tolerance' will be merged into a single lball. If there are multiple
lrods connecting another lball to lballs within the duplicate set, these will
be merged into a single lrod.

Return Information

If the clipping operation has succeeded, 'results' will contain an array of
length 'n_lattices' in 'lattices'. Each entry in this array is a
PK_clip_lattice_r_t structure containing a 'lattice' and some associated
information. If the 'status' indicates that the clipped 'lattice' contains an
invalidity created by the clipping operation, the relevant lattice topologies
will be contained in the array 'error_ltopols'.

If 'want_clipped_lballs' was set to PK_LOGICAL_true in the options structure
then 'clipped_lballs' will contain all those lballs in the new 'lattice' that
were involved in the clipping operation. 'lball_clip_types' will contain a
corresponding entry for each clipped lball indicating how it was involved.  If
an entry has the value PK_LBALL_clipped_created_c then the lball was created at
an end of a clipped lrod. If an entry has the value PK_LBALL_clipped_touched_c
then the lball lay in one of the clipping entities.

If none of the clipping entities clash with the lattice,
PK_clip_result_no_clash_c will be returned. If there is at least one clash but
these clashes do not define a clip, PK_clip_result_no_clip_c will be returned.
In both cases, no 'lattices' will be returned in 'results'.