KernelCAD Documentation

Overlay is a special type of 3D object, which represents a plane in 3D with editable 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 overlayer acts as a usual 2D view or editor

Overlay obejcts are KernelCAD sections, so they implement ISection interface. This mean that they have visibility, name, local frame, current and other properties of a section.

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, and empty overlay and activates the editor for the user input. Overlay Editor displayes new context menu and key stroke prompt with available commands

In this release overlays are transient, which means that when the editor is exited the overlayer 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: kernelCAD > 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 retun for null to verify that the user have 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 IFrameEx from ISection of the overlay and use IFrameEx.ToGlobal() or IFrameEx.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