src/gp/gp_Trsf.cdl

   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 class Trsf   from gp   inherits Storable
  16
  17         --- Purpose: Defines a non-persistent transformation in 3D space.
  18         --  The following transformations are implemented :
  19         --  . Translation, Rotation, Scale
  20         --  . Symmetry with respect to a point, a line, a plane.
  21         --  Complex transformations can be obtained by combining the
  22         --  previous elementary transformations using the method
  23         --  Multiply.
  24         --  The transformations can be represented as follow :
  25         --
  26         --       V1   V2   V3    T       XYZ        XYZ
  27         --    | a11  a12  a13   a14 |   | x |      | x'|
  28         --    | a21  a22  a23   a24 |   | y |      | y'|
  29         --    | a31  a32  a33   a34 |   | z |   =  | z'|
  30         --    |  0    0    0     1  |   | 1 |      | 1 |
  31         --
  32         --    where {V1, V2, V3} defines the vectorial part of the
  33         --    transformation and T defines the translation part of the
  34         --    transformation.
  35         --  This transformation never change the nature of the objects.
  36
  37
  38 uses Ax1      from gp,
  39      Ax2      from gp,
  40      Ax3      from gp,
  41      Mat      from gp,
  42      Pnt      from gp,
  43      TrsfForm from gp,
  44      Vec      from gp,
  45      XYZ      from gp,
  46      Trsf2d   from gp,
  47      Quaternion from gp
  48
  49 raises ConstructionError from Standard,
  50        OutOfRange        from Standard
  51
  52 is
  53
  54   Create   returns Trsf from gp;
  55         ---C++: inline
  56         --- Purpose : Returns the identity transformation.
  57
  58   Create(T : Trsf2d from gp) returns Trsf from gp;
  59         ---Purpose: Creates  a 3D transformation from the 2D transformation T.
  60         -- The resulting transformation has a homogeneous
  61         -- vectorial part, V3, and a translation part, T3, built from T:
  62         --       a11    a12
  63         -- 0             a13
  64         -- V3 =    a21    a22    0       T3
  65         -- =   a23
  66         --           0    0    1.
  67         -- 0
  68         -- It also has the same scale factor as T. This
  69         -- guarantees (by projection) that the transformation
  70         -- which would be performed by T in a plane (2D space)
  71         -- is performed by the resulting transformation in the xOy
  72         -- plane of the 3D space, (i.e. in the plane defined by the
  73         -- origin (0., 0., 0.) and the vectors DX (1., 0., 0.), and DY
  74         -- (0., 1., 0.)). The scale factor is applied to the entire space.
  75
  76   SetMirror (me : in out; P : Pnt)   is static;
  77         ---C++: inline
  78         --- Purpose :
  79         --  Makes the transformation into a symmetrical transformation.
  80         --  P is the center of the symmetry.
  81
  82
  83   SetMirror (me : in out; A1 : Ax1)   is static;
  84         --- Purpose :
  85         --  Makes the transformation into a symmetrical transformation.
  86         --  A1 is the center of the axial symmetry.
  87
  88
  89   SetMirror (me : in out; A2 : Ax2)   is static;
  90         --- Purpose :
  91         --  Makes the transformation into a symmetrical transformation.
  92         --  A2 is the center of the planar symmetry
  93         --  and defines the plane of symmetry by its origin, "X
  94         --  Direction" and "Y Direction".
  95
  96
  97   SetRotation (me : in out; A1 : Ax1; Ang : Real)    is static;
  98         --- Purpose :
  99         --  Changes the transformation into a rotation.
 100         --  A1 is the rotation axis and Ang is the angular value of the
 101         --  rotation in radians.
 102
 103   SetRotation (me : in out; R : Quaternion) is static;
 104         --- Purpose :
 105         --  Changes the transformation into a rotation defined by quaternion.
 106         --  Note that rotation is performed around origin, i.e.
 107         --  no translation is involved.
 108
 109   SetScale (me : in out; P : Pnt; S : Real)
 110         --- Purpose :
 111         --  Changes the transformation into a scale.
 112         --  P is the center of the scale and S is the scaling value.
 113         --  Raises ConstructionError  If <S> is null.
 114   raises
 115     ConstructionError from Standard
 116   is static;
 117
 118   SetDisplacement (me : in out; FromSystem1, ToSystem2 : Ax3)   is static;
 119         --- Purpose :
 120         --  Modifies this transformation so that it transforms the
 121         --  coordinate system defined by FromSystem1 into the
 122         --  one defined by ToSystem2. After this modification, this
 123         --  transformation transforms:
 124         -- -   the origin of FromSystem1 into the origin of ToSystem2,
 125         -- -   the "X Direction" of FromSystem1 into the "X
 126         --   Direction" of ToSystem2,
 127         -- -   the "Y Direction" of FromSystem1 into the "Y
 128         --   Direction" of ToSystem2, and
 129         -- -   the "main Direction" of FromSystem1 into the "main
 130         --   Direction" of ToSystem2.
 131         -- Warning
 132         -- When you know the coordinates of a point in one
 133         -- coordinate system and you want to express these
 134         -- coordinates in another one, do not use the
 135         -- transformation resulting from this function. Use the
 136         -- transformation that results from SetTransformation instead.
 137         -- SetDisplacement and SetTransformation create
 138         -- related transformations: the vectorial part of one is the
 139         -- inverse of the vectorial part of the other.
 140
 141
 142   SetTransformation (me : in out; FromSystem1, ToSystem2 : Ax3)   is static;
 143         --- Purpose : Modifies this transformation so that it transforms the
 144         -- coordinates of any point, (x, y, z), relative to a source
 145         -- coordinate system into the coordinates (x', y', z') which
 146         -- are relative to a target coordinate system, but which
 147         -- represent the same point
 148         --  The transformation is from the coordinate
 149         --  system "FromSystem1" to the coordinate system "ToSystem2".
 150         -- Example :
 151         --  In a C++ implementation :
 152         --  Real x1, y1, z1;  // are the coordinates of a point in the
 153         --                    // local system FromSystem1
 154         --  Real x2, y2, z2;  // are the coordinates of a point in the
 155         --                    // local system ToSystem2
 156         --  gp_Pnt P1 (x1, y1, z1)
 157         --  Trsf T;
 158         --  T.SetTransformation (FromSystem1, ToSystem2);
 159         --  gp_Pnt P2 = P1.Transformed (T);
 160         --  P2.Coord (x2, y2, z2);
 161
 162
 163   SetTransformation (me : in out; ToSystem : Ax3)    is static;
 164         --- Purpose : Modifies this transformation so that it transforms the
 165         --  coordinates of any point, (x, y, z), relative to a source
 166         --  coordinate system into the coordinates (x', y', z') which
 167         --  are relative to a target coordinate system, but which
 168         --  represent the same point
 169         --  The transformation is from the default coordinate system
 170         --  {P(0.,0.,0.), VX (1.,0.,0.), VY (0.,1.,0.), VZ (0., 0. ,1.) }
 171         --  to the local coordinate system defined with the Ax3 ToSystem.
 172         --  Use in the same way  as the previous method. FromSystem1 is
 173         --  defaulted to the absolute coordinate system.
 174
 175
 176   SetTransformation (me : in out; R : Quaternion; T : Vec) is static;
 177         --- Purpose :
 178         --  Sets transformation by directly specified rotation and translation.
 179
 180   SetTranslation (me : in out; V : Vec)   is static;
 181         ---C++: inline
 182         --- Purpose :
 183         --  Changes the transformation into a translation.
 184         --  V is the vector of the translation.
 185
 186   SetTranslation (me : in out; P1, P2 : Pnt)   is static;
 187         ---C++: inline
 188         --- Purpose :
 189         -- Makes the transformation into a translation where the translation vector
 190         -- is the vector (P1, P2) defined from point P1 to point P2.
 191
 192
 193   SetTranslationPart (me : in out; V : Vec)    is static;
 194         --- Purpose :  Replaces the translation vector with the vector V.
 195
 196
 197   SetScaleFactor (me : in out; S : Real)
 198         --- Purpose :  Modifies the scale factor.
 199         -- Raises ConstructionError  If S is null.
 200   raises
 201     ConstructionError from Standard
 202   is static;
 203
 204   SetValues(me : in out;
 205             a11, a12, a13, a14,
 206             a21, a22, a23, a24,
 207             a31, a32, a33, a34 : Real)
 208
 209         ---Purpose: Sets the coefficients  of the transformation.  The
 210         --          transformation  of the  point  x,y,z is  the point
 211         --          x',y',z' with :
 212         --
 213         --          x' = a11 x + a12 y + a13 z + a14
 214         --          y' = a21 x + a22 y + a23 z + a24
 215         --          z' = a31 x + a32 y + a33 z + a34
 216         --
 217         --          The method Value(i,j) will return aij.
 218         --          Raises ConstructionError if the determinant of  the aij is null.
 219         --          The matrix is orthogonalized before future using.
 220     raises
 221         ConstructionError from Standard
 222
 223     is static;
 224
 225
 226   IsNegative (me)  returns Boolean    is static;
 227         ---C++: inline
 228         --- Purpose : Returns true if the determinant of the vectorial part of
 229         -- this transformation is negative.
 230
 231   Form (me)  returns TrsfForm   is static;
 232         --- Purpose :
 233         --  Returns the nature of the transformation. It can be: an
 234         -- identity transformation, a rotation, a translation, a mirror
 235         -- transformation (relative to a point, an axis or a plane), a
 236         -- scaling transformation, or a compound transformation.
 237         ---C++: inline
 238
 239   ScaleFactor (me)  returns Real   is static;
 240         --- Purpose : Returns the scale factor.
 241         ---C++: inline
 242
 243
 244   TranslationPart (me)   returns XYZ   is static;
 245         --- Purpose :
 246         --  Returns the translation part of the transformation's matrix
 247         ---C++: inline
 248         ---C++: return const&
 249
 250   GetRotation (me; theAxis : out XYZ  from gp;
 251                    theAngle: out Real from Standard)
 252         returns Boolean from Standard is static;
 253         --- Purpose :
 254         --  Returns the boolean True if there is non-zero rotation.
 255         --  In the presence of rotation, the output parameters store the axis
 256         --  and the angle of rotation. The method always returns positive
 257         --  value "theAngle", i.e., 0. < theAngle <= PI.
 258         --  Note that this rotation is defined only by the vectorial part of
 259         --  the transformation; generally you would need to check also the
 260         --  translational part to obtain the axis (gp_Ax1) of rotation.
 261
 262   GetRotation (me) returns Quaternion from gp is static;
 263         --- Purpose :
 264         --  Returns quaternion representing rotational part of the transformation.
 265
 266   VectorialPart (me)   returns Mat   is static;
 267         --- Purpose :
 268         --  Returns the vectorial part of the transformation. It is
 269         --  a 3*3 matrix which includes the scale factor.
 270
 271
 272   HVectorialPart (me)   returns Mat   is static;
 273         --- Purpose :
 274         --  Computes the homogeneous vectorial part of the transformation.
 275         --  It is a 3*3 matrix which doesn't include the scale factor.
 276         --  In other words, the vectorial part of this transformation is equal
 277         --  to its homogeneous vectorial part, multiplied by the scale factor.
 278         --  The coefficients of this matrix must be multiplied by the
 279         --  scale factor to obtain the coefficients of the transformation.
 280         ---C++: inline
 281         ---C++: return const&
 282
 283
 284   Value (me; Row, Col : Integer)   returns Real
 285         ---C++: inline
 286         --- Purpose :
 287         --  Returns the coefficients of the transformation's matrix.
 288         --  It is a 3 rows * 4 columns matrix.
 289         --  This coefficient includes the scale factor.
 290         --  Raises OutOfRanged if Row < 1 or Row > 3 or Col < 1 or Col > 4
 291      raises OutOfRange
 292      is static;
 293
 294
 295
 296
 297
 298   Invert (me : in out)        raises ConstructionError  is static;
 299
 300   Inverted (me) returns Trsf  raises ConstructionError  is static;
 301         --- Purpose :
 302         --  Computes the reverse transformation
 303         --  Raises an exception if the matrix of the transformation
 304         --  is not inversible, it means that the scale factor is lower
 305         --  or equal to Resolution from package gp.
 306         --  Computes the transformation composed with T and  <me>.
 307         --  In a C++ implementation you can also write Tcomposed = <me> * T.
 308         --- Example :
 309         --      Trsf T1, T2, Tcomp; ...............
 310         --        Tcomp = T2.Multiplied(T1);         // or   (Tcomp = T2 * T1)
 311         --        Pnt P1(10.,3.,4.);
 312         --        Pnt P2 = P1.Transformed(Tcomp);    //using Tcomp
 313         --        Pnt P3 = P1.Transformed(T1);       //using T1 then T2
 314         --        P3.Transform(T2);                  // P3 = P2 !!!
 315         ---C++: inline
 316
 317   Multiplied (me; T : Trsf)   returns Trsf  is static;
 318         ---C++: inline
 319         ---C++: alias operator *
 320         --  Computes the transformation composed from T and <me>.
 321         --  In a C++ implementation you can also write Tcomposed = <me> * T.
 322         --  Example :
 323         --      Trsf T1, T2, Tcomp; ...............
 324         --      //composition :
 325         --        Tcomp = T2.Multiplied(T1);         // or   (Tcomp = T2 * T1)
 326         --      // transformation of a point
 327         --        Pnt P1(10.,3.,4.);
 328         --        Pnt P2 = P1.Transformed(Tcomp);    //using Tcomp
 329         --        Pnt P3 = P1.Transformed(T1);       //using T1 then T2
 330         --        P3.Transform(T2);                  // P3 = P2 !!!
 331
 332   Multiply (me : in out; T : Trsf)          is static;
 333         ---C++: alias operator *=
 334         --- Purpose :
 335         --  Computes the transformation composed with <me> and T.
 336         --  <me> = <me> * T
 337
 338   PreMultiply (me : in out; T : Trsf)  is static;
 339         --- Purpose :
 340         --  Computes the transformation composed with <me> and T.
 341         --  <me> = T * <me>
 342
 343
 344   Power (me : in out; N : Integer)   raises ConstructionError   is static;
 345
 346   Powered (me; N : Integer)  returns Trsf
 347         ---C++: inline
 348         --- Purpose :
 349         --  Computes the following composition of transformations
 350         --  <me> * <me> * .......* <me>, N time.
 351         --  if N = 0 <me> = Identity
 352         --  if N < 0 <me> = <me>.Inverse() *...........* <me>.Inverse().
 353         --
 354         --  Raises if N < 0 and if the matrix of the transformation not
 355         --  inversible.
 356      raises ConstructionError
 357      is static;
 358
 359
 360
 361   Transforms (me; X, Y, Z : out Real)   is static;
 362         ---C++: inline
 363
 364   Transforms (me; Coord : out XYZ)      is static;
 365         ---C++: inline
 366         --- Purpose : Transformation of a triplet XYZ with a Trsf
 367
 368   Orthogonalize(me: in out)
 369     is protected;
 370         --- Purpose : Makes orthogonalization of "matrix"
 371
 372 fields
 373
 374   scale  : Real;
 375   shape  : TrsfForm;
 376   matrix : Mat;
 377   loc    : XYZ;
 378
 379
 380 friends
 381
 382   class GTrsf
 383
 384 end;