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.
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.
See LabelEx Sample
|