pqp
 All Classes
PQP.h
1 /*************************************************************************\
2 
3  Copyright 1999 The University of North Carolina at Chapel Hill.
4  All Rights Reserved.
5 
6  Permission to use, copy, modify and distribute this software and its
7  documentation for educational, research and non-profit purposes, without
8  fee, and without a written agreement is hereby granted, provided that the
9  above copyright notice and the following three paragraphs appear in all
10  copies.
11 
12  IN NO EVENT SHALL THE UNIVERSITY OF NORTH CAROLINA AT CHAPEL HILL BE
13  LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR
14  CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, ARISING OUT OF THE
15  USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE UNIVERSITY
16  OF NORTH CAROLINA HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH
17  DAMAGES.
18 
19  THE UNIVERSITY OF NORTH CAROLINA SPECIFICALLY DISCLAIM ANY
20  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
21  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
22  PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
23  NORTH CAROLINA HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT,
24  UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
25 
26  The authors may be contacted via:
27 
28  US Mail: S. Gottschalk, E. Larsen
29  Department of Computer Science
30  Sitterson Hall, CB #3175
31  University of N. Carolina
32  Chapel Hill, NC 27599-3175
33 
34  Phone: (919)962-1749
35 
36  EMail: geom@cs.unc.edu
37 
38 
39 \**************************************************************************/
40 
41 #ifndef PQP_H
42 #define PQP_H
43 
44 #include "PQP_Compile.h"
45 #include "PQP_Internal.h"
46 
47 //----------------------------------------------------------------------------
48 //
49 // PQP API Return Values
50 //
51 //----------------------------------------------------------------------------
52 
53 const int PQP_OK = 0;
54  // Used by all API routines upon successful completion except
55  // constructors and destructors
56 
57 const int PQP_ERR_MODEL_OUT_OF_MEMORY = -1;
58  // Returned when an API function cannot obtain enough memory to
59  // store or process a PQP_Model object.
60 
61 const int PQP_ERR_OUT_OF_MEMORY = -2;
62  // Returned when a PQP query cannot allocate enough storage to
63  // compute or hold query information. In this case, the returned
64  // data should not be trusted.
65 
66 const int PQP_ERR_UNPROCESSED_MODEL = -3;
67  // Returned when an unprocessed model is passed to a function which
68  // expects only processed models, such as PQP_Collide() or
69  // PQP_Distance().
70 
71 const int PQP_ERR_BUILD_OUT_OF_SEQUENCE = -4;
72  // Returned when:
73  // 1. AddTri() is called before BeginModel().
74  // 2. BeginModel() is called immediately after AddTri().
75  // This error code is something like a warning: the invoked
76  // operation takes place anyway, and PQP does what makes "most
77  // sense", but the returned error code may tip off the client that
78  // something out of the ordinary is happenning.
79 
80 const int PQP_ERR_BUILD_EMPTY_MODEL = -5;
81  // Returned when EndModel() is called on a model to which no
82  // triangles have been added. This is similar in spirit to the
83  // OUT_OF_SEQUENCE return code, except that the requested operation
84  // has FAILED -- the model remains "unprocessed", and the client may
85  // NOT use it in queries.
86 
87 //----------------------------------------------------------------------------
88 //
89 // PQP_REAL
90 //
91 // The floating point type used throughout the package. The type is defined
92 // in PQP_Compile.h, and by default is "double"
93 //
94 //----------------------------------------------------------------------------
95 
96 //----------------------------------------------------------------------------
97 //
98 // PQP_Model
99 //
100 // A PQP_Model stores geometry to be used in a proximity query.
101 // The geometry is loaded with a call to BeginModel(), at least one call to
102 // AddTri(), and then a call to EndModel().
103 //
104 // // create a two triangle model, m
105 //
106 // PQP_Model m;
107 //
108 // PQP_REAL p1[3],p2[3],p3[3]; // 3 points will make triangle p
109 // PQP_REAL q1[3],q2[3],q3[3]; // another 3 points for triangle q
110 //
111 // // some initialization of these vertices not shown
112 //
113 // m.BeginModel(); // begin the model
114 // m.AddTri(p1,p2,p3,0); // add triangle p
115 // m.AddTri(q1,q2,q3,1); // add triangle q
116 // m.EndModel(); // end (build) the model
117 //
118 // The last parameter of AddTri() is the number to be associated with the
119 // triangle. These numbers are used to identify the triangles that overlap.
120 //
121 // AddTri() copies into the PQP_Model the data pointed to by the three vertex
122 // pointers, so that it is safe to delete vertex data after you have
123 // passed it to AddTri().
124 //
125 //----------------------------------------------------------------------------
126 //
127 // class PQP_Model - declaration contained in PQP_Internal.h
128 // {
129 //
130 // public:
131 // PQP_Model();
132 // ~PQP_Model();
133 //
134 // int BeginModel(int num_tris = 8); // preallocate for num_tris triangles;
135 // // the parameter is optional, since
136 // // arrays are reallocated as needed
137 //
138 // int AddTri(const PQP_REAL *p1, const PQP_REAL *p2, const PQP_REAL *p3,
139 // int id);
140 //
141 // int EndModel();
142 // int MemUsage(int msg); // returns model mem usage in bytes
143 // // prints message to stderr if msg == TRUE
144 // };
145 
146 //----------------------------------------------------------------------------
147 //
148 // PQP_CollideResult
149 //
150 // This saves and reports results from a collision query.
151 //
152 //----------------------------------------------------------------------------
153 //
154 // struct PQP_CollideResult - declaration contained in PQP_Internal.h
155 // {
156 // // statistics
157 //
158 // int NumBVTests();
159 // int NumTriTests();
160 // PQP_REAL QueryTimeSecs();
161 //
162 // // free the list of contact pairs; ordinarily this list is reused
163 // // for each query, and only deleted in the destructor.
164 //
165 // void FreePairsList();
166 //
167 // // query results
168 //
169 // int Colliding();
170 // int NumPairs();
171 // int Id1(int k);
172 // int Id2(int k);
173 // };
174 
175 //----------------------------------------------------------------------------
176 //
177 // PQP_Collide() - detects collision between two PQP_Models
178 //
179 //
180 // Declare a PQP_CollideResult struct and pass its pointer to collect
181 // collision data.
182 //
183 // [R1, T1] is the placement of model 1 in the world &
184 // [R2, T2] is the placement of model 2 in the world.
185 // The columns of each 3x3 matrix are the basis vectors for the model
186 // in world coordinates, and the matrices are in row-major order:
187 // R(row r, col c) = R[r][c].
188 //
189 // If PQP_ALL_CONTACTS is the flag value, after calling PQP_Collide(),
190 // the PQP_CollideResult object will contain an array with all
191 // colliding triangle pairs. Suppose CR is a pointer to the
192 // PQP_CollideResult object. The number of pairs is gotten from
193 // CR->NumPairs(), and the ids of the 15'th pair of colliding
194 // triangles is gotten from CR->Id1(14) and CR->Id2(14).
195 //
196 // If PQP_FIRST_CONTACT is the flag value, the PQP_CollideResult array
197 // will only get the first colliding triangle pair found. Thus
198 // CR->NumPairs() will be at most 1, and if 1, CR->Id1(0) and
199 // CR->Id2(0) give the ids of the colliding triangle pair.
200 //
201 //----------------------------------------------------------------------------
202 
203 const int PQP_ALL_CONTACTS = 1; // find all pairwise intersecting triangles
204 const int PQP_FIRST_CONTACT = 2; // report first intersecting tri pair found
205 
206 int
207 PQP_Collide(PQP_CollideResult *result,
208  PQP_REAL R1[3][3], PQP_REAL T1[3], PQP_Model *o1,
209  PQP_REAL R2[3][3], PQP_REAL T2[3], PQP_Model *o2,
210  int flag = PQP_ALL_CONTACTS);
211 
212 
213 #if PQP_BV_TYPE & RSS_TYPE // this is true by default,
214  // and explained in PQP_Compile.h
215 
216 //----------------------------------------------------------------------------
217 //
218 // PQP_DistanceResult
219 //
220 // This saves and reports results from a distance query.
221 //
222 //----------------------------------------------------------------------------
223 //
224 // struct PQP_DistanceResult - declaration contained in PQP_Internal.h
225 // {
226 // // statistics
227 //
228 // int NumBVTests();
229 // int NumTriTests();
230 // PQP_REAL QueryTimeSecs();
231 //
232 // // The following distance and points established the minimum distance
233 // // for the models, within the relative and absolute error bounds
234 // // specified.
235 //
236 // PQP_REAL Distance();
237 // const PQP_REAL *P1(); // pointers to three PQP_REALs
238 // const PQP_REAL *P2();
239 // };
240 
241 //----------------------------------------------------------------------------
242 //
243 // PQP_Distance() - computes the distance between two PQP_Models
244 //
245 //
246 // Declare a PQP_DistanceResult struct and pass its pointer to collect
247 // distance information.
248 //
249 // "rel_err" is the relative error margin from actual distance.
250 // "abs_err" is the absolute error margin from actual distance. The
251 // smaller of the two will be satisfied, so set one large to nullify
252 // its effect.
253 //
254 // "qsize" is an optional parameter controlling the size of a priority
255 // queue used to direct the search for closest points. A larger queue
256 // can help the algorithm discover the minimum with fewer steps, but
257 // will increase the cost of each step. It is not beneficial to increase
258 // qsize if the application has frame-to-frame coherence, i.e., the
259 // pair of models take small steps between each call, since another
260 // speedup trick already accelerates this situation with no overhead.
261 //
262 // However, a queue size of 100 to 200 has been seen to save time in a
263 // planning application with "non-coherent" placements of models.
264 //
265 //----------------------------------------------------------------------------
266 
267 int
268 PQP_Distance(PQP_DistanceResult *result,
269  PQP_REAL R1[3][3], PQP_REAL T1[3], PQP_Model *o1,
270  PQP_REAL R2[3][3], PQP_REAL T2[3], PQP_Model *o2,
271  PQP_REAL rel_err, PQP_REAL abs_err,
272  int qsize = 2);
273 
274 //----------------------------------------------------------------------------
275 //
276 // PQP_ToleranceResult
277 //
278 // This saves and reports results from a tolerance query.
279 //
280 //----------------------------------------------------------------------------
281 //
282 // struct PQP_ToleranceResult - declaration contained in PQP_Internal.h
283 // {
284 // // statistics
285 //
286 // int NumBVTests();
287 // int NumTriTests();
288 // PQP_REAL QueryTimeSecs();
289 //
290 // // If the models are closer than ( <= ) tolerance, these points
291 // // and distance were what established this. Otherwise,
292 // // distance and point values are not meaningful.
293 //
294 // PQP_REAL Distance();
295 // const PQP_REAL *P1();
296 // const PQP_REAL *P2();
297 //
298 // // boolean says whether models are closer than tolerance distance
299 //
300 // int CloserThanTolerance();
301 // };
302 
303 //----------------------------------------------------------------------------
304 //
305 // PQP_Tolerance() - checks if distance between PQP_Models is <= tolerance
306 //
307 //
308 // Declare a PQP_ToleranceResult and pass its pointer to collect
309 // tolerance information.
310 //
311 // The algorithm returns whether the true distance is <= or >
312 // "tolerance". This routine does not simply compute true distance
313 // and compare to the tolerance - models can often be shown closer or
314 // farther than the tolerance more trivially. In most cases this
315 // query should run faster than a distance query would on the same
316 // models and configurations.
317 //
318 // "qsize" again controls the size of a priority queue used for
319 // searching. Not setting qsize is the current recommendation, since
320 // increasing it has only slowed down our applications.
321 //
322 //----------------------------------------------------------------------------
323 
324 int
325 PQP_Tolerance(PQP_ToleranceResult *res,
326  PQP_REAL R1[3][3], PQP_REAL T1[3], PQP_Model *o1,
327  PQP_REAL R2[3][3], PQP_REAL T2[3], PQP_Model *o2,
328  PQP_REAL tolerance,
329  int qsize = 2);
330 
331 #endif
332 #endif
333 
334 
335 
336 
337 
338