src/gp/gp_Ax2.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 Ax2   from gp  inherits Storable
  21
  22         --- Purpose :
  23         --  Describes a right-handed coordinate system in 3D space.
  24         -- A coordinate system is defined by:
  25         -- -   its origin (also referred to as its "Location point"), and
  26         -- -   three orthogonal unit vectors, termed respectively the
  27         -- "X Direction", the "Y Direction" and the "Direction" (also
  28         --   referred to as the "main Direction").
  29         -- The "Direction" of the coordinate system is called its
  30         -- "main Direction" because whenever this unit vector is
  31         -- modified, the "X Direction" and the "Y Direction" are
  32         -- recomputed. However, when we modify either the "X
  33         -- Direction" or the "Y Direction", "Direction" is not modified.
  34         -- The "main Direction" is also the "Z Direction".
  35         -- Since an Ax2 coordinate system is right-handed, its
  36         -- "main Direction" is always equal to the cross product of
  37         -- its "X Direction" and "Y Direction". (To define a
  38         -- left-handed coordinate system, use gp_Ax3.)
  39         -- A coordinate system is used:
  40         -- -   to describe geometric entities, in particular to position
  41         --   them. The local coordinate system of a geometric
  42         --   entity serves the same purpose as the STEP function
  43         --   "axis placement two axes", or
  44         -- -   to define geometric transformations.
  45         -- Note: we refer to the "X Axis", "Y Axis" and "Z Axis",
  46         -- respectively, as to axes having:
  47         -- - the origin of the coordinate system as their origin, and
  48         -- -   the unit vectors "X Direction", "Y Direction" and "main
  49         --   Direction", respectively, as their unit vectors.
  50         -- The "Z Axis" is also the "main Axis".
  51
  52
  53 uses Ax1  from gp,
  54      Dir  from gp,
  55      Pnt  from gp,
  56      Trsf from gp,
  57      Vec  from gp
  58
  59 raises ConstructionError from Standard
  60
  61 is
  62
  63
  64   Create  returns Ax2;
  65         ---C++:inline
  66         --- Purpose : Creates an object corresponding to the reference
  67         --            coordinate system (OXYZ).
  68
  69
  70   Create (P : Pnt; N, Vx : Dir)   returns Ax2
  71         ---C++:inline
  72         --- Purpose :
  73         --  Creates an axis placement with an origin P such that:
  74         --   -   N is the Direction, and
  75         --   -   the "X Direction" is normal to N, in the plane
  76         --    defined by the vectors (N, Vx): "X
  77         --    Direction" = (N ^ Vx) ^ N,
  78        --  Exception: raises ConstructionError if N and Vx are parallel (same or opposite orientation).
  79      raises ConstructionError;
  80
  81
  82   Create (P : Pnt; V : Dir)  returns Ax2;
  83         --- Purpose :
  84         --  Creates -   a coordinate system with an origin P, where V
  85         -- gives the "main Direction" (here, "X Direction" and "Y
  86         --  Direction" are defined automatically).
  87
  88   SetAxis (me : in out; A1 : Ax1)
  89         --- Purpose : Assigns the origin and "main Direction" of the axis A1 to
  90         -- this coordinate system, then recomputes its "X Direction" and "Y Direction".
  91         -- Note: The new "X Direction" is computed as follows:
  92         -- new "X Direction" = V1 ^(previous "X Direction" ^ V)
  93         -- where V is the "Direction" of A1.
  94         -- Exceptions
  95         -- Standard_ConstructionError if A1 is parallel to the "X
  96         -- Direction" of this coordinate system.
  97         raises ConstructionError
  98
  99      is static;
 100
 101
 102   SetDirection (me : in out; V : Dir)
 103         --- Purpose :
 104         --  Changes the "main Direction" of this coordinate system,
 105         -- then recomputes its "X Direction" and "Y Direction".
 106         -- Note: the new "X Direction" is computed as follows:
 107         -- new "X Direction" = V ^ (previous "X Direction" ^ V)
 108         --   Exceptions
 109         -- Standard_ConstructionError if V is parallel to the "X
 110         -- Direction" of this coordinate system.
 111      raises ConstructionError
 112
 113      is static;
 114
 115   SetLocation (me : in out; P : Pnt)   is static;
 116         --- Purpose :
 117         --  Changes the "Location" point (origin) of <me>.
 118
 119
 120   SetXDirection (me : in out; Vx : Dir)
 121         --- Purpose :
 122         --  Changes the "Xdirection" of <me>. The main direction
 123         --  "Direction" is not modified, the "Ydirection" is modified.
 124         --  If <Vx> is not normal to the main direction then <XDirection>
 125         --  is computed as follows XDirection = Direction ^ (Vx ^ Direction).
 126         -- Exceptions
 127         -- Standard_ConstructionError if Vx or Vy is parallel to
 128         -- the "main Direction" of this coordinate system.
 129     raises ConstructionError
 130
 131      is static;
 132
 133   SetYDirection(me : in out; Vy : Dir)
 134         --- Purpose :
 135         --  Changes the "Ydirection" of <me>. The main direction is not
 136         --  modified but the "Xdirection" is changed.
 137         --  If <Vy> is not normal to the main direction then "YDirection"
 138         --  is computed as  follows
 139         --  YDirection = Direction ^ (<Vy> ^ Direction).
 140         -- Exceptions
 141         -- Standard_ConstructionError if Vx or Vy is parallel to
 142         -- the "main Direction" of this coordinate system.
 143     raises ConstructionError
 144
 145     is static;
 146
 147   Angle (me; Other : Ax2)  returns Real    is static;
 148         --- Purpose :
 149         --  Computes the angular value, in radians, between the main direction of
 150         --  <me> and the main direction of <Other>. Returns the angle
 151         --  between 0 and PI in radians.
 152
 153
 154   Axis (me)  returns Ax1         is static;
 155         ---C++:inline
 156         --- Purpose :
 157         --  Returns the main axis of <me>. It is the "Location" point
 158         --  and the main "Direction".
 159         ---C++: return const&
 160
 161
 162   Direction (me)  returns Dir    is static;
 163         ---C++:inline
 164         --- Purpose :
 165         --  Returns the main direction of <me>.
 166         ---C++: return const&
 167
 168
 169   Location (me)  returns Pnt     is static;
 170         ---C++:inline
 171         --- Purpose :
 172         --  Returns the "Location" point (origin) of <me>.
 173         ---C++: return const&
 174
 175
 176   XDirection (me)  returns Dir   is static;
 177         ---C++:inline
 178         --- Purpose :
 179         --  Returns the "XDirection" of <me>.
 180         ---C++: return const&
 181
 182
 183   YDirection(me)  returns Dir    is static;
 184         ---C++:inline
 185         --- Purpose :
 186         --  Returns the "YDirection" of <me>.
 187         ---C++: return const&
 188
 189
 190   IsCoplanar (me; Other : Ax2; LinearTolerance, AngularTolerance : Real)
 191      returns Boolean
 192      is static;
 193         --  Returns True if
 194         --  -   the "main Direction" of this coordinate system is   parallel to:
 195         -- -   the "main Direction" of the coordinate system Other, or
 196         --   -   the Direction of axis A1, and
 197         --
 198         -- Note: the tolerance criterion for angular equality is given by AngularTolerance.
 199
 200
 201   IsCoplanar (me; A1 : Ax1; LinearTolerance, AngularTolerance : Real)
 202      returns Boolean
 203      is static;
 204         ---C++:inline
 205         --- Purpose :
 206         --  Returns True if
 207         --  . the distance between <me> and the "Location" point of A1
 208         --    is lower of equal to LinearTolerance and
 209         --  . the main direction of <me> and the direction of A1 are normal.
 210         -- Note: the tolerance criterion for angular equality is given by AngularTolerance.
 211
 212   Mirror (me : in out; P : Pnt)          is static;
 213
 214        ---Purpose:
 215        -- Performs a symmetrical transformation of this coordinate
 216        -- system with respect to:
 217        -- -   the point P, and assigns the result to this coordinate system.
 218        -- Warning
 219        -- This transformation is always performed on the origin.
 220        -- In case of a reflection with respect to a point:
 221        -- - the main direction of the coordinate system is not changed, and
 222        -- - the "X Direction" and the "Y Direction" are simply reversed
 223        -- In case of a reflection with respect to an axis or a plane:
 224        --   -   the transformation is applied to the "X Direction"
 225        --    and the "Y Direction", then
 226        --   -   the "main Direction" is recomputed as the cross
 227        --    product "X Direction" ^ "Y   Direction".
 228        --  This maintains the right-handed property of the
 229        -- coordinate system.
 230
 231   Mirrored (me; P : Pnt)  returns Ax2    is static;
 232        ---Purpose:
 233        -- Performs a symmetrical transformation of this coordinate
 234        -- system with respect to:
 235        -- -   the point P, and creates a new one.
 236        -- Warning
 237        -- This transformation is always performed on the origin.
 238        -- In case of a reflection with respect to a point:
 239        -- - the main direction of the coordinate system is not changed, and
 240        -- - the "X Direction" and the "Y Direction" are simply reversed
 241        -- In case of a reflection with respect to an axis or a plane:
 242        --   -   the transformation is applied to the "X Direction"
 243        --    and the "Y Direction", then
 244        --   -   the "main Direction" is recomputed as the cross
 245        --    product "X Direction" ^ "Y   Direction".
 246        --  This maintains the right-handed property of the
 247        -- coordinate system.
 248
 249
 250
 251   Mirror (me : in out; A1 : Ax1)         is static;
 252        ---Purpose:
 253        -- Performs a symmetrical transformation of this coordinate
 254        -- system with respect to:
 255        -- -   the axis A1, and assigns the result to this coordinate systeme.
 256        -- Warning
 257        -- This transformation is always performed on the origin.
 258        -- In case of a reflection with respect to a point:
 259        -- - the main direction of the coordinate system is not changed, and
 260        -- - the "X Direction" and the "Y Direction" are simply reversed
 261        -- In case of a reflection with respect to an axis or a plane:
 262        --   -   the transformation is applied to the "X Direction"
 263        --    and the "Y Direction", then
 264        --   -   the "main Direction" is recomputed as the cross
 265        --    product "X Direction" ^ "Y   Direction".
 266        --  This maintains the right-handed property of the
 267        -- coordinate system.
 268
 269   Mirrored (me; A1 : Ax1)  returns Ax2   is static;
 270
 271        ---Purpose:
 272        -- Performs a symmetrical transformation of this coordinate
 273        -- system with respect to:
 274        -- -   the axis A1, and  creates a new one.
 275        -- Warning
 276        -- This transformation is always performed on the origin.
 277        -- In case of a reflection with respect to a point:
 278        -- - the main direction of the coordinate system is not changed, and
 279        -- - the "X Direction" and the "Y Direction" are simply reversed
 280        -- In case of a reflection with respect to an axis or a plane:
 281        --   -   the transformation is applied to the "X Direction"
 282        --    and the "Y Direction", then
 283        --   -   the "main Direction" is recomputed as the cross
 284        --    product "X Direction" ^ "Y   Direction".
 285        --  This maintains the right-handed property of the
 286        -- coordinate system.
 287
 288
 289
 290   Mirror (me : in out; A2 : Ax2)         is static;
 291        ---Purpose:
 292        -- Performs a symmetrical transformation of this coordinate
 293        -- system with respect to:
 294        -- -   the plane defined by the origin, "X Direction" and "Y
 295        --   Direction" of coordinate system A2 and  assigns the result to this coordinate systeme.
 296        -- Warning
 297        -- This transformation is always performed on the origin.
 298        -- In case of a reflection with respect to a point:
 299        -- - the main direction of the coordinate system is not changed, and
 300        -- - the "X Direction" and the "Y Direction" are simply reversed
 301        -- In case of a reflection with respect to an axis or a plane:
 302        --   -   the transformation is applied to the "X Direction"
 303        --    and the "Y Direction", then
 304        --   -   the "main Direction" is recomputed as the cross
 305        --    product "X Direction" ^ "Y   Direction".
 306        --  This maintains the right-handed property of the
 307        -- coordinate system.
 308
 309   Mirrored (me; A2 : Ax2)  returns Ax2   is static;
 310        ---Purpose:
 311        -- Performs a symmetrical transformation of this coordinate
 312        -- system with respect to:
 313        -- -   the plane defined by the origin, "X Direction" and "Y
 314        --   Direction" of coordinate system A2 and creates a new one.
 315        -- Warning
 316        -- This transformation is always performed on the origin.
 317        -- In case of a reflection with respect to a point:
 318        -- - the main direction of the coordinate system is not changed, and
 319        -- - the "X Direction" and the "Y Direction" are simply reversed
 320        -- In case of a reflection with respect to an axis or a plane:
 321        --   -   the transformation is applied to the "X Direction"
 322        --    and the "Y Direction", then
 323        --   -   the "main Direction" is recomputed as the cross
 324        --    product "X Direction" ^ "Y   Direction".
 325        --  This maintains the right-handed property of the
 326        -- coordinate system.
 327
 328
 329
 330
 331   Rotate (me : in out; A1 : Ax1; Ang : Real)         is static;
 332       ---C++:inline
 333
 334   Rotated (me; A1 : Ax1; Ang : Real)  returns Ax2    is static;
 335       ---C++:inline
 336
 337         --- Purpose :
 338         --  Rotates an axis placement. <A1> is the axis of the
 339         --  rotation . Ang is the angular value of the rotation
 340         --  in radians.
 341
 342
 343   Scale (me : in out; P : Pnt; S : Real)             is static;
 344       ---C++:inline
 345   Scaled (me; P : Pnt; S : Real)  returns Ax2        is static;
 346       ---C++:inline
 347        --- Purpose :
 348         --  Applies a scaling transformation on the axis placement.
 349         --  The "Location" point of the axisplacement is modified.
 350         --- Warnings :
 351         --  If the scale <S> is negative :
 352         --   . the main direction of the axis placement is not changed.
 353         --   . The "XDirection" and the "YDirection" are reversed.
 354         --  So the axis placement stay right handed.
 355
 356
 357   Transform (me : in out; T : Trsf)                  is static;
 358       ---C++:inline
 359   Transformed (me; T : Trsf)   returns Ax2           is static;
 360       ---C++:inline
 361         --- Purpose :
 362         --  Transforms an axis placement with a Trsf.
 363         --  The "Location" point, the "XDirection" and the
 364         --  "YDirection" are transformed with T.  The resulting
 365         --  main "Direction" of <me> is the cross product between
 366         --  the "XDirection" and the "YDirection" after transformation.
 367
 368
 369   Translate (me : in out; V : Vec)
 370       ---C++:inline
 371       is static;
 372
 373   Translated (me; V : Vec)  returns Ax2              is static;
 374        ---C++:inline
 375        --- Purpose :
 376         --  Translates an axis plaxement in the direction of the vector
 377         --  <V>. The magnitude of the translation is the vector's magnitude.
 378
 379
 380   Translate (me : in out; P1, P2 : Pnt)
 381       ---C++:inline
 382      is static;
 383
 384   Translated (me; P1, P2 : Pnt)   returns Ax2        is static;
 385       ---C++:inline
 386         --- Purpose :
 387         --  Translates an axis placement from the point <P1> to the
 388         --  point <P2>.
 389
 390
 391
 392
 393 fields
 394
 395    axis  : Ax1;
 396    vydir : Dir;
 397    vxdir : Dir;
 398
 399 end;