PK_FACE_contains_vectors

PK_ERROR_code_t               PK_FACE_contains_vectors
(
--- received arguments ---
PK_FACE_t                     face, --- face
PK_FACE_contains_vectors_o_t *options,
                                    --- options structure [PF]

--- returned arguments ---
PK_TOPOL_t                    topologies[]
                                    --- topologies coincident with given
                                    --- vectors
)


This function determines whether the points represented by the given vectors
or parameters lie inside, outside or on the boundary of the given face.

This function offers partial support for facet geometry [PF]


Specific Errors:
  PK_ERROR_no_geometry              missing geometry
  PK_ERROR_bad_option_data          bad option data


This function returns the unique, lowest dimension, topological entity in
the face which contains or coincides with each of the represented positions.

The interior of a hole is taken to be outside the face and the boundary of
a hole is taken to be part of the boundary of the face. Positions are
classified by returning the lowest dimension topological entity with which
they coincide.

    Topology           Enclosure Classification
    --------           ----------------------------
    Null               vector lies outside the face
    Edge or Vertex     vector lies on the the face on that edge or vertex
    Face               vector lies inside the face

The positions must be represented either as an array of coordinates or as an
array of parameter pairs, or both. If both are supplied the parameter pairs
and coordinates must correspond and 'n_uvs' and 'n_vectors' must be equal.

If 'loops' are supplied the function determines the containment with respect
only to these loops. For example, if a face has a periphery loop and several
hole loops and 'loops' is only the periphery loop, points inside the holes
will be regarded as inside the face.  The application must ensure that the
given loops bound a finite area for meaningful results to be returned.

For performance reasons, it is assumed by default that position vectors lie
on the face's surface.  If it is required to correctly classify position
vectors as outside the face if they do not lie on the face's surface then
the option 'is_on_surf' must be set to PK_LOGICAL_false.

See Spatial containment for more information.