0024428: Implementation of LGPL license
[occt.git] / src / Precision / Precision.cdl
CommitLineData
b311480e 1-- Created on: 1993-02-17
2-- Created by: Remi LEQUETTE
3-- Copyright (c) 1993-1999 Matra Datavision
973c2be1 4-- Copyright (c) 1999-2014 OPEN CASCADE SAS
b311480e 5--
973c2be1 6-- This file is part of Open CASCADE Technology software library.
b311480e 7--
973c2be1 8-- This library is free software; you can redistribute it and / or modify it
9-- under the terms of the GNU Lesser General Public version 2.1 as published
10-- by the Free Software Foundation, with special exception defined in the file
11-- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
12-- distribution for complete text of the license and disclaimer of any warranty.
b311480e 13--
973c2be1 14-- Alternatively, this file may be used under the terms of Open CASCADE
15-- commercial license or contractual agreement.
7fd59977 16
17package Precision
18
19 ---Purpose: The Precision package offers a set of functions defining precision criteria
20 -- for use in conventional situations when comparing two numbers.
21 -- Generalities
22 -- It is not advisable to use floating number equality. Instead, the difference
23 -- between numbers must be compared with a given precision, i.e. :
24 -- Standard_Real x1, x2 ;
25 -- x1 = ...
26 -- x2 = ...
27 -- If ( x1 == x2 ) ...
28 -- should not be used and must be written as indicated below:
29 -- Standard_Real x1, x2 ;
30 -- Standard_Real Precision = ...
31 -- x1 = ...
32 -- x2 = ...
33 -- If ( Abs ( x1 - x2 ) < Precision ) ...
34 -- Likewise, when ordering floating numbers, you must take the following into account :
35 -- Standard_Real x1, x2 ;
36 -- Standard_Real Precision = ...
37 -- x1 = ... ! a large number
38 -- x2 = ... ! another large number
39 -- If ( x1 < x2 - Precision ) ...
40 -- is incorrect when x1 and x2 are large numbers ; it is better to write :
41 -- Standard_Real x1, x2 ;
42 -- Standard_Real Precision = ...
43 -- x1 = ... ! a large number
44 -- x2 = ... ! another large number
45 -- If ( x2 - x1 > Precision ) ...
46 -- Precision in Cas.Cade
47 -- Generally speaking, the precision criterion is not implicit in Cas.Cade. Low-level geometric algorithms accept
48 -- precision criteria as arguments. As a rule, they should not refer directly to the precision criteria provided by the
49 -- Precision package.
50 -- On the other hand, high-level modeling algorithms have to provide the low-level geometric algorithms that they
51 -- call, with a precision criteria. One way of doing this is to use the above precision criteria.
52 -- Alternatively, the high-level algorithms can have their own system for precision management. For example, the
53 -- Topology Data Structure stores precision criteria for each elementary shape (as a vertex, an edge or a face). When
54 -- a new topological object is constructed, the precision criteria are taken from those provided by the Precision
55 -- package, and stored in the related data structure. Later, a topological algorithm which analyses these objects will
56 -- work with the values stored in the data structure. Also, if this algorithm is to build a new topological object, from
57 -- these precision criteria, it will compute a new precision criterion for the new topological object, and write it into the
58 -- data structure of the new topological object.
59 -- The different precision criteria offered by the Precision package, cover the most common requirements of
60 -- geometric algorithms, such as intersections, approximations, and so on.
61 -- The choice of precision depends on the algorithm and on the geometric space. The geometric space may be :
62 -- - a "real" 2D or 3D space, where the lengths are measured in meters, millimeters, microns, inches, etc ..., or
63 -- - a "parametric" space, 1D on a curve or 2D on a surface, where lengths have no dimension.
64 -- The choice of precision criteria for real space depends on the choice of the product, as it is based on the accuracy
65 -- of the machine and the unit of measurement.
66 -- The choice of precision criteria for parametric space depends on both the accuracy of the machine and the
67 -- dimensions of the curve or the surface, since the parametric precision criterion and the real precision criterion are
68 -- linked : if the curve is defined by the equation P(t), the inequation :
69 -- Abs ( t2 - t1 ) < ParametricPrecision
70 -- means that the parameters t1 and t2 are considered to be equal, and the inequation :
71 -- Distance ( P(t2) , P(t1) ) < RealPrecision
72 -- means that the points P(t1) and P(t2) are considered to be coincident. It seems to be the same idea, and it
73 -- would be wonderful if these two inequations were equivalent. Note that this is rarely the case !
74 -- What is provided in this package?
75 -- The Precision package provides :
76 -- - a set of real space precision criteria for the algorithms, in view of checking distances and angles,
77 -- - a set of parametric space precision criteria for the algorithms, in view of checking both :
78 -- - the equality of parameters in a parametric space,
79 -- - or the coincidence of points in the real space, by using parameter values,
80 -- - the notion of infinite value, composed of a value assumed to be infinite, and checking tests designed to verify
81 -- if any value could be considered as infinite.
82 -- All the provided functions are very simple. The returned values result from the adaptation of the applications
83 -- developed by the Open CASCADE company to Open CASCADE algorithms. The main interest of these functions
84 -- lies in that it incites engineers developing applications to ask questions on precision factors. Which one is to be
85 -- used in such or such case ? Tolerance criteria are context dependent. They must first choose :
86 -- - either to work in real space,
87 -- - or to work in parametric space,
88 -- - or to work in a combined real and parametric space.
89 -- They must next decide which precision factor will give the best answer to the current problem. Within an application
90 -- environment, it is crucial to master precision even though this process may take a great deal of time.
91
92uses
93 Standard
94
95is
96
97 Angular returns Real from Standard;
98 ---Purpose: Returns the recommended precision value
99 -- when checking the equality of two angles (given in radians).
100 -- Standard_Real Angle1 = ... , Angle2 = ... ;
101 -- If ( Abs( Angle2 - Angle1 ) < Precision::Angular() ) ...
102 -- The tolerance of angular equality may be used to check the parallelism of two vectors :
103 -- gp_Vec V1, V2 ;
104 -- V1 = ...
105 -- V2 = ...
106 -- If ( V1.IsParallel (V2, Precision::Angular() ) ) ...
107 -- The tolerance of angular equality is equal to 1.e-12.
108 -- Note : The tolerance of angular equality can be used when working with scalar products or
109 -- cross products since sines and angles are equivalent for small angles. Therefore, in order to
110 -- check whether two unit vectors are perpendicular :
111 -- gp_Dir D1, D2 ;
112 -- D1 = ...
113 -- D2 = ...
114 -- you can use :
115 -- If ( Abs( D1.D2 ) < Precision::Angular() ) ...
116 -- (although the function IsNormal does exist).
117
118 Confusion returns Real from Standard;
119 ---Purpose:
120 -- Returns the recommended precision value when
121 -- checking coincidence of two points in real space.
122 -- The tolerance of confusion is used for testing a 3D
123 -- distance :
124 -- - Two points are considered to be coincident if their
125 -- distance is smaller than the tolerance of confusion.
126 -- gp_Pnt P1, P2 ;
127 -- P1 = ...
128 -- P2 = ...
129 -- if ( P1.IsEqual ( P2 , Precision::Confusion() ) )
130 -- then ...
131 -- - A vector is considered to be null if it has a null length :
132 -- gp_Vec V ;
133 -- V = ...
134 -- if ( V.Magnitude() < Precision::Confusion() ) then ...
135 -- The tolerance of confusion is equal to 1.e-7.
136 -- The value of the tolerance of confusion is also used to
137 -- define :
138 -- - the tolerance of intersection, and
139 -- - the tolerance of approximation.
140 -- Note : As a rule, coordinate values in Cas.Cade are not
141 -- dimensioned, so 1. represents one user unit, whatever
142 -- value the unit may have : the millimeter, the meter, the
143 -- inch, or any other unit. Let's say that Cas.Cade
144 -- algorithms are written to be tuned essentially with
145 -- mechanical design applications, on the basis of the
146 -- millimeter. However, these algorithms may be used with
147 -- any other unit but the tolerance criterion does no longer
148 -- have the same signification.
149 -- So pay particular attention to the type of your application,
150 -- in relation with the impact of your unit on the precision criterion.
151 -- - For example in mechanical design, if the unit is the
152 -- millimeter, the tolerance of confusion corresponds to a
153 -- distance of 1 / 10000 micron, which is rather difficult to measure.
154 -- - However in other types of applications, such as
155 -- cartography, where the kilometer is frequently used,
156 -- the tolerance of confusion corresponds to a greater
157 -- distance (1 / 10 millimeter). This distance
158 -- becomes easily measurable, but only within a restricted
159 -- space which contains some small objects of the complete scene.
160
08cd2f6b 161 SquareConfusion returns Real from Standard;
162 ---Purpose:
163 -- Returns square of Confusion.
164 -- Created for speed and convenience.
165
7fd59977 166 Intersection returns Real from Standard;
167 ---Purpose:Returns the precision value in real space, frequently
168 -- used by intersection algorithms to decide that a solution is reached.
169 -- This function provides an acceptable level of precision
170 -- for an intersection process to define the adjustment limits.
171 -- The tolerance of intersection is designed to ensure
172 -- that a point computed by an iterative algorithm as the
173 -- intersection between two curves is indeed on the
174 -- intersection. It is obvious that two tangent curves are
175 -- close to each other, on a large distance. An iterative
176 -- algorithm of intersection may find points on these
177 -- curves within the scope of the confusion tolerance, but
178 -- still far from the true intersection point. In order to force
179 -- the intersection algorithm to continue the iteration
180 -- process until a correct point is found on the tangent
181 -- objects, the tolerance of intersection must be smaller
182 -- than the tolerance of confusion.
183 -- On the other hand, the tolerance of intersection must
184 -- be large enough to minimize the time required by the
185 -- process to converge to a solution.
186 -- The tolerance of intersection is equal to :
187 -- Precision::Confusion() / 100.
188 -- (that is, 1.e-9).
189
190 Approximation returns Real from Standard;
191 ---Purpose: Returns the precision value in real space, frequently used
192 -- by approximation algorithms.
193 -- This function provides an acceptable level of precision for
194 -- an approximation process to define adjustment limits.
195 -- The tolerance of approximation is designed to ensure
196 -- an acceptable computation time when performing an
197 -- approximation process. That is why the tolerance of
198 -- approximation is greater than the tolerance of confusion.
199 -- The tolerance of approximation is equal to :
200 -- Precision::Confusion() * 10.
201 -- (that is, 1.e-6).
202 -- You may use a smaller tolerance in an approximation
203 -- algorithm, but this option might be costly.
204
205 Parametric(P : Real from Standard; T : Real from Standard)
206 returns Real from Standard;
207 ---Purpose: Convert a real space precision to a parametric
208 -- space precision. <T> is the mean value of the
209 -- length of the tangent of the curve or the surface.
210 --
211 -- Value is P / T
212 --
213 ---C++: inline
214
215 PConfusion(T : Real from Standard) returns Real from Standard;
216 ---Purpose:
217 -- Returns a precision value in parametric space, which may be used :
218 -- - to test the coincidence of two points in the real space,
219 -- by using parameter values, or
220 -- - to test the equality of two parameter values in a parametric space.
221 -- The parametric tolerance of confusion is designed to
222 -- give a mean value in relation with the dimension of
223 -- the curve or the surface. It considers that a variation of
224 -- parameter equal to 1. along a curve (or an
225 -- isoparametric curve of a surface) generates a segment
226 -- whose length is equal to 100. (default value), or T.
227 -- The parametric tolerance of confusion is equal to :
228 -- - Precision::Confusion() / 100., or Precision::Confusion() / T.
229 -- The value of the parametric tolerance of confusion is also used to define :
230 -- - the parametric tolerance of intersection, and
231 -- - the parametric tolerance of approximation.
232 -- Warning
233 -- It is rather difficult to define a unique precision value in parametric space.
234 -- - First consider a curve (c) ; if M is the point of
235 -- parameter u and M' the point of parameter u+du on
236 -- the curve, call 'parametric tangent' at point M, for the
237 -- variation du of the parameter, the quantity :
238 -- T(u,du)=MM'/du (where MM' represents the
239 -- distance between the two points M and M', in the real space).
240 -- - Consider the other curve resulting from a scaling
241 -- transformation of (c) with a scale factor equal to
242 -- 10. The 'parametric tangent' at the point of
243 -- parameter u of this curve is ten times greater than the
244 -- previous one. This shows that for two different curves,
245 -- the distance between two points on the curve, resulting
246 -- from the same variation of parameter du, may vary considerably.
247 -- - Moreover, the variation of the parameter along the
248 -- curve is generally not proportional to the curvilinear
249 -- abscissa along the curve. So the distance between two
250 -- points resulting from the same variation of parameter
251 -- du, at two different points of a curve, may completely differ.
252 -- - Moreover, the parameterization of a surface may
253 -- generate two quite different 'parametric tangent' values
254 -- in the u or in the v parametric direction.
255 -- - Last, close to the poles of a sphere (the points which
256 -- correspond to the values -Pi/2. and Pi/2. of the
257 -- v parameter) the u parameter may change from 0 to
258 -- 2.Pi without impacting on the resulting point.
259 -- Therefore, take great care when adjusting a parametric
260 -- tolerance to your own algorithm.
261
262 PIntersection(T : Real from Standard) returns Real from Standard;
263 ---Purpose:
264 -- Returns a precision value in parametric space, which
265 -- may be used by intersection algorithms, to decide that
266 -- a solution is reached. The purpose of this function is to
267 -- provide an acceptable level of precision in parametric
268 -- space, for an intersection process to define the adjustment limits.
269 -- The parametric tolerance of intersection is
270 -- designed to give a mean value in relation with the
271 -- dimension of the curve or the surface. It considers
272 -- that a variation of parameter equal to 1. along a curve
273 -- (or an isoparametric curve of a surface) generates a
274 -- segment whose length is equal to 100. (default value), or T.
275 -- The parametric tolerance of intersection is equal to :
276 -- - Precision::Intersection() / 100., or Precision::Intersection() / T.
277
278 PApproximation(T : Real from Standard) returns Real from Standard;
279 ---Purpose: Returns a precision value in parametric space, which may
280 -- be used by approximation algorithms. The purpose of this
281 -- function is to provide an acceptable level of precision in
282 -- parametric space, for an approximation process to define
283 -- the adjustment limits.
284 -- The parametric tolerance of approximation is
285 -- designed to give a mean value in relation with the
286 -- dimension of the curve or the surface. It considers
287 -- that a variation of parameter equal to 1. along a curve
288 -- (or an isoparametric curve of a surface) generates a
289 -- segment whose length is equal to 100. (default value), or T.
290 -- The parametric tolerance of intersection is equal to :
291 -- - Precision::Approximation() / 100., or Precision::Approximation() / T.
292
293 Parametric(P : Real from Standard)
294 returns Real from Standard;
295 ---Purpose: Convert a real space precision to a parametric
296 -- space precision on a default curve.
297 --
298 -- Value is Parametric(P,1.e+2)
299 --
300
301 PConfusion returns Real from Standard;
302 ---Purpose: Used to test distances in parametric space on a
303 -- default curve.
304 --
305 -- This is Precision::Parametric(Precision::Confusion())
306 --
307 ---C++: inline
308
309 PIntersection returns Real from Standard;
310 ---Purpose: Used for Intersections in parametric space on a
311 -- default curve.
312 --
313 -- This is Precision::Parametric(Precision::Intersection())
314 --
315 ---C++: inline
316
317 PApproximation returns Real from Standard;
318 ---Purpose: Used for Approximations in parametric space on a
319 -- default curve.
320 --
321 -- This is Precision::Parametric(Precision::Approximation())
322 --
323 ---C++: inline
324
325 IsInfinite(R : Real from Standard) returns Boolean;
326 ---Purpose: Returns True if R may be considered as an infinite
327 -- number. Currently Abs(R) > 1e100
328
329 IsPositiveInfinite(R : Real from Standard) returns Boolean;
330 ---Purpose: Returns True if R may be considered as a positive
331 -- infinite number. Currently R > 1e100
332
333 IsNegativeInfinite(R : Real from Standard) returns Boolean;
334 ---Purpose: Returns True if R may be considered as a negative
335 -- infinite number. Currently R < -1e100
336
337
338 Infinite returns Real;
339 ---Purpose: Returns a big number that can be considered as
340 -- infinite. Use -Infinite() for a negative big number.
341
342end Precision;
343