KernelCAD Documentation

3D Label is a text string displayed in 3D View of KernelCAD components. 3D Labels are part of the model, hence they are stored and loaded from the model files. Similar to objects 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 objects, 3D Labels can belong directly to the model (top-level labels) or be a child of an object. 3D Labels can not have children. For top-level labels the Parent property (IItem.GetParent) is NULL.

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 object or above all object in the model.

To add 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 object" to attach label to the current section 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 object or detached from an object using Action menu of the Model Explorer

Programming Facing Labels

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 object query IItem implemented by the label as described below. IItem controls visibility of the label and its relation to all other items and objects. 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: KernelCAD >GetModel > IModel > IPropertyArray2 > GetProperty("ItemArray") > IArray2 > GetAt > IText

IItem implemented by a 3D Label attached to an object can be obtained via:

Query path: ISection > IPropertyArray2 > GetProperty("ItemArray") > IArray2 > GetAt > IText, where ISection represents the object.

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 object 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 section 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("TextSection_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 objects 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 objects 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 object and ISection queried from the text section (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 section is an empty object 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 object. 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.eObjTypeLabelSection);

where iModel2 is an IModel2 interface or using IDIObjGenerator.Create*(EObjectType.eObjTypeLabelSection) call. The object is a section 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 sections. 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 object 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 object. 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 object 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 object to apply to and select Action>Join in the explorer menu.

See LabelEx Sample