DG Kernel (ActiveX) Documentation


Skip Navigation Links.
Start page
Quick Start
Search Page
Installation
What is new
Upgrading Native Apps
Licensing
Collapse ModelsModels
Expand DG Kernel ControlsDG Kernel Controls
Expand API ReferenceAPI Reference
Expand ViewsViews
Expand Samples and TutorialsSamples and Tutorials
Expand GraphicsGraphics
Expand Math ObjectsMath Objects
Expand DeprecatedDeprecated
Redistribution
Model Viewer
Open Source
Support
Skip Navigation LinksHome Page > Models > Entities > Model Items > 3D Text Go to DGKC docs Search Documentation


3D Text (Labels)

3D Label is a text string displayed in 3D View. 3D Labels are entities with geometry of "Label3D" type. As entties they can be, an normally are, part of a model, hence they can be persisted into model files. 3D Labels also have 3D location (stored in the origin of its entity frame), Visibility, Name and Parent properties. The geometry of 3D Labels have  text string and font (size, face name and color) properties.

Facing Labels

Facing Labels are always oriented in plane parallel to the plane of the screen (to the viewing plane).

As entities, 3D Labels can belong directly to the model (top-level labels) or be a child of an entity.

Labels can be positioned statically at a 3D location or at a fixed screen location. It also can be set to appear always on top of an entity or above all entities in the model. Details.

When location of a label is obscured by an object, the label is not displayed. This Hidden Label Removal functionality is controlled by the EnableHiddenLabelRemoval component context property. It is false by default.

Programming Facing Labels

To create a new 3D facing label use IModel_DG.AddNewEntity1("Label3D") or IEntity_DG.AddNewChild1("Label3D").

To obtain access to a particular label, query ILabel_DG from the relevant IEntity_DG or IGeometry_DG.

IEntity_DG implemented by a top-level 3D Label can be obtained via:

Query path: DG Kernel >GetModel > IModel_DG > GetEntityAt.

IEntity_DG implemented by a 3D Label attached to an entity can be obtained via:

Query path: IEntity_DG > GetChildAt.

Labels aligned to the Eye Frame (i.e. screen, details) can have a rectangle drawn around the text. Use ILabel_DG queried from IEntity_DG  to enable this property.

See Label and LabelEx programming examples.

Smart Labels

Smart Labels are a special (managed) type of facing labels. They are arranged automatically on the screen so they do not overlap and are positioned close to the entity they are associated with. Details.

Sticky Labels

Sticky Labels can be rendered inside a rectangle arbitrary positioned and oriented in 3D or applied (attached/stuck) to a surface of an entity. These two states are called Free and Attached.

Sticky Labels can be created at runtime using call similar to:

IEntity_DG  iEntityLabel = iModel.AddNewEntity1("StickyLabel");

Where iModel is an IModel_DG. The returned entity is in free state and it can be positioned and oriented arbitrary in 3D space using the frame obtained via

IFrame_DG iFrame = iEntityLabel.GetLocation();

Query ILabelGeometry_DG from iEntityLabel to access properties of the label. Use ILabelGeometry_DG > ILabelGeometry_DG.GetLabel() > ILabel_DG to access the displayed string or its font.

Sticky labels are image-based. They are small images displayed on the surface. Quality of the image depends on the optimal zoom they are intended for. This zoom (and size of the image) depends on size of the font set with ILabel_DG.Font, configuration of the view and model size. On the start, without any view manipulation, default size of the text is intended to be close to one normally typed in an edit box on the screen. Text size can be forced to coincide with certain geometric height in vertical direction using ILabelGeometry_DG.SetGeometricHeight(). If ILabelGeometry_DG.SetGeometricHeight() is used, it is recommended to tune in the font size as well for the best quality.

Properties of font and text are not modifiable (unlike the location and position properties described below). New label with the modified properties has to be created instead.

Sticky Labels are created in Free state as a top-level entities. The text will be displayed on a rectangle in x and y palne of its current local frame. To apply the label to a surface:

  • Obtain IFrame_DG from the label using IEntity_DG.GetLocation() and modify location and orientation of the label to make it close to the surface.
  • Obtain IEntity_DG iSectParent interface, implemented by the entity to which the label is to be applied
  • Query IS ISticky_DG  from IEntity_DG of the label and call ISticky_DG.StickTo(iSectParent) to apply the label

As the result of ISticky_DG.StickTo() the label will become a child of the surface entity. Call ISticky_DG.Detach() to return to Free state. An attached label can be detached from its parent using ISticky_DG.Detach() in which case the label will keep the conformed shape, but can be moved independently.

Position and orientation of the label can be also changed at runtime by sliding and rotating it on the surface in attached state. To do that, set the current view mode to Modify with IViewModal.ViewMode and rotate the label with the mouse. Hold shift key to translate. Setting the View mode as auto mode using SetAutoMode can be convenient in this situation.

In detached mode the same action produces normal 3D rotations and translations of the rectangle independently of any surface.

Sticky labels are not persisted (transient) in this version. This means they are supposed to be created at runtime only.

See LabelEx Sample