src/Select3D/Select3D_Projector.cdl

   1 -- Created on: 1992-03-12
   2 -- Created by: Christophe MARION
   3 -- Copyright (c) 1992-1999 Matra Datavision
   4 -- Copyright (c) 1999-2014 OPEN CASCADE SAS
   5 --
   6 -- This file is part of Open CASCADE Technology software library.
   7 --
   8 -- This library is free software; you can redistribute it and/or modify it under
   9 -- the terms of the GNU Lesser General Public License version 2.1 as published
  10 -- by the Free Software Foundation, with special exception defined in the file
  11 -- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
  12 -- distribution for complete text of the license and disclaimer of any warranty.
  13 --
  14 -- Alternatively, this file may be used under the terms of Open CASCADE
  15 -- commercial license or contractual agreement.
  16
  17 --        <cma@sdsun2> copie quasi exacte de HLRAlgo_Projector
  18
  19 class Projector from Select3D inherits Transient from Standard
  20     ---Purpose: A framework to define 3D projectors.
  21     -- Projector provides services for projecting points from
  22     -- world-coordinates to a viewing plane. Projection could be defined by
  23     -- corresponding transformation, or coordinate system. The transformation
  24     -- could be constructed for a view with transposed view transformation
  25     -- matrix ( that represents view-orientation ), including, for perspective
  26     -- view, focal distance ( distance from an eye to the view plane ) and
  27     -- translational part that represents translation of focal point in
  28     -- view-coordinate space. The Select3D_Projector class recognizes the
  29     -- predefined set of popular projections: axonometric, top view, front
  30     -- view and uses more efficient algorithm for projection computations.
  31     -- User-defined transformation could be also defined in constructor.
  32     -- Perspective projection consists of two separate parts, that are
  33     -- composed together during computation: transformation component and
  34     -- focale distance.
  35
  36 uses
  37     Real    from Standard,
  38     Boolean from Standard,
  39     Trsf    from gp,
  40     GTrsf   from gp,
  41     Lin     from gp,
  42     Pnt     from gp,
  43     Vec     from gp,
  44     Ax2     from gp,
  45     Vec2d   from gp,
  46     Pnt2d   from gp,
  47     Box     from Bnd,
  48     View    from V3d
  49
  50 raises
  51     NoSuchObject from Standard
  52
  53 is
  54
  55     Create(aView:View from V3d) returns Projector from Select3D;
  56     --- Purpose: Constructs the 3D projector object defined by the 3D view aView.
  57     Create returns Projector from Select3D;
  58
  59     Create(CS : Ax2 from gp)
  60     ---Purpose: Creates an axonometric projector. <CS> represents viewing coordinate
  61     -- system and could be constructed from x direction, view plane normal direction,
  62     -- and view point location in world-coordinate space.
  63     returns Projector from Select3D;
  64
  65     Create(CS    : Ax2  from gp;
  66            Focus : Real from Standard)
  67     ---Purpose: Creates  a  perspective  projector. <CS> represents viewing
  68     -- coordinate system and could be constructed from x direction,
  69     -- view plane normal direction, and focal point location in world-coordinate
  70     -- space. <Focus> should represent distance of an eye from view plane
  71     -- in world-coordinate space (focal distance).
  72     returns Projector from Select3D;
  73
  74     Create(T         : Trsf    from gp;
  75            Persp     : Boolean from Standard;
  76            Focus     : Real    from Standard)
  77     ---Purpose: build a Projector from the given transformation.
  78     -- In case, when <T> transformation should represent custom view projection,
  79     -- it could be constructed from two separate components: transposed view
  80     -- orientation matrix and translation of focal point in view-coordiante
  81     -- system. <T> could be built up from x direction, up direction,
  82     -- view plane normal direction vectors and translation with SetValues(...)
  83     -- method, where first row arguments (a11, a12, a13, a14)  are x, y, z
  84     -- component of x direction vector, and x value of reversed translation
  85     -- vector. Second row arguments, are x y z for up direction and y value of
  86     -- reversed translation, and the third row defined in the same manner.
  87     -- This also suits for simple perspective view, where <Focus> is the focale
  88     -- distance of an eye from view plane in world-space coordiantes.
  89     -- Note, that in that case amount of perspective distortion (perspective
  90     -- angle) should be defined through focal distance.
  91     returns Projector from Select3D;
  92
  93     Create(GT        : GTrsf   from gp;
  94            Persp     : Boolean from Standard;
  95            Focus     : Real    from Standard)
  96     ---Purpose: build a Projector from the given transformation.
  97     -- In case, when <GT> transformation should represent custom view
  98     -- projection, it could be constructed from two separate components:
  99     -- transposed view orientation matrix and translation of a focal point
 100     -- in view-coordinate system.
 101     -- This also suits for perspective view, with <Focus> that could be
 102     -- equal to distance from an eye to a view plane in
 103     -- world-coordinates (focal distance).
 104     -- The 3x3 transformation matrix is built up from three vectors:
 105     -- x direction, up direction and view plane normal vectors, where each
 106     -- vector is a matrix row. Then <GT> is constructed from matrix and
 107     -- reversed translation with methods SetTranslationPart(..) and
 108     -- SetVectorialPart(..).
 109     -- Note, that in that case amount of perspective distortion (perspective
 110     -- angle) should be defined through focal distance.
 111     returns Projector from Select3D;
 112
 113     Set (me : mutable;
 114          T         : Trsf    from gp;
 115          Persp     : Boolean from Standard;
 116          Focus     : Real    from Standard)
 117     is static;
 118
 119     SetView(me : mutable; V : View from V3d);
 120     ---Purpose: Sets the 3D view V used at the time of construction.
 121
 122     View(me) returns any View from V3d;
 123     ---Purpose: Returns the 3D view used at the time of construction.
 124     ---C++: return const&
 125     ---C++: inline
 126
 127     Scaled(me : mutable; On : Boolean from Standard = Standard_False)
 128     ---Purpose: to compute with the given scale and translation.
 129     is virtual;
 130
 131     Perspective(me) returns Boolean
 132     ---Purpose: Returns True if there is a perspective transformation.
 133     ---C++: inline
 134     is virtual;
 135
 136     Transformation(me) returns GTrsf from gp
 137     ---Purpose: Returns the active transformation.
 138     ---C++: inline
 139     ---C++: return const &
 140     is virtual;
 141
 142     InvertedTransformation(me) returns GTrsf from gp
 143     ---Purpose: Returns the active inverted transformation.
 144     ---C++: inline
 145     ---C++: return const &
 146     is virtual;
 147
 148     FullTransformation(me) returns Trsf from gp
 149     ---Purpose: Returns the original transformation.
 150     ---C++: inline
 151     ---C++: return const &
 152     is virtual;
 153
 154     Focus(me) returns Real from Standard
 155     ---Purpose: Returns the focal length.
 156     ---C++: inline
 157     raises
 158         NoSuchObject from Standard -- if there is no perspective
 159     is virtual;
 160
 161     Transform(me; D : in out Vec from gp)
 162     ---C++: inline
 163     is virtual;
 164
 165     Transform(me; Pnt : in out Pnt from gp)
 166         ---C++: inline
 167     is virtual;
 168
 169     Project(me; P    :     Pnt   from gp;
 170                 Pout : out Pnt2d from gp)
 171     ---Purpose: Transform and apply perspective if needed.
 172     is virtual;
 173
 174     Project(me; P     :     Pnt  from gp;
 175                 X,Y,Z : out Real from Standard)
 176     ---Purpose: Transform and apply perspective if needed.
 177     is static;
 178
 179     Project(me; P     :     Pnt   from gp;
 180                 D1    :     Vec   from gp;
 181                 Pout  : out Pnt2d from gp;
 182         D1out : out Vec2d from gp)
 183     ---Purpose: Transform and apply perspective if needed.
 184     is virtual;
 185
 186     Shoot(me; X , Y : Real from Standard)
 187     returns Lin from gp
 188     ---Purpose: return a line going through the eye towards the
 189     --          2d point <X,Y>.
 190     is virtual;
 191
 192     Transform(me; P : in out Pnt from gp;
 193                   T : GTrsf from gp)
 194     ---C++: inline
 195     is virtual;
 196
 197     Transform(me; D : in out Lin from gp;
 198                   T : GTrsf from gp)
 199     ---C++: inline
 200     is virtual;
 201
 202 fields
 203     myType       : Integer from Standard;
 204
 205     myPersp      : Boolean from Standard is protected;
 206     myFocus      : Real    from Standard is protected;
 207     myScaledTrsf : Trsf    from gp is protected;
 208     myGTrsf      : GTrsf   from gp is protected;
 209     myInvTrsf    : GTrsf   from gp is protected;
 210
 211     myView       : View    from V3d;
 212
 213 end Projector;