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