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     Mat4    from Graphic3d,
  50     Mat4d   from Graphic3d
  51
  52 raises
  53     NoSuchObject from Standard
  54
  55 is
  56
  57     Create (theView : View from V3d) returns Projector from Select3D;
  58     --- Purpose: Constructs the 3D projector object from the passed view.
  59     -- The projector captures current model-view and projection transformation
  60     -- of the passed view.
  61
  62     Create returns Projector from Select3D;
  63     --- Purpose: Constructs identity projector.
  64
  65     Create (theCS : Ax2 from gp)
  66     ---Purpose: Builds the Projector from the model-view transformation specified
  67     -- by the passed viewing coordinate system <theCS>. The Projector has
  68     -- identity projection transformation, is orthogonal.
  69     -- The viewing coordinate system could be constructed from x direction,
  70     -- view plane normal direction, and view point location in
  71     -- world-coordinate space.
  72     returns Projector from Select3D;
  73
  74     Create (theCS    : Ax2  from gp;
  75             theFocus : Real from Standard)
  76     ---Purpose: Builds the Projector from the model-view transformation specified
  77     -- by the passed view coordinate system <theCS> and simplified perspective
  78     -- projection transformation defined by <theFocus> parameter.
  79     -- The viewing coordinate system could be constructed from x direction,
  80     -- view plane normal direction, and focal point location in world-coordinate
  81     -- space. <theFocus> should represent distance of an eye from view plane
  82     -- in world-coordinate space (focal distance).
  83     returns Projector from Select3D;
  84
  85     Create (theViewTrsf : Trsf    from gp;
  86             theIsPersp  : Boolean from Standard;
  87             theFocus    : Real    from Standard)
  88     ---Purpose: Build the Projector from the model-view transformation passed
  89     -- as <theViewTrsf> and simplified perspective projection transformation
  90     -- parameters passed as <theIsPersp> and <theFocus>.
  91     -- In case, when <theViewTrsf> transformation should represent custom view
  92     -- projection, it could be constructed from two separate components:
  93     -- transposed view orientation matrix and translation of focal point
  94     -- in view-coordinate system.
  95     -- <theViewTrsf> could be built up from x direction, up direction,
  96     -- view plane normal direction vectors and translation with SetValues(...)
  97     -- method, where first row arguments (a11, a12, a13, a14)  are x, y, z
  98     -- component of x direction vector, and x value of reversed translation
  99     -- vector. Second row arguments, are x y z for up direction and y value of
 100     -- reversed translation, and the third row defined in the same manner.
 101     -- This also suits for simple perspective view, where <theFocus> is the focale
 102     -- distance of an eye from view plane in world-space coordinates.
 103     -- Note, that in that case amount of perspective distortion (perspective
 104     -- angle) should be defined through focal distance.
 105     returns Projector from Select3D;
 106
 107     Create (theViewTrsf : GTrsf   from gp;
 108             theIsPersp  : Boolean from Standard;
 109             theFocus    : Real    from Standard)
 110     ---Purpose: Builds the Projector from the model-view transformation passed
 111     -- as <theViewTrsf> and projection transformation for <theIsPersp> and
 112     -- <theFocus> parameters.
 113     -- In case, when <theViewTrsf> transformation should represent custom view
 114     -- projection, it could be constructed from two separate components:
 115     -- transposed view orientation matrix and translation of a focal point
 116     -- in view-coordinate system.
 117     -- This also suits for perspective view, with <theFocus> that could be
 118     -- equal to distance from an eye to a view plane in
 119     -- world-coordinates (focal distance).
 120     -- The 3x3 transformation matrix is built up from three vectors:
 121     -- x direction, up direction and view plane normal vectors, where each
 122     -- vector is a matrix row. Then <theViewTrsf> is constructed from matrix and
 123     -- reversed translation with methods SetTranslationPart(..) and
 124     -- SetVectorialPart(..).
 125     -- Note, that in that case amount of perspective distortion (perspective
 126     -- angle) should be defined through focal distance.
 127     returns Projector from Select3D;
 128
 129     Create (theViewTrsf : Mat4d from Graphic3d;
 130             theProjTrsf : Mat4d from Graphic3d)
 131     ---Purpose: Builds the Projector from the passed model-view <theViewTrsf>
 132     -- and projection <theProjTrsf> transformation matrices.
 133     returns Projector from Select3D;
 134
 135     Set (me : mutable;
 136          theViewTrsf : Trsf    from gp;
 137          theIsPersp  : Boolean from Standard;
 138          theFocus    : Real    from Standard);
 139     ---Purpose: Sets new parameters for the Projector.
 140
 141     Set (me : mutable;
 142          theViewTrsf : Mat4d from Graphic3d;
 143          theProjTrsf : Mat4d from Graphic3d);
 144     ---Purpose: Sets new parameters for the Projector.
 145
 146     SetView (me : mutable;
 147              theView : View from V3d);
 148     ---Purpose: Sets new parameters for the Projector
 149     -- captured from the passed view.
 150
 151     Scaled (me : mutable; theToCheckOptimized : Boolean from Standard = Standard_False)
 152     ---Purpose: Pre-compute inverse transformation and ensure whether it is possible
 153     -- to use optimized transformation for the common view-orientation type or not
 154     -- if <theToCheckOptimized> is TRUE.
 155     is virtual;
 156
 157     Perspective (me) returns Boolean
 158     ---Purpose: Returns True if there is simplified perspective
 159     -- projection approach is used. Distortion defined by Focus.
 160     ---C++: inline
 161     is virtual;
 162
 163     Focus (me) returns Real from Standard
 164     ---Purpose: Returns the focal length of simplified perspective
 165     -- projection approach. Raises program error exception if the
 166     -- the projection transformation is not specified as simplified
 167     -- Perspective (for example, custom projection transformation is defined
 168     -- or the orthogonal Projector is defined).
 169     ---C++: inline
 170     is virtual;
 171
 172     Projection (me) returns Mat4d from Graphic3d;
 173     ---Purpose: Returns projection transformation. Please note that for
 174     -- simplified perspective projection approach, defined by Focus, the
 175     -- returned transformation is identity.
 176     ---C++: inline
 177     ---C++: return const &
 178
 179     Transformation (me) returns GTrsf from gp
 180     ---Purpose: Returns the view transformation.
 181     ---C++: inline
 182     ---C++: return const &
 183     is virtual;
 184
 185     InvertedTransformation (me) returns GTrsf from gp
 186     ---Purpose: Returns the inverted view transformation.
 187     ---C++: inline
 188     ---C++: return const &
 189     is virtual;
 190
 191     FullTransformation (me) returns Trsf from gp
 192     ---Purpose: Returns the uniform-scaled view transformation.
 193     ---C++: inline
 194     ---C++: return const &
 195     is virtual;
 196
 197     Transform (me; theD : in out Vec from gp)
 198     ---Purpose: Transforms the vector into view-coordinate space.
 199     ---C++: inline
 200     is virtual;
 201
 202     Transform (me; thePnt : in out Pnt from gp)
 203     ---Purpose: Transforms the point into view-coordinate space.
 204     ---C++: inline
 205     is virtual;
 206
 207     Project (me; theP : Pnt from gp; thePout : out Pnt2d from gp)
 208     ---Purpose: Transforms the point into view-coordinate space
 209     -- and applies projection transformation.
 210     is virtual;
 211
 212     Project (me; theP : Pnt  from gp; theX, theY, theZ : out Real from Standard)
 213     ---Purpose: Transforms the point into view-coordinate space
 214     -- and applies projection transformation.
 215     is static;
 216
 217     Project (me; theP     : Pnt   from gp;
 218                  theD1    : Vec from gp;
 219                  thePout  : out Pnt2d from gp;
 220                  theD1out : out Vec2d from gp)
 221     ---Purpose: Transforms the point and vector passed from its location
 222     -- into view-coordinate space and applies projection transformation.
 223     is virtual;
 224
 225     Shoot (me; theX, theY : Real from Standard) returns Lin from gp
 226     ---Purpose: Return projection line going through the 2d point <theX, theY>
 227     is virtual;
 228
 229     Transform(me; thePnt  : in out Pnt from gp;
 230                   theTrsf : GTrsf from gp)
 231     ---C++: inline
 232     is virtual;
 233
 234     Transform(me; theLin : in out Lin from gp;
 235                   theTrsf : GTrsf from gp)
 236     ---C++: inline
 237     is virtual;
 238
 239 fields
 240
 241     myType       : Integer from Standard;
 242     myPersp      : Boolean from Standard is protected;
 243     myFocus      : Real    from Standard is protected;
 244     myGTrsf      : GTrsf   from gp is protected;
 245     myInvTrsf    : GTrsf   from gp is protected;
 246     myScaledTrsf : Trsf    from gp is protected;
 247     myProjTrsf   : Mat4d   from Graphic3d is protected;
 248
 249 end Projector;