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             Tolang, TolDist : Real)
 209
 210         ---Purpose: Sets the coefficients  of the transformation.  The
 211         --          transformation  of the  point  x,y,z is  the point
 212         --          x',y',z' with :
 213         --
 214         --          x' = a11 x + a12 y + a13 z + a14
 215         --          y' = a21 x + a22 y + a23 z + a24
 216         --          z' = a31 x + a32 y + a43 z + a34
 217         --
 218         --          Tolang and  TolDist are  used  to  test  for  null
 219         --          angles and null distances to determine the form of
 220         --          the transformation (identity, translation, etc..).
 221         --
 222         --          The method Value(i,j) will return aij.
 223         --          Raises ConstructionError if the determinant of  the aij is null. Or  if
 224         --          the matrix as not a uniform scale.
 225
 226     raises
 227         ConstructionError from Standard
 228
 229     is static;
 230
 231
 232   IsNegative (me)  returns Boolean    is static;
 233         ---C++: inline
 234         --- Purpose : Returns true if the determinant of the vectorial part of
 235         -- this transformation is negative.
 236
 237   Form (me)  returns TrsfForm   is static;
 238         --- Purpose :
 239         --  Returns the nature of the transformation. It can be: an
 240         -- identity transformation, a rotation, a translation, a mirror
 241         -- transformation (relative to a point, an axis or a plane), a
 242         -- scaling transformation, or a compound transformation.
 243         ---C++: inline
 244
 245   ScaleFactor (me)  returns Real   is static;
 246         --- Purpose : Returns the scale factor.
 247         ---C++: inline
 248
 249
 250   TranslationPart (me)   returns XYZ   is static;
 251         --- Purpose :
 252         --  Returns the translation part of the transformation's matrix
 253         ---C++: inline
 254         ---C++: return const&
 255
 256   GetRotation (me; theAxis : out XYZ  from gp;
 257                    theAngle: out Real from Standard)
 258         returns Boolean from Standard is static;
 259         --- Purpose :
 260         --  Returns the boolean True if there is non-zero rotation.
 261         --  In the presence of rotation, the output parameters store the axis
 262         --  and the angle of rotation. The method always returns positive
 263         --  value "theAngle", i.e., 0. < theAngle <= PI.
 264         --  Note that this rotation is defined only by the vectorial part of
 265         --  the transformation; generally you would need to check also the
 266         --  translational part to obtain the axis (gp_Ax1) of rotation.
 267
 268   GetRotation (me) returns Quaternion from gp is static;
 269         --- Purpose :
 270         --  Returns quaternion representing rotational part of the transformation.
 271
 272   VectorialPart (me)   returns Mat   is static;
 273         --- Purpose :
 274         --  Returns the vectorial part of the transformation. It is
 275         --  a 3*3 matrix which includes the scale factor.
 276
 277
 278   HVectorialPart (me)   returns Mat   is static;
 279         --- Purpose :
 280         --  Computes the homogeneous vectorial part of the transformation.
 281         --  It is a 3*3 matrix which doesn't include the scale factor.
 282         --  In other words, the vectorial part of this transformation is equal
 283         --  to its homogeneous vectorial part, multiplied by the scale factor.
 284         --  The coefficients of this matrix must be multiplied by the
 285         --  scale factor to obtain the coefficients of the transformation.
 286         ---C++: inline
 287         ---C++: return const&
 288
 289
 290   Value (me; Row, Col : Integer)   returns Real
 291         ---C++: inline
 292         --- Purpose :
 293         --  Returns the coefficients of the transformation's matrix.
 294         --  It is a 3 rows * 4 columns matrix.
 295         --  This coefficient includes the scale factor.
 296         --  Raises OutOfRanged if Row < 1 or Row > 3 or Col < 1 or Col > 4
 297      raises OutOfRange
 298      is static;
 299
 300
 301
 302
 303
 304   Invert (me : in out)        raises ConstructionError  is static;
 305
 306   Inverted (me) returns Trsf  raises ConstructionError  is static;
 307         --- Purpose :
 308         --  Computes the reverse transformation
 309         --  Raises an exception if the matrix of the transformation
 310         --  is not inversible, it means that the scale factor is lower
 311         --  or equal to Resolution from package gp.
 312         --  Computes the transformation composed with T and  <me>.
 313         --  In a C++ implementation you can also write Tcomposed = <me> * T.
 314         --- Example :
 315         --      Trsf T1, T2, Tcomp; ...............
 316         --        Tcomp = T2.Multiplied(T1);         // or   (Tcomp = T2 * T1)
 317         --        Pnt P1(10.,3.,4.);
 318         --        Pnt P2 = P1.Transformed(Tcomp);    //using Tcomp
 319         --        Pnt P3 = P1.Transformed(T1);       //using T1 then T2
 320         --        P3.Transform(T2);                  // P3 = P2 !!!
 321         ---C++: inline
 322
 323   Multiplied (me; T : Trsf)   returns Trsf  is static;
 324         ---C++: inline
 325         ---C++: alias operator *
 326
 327   Multiply (me : in out; T : Trsf)          is static;
 328         ---C++: alias operator *=
 329         --- Purpose :
 330         --  Computes the transformation composed with T and  <me>.
 331         --  In a C++ implementation you can also write Tcomposed = <me> * T.
 332         --  Example :
 333         --      Trsf T1, T2, Tcomp; ...............
 334         --      //composition :
 335         --        Tcomp = T2.Multiplied(T1);         // or   (Tcomp = T2 * T1)
 336         --      // transformation of a point
 337         --        Pnt P1(10.,3.,4.);
 338         --        Pnt P2 = P1.Transformed(Tcomp);    //using Tcomp
 339         --        Pnt P3 = P1.Transformed(T1);       //using T1 then T2
 340         --        P3.Transform(T2);                  // P3 = P2 !!!
 341         --  Computes the transformation composed with <me> and T.
 342         --  <me> = T * <me>
 343
 344   PreMultiply (me : in out; T : Trsf)  is static;
 345         --- Purpose :
 346         --  Computes the transformation composed with <me> and T.
 347         --  <me> = T * <me>
 348
 349
 350   Power (me : in out; N : Integer)   raises ConstructionError   is static;
 351
 352   Powered (me : in out; N : Integer)  returns Trsf
 353         ---C++: inline
 354         --- Purpose :
 355         --  Computes the following composition of transformations
 356         --  <me> * <me> * .......* <me>, N time.
 357         --  if N = 0 <me> = Identity
 358         --  if N < 0 <me> = <me>.Inverse() *...........* <me>.Inverse().
 359         --
 360         --  Raises if N < 0 and if the matrix of the transformation not
 361         --  inversible.
 362      raises ConstructionError
 363      is static;
 364
 365
 366
 367   Transforms (me; X, Y, Z : out Real)   is static;
 368         ---C++: inline
 369
 370   Transforms (me; Coord : out XYZ)      is static;
 371         ---C++: inline
 372         --- Purpose : Transformation of a triplet XYZ with a Trsf
 373
 374
 375
 376 fields
 377
 378   scale  : Real;
 379   shape  : TrsfForm;
 380   matrix : Mat;
 381   loc    : XYZ;
 382
 383
 384 friends
 385
 386   class GTrsf
 387
 388 end;