3D Text (Labels)
3D Label is a text string displayed in 3D View. 3D Labels are part of the model, hence they are stored and
loaded from the model files. 3D Labels have 3D location, Visibility, Name and Parent properties. In
addition to that 3D Labels possess modifiable font (size, face name and
color) property.
Facing Labels
Facing Labels are always oriented in plane parallel to the plane of the screen
(to the viewing plane).
Labels are Localized Items. Like entities, 3D Labels can belong directly
to the model (top-level labels) or be a child of an entity.
3D Labels can not have children.
Labels can be positioned statically at a 3D model location or at a fixed
screen location. It also can be set to appear always on top of an entity or
above all entity in the model.
To add a new 3D Label in 3D Debugger select "New
Object" in Model menu. Select Label under Accessories node. Press
Modify button to change text and properties. Turn on "Make child of
current entity" to attach label to the current entity or leave it
unchecked to make it a top-level label.
To modify properties of a label in 3D Debugger open
Model Explorer, select the label in the tree
view and press Edit button on the right hand side.
Labels can be joined to an entity or detached from an entity using Action
menu of the Model Explorer
To create a new 3D facing label query IPropertyArray2
from IModel.
Call IPropertyArray2.GetProperty("Items"). Cast (query) the returned object to IArray2.
Call IArray2.InsertNew( eItemTypeLabel, -1 ) to add
the label.
To obtain access to a particular label query
IItem
implemented by the label as described below.
IItem
controls visibility of the label and its relation to all other items and
entities. All other properties of the label are controlled by ILocation,
ILocationEx,
IText
and IDIFont queried from the
IItem.
IItem
implemented by a top-level 3D Label can be obtained via:
Query path: DG Kernel >GetModel
> IModel > IPropertyArray2
> GetProperty("ItemArray") > IArray2
> GetAt > IText
IItem
implemented by a 3D Label attached to an entity can be obtained via:
Query path: ISection
> IPropertyArray2
> GetProperty("ItemArray") > IArray2
> GetAt > IText, where ISection
represents the entity.
Labels aligned to the Eye Frame (i.e. screen, details)
can have a rectangle drawn around the text. Use
ILabel3D_KC
queried from
IItem or
IText
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 positioned close to the
entity they are associated with. Details.
Geometric Text
Geometric Text is a text string implemented as a geometric shape arbitrary
located and oriented in 3D. It has all usual properties of a 3D entity like
position, orientation, material color, name etc accessible via ISection
and many other interfaces.
The text can be created programmatically or using
LabelEx Sample. Query
IDIObjGenerator from IModel.
Call IDIObjGenerator.Create3("TextEntity_KC"). Cast (query) the returned object
to ITextSection_KC
type. Use
ITextSection_KC.CreateGeometry*() to construct geometry of the text object.
Query I3DObject, IFrame*, ISection,
etc to modify location, color and other properties of the object
In the intial release it is recommended to delete the object and recreate it
again if modifications of the text string, font or other properties defined in
ITextSection_KC.CreateGeometry*() parameters are needed.
Engraving or welding text
As characters of text created with
ITextSection_KC.CreateGeometrySolid are solid entities they can be used for
Boolean Operations so the text can either be engraved (etched) or welded into a
surface. Boolean operations on
groups of entities are useful for that. For example to engrave a string on a
cylinder execute Boolean Subtract using
IBoolSectionEx.Execute3()
with the cylinder as the first entity and ISection queried from the text entity
(from ITextSection_KC)
as the second. The IncludeChildrenOther parameter of the context
should be true. This way all letters will be subtracted in one call despite the
parent entity is an empty entity because it is acting rather as a group.
Make few experiments with very short strings first as the operation can be very
slow. If the operation fails try increasing size of the characters, select
simpler font (Arial), position text so there are no tangetial surfaces and well
defined intersectino line with each letter.
See LabelEx sample for an example
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 Attached state.
Sticky Labels can be created programmaticaly at runtime using call similar to:
IItem iItem =
(IItem)iModel2.AddNewItem(EObjectType.eObjTypeLabelEntity);
where iModel2 is an IModel2 interface or using
IDIObjGenerator.Create*(EObjectType.eObjTypeLabelEntity)
call. The object is a entity so it implements
ISection*, IFrame* and other releated interfaces
and can be positioned and oriented arbitrary in 3D space.
Query ILabelSection_KC from iItem to access properties of the
label. Use
ILabelSection_KC.GetText() and
ILabelSection_KC.GetFont()
to obtain IText and
IDIFont to set or modify 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
IDIFont, configuration of the view and
model size. Before 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
ILabelSection_KC.SetGeometricHeight(). If
ILabelSection_KC.SetGeometricHeight() is used it is recommended to tune in
the font size too for the best quality.
Properties of font and text are not modifiable (unlike the location and position
properties described below). New label with changed 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 ISection interface implemented by the
entity to which the label will be applied
- Query one of IFrame* or I3DObject interfaces from
iItem and modify its lcation and
orientation to make it close to the surface.
- Query
ISticky_KC from iItem and call
ISticky_KC.StickTo()
to apply the label
As the result of
ISticky_KC.StickTo()
the label will become a child of the surface entity. Call
ISticky_KC.Detach()
to return to Free state. An attached label can be detached from its parent using
regular methods like ISection2.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.SetViewMode 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 in 3D Debugger
To create a sticky label in 3D Debugger in the Model > New Object >
Accessoires > Label > Modify select the "Arbitrary Orientable" type on the top.
For labels created this way option to make it a child of the current entity is
disabled in the New Object dialog as the default position is rarely acceptable.
To apply the label to a surface position and orient the label close to the
surface using the Current Objetc page or Modify mode. In Model>Explore dialog
set the label as current. Select the entity to apply to and select Action>Join
in the explorer menu.
See LabelEx Sample
|