1 -- Copyright (c) 1991-1999 Matra Datavision
2 -- Copyright (c) 1999-2014 OPEN CASCADE SAS
4 -- This file is part of Open CASCADE Technology software library.
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.
12 -- Alternatively, this file may be used under the terms of Open CASCADE
13 -- commercial license or contractual agreement.
17 -- Describes a unit vector in 3D space. This unit vector is also called "Direction".
19 -- gce_MakeDir which provides functions for more complex
20 -- unit vector constructions
21 -- Geom_Direction which provides additional functions for
22 -- constructing unit vectors and works, in particular, with the
23 -- parametric equations of unit vectors.
31 raises ConstructionError from Standard,
32 DomainError from Standard,
33 OutOfRange from Standard
40 --- Purpose : Creates a direction corresponding to X axis.
43 Create (V : Vec) returns Dir
45 --- Purpose : Normalizes the vector V and creates a direction. Raises ConstructionError if V.Magnitude() <= Resolution.
47 raises ConstructionError;
49 Create (Coord : XYZ) returns Dir
51 --- Purpose : Creates a direction from a triplet of coordinates. Raises ConstructionError if Coord.Modulus() <= Resolution from gp.
53 raises ConstructionError;
55 Create ( Xv, Yv, Zv : Real) returns Dir
57 --- Purpose : Creates a direction with its 3 cartesian coordinates. Raises ConstructionError if Sqrt(Xv*Xv + Yv*Yv + Zv*Zv) <= Resolution
58 raises ConstructionError;
60 --- Purpose : Modification of the direction's coordinates
61 -- If Sqrt (X*X + Y*Y + Z*Z) <= Resolution from gp where
62 -- X, Y ,Z are the new coordinates it is not possible to
63 -- construct the direction and the method raises the
64 -- exception ConstructionError.
67 SetCoord (me: in out; Index : Integer; Xi : Real)
70 -- For this unit vector, assigns the value Xi to:
71 -- - the X coordinate if Index is 1, or
72 -- - the Y coordinate if Index is 2, or
73 -- - the Z coordinate if Index is 3,
74 -- and then normalizes it.
76 -- Remember that all the coordinates of a unit vector are
77 -- implicitly modified when any single one is changed directly.
79 -- Standard_OutOfRange if Index is not 1, 2, or 3.
80 -- Standard_ConstructionError if either of the following
81 -- is less than or equal to gp::Resolution():
82 -- - Sqrt(Xv*Xv + Yv*Yv + Zv*Zv), or
83 -- - the modulus of the number triple formed by the new
84 -- value Xi and the two other coordinates of this vector
85 -- that were not directly modified.
91 SetCoord (me : in out; Xv, Yv, Zv : Real) raises ConstructionError is static;
93 ---Purpose: For this unit vector, assigns the values Xv, Yv and Zv to its three coordinates.
94 -- Remember that all the coordinates of a unit vector are
95 -- implicitly modified when any single one is changed directly.
98 SetX (me: in out; X : Real) raises ConstructionError is static;
100 ---Purpose: Assigns the given value to the X coordinate of this unit vector.
102 SetY (me: in out; Y : Real) raises ConstructionError is static;
104 ---Purpose: Assigns the given value to the Y coordinate of this unit vector.
106 SetZ (me: in out; Z : Real) raises ConstructionError is static;
108 ---Purpose: Assigns the given value to the Z coordinate of this unit vector.
110 SetXYZ (me: in out; Coord : XYZ) raises ConstructionError is static;
112 ---Purpose: Assigns the three coordinates of Coord to this unit vector.
114 Coord (me; Index : Integer) returns Real
117 -- Returns the coordinate of range Index :
118 -- Index = 1 => X is returned
119 -- Index = 2 => Y is returned
120 -- Index = 3 => Z is returned
122 -- Standard_OutOfRange if Index is not 1, 2, or 3.
126 Coord (me; Xv, Yv, Zv : out Real) is static;
128 ---Purpose: Returns for the unit vector its three coordinates Xv, Yv, and Zv.
130 X (me) returns Real is static;
132 ---Purpose: Returns the X coordinate for a unit vector.
134 Y (me) returns Real is static;
136 ---Purpose: Returns the Y coordinate for a unit vector.
138 Z (me) returns Real is static;
140 ---Purpose: Returns the Z coordinate for a unit vector.
142 XYZ (me) returns XYZ is static;
144 ---C++: return const&
145 --- Purpose : for this unit vector, returns its three coordinates as a number triplea.
147 IsEqual (me; Other : Dir; AngularTolerance : Real) returns Boolean
151 -- Returns True if the angle between the two directions is
152 -- lower or equal to AngularTolerance.
155 IsNormal(me; Other : Dir; AngularTolerance : Real) returns Boolean
159 -- Returns True if the angle between this unit vector and the unit vector Other is equal to Pi/2 (normal).
161 IsOpposite (me; Other : Dir; AngularTolerance : Real) returns Boolean
165 -- Returns True if the angle between this unit vector and the unit vector Other is equal to Pi (opposite).
168 IsParallel (me; Other : Dir; AngularTolerance : Real) returns Boolean
172 -- Returns true if the angle between this unit vector and the
173 -- unit vector Other is equal to 0 or to Pi.
174 -- Note: the tolerance criterion is given by AngularTolerance.
176 Angle (me; Other : Dir) returns Real is static;
178 -- Computes the angular value in radians between <me> and
179 -- <Other>. This value is always positive in 3D space.
180 -- Returns the angle in the range [0, PI]
183 AngleWithRef (me; Other, VRef : Dir) returns Real
185 -- Computes the angular value between <me> and <Other>.
186 -- <VRef> is the direction of reference normal to <me> and <Other>
187 -- and its orientation gives the positive sense of rotation.
188 -- If the cross product <me> ^ <Other> has the same orientation
189 -- as <VRef> the angular value is positive else negative.
190 -- Returns the angular value in the range -PI and PI (in radians). Raises DomainError if <me> and <Other> are not parallel this exception is raised
191 -- when <VRef> is in the same plane as <me> and <Other>
192 -- The tolerance criterion is Resolution from package gp.
199 Cross (me : in out; Right : Dir) raises ConstructionError is static;
200 --- Purpose : Computes the cross product between two directions
201 -- Raises the exception ConstructionError if the two directions
202 -- are parallel because the computed vector cannot be normalized
203 -- to create a direction.
205 ---C++: alias operator ^=
207 Crossed (me; Right : Dir) returns Dir raises ConstructionError is static;
208 --- Purpose : Computes the triple vector product.
210 -- Raises the exception ConstructionError if V1 and V2 are parallel
211 -- or <me> and (V1^V2) are parallel because the computed vector
212 -- can't be normalized to create a direction.
214 ---C++: alias operator ^
216 CrossCross (me : in out; V1, V2 : Dir) raises ConstructionError is static;
217 --- Propose: Computes the double vector product this ^ (V1 ^ V2).
218 -- CrossCross assigns the result to this unit vector
220 -- Standard_ConstructionError if:
221 -- - V1 and V2 are parallel, or
222 -- - this unit vector and (V1 ^ V2) are parallel.
223 -- This is because, in these conditions, the computed vector
224 -- is null and cannot be normalized.
227 CrossCrossed (me; V1, V2 : Dir) returns Dir raises ConstructionError
229 --- Purpose: Computes the double vector product this ^ (V1 ^ V2).
230 -- - CrossCrossed creates a new unit vector.
232 -- Standard_ConstructionError if:
233 -- - V1 and V2 are parallel, or
234 -- - this unit vector and (V1 ^ V2) are parallel.
235 -- This is because, in these conditions, the computed vector
236 -- is null and cannot be normalized.
239 Dot (me; Other : Dir) returns Real is static;
240 --- Purpose : Computes the scalar product
242 ---C++: alias operator *
245 DotCross (me; V1, V2 : Dir) returns Real is static;
247 -- Computes the triple scalar product <me> * (V1 ^ V2).
249 -- The computed vector V1' = V1 ^ V2 is not normalized
250 -- to create a unitary vector. So this method never
251 -- raises an exception even if V1 and V2 are parallel.
254 Reverse (me : in out) is static;
257 Reversed (me) returns Dir is static;
258 --- Purpose : Reverses the orientation of a direction
260 ---C++: alias operator -
263 --- Purpose : geometric transformations
264 -- Performs the symmetrical transformation of a direction
265 -- with respect to the direction V which is the center of
268 Mirror (me : in out; V : Dir) is static;
270 Mirrored (me; V : Dir) returns Dir is static;
272 -- Performs the symmetrical transformation of a direction
273 -- with respect to the direction V which is the center of
277 Mirror (me : in out; A1 : Ax1) is static;
279 Mirrored (me; A1 : Ax1) returns Dir is static;
281 -- Performs the symmetrical transformation of a direction
282 -- with respect to an axis placement which is the axis
286 Mirror (me : in out; A2 : Ax2) is static;
288 Mirrored (me; A2 : Ax2) returns Dir is static;
291 -- Performs the symmetrical transformation of a direction
292 -- with respect to a plane. The axis placement A2 locates
293 -- the plane of the symmetry : (Location, XDirection, YDirection).
295 Rotate (me : in out; A1 : Ax1; Ang : Real) is static;
298 Rotated (me; A1 : Ax1; Ang : Real) returns Dir is static;
301 -- Rotates a direction. A1 is the axis of the rotation.
302 -- Ang is the angular value of the rotation in radians.
304 Transform (me : in out; T : Trsf) is static;
306 Transformed (me; T : Trsf) returns Dir is static;
308 -- Transforms a direction with a "Trsf" from gp.
310 -- If the scale factor of the "Trsf" T is negative then the
311 -- direction <me> is reversed.