[occt.git] / src / gp / gp_Dir.cdl

-- Copyright (c) 1991-1999 Matra Datavision
-- Copyright (c) 1999-2012 OPEN CASCADE SAS
--
-- The content of this file is subject to the Open CASCADE Technology Public
-- License Version 6.5 (the "License"). You may not use the content of this file
-- except in compliance with the License. Please obtain a copy of the License
-- at http://www.opencascade.org and read it completely before using this file.
--
-- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
-- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
--
-- The Original Code and all software distributed under the License is
-- distributed on an "AS IS" basis, without warranty of any kind, and the
-- Initial Developer hereby disclaims all such warranties, including without
-- limitation, any warranties of merchantability, fitness for a particular
-- purpose or non-infringement. Please see the License for the specific terms
-- and conditions governing the rights and limitations under the License.


class Dir   from gp  inherits Storable
        ---Purpose:
        -- Describes a unit vector in 3D space. This unit vector is also called "Direction".
        -- See Also
        -- gce_MakeDir which provides functions for more complex
        -- unit vector constructions
        -- Geom_Direction which provides additional functions for
        -- constructing unit vectors and works, in particular, with the
        -- parametric equations of unit vectors.

uses  Ax1  from gp,
      Ax2  from gp,
      Trsf from gp,
      Vec  from gp,
      XYZ  from gp

raises ConstructionError from Standard,
       DomainError       from Standard,
       OutOfRange        from Standard

