doc/point_distance_to_face.3.html

   1 <html>
   2 <head>
   3 <meta name="generator" content="groff -Thtml, see www.gnu.org">
   4 <meta name="Content-Style" content="text/css">
   5 <title>point_distance_to_face</title>
   6 </head>
   7 <body>
   8
   9 <h1 align=center>point_distance_to_face</h1>
  10 <a href="#NAME">NAME</a><br>
  11 <a href="#SYNOPSIS">SYNOPSIS</a><br>
  12 <a href="#DESCRIPTION">DESCRIPTION</a><br>
  13 <a href="#RETURNS">RETURNS</a><br>
  14 <a href="#AUTHOR">AUTHOR</a><br>
  15 <a href="#LICENSE">LICENSE</a><br>
  16 <a href="#VERSION">VERSION</a><br>
  17 <a href="#SEE ALSO">SEE ALSO</a><br>
  18
  19 <hr>
  20 <!-- Creator     : groff version 1.17.2 -->
  21 <!-- CreationDate: Fri May  3 14:57:33 2002 -->
  22 <a name="NAME"></a>
  23 <h2>NAME</h2>
  24 <table width="100%" border=0 rules="none" frame="void"
  25        cols="2" cellspacing="0" cellpadding="0">
  26 <tr valign="top" align="left">
  27 <td width="10%"></td><td width="90%">
  28 point_distance_to_face - distance from point to bounded convex polygon (face)</td></table>
  29 <a name="SYNOPSIS"></a>
  30 <h2>SYNOPSIS</h2>
  31
  32 <table width="100%" border=0 rules="none" frame="void"
  33        cols="2" cellspacing="0" cellpadding="0">
  34 <tr valign="top" align="left">
  35 <td width="10%"></td><td width="90%">
  36 <pre><b>#include &lt;matvec.h&gt;
  37
  38 float point_distance_to_face (const float *points, int nr_points, const float *plane, const float *point, int *edge);
  39 </b></pre></td></table>
  40 <a name="DESCRIPTION"></a>
  41 <h2>DESCRIPTION</h2>
  42
  43 <table width="100%" border=0 rules="none" frame="void"
  44        cols="2" cellspacing="0" cellpadding="0">
  45 <tr valign="top" align="left">
  46 <td width="10%"></td><td width="90%">
  47 Given a point and a bounded convex polygon (a
  48 &quot;face&quot;), the function
  49 <b>point_distance_to_face</b> calculates the distance from
  50 the point to the face. There are two importance cases to
  51 consider here:</td></table>
  52
  53 <table width="100%" border=0 rules="none" frame="void"
  54        cols="2" cellspacing="0" cellpadding="0">
  55 <tr valign="top" align="left">
  56 <td width="10%"></td><td width="90%">
  57 (a) The point is directly above or below the face. In other
  58 words, a line dropped from the point perpendicular to the
  59 face intersects the face within the boundary of the polygon.
  60 In this case, the function returns the shortest distance
  61 from the point to the intersection (and is essentially
  62 equivalent to <b>point_distance_to_plane</b>).</td></table>
  63
  64 <table width="100%" border=0 rules="none" frame="void"
  65        cols="2" cellspacing="0" cellpadding="0">
  66 <tr valign="top" align="left">
  67 <td width="10%"></td><td width="90%">
  68 (b) The point is not directly above or below the face. In
  69 this case the function works out the distance to the nearest
  70 edge of the face.</td></table>
  71
  72 <table width="100%" border=0 rules="none" frame="void"
  73        cols="2" cellspacing="0" cellpadding="0">
  74 <tr valign="top" align="left">
  75 <td width="10%"></td><td width="90%">
  76 The face is specified as a list of points and a plane (ie.
  77 plane coefficients). If <b>plane</b> is <b>NULL</b>, then
  78 the function calls <b>plane_coefficients(3)</b> on your
  79 behalf. If the face is fixed, and you will call this
  80 function lots of times, then it is a good idea to calculate
  81 the plane coefficients once only and cache
  82 them.</td></table>
  83 <a name="RETURNS"></a>
  84 <h2>RETURNS</h2>
  85
  86 <table width="100%" border=0 rules="none" frame="void"
  87        cols="2" cellspacing="0" cellpadding="0">
  88 <tr valign="top" align="left">
  89 <td width="10%"></td><td width="90%">
  90 The distance of the point from the face. The distance will
  91 be positive if the point is above the face (ie. inside the
  92 plane: see <b>point_distance_to_plane(3)</b>), or negative
  93 otherwise.</td></table>
  94
  95 <table width="100%" border=0 rules="none" frame="void"
  96        cols="2" cellspacing="0" cellpadding="0">
  97 <tr valign="top" align="left">
  98 <td width="10%"></td><td width="90%">
  99 If <b>edge</b> is not <b>NULL</b>, then it is set to one of
 100 the following values:</td></table>
 101
 102 <table width="100%" border=0 rules="none" frame="void"
 103        cols="2" cellspacing="0" cellpadding="0">
 104 <tr valign="top" align="left">
 105 <td width="10%"></td><td width="90%">
 106 <b>*edge == -1</b> if the point is directly above or below
 107 the face, corresponding to case (a) above.</td></table>
 108
 109 <table width="100%" border=0 rules="none" frame="void"
 110        cols="2" cellspacing="0" cellpadding="0">
 111 <tr valign="top" align="left">
 112 <td width="10%"></td><td width="90%">
 113 <b>*edge == 0 .. nr_points-1</b> if the point is closest to
 114 that particular edge, corresponding to case (b)
 115 above.</td></table>
 116 <a name="AUTHOR"></a>
 117 <h2>AUTHOR</h2>
 118
 119 <table width="100%" border=0 rules="none" frame="void"
 120        cols="2" cellspacing="0" cellpadding="0">
 121 <tr valign="top" align="left">
 122 <td width="10%"></td><td width="90%">
 123 Richard Jones &lt;rich@annexia.org&gt;</td></table>
 124 <a name="LICENSE"></a>
 125 <h2>LICENSE</h2>
 126
 127 <table width="100%" border=0 rules="none" frame="void"
 128        cols="2" cellspacing="0" cellpadding="0">
 129 <tr valign="top" align="left">
 130 <td width="10%"></td><td width="90%">
 131 GNU LGPL (see http://www.gnu.org/)</td></table>
 132 <a name="VERSION"></a>
 133 <h2>VERSION</h2>
 134
 135 <table width="100%" border=0 rules="none" frame="void"
 136        cols="2" cellspacing="0" cellpadding="0">
 137 <tr valign="top" align="left">
 138 <td width="10%"></td><td width="90%">
 139 c2lib-1.2.13</td></table>
 140 <a name="SEE ALSO"></a>
 141 <h2>SEE ALSO</h2>
 142
 143 <table width="100%" border=0 rules="none" frame="void"
 144        cols="2" cellspacing="0" cellpadding="0">
 145 <tr valign="top" align="left">
 146 <td width="10%"></td><td width="90%">
 147 <b>point_distance_to_plane(3)</b>,
 148 <b>plane_coefficients(3)</b>, <b>point_lies_in_face(3)</b>,
 149 <b>point_distance_to_line(3)</b>.</td></table>
 150 <hr>
 151 </body>
 152 </html>