3D Labels

Created:6/28/2001
Description:

This tool contains a toolbar providing functionality to create text labels in the 3D environment of ArcScene. The text and location of the labels of the toolbar can be originated from features in a layer, as well as by user defined positions via mouse clicks. Dialogs are provided to allow the modification of the rotation, offset, and orientation of the labels. The labels can also be saved and opened into ArcScene documents via the toolbar.

The 3D label toolbar utilizes a library created from another Developer Sample project which contains the core functionality of the 3D labeling. That code highlights the procedures for using the OpenGL type library to create 3D text using fonts on the system. The Label3DEngine project should be reviewed to gain a more specfic understanding of the OpenGL methods used.





How to use:

    Steps for adding a command/tool from a DLL:

  1. Register the DLL: Label3DToolbar.dll and the DLL: DDDAnalystTextSample.dll. You can register a DLL on Windows by typing in the Start Menu\Run dialog box 'regsvr32 ' and the path to the dll file.
  2. In the Customize dialog, click on 'Add from file', and browse to select 'Label3DToobar.dll'.
  3. Under the Toolbars tab, check the '3D Labels' toolbar. Dismiss the Customize dialog.

    Using the Tool:

  1. Start ArcScene and load a feature layer containing an attribute in which to base the label on. The data folder distrubuted with these sample contains the \site1\bldgs3d shapefile which can be used to demostrate use of the toolbar.
  2. In the dropdown 'Layer' listbox on the 3DLabels toolbar, select "bldgs3D" and select "owner" from the dropdown 'Field' listbox.
  3. Place a check in the 'On' checkbox of the toolbar to make the labels visible. Zoom into the dataset to view the labels more closely.
  4. From the 3D Labels dropdown menu, select 'Font' to change the property of the fonts for all the labels; selecting 'Rotation' and 'Offset' will also modify these properties for all the labels in the select layer. Turn the labels of by unchecking the 'On' checkbox.
  5. Select the first layer in the layer dropdown list, 'graphics layer', turn the labels for the layer on, and select the 'Add a label' tool. Click on any geography in the scene, such as a building, and enter the text for the label you have just added.
  6. Choose the 'Select a label' tool and select an existing label by clicking on it. A dialog will open allowing you to change any available properties for the individual label.
  7. Checking 'Billboarding' from the '3D Labels' dropdown menu will result in the labels for the selected layer always rotating to face the observer
  8. Save all the visible labels in the scene to a text file, or open a text file in the appropriate format through the 'Label File' item on the dropdown menu.

    To recompile or to view the complete source code for this project:

  1. The shared code modules should be downloaded and in the correct relative path to this project. (See link below to download the '3D Analyst Developer Sample utilties').

  2. The proper location for the source code is:

    <ArcGISInstallPath>\ArcObjects Developer Kit\Samples\3D Analyst\3D Visualization\3D Text\Label3DToolbar\*.*


This custom label engine can also be controlled programmatically in ArcScene VBA. Here's an example:

Public Sub ToolbarLabelEngineTester()

  ' query the toolbar for the underlying label engine:
  Dim pEnv As ILabel3DToolbarEnv
  Dim pToolbar As DDDLabelToolbar
  Set pToolbar = New DDDLabelToolbar
  Set pEnv = pToolbar
  
  ' as an example, toggle the visiblity of the first layer labels:
  If pEnv.LabelEngine.LabelGroups.Count >  1 Then
    pEnv.LabelEngine.LabelGroup(1).Visible = Not pEnv.LabelEngine.LabelGroup(1).Visible
  End If
  
  ' add a label directly to the default 'imagined as the basic graphics layer' label group:
  Dim pWhere As IPoint
  Dim pScene As IScene
  Dim pDoc As ISxDocument
  Set pDoc = ThisDocument: Set pScene = pDoc.Scene
  Set pWhere = New Point
  With pWhere
    .X = (pScene.Extent.xmax + pScene.Extent.xmin) / 2
    .Y = (pScene.Extent.ymax + pScene.Extent.ymin) / 2
    .Z = (pScene.Extent.zmax)
  End With
  pEnv.LabelEngine.AddLabelDirect pWhere, "Added Directly", , , 100
  pEnv.LabelEngine.LabelGroup(0).Visible = True

  ' add a label to a custom group and add the group to the engine and the toolbar:
  Dim pNewGroup As LabelGroup
  Set pNewGroup = New LabelGroup
  pNewGroup.Name = "<Custom Label Group>"
  pNewGroup.FontSize = 100
  
  pWhere.X = pScene.Extent.xmin
  pWhere.Y = pScene.Extent.ymin
  pWhere.Z = 0
  
  Dim pColor As IColor
  Set pColor = New RgbColor
  pColor.RGB = vbBlue
  
  pNewGroup.Visible = True
  pNewGroup.LabelItem = " <default>"
  pEnv.LabelEngine.LabelGroups.Add pNewGroup
  
  ' update the scaling for the group using the label engine function:
  pEnv.LabelEngine.UpdateExtentScale pNewGroup, pScene.Extent.xmax - pScene.Extent.xmin, pScene.Extent.ymax - pScene.Extent.ymin, pScene.Extent.zmax - pScene.Extent.zmin, True
  
  ' add the label to the designated group:
  pEnv.LabelEngine.AddLabelDirect pWhere, "Added To Custom Group", pNewGroup.Name, , 200, pColor
  
  ' update the toolbar:
  pEnv.RefreshToolbar
    
