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
 359
 360
 361 protected:
 362
 363
 364
 365
 366
 367 private:
 368
 369
 370
 371   gp_XYZ coord;
 372
 373
 374 };
 375
 376
 377 #include <gp_Vec.lxx>
 378
 379
 380
 381
 382
 383 #endif // _gp_Vec_HeaderFile