PQP.h
Go to the documentation of this file.
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 
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 
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 
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
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 
213  PQP_REAL RR[3][3], PQP_REAL T[3], PQP_Model* o1,
214  PQP_REAL P1[3], PQP_REAL P2[3],
215  int flag = PQP_ALL_CONTACTS);
216 
217 
218 #if PQP_BV_TYPE & RSS_TYPE // this is true by default,
219  // and explained in PQP_Compile.h
220 
221 //----------------------------------------------------------------------------
222 //
223 // PQP_DistanceResult
224 //
225 // This saves and reports results from a distance query.
226 //
227 //----------------------------------------------------------------------------
228 //
229 // struct PQP_DistanceResult - declaration contained in PQP_Internal.h
230 // {
231 // // statistics
232 //
233 // int NumBVTests();
234 // int NumTriTests();
235 // PQP_REAL QueryTimeSecs();
236 //
237 // // The following distance and points established the minimum distance
238 // // for the models, within the relative and absolute error bounds
239 // // specified.
240 //
241 // PQP_REAL Distance();
242 // const PQP_REAL *P1(); // pointers to three PQP_REALs
243 // const PQP_REAL *P2();
244 // };
245 
246 //----------------------------------------------------------------------------
247 //
248 // PQP_Distance() - computes the distance between two PQP_Models
249 //
250 //
251 // Declare a PQP_DistanceResult struct and pass its pointer to collect
252 // distance information.
253 //
254 // "rel_err" is the relative error margin from actual distance.
255 // "abs_err" is the absolute error margin from actual distance. The
256 // smaller of the two will be satisfied, so set one large to nullify
257 // its effect.
258 //
259 // "qsize" is an optional parameter controlling the size of a priority
260 // queue used to direct the search for closest points. A larger queue
261 // can help the algorithm discover the minimum with fewer steps, but
262 // will increase the cost of each step. It is not beneficial to increase
263 // qsize if the application has frame-to-frame coherence, i.e., the
264 // pair of models take small steps between each call, since another
265 // speedup trick already accelerates this situation with no overhead.
266 //
267 // However, a queue size of 100 to 200 has been seen to save time in a
268 // planning application with "non-coherent" placements of models.
269 //
270 //----------------------------------------------------------------------------
271 
272 int
273 PQP_Distance(PQP_DistanceResult *result,
274  PQP_REAL R1[3][3], PQP_REAL T1[3], PQP_Model *o1,
275  PQP_REAL R2[3][3], PQP_REAL T2[3], PQP_Model *o2,
276  PQP_REAL rel_err, PQP_REAL abs_err,
277  int qsize = 2);
278 
279 //----------------------------------------------------------------------------
280 //
281 // PQP_ToleranceResult
282 //
283 // This saves and reports results from a tolerance query.
284 //
285 //----------------------------------------------------------------------------
286 //
287 // struct PQP_ToleranceResult - declaration contained in PQP_Internal.h
288 // {
289 // // statistics
290 //
291 // int NumBVTests();
292 // int NumTriTests();
293 // PQP_REAL QueryTimeSecs();
294 //
295 // // If the models are closer than ( <= ) tolerance, these points
296 // // and distance were what established this. Otherwise,
297 // // distance and point values are not meaningful.
298 //
299 // PQP_REAL Distance();
300 // const PQP_REAL *P1();
301 // const PQP_REAL *P2();
302 //
303 // // boolean says whether models are closer than tolerance distance
304 //
305 // int CloserThanTolerance();
306 // };
307 
308 //----------------------------------------------------------------------------
309 //
310 // PQP_Tolerance() - checks if distance between PQP_Models is <= tolerance
311 //
312 //
313 // Declare a PQP_ToleranceResult and pass its pointer to collect
314 // tolerance information.
315 //
316 // The algorithm returns whether the true distance is <= or >
317 // "tolerance". This routine does not simply compute true distance
318 // and compare to the tolerance - models can often be shown closer or
319 // farther than the tolerance more trivially. In most cases this
320 // query should run faster than a distance query would on the same
321 // models and configurations.
322 //
323 // "qsize" again controls the size of a priority queue used for
324 // searching. Not setting qsize is the current recommendation, since
325 // increasing it has only slowed down our applications.
326 //
327 //----------------------------------------------------------------------------
328 
329 int
330 PQP_Tolerance(PQP_ToleranceResult *res,
331  PQP_REAL R1[3][3], PQP_REAL T1[3], PQP_Model *o1,
332  PQP_REAL R2[3][3], PQP_REAL T2[3], PQP_Model *o2,
333  PQP_REAL tolerance,
334  int qsize = 2);
335 
336 #endif
337 #endif
338 
339 
340 
341 
342 
343 
const int PQP_ERR_OUT_OF_MEMORY
Definition: PQP.h:61
const int PQP_ERR_UNPROCESSED_MODEL
Definition: PQP.h:66
const int PQP_FIRST_CONTACT
Definition: PQP.h:204
int PQP_Collide(PQP_CollideResult *result, PQP_REAL R1[3][3], PQP_REAL T1[3], PQP_Model *o1, PQP_REAL R2[3][3], PQP_REAL T2[3], PQP_Model *o2, int flag=PQP_ALL_CONTACTS)
const int PQP_ERR_MODEL_OUT_OF_MEMORY
Definition: PQP.h:57
const int PQP_OK
Definition: PQP.h:53
const int PQP_ERR_BUILD_OUT_OF_SEQUENCE
Definition: PQP.h:71
const int PQP_ERR_BUILD_EMPTY_MODEL
Definition: PQP.h:80
int PQP_TriLineIntersect(PQP_CollideResult *result, PQP_REAL RR[3][3], PQP_REAL T[3], PQP_Model *o1, PQP_REAL P1[3], PQP_REAL P2[3], int flag=PQP_ALL_CONTACTS)
png_infop png_uint_32 flag
Definition: png.h:2159
const int PQP_ALL_CONTACTS
Definition: PQP.h:203


openhrp3
Author(s): AIST, General Robotix Inc., Nakamura Lab of Dept. of Mechano Informatics at University of Tokyo
autogenerated on Sat May 8 2021 02:42:40