End Sub

  
Application: ArcScene

Requires: An ArcScene session with data loaded, and the OpenGL Visual Basic type libary.

Difficulty: Beginner


Visual Basic
File Description
cls3DLabelDemo.cls The IToolbarDef class module for the tool.
clsAddLabel.cls ITool implementation to add a label.
clsChkBillboard.cls ICommand implementation to turn on the billboarding for labels.
clsLabel3DMNU.cls ICommand implementation for the main toolbar dropdown menu.
clsLabelEngine.cls The main class module containing the 3D Label Engine used by the toolbar.
clsLabelProps.cls ICommand implementation to open the property dialog for labels.
clsLayerBox.cls ICommand implementation for a listbox contain the layers availabke for labeling.
clsLayerLabels.cls A class containing all labels in a layer.
clsMNUGetDefaults.cls ICommand implementation to reset the labels to default properties.
clsMNULayerBB.cls ICommand implementation for the menu item which turns on the billboarding for labels.
clsMNULayerFont.cls ICommand implementation for the menu item to change the font of labels.
clsMNULayerName.cls ICommand implementation used for the listing of a layer to be labeled.
clsMNULayerOffset.cls ICommand implementation for the menu item to change the offset of labels.
clsMNULayerRotation.cls ICommand implementation for the menu item to change the rotation of labels.
clsMNUOpenLabels.cls ICommand implementation for the menu to open labels from a text file.
clsMNUPersist.cls ICommand implementation for the root level menu to open and save labels.
clsMNUSaveLabels.cls ICommand implementation for the menu to save labels to a text file.
clsSceneGraphEvents.cls Class module containing the event handler for SceneGraph and SceneDocument events important for the tool.
clsSelectLabel.cls ITool implementation to select a label.
clsSGEvents.cls Class module containing the event handler for SceneGraph and SceneDocument events important for the engine.
DDDFont.cls Class module for handling fonts on the system for the tool.
DDDText.cls Class module containing the properties of a label.
IDDDFont.cls Class module containing the interface defining the properties of a font.
IDDDText.cls Class module containing the interface defining the properties of a label.
frmListChoose.frm Dialog for choosing labels.
frmProps.frm Dialog box presenting the properties of labels.
frmSlider.frm Dialog box presenting the properties of labels via a slider.
modLabel3DToolbar.bas Main code module containing code used by the toolbar.
modLabelEngine.bas Main code module containing code used by the labeling engine.
FontUtils.bas Code module containing code used by the toolbar concerning fonts.
Label3DEngine.vbp Project file for the labeling engine.
Label3DToolbar.vbp Project file for the labeling toolbar.
DDDAnalystTextSample.dll The compiled project for the labeling engine.
Label3DToolbar.dll The compiled project for the labeling toolbar.
(3D Analyst Developer Sample utilties) This project also references shared code located in Visual Basic code modules. To compile this project, these files are necessary in the location: '<ARCGIS INSTALL PATH > \ArcObjects Developer Kit\Samples\3D Analyst\Utilities\ '


Key CoClasses: Vector3D
Key Interfaces: ICommand, ITool, IToolbarDef, ISceneGraph, ISceneViewer
Key Members: ISceneGraph::Locate