BRL-CAD
tol.h
Go to the documentation of this file.
1 /* T O L . H
2  * BRL-CAD
3  *
4  * Copyright (c) 2004-2014 United States Government as represented by
5  * the U.S. Army Research Laboratory.
6  *
7  * This library is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Lesser General Public License
9  * version 2.1 as published by the Free Software Foundation.
10  *
11  * This library is distributed in the hope that it will be useful, but
12  * WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  * Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public
17  * License along with this file; see the file named COPYING for more
18  * information.
19  */
20 
21 /*----------------------------------------------------------------------*/
22 /** @file tol.h */
23 /** @addtogroup tol */
24 /** @{ */
25 /** @brief Support for uniform tolerances
26  *
27  * A handy way of passing around the tolerance information needed to
28  * perform approximate floating-point calculations on geometry.
29  *
30  * dist & dist_sq establish the distance tolerance.
31  *
32  * If two points are closer together than dist, then they are to be
33  * considered the same point.
34  *
35  * For example:
36  @code
37  point_t a, b;
38  vect_t diff;
39  VSUB2(diff, a, b);
40  if (MAGNITUDE(diff) < tol->dist) a & b are the same.
41  or, more efficiently:
42  if (MAQSQ(diff) < tol->dist_sq)
43  @endcode
44  * perp & para establish the angular tolerance.
45  *
46  * If two rays emanate from the same point, and their dot product is
47  * nearly one, then the two rays are the same, while if their dot
48  * product is nearly zero, then they are perpendicular.
49  *
50  * For example:
51  @code
52  vect_t a, b;
53  if (fabs(VDOT(a, b)) >= tol->para) a & b are parallel
54  if (fabs(VDOT(a, b)) <= tol->perp) a & b are perpendicular
55  @endcode
56  *
57  *@note
58  * tol->dist_sq = tol->dist * tol->dist;
59  *@n tol->para = 1 - tol->perp;
60  */
61 
62 #ifndef BN_TOL_H
63 #define BN_TOL_H
64 
65 #include "common.h"
66 #include "bn/defines.h"
67 #include "bu/magic.h"
68 
70 
71 struct bn_tol {
72  uint32_t magic;
73  double dist; /**< @brief >= 0 */
74  double dist_sq; /**< @brief dist * dist */
75  double perp; /**< @brief nearly 0 */
76  double para; /**< @brief nearly 1 */
77 };
78 
79 /**
80  * asserts the validity of a bn_tol struct.
81  */
82 #define BN_CK_TOL(_p) BU_CKMAG(_p, BN_TOL_MAGIC, "bn_tol")
83 
84 /**
85  * initializes a bn_tol struct to zero without allocating any memory.
86  */
87 #define BN_TOL_INIT(_p) { \
88  (_p)->magic = BN_TOL_MAGIC; \
89  (_p)->dist = 0.0; \
90  (_p)->dist_sq = 0.0; \
91  (_p)->perp = 0.0; \
92  (_p)->para = 1.0; \
93  }
94 
95 /**
96  * macro suitable for declaration statement zero-initialization of a
97  * bn_tol struct.
98  */
99 #define BN_TOL_INIT_ZERO { BN_TOL_MAGIC, 0.0, 0.0, 0.0, 1.0 }
100 
101 /**
102  * returns truthfully whether a bn_tol struct has been initialized.
103  */
104 #define BN_TOL_IS_INITIALIZED(_p) (((struct bn_tol *)(_p) != (struct bn_tol *)0) && LIKELY((_p)->magic == BN_TOL_MAGIC))
105 
106 /**
107  * replaces the hard coded tolerance value
108  */
109 #define BN_TOL_DIST 0.0005
110 
111 /**
112  * returns truthfully whether a given dot-product of two unspecified
113  * vectors are within a specified parallel tolerance.
114  */
115 #define BN_VECT_ARE_PARALLEL(_dot, _tol) \
116  (((_dot) <= -SMALL_FASTF) ? (NEAR_EQUAL((_dot), -1.0, (_tol)->perp)) : (NEAR_EQUAL((_dot), 1.0, (_tol)->perp)))
117 
118 /**
119  * returns truthfully whether a given dot-product of two unspecified
120  * vectors are within a specified perpendicularity tolerance.
121  */
122 #define BN_VECT_ARE_PERP(_dot, _tol) \
123  (((_dot) < 0) ? ((-(_dot))<=(_tol)->perp) : ((_dot) <= (_tol)->perp))
124 
126 
127 #endif /* BN_TOL_H */
128 /** @} */
129 /*
130  * Local Variables:
131  * mode: C
132  * tab-width: 8
133  * indent-tabs-mode: t
134  * c-file-style: "stroustrup"
135  * End:
136  * ex: shiftwidth=4 tabstop=8
137  */
double dist
>= 0
Definition: tol.h:73
double dist_sq
dist * dist
Definition: tol.h:74
Header file for the BRL-CAD common definitions.
#define __BEGIN_DECLS
Definition: common.h:73
Support for uniform tolerances.
Definition: tol.h:71
double perp
nearly 0
Definition: tol.h:75
uint32_t magic
Definition: tol.h:72
#define __END_DECLS
Definition: common.h:74
double para
nearly 1
Definition: tol.h:76