point_distance_to_face(3)

NAME
point_distance_to_face - distance from point to bounded convex polygon (face)

SYNOPSIS
#include <matvec.h>

float point_distance_to_face (const float *points, int nr_points, const float *plane, const float *point, int *edge);

DESCRIPTION

Given a point and a bounded convex polygon (a "face"), the function point_distance_to_face calculates the distance from the point to the face. There are two importance cases to consider here:

(a) The point is directly above or below the face. In other words, a line dropped from the point perpendicular to the face intersects the face within the boundary of the polygon. In this case, the function returns the shortest distance from the point to the intersection (and is essentially equivalent to point_distance_to_plane).

(b) The point is not directly above or below the face. In this case the function works out the distance to the nearest edge of the face.

The face is specified as a list of points and a plane (ie. plane coefficients). If plane is NULL, then the function calls plane_coefficients(3) on your behalf. If the face is fixed, and you will call this function lots of times, then it is a good idea to calculate the plane coefficients once only and cache them.

RETURNS
The distance of the point from the face. The distance will be positive if the point is above the face (ie. inside the plane: see point_distance_to_plane(3)), or negative otherwise.

If edge is not NULL, then it is set to one of the following values:

*edge == -1 if the point is directly above or below the face, corresponding to case (a) above.

*edge == 0 .. nr_points-1 if the point is closest to that particular edge, corresponding to case (b) above.

AUTHOR
Richard Jones <rich@annexia.org>

LICENSE
GNU LGPL (see http://www.gnu.org/)

VERSION
c2lib-1.2.14

SEE ALSO
point_distance_to_plane(3), plane_coefficients(3), point_lies_in_face(3), point_distance_to_line(3).