src/gp/gp_XYZ.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_XYZ_HeaderFile
  16 #define _gp_XYZ_HeaderFile
  17
  18 #include <Standard.hxx>
  19 #include <Standard_DefineAlloc.hxx>
  20 #include <Standard_Handle.hxx>
  21
  22 #include <Standard_Real.hxx>
  23 #include <Standard_Integer.hxx>
  24 #include <Standard_Boolean.hxx>
  25
  26 #include <Standard_OStream.hxx>
  27
  28 class Standard_ConstructionError;
  29 class Standard_OutOfRange;
  30 class gp_Mat;
  31
  32
  33
  34 //! This class describes a cartesian coordinate entity in
  35 //! 3D space {X,Y,Z}. This entity is used for algebraic
  36 //! calculation. This entity can be transformed
  37 //! with a "Trsf" or a  "GTrsf" from package "gp".
  38 //! It is used in vectorial computations or for holding this type
  39 //! of information in data structures.
  40 class gp_XYZ
  41 {
  42 public:
  43
  44   DEFINE_STANDARD_ALLOC
  45
  46
  47   //! Creates an XYZ object with zero co-ordinates (0,0,0)
  48     gp_XYZ();
  49
  50   //! creates an XYZ with given coordinates
  51     gp_XYZ(const Standard_Real X, const Standard_Real Y, const Standard_Real Z);
  52
  53   //! For this XYZ object, assigns
  54   //! the values X, Y and Z to its three coordinates
  55     void SetCoord (const Standard_Real X, const Standard_Real Y, const Standard_Real Z);
  56
  57
  58   //! modifies the coordinate of range Index
  59   //! Index = 1 => X is modified
  60   //! Index = 2 => Y is modified
  61   //! Index = 3 => Z is modified
  62   //! Raises OutOfRange if Index != {1, 2, 3}.
  63     void SetCoord (const Standard_Integer Index, const Standard_Real Xi);
  64
  65   //! Assigns the given value to the X coordinate
  66     void SetX (const Standard_Real X);
  67
  68   //! Assigns the given value to the Y coordinate
  69     void SetY (const Standard_Real Y);
  70
  71   //! Assigns the given value to the Z coordinate
  72     void SetZ (const Standard_Real Z);
  73
  74
  75   //! returns the coordinate of range Index :
  76   //! Index = 1 => X is returned
  77   //! Index = 2 => Y is returned
  78   //! Index = 3 => Z is returned
  79   //!
  80   //! Raises OutOfRange if Index != {1, 2, 3}.
  81     Standard_Real Coord (const Standard_Integer Index) const;
  82
  83     Standard_Real& ChangeCoord (const Standard_Integer theIndex);
  84
  85     void Coord (Standard_Real& X, Standard_Real& Y, Standard_Real& Z) const;
  86
  87     //! Returns a const ptr to coordinates location.
  88     //! Is useful for algorithms, but DOES NOT PERFORM
  89     //! ANY CHECKS!
  90     inline const Standard_Real* GetData() const { return (&x); }
  91
  92     //! Returns a ptr to coordinates location.
  93     //! Is useful for algorithms, but DOES NOT PERFORM
  94     //! ANY CHECKS!
  95     inline Standard_Real* ChangeData() { return (&x); }
  96
  97   //! Returns the X coordinate
  98     Standard_Real X() const;
  99
 100   //! Returns the Y coordinate
 101     Standard_Real Y() const;
 102
 103   //! Returns the Z coordinate
 104     Standard_Real Z() const;
 105
 106   //! computes Sqrt (X*X + Y*Y + Z*Z) where X, Y and Z are the three coordinates of this XYZ object.
 107     Standard_Real Modulus() const;
 108
 109   //! Computes X*X + Y*Y + Z*Z where X, Y and Z are the three coordinates of this XYZ object.
 110     Standard_Real SquareModulus() const;
 111
 112
 113   //! Returns True if he coordinates of this XYZ object are
 114   //! equal to the respective coordinates Other,
 115   //! within the specified tolerance Tolerance. I.e.:
 116   //! abs(<me>.X() - Other.X()) <= Tolerance and
 117   //! abs(<me>.Y() - Other.Y()) <= Tolerance and
 118   //! abs(<me>.Z() - Other.Z()) <= Tolerance.
 119   Standard_EXPORT Standard_Boolean IsEqual (const gp_XYZ& Other, const Standard_Real Tolerance) const;
 120
 121
 122   //! <me>.X() = <me>.X() + Other.X()
 123   //! <me>.Y() = <me>.Y() + Other.Y()
 124   //! <me>.Z() = <me>.Z() + Other.Z()
 125     void Add (const gp_XYZ& Other);
 126   void operator += (const gp_XYZ& Other)
 127 {
 128   Add(Other);
 129 }
 130
 131
 132   //! new.X() = <me>.X() + Other.X()
 133   //! new.Y() = <me>.Y() + Other.Y()
 134   //! new.Z() = <me>.Z() + Other.Z()
 135   Standard_NODISCARD gp_XYZ Added (const gp_XYZ& Other) const;
 136   Standard_NODISCARD gp_XYZ operator + (const gp_XYZ& Other) const
 137 {
 138   return Added(Other);
 139 }
 140
 141
 142   //! <me>.X() = <me>.Y() * Other.Z() - <me>.Z() * Other.Y()
 143   //! <me>.Y() = <me>.Z() * Other.X() - <me>.X() * Other.Z()
 144   //! <me>.Z() = <me>.X() * Other.Y() - <me>.Y() * Other.X()
 145     void Cross (const gp_XYZ& Right);
 146   void operator ^= (const gp_XYZ& Right)
 147 {
 148   Cross(Right);
 149 }
 150
 151
 152   //! new.X() = <me>.Y() * Other.Z() - <me>.Z() * Other.Y()
 153   //! new.Y() = <me>.Z() * Other.X() - <me>.X() * Other.Z()
 154   //! new.Z() = <me>.X() * Other.Y() - <me>.Y() * Other.X()
 155   Standard_NODISCARD gp_XYZ Crossed (const gp_XYZ& Right) const;
 156   Standard_NODISCARD gp_XYZ operator ^ (const gp_XYZ& Right) const
 157 {
 158   return Crossed(Right);
 159 }
 160
 161
 162   //! Computes the magnitude of the cross product between <me> and
 163   //! Right. Returns || <me> ^ Right ||
 164     Standard_Real CrossMagnitude (const gp_XYZ& Right) const;
 165
 166
 167   //! Computes the square magnitude of the cross product between <me> and
 168   //! Right. Returns || <me> ^ Right ||**2
 169     Standard_Real CrossSquareMagnitude (const gp_XYZ& Right) const;
 170
 171   //! Triple vector product
 172   //! Computes <me> = <me>.Cross(Coord1.Cross(Coord2))
 173     void CrossCross (const gp_XYZ& Coord1, const gp_XYZ& Coord2);
 174
 175   //! Triple vector product
 176   //! computes New = <me>.Cross(Coord1.Cross(Coord2))
 177     Standard_NODISCARD gp_XYZ CrossCrossed (const gp_XYZ& Coord1, const gp_XYZ& Coord2) const;
 178
 179   //! divides <me> by a real.
 180     void Divide (const Standard_Real Scalar);
 181   void operator /= (const Standard_Real Scalar)
 182 {
 183   Divide(Scalar);
 184 }
 185
 186   //! divides <me> by a real.
 187   Standard_NODISCARD gp_XYZ Divided (const Standard_Real Scalar) const;
 188   Standard_NODISCARD gp_XYZ operator / (const Standard_Real Scalar) const
 189 {
 190   return Divided(Scalar);
 191 }
 192
 193   //! computes the scalar product between <me> and Other
 194     Standard_Real Dot (const gp_XYZ& Other) const;
 195   Standard_Real operator * (const gp_XYZ& Other) const
 196 {
 197   return Dot(Other);
 198 }
 199
 200   //! computes the triple scalar product
 201     Standard_Real DotCross (const gp_XYZ& Coord1, const gp_XYZ& Coord2) const;
 202
 203
 204   //! <me>.X() = <me>.X() * Scalar;
 205   //! <me>.Y() = <me>.Y() * Scalar;
 206   //! <me>.Z() = <me>.Z() * Scalar;
 207     void Multiply (const Standard_Real Scalar);
 208   void operator *= (const Standard_Real Scalar)
 209 {
 210   Multiply(Scalar);
 211 }
 212
 213
 214   //! <me>.X() = <me>.X() * Other.X();
 215   //! <me>.Y() = <me>.Y() * Other.Y();
 216   //! <me>.Z() = <me>.Z() * Other.Z();
 217     void Multiply (const gp_XYZ& Other);
 218   void operator *= (const gp_XYZ& Other)
 219 {
 220   Multiply(Other);
 221 }
 222
 223   //! <me> = Matrix * <me>
 224     void Multiply (const gp_Mat& Matrix);
 225   void operator *= (const gp_Mat& Matrix)
 226 {
 227   Multiply(Matrix);
 228 }
 229
 230
 231   //! New.X() = <me>.X() * Scalar;
 232   //! New.Y() = <me>.Y() * Scalar;
 233   //! New.Z() = <me>.Z() * Scalar;
 234   Standard_NODISCARD gp_XYZ Multiplied (const Standard_Real Scalar) const;
 235   Standard_NODISCARD gp_XYZ operator * (const Standard_Real Scalar) const
 236 {
 237   return Multiplied(Scalar);
 238 }
 239
 240
 241   //! new.X() = <me>.X() * Other.X();
 242   //! new.Y() = <me>.Y() * Other.Y();
 243   //! new.Z() = <me>.Z() * Other.Z();
 244   Standard_NODISCARD gp_XYZ Multiplied (const gp_XYZ& Other) const;
 245
 246   //! New = Matrix * <me>
 247   Standard_NODISCARD gp_XYZ Multiplied (const gp_Mat& Matrix) const;
 248   Standard_NODISCARD gp_XYZ operator * (const gp_Mat& Matrix) const
 249 {
 250   return Multiplied(Matrix);
 251 }
 252
 253
 254   //! <me>.X() = <me>.X()/ <me>.Modulus()
 255   //! <me>.Y() = <me>.Y()/ <me>.Modulus()
 256   //! <me>.Z() = <me>.Z()/ <me>.Modulus()
 257   //! Raised if <me>.Modulus() <= Resolution from gp
 258     void Normalize();
 259
 260
 261   //! New.X() = <me>.X()/ <me>.Modulus()
 262   //! New.Y() = <me>.Y()/ <me>.Modulus()
 263   //! New.Z() = <me>.Z()/ <me>.Modulus()
 264   //! Raised if <me>.Modulus() <= Resolution from gp
 265     Standard_NODISCARD gp_XYZ Normalized() const;
 266
 267
 268   //! <me>.X() = -<me>.X()
 269   //! <me>.Y() = -<me>.Y()
 270   //! <me>.Z() = -<me>.Z()
 271     void Reverse();
 272
 273
 274   //! New.X() = -<me>.X()
 275   //! New.Y() = -<me>.Y()
 276   //! New.Z() = -<me>.Z()
 277     Standard_NODISCARD gp_XYZ Reversed() const;
 278
 279
 280   //! <me>.X() = <me>.X() - Other.X()
 281   //! <me>.Y() = <me>.Y() - Other.Y()
 282   //! <me>.Z() = <me>.Z() - Other.Z()
 283     void Subtract (const gp_XYZ& Right);
 284   void operator -= (const gp_XYZ& Right)
 285 {
 286   Subtract(Right);
 287 }
 288
 289
 290   //! new.X() = <me>.X() - Other.X()
 291   //! new.Y() = <me>.Y() - Other.Y()
 292   //! new.Z() = <me>.Z() - Other.Z()
 293   Standard_NODISCARD gp_XYZ Subtracted (const gp_XYZ& Right) const;
 294   Standard_NODISCARD gp_XYZ operator - (const gp_XYZ& Right) const
 295 {
 296   return Subtracted(Right);
 297 }
 298
 299
 300   //! <me> is set to the following linear form :
 301   //! A1 * XYZ1 + A2 * XYZ2 + A3 * XYZ3 + XYZ4
 302     void SetLinearForm (const Standard_Real A1, const gp_XYZ& XYZ1, const Standard_Real A2, const gp_XYZ& XYZ2, const Standard_Real A3, const gp_XYZ& XYZ3, const gp_XYZ& XYZ4);
 303
 304
 305   //! <me> is set to the following linear form :
 306   //! A1 * XYZ1 + A2 * XYZ2 + A3 * XYZ3
 307     void SetLinearForm (const Standard_Real A1, const gp_XYZ& XYZ1, const Standard_Real A2, const gp_XYZ& XYZ2, const Standard_Real A3, const gp_XYZ& XYZ3);
 308
 309
 310   //! <me> is set to the following linear form :
 311   //! A1 * XYZ1 + A2 * XYZ2 + XYZ3
 312     void SetLinearForm (const Standard_Real A1, const gp_XYZ& XYZ1, const Standard_Real A2, const gp_XYZ& XYZ2, const gp_XYZ& XYZ3);
 313
 314
 315   //! <me> is set to the following linear form :
 316   //! A1 * XYZ1 + A2 * XYZ2
 317     void SetLinearForm (const Standard_Real A1, const gp_XYZ& XYZ1, const Standard_Real A2, const gp_XYZ& XYZ2);
 318
 319
 320   //! <me> is set to the following linear form :
 321   //! A1 * XYZ1 + XYZ2
 322     void SetLinearForm (const Standard_Real A1, const gp_XYZ& XYZ1, const gp_XYZ& XYZ2);
 323
 324
 325   //! <me> is set to the following linear form :
 326   //! XYZ1 + XYZ2
 327     void SetLinearForm (const gp_XYZ& XYZ1, const gp_XYZ& XYZ2);
 328
 329
 330   //! Dumps the content of me into the stream
 331   Standard_EXPORT void DumpJson (Standard_OStream& theOStream, Standard_Integer theDepth = -1) const;
 332
 333 protected:
 334
 335
 336
 337
 338
 339 private:
 340
 341
 342
 343   Standard_Real x;
 344   Standard_Real y;
 345   Standard_Real z;
 346
 347
 348 };
 349
 350
 351 #include <gp_XYZ.lxx>
 352
 353
 354
 355
 356
 357 #endif // _gp_XYZ_HeaderFile