is


  Create  returns Dir;
        ---C++:inline
        --- Purpose : Creates a direction corresponding to X axis.
   

  Create (V : Vec)  returns Dir
        ---C++:inline
        --- Purpose : Normalizes the vector V and creates a direction. Raises ConstructionError if V.Magnitude() <= Resolution.

     raises ConstructionError;

  Create (Coord : XYZ)   returns Dir
        ---C++:inline
        --- Purpose : Creates a direction from a triplet of coordinates. Raises ConstructionError if Coord.Modulus() <= Resolution from gp.

     raises ConstructionError;
  
  Create ( Xv, Yv, Zv : Real)  returns Dir
        ---C++:inline  
        --- Purpose : Creates a direction with its 3 cartesian coordinates. Raises ConstructionError if Sqrt(Xv*Xv + Yv*Yv + Zv*Zv) <= Resolution
     raises ConstructionError;
 
        --- Purpose : Modification of the direction's coordinates
        --  If Sqrt (X*X + Y*Y + Z*Z) <= Resolution from gp where 
        --  X, Y ,Z are the new coordinates it is not possible to 
        --  construct the direction and the method raises the 
        --  exception ConstructionError.


  SetCoord (me: in out; Index : Integer; Xi : Real)
        ---C++:inline
        ---Purpose:
    	-- For this unit vector,  assigns the value Xi to:
    	--   -   the X coordinate if Index is 1, or
    	--   -   the Y coordinate if Index is 2, or
    	--   -   the Z coordinate if Index is 3, 
    	--   and then normalizes it.
    	-- Warning
    	-- Remember that all the coordinates of a unit vector are
    	-- implicitly modified when any single one is changed directly.
    	-- Exceptions
    	-- Standard_OutOfRange if Index is not 1, 2, or 3.
    	-- Standard_ConstructionError if either of the following
    	-- is less than or equal to gp::Resolution():
    	-- -   Sqrt(Xv*Xv + Yv*Yv + Zv*Zv), or
    	-- -   the modulus of the number triple formed by the new
    	--   value Xi and the two other coordinates of this vector
    	--   that were not directly modified.      
        
     raises OutOfRange,
           ConstructionError
     is static;

  SetCoord (me : in out; Xv, Yv, Zv : Real) raises ConstructionError is static;
          ---C++:inline
    	---Purpose: For this unit vector,  assigns the values Xv, Yv and Zv to its three coordinates. 
    	-- Remember that all the coordinates of a unit vector are
    	-- implicitly modified when any single one is changed directly.


  SetX (me: in out; X : Real)      raises ConstructionError  is static;
        ---C++:inline
    	---Purpose: Assigns the given value to the X coordinate of this   unit vector.

  SetY (me: in out; Y : Real)      raises ConstructionError  is static;
        ---C++:inline
    	---Purpose: Assigns the given value to the Y coordinate of this   unit vector.

  SetZ (me: in out; Z : Real)      raises ConstructionError  is static;
        ---C++:inline
    	---Purpose: Assigns the given value to the Z  coordinate of this   unit vector.

  SetXYZ (me: in out; Coord : XYZ) raises ConstructionError  is static;
        ---C++:inline
	---Purpose: Assigns the three coordinates of Coord to this unit vector. 

  Coord (me; Index : Integer)   returns Real
        ---C++:inline
        --- Purpose :
        --  Returns the coordinate of range Index :
        --  Index = 1 => X is returned
        --  Index = 2 => Y is returned
        --  Index = 3 => Z is returned
    	-- Exceptions
        -- Standard_OutOfRange if Index is not 1, 2, or 3.
    raises OutOfRange
      is static;

  Coord (me; Xv, Yv, Zv : out Real) is static;
        ---C++:inline  
    	---Purpose: Returns for the  unit vector  its three coordinates Xv, Yv, and Zv.
    
  X (me)  returns Real              is static;
        ---C++:inline
    	---Purpose: Returns the X coordinate for a  unit vector.

  Y (me)  returns Real              is static;
        ---C++:inline
    	---Purpose: Returns the Y coordinate for a  unit vector.

  Z (me)  returns Real              is static;
        ---C++:inline
    	---Purpose: Returns the Z coordinate for a  unit vector.

  XYZ (me)  returns XYZ             is static;
        ---C++: inline
    	---C++: return const&
    	--- Purpose : for this unit vector, returns  its three coordinates as a number triplea.

  IsEqual (me; Other : Dir; AngularTolerance : Real)     returns Boolean
     is static;
       ---C++:inline
       --- Purpose : 
       --  Returns True if the angle between the two directions is
       --  lower or equal to AngularTolerance.


  IsNormal(me; Other : Dir; AngularTolerance : Real)     returns Boolean
     is static;
        ---C++: inline                  
        --- Purpose :
        --  Returns True if  the angle between this unit vector and the unit vector Other is equal to Pi/2 (normal).

  IsOpposite (me; Other : Dir; AngularTolerance : Real)  returns Boolean
     is static;
        ---C++: inline     
        --- Purpose:
	--  Returns True if  the angle between this unit vector and the unit vector Other is equal to  Pi (opposite).


  IsParallel (me; Other : Dir; AngularTolerance : Real)  returns Boolean
     is static;
        ---C++: inline     
        --- Purpose :
        -- Returns true if the angle between this unit vector and the
    	-- unit vector Other is equal to 0 or to Pi.
    	-- Note: the tolerance criterion is given by AngularTolerance.

  Angle (me; Other : Dir)   returns Real   is static;
        --- Purpose :
    	--  Computes the angular value in radians between <me> and
    	--  <Other>. This value is always positive in 3D space.
    	--  Returns the angle in the range [0, PI]


  AngleWithRef (me; Other, VRef : Dir)  returns Real
        --- Purpose :
        --  Computes the angular value between <me> and <Other>.
        --  <VRef> is the direction of reference normal to <me> and <Other>
        --  and its orientation gives the positive sense of rotation.
        --  If the cross product <me> ^ <Other> has the same orientation 
        --  as <VRef> the angular value is positive else negative.
        --  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
        --  when <VRef> is in the same plane as <me> and <Other>
        --  The tolerance criterion is Resolution from package gp.
     raises  DomainError
  
     is static;


  Cross (me : in out; Right : Dir)        raises ConstructionError  is static;
        --- Purpose : Computes the cross product between two directions
        --  Raises the exception ConstructionError if the two directions
        --  are parallel because the computed vector cannot be normalized
        --  to create a direction.    
        ---C++: inline
	---C++: alias operator ^=
	
  Crossed (me; Right : Dir)  returns Dir  raises ConstructionError  is static;
    --- Purpose : Computes the triple vector product.
        --  <me> ^ (V1 ^ V2)
        --  Raises the exception ConstructionError if V1 and V2 are parallel 
        --  or <me> and (V1^V2) are parallel because the computed vector 
        --  can't be normalized to create a direction.
        ---C++: inline
        ---C++: alias operator ^

  CrossCross (me : in out; V1, V2 : Dir)  raises ConstructionError  is static;
    	--- Propose:  Computes the double vector product this ^ (V1 ^ V2).
    	--   CrossCross assigns the result to this unit vector 
    	-- Exceptions
    	-- Standard_ConstructionError if:
    	-- -   V1 and V2 are parallel, or
    	-- -   this unit vector and (V1 ^ V2) are parallel.
    	-- This is because, in these conditions, the computed vector
    	-- is null and cannot be normalized.
	---C++: inline
	
  CrossCrossed (me; V1, V2 : Dir)  returns Dir  raises ConstructionError
     is static;
	--- Purpose:  Computes the double vector product this ^ (V1 ^ V2).
    	--  -   CrossCrossed creates a new unit vector. 
    	-- Exceptions
    	-- Standard_ConstructionError if:
    	-- -   V1 and V2 are parallel, or
    	-- -   this unit vector and (V1 ^ V2) are parallel.
    	-- This is because, in these conditions, the computed vector
    	-- is null and cannot be normalized.
        ---C++: inline

  Dot (me; Other : Dir)   returns Real   is static;
        --- Purpose : Computes the scalar product
        ---C++: inline
        ---C++: alias operator *


  DotCross (me; V1, V2 : Dir)  returns Real   is static;
        --- Purpose : 
        --  Computes the triple scalar product <me> * (V1 ^ V2).
        -- Warnings :
        --  The computed vector V1' = V1 ^ V2 is not normalized
        --  to create a unitary vector. So this method never 
        --  raises an exception even if V1 and V2 are parallel.
        ---C++: inline

  Reverse (me : in out)        is static;
        ---C++: inline
	
  Reversed (me)  returns Dir   is static;
        --- Purpose : Reverses the orientation of a direction
        ---C++: inline
        ---C++: alias operator -


	--- Purpose : geometric transformations
        --  Performs the symmetrical transformation of a direction
        --  with respect to the direction V which is the center of 
        --  the  symmetry.]
	
  Mirror (me : in out; V : Dir)         is static;

  Mirrored (me; V : Dir)  returns Dir   is static;
        --- Purpose :
        --  Performs the symmetrical transformation of a direction
        --  with respect to the direction V which is the center of 
        --  the  symmetry.


  Mirror (me : in out; A1 : Ax1)        is static;

  Mirrored (me; A1 : Ax1)  returns Dir  is static;
        --- Purpose :
        --  Performs the symmetrical transformation of a direction
        --  with respect to an axis placement which is the axis
        --  of the symmetry.

 
  Mirror (me : in out; A2 : Ax2)        is static;

  Mirrored (me; A2 : Ax2)  returns Dir  is static;

        --- Purpose :
        --  Performs the symmetrical transformation of a direction
        --  with respect to a plane. The axis placement A2 locates 
        --  the plane of the symmetry : (Location, XDirection, YDirection).

  Rotate (me : in out; A1 : Ax1; Ang : Real)         is static;
        ---C++: inline  
  
  Rotated (me; A1 : Ax1; Ang : Real)   returns Dir   is static;
        ---C++: inline  
        --- Purpose :
        --  Rotates a direction. A1 is the axis of the rotation.
        --  Ang is the angular value of the rotation in radians.

 Transform   (me : in out; T : Trsf)      is static;

  Transformed (me; T : Trsf)  returns Dir  is static;
    	--- Purpose : 
        --  Transforms a direction with a "Trsf" from gp.
        -- Warnings :
        --  If the scale factor of the "Trsf" T is negative then the
        --  direction <me> is reversed.
        ---C++: inline

      
