b537f560b062125a537d9ff1bc51cfbc3bce4fe6
[occt.git] / src / gp / gp_Vec.hxx
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.
14
15 #ifndef _gp_Vec_HeaderFile
16 #define _gp_Vec_HeaderFile
17
18 #include <Standard.hxx>
19 #include <Standard_DefineAlloc.hxx>
20 #include <Standard_Handle.hxx>
21
22 #include <gp_XYZ.hxx>
23 #include <Standard_Real.hxx>
24 #include <Standard_Integer.hxx>
25 #include <Standard_Boolean.hxx>
26 class Standard_ConstructionError;
27 class Standard_DomainError;
28 class Standard_OutOfRange;
29 class gp_VectorWithNullMagnitude;
30 class gp_Dir;
31 class gp_XYZ;
32 class gp_Pnt;
33 class gp_Ax1;
34 class gp_Ax2;
35 class gp_Trsf;
36
37
38
39 //! Defines a non-persistent vector in 3D space.
40 class gp_Vec 
41 {
42 public:
43
44   DEFINE_STANDARD_ALLOC
45
46   
47   //! Creates a zero vector.
48     gp_Vec();
49   
50   //! Creates a unitary vector from a direction V.
51     gp_Vec(const gp_Dir& V);
52   
53   //! Creates a vector with a triplet of coordinates.
54     gp_Vec(const gp_XYZ& Coord);
55   
56   //! Creates a point with its three cartesian coordinates.
57     gp_Vec(const Standard_Real Xv, const Standard_Real Yv, const Standard_Real Zv);
58   
59
60   //! Creates a vector from two points. The length of the vector
61   //! is the distance between P1 and P2
62     gp_Vec(const gp_Pnt& P1, const gp_Pnt& P2);
63   
64   //! Changes the coordinate of range Index
65   //! Index = 1 => X is modified
66   //! Index = 2 => Y is modified
67   //! Index = 3 => Z is modified
68   //! Raised if Index != {1, 2, 3}.
69     void SetCoord (const Standard_Integer Index, const Standard_Real Xi);
70   
71   //! For this vector, assigns
72   //! -   the values Xv, Yv and Zv to its three coordinates.
73     void SetCoord (const Standard_Real Xv, const Standard_Real Yv, const Standard_Real Zv);
74   
75   //! Assigns the given value to the X coordinate of this vector.
76     void SetX (const Standard_Real X);
77   
78   //! Assigns the given value to the X coordinate of this vector.
79     void SetY (const Standard_Real Y);
80   
81   //! Assigns the given value to the X coordinate of this vector.
82     void SetZ (const Standard_Real Z);
83   
84   //! Assigns the three coordinates of Coord to this vector.
85     void SetXYZ (const gp_XYZ& Coord);
86   
87
88   //! Returns the coordinate of range Index :
89   //! Index = 1 => X is returned
90   //! Index = 2 => Y is returned
91   //! Index = 3 => Z is returned
92   //! Raised if Index != {1, 2, 3}.
93     Standard_Real Coord (const Standard_Integer Index) const;
94   
95   //! For this vector returns its three coordinates Xv, Yv, and Zvinline
96     void Coord (Standard_Real& Xv, Standard_Real& Yv, Standard_Real& Zv) const;
97   
98   //! For this vector, returns its X coordinate.
99     Standard_Real X() const;
100   
101   //! For this vector, returns its Y coordinate.
102     Standard_Real Y() const;
103   
104   //! For this vector, returns its Z  coordinate.
105     Standard_Real Z() const;
106   
107   //! For this vector, returns
108   //! -   its three coordinates as a number triple
109     const gp_XYZ& XYZ() const;
110   
111
112   //! Returns True if the two vectors have the same magnitude value
113   //! and the same direction. The precision values are LinearTolerance
114   //! for the magnitude and AngularTolerance for the direction.
115   Standard_EXPORT Standard_Boolean IsEqual (const gp_Vec& Other, const Standard_Real LinearTolerance, const Standard_Real AngularTolerance) const;
116   
117
118   //! Returns True if abs(<me>.Angle(Other) - PI/2.) <= AngularTolerance
119   //! Raises VectorWithNullMagnitude if <me>.Magnitude() <= Resolution or
120   //! Other.Magnitude() <= Resolution from gp
121     Standard_Boolean IsNormal (const gp_Vec& Other, const Standard_Real AngularTolerance) const;
122   
123
124   //! Returns True if PI - <me>.Angle(Other) <= AngularTolerance
125   //! Raises VectorWithNullMagnitude if <me>.Magnitude() <= Resolution or
126   //! Other.Magnitude() <= Resolution from gp
127     Standard_Boolean IsOpposite (const gp_Vec& Other, const Standard_Real AngularTolerance) const;
128   
129
130   //! Returns True if Angle(<me>, Other) <= AngularTolerance or
131   //! PI - Angle(<me>, Other) <= AngularTolerance
132   //! This definition means that two parallel vectors cannot define
133   //! a plane but two vectors with opposite directions are considered
134   //! as parallel. Raises VectorWithNullMagnitude if <me>.Magnitude() <= Resolution or
135   //! Other.Magnitude() <= Resolution from gp
136     Standard_Boolean IsParallel (const gp_Vec& Other, const Standard_Real AngularTolerance) const;
137   
138
139   //! Computes the angular value between <me> and <Other>
140   //! Returns the angle value between 0 and PI in radian.
141   //! Raises VectorWithNullMagnitude if <me>.Magnitude() <= Resolution from gp or
142   //! Other.Magnitude() <= Resolution because the angular value is
143   //! indefinite if one of the vectors has a null magnitude.
144     Standard_Real Angle (const gp_Vec& Other) const;
145   
146   //! Computes the angle, in radians, between this vector and
147   //! vector Other. The result is a value between -Pi and Pi.
148   //! For this, VRef defines the positive sense of rotation: the
149   //! angular value is positive, if the cross product this ^ Other
150   //! has the same orientation as VRef relative to the plane
151   //! defined by the vectors this and Other. Otherwise, the
152   //! angular value is negative.
153   //! Exceptions
154   //! gp_VectorWithNullMagnitude if the magnitude of this
155   //! vector, the vector Other, or the vector VRef is less than or
156   //! equal to gp::Resolution().
157   //! Standard_DomainError if this vector, the vector Other,
158   //! and the vector VRef are coplanar, unless this vector and
159   //! the vector Other are parallel.
160     Standard_Real AngleWithRef (const gp_Vec& Other, const gp_Vec& VRef) const;
161   
162   //! Computes the magnitude of this vector.
163     Standard_Real Magnitude() const;
164   
165   //! Computes the square magnitude of this vector.
166     Standard_Real SquareMagnitude() const;
167   
168   //! Adds two vectors
169     void Add (const gp_Vec& Other);
170   void operator += (const gp_Vec& Other)
171 {
172   Add(Other);
173 }
174   
175   //! Adds two vectors
176   Standard_NODISCARD gp_Vec Added (const gp_Vec& Other) const;
177   Standard_NODISCARD gp_Vec operator + (const gp_Vec& Other) const
178 {
179   return Added(Other);
180 }
181   
182   //! Subtracts two vectors
183     void Subtract (const gp_Vec& Right);
184   void operator -= (const gp_Vec& Right)
185 {
186   Subtract(Right);
187 }
188   
189   //! Subtracts two vectors
190   Standard_NODISCARD gp_Vec Subtracted (const gp_Vec& Right) const;
191   Standard_NODISCARD gp_Vec operator - (const gp_Vec& Right) const
192 {
193   return Subtracted(Right);
194 }
195   
196   //! Multiplies a vector by a scalar
197     void Multiply (const Standard_Real Scalar);
198   void operator *= (const Standard_Real Scalar)
199 {
200   Multiply(Scalar);
201 }
202   
203   //! Multiplies a vector by a scalar
204   Standard_NODISCARD gp_Vec Multiplied (const Standard_Real Scalar) const;
205   Standard_NODISCARD gp_Vec operator * (const Standard_Real Scalar) const
206 {
207   return Multiplied(Scalar);
208 }
209   
210   //! Divides a vector by a scalar
211     void Divide (const Standard_Real Scalar);
212   void operator /= (const Standard_Real Scalar)
213 {
214   Divide(Scalar);
215 }
216   
217   //! Divides a vector by a scalar
218   Standard_NODISCARD gp_Vec Divided (const Standard_Real Scalar) const;
219   Standard_NODISCARD gp_Vec operator / (const Standard_Real Scalar) const
220 {
221   return Divided(Scalar);
222 }
223   
224   //! computes the cross product between two vectors
225     void Cross (const gp_Vec& Right);
226   void operator ^= (const gp_Vec& Right)
227 {
228   Cross(Right);
229 }
230   
231   //! computes the cross product between two vectors
232   Standard_NODISCARD gp_Vec Crossed (const gp_Vec& Right) const;
233   Standard_NODISCARD gp_Vec operator ^ (const gp_Vec& Right) const
234 {
235   return Crossed(Right);
236 }
237   
238
239   //! Computes the magnitude of the cross
240   //! product between <me> and Right.
241   //! Returns || <me> ^ Right ||
242     Standard_Real CrossMagnitude (const gp_Vec& Right) const;
243   
244
245   //! Computes the square magnitude of
246   //! the cross product between <me> and Right.
247   //! Returns || <me> ^ Right ||**2
248     Standard_Real CrossSquareMagnitude (const gp_Vec& Right) const;
249   
250   //! Computes the triple vector product.
251   //! <me> ^= (V1 ^ V2)
252     void CrossCross (const gp_Vec& V1, const gp_Vec& V2);
253   
254   //! Computes the triple vector product.
255   //! <me> ^ (V1 ^ V2)
256     Standard_NODISCARD gp_Vec CrossCrossed (const gp_Vec& V1, const gp_Vec& V2) const;
257   
258   //! computes the scalar product
259     Standard_Real Dot (const gp_Vec& Other) const;
260   Standard_Real operator * (const gp_Vec& Other) const
261 {
262   return Dot(Other);
263 }
264   
265   //! Computes the triple scalar product <me> * (V1 ^ V2).
266     Standard_Real DotCross (const gp_Vec& V1, const gp_Vec& V2) const;
267   
268   //! normalizes a vector
269   //! Raises an exception if the magnitude of the vector is
270   //! lower or equal to Resolution from gp.
271     void Normalize();
272   
273   //! normalizes a vector
274   //! Raises an exception if the magnitude of the vector is
275   //! lower or equal to Resolution from gp.
276     Standard_NODISCARD gp_Vec Normalized() const;
277   
278   //! Reverses the direction of a vector
279     void Reverse();
280   
281   //! Reverses the direction of a vector
282     Standard_NODISCARD gp_Vec Reversed() const;
283   Standard_NODISCARD gp_Vec operator -() const
284 {
285   return Reversed();
286 }
287   
288
289   //! <me> is set to the following linear form :
290   //! A1 * V1 + A2 * V2 + A3 * V3 + V4
291     void SetLinearForm (const Standard_Real A1, const gp_Vec& V1, const Standard_Real A2, const gp_Vec& V2, const Standard_Real A3, const gp_Vec& V3, const gp_Vec& V4);
292   
293
294   //! <me> is set to the following linear form :
295   //! A1 * V1 + A2 * V2 + A3 * V3
296     void SetLinearForm (const Standard_Real A1, const gp_Vec& V1, const Standard_Real A2, const gp_Vec& V2, const Standard_Real A3, const gp_Vec& V3);
297   
298
299   //! <me> is set to the following linear form :
300   //! A1 * V1 + A2 * V2 + V3
301     void SetLinearForm (const Standard_Real A1, const gp_Vec& V1, const Standard_Real A2, const gp_Vec& V2, const gp_Vec& V3);
302   
303
304   //! <me> is set to the following linear form :
305   //! A1 * V1 + A2 * V2
306     void SetLinearForm (const Standard_Real A1, const gp_Vec& V1, const Standard_Real A2, const gp_Vec& V2);
307   
308
309   //! <me> is set to the following linear form : A1 * V1 + V2
310     void SetLinearForm (const Standard_Real A1, const gp_Vec& V1, const gp_Vec& V2);
311   
312
313   //! <me> is set to the following linear form : V1 + V2
314     void SetLinearForm (const gp_Vec& V1, const gp_Vec& V2);
315   
316   Standard_EXPORT void Mirror (const gp_Vec& V);
317   
318
319   //! Performs the symmetrical transformation of a vector
320   //! with respect to the vector V which is the center of
321   //! the  symmetry.
322   Standard_NODISCARD Standard_EXPORT gp_Vec Mirrored (const gp_Vec& V) const;
323   
324   Standard_EXPORT void Mirror (const gp_Ax1& A1);
325   
326
327   //! Performs the symmetrical transformation of a vector
328   //! with respect to an axis placement which is the axis
329   //! of the symmetry.
330   Standard_NODISCARD Standard_EXPORT gp_Vec Mirrored (const gp_Ax1& A1) const;
331   
332   Standard_EXPORT void Mirror (const gp_Ax2& A2);
333   
334
335   //! Performs the symmetrical transformation of a vector
336   //! with respect to a plane. The axis placement A2 locates
337   //! the plane of the symmetry : (Location, XDirection, YDirection).
338   Standard_NODISCARD Standard_EXPORT gp_Vec Mirrored (const gp_Ax2& A2) const;
339   
340     void Rotate (const gp_Ax1& A1, const Standard_Real Ang);
341   
342
343   //! Rotates a vector. A1 is the axis of the rotation.
344   //! Ang is the angular value of the rotation in radians.
345     Standard_NODISCARD gp_Vec Rotated (const gp_Ax1& A1, const Standard_Real Ang) const;
346   
347     void Scale (const Standard_Real S);
348   
349   //! Scales a vector. S is the scaling value.
350     Standard_NODISCARD gp_Vec Scaled (const Standard_Real S) const;
351   
352   //! Transforms a vector with the transformation T.
353   Standard_EXPORT void Transform (const gp_Trsf& T);
354   
355   //! Transforms a vector with the transformation T.
356   Standard_NODISCARD gp_Vec Transformed (const gp_Trsf& T) const;
357   
358   //! Dumps the content of me into the stream
359   Standard_EXPORT void DumpJson (Standard_OStream& theOStream, Standard_Integer theDepth = -1) const;
360
361
362
363
364 protected:
365
366
367
368
369
370 private:
371
372
373
374   gp_XYZ coord;
375
376
377 };
378
379
380 #include <gp_Vec.lxx>
381
382
383
384
385
386 #endif // _gp_Vec_HeaderFile