Overlays
Overlay is a special type of 3D object, which represents a plane in 3D with
editable basic two dimentional geometry on it. Most often overlays are aligned with
the plane of the screen. Overlays are useful for drawing set of lines and curves
on top of visibe 3D scene. So they offfer a "mixed" 3D/2D viewing and editing
mode. If 3D model is empty or all objects are invisible an active overlay acts
as a usual 2D view or editor
Overlay obejcts are entities, so they implement IEntity_DG and ISection interfaces. This means that they
have
visibility, name, local frame, current and other properties of an entity.
Overlays can be created directly by the user at runtime using Advanced > Edit >
"New Overlay" comand in context menu ('o' key is the shortcut). See Programming
Overlays below for a way of creating overlays programmatically.
Overlay represents some 2D geometry. Modifications of an overlay in Direct User
Access mode (by the end user at runtime) are performed by an Overlay Editor. The
"New Overlay" comand creates an overlay editor, an empty overlay and activates
the editor for user input. Overlay Editor displays its own context menu and key
stroke prompt with available commands
In this release overlays are transient, which means that when the editor is
exited the overlay is destroyed and all information is discarded. Contact us to request overlays which can be
saved with the model.
Internal geometry of an overlay is stored as a 2D
Model object, which is a collection of separate 2D items
Direct Access
To create 2D geometry of an overlay at run time, open an Overlay Editor as
described above. Select "New Strip" in context menu (or press 'l' key for line
with the focus at the window). Click several points to create a strip of
segments. Hold Control key to finish the sequence. Hold both Control and Shift
keys to finish the sequence and close the loop at same time.
Select a point or segment and drag it around to modify the strip. Select a
segment and select Break command in context menu ('b' short key) to divide the
segment in the middle with a new point. Select a point and press Delete key or
Delete option in menu to replace adjacent segments with a single shortcut
segment.
Select Exit ('e' short key) to close the editor and to return to the normal 3D
mode. Select exit twice if there was a point or line modification prior to this.
Programming Overlays
To create an overlay obtain IPropertyArray
via query: DGKernel > GetView() >
IPropertyArray.
Call IPropertyArray.GetPropertyEx("OverlayView",
create, activate) and cast the retuned interface to
I2DView_KC. The second and
third parameters have integer type. If the second parameter in the call equals
to 1 an overlay editor is created if it does not exist. If the second parameter
is different from 1 and the editor does not exist the method retuns null object.
If the second parameter in the call equals to 1 the overlay editor is activated
for user input. If the second parameter is different from 1 and the method
returns the interface without attempting to activate the editor.
Normally the application makes the first call to IPropertyArray.GetPropertyEx()
with both parameters set to 1 like IPropertyArray.GetPropertyEx("OverlayView",
1, 1) . Call this method with the first parameter 0 and check the return
for null to verify that the user has not closed the editor via direct access.
Methods of I2DView_KC
allow mapping between screen points (pixels) and geometric 2D coordinates in the
2D plane.
Query I2DView_KC >
I2DEditor_KC to obtain the
Overlay Editor. Call I2DEditor_KC.GetObject()
to obtain ISection of the overlay. Query
IModel_KC from ISection of the overlay to
access its 2D geometry. Use methods of
IModel_KC to modify structure
of the 2D model and parametrs of its items and elements. More details.
See also overlay editor
3D Mapping
Mapping is convertion between the internal 2D coordinates of the overlay
(coordinates retirned by the IElement.GetParam(k)
as described in 2D Scene items) and
coordinates of the same point in the global 3D axes. This conversion
involves orientation and position of the 3D palne of the overlay.
To make the conversion, query IFrame_DG from IEntity_DG or ISection
of the overlay and use IFrame_DG.ToGlobal() or IFrame_DG.ToLocal().
More precisely:
To convert from x and y 2D coordinates to 3D construct a DIPoint object with x,
y, 0 coordinates like (C++):
DIPoint
point(x, y, 0) ;
And call
IFrameEx.ToGlobal(&point);
After the call point will contain global 3D coordinates.
To convert from global coordinates x3D, y3D, x3D to local x and y construct
a DIPoint object with x3D, y3D, x3D coordinates like:
DIPoint
point(x3D, y3D, x3D) ;
And call
IFrameEx.ToLocal(&point);
After that
x = point.x[0]; and y = point.y[1]; will be the 2D
coordinates of projection of point to the plane of the overlay
Advanced:
(a) Using a non-zero number h instead of 0 above will
produce a 3D point at distance h from the plane of overlay on the
side which depends on sign of h.
(b) Above means that plane of the overlay is the palne of x and y axes of the local frame of the overlay
(c) Initial default position and orientation of an overlay consides with this of
the Eye Frame. For example if the view was
manipulated or set programmatically to identity: x to left, y strictly up, the
global coordinates can be obtained by simply taking x and y same as for 2D view
and z=0.
(d) In active state of overlay editor geometry of the overlay is rendered on top
of the scene irrespectively of its actual 3D position
See also: Overlay sample
|