fields

    coord : XYZ;

end;
Commit	Line	Data
b311480e	1	-- Copyright (c) 1991-1999 Matra Datavision
	2	-- Copyright (c) 1999-2012 OPEN CASCADE SAS
	3	--
	4	-- The content of this file is subject to the Open CASCADE Technology Public
	5	-- License Version 6.5 (the "License"). You may not use the content of this file
	6	-- except in compliance with the License. Please obtain a copy of the License
	7	-- at http://www.opencascade.org and read it completely before using this file.
	8	--
	9	-- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
	10	-- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
	11	--
	12	-- The Original Code and all software distributed under the License is
	13	-- distributed on an "AS IS" basis, without warranty of any kind, and the
	14	-- Initial Developer hereby disclaims all such warranties, including without
	15	-- limitation, any warranties of merchantability, fitness for a particular
	16	-- purpose or non-infringement. Please see the License for the specific terms
	17	-- and conditions governing the rights and limitations under the License.
	18
7fd59977	19
	20	class Dir from gp inherits Storable
	21	---Purpose:
	22	-- Describes a unit vector in 3D space. This unit vector is also called "Direction".
	23	-- See Also
	24	-- gce_MakeDir which provides functions for more complex
	25	-- unit vector constructions
	26	-- Geom_Direction which provides additional functions for
	27	-- constructing unit vectors and works, in particular, with the
	28	-- parametric equations of unit vectors.
	29
	30	uses Ax1 from gp,
	31	Ax2 from gp,
	32	Trsf from gp,
	33	Vec from gp,
	34	XYZ from gp
	35
	36	raises ConstructionError from Standard,
	37	DomainError from Standard,
	38	OutOfRange from Standard
	39
	40	is
	41
	42
	43	Create returns Dir;
	44	---C++:inline
	45	--- Purpose : Creates a direction corresponding to X axis.
	46
	47
	48	Create (V : Vec) returns Dir
	49	---C++:inline
	50	--- Purpose : Normalizes the vector V and creates a direction. Raises ConstructionError if V.Magnitude() <= Resolution.
	51
	52	raises ConstructionError;
	53
	54	Create (Coord : XYZ) returns Dir
	55	---C++:inline
	56	--- Purpose : Creates a direction from a triplet of coordinates. Raises ConstructionError if Coord.Modulus() <= Resolution from gp.
	57
	58	raises ConstructionError;
	59
	60	Create ( Xv, Yv, Zv : Real) returns Dir
	61	---C++:inline
	62	--- Purpose : Creates a direction with its 3 cartesian coordinates. Raises ConstructionError if Sqrt(XvXv + YvYv + Zv*Zv) <= Resolution
	63	raises ConstructionError;
	64
	65	--- Purpose : Modification of the direction's coordinates
	66	-- If Sqrt (XX + YY + Z*Z) <= Resolution from gp where
	67	-- X, Y ,Z are the new coordinates it is not possible to
	68	-- construct the direction and the method raises the
	69	-- exception ConstructionError.
	70
	71
	72	SetCoord (me: in out; Index : Integer; Xi : Real)
	73	---C++:inline
	74	---Purpose:
	75	-- For this unit vector, assigns the value Xi to:
	76	-- - the X coordinate if Index is 1, or
	77	-- - the Y coordinate if Index is 2, or
	78	-- - the Z coordinate if Index is 3,
	79	-- and then normalizes it.
	80	-- Warning
	81	-- Remember that all the coordinates of a unit vector are
	82	-- implicitly modified when any single one is changed directly.
