1 -- Copyright (c) 1991-1999 Matra Datavision
2 -- Copyright (c) 1999-2014 OPEN CASCADE SAS
3 --
4 -- This file is part of Open CASCADE Technology software library.
5 --
6 -- This library is free software; you can redistribute it and/or modify it under
7 -- the terms of the GNU Lesser General Public License version 2.1 as published
8 -- by the Free Software Foundation, with special exception defined in the file
9 -- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
10 -- distribution for complete text of the license and disclaimer of any warranty.
11 --
12 -- Alternatively, this file may be used under the terms of Open CASCADE
13 -- commercial license or contractual agreement.
15 class Vec   from gp
17         --- Purpose :
18         --  Defines a non-persistent vector in 3D space.
21 uses Ax1  from gp,
22      Ax2  from gp,
23      Dir  from gp,
24      Pnt  from gp,
25      Trsf from gp,
26      XYZ  from gp
28 raises ConstructionError        from Standard,
29        DomainError              from Standard,
30        OutOfRange               from Standard,
31        VectorWithNullMagnitude  from gp
33 is
35   Create   returns Vec;
36         ---C++: inline
37         --- Purpose : Creates a zero vector.
40   Create (V : Dir)  returns Vec;
41         ---C++: inline
42         --- Purpose : Creates a unitary vector from a direction V.
44   Create (Coord : XYZ)  returns Vec;
45         ---C++: inline
46         --- Purpose : Creates a vector with a triplet of coordinates.
48   Create (Xv, Yv, Zv : Real)  returns Vec;
49         ---C++: inline
50         --- Purpose : Creates a point with its three cartesian coordinates.
52   Create (P1, P2 : Pnt)  returns Vec;
53         ---C++: inline
54         --- Purpose :
55         --  Creates a vector from two points. The length of the vector
56         --  is the distance between P1 and P2
58   SetCoord(me: in out; Index : Integer; Xi : Real)
59         ---C++: inline
60         --- Purpose : Changes the coordinate of range Index
61         --  Index = 1 => X is modified
62         --  Index = 2 => Y is modified
63         --  Index = 3 => Z is modified
64      raises OutOfRange
65         --- Purpose : Raised if Index != {1, 2, 3}.
66      is static;
68   SetCoord (me : in out; Xv, Yv, Zv : Real)   is static;
69         ---C++: inline
70         ---Purpose: For this vector, assigns
71         -- -   the values Xv, Yv and Zv to its three coordinates.
73   SetX (me: in out; X : Real)                 is static;
74         ---Purpose: Assigns the given value to the X coordinate of this vector.
75         ---C++: inline
77   SetY (me: in out; Y : Real)                 is static;
78         ---Purpose: Assigns the given value to the X coordinate of this vector.
79         ---C++: inline
81   SetZ (me: in out; Z : Real)                 is static;
82          ---Purpose: Assigns the given value to the X coordinate of this vector.
83         ---C++: inline
85   SetXYZ (me: in out; Coord : XYZ)            is static;
86         ---Purpose: Assigns the three coordinates of Coord to this vector.
87         ---C++: inline
89   Coord (me; Index : Integer)   returns Real
90         ---C++: inline
91         --- Purpose :
92         --  Returns the coordinate of range Index :
93         --  Index = 1 => X is returned
94         --  Index = 2 => Y is returned
95         --  Index = 3 => Z is returned
96       raises OutOfRange
97         --- Purpose : Raised if Index != {1, 2, 3}.
98       is static;
100   Coord (me; Xv, Yv, Zv : out Real)   is static;
101         ---Purpose: For this vector returns its three coordinates Xv, Yv, and Zvinline
102         ---C++: inline
104   X (me)  returns Real                is static;
105         ---Purpose: For this vector, returns its X coordinate.
106         ---C++: inline
108   Y (me)  returns Real                is static;
109         ---Purpose: For this vector, returns its Y coordinate.
110         ---C++: inline
112   Z (me)  returns Real                is static;
113         ---Purpose: For this vector, returns its Z  coordinate.
114         ---C++: inline
116   XYZ (me)  returns XYZ               is static;
117         ---Purpose:    For this vector, returns
118         -- -   its three coordinates as a number triple
119         ---C++: inline
120         ---C++: return const&
122   IsEqual (me; Other : Vec; LinearTolerance, AngularTolerance : Real)
123      returns Boolean
124        --- Purpose :
125        --  Returns True if the two vectors have the same magnitude value
126        --  and the same direction. The precision values are LinearTolerance
127        --  for the magnitude and AngularTolerance for the direction.
128      is static;
130   IsNormal (me; Other : Vec; AngularTolerance : Real)     returns Boolean
131         --- Purpose :
132         --  Returns True if abs(<me>.Angle(Other) - PI/2.) <= AngularTolerance
133         --   Raises VectorWithNullMagnitude if <me>.Magnitude() <= Resolution or
134         --  Other.Magnitude() <= Resolution from gp
135         ---C++: inline
136      raises VectorWithNullMagnitude
138      is static;
140   IsOpposite (me; Other : Vec; AngularTolerance : Real)   returns Boolean
141         --- Purpose :
142         --  Returns True if PI - <me>.Angle(Other) <= AngularTolerance
143         --  Raises VectorWithNullMagnitude if <me>.Magnitude() <= Resolution or
144         --  Other.Magnitude() <= Resolution from gp
145         ---C++: inline
146      raises VectorWithNullMagnitude
148      is static;
150   IsParallel (me; Other : Vec; AngularTolerance : Real)   returns Boolean
151         --- Purpose :
152         --  Returns True if Angle(<me>, Other) <= AngularTolerance or
153         --  PI - Angle(<me>, Other) <= AngularTolerance
154         --  This definition means that two parallel vectors cannot define
155         --  a plane but two vectors with opposite directions are considered
156         --  as parallel. Raises VectorWithNullMagnitude if <me>.Magnitude() <= Resolution or
157         --  Other.Magnitude() <= Resolution from gp
158         ---C++: inline
159      raises VectorWithNullMagnitude
161      is static;
163   Angle (me; Other : Vec)  returns Real
164         --- Purpose :
165         --  Computes the angular value between <me> and <Other>
166         --  Returns the angle value between 0 and PI in radian.
167         --    Raises VectorWithNullMagnitude if <me>.Magnitude() <= Resolution from gp or
168         --  Other.Magnitude() <= Resolution because the angular value is
169         --  indefinite if one of the vectors has a null magnitude.
170         ---C++: inline
171      raises VectorWithNullMagnitude
173      is static;
176   AngleWithRef (me; Other , VRef : Vec)   returns Real
177         ---C++: inline
178         --- Purpose : Computes the angle, in radians, between this vector and
179         -- vector Other. The result is a value between -Pi and Pi.
180         -- For this, VRef defines the positive sense of rotation: the
181         -- angular value is positive, if the cross product this ^ Other
182         -- has the same orientation as VRef relative to the plane
183         -- defined by the vectors this and Other. Otherwise, the
184         -- angular value is negative.
185         -- Exceptions
186         -- gp_VectorWithNullMagnitude if the magnitude of this
187         -- vector, the vector Other, or the vector VRef is less than or
188         -- equal to gp::Resolution().
189         -- Standard_DomainError if this vector, the vector Other,
190         -- and the vector VRef are coplanar, unless this vector and
191         -- the vector Other are parallel.
193      raises VectorWithNullMagnitude,
195             DomainError
197      is static;
199   Magnitude (me)   returns Real        is static;
200         ---Purpose: Computes the magnitude of this vector.
201         ---C++: inline
203   SquareMagnitude (me)   returns Real  is static;
204          ---Purpose: Computes the square magnitude of this vector.
205          ---C++: inline
207         --- Purpose : Adds two vectors
209   Add (me : in out; Other : Vec)          is static;
210         ---C++: inline
211         ---C++: alias operator +=
213   Added (me; Other : Vec)  returns Vec    is static;
214         ---C++: inline
215         ---C++: alias operator +
216   --- Purpose : Adds two vectors
217         --- Purpose : Subtracts two vectors
219   Subtract (me : in out; Right : Vec)       is static;
220         ---C++: inline
221         ---C++: alias operator -=
223   Subtracted (me; Right : Vec)  returns Vec  is static;
224         ---C++: inline
225         ---C++: alias operator -
226         --- Purpose : Subtracts two vectors
227         --- Purpose : Multiplies a vector by a scalar
229   Multiply (me : in out; Scalar : Real)           is static;
230         ---C++: inline
231         ---C++: alias operator *=
233   Multiplied (me; Scalar : Real)   returns Vec   is static;
234         ---C++: inline
235         ---C++: alias operator *
236     --- Purpose : Multiplies a vector by a scalar
237         --- Purpose : Divides a vector by a scalar
239   Divide (me : in out; Scalar : Real)             is static;
240         ---C++: inline
241         ---C++: alias operator /=
243   Divided (me; Scalar : Real)   returns Vec      is static;
244         ---C++: inline
245         ---C++: alias operator /
246         --- Purpose : Divides a vector by a scalar
248         --- Purpose : computes the cross product between two vectors
250   Cross (me : in out; Right : Vec)                     is static;
251         ---C++: inline
252         ---C++: alias operator ^=
254   Crossed (me; Right : Vec)  returns Vec               is static;
255         --- Purpose : computes the cross product between two vectors
256         ---C++: inline
257         ---C++: alias operator ^
259   CrossMagnitude (me; Right : Vec) returns Real        is static;
260         --- Purpose :
261         --  Computes the magnitude of the cross
262         --  product between <me> and Right.
263         --  Returns || <me> ^ Right ||
264         ---C++: inline
266   CrossSquareMagnitude (me; Right : Vec) returns Real  is static;
267         --- Purpose :
268         --  Computes the square magnitude of
269         --  the cross product between <me> and Right.
270         --  Returns || <me> ^ Right ||**2
271         ---C++: inline
273         --- Purpose : Computes the triple vector product.
274         --  <me> ^ (V1 ^ V2)
276   CrossCross (me : in out; V1, V2 : Vec)          is static;
277         ---C++: inline
279   CrossCrossed (me; V1, V2 : Vec)   returns Vec   is static;
280         ---C++: inline
282         --- Purpose : Computes the triple vector product.
283         --  <me> ^ (V1 ^ V2)
285   Dot (me; Other : Vec)  returns Real            is static;
286         ---C++: inline
287         ---C++: alias operator *
288         --- Purpose : computes the scalar product
290   DotCross (me; V1, V2 : Vec)  returns Real      is static;
291         ---C++: inline
292         --- Purpose : Computes the triple scalar product <me> * (V1 ^ V2).
295         --- Purpose : normalizes a vector
296         --  Raises an exception if the magnitude of the vector is
297         --  lower or equal to Resolution from gp.
299   Normalize (me : in out)       raises ConstructionError   is static;
300         ---C++: inline
302   Normalized (me)  returns Vec  raises ConstructionError   is static;
303         --- Purpose : normalizes a vector
304         --  Raises an exception if the magnitude of the vector is
305         --  lower or equal to Resolution from gp.
306         ---C++: inline
308         --- Purpose : Reverses the direction of a vector
310   Reverse (me : in out)        is static;
311         ---C++: inline
313   Reversed (me)  returns Vec   is static;
314         --- Purpose : Reverses the direction of a vector
315         ---C++: inline
316         ---C++: alias operator -
318    SetLinearForm (me : in out;
319                  A1 : Real; V1 : Vec; A2 : Real; V2 : Vec;
320                  A3 : Real; V3 : Vec; V4 : Vec)
321      is static;
322         --- Purpose :
323         --  <me> is setted to the following linear form :
324         --  A1 * V1 + A2 * V2 + A3 * V3 + V4
325         ---C++: inline
327   SetLinearForm (me : in out;
328                  A1 : Real; V1 : Vec; A2 : Real; V2 : Vec; A3 : Real; V3 : Vec)
329      is static;
330         --- Purpose :
331         --  <me> is setted to the following linear form :
332         --  A1 * V1 + A2 * V2 + A3 * V3
333         ---C++: inline
335   SetLinearForm (me : in out;
336                  A1 : Real; V1 : Vec; A2 : Real; V2 : Vec; V3 : Vec)
337      is static;
338         --- Purpose :
339         --  <me> is setted to the following linear form :
340         --  A1 * V1 + A2 * V2 + V3
341         ---C++: inline
343   SetLinearForm (me : in out; A1 : Real; V1 : Vec; A2 : Real; V2 : Vec)
344      is static;
345         --- Purpose :
346         --  <me> is setted to the following linear form :
347         --  A1 * V1 + A2 * V2
348         ---C++: inline
350   SetLinearForm (me : in out; A1 : Real; V1, V2 : Vec)
351      is static;
352         --- Purpose :
353         --  <me> is setted to the following linear form : A1 * V1 + V2
354         ---C++: inline
356   SetLinearForm (me : in out; V1, V2 : Vec)
357      is static;
358         --- Purpose :
359         --  <me> is setted to the following linear form : V1 + V2
360         ---C++: inline
362   Mirror (me : in out; V : Vec)          is static;
364   Mirrored (me; V : Vec) returns Vec     is static;
365         --- Purpose :
366         --  Performs the symmetrical transformation of a vector
367         --  with respect to the vector V which is the center of
368         --  the  symmetry.
370   Mirror (me : in out; A1 : Ax1)         is static;
372   Mirrored (me; A1 : Ax1)  returns Vec   is static;
373         --- Purpose :
374         --  Performs the symmetrical transformation of a vector
375         --  with respect to an axis placement which is the axis
376         --  of the symmetry.
378   Mirror (me : in out; A2 : Ax2)         is static;
380   Mirrored (me; A2 : Ax2)   returns Vec  is static;
381  --- Purpose :
382         --  Performs the symmetrical transformation of a vector
383         --  with respect to a plane. The axis placement A2 locates
384         --  the plane of the symmetry : (Location, XDirection, YDirection).
387   Rotate (me : in out; A1 : Ax1; Ang : Real)       is static;
388        ---C++: inline
390   Rotated (me; A1 : Ax1; Ang : Real)  returns Vec  is static;
391         --- Purpose :
392         --  Rotates a vector. A1 is the axis of the rotation.
393         --  Ang is the angular value of the rotation in radians.
394         ---C++: inline
396     Scale (me : in out; S : Real)       is static;
397        ---C++: inline
399     Scaled (me; S : Real)  returns Vec  is static;
400         --- Purpose : Scales a vector. S is the scaling value.
401         ---C++: inline
402         --- Purpose : Transforms a vector with the transformation T.
404   Transform (me : in out; T : Trsf)         is static;
406   Transformed (me; T : Trsf)   returns Vec  is static;
407        ---C++: inline
408        --- Purpose : Transforms a vector with the transformation T.
409 fields
411   coord : XYZ;
413 end;