DG Kernel (ActiveX) Documentation


Skip Navigation Links.
Skip Navigation LinksHome Page > Models > Entities > Geometry > Overlays Go to DGKC docs Search Documentation


Overlays

Overlay is a type of geometry, 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 normal 2D view or editor

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 entities

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 IDictionary_DG via query: DGAX> GetView() >IView_DG > GetExtendedProperties() > IDictionary_DG, call IDictionary_DG.GetInterface("OverlayView") and cast the retuned interface to I2DEditor_DG.

Use I2DEditor_DG.EditableObject property to obtain IEntity_DG of the entity, which has the overlay as its geometry. Query IModel2d_DG from the IEntity_DG of the overlay to access its 2D geometry. Use methods of IModel2d_DG 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 Entities) 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 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++):

Point_DG 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:

Point_DG 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