83	-- Exceptions
84	-- Standard_OutOfRange if Index is not 1, 2, or 3.
85	-- Standard_ConstructionError if either of the following
86	-- is less than or equal to gp::Resolution():
87	-- - Sqrt(XvXv + YvYv + Zv*Zv), or
88	-- - the modulus of the number triple formed by the new
89	-- value Xi and the two other coordinates of this vector
90	-- that were not directly modified.
91
92	raises OutOfRange,
93	ConstructionError
94	is static;
95
96	SetCoord (me : in out; Xv, Yv, Zv : Real) raises ConstructionError is static;
97	---C++:inline
98	---Purpose: For this unit vector, assigns the values Xv, Yv and Zv to its three coordinates.
99	-- Remember that all the coordinates of a unit vector are
100	-- implicitly modified when any single one is changed directly.
101
102
103	SetX (me: in out; X : Real) raises ConstructionError is static;
104	---C++:inline
105	---Purpose: Assigns the given value to the X coordinate of this unit vector.
106
107	SetY (me: in out; Y : Real) raises ConstructionError is static;
108	---C++:inline
109	---Purpose: Assigns the given value to the Y coordinate of this unit vector.
110
111	SetZ (me: in out; Z : Real) raises ConstructionError is static;
112	---C++:inline
113	---Purpose: Assigns the given value to the Z coordinate of this unit vector.
114
115	SetXYZ (me: in out; Coord : XYZ) raises ConstructionError is static;
116	---C++:inline
117	---Purpose: Assigns the three coordinates of Coord to this unit vector.
118
119	Coord (me; Index : Integer) returns Real
120	---C++:inline
121	--- Purpose :
122	-- Returns the coordinate of range Index :
123	-- Index = 1 => X is returned
124	-- Index = 2 => Y is returned
125	-- Index = 3 => Z is returned
126	-- Exceptions
127	-- Standard_OutOfRange if Index is not 1, 2, or 3.
128	raises OutOfRange
129	is static;
130
131	Coord (me; Xv, Yv, Zv : out Real) is static;
132	---C++:inline
133	---Purpose: Returns for the unit vector its three coordinates Xv, Yv, and Zv.
134
135	X (me) returns Real is static;
136	---C++:inline
137	---Purpose: Returns the X coordinate for a unit vector.
138
139	Y (me) returns Real is static;
140	---C++:inline
141	---Purpose: Returns the Y coordinate for a unit vector.
142
143	Z (me) returns Real is static;
144	---C++:inline
145	---Purpose: Returns the Z coordinate for a unit vector.
146
147	XYZ (me) returns XYZ is static;
148	---C++: inline
149	---C++: return const&
150	--- Purpose : for this unit vector, returns its three coordinates as a number triplea.
151
152	IsEqual (me; Other : Dir; AngularTolerance : Real) returns Boolean
153	is static;
154	---C++:inline
155	--- Purpose :
156	-- Returns True if the angle between the two directions is
157	-- lower or equal to AngularTolerance.
158
159
160	IsNormal(me; Other : Dir; AngularTolerance : Real) returns Boolean
161	is static;
162	---C++: inline
163	--- Purpose :
164	-- Returns True if the angle between this unit vector and the unit vector Other is equal to Pi/2 (normal).
165
166	IsOpposite (me; Other : Dir; AngularTolerance : Real) returns Boolean
167	is static;
168	---C++: inline
169	--- Purpose:
170	-- Returns True if the angle between this unit vector and the unit vector Other is equal to Pi (opposite).
171
172
173	IsParallel (me; Other : Dir; AngularTolerance : Real) returns Boolean
174	is static;
175	---C++: inline
176	--- Purpose :
177	-- Returns true if the angle between this unit vector and the
178	-- unit vector Other is equal to 0 or to Pi.
179	-- Note: the tolerance criterion is given by AngularTolerance.
180
181	Angle (me; Other : Dir) returns Real is static;
182	--- Purpose :
183	-- Computes the angular value in radians between <me> and
184	-- <Other>. This value is always positive in 3D space.
185	-- Returns the angle in the range [0, PI]
186
187
188	AngleWithRef (me; Other, VRef : Dir) returns Real
189	--- Purpose :
190	-- Computes the angular value between <me> and <Other>.
191	-- <VRef> is the direction of reference normal to <me> and <Other>
192	-- and its orientation gives the positive sense of rotation.
193	-- If the cross product <me> ^ <Other> has the same orientation
194	-- as <VRef> the angular value is positive else negative.
195	-- 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
196	-- when <VRef> is in the same plane as <me> and <Other>
197	-- The tolerance criterion is Resolution from package gp.
198	raises DomainError
199
200	is static;
201
202
203
204	Cross (me : in out; Right : Dir) raises ConstructionError is static;
205	--- Purpose : Computes the cross product between two directions
206	-- Raises the exception ConstructionError if the two directions
207	-- are parallel because the computed vector cannot be normalized
208	-- to create a direction.
209	---C++: inline
210	---C++: alias operator ^=
211
212	Crossed (me; Right : Dir) returns Dir raises ConstructionError is static;
213	--- Purpose : Computes the triple vector product.
214	-- <me> ^ (V1 ^ V2)
215	-- Raises the exception ConstructionError if V1 and V2 are parallel
216	-- or <me> and (V1^V2) are parallel because the computed vector
217	-- can't be normalized to create a direction.
218	---C++: inline
219	---C++: alias operator ^
220
221	CrossCross (me : in out; V1, V2 : Dir) raises ConstructionError is static;
222	--- Propose: Computes the double vector product this ^ (V1 ^ V2).
223	-- CrossCross assigns the result to this unit vector
224	-- Exceptions
225	-- Standard_ConstructionError if:
226	-- - V1 and V2 are parallel, or
227	-- - this unit vector and (V1 ^ V2) are parallel.
228	-- This is because, in these conditions, the computed vector
229	-- is null and cannot be normalized.
230	---C++: inline
231
232	CrossCrossed (me; V1, V2 : Dir) returns Dir raises ConstructionError
233	is static;
234	--- Purpose: Computes the double vector product this ^ (V1 ^ V2).
235	-- - CrossCrossed creates a new unit vector.
236	-- Exceptions
237	-- Standard_ConstructionError if:
238	-- - V1 and V2 are parallel, or
239	-- - this unit vector and (V1 ^ V2) are parallel.
240	-- This is because, in these conditions, the computed vector
241	-- is null and cannot be normalized.
242	---C++: inline
243
244	Dot (me; Other : Dir) returns Real is static;
245	--- Purpose : Computes the scalar product
246	---C++: inline
247	---C++: alias operator *
248
249
250	DotCross (me; V1, V2 : Dir) returns Real is static;
251	--- Purpose :
252	-- Computes the triple scalar product <me> * (V1 ^ V2).
253	-- Warnings :
254	-- The computed vector V1' = V1 ^ V2 is not normalized
255	-- to create a unitary vector. So this method never
256	-- raises an exception even if V1 and V2 are parallel.
257	---C++: inline
258
259	Reverse (me : in out) is static;
260	---C++: inline
261
262	Reversed (me) returns Dir is static;
263	--- Purpose : Reverses the orientation of a direction
264	---C++: inline
265	---C++: alias operator -
266
267
268	--- Purpose : geometric transformations
269	-- Performs the symmetrical transformation of a direction
270	-- with respect to the direction V which is the center of
271	-- the symmetry.]
272
273	Mirror (me : in out; V : Dir) is static;
274
275	Mirrored (me; V : Dir) returns Dir is static;
276	--- Purpose :
277	-- Performs the symmetrical transformation of a direction
278	-- with respect to the direction V which is the center of
279	-- the symmetry.
280
281
282	Mirror (me : in out; A1 : Ax1) is static;
283
284	Mirrored (me; A1 : Ax1) returns Dir is static;
285	--- Purpose :
286	-- Performs the symmetrical transformation of a direction
287	-- with respect to an axis placement which is the axis
288	-- of the symmetry.
289
290
291	Mirror (me : in out; A2 : Ax2) is static;
292
293	Mirrored (me; A2 : Ax2) returns Dir is static;
294
295	--- Purpose :
296	-- Performs the symmetrical transformation of a direction
297	-- with respect to a plane. The axis placement A2 locates
298	-- the plane of the symmetry : (Location, XDirection, YDirection).
299
300	Rotate (me : in out; A1 : Ax1; Ang : Real) is static;
301	---C++: inline
302
303	Rotated (me; A1 : Ax1; Ang : Real) returns Dir is static;
304	---C++: inline
305	--- Purpose :
306	-- Rotates a direction. A1 is the axis of the rotation.
307	-- Ang is the angular value of the rotation in radians.
308
309	Transform (me : in out; T : Trsf) is static;
310
311	Transformed (me; T : Trsf) returns Dir is static;
312	--- Purpose :
313	-- Transforms a direction with a "Trsf" from gp.
314	-- Warnings :
315	-- If the scale factor of the "Trsf" T is negative then the
316	-- direction <me> is reversed.
317	---C++: inline
318
319
320	fields
321
322	coord : XYZ;
323
324	end;