src/gp/gp_Vec.cdl

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